🏭 Author the issue-side factory workflow for Stages 1–3

[minkimcello]

Parent: #633

Architecture ancestry: PR #630

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

Stack position: L7; parallel with L8 from the same foundation integration head

Readiness: blocked until the exact foundation integration SHA containing accepted C0/F1/F2/F3/F6 commits is recorded; no role, transition, record-boundary, or Agent-authority choice is delegated

Purpose and observable outcome

One authorized Project admission starts or resumes one durable run, and the authored executable Markdown factory carries product intent through User, Architect, and Planner with adjacent handoffs, same-stage correction, and exact backward invalidation recorded on the issue.

Authoritative behavior

• The immutable root document is workflows/github-actions-software-factory/Factory.md; bundled role/stage components live beneath workflows/github-actions-software-factory/components/ and are declared in root frontmatter.
• Root props contain only authenticated bounded issue/repository/Project intake values; stable run identity is supplied by the host after the authenticated reread, not recomputed from mutable document input.
• Stage 1 is User, Stage 2 Architect, Stage 3 Planner, and forward progress is adjacent only.
• Each role gets the accepted chain and bounded rendered evidence in one <Prompt> turn. Authored Markdown owns <Loop max>, parsing, classification, and transition branches.
• Same-stage amendment retains history and projects the same status. Backward invalidation records the earliest invalidated contract and deactivates all later handoffs.
• Full Stages 1–3 handoffs are issue comments. Project state and comments are projections after the accepted journal outcome.
• Agents are strict/tool-less; generated XMD has no role in Stages 1–3.

Current state

The branch already has immutable workflow bundles, root props, retained lifecycle/suspension, strict workflow Agent sessions, one-turn Prompt/Session behavior, parsing/control-flow components, Issue read/upsert, and normalized output support. There is no factory document, factory outcome schema in authored use, admission composition, role prompt bundle, issue-comment write, or Project projection. F1/F2/F3/F6 supply those missing foundations.

Affected modules and public contracts

• Add workflows/github-actions-software-factory/Factory.md and components for intake routing, User, Architect, Planner, issue handoff rendering, and shared frontier handling.
• Add no JavaScript/TypeScript component unless Markdown plus typed eval cannot carry a classifier; any eval performs pure parse/classification/formatting only and receives no provider capability.
• Add document fixtures and explicit integration tests under packages/workflow/tests/ or packages/cli/tests/ using normalized output.
• Update the factory specification examples only if authored syntax reveals a mismatch; do not change the frozen lifecycle contract inside this story.

Ordered implementation plan

1. Declare the immutable bundle and closed root-prop schema; validate intake against the retained run/issue/Project identity before rendering.
2. Implement one shared authored frontier component that reads F6 records, selects exactly the active Stage 1–3 component, and refuses a skipped/contradictory frontier.
3. Author the User prompt/outcome parse and branches for amendment, pass to Architect, or actionable refusal.
4. Author the Architect prompt/outcome parse and branches for amendment, pass to Planner, return to User, or clarify forward without unnecessary invalidation.
5. Author the Planner prompt/outcome parse and branches for amendment, pass to Implementor, return to Architect/User, or clarify forward.
6. For each accepted outcome, retain it first, then reconcile the full issue handoff comment and exact Project status through F3.
7. Implement the PR-to-issue backward crossing: the issue gets the full handoff and the PR-side caller later receives the stable issue-comment link.
8. Render normalized operator output that reports the completed action in past tense and explains every possible refusal before the operator encounters it.

Failure, cancellation, teardown, and replay

Invalid intake, wrong stage, malformed Agent outcome, unavailable provider, stale frontier, unauthorized projection, or contradictory retained state refuses/fails before the next stage is accepted. A Prompt failure closes its turn/session under the strict Agent contract. Cancellation tears down the current role and provider scopes and retains no invented handoff. If a GitHub projection completed before interruption, replay reconciles it from the accepted outcome. Completed replay invokes no Agent and rewrites no comment/Project state.

Frozen evidence matrix

• Valid admission creates/resumes one run and records User → Architect → Planner → Implementor adjacently.
• Every attempted skipped stage refuses before journal/comment/Project mutation.
• Two amendments at each of Stages 1–3 retain history while one latest handoff remains active.
• Backward invalidation to User, Architect, and Planner deactivates exactly the downstream chain and later progression reruns it.
• Issue comments contain full deterministic handoffs with stable identities; Project status remains a projection.
• Duplicate intake and interruption around comment/Project effects converge without duplicate handoffs.
• Agents receive only rendered bounded evidence and all native tool/MCP/filesystem/Git/GitHub/credential attempts fail before provider placement.
• Completed replay starts no Agent or GitHub effect.
• Normalized output reads as an operator narrative and hides schemas/captures/bindings.

Focused feedback evidence

Add explicit files such as packages/workflow/tests/factory-stages-1-3.test.ts, factory-preparation-invalidation.test.ts, and packages/cli/tests/factory-preparation-output.test.ts. Run them with existing workflow bundle, Agent-session, lifecycle, Issue, and generated-observation regression files plus deno task test --changed. Render and read the normalized document output. Commit when this matrix passes and report the exact L7 SHA and commands.

Delivery verification

Run deno task lint and deno task check; run deno task check:jsr only if public package surfaces move. CI owns exhaustive runtimes unless the document runner/shared test setup changes.

Exclusions

No Stage 4 file mutation/Git/evidence/PR creation, Stage 5–7 review/settlement, Actions YAML, TypeScript controller, hidden Agent loop, comment authority, or undeclared bundle component.

Risks and recovery

The main risk is duplicating F6's frontier in document-specific state. The document branches only on validated F6 records. A lifecycle contract gap returns to C0/F6; ordinary wording/output corrections remain in L7.

Handoff

Record the exact foundation integration SHA and verify it contains accepted C0/F1/F2/F3/F6 commits. Author only Stages 1–3, freeze the evidence, and return one exact L7 feedback commit. Preserve it for the lifecycle integration merge before L8.