dev-loops 0.7.1 → 0.7.2

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
@@ -50,9 +53,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 +72,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 +112,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,13 +122,13 @@ 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
+  - 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
   - 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
@@ -199,8 +203,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 +238,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,15 @@ doing manually; it is not a general conflict-resolution engine.
 
 ## Required before merge
 
+<!-- rule: MERGE-PRECOND-REQUIRED -->
 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. ✅ Issue-backed work: PR body contains `Closes #N` or `Fixes #N`; for an issue-less lightweight PR the closing reference is instead absent by design (owned by `ARTIFACT-LIGHTWEIGHT-BODY-INVARIANTS` in [Artifact Authority Contract](artifact-authority-contract.md))
+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.
 
@@ -140,10 +141,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 +156,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)
 
 ## 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)
+