dev-loops 0.6.0 → 0.7.2

package/.claude/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/.claude/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/.claude/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)
+

package/.claude/skills/docs/public-dev-loop-contract.md

@@ -1,10 +1,10 @@
 # Public dev-loop contract
 
-This document is the canonical authority for the public `dev-loop` entrypoint, its routed semantics, accepted shorthand, and the rule that internal strategy names stay behind that public façade.
+Canonical owner for the public `dev-loop` entrypoint: routed semantics, accepted shorthand, and the rule that internal strategy names stay behind the façade.
 
 This canonical owner lives in the shipped `skills/docs/` surface because installed skill/runtime consumers reliably own the skills subtree. In installed layouts, read the same contract via [Public Dev Loop Contract](../docs/public-dev-loop-contract.md) from the installed skill directory.
 
-Other repo docs may summarize or link this contract, but they should not redefine it.
+Other repo docs MAY summarize or link this contract; they MUST NOT redefine it.
 
 ## Public surface
 
@@ -12,7 +12,7 @@ The single public entrypoint is:
 
 - `dev-loop`
 
-It should be callable from the user-facing workflow surfaces, including:
+`dev-loop` MUST be callable from the user-facing workflow surfaces, including:
 
 - `subagent dev-loop`
 - `/skill:dev-loop`
@@ -28,8 +28,6 @@ Day-one user-intent forms:
 - auto dev loop on issue `<n>`
 - what state is the dev loop in?
 
-Users should not have to choose `dev-loop` vs internal seam names up front.
-
 ## Issue-based shorthand auto trigger contract
 
 This shorthand form is explicitly accepted and resolves to the same bounded public `dev-loop` intent:
@@ -44,7 +42,7 @@ Canonical mapping:
 
 Stop-boundary contract for this shorthand:
 
-1. continue through the normal GitHub/Copilot loop (assignment, PR watch, draft review/fix, Copilot review/fix, and final pre-approval work) unless a genuine stop condition is reached
+1. continue through the normal GitHub/Copilot loop (assignment, PR watch, draft/Copilot review-fix, final pre-approval) unless a genuine stop condition is reached
 2. stop at the final human approval decision by default
 3. after formal approval, stop again in `waiting_for_merge_authorization` unless merge authorization is explicitly granted for the active issue/PR scope
 4. merge only after explicit merge authorization for the active issue/PR scope
@@ -76,7 +74,8 @@ Use this taxonomy consistently across docs, discovery surfaces, and tests:
 
 Any remaining specialized Copilot behavior stays internal-only behind `dev-loop`.
 
-Regression tests must fail if this taxonomy drifts in wording or surfaced entrypoint assets.
+<!-- rule: FACADE-TAXONOMY-DRIFT-TEST -->
+`FACADE-TAXONOMY-DRIFT-TEST`: Regression tests MUST fail if this taxonomy drifts in wording or surfaced entrypoint assets.
 
 ## Canonical current state
 
@@ -90,17 +89,7 @@ The public router consumes one canonical current state with these top-level dime
 | `status` | `active` \| `waiting` \| `blocked` \| `approval_ready` \| `merge_ready` \| `done` |
 | `authorization` | `authorized` \| `needs_confirmation` \| `not_authorized` |
 
-The authoritative first-slice evaluator is:
-
-- `packages/core/src/loop/public-dev-loop-routing.mjs`
-
-Authoritative status-report helper:
-
-- `resolveAuthoritativeDevLoopStatus()` in `packages/core/src/loop/public-dev-loop-routing.mjs`
-
-Authoritative startup/resume bundle helper:
-
-- `resolveAuthoritativeStartupResumeBundle()` in `packages/core/src/loop/public-dev-loop-routing.mjs`
+The authoritative first-slice evaluator, status-report helper (`resolveAuthoritativeDevLoopStatus()`), and startup/resume bundle helper (`resolveAuthoritativeStartupResumeBundle()`) all live in `packages/core/src/loop/public-dev-loop-routing.mjs`.
 
 Its tests are:
 
@@ -118,7 +107,8 @@ Before answering status/progress/readiness/merge-state/next-step questions, cons
 
 Prior chat context is only a hint, never state authority.
 
-If authoritative identity/state (including issue↔PR linkage when relevant) cannot be resolved confidently, fail closed to reconcile/unknown instead of guessing.
+<!-- rule: FACADE-STATUS-AUTHORITATIVE-FAIL-CLOSED -->
+`FACADE-STATUS-AUTHORITATIVE-FAIL-CLOSED`: If authoritative identity/state (including issue↔PR linkage when relevant) cannot be resolved confidently, consumers MUST fail closed to reconcile/unknown instead of guessing.
 For async/durable-auto flows, do not claim that `dev-loop` has started or is running unless a visible Pi-managed async run id has also been resolved.
 
 When the routed next step requires confirmation for a mutation, the status/startup next action should name that concrete pending mutation (for example issue assignment to `copilot-swe-agent`) instead of generic "approval gate" wording.
