Implementation handoff execution

Implementation Handoff Execution

Overview

Execute an existing handoff system from its Version 1 handoff-contract.md and current ledger position. Treat the contract as durable authorization and topology policy, the ledger plus Git state as recovery evidence, each active handoff/lane as a scope boundary, and root-verified validation plus commit evidence as the basis for Validated.

This skill consumes structures normally created by the implementation-handoff-orchestration skill. If no structure exists, use orchestration first. If a legacy structure lacks the contract, upgrade it only when the current user explicitly grants equivalent execution authorization.

When To Use

• A user asks to execute, continue, resume, recover, or finish an approved phase/handoff workstream.
• A repository has a roadmap, ledger, decisions, architecture target, risks, review checklist, phases, and handoffs under docs/loop/<workstream-slug>/.
• Work should continue without generic handoff, human-review, or phase-gate pauses.
• Context loss requires reconstruction from durable governance evidence.

When Not To Use

• The user has not approved creating or executing the handoff system.
• No handoff/ledger structure exists; use orchestration first.
• The request is review/report-only or a small one-off edit.
• The request is only an unauthorized production deploy, destructive data operation, or external release action.

Core Principle

Execute in the contract's topology: serial by default or controlled parallel when explicitly recorded. Continue automatically through investigation, repair, validation, self-review, phase gates, governance updates, integration, and logical commits. Under continuous_autonomous, stop implementation only at a proven Genuine Decision Dead End or an unavoidable user-owned worktree conflict. Finish all safe implementation despite release-only blockers, then stop before unauthorized release actions.

Contract Recovery And Compatibility

Before implementation edits:

1. Locate docs/loop/<workstream-slug>/handoff-contract.md.
2. Require Contract Version: 1, Contract Status: Approved for Execution, an authorized scope covering the active handoff, and an execution mode that permits the requested continuation.
3. Read Decision Authority, Phase Gate Policy, Human Review Policy, Release Policy, Commit Policy, and Scope Repair Policy by their canonical Version 1 field names.
4. Resolve Execution Topology without asking:
   • missing topology fields in an existing Version 1 contract mean serial;
   • serial uses the ordinary single-runner loop;
   • controlled_parallel requires its recorded approval evidence, topology document, authority limits, isolation policy, and fallback policy.
5. Mirror contract identity, authorization, topology, and current fallback state in the ledger.
6. Under continuous_autonomous, continue across handoffs and phases without generic review prompts.

For a legacy workstream without a contract:

• If the current user explicitly grants equivalent continuous execution authority, create Version 1 as a governance-only preflight change, record approval evidence, update the ledger, and continue.
• Otherwise continue read-only recovery and request execution authorization before implementation edits.

If the contract version is unsupported, status is Draft/Revoked/Superseded, or authorized scope excludes required work, do not implement until current user authority resolves it.

The contract never implies permission for deploy, cutover, destructive production operations, irreversible cleanup, backward-compatibility breaks, or external provider actions.

Topology approval is never execution or release approval. Do not ask the user to choose topology during execution; consume the recorded value or apply the legacy serial default.

Hard Boundaries

