dev-loops 0.6.0 → 0.7.2

package/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,67 +88,99 @@ 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.
-
-## Merge gate (`requireRetrospectiveGate`)
-
-When `workflow.requireRetrospectiveGate` is enabled in `.devloops` at repo root, merge-ready progression is blocked after `pre_approval_gate` unless the retrospective checkpoint:
-- has `state: "complete"`
-- includes a `behavioralReview` with `mergeApproved: true`, `followedWorkingAgreement` (boolean), `gateQualityAcceptable` (boolean), and `drifts` (array)
-- includes `mergeRecommendation` (non-empty string)
-- **(developer mode only)** includes `behavioralReview.internalToolingOnly: true` (boolean) and `behavioralReview.rawCallViolations: []` (empty array) — see **Internal-tooling-only rule** below
-
-The enforcement function is `evaluateRetrospectiveMergeApproval(checkpoint, { developerMode })` in `packages/core/src/loop/pr-gate-coordination.mjs`, called from `evaluatePrGateCoordination` at each merge-ready boundary.
-
-### Internal-tooling-only rule (issue #982) — DEVELOPER MODE ONLY, opt-in
-
-This is a **developer-mode** retro step: it enforces the dev-loops maintainers' own dogfooding discipline and is **opt-in** via `workflow.requireRetrospectiveInternalTooling` (**default OFF**). **Consumers of the dev-loops extension are never blocked by it** — a consumer may legitimately use raw `gh`/`python`/`node -e` in their own workflow, so when the flag is OFF (the consumer default) the `internalToolingOnly`/`rawCallViolations` fields are neither required nor enforced, and a complete, merge-approved checkpoint passes exactly as it would without these fields. The check only requires and enforces them when `workflow.requireRetrospectiveInternalTooling: true` (the dev-loops repo opts in via its own repo-root `.devloops`).
-
-When developer mode is ON, the loop's own execution must use internal dev-loops tooling only. **Agent-level top-level raw calls are all the same breach and all block the merge gate:**
-
-- `gh ...` (including `gh api`, `gh ... --jq`) — use `gate capture-threads`, `gate reply-resolve`, `dev-loops loop info`, `queue …`, or a `node scripts/...` wrapper instead
-- `python` / `python3` — parse JSON with the tool's `--jq`/built-in output, not an inline Python one-liner
-- `node -e` / `node --eval` — inline eval to read/parse tool output is a violation; `node scripts/foo.mjs` is **not**
-
-**Allowed (NOT violations):** dev-loops subcommands, and `node scripts/*.mjs` invocations — those scripts legitimately call `gh`/GraphQL internally; that is the tooling. The rule targets the agent's own top-level shell calls, not a script's internals.
-
-The retrospective author records the result in the checkpoint:
-- `behavioralReview.internalToolingOnly` (boolean) — `true` only when the run used internal tooling throughout
-- `behavioralReview.rawCallViolations` (array of strings) — one entry per agent-level raw call; empty when clean
-
-**Fail-closed (developer mode only):** when `requireRetrospectiveInternalTooling` is ON, the merge gate blocks (`retrospective_gate_pending`) if `internalToolingOnly` is not `true` **OR** `rawCallViolations` is missing/non-empty. `state: "complete"` alone is **not** sufficient — a clean tooling record is also required. When the flag is OFF (consumer default) this check is inert: it never blocks, even for a checkpoint that omits the fields or records a violation.
-
-**Back-compat:** an OLD checkpoint that omits `internalToolingOnly`/`rawCallViolations` only fails closed in developer mode; with the flag OFF (consumer default) it passes unchanged. Re-record the retrospective with the new fields to clear a developer-mode block.
-
-**Write-op allowlist (verifier only):** `gh pr merge`, `gh pr ready`, `gh issue create`, `gh issue edit` have no internal wrapper today. The deterministic verifier (below) records these as `allowedWriteOps` rather than violations so the gate is not blocked forever on an unavoidable gap. Close the gap with a wrapper to remove an entry. The gate itself still fails on any non-empty `rawCallViolations` the author records.
-
-### Deterministic verifier
-
-`node scripts/loop/check-retro-tooling.mjs [--transcript <path>] [--json]` reads a newline-delimited transcript of the shell commands the agent ran (one top-level command per line, via `--transcript` or stdin) and reports agent-level raw `gh`/`python`/`python3`/`node -e`/`node --eval` calls. Use it to derive the `rawCallViolations` array the retrospective author records. Exit code `1` when violations are found, `0` when clean. The pure `analyzeTranscript(transcript)` export returns `{ violations, allowedWriteOps, internalToolingOnly }`.
-
-Matching rules: a tool name at the start of a command segment (start of line, or after `&&`/`||`/`|`/`;`); `node` is a violation only with `-e`/`--eval`. Before classifying, the verifier normalizes the segment head — it strips leading `NAME=value` env-assignment prefixes (`GH_TOKEN=x gh api`), strips a leading wrapper binary from `{sudo, env, xargs, time, nice, command}` (`sudo gh api`, `xargs gh api`), and reduces a path-prefixed binary to its basename (`./node_modules/.bin/gh`, `/usr/bin/python3`) — so the common prefixed/wrapped raw-call forms are caught. Known limitation: it does NOT fully parse shell quoting/substitution. A separator inside a quoted argument can over-report; deeply obfuscated calls (command substitution `$(...)`, aliases, `eval`) may evade it — prefer single-line, single-purpose commands in transcripts.
-
-### Merge gate states
-
-| Retrospective state | Merge gate result |
-|---|---|
-| No checkpoint file | Blocked: `retrospective_gate_pending` |
-| `state: "complete"` with `mergeApproved: true` and valid base fields (consumer default; internal-tooling check OFF) | Allowed: proceeds to `FINAL_APPROVAL_READY` |
-| `state: "complete"` without `mergeApproved: true` | Blocked |
-| **Developer mode ON** + `internalToolingOnly` not `true`, or `rawCallViolations` missing/non-empty | Blocked |
-| **Developer mode OFF** (consumer default) + missing `internalToolingOnly`/`rawCallViolations` or a recorded violation | Allowed (check is inert) |
-| Missing base required fields (`followedWorkingAgreement`, `gateQualityAcceptable`, `drifts`, `mergeRecommendation`) | Blocked |
-| `state: "skipped"` or `state: "required"` | Blocked |
-
-### Configuration
-
-```yaml
-# .devloops at repo root
-workflow:
-  requireRetrospective: true                  # startup/resume gate
-  requireRetrospectiveGate: true               # merge gate after pre_approval_gate
-  requireRetrospectiveInternalTooling: true    # developer-mode internal-tooling-only check (default OFF; consumers leave unset)
-```
+<!-- 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 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)
+
+<!-- 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
+   contract; see [Workflow Handoff Contract](./workflow-handoff-contract.md).
+2. **Durability — advisory PR comment.** The conductor posts a single advisory PR
+   comment carrying the findings (`rawCallViolations`, `internalToolingOnly`,
+   `allowedWriteOps`). Durable and on-GitHub, but **not a gate**. No disk artifact
+   is written for retrospective *findings*.
+3. **No config.** There is nothing to configure: the retrospective always runs and
+   always returns findings. `requireRetrospectiveGate` and
+   `requireRetrospectiveInternalTooling` no longer exist.
+
+A PR that is otherwise green becomes merge-ready with the violations **recorded**,
+not blocked. The conductor may note them, open a follow-up, coach — or ignore.
+
+### Internal-tooling-only rule (issue #982) — now advisory
+
+This rule records the dev-loops maintainers' own dogfooding discipline: the loop's
+own execution should use internal dev-loops tooling, not agent-level raw
+`gh`/`python`/`node -e` escape hatches. **It no longer blocks.** The flagged calls
+are reported as advisory findings via the envelope + PR comment.
+
+**Flagged as raw-call violations:** `gh ...` (including `gh api`, `gh ... --jq`),
+`python` / `python3`, `node -e` / `node --eval` (inline eval). **Allowed (NOT
+violations):** dev-loops subcommands and `node scripts/*.mjs` invocations — those
+scripts legitimately call `gh`/GraphQL internally; that is the tooling. The rule
+targets the agent's own top-level shell calls, not a script's internals.
+
+**Write-op allowlist (verifier only):** `gh pr merge`, `gh pr ready`,
+`gh issue create`, `gh issue edit` have no internal wrapper today. The deterministic
+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
+newline-delimited transcript of the shell commands the agent ran (one top-level
+command per line, via `--transcript` or stdin) and reports agent-level raw
+`gh`/`python`/`python3`/`node -e`/`node --eval` calls. It is a **findings-producer**:
+its JSON output (`{ ok, internalToolingOnly, rawCallViolations, allowedWriteOps }`)
+is returned to the conductor via the envelope's `retrospectiveFindings` field (the
+envelope carries the normalized shape `{ internalToolingOnly, rawCallViolations,
+allowedWriteOps }` — the redundant `ok` flag is dropped by normalization) — it
+is **not** written to a checkpoint and **not** a gate. Exit code `1` when violations
+are found, `0` when clean. The pure `analyzeTranscript(transcript)` export returns
+`{ violations, allowedWriteOps, internalToolingOnly }`.
+
+Matching rules: a tool name at the start of a command segment (start of line, or
+after `&&`/`||`/`|`/`;`); `node` is a violation only with `-e`/`--eval`. Before
+classifying, the verifier normalizes the segment head — it strips leading
+`NAME=value` env-assignment prefixes (`GH_TOKEN=x gh api`), strips a leading
+wrapper binary from `{sudo, env, xargs, time, nice, command}` (`sudo gh api`,
+`xargs gh api`), and reduces a path-prefixed binary to its basename
+(`./node_modules/.bin/gh`, `/usr/bin/python3`) — so the common prefixed/wrapped
+raw-call forms are caught. Known limitation: it does NOT fully parse shell
+quoting/substitution. A separator inside a quoted argument can over-report; deeply
+obfuscated calls (command substitution `$(...)`, aliases, `eval`) may evade it —
+prefer single-line, single-purpose commands in transcripts.
+
+### Lifecycle reconciliation
+
+The retrospective is described consistently as a **post-merge / advisory
+reflection**, never a pre-merge blocker. The former contradiction —
+`lifecycle-state.mjs` documenting the retro as a post-merge write while
+`pr-gate-coordination.mjs` enforced it pre-merge — is resolved by removing the
+pre-merge gate: the merge lifecycle step proceeds, and the retrospective is an
+advisory reflection whose findings reach the conductor via the envelope.
 
 ## Durable artifact format
 
