🏭 Build the GitHub Actions-hosted AI software factory

[taras]

Why

Build the GitHub Actions-hosted AI Software Factory specified in draft PR
#630.

The factory turns one issue into one durable XMD run whose current owner is
projected on a GitHub Project. Product intent, architecture, planning,
implementation, and review accumulate as an accepted handoff chain. GitHub
Actions invokes the run; XMD owns the procedure, transitions, effects, and
journal. There is no separate controller.

Settled lifecycle

Stage	Status
0	Backlog
1	User
2	Architect
3	Planner
4	Implementor
5	Planner Review
6	Architect Review
7	User Review
8	Closed

Forward progress is strictly adjacent:

1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8

A backward transition may jump to the earliest invalidated contract, but every
later stage runs again. Same-stage correction is iteration, not progress.

Ownership bands

Each horizontal band belongs to one participant. The User forms the base,
Architect and Planner progressively narrow uncertainty, and implementation is
the apex. Validation returns through the paired prompt on each band.

Feedback through preparation

An implementation question descends only as far as the earliest contract that
does not resolve it. Each participant can stop an unnecessary invalidation and
send the work forward again.

flowchart TB
 I4["4 Implement Issue"] -->|Question| P3{"3 Planner<br/>Does the existing plan resolve it?"}
 P3 -->|Yes - clarify and return| I4
 P3 -->|No| A2{"2 Architect<br/>Does the specification cover it?"}
 A2 -->|Yes - send forward| P3
 A2 -->|No - real product gap| U1["1 User<br/>Make product decision"]

Loading

Feedback through validation

Review feedback bubbles toward implementation through the validation roles.
Only a proven upstream gap crosses the apex and descends the preparation side.

flowchart BT
 U7["7 User<br/>Review PR"] -->|Feedback| A6{"6 Architect<br/>Specification issue?"}
 A6 -->|No - return forward| U7
 A6 -->|Yes or uncertain| P5{"5 Planner<br/>Plan or evidence issue?"}
 P5 -->|No - return forward| A6
 P5 -->|Implementation correction| I4["4 Implementor<br/>Correct implementation"]
 I4 -->|New revision| P5
 I4 -->|Plan gap| P3["3 Planner<br/>Prepare Issue"]
 P3 -->|Specification gap| A2["2 Architect<br/>Review Issue"]
 A2 -->|Product gap| U1["1 User<br/>Assign Issue"]

Loading

Sequence

sequenceDiagram
 autonumber
 actor User
 participant Project as GitHub Project
 participant Actions as GitHub Actions
 participant XMD as Durable XMD workflow
 participant Agent as Current role Agent
 participant Issue as GitHub Issue
 participant Git as Workspace + Git
 participant PR as Draft Pull Request

 User->>Project: Assign Issue from Backlog (0) to User (1)
 Project-->>Actions: Authorized intake signal
 Actions->>XMD: Start run for issue at immutable definition SHA
 Note over XMD: One issue = one durable run<br/>Definition SHA never changes

 loop Stages 1-3 remove uncertainty
 XMD->>Agent: Render accepted chain and invoke current role
 Agent-->>XMD: Structured outcome
 alt Same-stage amendment
 XMD->>Issue: Record iteration
 XMD->>Project: Keep current stage
 else Earlier contract invalidated
 XMD->>Issue: Record full backward handoff
 XMD->>Project: Set earliest invalidated stage
 else Current role passes
 XMD->>Issue: Record accepted adjacent handoff
 XMD->>Project: Advance exactly one stage
 end
 end

 XMD->>Agent: Stage 4 Implementor receives accepted plan
 Agent-->>XMD: Generated XMD with proposed writes/deletions
 XMD->>Git: Admit scoped mutations, stage, commit, and run evidence
 Git-->>XMD: Implementation head SHA
 XMD->>Git: Checkpoint head, target base, and merge base

 alt Base synchronization merges cleanly
 XMD->>Git: Perform trusted merge
 Git-->>XMD: New head SHA
 Note over XMD,Git: Remain at Stage 4<br/>Stages 5-7 are invalidated
 XMD->>Git: Run selected evidence and non-force push
 else Merge conflicts
 Git-->>XMD: Durable structured conflict evidence
 XMD->>PR: Link exact SHAs, paths, blob identities, and classes
 XMD-->>User: Suspend for human resolution in the initial release
 User->>PR: Resolve and push changed branch
 PR-->>Actions: Authorized resume signal
 Actions->>XMD: Resume the same durable run
 XMD->>PR: Observe new exact head/base revision
 Note over XMD: Re-enter Stage 4<br/>No review is inherited
 end

 XMD->>PR: Create/update draft PR
 XMD->>PR: Record adjacent handoff with exact head and base SHAs
 XMD->>Project: Advance to Planner Review (5)

 XMD->>Agent: Planner Review exact head and base SHAs
 Agent-->>XMD: Verdict for that exact revision
 XMD->>PR: Record accepted Planner verdict
 XMD->>Project: Advance to Architect Review (6)

 XMD->>Agent: Architect Review same revision and Planner verdict
 Agent-->>XMD: Verdict for that exact revision
 XMD->>PR: Record accepted Architect verdict and make PR ready
 XMD->>Project: Advance to User Review (7)

 XMD-->>User: Review PR at exact validated head/base revision and handoff chain
 alt User accepts
 User-->>XMD: Authorize merge
 XMD->>PR: Merge with permitted target policy
 XMD->>Project: Advance to Closed (8)
 Note over XMD,Issue: Retain merged terminal reason and merge identity
 else User abandons
 User-->>XMD: Authorize abandonment
 XMD->>Project: Advance to Closed (8)
 Note over XMD,Issue: Retain abandoned terminal reason
 else User requests changes
 User-->>XMD: Identify earliest invalidated contract
 XMD->>Project: Move backward to Stage 1-6
 Note over XMD,Project: Forward progress traverses every later stage again
 end

