Add the operating-mode transition proposal (docs/transition.md)

[yihanzhu]

Construction mode ends only through an operator-merged operating-mode transition, and config/construction-mode.json is a path construction may not edit. This document is the proposal the operator acts on: what construction built (step → unit → status table), what "implementation-complete" does and does not mean, the exact fields of the mode record the transition PR changes and their proposed values, the ruleset verification per post_transition_ruleset, what becomes possible after the transition mapped to roadmap steps 7–12 in order, what the operator must provide (never pasted into chat or the repo), what stays human forever, and ten one-line open questions for the operator.

One finding the document records: the mode record's post_transition_ruleset is field-for-field identical to the live main ruleset today, so construction never loosened the branch rules; the relaxation lives in the AGENTS/REVIEW overlays and the publisher gate keyed off status: active, and flipping status is the single load-bearing change.

Documentation only: docs/transition.md (260 lines), a pointer in README next to the construction-mode paragraph, a line in RESTORE.md beside the components doc, and the path appended to ci/required-files.txt.

Proof run on 13e7879: bash scripts/check-rename.sh clean; every path in ci/required-files.txt resolves; bash scripts/test/portable-core-schema.test.sh → failures: 0.

Construction mode: inactive output, no human gate. Nothing in this PR performs the transition.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying ystack with    Cloudflare Pages

Latest commit:	ffb09e1
Status:	✅  Deploy successful!
Preview URL:	https://44e28cfe.fabrica-6yx.pages.dev
Branch Preview URL:	https://ystack-docs-operating-mode-t.fabrica-6yx.pages.dev

View logs

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: 13e7879
Reviewed-base: fae1848
reviewer: gpt-5.5 @ high

Posted verbatim by codex-review.sh (codex exec review --json --base refs/codex-review/253-50476/base in an isolated temp worktree, sandbox forced read-only). Comments only — Codex never pushes, approves, or merges.

The new transition runbook overstates current completion and gives an incomplete transition scope that would leave the repository documentation stale. These are actionable documentation defects in a file meant to drive a safety-critical operating-mode change.

Full review comments:

• [P2] Do not mark unfinished rollout units complete — /private/var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.luPL3yooRV/docs/transition.md:18-22
  When this proposal is read before the pending/in-progress roadmap units land, this paragraph says all twelve rollout units have reached main and that the portable control plane is complete, but the table immediately below still marks steps 7, 9–11 as pending PRs and steps 8/12 as in progress. That overstates the evidence for a safe transition and leaves the new docs incoherent; the review policy requires the repository state to remain coherent after merge (REVIEW.md:19-25).

• [P2] Include README/docs updates in the transition plan — /private/var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.luPL3yooRV/docs/transition.md:153-156
  If the operator follows this “nothing else” instruction when retiring construction mode, the existing README paragraph and this proposal’s present-tense text will continue to say construction mode is active after the mode record says it is retired. The repo rules require every PR to keep README/docs in sync (AGENTS.md:107), so the transition checklist should include those documentation edits or explicitly require a paired doc-sync step before declaring the transition complete.

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: f8f9cbe
Reviewed-base: fae1848
reviewer: gpt-5.5 @ high

Posted verbatim by codex-review.sh (codex exec review --json --base refs/codex-review/253-8657/base in an isolated temp worktree, sandbox forced read-only). Comments only — Codex never pushes, approves, or merges.

The new transition checklist contains conflicting instructions about both the transition PR scope and whether pending roadmap units may remain unfinished. Those contradictions affect the operating-mode transition procedure and should be corrected before merging.

Full review comments:

• [P2] Include the required doc updates in transition scope — /private/var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.2hARKIaVtB/docs/transition.md:89-90
  For the transition PR, this scope excludes anything an agent could have authored, but §3.3 later requires updating README's construction-mode paragraph, docs/components.md, and this file's present-tense text. Those docs are not the operator-only mode record, and README/docs sync is required by repo policy (AGENTS.md:107), so following this sentence would produce a transition PR that leaves active-mode docs stale.

• [P2] Reconcile pending-work questions with the precondition — /private/var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.2hARKIaVtB/docs/transition.md:258-263
  When steps 8/12 or PRs Roadmap item 9: Add the inactive review-fix loop planner #249-Roadmap item 11: Add inactive deploy and rollback gates #252 are still pending, these questions say the transition can proceed with pending work or under restored gates, but §1/§3 set every row merged as the precondition before writing the transition PR. This contradiction can retire construction mode before the roadmap units the checklist says are required; either remove these as options or change the precondition and table accordingly.

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: c0487b3
Reviewed-base: fae1848
reviewer: gpt-5.5 @ high

Posted verbatim by codex-review.sh (codex exec review --json --base refs/codex-review/253-30152/base in an isolated temp worktree, sandbox forced read-only). Comments only — Codex never pushes, approves, or merges.

The new operator-facing transition document contains an internal contradiction about the status of required roadmap PRs, which can mislead the transition gate. No code execution issue was found.

Review comment:

• [P2] Keep step 8/12 status consistent — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.WvrbSqC2CD/docs/transition.md:37-41
  When the operator follows this transition checklist, §1 says steps 8 and 12 have no branch or PR, but §6 later says they are open PRs Roadmap item 8: Add the inactive workflow-scope qualification evaluator #254 and Roadmap item 12: Add the inactive maintenance loop (control bands, scan to intents, incident to eval) #255. That makes the gating table unreliable for deciding whether the transition precondition is met; please update the table/prose here to match the current PR status, consistent with the repo's docs-sync rule (AGENTS.md:107).

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: ffb09e1
Reviewed-base: fae1848
reviewer: gpt-5.5 @ high

Posted verbatim by codex-review.sh (codex exec review --json --base refs/codex-review/253-19050/base in an isolated temp worktree, sandbox forced read-only). Comments only — Codex never pushes, approves, or merges.

The changes add a transition proposal document, link it from README/RESTORE, and include it in the restore-critical manifest. I did not find any actionable correctness issues in the changed files.