dev-loops 0.7.1 → 0.8.0

package/skills/docs/copilot-loop-operations.md

@@ -1,6 +1,6 @@
 # Copilot loop operations
 
-This document is the canonical operational reference for the deterministic Copilot PR follow-up state machine used by the routed `copilot_pr_followup`, `wait_watch`, `reviewer_fixer`, and `final_approval` paths behind `dev-loop`.
+Canonical owner for operating the deterministic Copilot PR follow-up state machine — the operational reference for the routed `copilot_pr_followup`, `wait_watch`, `reviewer_fixer`, and `final_approval` paths behind `dev-loop`. The machine's states and transitions are defined by [Copilot Loop State Graph](../../docs/copilot-loop-state-graph.md).
 
 Use it together with:
 - [Copilot PR Follow-up Skill](../copilot-pr-followup/SKILL.md)
@@ -25,18 +25,17 @@ Use the machines to answer:
 - what the next required action is
 - when to stop instead of guessing
 
-Each machine captures an observable snapshot from GitHub facts (plus explicit bounded local loop
-metadata when required) and interprets it into exactly one current state plus allowed next
-transitions. In the `dev-loops` source repository, the supporting source-authority references are [Copilot Loop State Graph](../../docs/copilot-loop-state-graph.md) and [Reviewer Loop State Graph](../../docs/reviewer-loop-state-graph.md) under `../../docs/` relative to `skills/copilot-pr-followup/SKILL.md`. Treat those links as source-repo references, not bundled installed-skill docs.
+Each machine's snapshot-to-state mapping is defined in its owner doc (see the Overview of
+[Copilot Loop State Graph](../../docs/copilot-loop-state-graph.md) and
+[Reviewer Loop State Graph](../../docs/reviewer-loop-state-graph.md)), under `../../docs/`
+relative to `skills/copilot-pr-followup/SKILL.md` in the `dev-loops` source repository. Treat
+those links as source-repo references, not bundled installed-skill docs.
 
 For tracker-first MVP `story -> PR -> tracker sync` work, the source-repo reference is [Tracker-First Story-to-PR Contract](../../docs/tracker-story-pr-contract.md). That source doc inherits source-of-truth ownership, the required work item <-> PR link, and reverse-sync semantics from `#21`; it only adds the mutually exclusive workflow-family states and post-merge sync-verification states for this narrower MVP slice.
 
 ## Key guarantees from the state machine
 
-- `unresolvedThreadCount > 0` always routes to fix/reply-resolve — never to a wait/watch state
-- `snapshot.copilotReviewRequestStatus === "unavailable"` or `snapshot.copilotReviewRequestStatus === "failed"` routes to a terminal stop state — never to sleep or watch
-- `agentFixStatus === "applied"` with unresolved threads routes to `already_fixed_needs_reply_resolve` — reply/resolve on GitHub is required before re-requesting review
-- Copilot being in `requested_reviewers` (`"requested"` or `"already-requested"`) routes to `waiting_for_copilot_review`
+These routing guarantees are owned by [Copilot Loop State Graph](../../docs/copilot-loop-state-graph.md); see `COPILOT-STATE-UNRESOLVED-PRIORITY`, `COPILOT-STATE-TERMINAL-STOP`, `COPILOT-STATE-REPLY-BEFORE-REREQUEST`, and `COPILOT-STATE-ACTIVE-REQUEST-WAIT` there for the routing rules driving `unresolvedThreadCount`, `copilotReviewRequestStatus`, and `agentFixStatus`.
 
 ## How to use the state machine in practice
 
@@ -51,7 +50,7 @@ For tracker-first MVP `story -> PR -> tracker sync` work, the source-repo refere
 
 4. Branch on the detector output instead of inventing a polling loop:
    - `state=waiting_for_copilot_review` with `snapshot.copilotReviewOnCurrentHead=false`: do **not** poll manually; either run `node <resolved-skill-scripts>/loop/run-watch-cycle.mjs --repo <owner/name> --pr <number>` for persistent async waiting or report the wait state and resume later after the single detector call
-   - `state=waiting_for_ci` with `snapshot.ciStatus` in `{ "pending", "none" }`: do **not** poll manually by default; use `dev-loops loop watch-ci --repo <owner/name> --pr <number>` to block-wait on the combined check/status state (provider-agnostic — CircleCI, GitHub Actions, and any external commit-status / check-run). `gh run watch <run-id>` is an Actions-only fallback when the current-head run id is already known and you know the gating checks are GitHub Actions. Either way, on `timeout`/`changed` report pending CI and resume later after the single detector refresh. Bounded exception: if GitHub created zero current-head check suites/statuses, the previous head rollup was green, and local `npm run verify` already passed for the same current head, rerun `detect-copilot-loop-state.mjs` with `--local-validation-head-sha <current-head-sha>` so the detector can promote that exact zero-suite case to `snapshot.ciStatus="crediblyGreen"` instead of waiting forever on raw `none`.
+   - `state=waiting_for_ci` with `snapshot.ciStatus` in `{ "pending", "none" }`: do **not** poll manually by default; use `dev-loops loop watch-ci --repo <owner/name> --pr <number>` or `node <resolved-skill-scripts>/github/wait-pr-checks.mjs --repo <owner/name> --pr <number>` (settle-blocking with a 0/1/2 exit contract) to block-wait on the combined check/status state (provider-agnostic — CircleCI, GitHub Actions, and any external commit-status / check-run). `gh run watch <run-id>` is an Actions-only fallback when the current-head run id is already known and you know the gating checks are GitHub Actions. Either way, on `timeout`/`changed` report pending CI and resume later after the single detector refresh. Bounded exception: if GitHub created zero current-head check suites/statuses, the previous head rollup was green, and local `npm run verify` already passed for the same current head, rerun `detect-copilot-loop-state.mjs` with `--local-validation-head-sha <current-head-sha>` so the detector can promote that exact zero-suite case to `snapshot.ciStatus="crediblyGreen"` instead of waiting forever on raw `none`.
    - `snapshot.ciStatus="failure"` remains a stop/fix state, never a wait loop
 
 5. For reviewer-side draft-review work, run `node <resolved-skill-scripts>/loop/detect-reviewer-loop-state.mjs --repo <owner/name> --pr <number> [--reviewer-login <login>] [--local-state <path>]`.
@@ -64,10 +63,7 @@ For tracker-first MVP `story -> PR -> tracker sync` work, the source-repo refere
 
 ## Judgment calls that remain in the agent layer
 