@@ -162,25 +197,17 @@ The checkpoint file is written by `.pi/extensions/dev-loop-behavioral-review.ts`
 
 ### After retrospective is done (written by operator or skill)
 
-A minimal completion clears the startup gate. To also clear the **merge gate**
-(`requireRetrospectiveGate`), include the `behavioralReview`, `gateQuality`, and
-`mergeRecommendation` fields:
+A minimal completion clears the startup/resume completion gate. The checkpoint
+file carries **only completion state** — retrospective *findings*
+(`behavioralReview`, `rawCallViolations`, `internalToolingOnly`) no longer live on
+disk; they travel in the handoff envelope's `retrospectiveFindings` field and an
+advisory PR comment (issue #1077, Reading B):
 
 ```json
 {
   "state": "complete",
   "completedAt": "2026-05-29T16:30:00.000Z",
-  "notes": "Loop followed working agreement; minor drift on thread resolution.",
-  "gateQuality": "Real gates with concrete findings and follow-through.",
-  "mergeRecommendation": "Merge approved — all gates passed clean.",
-  "behavioralReview": {
-    "mergeApproved": true,
-    "followedWorkingAgreement": true,
-    "gateQualityAcceptable": true,
-    "drifts": [],
-    "internalToolingOnly": true,
-    "rawCallViolations": []
-  }
+  "notes": "Loop followed working agreement; minor drift on thread resolution."
 }
 ```
 
@@ -199,9 +226,9 @@ A minimal completion clears the startup gate. To also clear the **merge gate**
 | Artifact | Location |
 |---|---|
 | Checkpoint state machine | `packages/core/src/loop/retrospective-checkpoint.mjs` (internal core module; not part of the public package exports surface) |
-| Merge gate evaluator | `packages/core/src/loop/pr-gate-coordination.mjs` — `evaluateRetrospectiveMergeApproval` |
-| Internal-tooling verifier | `scripts/loop/check-retro-tooling.mjs` (+ `test/loop/check-retro-tooling.test.mjs`) |
-| Tests | `packages/core/test/retrospective-checkpoint.test.mjs`, `packages/core/test/pr-gate-coordination.test.mjs` |
+| Internal-tooling verifier (findings-producer) | `scripts/loop/check-retro-tooling.mjs` (+ `test/loop/check-retro-tooling.test.mjs`) |
+| Advisory findings envelope field | `packages/core/src/loop/handoff-envelope.mjs` — `retrospectiveFindings` |
+| Tests | `packages/core/test/retrospective-checkpoint.test.mjs`, `packages/core/test/pr-gate-coordination.test.mjs`, `packages/core/test/handoff-envelope.test.mjs` |
 | Extension (writes required marker, fires review prompt) | `.pi/extensions/dev-loop-behavioral-review.ts` |
 | Checkpoint file | `.pi/dev-loop-retrospective-checkpoint.json` |
 | AGENTS.md repo contract | [Agent Instructions](../../AGENTS.md) — concise repo contract and working rules |

package/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/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/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/skills/docs/ui-e2e-scoping-step.md

@@ -96,6 +96,38 @@ to match `UI_E2E_CHECK_NAMES` so the gate can read a real signal:
 So a deck- or article-only PR has a CI check that can actually satisfy the gate;
 without these jobs such a PR would fail closed with no satisfiable signal.
 
+## Verifying a UI change: render and look, but don't persist ad-hoc checks
+
+When you change a rendered artifact's layout, **verify it visually before merging** —
+render the built page and inspect real geometry (`getBoundingClientRect` for
+edges/widths, a full-page screenshot to actually look at it) at desktop and mobile
+widths. This intermediary e2e pass is a required *verification strategy*: a layout
+claim ("the columns align now") is only credible once measured against the rendered
+page, not the source CSS.
+
+It is **not** something to persist into the codebase. The registered, always-on
+coverage is the shared fit/CSP suite (`defineArticleSuite`/`defineDeckSuite`); do
+not grow it with one-off pixel/alignment assertions written to confirm a single
+fix. Use a throwaway script to render, measure, and screenshot while iterating,
+then drop it. Adding a bespoke geometry assertion per fix bloats the suite and
+couples it to incidental layout numbers.
+
+## An assertion must be able to fail on the defect
+
+A UI assertion that is **true for the broken state validates the bug**. Real
+example (the layout regression this rule comes from): a check asserted
+`margin-left > 1px` on the prose to prove it was "centered" — but the visible bug
+*was* the prose floating in a narrow centered measure, misaligned from the
+full-width boxes beside it. `margin-left` was large in exactly the broken state, so
+the check passed green on every gate while the page rendered visibly broken.
+
+Before trusting any UI assertion, confirm it **fails on the defect**: run it against
+the broken layout, or inject the defect (e.g. shove one block's left edge) and check
+that the assertion goes red. An assertion that cannot fail on the bug it names is
+not coverage — it is false confidence. Prefer asserting the invariant that actually
+defines "correct" (e.g. all content blocks share one left edge within tolerance)
+over a proxy that happens to correlate with it.
+
 ## Non-goals
 
 Not always-on screenshot testing; not mandatory multi-browser. The criterion is

package/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
 

package/skills/docs/workflow-handoff-contract.md

@@ -17,6 +17,35 @@ template.
 | Gate state (detectors) + strategy defaults | `currentGate`, `worktreeRequired` |
 | Settings (`.devloops` at repo root + `defaults.yaml`) | `gateConfig`, `stopRules`, `asyncStartMode`, `requireDraftFirst`, `maxCopilotRounds` |
 | Gate state (detectors) | `currentHeadSha`, `ciStatus`, `unresolvedThreadCount`, `copilotRoundCount` |
+| Canonical sanctioned-command map (`scripts/loop/sanctioned-commands.mjs`) | `sanctionedCommands` |
+
+## Sanctioned commands (MANDATORY DEFAULT — issue #1081)
+
+`sanctionedCommands` is a **mandatory default** element of every handoff
+envelope. It is the operation → wrapper command map (which wrapper performs
+which GitHub/loop operation), plus the forbidden and orchestrator-owned lists.
+The `loop build-envelope` CLI injects it into every emitted envelope, so a
+spawned dev-loop subagent receives it verbatim without the briefer adding it —
+no re-deriving which wrapper does `gh pr ready` etc.
+
+The **single source of truth** is `scripts/loop/sanctioned-commands.mjs` (a
+frozen data module). `@dev-loops/core` stays consumer-agnostic: it defines the
+envelope SHAPE and carries whatever `sanctionedCommands` object the consumer
+supplies; the repo-specific `scripts/...` paths live only in the consumer
+module. Do not duplicate the map into prose — reference the module.
+
+```typescript
+sanctionedCommands?: {
+  reads: Record<string, string>;         // operation → wrapper path (some also accept `loop info`)
+  edits: Record<string, string>;
+  lifecycle: Record<string, string>;
+  forbidden: string[];                   // raw `gh pr view/checks/edit`, `node -e`, `python -c`, transcript tailing, sleep-poll loops
+  orchestratorOwned: string[];           // `gh pr merge`, board status transitions — never done by a subagent
+};
+```
+
+A contract test (`test/contracts/sanctioned-commands-exist.test.mjs`) asserts
+every mapped wrapper exists on disk and fails closed if one is renamed/removed.
 
 ## Acceptance templates
 
@@ -111,6 +140,15 @@ interface HandoffEnvelope {
     scopeConstraint?: string;
     customStopAt?: string;
   };
+
+  // Mandatory default (issue #1081). Source: scripts/loop/sanctioned-commands.mjs
+  sanctionedCommands?: {
+    reads: Record<string, string>;
+    edits: Record<string, string>;
+    lifecycle: Record<string, string>;
+    forbidden: string[];
+    orchestratorOwned: string[];
+  };
 }
 ```
 
@@ -121,6 +159,7 @@ interface HandoffEnvelope {
 3. Execute `nextAction`.
 4. Respect `stopRules` — do not proceed past a gated stop point without authorization.
 5. Use `acceptance` to self-validate before declaring completion.
+6. Use `sanctionedCommands` as the authoritative operation → wrapper map: never call a raw `gh`/`node -e`/`python -c` for an operation the map covers, and never perform an `orchestratorOwned` action.
 
 ## Backward compatibility