• Do not skip handoffs without a decision-log entry.
• Do not broaden the approved workstream outcome.
• Permit only Bounded Scope Repair recorded as an emergent checkpoint or corrective handoff.
• Do not treat historical docs as current truth when current code/tests disagree.
• Do not mark Validated without sufficient evidence.
• Do not perform unauthorized deploys, destructive migrations, irreversible cleanup, or external provider actions.
• Do not revert, overwrite, stage, or commit unrelated/user-owned changes.
• Use git add . only when status proves every dirty file belongs to the active checkpoint; otherwise stage explicit paths.
• Do not mark a handoff Validated while active changes remain uncommitted or required commit evidence is missing.
• Only the root orchestrator may create agents, update docs/loop/<workstream-slug>/**, verify worker evidence, integrate lane commits, resolve cross-lane conflicts, or run global join gates.
• Leaf workers may not create/delegate to agents, edit governance, leave their lane write scope, change the target/integration branch, integrate other lanes, ask the user for decisions, push, open PRs, merge target branches, deploy, run unauthorized migrations, or invoke external providers.
• Do not dispatch parallel writers without isolated branches/worktrees and exact baseline SHAs.
• Do not accept a worker's completion claim as validation evidence without root inspection of its diff, commit, scope, and command results.

Required Inputs

Infer these before asking:

• Workstream root and handoff-contract.md.
• Roadmap, progress ledger, decision log, architecture target state, risk/open-question log, and review checklist.
• Current phase, active handoff, last validated handoff, next handoff, dependencies, statuses, blockers, validation debt, and release blockers.
• Current handoff plus every Must Read Before Starting reference.
• Commit checkpoints, existing commit evidence, and non-applicability evidence.
• Baseline git status and unrelated dirty files.
• Build/test/static/validation commands from current project evidence.
• Execution topology, topology evidence, lane DAG, write scopes, resource locks, integration gates, branch/worktree baselines, queues, and fallback state.

Ask only when the workstream cannot be found, authorization is absent, contradictory state cannot be resolved from evidence, an indispensable source has no safe alternative, a Genuine Decision Dead End is proven, or preserving user-owned work is impossible.

Source Of Truth Order

1. Latest user instruction.
2. Current code, schema, configuration, contracts, and tests.
3. Approved Version 1 handoff contract.
4. Current ledger and active handoff summaries.
5. Current decision and risk/open-question logs.
6. Roadmap, phase docs, and architecture target state.
7. Historical handoffs, release notes, and older docs.

Record documentation drift when historical docs disagree with current source reality.

Decision Authority

Select a safe direction using this precedence:

1. Latest user instruction and approved workstream goal/non-goals.
2. Current code, schema, configuration, contracts, and tests.
3. Approved contract, ledger, active handoff, and recorded decisions.
4. Security, privacy, tenant isolation, and least privilege.
5. Backward compatibility.
6. Additive, reversible, and minimal implementation.
7. Repository conventions and validated architecture boundaries.

When this order identifies a safe option, record an Agent-Derived Decision for boundary-relevant choices and continue without asking the user.

Pre-Implementation Decision Gate: Genuine Decision Dead End

Run this gate after contract/state recovery and before marking a handoff In Progress.

A user-facing decision blocker exists only when every condition is true:

1. A material product, contract, security/privacy, tenant-isolation, schema, compatibility, scope, runtime, or external-authorization decision is required.
2. The answer cannot be derived from user instructions, the approved contract, decisions, current code/schema/configuration, tests, or repository conventions.
3. No safe option can be preferred using least privilege, backward compatibility, reversibility, minimal scope, and existing behavior.
4. Continuing would require unsafe guessing or could cause data loss, a security/privacy breach, a material contract violation, or an irreversible external effect.
5. Further read-only investigation, normal diagnosis, safe experimentation, or alternative validation cannot resolve the uncertainty.

Known defects, source mismatches, incomplete implementation, reproducible build/test failures, missing validation, pending commits, and safely repairable migration/security findings are execution work when evidence defines a safe correction.

When all five conditions pass:

• Mark the handoff Blocked.
• Record blocker id, owner, exact question, sources, alternatives, why none is safely preferable, all five predicate results, and independent work already completed.
• In controlled parallel, keep independent safe lanes running and defer the user-facing stop until no independent eligible work remains.
• Ask one concise batch of decision questions and return IMPLEMENTATION_DECISION_BLOCKED only after independent safe work is exhausted; in serial mode this is immediate.
• Continue read-only evidence gathering when it may resolve the decision.

Record the answer, re-run the gate, return the handoff to In Progress, and continue immediately when the blocker clears.

Execution Model

Read references/execution-protocol.md completely when executing real handoffs. When Execution Topology is controlled_parallel, also read references/controlled-parallel-execution.md completely.

1. Recover State

Read/validate the contract, then roadmap, ledger, decisions, risks, review checklist, current phase, last validated summary, active handoff, and required sources.

In serial mode, select the earliest eligible row in dependency order:

1. Needs Fix.
2. In Progress, Implemented, or Reviewed without complete evidence.
3. Blocked whose blocker is resolved.
4. Not Started.

Prefer consistent current/next pointers, but never skip an earlier eligible dependency without a decision.

In controlled-parallel mode, root reconstructs ready, active, integration, and lock queues from governance plus real Git/worktree state. Runtime agent IDs are advisory; branch, worktree, baseline, status, and commits are the durable source of truth.

2. Preflight

• Record dirty-worktree baseline and preserve unrelated changes.
• Confirm git worktree availability when commits are required.
• Validate or explicitly upgrade the contract.
• Read all required sources that exist and classify missing ones.
• Run the Genuine Decision Dead End gate.
• Confirm dependencies are Validated, Skipped, or Cancelled with evidence.
• Identify the next incomplete checkpoint.
• Build a short execution plan from objective, scope, non-goals, tests, impacts, recovery rules, and exit criteria.
• Mark the handoff In Progress after the gate clears.
• For controlled parallel, validate 06-controlled-parallel-topology.md, the acyclic DAG, lane write scopes, locks, root-only authority, depth one, worker cap, and isolated worktrees before dispatch.
• If agent tools, capacity, or safe worktree isolation are unavailable, record degraded_to_serial in ledger/risk evidence and continue serially without reapproval.

2A. Controlled Parallel Scheduler

Root dispatches a handoff only when:

• every explicit dependency is satisfied;
• its exclusive write scope does not overlap active lanes;
• all required shared-resource locks are free;
• backend/schema/contract producer-before-consumer order is preserved;
• its isolated branch/worktree and baseline are verified; and
• worker capacity exists.

Require a contract cap no greater than five. Effective leaf capacity is min(contract cap, available agent slots - 1, ready safe lanes). Here, ready safe lanes means dependency-ready, write-disjoint, mutually lock-compatible lanes after atomic lock reservation; recompute it after every dispatch. Never create more than five leaf workers, and always reserve root capacity. Reuse a worker for sequential handoffs in the same lane when safe; do not create one worker per handoff.

Serialize conflicts using these lock classes: governance, repo:<path-or-module>, database:migration, runtime:<port-or-service>, build:<repository>, browser:<test-account>, and external-provider. Full builds, migration verification, authenticated browser smoke, and use of the same test account are serial per repository/shared resource.

Root gives each leaf a self-contained task packet containing lane/handoff IDs, branch/worktree/baseline, allowed and forbidden paths, resource locks, targeted validation, commit expectations, return schema, and an explicit no-agent/no-delegation rule.

3. Execute The Active Handoff

Modify only files required by the active handoff and approved Bounded Scope Repairs. Include tests/docs when required. A docs-only handoff must not change implementation files.

Investigate and repair known defects, source mismatches, test failures, migration/schema issues, and safely remediable security/KVKK/PII findings inside the approved outcome.

In controlled parallel, leaf workers implement and commit only their lane slice. They return evidence to root and cannot update governance or mark a handoff Validated.

4. Bounded Scope Repair

Add an emergent checkpoint or corrective handoff and continue when discovered work:

• is necessary for the approved outcome;
• preserves non-goals and public/product behavior;
• avoids unauthorized destructive, production, deploy, or external actions;
• is reversible or backward compatible;
• has explicit validation and commit boundaries; and
• is recorded in the ledger, handoff summary, risks, and decision log when boundary-relevant.

Re-run the decision gate only when the discovery materially changes the approved outcome or cannot satisfy these conditions.

5. Validate And Recover

Run the exact validation named by current evidence. On failure, record the command/result, diagnose, repair within the approved outcome, and re-run. Use build/test/static inspection, migration/schema checks, security review, manual read-only audits, and exact non-applicability evidence as appropriate.

If an environment prevents evidence:

• Record validation debt.
• Run safe alternative checks.
• Continue independent handoffs that do not depend on the missing evidence.
• Retry the debt before final closeout.
• Never mark Validated without sufficient evidence.
• Return VALIDATION_BLOCKED_AFTER_INDEPENDENT_WORK_EXHAUSTED only after independent implementation and all safe recovery/alternative paths are exhausted.

6. Self-Review

Check scope/outcome, runtime behavior, tests, data/migration state, security/KVKK/PII, tenant isolation, compatibility, observability, decisions, risks, documentation, evidence, and commit hygiene. Use Developer, Tester, Reviewer, Architect, Security/KVKK Reviewer, Release Owner, and Operator lenses where useful.

7. Update Governance

• Update handoff status and all completion sections.
• Update ledger percentages, current/last/next pointers, blockers, release blockers, validation debt, last session note, and uncommitted changes.
• Mirror contract version/status, execution mode, authorized scope, and approval evidence.
• Add Agent-Derived Decisions, approved skips, bounded repair decisions, and compatibility choices.
• Update risks/questions and phase/roadmap only when current evidence requires it.

Only root performs these governance updates. For controlled parallel, also update active lanes, ready queue, integration queue, resource locks, worker source hashes, integrated hashes, fallback state, protocol violations, and recovery evidence.

Status model:

• Not Started -> In Progress -> Implemented -> Reviewed -> Validated.
• Needs Fix is an internal recovery loop returning to In Progress without user approval.
• Blocked is only a proven Genuine Decision Dead End or unavoidable user-owned worktree conflict.
• Deferred, Skipped, and Cancelled require a decision id.
• Only Validated, Skipped, or Cancelled may satisfy phase completion.

8. Commit Logical Checkpoints

After implementation, validation, self-review, and governance updates:

1. Compare current status with the preflight baseline.
2. Stage only active checkpoint files.
3. Inspect the staged diff.
4. Commit the coherent logical slice with why/change/validation context.
5. Record implementation commit hash, subject, files, and evidence.
6. Commit the governance hash update separately when needed; it need not record its own hash.
7. Confirm no active handoff changes remain uncommitted.

Diagnose and retry git/staging failures. Ask only when recovery would overwrite user work, rewrite unauthorized history, or require waiving a checkpoint.

8A. Integrate Controlled Parallel Lanes

Root independently verifies worker branch/worktree/baseline, committed diff, allowed paths, targeted tests, and reported risks. Reject or return incomplete/out-of-scope evidence.

After verification, root integrates only the explicit lane commit(s) into the recorded integration branch using the repository's safe integration policy, normally cherry-pick. Lane branches use the recorded lane-branch naming policy; cross-repository lanes keep the same lane ID. Record worker source SHA and resulting integrated SHA separately. Root alone resolves conflicts and runs serial join validation before Validated.

Local lane integration does not authorize merging the integration branch to main/target, push, PR, deploy, migration execution, or external effects.

9. Continue Or Stop

Under an approved continuous_autonomous contract, continue across handoffs and phases when the active work is validated/committed, governance is current, dependencies allow progress, and no Genuine Decision Dead End remains.

Continue and self-repair for:

• Generic manual review markers.
• Evidence-satisfied phase gates.
• Known defects and incomplete in-scope work.
• Recoverable build/test/validation failures.
• Missing evidence and pending commits.
• Safely repairable migration/schema/security/tenant findings.
• Bounded scope discoveries.
• Release blockers that do not change what must be built.

Do not end a run after preflight, diagnosis, a recoverable failure, self-review, a checkpoint commit, or a generic phase gate.

Human Review, Phase Gate, And Release Policy

• Replace generic human review with documented self-review under continuous_autonomous.
• Auto-pass a phase gate when exit evidence is satisfied and no Genuine Decision Dead End remains.
• Keep release blockers visible while completing all safe implementation.
• Stop immediately before an unauthorized deploy, cutover, destructive production operation, irreversible cleanup, backward-compatibility break, or external provider action.
• Never treat continuous execution as release authorization.

Context-Loss Recovery

1. Read and validate the contract.
2. Read ledger global fields and rows.
3. Read the last validated handoff summary.
4. Read the active/next handoff completely.
5. Read affecting decisions and risks.
6. Inspect current code/tests for drift.
7. For controlled parallel, compare ledger lane/queue/lock data with actual branch, worktree, status, baseline, and commits.
8. Reconstruct a concise state summary and continue.

Never rely on conversation memory when current files answer the question.

Worker Loss And Protocol Recovery

• On timeout or worker loss, root inspects lane worktree, branch, status, baseline, and commits before reassignment.
• Reuse the same leaf when safe or give the same lane to a replacement leaf; replacement depth remains one.
• If an unexpected descendant agent appears, root interrupts it, records PARALLEL_PROTOCOL_VIOLATION, inspects its effects, and continues the lane serially or with a compliant replacement.
• A blocked lane does not stop independent safe lanes.
• Worker decisions return to root; root reruns the Genuine Decision Dead End test and is the only actor that asks the user.
• Missing agent tooling, capacity, or safe isolation records degraded_to_serial in the ledger fallback state, last session note, and risk evidence, then continues serially under the existing approval.

Dirty Worktree Handling

Treat existing changes as user-owned unless clearly created in the current run. Work with relevant changes, ignore unrelated ones, never revert them, and compare against the baseline before staging. If conflict cannot be resolved without overwrite, record the exact conflict and stop with a decision blocker.

Final Output Format

Report:

• Contract status, version, execution mode, topology, fallback state, and authorization used.
• Root/worker lane state and integration evidence when controlled parallel was active.
• Active handoff completed or blocker encountered.
• Files changed and validation commands/results.
• Commit hashes/messages or exact non-applicability/blocker evidence.
• Self-review and governance updates.
• Next handoff and auto-continue state.
• Final decision: HANDOFF_VALIDATED_CONTINUING, ALL_HANDOFFS_COMPLETE, IMPLEMENTATION_COMPLETE_RELEASE_BLOCKED, IMPLEMENTATION_DECISION_BLOCKED, or VALIDATION_BLOCKED_AFTER_INDEPENDENT_WORK_EXHAUSTED.

Pressure Scenarios / Skill Tests

Scenario	Expected Behavior
No context, approved Version 1 contract	Recovers authorization and state before editing, then continues.
Legacy workstream plus explicit current authority	Creates Version 1 as governance preflight and continues.
Recoverable build/test failure	Enters recovery, diagnoses, repairs, revalidates, and continues.
Safely inferable material choice	Records an Agent-Derived Decision and continues.
Genuine unsafe ambiguity	Proves all five conditions, records evidence, then asks one exact decision batch.
Generic human review	Self-reviews and continues.
Evidence-satisfied phase gate	Auto-passes and continues.
Bounded scope discovery	Adds a corrective checkpoint/handoff, records it, validates, and continues.
Validation environment unavailable	Tracks debt, continues independent work, retries before closeout, and reports honestly.
Release blocker only	Completes implementation and stops before the unauthorized release action.
Dirty worktree	Preserves user changes and stages only checkpoint files.
Resolved Blocked handoff	Selects it before later Not Started handoffs and returns it to In Progress.
Legacy Version 1 without topology	Defaults to serial without asking or requiring contract migration.
Six ready lanes, four total slots	Uses at most three leaf workers and preserves root capacity.
More than five safe lanes	Never creates more than five leaf workers.
Shared write scope, migration, build, port, account, or provider	Prevents simultaneous dispatch with dependency edges or exclusive locks.
Leaf attempts delegation or governance write	Stops the violation, records PARALLEL_PROTOCOL_VIOLATION, and recovers under root.
Worker reports completion without tests/scope evidence	Root rejects validation until sufficient independent evidence exists.
Worker timeout or context loss	Recovers from Git/worktree/baseline/commit state and reuses or replaces one depth-one leaf.
Agent tools or safe isolation unavailable	Records degraded_to_serial and continues serially without asking topology again.
Controlled topology with Draft contract	Does not implement.

Common Mistakes

Mistake	Correction
Starting from conversation memory	Recover contract, ledger, summaries, decisions, risks, and source reality.
Asking continue? after handoffs/phases	Continue under continuous_autonomous unless a Genuine Decision Dead End is proven.
Stopping at first failure	Diagnose, repair, revalidate, and continue.
Asking for a safely inferable choice	Record an Agent-Derived Decision and continue.
Stopping for necessary reversible scope repair	Add a bounded checkpoint/handoff and continue.
Treating release blockers as decision blockers	Finish implementation and stop only before the release action.
Marking Validated after edits	Require sufficient validation and commit evidence.
Overwriting unrelated work	Preserve baseline user changes and stage narrowly.
One giant final commit	Commit coherent logical checkpoints.
Re-asking the topology choice	Consume the contract or use legacy serial; orchestration owns topology selection.
Trusting worker completion text	Root verifies diff, scope, commit, and validation evidence independently.
Letting workers update governance or integrate	Keep governance, verification, joins, and integration root-only.
Counting root as a leaf slot	Reserve one available slot for root and apply the contract cap.

Final Checklist

• Version 1 contract was validated or explicitly upgraded from current authority.
• Roadmap, ledger, phase, handoff, decisions, risks, review checklist, and must-read sources were read.
• Active handoff was selected from state/dependency evidence.
• Missing topology fields defaulted to serial; recorded topology was not re-asked.
• Controlled-parallel authority, cap, depth, worktrees, DAG, locks, and fallback were validated before dispatch.
• Only root created agents, changed governance, verified evidence, integrated commits, resolved conflicts, and ran joins.
• Every leaf received a self-contained packet and stayed within its branch/worktree/write scope without delegation.
• Worker source and integrated hashes plus targeted and join validation were recorded.
• Missing capacity/isolation degraded to serial with ledger evidence.
• Every user-facing stop passed all five Genuine Decision Dead End conditions.
• Safely inferable choices became Agent-Derived Decisions.
• Bounded repairs stayed inside the approved outcome and were recorded.
• Recoverable failures were diagnosed and retried.
• Validation evidence is sufficient or honest debt/blocker status is recorded.
• Self-review and governance updates are complete.
• Required logical commits are recorded and active changes are committed.
• Evidence-satisfied phase gates auto-passed.
• Release authorization was not inferred.
• Final response contains evidence, status, next action, and terminal decision.