-- Whether a comment should be accepted, deferred, or disagreed with
-- Whether the code change is already sufficient (→ sets `agentFixStatus: "applied"`)
-- What the narrowest valid fix is
-- Whether another Copilot pass is desired (→ triggers re-request or selects `done`)
+See [Copilot Loop State Graph](../../docs/copilot-loop-state-graph.md)'s "Agent judgment boundary" for the bounded list of decisions the state machine leaves to the agent.
 
 ## Workflow overview
 
@@ -102,7 +98,7 @@ Useful checks:
 
 If the user asks for status/progress/readiness/merge-state/next-step (including “what is next”):
 - resolve authoritative active artifact identity first (issue/PR, plus branch/head SHA when useful)
-- for issue targets, do not assert "no open PR" until authoritative issue↔PR linkage is resolved via the startup resolver (`dev-loops loop startup --issue <number>`, run inside the `dev-loop` async subagent) — do not run `detect-linked-issue-pr.mjs` manually
+- for issue targets, resolve authoritative issue↔PR linkage via the startup resolver (`dev-loops loop startup --issue <number>`, run inside the `dev-loop` async subagent) rather than running `detect-linked-issue-pr.mjs` manually; the fail-closed-until-resolved requirement is owned by `FACADE-STATUS-AUTHORITATIVE-FAIL-CLOSED` in [Public Dev Loop Contract](./public-dev-loop-contract.md)
 - resolve artifact state (`open`/`closed`/`merged`/`not_applicable`)
 - resolve current loop state and next action from deterministic helper/state output
 - include explicit resolved artifact identity in the answer
@@ -166,11 +162,14 @@ When you do hand work to Copilot:
 
 ## PR description contract
 
+This section governs tracker-backed (Copilot-handoff) PRs; issue-less/plan-file-backed PRs are governed by merge precondition 7 in merge-preconditions.md instead.
+
 Follow the PR description contract (see [Agent Instructions](../../AGENTS.md) if present; otherwise use the structure below): detailed structured descriptions, not thin placeholders. At minimum include change summary, scope/context, explicit acceptance criteria, explicit definition of done, and explicit non-goals, and `Closes #N` (or `Fixes #N`) for the linked issue so GitHub auto-closes it on merge.
 
 Checkbox rule: acceptance criteria, definition-of-done items, and any task list must be rendered as real GitHub markdown checkboxes inside list items (`- [ ]` / `- [x]`, also `* [ ]` / `* [x]`). Do not wrap checkbox markers (e.g. `[x]`) in backticks. Do not place checkbox markers inside table cells — task lists are not interactive there even with a leading `- `.
 
