🏭 Author the Stage 4 implementation workflow

[minkimcello]

Parent: #633

Architecture ancestry: PR #630

Planning base: 0479b3b1e6a3de08fb7d9de515a3efde80e7fe91; implementation base is the exact foundation integration head containing accepted C0 and F1–F6 feedback commits

Stack position: L8; parallel with L7 from the same foundation head; predecessor of L9

Readiness: blocked until the exact foundation integration SHA containing accepted C0/F1–F6 commits is recorded; no mutation, merge, evidence, publication, conflict, or handoff choice is delegated

Purpose and observable outcome

The authored factory turns one accepted plan into an exact implementation revision, runs its plan-selected evidence, synchronizes it without rewriting history, publishes the implementation branch, and hands a draft PR to Planner Review or suspends safely for manual conflict resolution.

Authoritative behavior

• Stage 4 is an authored component beneath workflows/github-actions-software-factory/components/ in the immutable bundle established by L7.
• The Implementor Agent receives accepted rendered evidence, no native tools, and admitted read observation only. Its final proposal is untrusted generated XMD data.
• Generated writes use only the existing exact table: paired File:write, paired Dir, and self-closing File.Delete, under frozen roots/forms. Authored XMD performs Add, Commit, Merge, evidence, Push, PR upsert, comments, and Project projection.
• Clean base synchronization creates parents [implementationHead, targetBase], remains Stage 4, runs evidence, and publishes by reconciled ordinary non-force Push.
• Every conflict restores the old root, records exact evidence, publishes an actionable handoff, and suspends. A manually pushed resolution is a new Stage 4 revision with no inherited review.
• Stage 5 receives only the reread exact { headSha, baseSha } after commit/evidence/push/PR reconciliation completes.

Current state

The branch has strict workflow Agents, generated observation/proposal loops, generated-XMD read/write admission, transactional Repository/Worktree/Dir/Switch/Add/Commit, reconciled non-force Push, PR upsert/read evidence, suspension/answer delivery, and immutable bundles. F1–F6 add remote continuation, authenticated wakeup, GitHub projections, Merge, evidence execution, and factory protocol. No authored Stage 4 component composes them.

Affected modules and public contracts

• Add Stage 4/Implementor/conflict/evidence/handoff Markdown components to the factory bundle; extend root frontmatter declarations.
• Add only narrowly reusable authored components for deterministic formatting/flow; provider mechanics remain in F1–F6.
• Add end-to-boundary fixtures for generated files, subprocess evidence, Git remote, PR host, suspension, and runner restart under explicit test files.
• Update factory spec examples only to match implemented authored syntax, without changing settled behavior.

Ordered implementation plan

1. Validate the accepted Planner handoff and select/materialize the exact retained implementation root and authorized repository/branch ceilings.
2. Run the Implementor observation loop through admitted reads, parse the final structured proposal, and preflight the entire generated fragment before any write.
3. Apply admitted file writes/deletions, then invoke trusted Add and Commit with a deterministic Stage 4 intent.
4. Reread target base/merge base and invoke F4 Merge when synchronization is required.
5. On clean state, invoke F5 for the accepted plan's exact evidence list, retain its outcome, reconcile F1 state, and invoke ordinary non-force Push.
6. Create/update the draft PR, reread its exact head/base, retain the Stage 4 handoff, then reconcile the PR comment and Project Planner Review projection.
7. On conflict, retain F4 evidence, verify old-root restoration, write the actionable handoff, and suspend through F2. On resume, reread the branch; only a changed authenticated head becomes a new Stage 4 revision.
8. At every boundary, validate F6 active frontier and exact revision before the next effect opens.

Failure, cancellation, teardown, and replay

Malformed proposal, unadmitted component/path/form, stale root/acquisition/head/base, Git/evidence failure, Push divergence/unavailability, PR conflict, unauthorized answer, or unchanged manual branch prevents Stage 5. Cancellation closes Agent/process/Git/provider scopes; committed earlier effects remain and reconcile on resume. A conflict is not resolved by resume input alone. Completed replay restores retained Stage 4 output and starts no Agent/process/Git/GitHub provider.

Frozen evidence matrix

• Agent/generated XMD cannot stage, commit, merge, execute, push, mutate GitHub, access credentials, or escape admitted paths/forms.
• Valid proposal commits exact admitted changes and retains commit/evidence/revision identities.
• Clean base movement creates ordered synchronization parents, stays at Stage 4, runs evidence, and non-force publishes before handoff.
• Every conflict class restores the pre-merge root, retains complete evidence, and suspends without automatic mutation.
• Unchanged resume refuses; manually changed branch becomes a new Stage 4 revision and invalidates all review.
• PR remains draft and Stage 5 receives the exact reread { headSha, baseSha } only after durable handoff/projections reconcile.
• Kill/interruption at each Agent/write/Git/evidence/Push/PR/comment/Project boundary resumes without duplicate accepted effect.
• No trace contains rebase, force, force-with-lease, reset replacement, blind second Push, or lifecycle logic in Actions.
• Completed replay starts nothing and preserves the same active revision.

Focused feedback evidence

Add explicit files such as packages/workflow/tests/factory-stage-4.test.ts, factory-stage-4-conflict.test.ts, factory-stage-4-recovery.test.ts, and packages/cli/tests/factory-stage-4-output.test.ts. Run them with generated-XMD, Git Merge/Push, evidence, PR durability, suspension/answer, Agent session, and bundle regressions plus deno task test --changed. Render normalized output. Commit when this matrix passes and report the exact L8 SHA and commands.

Delivery verification

Run deno task lint, deno task check, and deno task check:jsr only if public exports move in this story. The explicit integration files are required because graph-based selection cannot see subprocess/remotes/generated documents.

Exclusions

No automatic/generated conflict resolution, Stage 5–7 verdict, ready/merge/abandon, Actions evidence step, new provider primitive, widened generated-XMD table, or second controller.

Risks and recovery

The largest risk is crossing authority boundaries while composing many accepted effects. A defect stays in L8 when composition/order is wrong; a primitive contract defect returns to its F-story and restacks L8. Do not workaround a foundation defect in Markdown or YAML.

Handoff

Record the exact foundation integration SHA containing all accepted F heads. Author only Stage 4 composition, freeze the matrix, and return the exact L8 feedback commit. L9 begins from the lifecycle integration head that preserves accepted L7 then L8 commits.