Loading

Identity and invalidation

Two SHA identities remain distinct:

1. The XMD workflow definition SHA is immutable for the factory run.
2. The implementation revision evolves as { headSha, baseSha }.

Every Stage 5-7 conclusion names the exact implementation revision it reviewed.
Any change to headSha remains or returns to Stage 4 and invalidates Stages
5-7. Base movement without a head change invalidates Stage 5; if synchronization
or implementation work is required, it returns to Stage 4.

The initial synchronization policy merges the latest base into the published
implementation branch. It uses the ordinary reconciled non-force Push effect.
Rebases, force pushes, and force-with-lease are outside this issue.

Record and authority boundaries

• The issue owns product intent, architecture, planning, and the transition into
  implementation. Issue comments record Stages 1-3.
• Stage 4 creates or updates a draft PR before its first Planner Review handoff.
  The draft PR owns implementation iterations and Stages 5-7.
• Crossing backward from the PR to Stages 1-3 writes the full handoff on the
  issue and a short link on the PR. Crossing back into implementation links the
  accepted issue handoff from the PR.
• Comments are the human-readable transition record. The XMD journal is the
  durable execution record. The Project status is a projection of that record.
• The Agent decides desired contents. XMD inspects Git, applies admitted file
  effects, stages, commits, merges, runs evidence, pushes, updates GitHub, and
  reconciles interruption.
• The workflow Agent receives no Git, filesystem, shell, GitHub, Workspace,
  checkout, native-tool, or equivalent MCP authority.

Acceptance criteria

• One GitHub issue maps to one durable XMD factory run across every Stage 4
  revision.
• The Project exposes the nine settled statuses and XMD enforces adjacent
  forward transitions.
• Same-stage iteration and backward invalidation preserve history while
  replacing the active validation frontier.
• GitHub Actions only starts or resumes XMD and supplies a bounded GitHub
  environment; it owns no role outcome or transition decision.
• Stage 1-3 handoffs are recorded on the issue using the settled crossing
  rules.
• Stage 4 creates or updates a draft PR and hands Stage 5 its exact
  { headSha, baseSha }.
• Planner, Architect, and User review conclusions are accepted only for the
  exact current revision.
• A changed head returns to Stage 4; a base-only change returns to Stage 5
  unless Stage 4 work is required.
• Clean base merges create a new Stage 4 revision, run the selected evidence,
  and publish through a normal non-force push.
• A conflicted merge records exact head, base, merge base, conflict paths,
  base/ours/theirs blob identities, and conflict classifications.
