dev-loops 0.7.1 → 0.7.2

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
 
@@ -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 |

package/.claude/skills/docs/retrospective-checkpoint-contract.md

@@ -1,6 +1,9 @@
 # Retrospective checkpoint contract
 
-This document defines the enforcement seam for the post-run behavioral retrospective checkpoint after qualifying async `dev-loop` completions in this repository. Whether a missing checkpoint blocks the next qualifying start/resume is controlled by `.devloops` at repo root `workflow.requireRetrospective`; shipped defaults remain permissive and this repo opts in.
+Canonical owner for the enforcement seam of the post-run behavioral retrospective checkpoint after qualifying async `dev-loop` completions in this repository.
+
+<!-- rule: RETRO-ENFORCEMENT-CONFIG-GATED -->
+Whether a missing checkpoint blocks the next qualifying start/resume MUST be controlled by `.devloops` at repo root `workflow.requireRetrospective`; shipped defaults remain permissive and this repo opts in.
 
 ## Relationship to formal dev mode
 
@@ -85,21 +88,24 @@ Callers have two supported integration options:
 4. Call `evaluateRetrospectiveGate({ checkpointState, proposedRouting })`.
 5. Use the gate result (not the raw routing result) as the effective routing decision when enforcement is enabled; otherwise keep the raw routing result and treat the checkpoint artifact as advisory context only.
 
-If the gate result is `needs_reconcile`, the caller must not proceed with the proposed routing. The `nextAction` field instructs the operator to complete or explicitly skip the retrospective.
+<!-- rule: RETRO-GATE-FAIL-CLOSED -->
+If the gate result is `needs_reconcile`, the caller MUST NOT proceed with the proposed routing. The `nextAction` field instructs the operator to complete or explicitly skip the retrospective.
 
 ## Advisory findings — never a merge gate (issue #1077, Reading B)
 
+<!-- rule: RETRO-ADVISORY-NEVER-GATE -->
 The retrospective is **advisory**: it runs, records flagged raw-call / discipline
 observations honestly, and passes them back to the conductor (main agent) to