@@ -140,10 +130,8 @@ Required authoritative inputs:
   - `auto_continue_current` always resolves to `durable_auto`
 - `issueLinkageResolution` (`resolved_linked_pr` \| `resolved_no_open_pr` \| `not_applicable`)
   - required when `currentState.target.kind === issue`
-- `issueReadiness` (`ready` \| `needs_clarification` \| `not_applicable`)
-  - required for Copilot-first issue targets with `issueLinkageResolution=resolved_no_open_pr`
-- `issueAssignmentState` (`unassigned` \| `assigned_to_copilot` \| `not_applicable`)
-  - required for Copilot-first issue targets with `issueLinkageResolution=resolved_no_open_pr`
+- `issueReadiness` (`ready` \| `needs_clarification` \| `not_applicable`) and `issueAssignmentState` (`unassigned` \| `assigned_to_copilot` \| `not_applicable`)
+  - both required for Copilot-first issue targets with `issueLinkageResolution=resolved_no_open_pr`
 - `artifactState` (`open` \| `closed` \| `merged` \| `not_applicable`)
 - explicit resolved `loopState` (`unknown` is not authoritative input)
 - required for async/durable-auto startup or status paths: `asyncRun`
@@ -151,8 +139,8 @@ Required authoritative inputs:
   - durable-auto success requires `kind=pi_managed_run`, a non-empty visible `runId`, and `visible=true`
   - when `inspectionState` is provided as `hidden`, `stale`, or `uninspectable`, durable-auto must fail closed with that state surfaced in diagnostics
   - detached local processes are diagnostic-only evidence and must fail closed instead of being treated as a successful async start
-- when refreshed loop state is `linked_pr_ready_for_followup` for an issue target with a resolved linked PR, startup/resume and status resolution must promote stale bootstrap waiting to the linked PR follow-up path (or fail closed if the linked-PR facts are incomplete/contradictory) instead of preserving the old bootstrap wait route
-- when refreshed loop state is `prior_linked_pr_closed_unmerged` for a Copilot-owned issue target with `issueLinkageResolution=resolved_no_open_pr`, startup/resume and status resolution must fail closed to reconcile instead of treating the issue as a healthy bootstrap wait or fresh issue-intake path
+- refreshed `linked_pr_ready_for_followup` for an issue target with a resolved linked PR: promote stale bootstrap waiting to the linked PR follow-up path, or fail closed if the linked-PR facts are incomplete/contradictory, instead of preserving the old bootstrap wait route
+- refreshed `prior_linked_pr_closed_unmerged` for a Copilot-owned issue target with `issueLinkageResolution=resolved_no_open_pr`: fail closed to reconcile instead of treating the issue as a healthy bootstrap wait or fresh issue-intake path
 
 Resolved bundle output shape:
 
@@ -222,8 +210,8 @@ Resolved bundle output shape:
 
 Dev-mode observability requirement:
 
-- saved artifacts must preserve the `contractTrace` decision, wait strategy, state-refresh boundary, and stop classification so a fresh session can explain why a healthy wait re-attached, stopped, or failed closed without replaying the whole run
-- wait/watch artifacts must record the effective timeout budget in force and whether the seam ran as `persistent_watch` or `one_shot_probe`; when a surface does not own a poll interval directly it may record `effectivePollIntervalMs=null` rather than inventing a value
+- saved artifacts MUST preserve the `contractTrace` decision, wait strategy, state-refresh boundary, and stop classification so a fresh session can explain a re-attach, stop, or fail-closed without replaying the run
+- wait/watch artifacts MUST record the effective timeout budget and whether the seam ran as `persistent_watch` or `one_shot_probe`; a surface without a poll interval MAY record `effectivePollIntervalMs=null` instead of inventing one
 
 Fail-closed semantics:
 
@@ -271,7 +259,7 @@ Internal strategy naming is implementation detail; normal orchestration always s
 
 Tracker-backed local implementation is an input-source addition to the existing `local_implementation` strategy. It does **not** create a new routing mode, strategy family, or public workflow entrypoint.
 
