EPIC: Bee task-family handoff — inherited context, implementation, verification, and learning #1667

Goal

Make every Bee start from a complete, structured task family rather than a bare issue, so it can continue the Queen's plan, reuse existing work, implement a bounded slice, verify that the result works, and return evidence another agent can independently review.

Existing contracts to reconcile first

• gHashTag/t27/specs/system/unified-agent-operations.t27 defines the proposal/spec/design/tasks change folder and parallel-task marking.
• gHashTag/t27/specs/queen/actors.t27 defines actor semantics but explicitly says some behavior is contract-only until wired into the supervisor.
• gHashTag/trinity/apps/website/public/t27/files/specs/queen/dispatch.t27 is the canonical task lifecycle description.
• gHashTag/trinity/apps/website/public/t27/files/specs/queen/control.t27 defines control events and existing lifecycle constraints.
• Existing task state, leases, retries, cancellation, review, and evidence must be preserved; do not create a parallel queue or worker registry.

Boundary

This epic defines the handoff contract and validation loop. It does not replace the production supervisor in one step, does not create another task database, and does not treat generated code or a green-looking summary as proof.

Required task family

Every non-trivial task should carry or link:

1. Parent epic and exact bounded child issue.
2. User goal, non-goals, constraints, and acceptance criteria.
3. Canonical specs and relevant existing implementation paths found by reuse search.
4. Dependency graph and parallelization rules; file ownership/conflict boundaries.
5. Expected artifacts and allowed capability/tool set.
6. Known risks, missing T27 capabilities, and approved exceptions.
7. Verification plan with commands, fixtures, expected outputs, and failure handling.
8. Evidence bundle: changed paths, test output, compiler/version, commit/PR, known limitations.
9. Independent review verdict and follow-up learning record.

Execution protocol

• QUEEN_PLAN: clarify the objective, search existing specs/code/issues, and decompose into atomic tasks.
• BEE_PREPARE: read parent context, contracts, boundaries, and relevant examples before editing.
• BEE_IMPLEMENT: change only the owned slice, using T27-first implementation policy.
• BEE_VERIFY: compile, run focused tests, regression tests, and acceptance checks; do not claim tests that were not run.
• INDEPENDENT_REVIEW: a different reviewer checks correctness, scope, security, and evidence.
• REPAIR_OR_ACCEPT: failures return actionable diagnostics to the original Bee; bounded retries with explicit stop/escalation rules.
• QUEEN_INTEGRATE: merge only after acceptance; preserve rollback and production invariants.
• LEARN: record reusable knowledge or a verified skill update only when evidence supports it.

Required failure behavior

• Missing API/tool/spec: report the exact gap and search evidence; do not silently switch to Python/JS or invent an interface.
• Failing tests: include actual command, failure summary, and relevant logs; do not report success.
• Conflicting specs: stop the affected change, identify canonical-source ambiguity, and request or create a bounded ADR task.
• Scope expansion: split a child issue rather than silently broadening the Bee's assignment.
• No independent reviewer available: mark review pending, not accepted.

Testing and observability

• Add schema/conformance tests for task-family fields and required links.
• Add replay fixtures for success, compile failure, test failure, cancellation, timeout, stale lease, conflicting files, missing capability, and reviewer rejection.
• Differential-test new behavior against the existing supervisor before cutover.
• Measure first-pass acceptance, compile/test success, repair-loop count, context size, wall time, reviewer rejection reasons, and regression rate.
• Keep historical metrics labeled with their timestamp and source; do not present snapshots as live.

Success Criteria

• Task-family schema is expressed in T27 where feasible and validated automatically.
• A Bee can reconstruct the needed context from the parent/child links without guessing.
• Implementation and verification are separate explicit stages.
• A task cannot be marked accepted without evidence and a review verdict.
• Retry, cancel, lease, and failure semantics remain compatible with the existing task lifecycle.
• Representative replay tests cover the failure modes above.
• A pilot set of real tasks shows fewer avoidable rework loops without weakening correctness.