dev-loops 0.6.0 → 0.7.2

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,23 +112,23 @@ 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>`
 - `waiting_for_initial_copilot_implementation`: keep waiting; in durable-auto mode use:
   ```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
@@ -198,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.
 
@@ -231,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/local-planning-flow.md

@@ -2,7 +2,7 @@
 
 The operator sequence for the local-first plan-file flow. The [Artifact Authority Contract](artifact-authority-contract.md) owns the model and the per-phase contract details; this doc names the shipped helper scripts in the order they run for one plan file. The [Local-Planning Worked Example](local-planning-worked-example.md) shows a single plan file evolving through these steps.
 
-The flow applies under local-planning mode (`strategy.default: local-first`, the shipped default — see the contract's [Shipped default posture](artifact-authority-contract.md#shipped-default-posture)). The plan file lives under `localPlanning.plansDir`, which defaults to `docs/phases/`.
+The flow applies under local-planning mode (`strategy.default: local-first`, the shipped default — see the contract's [Shipped default posture](artifact-authority-contract.md#shipped-default-posture)). The plan file lives under `docs/phases/`.
 
 ## Stages
 

package/skills/docs/local-planning-worked-example.md

@@ -2,7 +2,7 @@
 
 One plan file, `docs/phases/phase-42.md`, carried through every stage of the [Local-Planning Flow](local-planning-flow.md): authored, validated, refined in place, held at the local human-review checkpoint, then promoted to a draft PR. Each stage below shows the same file's content as it evolves. The contract details live in the [Artifact Authority Contract](artifact-authority-contract.md); this is a concrete trace of one file.
 
-The repo runs local-planning by default (`strategy.default: local-first`), and the plan lives under `localPlanning.plansDir` (`docs/phases/`).
+The repo runs local-planning by default (`strategy.default: local-first`), and the plan lives under `docs/phases/`.
 
 ## Stage 1 — Authored
 

package/skills/docs/merge-preconditions.md

@@ -38,14 +38,31 @@ 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.
+
+### Evidence writes and `gh pr merge` MUST be separate tool calls (#1172)
+
+The PreToolUse Bash gate evaluates `gh pr merge` **before** the Bash tool call executes. A compound
+command that both writes gate evidence (the findings-log ledger, `upsert-checkpoint-verdict`) and
+merges in the same call is blocked at hook-evaluation time — the write never runs. This can look
+like the ledger "vanished" between writing and merging; it was never written. The block message
+names this when it detects an evidence-writing invocation in the same command string.
+
+Documented pattern — **write, verify, then merge alone**:
+
+1. Write the gate evidence (findings-log ledger / checkpoint verdict) in its own Bash call.
+2. Verify it landed (e.g. `ls tmp/gate-findings/<slug>/pr-<n>/`) in a separate call.
+3. Run `gh pr merge` alone, with no other command chained via `&&`/`;`/newline.
 
 ## Title markers
 
@@ -89,7 +106,7 @@ explicit instruction can unlock.
 When a repo sets `approval.humanHandoff.enabled: true` in `.devloops`, the loop
 does not just park silently at the human-merge stop — at the
 `pre_approval_gate` / `waiting_for_merge_authorization` boundary it **offers**
-to route the PR to a named human (pairs with `autonomy.humanMergeOnly`: when
+to route the PR to a contributor (pairs with `autonomy.humanMergeOnly`: when
 human-merge is enforced, the handoff names who should take it). Disabled by
 default; no candidate sourcing when disabled.
 
@@ -124,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
@@ -141,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/plan-file-contract.md

@@ -4,7 +4,7 @@ A plan file is the persisted markdown artifact that drives work in local-plannin
 
 ## Format
 
-A plan file is a markdown document whose sections are level-2 (`##`) headings. It follows the same shape as the phase docs already committed under `docs/phases/`. The directory that holds plan files is `localPlanning.plansDir`, which defaults to `docs/phases/`.
+A plan file is a markdown document whose sections are level-2 (`##`) headings. It follows the same shape as the phase docs already committed under `docs/phases/`, which is also the directory that holds plan files.
 
 ## Base authoring sections
 

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)
+