• Unsupported conflict forms suspend without granting the Agent additional
  authority.
• A manually changed branch is observed as a new exact revision and re-enters
  Stage 4 before review.
• Stage 6 alone may make the PR ready. Merge or abandonment is the adjacent
  Stage 7 -> 8 transition with its terminal reason retained.
• Interrupted GitHub effects reconcile under stable identities rather than
  being repeated blindly.
• Rebases and force pushes are refused.

Initial release decision

Decide before Planner readiness:

• Implement structured generated-XMD resolution for ordinary text conflicts
  in the first release; or
• Suspend for human resolution on every conflict.

Architecture recommendation: choose the second option. Automatically perform
clean merges, suspend on every conflict, prohibit rebases and force pushes, and
add structured ordinary-text resolution later as a separately bounded
capability.

Deployment decisions before readiness

• Select the durable WorkflowRun, Workspace, Agent-session, and executor-lock
  provider shared by ephemeral Actions runners.
• Select the authorized Project admission, human-answer, and resume ingress and
  its actor authentication.
• Select the GitHub principal and exact repository, issue, pull-request, Project,
  merge, and abandonment permission ceilings.

Architecture

• Draft PR: #630
• Reviewed specification commit: a047204c

[minkimcello]

I asked GPT to start planning out this work and this is what I got back:

The implementation blockers are these eight contract questions:

1. What is the canonical Stage 1 Project status: User or Product Owner?
2. How should v1 handle Git conflicts? The recommendation is: auto-merge only clean changes, record conflict evidence, restore the pre-merge Workspace, and suspend for human resolution—never rebase or force-push.
3. What durable shared provider stores WorkflowRun data, Workspace bytes, Agent sessions, and the executor lock across ephemeral Actions runners?
4. What authenticated ingress starts a run, delivers human answers, and resumes it?
5. Which GitHub principal performs operations, and what are its exact permission ceilings?
6. How is an issue permanently correlated with one run ID without relying on mutable Project fields or comments?
7. Which target-branch merge method may Stage 7 authorize?
8. Who may authorize abandonment, and exactly what does abandonment do to the PR, issue, Project item, and retained workflow state?

After answering those, there is one procedural prerequisite rather than another product question: rebase the draft, architecture PR #630 onto current main, reconcile the contracts, handle the unreferenced ownership diagram, review it, and merge the specification. Only then is the first implementation slice ready to hand off.

[minkimcello]

The factory implementation is organized as a stacked set of independently reviewable stories. The stack starts from PR #630's architecture branch at exact commit 0479b3b1e6a3de08fb7d9de515a3efde80e7fe91; it does not wait for #630 to merge.

C0 first records the settled conflict, provider, ingress, authority, identity, merge, and abandonment decisions in architecture.md and the specifications on top of that branch. Its accepted feedback commit becomes the base for the parallel foundation stories.

• C0 / #710: Complete the software-factory contract above PR 🏭 Specify the GitHub Actions-hosted AI software factory #630
• F1 / #698: Add the remote workflow provider and executor ownership
• F2 / #699: Add authenticated GitHub ingress and human delivery
• F3 / #700: Add reconciled GitHub projection effects
• F4 / #701: Add trusted Git merge and conflict suspension
• F5 / #702: Add durable workflow evidence execution
• F6 / #703: Define factory lifecycle records and the validation frontier
• L7 / #704: Author the issue-side factory workflow for Stages 1–3
• L8 / #705: Author the Stage 4 implementation workflow
• L9 / #706: Author exact-revision review for Stages 5–6
• L10 / #707: Author authenticated user settlement for Stages 7–8
• E11 / #708: Integrate GitHub Actions, reconcile the stack with main, and prove the factory end to end

F1, F3, F4, F5, and F6 can proceed in parallel from C0. F2's GitHub-facing work can proceed alongside them and integrates with F1 before feedback. L7 and L8 can proceed in parallel from the composed foundation head; L9 follows L8, L10 follows L9, and E11 completes the stack and reconciles it with then-current main.

Each implementation PR closes only its child issue, says Part of #633, and records Architecture ancestry: #630. Issue #633 remains the parent outcome and closes only after E11's frozen end-to-end evidence passes.