-For tracker-backed local sessions, the tracker issue is canonical. `docs/phases/phase-<n>.md` must not exist for that same session, and local execution must not maintain a second durable phase-doc copy of the same spec.
+For tracker-backed local sessions, the tracker issue is canonical; the no-duplicate-phase-doc rule is owned by `ARTIFACT-TRACKER-FIRST-NO-DUP` in [Artifact Authority Contract](artifact-authority-contract.md).
 
 Deterministic GitHub-backed spec resolution:
 
@@ -284,13 +272,13 @@ Deterministic GitHub-backed spec resolution:
 State-sync expectations for this slice:
 
 - local branch state and `tmp/` artifacts remain local execution state
-- durable scope / acceptance / status changes discovered during local execution should sync back to the tracker issue, because the tracker issue remains the canonical spec source for tracker-backed sessions
+- durable scope / acceptance / status changes discovered during local execution SHOULD sync back to the tracker issue
 - this slice does **not** introduce full bidirectional tracker sync or tracker-provider adapters beyond the bounded GitHub-backed helper path above
 
 Non-duplication rule:
 
 - do not create, read, or update `docs/phases/phase-<n>.md` for the same tracker-backed session
-- if a duplicate local phase doc already exists for the same tracker-backed session, reconcile that conflict explicitly before continuing; do not silently keep two durable spec surfaces alive
+- if a duplicate local phase doc already exists, reconcile explicitly before continuing rather than keeping two durable spec surfaces alive
 
 ## Copilot-first issue-assignment seam (unassigned issues)
 
@@ -330,7 +318,7 @@ For issue targets, authoritative issue↔PR linkage resolution remains part of s
 
 - when canonical issue state includes `linkedPr`, route selection first uses that linked PR as the authoritative routable artifact
 - when canonical issue state does **not** include `linkedPr`, status/reporting consumers must still require explicit authoritative linkage resolution before asserting there is no open linked PR
-- when authoritative linkage resolves an already-open linked PR, that PR is the only canonical active artifact for the issue during follow-up; startup/status/follow-up must reuse it and fail closed against opening another PR until the prior state is explicitly reconciled
+- <!-- rule: FACADE-LINKED-PR-SINGLE-ARTIFACT --> `FACADE-LINKED-PR-SINGLE-ARTIFACT`: when authoritative linkage resolves an already-open linked PR, that PR is the only canonical active artifact for the issue during follow-up; startup/status/follow-up MUST reuse it and MUST fail closed against opening another PR until the prior state is explicitly reconciled
 
 ## Deterministic routing order
 
@@ -349,6 +337,28 @@ First-match-wins routing posture:
 11. PR owned by Copilot -> `copilot_pr_followup`
 12. anything else -> fail closed to `needs_reconcile`
 
+## Required transitions
+
+The gate graph (`DEV_LOOP_GATE` / `PUBLIC_DEV_LOOP_GATE_CONTRACT` in
+`public-dev-loop-routing.mjs`) is stateless per cycle: each `evaluatePublicDevLoopRouting`
+call re-derives one gate from fresh authoritative state, so every non-terminal (route/wait)
+gate can be followed, on the next cycle, by any of the gates.
+
+- `final_approval` -> any dev-loop gate
+- `wait_watch` -> any dev-loop gate
+- `local_implementation` -> any dev-loop gate
+- `issue_intake` -> any dev-loop gate
+- `external_pr_followup` -> any dev-loop gate
+- `reviewer_fixer` -> any dev-loop gate
+- `copilot_pr_followup` -> any dev-loop gate
+
+Terminal gates (`stop_blocked_or_not_authorized`, `stop_done_terminal`,
+`waiting_for_merge_authorization`, `fail_closed_reconcile`) have no outgoing transitions —
+reaching one ends the current evaluation cycle. Their route-kind classification
+(`stop` / `needs_reconcile`) is the authoritative terminal marker; the route/wait gates above
+are the authoritative non-terminal set. This machine is wired into the L2/L3 state-machine
+conformance harness (`validate-state-machine-conformance.mjs`).
+
 ## Conflict reconciliation path (`CONFLICTING` / `DIRTY`)
 
 When an open linked PR reports merge conflict against `main`, treat this as an explicit bounded local-agent reconciliation path, not as a blind merge/update step:
@@ -360,27 +370,33 @@ When an open linked PR reports merge conflict against `main`, treat this as an e
    - issue/PR scope and acceptance criteria
    - current-head gate evidence and relevant unresolved review feedback
    - local validation surface for the touched conflict slice
-3. if required authoritative context is missing, stale for the current head, or contradictory, fail closed to reconcile
+3. <!-- rule: FACADE-CONFLICT-CONTEXT-FAIL-CLOSED --> `FACADE-CONFLICT-CONTEXT-FAIL-CLOSED`: if required authoritative context is missing, stale for the current head, or contradictory, orchestration MUST fail closed to reconcile
 4. only when that context is complete for one current head, resolve the conflict locally on the PR branch