-New PRs in this workflow must be opened as **draft** PRs first when the repository enables `.devloops` at repo root `workflow.requireDraftFirst`. The built-in shipped default remains permissive; this repo opts in. Do not create a fresh PR directly in ready-for-review state unless the user explicitly overrides that policy for the current PR scope. The draft gate inspection is a real workflow boundary, so a new PR must exist in draft before `gh pr ready` is even eligible.
+<!-- rule: OPS-DRAFT-FIRST-PR -->
+`OPS-DRAFT-FIRST-PR`: New PRs in this workflow MUST always be opened as **draft** PRs — mechanically enforced by the `create-pr.mjs` wrapper below, which is unconditionally draft-only and rejects `--ready`. Agents MUST NOT create a fresh PR directly in ready-for-review state; `gh pr ready` (via the `ready-for-review.mjs` wrapper) is the only path out of draft, gated on clean draft-gate evidence. This rule owns the draft-first mechanism itself; [TRACKER-PROJECTION-REQUIRED-METADATA](./tracker-first-loop-state.md#31-required-pr-metadata) owns the tracker-facing "PR MUST start as a draft" metadata expectation. The draft gate inspection is a real workflow boundary, so a new PR must exist in draft before `gh pr ready` is even eligible.
 
 Only use `node <resolved-skill-scripts>/github/create-pr.mjs` when authoritative issue↔PR resolution says there is no already-open linked PR. If a PR already exists, reuse/update that canonical PR instead of opening another one. This wrapper preserves the underlying `gh pr create` output contract while enforcing draft-first mechanically and self-assigning the PR by default (`--assignee @me`).
 
@@ -230,4 +229,11 @@ Helper-owned sleep inside `run-watch-cycle.mjs`, `probe-copilot-review.mjs`, or
 
 A watcher sleeping between polls is expected behavior, not a blocker.
 
+## Hard rule: no inline interpreters
+
+<!-- rule: OPS-NO-INLINE-INTERPRETER -->
+`OPS-NO-INLINE-INTERPRETER`: Coordinator and agent flows MUST NOT invoke an inline interpreter (`node -e`/`node --eval`, `python3 -c`, `python3 - <<EOF` heredocs, or equivalent) to (a) parse any dev-loops tool output, or (b) mutate repository files. Sanctioned paths: a tool's `--jq`/`--silent` output flags (or `gh ... --jq`) for (a); the editor/patch tools, or `gh ... --body-file` composed from a `--jq` read, for (b). This rule applies to ALL repos using the dev-loop workflow, not just the source repo.
+
+Post-watch read pattern: after a probe/watch settles, do not parse its output — re-read state via `detect-copilot-loop-state.mjs --repo <owner/name> --pr <number>` and, for thread bodies/ids, `list-review-threads.mjs --repo <owner/name> --pr <number> --unresolved-only` (see [Copilot PR Follow-up Skill](../copilot-pr-followup/SKILL.md) Step 6).
+
 If the polling interval is 1 minute, do not treat silence shorter than one full poll interval as suspicious, and do not configure needs-attention thresholds close to a few seconds for this loop.

package/skills/docs/cross-harness-regression-contract.md

@@ -32,13 +32,13 @@ Definitions:
 
 ## Claude-Code-path test inventory
 
-When a change targets a Claude-Code-specific seam, the following suites are the baseline that MUST stay green, and are the first place to add coverage for a Pi-originated change that must not regress Claude Code:
+When a change targets a Claude-Code-specific seam, the following suites are the baseline that MUST stay green, and are the first place to add coverage for a Pi-originated change that MUST NOT regress Claude Code:
 
 - `npm run test:assets` — runs `test/contracts/*.test.mjs`, including `test/contracts/claude-assets-reproducible.test.mjs`, `test/contracts/claude-headless-smoke.test.mjs`, `test/contracts/claude-plugin-manifest.test.mjs`, `test/contracts/claude-plugin-marketplace.test.mjs`, `test/contracts/claude-hooks-settings.test.mjs`, and `test/contracts/cli-harness-agnostic.test.mjs`
 - `npm run smoke:headless` — runs `scripts/claude/headless-info-smoke.mjs`; this is a manual/local-only check, not part of `npm test` or `npm run verify` and not run by CI — run it directly when a change touches Claude Code headless-info behavior
 - `npm run test:core` — runs `packages/core/test/*.test.mjs`, including `packages/core/test/claude-headless-entry.test.mjs`, `packages/core/test/claude-hook-decisions.test.mjs`, `packages/core/test/run-context.test.mjs`, `packages/core/test/async-start-contract.test.mjs`
 
-Symmetrically, for a change targeting the Claude-Code-specific seam that must not regress Pi, `npm run test:extension` (which runs `test/extension-*.test.mjs`, including `test/extension-pi-adapter.test.mjs`, the Pi-side adapter inventory) is the baseline suite to check and extend.
+Symmetrically, for a change targeting the Claude-Code-specific seam that MUST NOT regress Pi, `npm run test:extension` (which runs `test/extension-*.test.mjs`, including `test/extension-pi-adapter.test.mjs`, the Pi-side adapter inventory) is the baseline suite to check and extend.
 
 ## How to add coverage
 

package/skills/docs/debt-remediation-contract.md

@@ -1,6 +1,6 @@
 # Debt remediation contract
 
-Canonical authority for the debt remediation pipeline and its integration with the `dev-loop` execution path.
+Canonical owner for the debt remediation pipeline and its integration with the `dev-loop` execution path.
 
 ## Pipeline
 

package/skills/docs/epic-tree-refinement-procedure.md

@@ -1,7 +1,7 @@
 # Epic tree refinement procedure
 
-This document is the canonical procedure for depth-first, top-down-then-bottom-up refinement of
-an existing GitHub sub-issue tree (parent → children → grandchildren).
+Canonical owner for depth-first, top-down-then-bottom-up refinement of an existing GitHub
+sub-issue tree (parent → children → grandchildren).
 
 Use it together with:
 - [Issue Intake Procedure](./issue-intake-procedure.md) — Phase 3b calls this procedure for epic decomposition
@@ -67,7 +67,8 @@ For the root issue:
 9. Show the diff and obtain confirmation before mutating GitHub
 10. Apply: `gh issue edit <root> --repo <repo> --body-file tmp/issues/<root>/refinement/root-body.md`
 
-**Gate:** Phase B must not start until Phase A is complete and the root body is updated on GitHub.
+<!-- rule: EPIC-REFINEMENT-SERIAL-PHASE-GATE -->
+**Gate:** Phase B MUST NOT start until Phase A is complete and the root body is updated on GitHub. The same serial-gate discipline applies at every phase boundary below: a level/phase MUST fully complete (siblings may run in parallel within it) before the next one starts.
 
 ---
 
@@ -96,7 +97,7 @@ parent's updated body, not each other's output.
 **Parallelism rule:** All siblings at the same level can be refined concurrently. No child needs
 another child's output; each child only reads the parent's contract and its own current body.
 
-**Serial gate between levels:** All children at level N must complete before descending to level N+1.
+**Serial gate between levels** ([EPIC-REFINEMENT-SERIAL-PHASE-GATE](#phase-a--root-refinement-serial)): all children at level N must complete before descending to level N+1.
 
 Repeat Phase B until all leaves are refined.
 
@@ -122,7 +123,7 @@ updated bodies, not sibling parents).
 6. Show the diff and obtain confirmation before mutating
 7. Apply: `gh issue edit <parent> --repo <repo> --body-file tmp/issues/<parent>/refinement/parent-reconciled-body.md`
 
-**Serial gate between levels:** All parents at depth N must complete reconciliation before ascending to depth N-1.
+**Serial gate between levels** ([EPIC-REFINEMENT-SERIAL-PHASE-GATE](#phase-a--root-refinement-serial)): all parents at depth N must complete reconciliation before ascending to depth N-1.
 
 ---
 
@@ -146,21 +147,28 @@ After all immediate children of the root have been reconciled:
      --repo <repo> --issue <root> --expected <n1,n2,...> --ordered
    ```
 
-**Gate:** Root final reconcile completes the procedure. All issues in the tree must now have:
-- AC checklist, DoD checklist, AC/DoD matrix, non-goals, explicit scope boundary
+**Gate:** Root final reconcile completes the procedure. Every issue in the tree must now satisfy
+[EPIC-REFINEMENT-REQUIRED-CONTRACTS](#rules).
 
 ---
 
 ## Rules
 
-- **No implementation, no PRs, no Copilot assignment** — this procedure is refinement-only
-- **Use `gh issue edit`** to apply changes directly — do not create new issues or PRs
-- **No prose parent/child links in bodies** — GitHub sub-issues API handles hierarchy
-- **Each issue must have:** AC checklist, DoD checklist, non-goals, AC/DoD matrix, scope boundary
-- **Scope boundary format:** `"This issue owns X. It does NOT own Y (#NNN) or Z (#MMM)."`
-- **Show the diff** and get confirmation before each `gh issue edit` mutation (unless unattended with explicit authorization)
-- **Write tmp artifacts** under `tmp/issues/<number>/refinement/` before applying
-- **Do not duplicate** the child list in parent bodies — the sub-issue tree API owns hierarchy
+<!-- rule: EPIC-REFINEMENT-SCOPE-BOUNDARY -->
+This procedure MUST stay refinement-only: no implementation, no PRs, no Copilot assignment.
+Apply changes directly with `gh issue edit` — never create new issues or PRs. Hierarchy MUST
+stay in the GitHub sub-issues API, not prose parent/child links or a duplicated child-list
+checklist in parent bodies.
+
+<!-- rule: EPIC-REFINEMENT-REQUIRED-CONTRACTS -->
+Each issue in the tree MUST carry: an AC checklist, a DoD checklist, a non-goals section, an
+AC/DoD matrix, and an explicit scope boundary in the format
+`"This issue owns X. It does NOT own Y (#NNN) or Z (#MMM)."`
+
+<!-- rule: EPIC-REFINEMENT-CONFIRM-BEFORE-MUTATE -->
+`EPIC-REFINEMENT-CONFIRM-BEFORE-MUTATE`: The procedure MUST write the refined body to
+`tmp/issues/<number>/refinement/` first and MUST show the diff and get confirmation before
+each `gh issue edit` mutation, unless running unattended with explicit authorization.
 
 ---
 
@@ -179,18 +187,13 @@ Phase D:  [root]                            serial (1 step)
 
 Total serial steps for a tree with depth D: `1 + (D-1) + (D-1) + 1 = 2D`
 
-**Fan-out rule:** At any level, when a parent is refined, ALL its children can be refined in parallel.
-
-**Serial gates:**
-- Root refinement must complete before any child starts
-- A parent's reconciliation must wait for ALL its children to finish
-- Root reconciliation must wait for all immediate children to reconcile
+**Fan-out rule:** At any level, when a parent is refined, ALL its children can be refined in parallel. Root/leaf/child ordering follows [EPIC-REFINEMENT-SERIAL-PHASE-GATE](#phase-a--root-refinement-serial) throughout.
 
 ---
 
 ## Completion criteria
 
-The procedure is complete when all issues in the tree satisfy:
+The procedure is complete when all issues in the tree satisfy [EPIC-REFINEMENT-REQUIRED-CONTRACTS](#rules), verified as:
 
 | Check | How to verify |
 |---|---|

package/skills/docs/issue-intake-procedure.md

@@ -1,17 +1,20 @@
 # Issue intake procedure
 
-This document is the canonical owner of the routed `issue_intake` procedure behind the public `dev-loop` façade.
+Canonical owner for the routed `issue_intake` procedure behind the public `dev-loop` façade: preflight, normalization, async refinement, epic decomposition, and Copilot handoff.
 
 Use it together with:
 - [Copilot PR Follow-up Skill](../copilot-pr-followup/SKILL.md)
-- [Public Dev Loop Contract](./public-dev-loop-contract.md)
+- [Public Dev Loop Contract](./public-dev-loop-contract.md) — owner of `FACADE-LINKED-PR-SINGLE-ARTIFACT`, `FACADE-BOOTSTRAP-WATCH-ROUTE`, `FACADE-BOOTSTRAP-ISOLATED-WORKTREE-CONTINUATION`
 - [Retrospective Checkpoint Contract](./retrospective-checkpoint-contract.md) when the current step depends on async start/resume/status or retrospective enforcement
+- [Stop Conditions](./stop-conditions.md) — owner of `STOP-INITIAL-COPILOT-001` and the other strategy-wide stop/wait rules this procedure operationalizes
+- [Merge Preconditions](./merge-preconditions.md) — the merge gate this procedure defers to before `gh pr merge`
 
 When routed work is issue-first rather than already in active PR follow-up, use the procedure below before entering the shared post-PR loop. Treat this document as the issue-refinement specialist procedure for the routed `issue_intake` seam.
 
 ## New-idea safety layer (default contract in this repo)
 
-For **all new ideas** that are not already anchored to an existing issue (including abstract ideas such as plain-language requests without an issue number or plan-doc path), apply this procedure-owned intake contract before any GitHub mutation:
+<!-- rule: INTAKE-NEW-IDEA-SAFETY -->
+For **all new ideas** that are not already anchored to an existing issue (including abstract ideas such as plain-language requests without an issue number or plan-doc path), the procedure MUST apply this intake contract before any GitHub mutation:
 
 - procedure owns classification; human operator gates all mutations
 - run classification in fresh context by default
@@ -23,6 +26,15 @@ For **all new ideas** that are not already anchored to an existing issue (includ
 - after approval, run a second async mutation pass (dispatched via the procedure) instead of mutating directly from inherited context
 - verify post-mutation artifact state and record what actually changed
 
+**Quick-capture exemption:** board quick-capture enqueue (the `/loop-enqueue` freeform
+path — freeform text turned directly into a minimal issue, gated on explicit human
+approval, then grilled inline and added to the board) MAY defer the up-front proposal
+artifact, the async classification pass, the async fan-out/fan-in proposal generation, and
+the second async mutation pass; its inline confirm→create→grill steps stand in for them,
+with grilling supplying classification/refinement after creation. The human-gated-mutation
+and create-new-only safeties still apply — it always creates a new issue and never
+repurposes/overwrites an existing one.
+
 Deterministic intake + mutation-gate state machine:
 
 ```text
@@ -50,9 +62,11 @@ Proposal artifact contract:
 - machine-readable JSON snapshot
 - write temporary artifacts under `Proposal` (`tmp/new-idea-intake/<run-id>/proposal.md`) and `tmp/new-idea-intake/<run-id>/proposal.json`
 
-If the Phase 1 preflight verdict is `pause_for_clarification`, stop and ask.
-If the intake state machine stops at `stopped_overlap_needs_decision` or `stopped_low_confidence`, stop and ask.
-If the intake state machine stops at `stopped_explicit_reject`, stop and record that the proposal was rejected; do not mutate GitHub.
+<!-- rule: INTAKE-STOP-STATES -->
+If the Phase 1 preflight verdict is `pause_for_clarification`, the procedure MUST stop and ask.
+If the intake state machine stops at `stopped_overlap_needs_decision` or `stopped_low_confidence`, the procedure MUST stop and ask.
+If the intake state machine stops at `stopped_explicit_reject`, the procedure MUST stop and record that the proposal was rejected; it MUST NOT mutate GitHub.
+
 After approval, start a separate async mutation pass (dispatched via the procedure) that consumes the approved proposal and emits a post-mutation verification artifact. Emit a concise post-mutation verification artifact and record what the mutation pass actually changed and verify the resulting issue/artifact state.
 
 ## Unattended issue-first execution and automatic re-entry
@@ -67,7 +81,7 @@ Under that unattended execution contract:
 - If a PR already exists, classify the post-assignment seam before follow-up
 - `waiting_for_initial_copilot_implementation`: keep waiting
 - `linked_pr_ready_for_followup`: route to the existing PR follow-up path immediately; resume from that PR
-- when routing leaves bootstrap wait for `linked_pr_ready_for_followup`, do not stop only because local isolation is required; re-enter the same PR follow-up from a safe isolated checkout/worktree
+- when routing leaves bootstrap wait for `linked_pr_ready_for_followup`, follow [FACADE-BOOTSTRAP-ISOLATED-WORKTREE-CONTINUATION](public-dev-loop-contract.md): re-enter the same PR follow-up from a safe isolated checkout/worktree instead of stopping solely because local isolation is required
 - When the draft PR appears, classify whether it is still the bootstrap-only Copilot draft before entering normal follow-up
 - if a child async run exits while the deterministic state is still non-terminal (for example `waiting_for_copilot_review`), automatically resume/restart follow-up when continuation is feasible instead of requiring manual operator restart
 - continue unattended until the human approval checkpoint unless a genuine stop condition is reached
@@ -107,10 +121,9 @@ Preflight verdicts:
 - detect an existing linked PR with the deterministic linked-PR helper:
   `node <resolved-skill-scripts>/github/detect-linked-issue-pr.mjs --repo <resolved-repo> --issue <number>`
 - treat the helper output as authoritative for linked-PR detection/selection
-- do not re-implement linked-event query behavior, pagination, repo filtering, or tie-break logic
-- do not rely only on PR title/body containing a literal issue number
+- <!-- rule: INTAKE-LINKED-PR-HELPER-DELEGATION --> `INTAKE-LINKED-PR-HELPER-DELEGATION`: Agents MUST NOT re-implement linked-event query behavior, pagination, repo filtering, or tie-break logic, and MUST NOT rely only on PR title/body containing a literal issue number.
 - treat an open linked PR as the active implementation for this issue
-- once an open linked PR exists, that PR is the only canonical follow-up artifact for the issue; attach follow-up work to it and do not open another PR unless the prior PR was explicitly superseded and reconciled first
+- once an open linked PR exists, attach follow-up work to it per `FACADE-LINKED-PR-SINGLE-ARTIFACT` (owned in [Public Dev Loop Contract](public-dev-loop-contract.md)) for the `issue_intake` strategy
 - **follow-up-capture rule:** when a follow-up is discovered while working a PR/loop, note it on the originating issue (or the PR body); file a standalone issue only if the follow-up is genuinely independent of the PR **and** outlives it (a real separate bug/feature that would be lost as a note on a soon-closed issue). Prefer noting PR-scoped follow-ups on the originating artifact over spinning up standalone tracker items for work that is part of the same effort or will be resolved imminently. See [Sub-Issue Tree Contract](../../docs/sub-issue-tree-contract.md).
 - if a PR already exists, classify bootstrap-wait versus follow-up:
   `node <resolved-skill-scripts>/loop/detect-initial-copilot-pr-state.mjs --repo <resolved-repo> --issue <number>`
@@ -118,20 +131,20 @@ Preflight verdicts:
   ```sh
   node <resolved-skill-scripts>/loop/watch-initial-copilot-pr.mjs --repo <resolved-repo> --issue <number>
   ```
-  - must use the dedicated `watch-initial-copilot-pr.mjs` watcher and its default 1-hour watch budget
+  - durable-auto ownership of this seam (the dedicated watcher + its default 1-hour watch budget) is owned by [FACADE-BOOTSTRAP-WATCH-ROUTE](public-dev-loop-contract.md); this procedure does not restate that rule
   - quiet/no-activity watch observations alone are non-terminal
   - `ready_for_followup`: linked PR has become substantive; resume from that PR
   - `timed_out`: observational first; refresh authoritative state
   - if refreshed state is still `waiting_for_initial_copilot_implementation`, remain attached to the same durable wait seam and continue waiting
-  - if the refreshed state exits this seam, route based on that refreshed state instead of surfacing timeout attention
-  - when the refreshed state is `linked_pr_ready_for_followup`, re-enter normal PR follow-up; if the follow-up handoff carries `conductorRouting.handoffEnvelope.requiresLocalIsolation=true`, perform the expected isolated-checkout/worktree handoff and continue
-  - only surface timeout attention when the seam's durable watch budget is actually exhausted
+  - <!-- rule: INTAKE-TIMEOUT-ROUTE-ON-SEAM-EXIT --> `INTAKE-TIMEOUT-ROUTE-ON-SEAM-EXIT`: if the refreshed state exits this seam, route based on that refreshed state instead of surfacing timeout attention
+  - when the refreshed state is `linked_pr_ready_for_followup`, re-enter normal PR follow-up per [FACADE-BOOTSTRAP-ISOLATED-WORKTREE-CONTINUATION](public-dev-loop-contract.md): if the follow-up handoff carries `conductorRouting.handoffEnvelope.requiresLocalIsolation=true`, perform the expected isolated-checkout/worktree handoff and continue
+  - <!-- rule: INTAKE-TIMEOUT-SURFACE-BUDGET-EXHAUSTED --> `INTAKE-TIMEOUT-SURFACE-BUDGET-EXHAUSTED`: only surface timeout attention when the seam's durable watch budget is actually exhausted
   - for explicit inspect/status requests, report the still-waiting state and exit normally
 - carry that resolved repo slug through every later GitHub issue/PR command
 
 ### From a plan-doc path
 
-- Resolve the target repository slug for this work item before any GitHub search or mutation
+- <!-- rule: INTAKE-REPO-SLUG-RESOLVE-FIRST --> `INTAKE-REPO-SLUG-RESOLVE-FIRST`: Resolve the target repository slug for this work item before any GitHub search or mutation
 - default to the current repository slug
 - if the plan-doc reference explicitly points at another GitHub repository, resolve `<resolved-repo>` first
 - search existing issues with:
@@ -199,8 +212,10 @@ node <resolved-skill-scripts>/github/manage-sub-issues.mjs list \
   --repo <resolved-repo> --issue <parent-number>
 ```
 
-Do **not** re-implement sub-issue management ad hoc or bypass `manage-sub-issues.mjs`.
-Do **not** maintain a body checklist that duplicates the sub-issue tree.
+Ad-hoc bypass of `manage-sub-issues.mjs` and duplicating the tree in the parent body are owned
+by `SUBISSUE-NO-ADHOC-BYPASS` and `SUBISSUE-LEAN-BODY-NO-DUPLICATE` in
+[Sub-Issue Tree Contract](../../docs/sub-issue-tree-contract.md); this procedure does not
+restate those rules.
 
 For the full `manage-sub-issues.mjs` contract, use [Sub-Issue Tree Contract](../../docs/sub-issue-tree-contract.md) when working in the `dev-loops` source repository. That contract is a source-repo reference, not part of the bundled installed skill-doc surface. For installed or normalized skill copies, inspect the target repository docs/source directly instead of assuming a bundled shared-doc copy exists.
 
@@ -232,9 +247,9 @@ The merge itself is gated, not implied by the lines above. Before any `gh pr mer
 gh pr merge <pr-number> --repo <resolved-repo> --squash --delete-branch
 ```
 
-Bootstrap-wait interpretation remains fail-closed and observational-first:
-- `ready_for_followup`: linked PR has become substantive; resume from that PR
-- `timed_out`: observational first; refresh authoritative state
-- if refreshed state is still `waiting_for_initial_copilot_implementation`, remain attached to the same durable wait seam and continue waiting
-- if refreshed state exits that seam, route based on refreshed state instead of surfacing timeout attention
+Bootstrap-wait interpretation remains fail-closed and observational-first — same seam as Phase 2's `waiting_for_initial_copilot_implementation` handling above: `ready_for_followup` resumes from the now-substantive linked PR; `timed_out` is observational first; refresh authoritative state and re-apply the Phase 2 branching (still-waiting vs. seam-exit) rather than re-deriving it here.
+
+## Cross-references
+
+See the "Use it together with" list at the top; additionally, [Epic Tree Refinement Procedure](./epic-tree-refinement-procedure.md) refines an existing sub-issue tree, while this procedure creates it (Phase 3b).
 

package/skills/docs/merge-preconditions.md

@@ -38,14 +38,17 @@ doing manually; it is not a general conflict-resolution engine.
 
 ## Required before merge
 
+<!-- rule: MERGE-PRECOND-REQUIRED -->
+Before merge, ALL of the following MUST hold:
+
 1. ✅ Conflict-free with base (`mergeable: MERGEABLE`; not `CONFLICTING`/`DIRTY`/`BEHIND`/`UNKNOWN`)
-1. ✅ CI green on current head (or crediblyGreen via `--local-validation-head-sha`)
-2. ✅ Draft gate satisfied (clean verdict)
-3. ✅ Pre-approval gate satisfied (clean verdict, current head)
-4. ✅ All review threads resolved
-5. ✅ Explicit merge authorization from operator
-6. ✅ PR body contains `Closes #N` or `Fixes #N`
-7. ✅ PR **title** free of merge-blocking markers — `WIP`, `[WIP]`, `DRAFT`, `DO NOT MERGE`, `🚧` (case-insensitive)
+2. ✅ CI green on current head (or crediblyGreen via `--local-validation-head-sha`)
+3. ✅ Draft gate satisfied — clean `draft_gate` verdict per `GATE-COMMENT-VERDICT-VALUES` ([Checkpoint Verdict Comment Contract](../../docs/gate-review-comment-contract.md))
+4. ✅ Pre-approval gate satisfied — clean `pre_approval_gate` verdict on the current head, same rule
+5. ✅ All review threads resolved
+6. ✅ Explicit merge authorization from operator
+7. ✅ Closing-reference state matches artifact backing, each arm owned by a different contract: tracker-backed work — PR body contains `Closes #N` or `Fixes #N` (owned by the PR description contract in [copilot-loop-operations.md](copilot-loop-operations.md)); issue-less lightweight (PR-body-as-spec, no backing issue) — the closing reference is absent by design and `node scripts/loop/validate-pr-body-spec.mjs --repo <owner/name> --pr <number> --no-issue` passes clean (owned by `ARTIFACT-LIGHTWEIGHT-BODY-INVARIANTS` in [Artifact Authority Contract](artifact-authority-contract.md)); plan-file promotion (P4) — the PR body carries the committed plan-doc path as the spec-of-record and, being issue-less by design (`buildPromotionPrBody` neutralizes closing keywords), the closing reference MUST NOT be present
+8. ✅ PR **title** free of merge-blocking markers — `WIP`, `[WIP]`, `DRAFT`, `DO NOT MERGE`, `🚧` (case-insensitive)
 
 > Runner-coordination lock: the pre-merge evidence check fails closed on a stale/foreign runner claim for the PR. A completing run releases its claim best-effort at every terminal stop (including the human approval checkpoint), so a merge re-dispatch normally proceeds. If a lock held by a completed/dead run still blocks the merge, take it over explicitly with `node <resolved-skill-scripts>/loop/pr-runner-coordination.mjs takeover --repo <owner/name> --pr <number>`. Never take over a genuinely active (non-stale) run — that fail-closed block is intentional.
 
@@ -79,9 +82,9 @@ A marker is allowed only while the PR is still in draft; it must be removed befo
 
 ## Merge authorization
 
-- Must be explicit for the active issue/PR scope
+- Merge authorization MUST be explicit for the active issue/PR scope
 - `"Merge authorized if gates green"` is valid explicit authorization
-- Implied approval from prior turns is not sufficient
+- Implied approval from prior turns MUST NOT be treated as sufficient
 
 ### `autonomy.humanMergeOnly` — fixed human-only merge (non-overridable)
 
@@ -140,10 +143,8 @@ human(s).
 
 ## Post-merge
 
-- Remove merged worktree (canonical): `node scripts/loop/cleanup-worktree.mjs --repo-root <main> (--issue <n> | --pr <n>)`.
-  It resolves the namespaced path, runs `git worktree remove --force <path> && git worktree prune` (the underlying
-  mechanism) from the main checkout, and refuses any path not under `tmp/worktrees/dev-loops/`. See
-  [worktree guidance](../../docs/worktree-guidance.md).
+- Remove merged worktree (canonical, `WORKTREE-CLEANUP`): `node scripts/loop/cleanup-worktree.mjs --repo-root <main> (--issue <n> | --pr <n>)`.
+  See [Worktree usage guidance](../../docs/worktree-guidance.md#post-merge-cleanup).
 - Archive long-done queue items (operator-induced, NOT a cron): `node scripts/projects/archive-done-items.mjs --repo <owner/name> || true`.
   Runs as part of this post-merge hook. It applies the configured `queue.archiveOlderThanDays` (default `7d`) and archives
   board items whose issue/PR has been closed at least that long. Best-effort: run it as a standard post-merge step but ignore
@@ -157,3 +158,6 @@ human(s).
 - [Confirmation rules](confirmation-rules.md)
 - [Validation policy](validation-policy.md)
 - [Stop conditions](stop-conditions.md)
+- [PR Lifecycle Contract](pr-lifecycle-contract.md)
+- [Checkpoint Verdict Comment Contract](../../docs/gate-review-comment-contract.md) — `GATE-COMMENT-VERDICT-VALUES`
+- [Contract style guide](contract-style-guide.md)

package/skills/docs/pr-lifecycle-contract.md

@@ -1,6 +1,7 @@
 # PR lifecycle contract
 
-This document defines the deterministic **family-local PR lifecycle contract** for the GitHub/Copilot workflow family in `dev-loops`.
+Canonical owner for **PR state vocabulary** rules for the GitHub/Copilot workflow family
+in `dev-loops` — the deterministic family-local PR lifecycle contract.
 
 The canonical contract lives in the shipped `skills/docs/` surface because installed skill/runtime consumers reliably own the skills subtree.
 
@@ -38,23 +39,27 @@ It does not redefine helper transport mechanics, reviewer-loop internals, conduc
 
 ## Core rules
 
-- Exactly **one current lifecycle state** must apply at a time.
-- The lifecycle must fail closed when required evidence is missing, stale, ambiguous, or unparsable.
+<!-- rule: LIFECYCLE-ONE-STATE -->
+`LIFECYCLE-ONE-STATE`: Exactly **one current lifecycle state** MUST apply at a time.
+
+- The lifecycle MUST fail closed when required evidence is missing, stale, ambiguous, or unparsable (see [Fail-closed rules](#fail-closed-rules), `LIFECYCLE-FAIL-CLOSED`).
 - Every gate-crossing decision is for the **current PR head SHA**.
 - Draft existence alone is **not** draft-gate readiness.
-- A PR must clear the draft-stage gate for the current head before Copilot review may be requested.
+- A PR MUST clear the draft-stage gate for the current head before Copilot review may be requested.
 - Ready -> draft resets the lifecycle back into draft-stage gating.
 - A merge-blocking marker in the PR **title** (`WIP`/`[WIP]`/`DRAFT`/`DO NOT MERGE`/`🚧`, case-insensitive) blocks the draft -> ready transition and, for non-draft PRs, blocks entry to the pre-approval gate and final approval (`title_marker_blocked`). Markers are permitted only while the PR remains draft. See [Merge preconditions](merge-preconditions.md#title-markers).
 - Human approval / merge are explicit external waits, not hidden remediation states.
 
 ## Two required local gates
 
-Each gate runs an independent review chain with its own disposition ledger, review angles,
-and exit conditions. The chains are not interchangeable; see [Checkpoint Review Chain Contract](../../docs/gate-review-sub-loop-contract.md).
+Each gate runs an independent review chain (`GATE-EXEC-SEPARATE-CHAINS`); see
+[Checkpoint Review Chain Contract](../../docs/gate-review-sub-loop-contract.md). Every gate
+pass writes a durable disposition ledger (`GATE-EXEC-DISPOSITION-LEDGER`) before the
+visible comment defined by [Gate Review Comment Contract](../../docs/gate-review-comment-contract.md).
 
 ### 1. `draft_gate`
 
-Applies while the PR is draft.
+<!-- term: gate:draft_gate --> Applies while the PR is draft.
 
 Purpose:
 - decide whether the current draft head is materially reviewable
@@ -64,8 +69,6 @@ Purpose:
 Boundary note:
 - `draft_gate` governs only the draft -> ready-for-review boundary for the reviewed head
 - a clean verdict requires no findings at any severity in the gate's `blockCleanOnFindingSeverities` (resolved from config via `resolveGateConfig(config, "draft").blockCleanOnFindingSeverities`)
-- every gate pass writes a durable disposition ledger via `write-gate-findings-log.mjs` under `tmp/gate-findings/`
-- visible comment schema/evidence rules stay in [Gate Review Comment Contract](../../docs/gate-review-comment-contract.md)
 - `gates.draft.requireCi=false` does **not** relax `pre_approval_gate`; final approval and merge readiness still require green current-head CI
 
 ### 2. `pre_approval_gate`
@@ -77,33 +80,31 @@ This gate uses review angles resolved from config (`resolveGateAngles(config, "p
 Boundary note:
 - `pre_approval_gate` governs only final approval readiness for the reviewed head
 - a clean verdict requires no findings at any severity in the gate's `blockCleanOnFindingSeverities` (resolved from config via `resolveGateConfig(config, "preApproval").blockCleanOnFindingSeverities`)
-- every gate pass writes a durable disposition ledger via `write-gate-findings-log.mjs` under `tmp/gate-findings/`
-- non-draft PRs do not need visible `draft_gate` evidence to enter the post-draft review / `pre_approval_gate` lifecycle; only the draft -> ready transition depends on `draft_gate`
-- visible comment schema/evidence rules stay in [Gate Review Comment Contract](../../docs/gate-review-comment-contract.md)
+- non-draft PRs do not need *per-head* `draft_gate` evidence to enter the post-draft review / `pre_approval_gate` lifecycle — the one-time draft -> ready transition record still applies; a non-draft PR with no clean `draft_gate` evidence at all fails closed and must reconcile that missing evidence first (see the current-head `draft_gate` evidence bullet under [Fail-closed rules](#fail-closed-rules))
 
 ## Lifecycle states
 
-The family-local lifecycle should be modeled in this vocabulary. These state identifiers are part of the stable contract surface for this lifecycle, even if adjacent helper implementations evolve around them:
+The family-local lifecycle SHOULD be modeled in this vocabulary. These state identifiers are part of the stable contract surface for this lifecycle, even if adjacent helper implementations evolve around them:
 
 | State | Meaning |
 |---|---|
-| `draft_local_review_gate` | draft PR is at the local draft-stage gate boundary |
-| `draft_local_remediation` | draft-stage findings require more local remediation while the PR remains draft |
-| `ready_state_needs_copilot_request` | draft gate is clear for the current head; Copilot request is the next legal step |
+| <!-- term: state:draft_local_review_gate --> `draft_local_review_gate` | draft PR is at the local draft-stage gate boundary |
+| <!-- term: state:draft_local_remediation --> `draft_local_remediation` | draft-stage findings require more local remediation while the PR remains draft |
+| <!-- term: state:ready_state_needs_copilot_request --> `ready_state_needs_copilot_request` | draft gate is clear for the current head; Copilot request is the next legal step |
 | `waiting_for_copilot_review` | Copilot request/re-review is observably in progress for the current head |
-| `copilot_feedback_remediation` | unresolved Copilot feedback exists; fixes are the next active step |
-| `copilot_reply_resolve_pending` | fixes were applied, but GitHub thread reply/resolve work still remains |
-| `merge_conflict_resolution` | current PR head conflicts with base or local reconcile is in progress; resolve conflicts before any further gate progression |
-| `final_local_preapproval_gate` | current-head post-Copilot convergence is ready for the final local gate |
-| `final_gate_remediation` | Pre-approval gate findings require more remediation after the final gate |
-| `waiting_for_human_pr_approval` | local gates are satisfied; waiting for explicit human approval |
-| `waiting_for_merge` | approval exists; waiting for merge / merge-triggering external action |
-| `terminal_slice_complete` | merged/closed and no further owned step remains |
-| `stopped_needs_user_decision` | blocked/ambiguous state requiring explicit human decision |
+| <!-- term: state:copilot_feedback_remediation --> `copilot_feedback_remediation` | unresolved Copilot feedback exists; fixes are the next active step |
+| <!-- term: state:copilot_reply_resolve_pending --> `copilot_reply_resolve_pending` | fixes were applied, but GitHub thread reply/resolve work still remains |
+| <!-- term: state:merge_conflict_resolution --> `merge_conflict_resolution` | current PR head conflicts with base or local reconcile is in progress; resolve conflicts before any further gate progression |
+| <!-- term: state:final_local_preapproval_gate --> `final_local_preapproval_gate` | current-head post-Copilot convergence is ready for the final local gate |
+| <!-- term: state:final_gate_remediation --> `final_gate_remediation` | Pre-approval gate findings require more remediation after the final gate |
+| <!-- term: state:waiting_for_human_pr_approval --> `waiting_for_human_pr_approval` | local gates are satisfied; waiting for explicit human approval |
+| <!-- term: state:waiting_for_merge --> `waiting_for_merge` | approval exists; waiting for merge / merge-triggering external action |
+| <!-- term: state:terminal_slice_complete --> `terminal_slice_complete` | merged/closed and no further owned step remains |
+| <!-- term: state:stopped_needs_user_decision --> `stopped_needs_user_decision` | blocked/ambiguous state requiring explicit human decision |
 
 ## Required transitions
 
-At minimum, the lifecycle must enforce these transitions:
+At minimum, the lifecycle MUST enforce these transitions:
 
 - `draft_local_review_gate` -> `draft_local_remediation`
   - blocking `draft_gate` findings
@@ -133,6 +134,8 @@ At minimum, the lifecycle must enforce these transitions:
   - pre-approval gate findings require changes
 - `final_local_preapproval_gate` -> `waiting_for_human_pr_approval`
   - clean current-head `pre_approval_gate` evidence exists
+- `final_gate_remediation` -> `final_local_preapproval_gate`
+  - fixes pushed after pre-approval gate findings
 - `waiting_for_human_pr_approval` -> `waiting_for_merge`
   - approval arrives
 - `waiting_for_human_pr_approval` -> `draft_local_review_gate`
@@ -145,17 +148,17 @@ At minimum, the lifecycle must enforce these transitions:
 - no Copilot request before clean current-head `draft_gate` evidence
 - no direct skip from fix-applied to Copilot re-request while reply/resolve remains incomplete
 - no reuse of ready-side or gate evidence after ready -> draft
-- a conflicted PR must not be treated as `waiting_for_human_pr_approval`, `waiting_for_merge`, or merge-ready, even if older gate comments and CI were previously green
+- <!-- rule: LIFECYCLE-CONFLICT-BLOCKS-PROGRESS --> `LIFECYCLE-CONFLICT-BLOCKS-PROGRESS`: a conflicted PR MUST NOT be treated as `waiting_for_human_pr_approval`, `waiting_for_merge`, or merge-ready, even if older gate comments and CI were previously green
 - no implicit fallthrough from approval/merge waits into remediation without a triggering event
 
 ## Remediation ownership boundary
 
-The lifecycle must keep the next action class explicit:
+The lifecycle MUST keep the next action class explicit:
 - draft-stage local findings route to `draft_local_remediation`
 - unresolved Copilot feedback routes to `copilot_feedback_remediation`
 - fixes applied but unresolved GitHub reply/resolve work remains route to `copilot_reply_resolve_pending`
 - pre-approval gate findings route to `final_gate_remediation`
-- merge conflicts route to `merge_conflict_resolution` and must be reconciled locally on the PR branch before lifecycle re-entry
+- merge conflicts route to `merge_conflict_resolution` and MUST be reconciled locally on the PR branch before lifecycle re-entry
 - human approval / merge remain explicit external waits
 
 Reviewer-loop reminder:
@@ -164,7 +167,7 @@ Reviewer-loop reminder:
 
 ## Required evidence classes
 
-The lifecycle distinguishes two evidence classes:
+The lifecycle distinguishes three evidence classes:
 
 1. **observable GitHub state**
    - PR draft/non-draft/merged/closed state
@@ -176,10 +179,8 @@ The lifecycle distinguishes two evidence classes:
    - current-head `draft_gate` evidence when draft-gate clearance is required
    - current-head `pre_approval_gate` evidence when final approval readiness is required
 
-3. **durable disposition ledger**
-   - every gate pass logs findings and dispositions under `tmp/gate-findings/<repo-slug>/pr-<N>/`
-   - the ledger is the durable record of what each gate found and what was decided
-   - the visible PR comment is a summary; the disposition ledger is the complete record
+3. **durable disposition ledger** — owned by `GATE-EXEC-DISPOSITION-LEDGER`
+   (see [Checkpoint Review Chain Contract](../../docs/gate-review-sub-loop-contract.md#disposition-ledger-and-durable-logging))
 
 ### Precedence rules
 
@@ -189,7 +190,8 @@ The lifecycle distinguishes two evidence classes:
 
 ## Fail-closed rules
 
-The lifecycle must stop or reconcile rather than advance when:
+<!-- rule: LIFECYCLE-FAIL-CLOSED -->
+`LIFECYCLE-FAIL-CLOSED`: The lifecycle MUST stop or reconcile rather than advance when:
 - current head SHA cannot be determined
 - required current-head `draft_gate` evidence is missing
 - required current-head `pre_approval_gate` evidence is missing
@@ -202,9 +204,16 @@ The lifecycle must stop or reconcile rather than advance when:
 - a boundary that is already CI/validation-dependent cannot confirm current-head freshness because the relevant status is pending, none, unknown, or stale
 - a required visible gate comment could not be confirmed posted
 
-In those cases the workflow must not:
+In those cases the workflow MUST NOT:
 - leave draft
 - request or re-request Copilot review
 - declare final approval readiness
 - silently fall through to a more permissive state
 
+## Cross-references
+
+- [Checkpoint Review Chain Contract](../../docs/gate-review-sub-loop-contract.md) — `GATE-EXEC-*` execution-shape rules
+- [Gate Review Comment Contract](../../docs/gate-review-comment-contract.md) — `GATE-COMMENT-*` PR-comment field rules
+- [Merge preconditions](merge-preconditions.md)
+- [Contract style guide](contract-style-guide.md)
+