-**decide** what to do with them — but it **NEVER blocks a merge or any lifecycle
-transition**. The pre-merge retrospective gate (`evaluateRetrospectiveMergeApproval`
+**decide** what to do with them — but it MUST NOT block a merge or any lifecycle
+transition. The pre-merge retrospective gate (`evaluateRetrospectiveMergeApproval`
 and the `requireRetrospectiveGate` / `requireRetrospectiveInternalTooling` config
 keys) has been **removed**. There is no `retrospective_gate_pending` / `blocked`
 disposition on account of the internal-tooling raw-call record.
 
 ### How findings travel (Reading B)
 
-1. **Deterministic return contract.** The loop subagent's handoff envelope carries
+<!-- rule: RETRO-FINDINGS-ENVELOPE-CARRY -->
+1. **Deterministic return contract.** The loop subagent's handoff envelope MUST carry
    the retrospective findings as a structured `retrospectiveFindings` field — the
    `check-retro-tooling.mjs` JSON output (`{ internalToolingOnly, rawCallViolations,
    allowedWriteOps }`), not prose. The conductor reads that field. This is a hard
@@ -134,6 +140,13 @@ verifier records these as `allowedWriteOps` rather than violations so they are
 surfaced distinctly, not as breaches. Close the gap with a wrapper to remove an
 entry. None of these block anything.
 
+**Inline-interpreter check item:** the raw-call scan below mechanically catches
+`node -e`/`python3 -c`/heredoc calls as a `rawCallViolations` entry — the same
+class barred by `OPS-NO-INLINE-INTERPRETER` in
+[Copilot loop operations](copilot-loop-operations.md). This is an addition to
+what the retrospective records, not a new gate: `RETRO-ADVISORY-NEVER-GATE`
+semantics are unchanged.
+
 ### Deterministic verifier (findings-producer)
 
 `node scripts/loop/check-retro-tooling.mjs [--transcript <path>] [--json]` reads a

package/.claude/skills/docs/spike-mode-contract.md

@@ -1,6 +1,6 @@
 # Spike-mode contract
 
-A spike is a time-boxed, exploratory dev-loop run started from a local question with no GitHub issue. Its deliverable is a findings document. When the exploration reaches a recommendation, the operator concludes it with one of two exits: **discard** (drop it with zero tracker artifacts) or **graduate** (emit a #947-style local-first plan file that enters the existing plan→PR promotion path).
+Canonical owner for spike mode: the time-boxed, exploratory dev-loop run started from a local question with no GitHub issue. Its deliverable is a findings document. When the exploration reaches a recommendation, the operator concludes it with one of two exits: **discard** (drop it with zero tracker artifacts) or **graduate** (emit a #947-style local-first plan file that enters the existing plan→PR promotion path).
 
 This doc is the canonical operator sequence for spike mode and carries a worked example showing both exits. The spike artifact lives outside the tracker; it is exempt from the production-gate ceremony at entry and runs under a relaxed gate profile (`gates.spike`). The [Artifact Authority Contract](artifact-authority-contract.md) owns the local-planning model a graduated spike feeds into.
 
@@ -53,7 +53,10 @@ Hand the artifact to startup with `--spike` (mutually exclusive with `--issue`,
 node scripts/loop/resolve-dev-loop-startup.mjs --spike <spike.md>
 ```
 
-`buildSpikeInput` (`scripts/loop/resolve-dev-loop-startup.mjs`) reads the file read-only — no tracker mutation, no GitHub call, no issue or PR number. It requires the exploration scaffold; a missing/unreadable file, or one failing `validateSpikeExplorationSections`, throws and startup fails closed (exit 1, no readiness bundle). On success it builds a `local_phase` startup input with the resolved spike path as the target `phase` and threads `spikeIntakeState` onto the output. A spike with no Recommendation reports `spike_in_progress`. The spike path is exempt from the worktree-isolation guard because there is no issue to key a worktree on (`planFileExempt: true`).
+`buildSpikeInput` (`scripts/loop/resolve-dev-loop-startup.mjs`) reads the file read-only — no tracker mutation, no GitHub call, no issue or PR number.
+
+<!-- rule: SPIKE-STARTUP-SCAFFOLD-GATE -->
+Startup MUST require the exploration scaffold: a missing/unreadable file, or one failing `validateSpikeExplorationSections`, MUST throw, and startup MUST fail closed (exit 1, no readiness bundle). On success it builds a `local_phase` startup input with the resolved spike path as the target `phase` and threads `spikeIntakeState` onto the output. A spike with no Recommendation reports `spike_in_progress`. The spike path is exempt from the worktree-isolation guard because there is no issue to key a worktree on (`planFileExempt: true`).
 
 ### 3. Run under the relaxed gate profile
 
@@ -67,7 +70,8 @@ When the exploration concludes, fill in `## Recommendation`. The intake state is
 node scripts/refine/exit-spike.mjs --spike-file <spike.md> --disposition <discard|graduate> [--plan-file <path>] [--json]
 ```
 
-`evaluateSpikeExit` (`packages/core/src/loop/spike-exit-contract.mjs`) is eligible only from `spike_ready_for_exit`. From any other state it fails closed with `not_ready_for_exit`; an unrecognized disposition fails closed with `unknown_disposition`. On a fail-closed path the CLI makes zero tracker mutation, writes no plan file, and exits 1.
+<!-- rule: SPIKE-EXIT-ELIGIBILITY -->
+`evaluateSpikeExit` (`packages/core/src/loop/spike-exit-contract.mjs`) MUST be eligible only from `spike_ready_for_exit`: from any other state it MUST fail closed with `not_ready_for_exit`, and an unrecognized disposition MUST fail closed with `unknown_disposition`. On a fail-closed path the CLI MUST make zero tracker mutation, write no plan file, and exit 1.
 
 ## Exit dispositions
 
@@ -75,22 +79,25 @@ The two dispositions are `SPIKE_EXIT_DISPOSITION.DISCARD` (`"discard"`) and `SPI
 
 ### discard
 
-The recommendation is "don't pursue". The spike is dropped with zero tracker artifacts; the findings document on disk is the whole record. The CLI writes nothing and creates no GitHub artifact. `--plan-file` is irrelevant for a discard.
+<!-- rule: SPIKE-DISCARD-ZERO-MUTATION -->
+The recommendation is "don't pursue". Discard MUST drop the spike with zero tracker artifacts — the findings document on disk is the whole record. The CLI MUST write nothing and MUST create no GitHub artifact. `--plan-file` is irrelevant for a discard.
 
 ### graduate
 
-The recommendation is "pursue this". `buildGraduatedPlanBody` builds a #947-consumable plan-file body from the spike's `Question`, `Approach`, `Findings`, and `Recommendation`, and `exit-spike.mjs` writes it to the required `--plan-file` path. The mapping:
+<!-- rule: SPIKE-GRADUATE-PLAN-FILE-REQUIRED -->
+The recommendation is "pursue this". `buildGraduatedPlanBody` builds a #947-consumable plan-file body from the spike's `Question`, `Approach`, `Findings`, and `Recommendation`, and `exit-spike.mjs` writes it to the required `--plan-file` path — `--plan-file` MUST be present for a graduate exit; the CLI MUST NOT guess an output path. The mapping:
 
 - `Question` + `Approach` become the Objective's context.
 - `Recommendation` becomes the In-scope work.
 - `Findings` are recorded as supporting evidence.
 - A fixed Explicit non-goals block keeps the plan from re-opening the concluded exploration.
 
-The emitted body carries the four plan-file base sections (`## Status`, `## Objective`, `## In scope`, `## Explicit non-goals` — see [Plan-file Contract](plan-file-contract.md)), so it passes `validatePlanFile` and enters the local-first plan→PR promotion path (#952) unchanged: refine it, hold the local human-review checkpoint, then `promote-plan.mjs`. Graduation is idempotent — `buildGraduatedPlanBody` is pure, so re-running reproduces the same plan file. `buildGraduatedPlanBody` fails closed (throws) on an empty required section, so a graduate exit cannot emit a plan the validator would reject. `--plan-file` is required for graduate (the CLI never guesses an output path).
+The emitted body carries the four plan-file base sections (`## Status`, `## Objective`, `## In scope`, `## Explicit non-goals` — see [Plan-file Contract](plan-file-contract.md)), so it passes `validatePlanFile` and enters the local-first plan→PR promotion path (#952) unchanged: refine it, hold the local human-review checkpoint, then `promote-plan.mjs`. Graduation is idempotent — `buildGraduatedPlanBody` is pure, so re-running reproduces the same plan file, and it fails closed (throws) on an empty required section, so a graduate exit cannot emit a plan the validator would reject.
 
 ## Relaxed gate profile
 
-A spike's deliverable is a findings doc, so it does not carry the full production draft → pre-approval → Copilot gate set. `gates.spike` is a relaxed profile, shipped in `packages/core/src/config/extension-defaults.yaml`:
+<!-- rule: SPIKE-RELAXED-GATE-PROFILE -->
+A spike's deliverable is a findings doc, so it MUST NOT carry the full production draft → pre-approval → Copilot gate set; it runs under `gates.spike`, a relaxed profile shipped in `packages/core/src/config/extension-defaults.yaml`:
 
 ```yaml
 gates:

package/.claude/skills/docs/stop-conditions.md

@@ -2,29 +2,44 @@
 
 Canonical owner for agent stop / wait / block conditions across all workflow families.
 
+## Terms
+
+| Term | Definition |
+|---|---|
+| <!-- term: state:blocked --> `blocked` | Lifecycle state requiring a human decision before the loop continues. |
+| <!-- term: state:done --> `done` | Terminal lifecycle state. |
+| <!-- term: state:approval_ready --> `approval_ready` | Lifecycle state where approval evidence is ready but merge authorization is not implied. |
+| <!-- term: state:merge_ready --> `merge_ready` | Lifecycle state where merge preconditions are ready to evaluate. |
+| <!-- term: state:waiting --> `waiting` | Lifecycle state for healthy external waits. |
+| <!-- term: state:waiting_for_initial_copilot_implementation --> `waiting_for_initial_copilot_implementation` | Bootstrap wait state for the first Copilot PR. |
+| <!-- term: state:waiting_for_copilot_review --> `waiting_for_copilot_review` | Copilot review-settle wait state for the current head. |
+| <!-- term: state:waiting_for_merge_authorization --> `waiting_for_merge_authorization` | Stop state for merge-ready work without explicit merge authorization. |
+| <!-- term: reason:needs_reconcile --> `needs_reconcile` | Reconcile reason for ambiguous, contradictory, or unsupported state. |
+
 ## Genuine stop conditions
 
-| Condition | Strategy | Behavior |
-|---|---|---|
-| `blocked` lifecycle state | all | Stop for human decision |
-| `done` lifecycle state | all | Terminal stop |
-| `approval_ready` without explicit merge auth | `final_approval` | Stop at approval gate |
-| `merge_ready` without explicit merge auth | all | Stop at `waiting_for_merge_authorization` |
-| `autonomy.humanMergeOnly: true` | all | Always stop at merge for human action, even with explicit merge auth — agent never runs `gh pr merge` (see [Merge preconditions](merge-preconditions.md)) |
-| Ambiguous / contradictory state | all | Fail closed to `needs_reconcile` |
-| Missing authoritative startup inputs | `dev-loop` | Fail closed |
+| Rule ID | Condition | Strategy | Behavior |
+|---|---|---|---|
+| <!-- rule: STOP-BLOCKED-001 --> `STOP-BLOCKED-001` | `blocked` lifecycle state | all | The loop MUST stop for a human decision. |
+| <!-- rule: STOP-DONE-001 --> `STOP-DONE-001` | `done` lifecycle state | all | The loop MUST treat the state as terminal. |
+| <!-- rule: STOP-APPROVAL-001 --> `STOP-APPROVAL-001` | `approval_ready` without explicit merge authorization | `final_approval` | The loop MUST stop at the approval gate. |
+| <!-- rule: STOP-MERGE-AUTH-001 --> `STOP-MERGE-AUTH-001` | `merge_ready` without explicit merge authorization | all | The loop MUST stop at `waiting_for_merge_authorization`. |
+| <!-- rule: STOP-HUMAN-MERGE-001 --> `STOP-HUMAN-MERGE-001` | `autonomy.humanMergeOnly: true` | all | The loop MUST stop at merge for human action even with explicit merge authorization; the agent MUST NOT run `gh pr merge` (see [Merge preconditions](merge-preconditions.md)). |
+| <!-- rule: STOP-RECONCILE-001 --> `STOP-RECONCILE-001` | Ambiguous or contradictory state | all | The loop MUST fail closed to `needs_reconcile`. |
+| <!-- rule: STOP-STARTUP-INPUTS-001 --> `STOP-STARTUP-INPUTS-001` | Missing authoritative startup inputs | `dev-loop` | The loop MUST fail closed. |
 
 ## Non-stop conditions
 
-| Condition | Strategy | Behavior |
-|---|---|---|
-| `waiting` lifecycle state | `wait_watch` | Healthy wait; re-dispatch from main session |
-| `waiting_for_initial_copilot_implementation` | `issue_intake` | Bootstrap wait with 1h watch budget |
-| `waiting_for_copilot_review` | `copilot_pr_followup` | Continuation boundary, not completion |
-| Quiet watcher observations | `wait_watch` | Observational only, do not surface |
+| Rule ID | Condition | Strategy | Behavior |
+|---|---|---|---|
+| <!-- rule: STOP-WAIT-001 --> `STOP-WAIT-001` | `waiting` lifecycle state | `wait_watch` | The loop MUST treat this as a healthy wait and re-dispatch from the main session. |
+| <!-- rule: STOP-INITIAL-COPILOT-001 --> `STOP-INITIAL-COPILOT-001` | `waiting_for_initial_copilot_implementation` | `issue_intake` | The loop MUST use the bootstrap wait with a one-hour watch budget. |
+| <!-- rule: STOP-COPILOT-REVIEW-001 --> `STOP-COPILOT-REVIEW-001` | `waiting_for_copilot_review` | `copilot_pr_followup` | The loop MUST treat this as a continuation boundary, not completion. |
+| <!-- rule: STOP-QUIET-WATCHER-001 --> `STOP-QUIET-WATCHER-001` | Quiet watcher observations | `wait_watch` | The loop MUST treat quiet observations as observational only and MUST NOT surface them as stops by themselves. |
 
 ## Cross-references
 
 - [Confirmation rules](confirmation-rules.md)
 - [Merge preconditions](merge-preconditions.md)
 - [Public Dev Loop Contract](public-dev-loop-contract.md)
+- [Contract style guide](contract-style-guide.md)

package/.claude/skills/docs/tracker-first-loop-state.md

@@ -1,7 +1,8 @@
 # Tracker-First Story-to-PR Contract
 
-This document defines the adapter-agnostic MVP contract for the tracker-first
-story-to-PR workflow in `dev-loops`.
+Canonical owner for the adapter-agnostic MVP contract for the tracker-first
+story-to-PR workflow in `dev-loops`, and for the tracker-first loop state
+machine (#449).
 
 **MVP invariant: one tracker work item → one GitHub PR.**
 
@@ -30,7 +31,8 @@ Implementation for each:
 | Epic / PRD reference | Optional linked metadata only; no roll-up or automation in this slice |
 | ADR / RFC reference | Optional linked metadata only; no decision-sync in this slice |
 
-**Invariant:** For any single tracker work item in scope, there is at most
+<!-- rule: TRACKER-ONE-ACTIVE-PR -->
+For any single tracker work item in scope, there MUST be at most
 one active GitHub PR at a time. Multi-PR workflows and roll-up automation
 are out of scope for this slice.
 
@@ -57,6 +59,9 @@ already-correct PR leaves it unchanged.
 
 ### 3.1 Required PR Metadata
 
+<!-- rule: TRACKER-PROJECTION-REQUIRED-METADATA -->
+Every projected PR MUST carry the following fields:
+
 | Field | Rule |
 |---|---|
 | PR title | `[{TRACKER_ID}] {tracker item title}` — bracketed tracker identifier followed by the item title verbatim |
@@ -64,7 +69,7 @@ already-correct PR leaves it unchanged.
 | PR body — Summary section | Required. Brief description of the change implemented in this PR. |
 | PR body — Acceptance Criteria section | Required. Copied or linked from the tracker item's acceptance criteria. |
 | Labels | Required: `tracker:{TRACKER_ID}`. Optional reference labels: `epic:{EPIC_ID}`, `prd:{PRD_ID}` when references are present. |
-| Draft state | PR must start as a draft. It must not be marked ready-for-review until development work is complete. |
+| Draft state | PR MUST start as a draft. It MUST NOT be marked ready-for-review until development work is complete. |
 
 ### 3.2 Optional Reference Metadata
 
@@ -85,9 +90,9 @@ They are read-only metadata in this slice and do not trigger any automation:
 2. **On tracker item field change**: Re-apply projection rules to PR title,
    body, and labels. Leave any sections not covered by projection rules
    (e.g. reviewer-added review comments) intact.
-3. **Idempotent regeneration**: If the PR already has the correct title, body
-   sections, and labels, no mutation is performed. Projection is a no-op
-   when the current state already matches the target.
+3. <!-- rule: TRACKER-PROJECTION-IDEMPOTENT --> **Idempotent regeneration**: Projection MUST be a no-op when the PR already has the correct
+   title, body sections, and labels — re-applying the rules to an already-correct PR MUST NOT
+   mutate it.
 
 ### 3.4 PR Body Template
 
@@ -120,7 +125,7 @@ implementations map canonical action names to tracker-native field updates.
 | `pr_merged` — PR merged | `set_done` | Tracker moves to done/completed terminal state |
 | `pr_closed_unmerged` — PR closed without merge | `none` | No automatic terminal transition; human decision required |
 | `no_tracker_item` | `none` | No tracker item to update |
-| `blocked_needs_user_decision` | `none` | Stop and report; no automatic tracker update |
+| <!-- rule: TRACKER-BLOCKED-FAIL-CLOSED --> `blocked_needs_user_decision` | `none` | An unexpected or contradictory snapshot MUST stop and report; the helper MUST NOT apply an automatic tracker update |
 
 ### 4.2 Event Triggers
 

package/.claude/skills/docs/validation-policy.md

@@ -4,9 +4,8 @@ Canonical owner for validation requirements across all workflow families.
 
 ## Default validation
 
-- `npm run verify` is the default repo-level local validation path
-- Must pass before: PR creation, gate entry, merge
-- At minimum: `npm test && npm run test:dev-loop`
+<!-- rule: VALIDATE-VERIFY-BEFORE-GATE -->
+`VALIDATE-VERIFY-BEFORE-GATE`: `npm run verify` is the default repo-level local validation path and MUST pass before PR creation, gate entry, and merge; at minimum this means `npm test && npm run test:dev-loop`.
 
 ## Gate-specific requirements
 
@@ -17,8 +16,8 @@ Canonical owner for validation requirements across all workflow families.
 
 ## Coverage requirements
 
-- ≥90% coverage for lines, statements, functions, and branches on changed files
-- Test-first for all non-trivial logic
+<!-- rule: VALIDATE-COVERAGE-THRESHOLD -->
+`VALIDATE-COVERAGE-THRESHOLD`: Changed files MUST have ≥90% coverage for lines, statements, functions, and branches, and non-trivial logic MUST be test-first.
 
 ## Cross-references