-5. after conflict resolution, rerun required local validation, gate checks, and required CI checks for the new head before approval/merge evaluation
+5. <!-- rule: FACADE-CONFLICT-REVALIDATE-NEW-HEAD --> `FACADE-CONFLICT-REVALIDATE-NEW-HEAD`: after conflict resolution, orchestration MUST rerun required local validation, gate checks, and required CI checks for the new head before approval/merge evaluation
 
 ## `auto dev loop` durable auto contract
 
-When the public intent is `auto dev loop`, the router must:
+When the public intent is `auto dev loop`, the router MUST:
 
 1. require canonical current state resolution first
 2. route to the same detected internal strategy as normal state-based routing
 3. mark execution mode as durable auto ownership (`durable_auto`)
 4. keep waiting/watch states in healthy-wait semantics (`auto_healthy_wait`)
 
-In healthy waiting states, quiet watcher observations (for example `timeout` or `idle`) are observational only and must not be surfaced as attention by themselves. Escalation is still expected for true blocked/authorization/reconcile states.
+In healthy waiting states, quiet watcher observations (for example `timeout` or `idle`) are observational only and MUST NOT be surfaced as attention by themselves. Escalation is still expected for true blocked/authorization/reconcile states.
 
-For the Copilot-first bootstrap seam (`waiting_for_initial_copilot_implementation`), durable-auto ownership must route to the dedicated `watch-initial-copilot-pr.mjs` watcher with its default 1-hour watch budget. Quiet/no-activity observations alone do not eject durable ownership while refreshed authoritative state still resolves `waiting_for_initial_copilot_implementation`; inspect/status intents may still summarize that state and exit normally. This seam has a bootstrap-only exception to the general blocked escalation rule: when the linked PR is still bootstrap-only, approval-gated Actions/Copilot runs in `action_required` (GitHub Actions run conclusion, not a lifecycle state term) are treated as non-blocking observational signals (surfacing as concluded session activity) and do not by themselves force stop/escalation.
-When refreshed authoritative bootstrap state instead resolves `prior_linked_pr_closed_unmerged`, that is not a healthy wait seam: the routed outcome must fail closed to reconcile so status/startup answers surface the prior closed-unmerged PR decision rather than implying normal watch continuity.
+Bootstrap-only exception to the general blocked-escalation rule for `waiting_for_initial_copilot_implementation`:
 
-When that refreshed seam state advances to `linked_pr_ready_for_followup`, durable-auto continuation must re-enter the same linked PR follow-up path. If the follow-up handoff carries `conductorRouting.handoffEnvelope.requiresLocalIsolation=true`, orchestration should continue through an isolated checkout/worktree transition instead of treating that boundary as final completion.
+| Rule ID | Condition | Outcome |
+|---|---|---|
+| <!-- rule: FACADE-BOOTSTRAP-WATCH-ROUTE --> `FACADE-BOOTSTRAP-WATCH-ROUTE` | durable-auto ownership of this seam | ownership MUST route to the dedicated `watch-initial-copilot-pr.mjs` watcher with its default 1-hour watch budget |
+| <!-- rule: FACADE-BOOTSTRAP-QUIET-NO-EJECT --> `FACADE-BOOTSTRAP-QUIET-NO-EJECT` | quiet/no-activity observation while refreshed state still resolves this seam | durable ownership MUST NOT be ejected; inspect/status intents MAY still summarize that state and exit normally |
+| <!-- rule: FACADE-BOOTSTRAP-ACTION-REQUIRED-NONBLOCKING --> `FACADE-BOOTSTRAP-ACTION-REQUIRED-NONBLOCKING` | bootstrap-only linked PR; approval-gated Actions/Copilot run reports `action_required` (a run conclusion, not a lifecycle state) | treated as a non-blocking observational signal (concluded session activity); MUST NOT by itself force stop/escalation |
+| <!-- rule: FACADE-BOOTSTRAP-CLOSED-UNMERGED-RECONCILE --> `FACADE-BOOTSTRAP-CLOSED-UNMERGED-RECONCILE` | refreshed bootstrap state resolves `prior_linked_pr_closed_unmerged` | MUST fail closed to reconcile so status/startup surfaces the prior closed-unmerged decision instead of normal watch continuity |
+| <!-- rule: FACADE-BOOTSTRAP-FOLLOWUP-REENTRY --> `FACADE-BOOTSTRAP-FOLLOWUP-REENTRY` | refreshed seam state advances to `linked_pr_ready_for_followup` | durable-auto continuation MUST re-enter the same linked PR follow-up path |
+| <!-- rule: FACADE-BOOTSTRAP-ISOLATED-WORKTREE-CONTINUATION --> `FACADE-BOOTSTRAP-ISOLATED-WORKTREE-CONTINUATION` | follow-up handoff carries `conductorRouting.handoffEnvelope.requiresLocalIsolation=true` | orchestration SHOULD continue through an isolated checkout/worktree transition rather than treat that boundary as final completion (the runtime surfaces the flag; it does not enforce re-entry) |
 
