🏭 Complete the software-factory contract above PR #630

[minkimcello]

Parent: #633

Architecture ancestry: PR #630

Exact implementation base: branch codex/github-actions-software-factory-architecture at 0479b3b1e6a3de08fb7d9de515a3efde80e7fe91

Stack position: C0, the first child branch and contract root for every implementation story

Readiness: ready to plan/implement from the exact base above; no predecessor feedback commit is required and no product decision remains open

Purpose

Turn PR #630's draft architecture into the decision-complete contract that the implementation stack follows, without waiting for #630 to merge. This story changes specifications and architecture only; its accepted feedback commit becomes the exact base for F1–F6.

Authoritative decisions

• Stage 1 is exactly User.
• The first release performs clean synchronization and suspends on every conflict; manual resolution creates a new Stage 4 revision with no inherited review. Automatic conflict mutation, rebase, force push, and force-with-lease are absent.
• One SQLite-backed Cloudflare Durable Object per run owns WorkflowRun/journal state, Workspace roots and content-addressed bytes, Agent-session checkpoints, pending answers, and executor ownership.
• Executor ownership is one authenticated Durable Object WebSocket connection, not a timed lease. Every authoritative request validates that live acquisition and expected Workspace root inside its mutation transaction.
• A dedicated GitHub App verifies webhook ingress and human form submissions; Actions authenticates to the provider through GitHub OIDC. Ingress retains bounded intake and wakes XMD but owns no transition.
• GitHub mutations use short-lived App installation tokens with Metadata read, Contents write, Issues write, Pull requests write, Checks read, Commit statuses read, and organization Projects write only. Initial-release mutation of .github/workflows/** is refused.
• A human authorizing admission, an answer, merge, change, or abandonment has Project write and repository write-or-higher access. The App performs the effect while the journal retains the human actor.
• Run identity is base32(sha256("github-issue-v1\0" + githubHost + "\0" + issueNodeId)) after rereading the issue. Issue transfer that changes provider identity is unsupported drift.
• Stage 7 target publication creates a trusted merge commit with first parent baseSha and second parent headSha, then performs a non-force compare-and-swap target-ref update. A moved target refuses before mutation and invalidates the exact-revision reviews.
• Abandonment is an authenticated exact-revision decision with a required reason. It closes the PR unmerged, closes the issue as not_planned, projects Closed, completes terminal kind abandoned, and retains all branches and evidence. Successful closure completes terminal kind merged with exact merge commit and actor.

Current state at the exact base

• specs/github-actions-software-factory-spec.md Sections 8.1 and 8.2 still describe conflict scope and deployment architecture as remaining decisions.
• architecture.md and the shared workflow specifications do not yet define the Cloudflare host, WebSocket acquisition, GitHub intake, exact permission ceiling, digest run identity, target compare-and-swap, or terminal abandonment contract.
• The ownership-bands SVG added at the 🏭 Specify the GitHub Actions-hosted AI software factory #630 head is not referenced by the draft specification.
• The stack root's merge base with origin/main is 0e88e910a19e5acb2f1e43839efc382c5b11880a; the observed origin/main head 1721c0672334f23c93290de35b7a5548e260fa98 is 33 commits beyond it. This story does not import that drift; E11 owns explicit final reconciliation.

Included changes and public contracts

• Amend specs/github-actions-software-factory-spec.md to replace every open decision with the authoritative behavior above, define success/refusal/suspension/replay/terminal semantics, and state the implementation stack's public constructs and provider responsibilities.
• Amend architecture.md with the remote-host topology, principal and credential boundaries, durable ownership, connection-scoped executor, GitHub intake, exact target-publication path, and retained terminal outcomes.
• Amend the touched sections and contract inventory of specs/workflow-spec.md, specs/workflow-workspace-spec.md, and specs/executable-mdx-spec.md so later stories can add provider-neutral APIs and runtime-specific adapters without choosing their ownership.
• Freeze these exact authored constructs and forms in the construct inventory: paired <Issue.Comment url as> and <PullRequest.Comment url as> whose content is the body; self-closing <Project.Status item field option as>, <PullRequest.Ready url as>, <PullRequest.Close url as>, and <Issue.Close url reason as>; self-closing <Git.Merge firstParent secondParent mergeBase purpose as>; self-closing <Git.PublishTarget expectedRemoteCommit sourceCommit reviewedHead as> whose repository/remote/target/force ceiling is host-owned; and self-closing <Evidence.Run commands as> whose structured commands and host ceilings are authored/trusted and absent from generated-XMD tables. A provider-neutral remote WorkflowHost and closed factory protocol records remain APIs rather than document elements.
• Reference the ownership-bands SVG from the factory specification or remove it from the stack; do not leave an unreferenced asset.

Exclusions

• No production TypeScript, Workers deployment, Actions workflow, executable factory document, dependency change, generated artifact, or retained-schema migration.
• No import of current main and no rewrite of 🏭 Specify the GitHub Actions-hosted AI software factory #630's existing commits.
• No alternative provider, timed executor lease, PAT, comment-authorized answer, ordinary squash/rebase merge, automatic conflict resolution, or state machine outside XMD.

Ordered implementation plan

1. Replace Sections 8.1 and 8.2 of the factory specification with normative first-release behavior and move the consequences into the lifecycle, synchronization, conflict, authority, and terminal sections where readers need them.
2. Add the remote topology and ownership model to architecture.md, distinguishing the Cloudflare Durable Object server, ephemeral Actions runner clients, GitHub App ingress, GitHub mutation principal, and authored XMD authority.
3. Define exact stable identities, natural keys, transaction boundaries, connection loss, duplicate delivery, stale authority, suspension, cancellation, completed replay, and retained terminal history.
4. Add the provider-neutral/runtime-specific ownership and exact construct/API inventory to the shared workflow specifications without prescribing ordinary internal mechanics.
5. Reconcile terminology and examples across issue 🏭 Build the GitHub Actions-hosted AI software factory #633, PR 🏭 Specify the GitHub Actions-hosted AI software factory #630's specification, architecture, and the ownership SVG; use User consistently.
6. Read the documents in comprehension order and remove duplicated rationale or remaining roadmap language that asks an Implementor to choose behavior.

Failure, cancellation, replay, and recovery contract

The specification must say that a foreign/stale acquisition, changed root, unauthorized intake, ambiguous remote observation, stale revision, moved target, malformed retained record, and unsupported issue transfer refuse before protected mutation. Connection loss releases executor ownership; it does not roll back a committed transaction. Cancellation publishes no invented external completion. Reconciliation adopts only a compatible observed effect. Completed replay contacts no provider and starts no Agent, process, Git, GitHub, or Project operation.

Frozen evidence matrix

• A requirements trace maps every authoritative decision above to one normative architecture/specification location and no “remaining decision” text contradicts it.
• The lifecycle trace covers success, same-stage iteration, every backward invalidation destination, conflict suspension/manual resolution, merge, change request, abandonment, interruption, cancellation, and completed replay.
• The ownership trace names who owns intake, execution, persistence, credentials, Git/evidence processes, transition decisions, projection, target publication, and terminal reconciliation.
• The identity trace separates definition SHA, run ID, expansion/effect identity, Workspace root, implementation { headSha, baseSha }, webhook delivery, suspension/decision subject, and provider result identities.
• The permission trace grants only the settled GitHub App permissions and refuses .github/workflows/**, another repository/Project/field/option/branch/target, force publication, and an under-authorized human.
• The construct inventory assigns each public API to a provider-neutral module or named runtime adapter and leaves no public spelling for an Implementor to invent.
• The SVG is referenced by the specification or removed.
• git diff --check 0479b3b1e6a3de08fb7d9de515a3efde80e7fe91...HEAD reports no whitespace errors.

Focused feedback evidence

Run the requirements, lifecycle, ownership, identity, permission, and construct traces as a structured document review, then run git diff --check 0479b3b1e6a3de08fb7d9de515a3efde80e7fe91...HEAD. Markdown is excluded from repository formatting, so deno task lint is not evidence for this story. Commit immediately when this frozen evidence passes and report the exact SHA plus the reviewed document sections and command output.

Delivery verification

No product test suite is required for this specification-only story. If implementation or executable fixtures enter the diff, the story is out of scope and must be split or replanned before delivery.

Risks and recovery

The principal risk is downstream work coding against a private interpretation rather than this contract. Recovery is to stop the dependent story, amend C0 explicitly, create a new accepted C0 feedback commit, and restack every affected descendant. Do not repair a structural omission implicitly inside an implementation PR.

Handoff

Create a child branch from exact commit 0479b3b1e6a3de08fb7d9de515a3efde80e7fe91. Make only the contract changes above. When the frozen evidence passes, create the C0 feedback commit and return its exact SHA; that SHA, not a moving branch name, becomes the base recorded by F1–F6.