-Main conductor orchestration must treat non-terminal follow-up/wait states (for example `waiting_for_copilot_review`) as continuation boundaries rather than clean completion. If an async child exits before the requested stop boundary and continuation is feasible, re-dispatch via the main session driver (the subagent exits on external wait; the main session re-dispatches); otherwise surface the concrete blocker.
+Main conductor orchestration MUST treat non-terminal follow-up/wait states (for example `waiting_for_copilot_review`) as continuation boundaries rather than clean completion. If an async child exits before the requested stop boundary and continuation is feasible, re-dispatch via the main session driver (the subagent exits on external wait; the main session re-dispatches); otherwise surface the concrete blocker.
 
 ## Internal / external model
 
@@ -413,9 +429,9 @@ flowchart TD
 
 - `dev-loop` is the only intended public workflow entrypoint.
 - any remaining specialized Copilot behavior is internal-only and non-user-invocable behind the canonical internal route-pack surface (`issue-intake`, `copilot-pr-followup`, `local-implementation`, `final-approval`).
-- Documentation and examples should lead with `dev-loop` and explain routed behavior.
-- Almost all workflow branching should converge into deterministic state-machine/tooling surfaces behind `dev-loop`.
-- User-visible variation should be expressed through the external `dev-loop` API / bounded parameters or settings, not by preserving multiple public workflow names or legacy compatibility seams.
+- Documentation and examples SHOULD lead with `dev-loop` and explain routed behavior.
+- Workflow branching SHOULD converge into deterministic state-machine/tooling surfaces behind `dev-loop`.
+- User-visible variation SHOULD be expressed through the `dev-loop` API/parameters or settings, not multiple public workflow names or legacy compatibility seams.
 
 ## Bounded variation parameter contract
 
@@ -437,7 +453,7 @@ Any conflict that would materially change artifact identity, ownership truth, or
 | `mode` | `bounded_handoff` (default) \| `durable_auto` | Steers execution mode; `durable_auto` uses the same durable-auto execution-mode semantics as `auto_continue_current`, without replacing the selected intent |
 | `watch` | boolean | Explicitly request wait/watch semantics; fails closed for otherwise-successful non-wait routed results, while preserving authoritative `stop` and `needs_reconcile` outcomes |
 | `intent` | any existing public `dev-loop` intent | Disambiguates the supported public intent; maps to existing contract values |
-| `targetPreference` | `prefer_github_first` (default) \| `prefer_local` | Steers routing preference; must not override authoritative linked-PR or active-artifact truth |
+| `targetPreference` | `prefer_local` (default) \| `prefer_github_first` | Steers routing preference; must not override authoritative linked-PR or active-artifact truth |
 
 The bounded allow-list is exported from `packages/core/src/loop/public-dev-loop-routing.mjs` as `DEV_LOOP_VARIATION_PARAMETER_CONTRACT`.
 
@@ -461,7 +477,7 @@ The following parameter/state combinations fail closed to `needs_reconcile` inst
 | `mode=bounded_handoff` + `intent=auto_continue_current` | `auto_continue_current` always requires durable auto execution mode |
 | Unrecognized `mode` value | Value not on the bounded allow-list |
 | Unrecognized `targetPreference` value | Value not on the bounded allow-list |
-| `watch=true` when an otherwise-successful routed result is not wait/watch-eligible | Watch semantics require a routed wait result (`routeKind=wait`), not just `selectedGate=wait_watch`; existing `stop` and `needs_reconcile` outcomes stay authoritative |
+| `watch=true` when an otherwise-successful routed result is not wait/watch-eligible | Watch semantics require a routed wait result (`routeKind=wait`), not just `selectedGate=wait_watch`; `stop`/`needs_reconcile` outcomes stay authoritative |
 | Non-boolean `watch` value | Value is outside the bounded boolean allow-list and must fail closed |
 | `targetPreference=prefer_local` when authoritative state has a linked PR or active PR artifact | Preference must not override authoritative PR/linked-PR active artifact truth |
 | `mode=durable_auto` without authoritative current state | Durable auto requires authoritative current state to route from |