dev-loops 0.6.0 → 0.7.1

package/.claude/skills/docs/artifact-authority-contract.md

@@ -10,7 +10,7 @@ Other repo docs may summarize or link this contract, but they should not redefin
 
 dev-loops supports two mutually exclusive artifact authority modes. Every work item originates from exactly one authoritative artifact: a GitHub issue or a persisted markdown plan file. Work originates from a PR or a direct local change only when explicitly requested.
 
-The shipped extension default selects local-planning; see [Shipped default posture](#shipped-default-posture) below. The mode names that follow describe the two tiers; "default" in their headings refers to the github-first code-level fallback in `BUILT_IN_DEFAULTS`, which the shipped extension layer overrides to local-first.
+The shipped extension default selects local-planning; see [Shipped default posture](#shipped-default-posture) below. The mode names that follow describe the two tiers; "default" in their headings refers to the local-first code-level default in `BUILT_IN_DEFAULTS`.
 
 ### Tracker-first
 
@@ -25,6 +25,7 @@ Key contract:
 - GitHub issue state is authoritative — not local notes or chat context
 - A linked PR is the single canonical follow-up artifact for the issue
 - When an open linked PR exists, reuse it rather than opening another
+- Follow-ups discovered while working a PR/loop are noted on the originating issue or PR body by default; a standalone issue is filed only when the follow-up is genuinely independent of the PR and outlives it (see [Sub-Issue Tree Contract](../../docs/sub-issue-tree-contract.md))
 - Implementation may proceed through either the GitHub-first routed path or the local implementation strategy (see [Public Dev Loop Contract](public-dev-loop-contract.md) `targetPreference`)
 
 ### Local-planning
@@ -41,12 +42,29 @@ Key contract:
 - GitHub issues may still be used for tracking or linking, but the plan file is authoritative for scope and acceptance criteria
 - A tracker-backed local implementation session (GitHub issue as canonical spec) must not also maintain a duplicate `docs/phases/phase-<n>.md` — see [Public Dev Loop Contract](public-dev-loop-contract.md) "Tracker-backed local implementation input-source contract"
 
+### Lightweight (PR-body-as-spec)
+
+**The PR description itself is the authoritative artifact store — no committed plan artifact.** This is a lightweight modifier on the local `--issue` path (`resolve-dev-loop-startup.mjs --issue <n> --lightweight`, `canonicalSpecSource: pr_body`), not a settings-level mode. No phase/plan doc is minted or committed; the PR body carries the spec-of-record invariants directly. The gate sequence is identical to the phase-doc path (draft → pre-approval fanout → detect-evidence → human merge); only the backing artifact differs (PR body vs phase doc).
+
+Artifacts:
+- **Planning + execution artifact:** the GitHub PR — its description is the spec, its diff is the execution
+- **No committed plan doc:** no `docs/phases/*.md` is created for the session
+
+Key contract:
+- The PR body must carry the same invariants a durable spec would: **Objective/why, in-scope + explicit non-goals, testable acceptance criteria, definition of done, open questions/risks**. `scripts/loop/validate-pr-body-spec.mjs` (reusing the generic markdown logic of `@dev-loops/core/loop/issue-refinement-artifact`, `validatePrBodySpec`) validates these and **fails closed** with a distinct `missing_*` reason per absent invariant.
+- The PR body MUST also carry the `Closes #N` linkage (GitHub's other closing keywords count too); `validate-pr-body-spec` fails closed with `missing_closing_issue_reference` without it, and with `closes_wrong_issue` when an `--expected-issue` is given and doesn't match — the lightweight path's issue-tracking state must never silently diverge from PR state (issue #1181).
+- This flips the promotion invariant below (P4, "the PR body carries the committed plan-doc **path**"): under lightweight there is no committed plan doc — the PR body **is** the spec, not a pointer to one.
+- The explicit `--lightweight` flag is the primary, deterministic trigger. The secondary heuristic (chore/fix commit type + no `--plan-file` + small change) is a documented manual signal for when to reach for the flag; it is not an automatic selector.
+- `--lightweight` is rejected when combined with `--plan-file` (they are opposites: `--plan-file` commits a durable plan doc as the spec, `--lightweight` makes the PR body the spec) and only composes with `--issue`.
+- Pre-approval acceptance-criteria verification reads the AC/DoD/invariants directly from the PR body rather than a linked issue body; see [Acceptance Criteria Verification](acceptance-criteria-verification.md).
+
 ### Mode selection table
 
 | Mode | Canonical artifact | GitHub issue required | Settings value |
 |---|---|---|---|
 | Tracker-first | GitHub issue | Yes | `strategy.default: github-first` |
 | Local-planning (shipped default) | Markdown plan file | No | `strategy.default: local-first` |
+| Lightweight (PR-body-as-spec) | GitHub PR description | Yes (`--issue`) | modifier: `--lightweight` (`canonicalSpecSource: pr_body`) |
 
 `inputSource.default` further disambiguates local-first startup:
 | inputSource | Meaning |
@@ -81,7 +99,7 @@ The `inputSource.default` key disambiguates local-first startup:
 
 The effective default for a consumer comes from the config-merge layering in `packages/core/src/config/config.mjs`. Precedence, low to high:
 
-1. `BUILT_IN_DEFAULTS` (frozen in `config.mjs`) — `strategy.default: github-first`. This is the code-level fallback when no other layer sets the key.
+1. `BUILT_IN_DEFAULTS` (frozen in `config.mjs`) — `strategy.default: local-first`. This is the code-level fallback when no other layer sets the key.
 2. Extension-packaged defaults (`packages/core/src/config/extension-defaults.yaml`, loaded as the `extensionDefaults` layer) — `strategy.default: local-first`. This is the opinion the package ships and the layer that wins over the built-in fallback.
 3. Repo-local `.pi/dev-loop/defaults.*` (legacy) — applied when present.
 4. Repo `.devloops` at repo root — the per-repo override, highest precedence. When `.devloops` is absent, the legacy `.pi/dev-loop/settings.*` / `overrides.*` apply at this position instead.
@@ -95,7 +113,7 @@ Two legacy repo-local layers also exist under `.pi/dev-loop/` (the package no lo
 These are not valid artifact authority mode selectors:
 - `strategy.default: copilot` — not a valid mode; the enum accepts only `github-first` or `local-first` (`packages/core/src/config/config.mjs`)
 - Free-form string values — fail closed
-- Omitting `strategy.default` from every layer — resolves to `github-first` from `BUILT_IN_DEFAULTS`; with the shipped extension layer present it resolves to `local-first`
+- Omitting `strategy.default` from every layer — resolves to `local-first` from `BUILT_IN_DEFAULTS`
 
 ## Local-first plan-file flow end to end
 
@@ -103,7 +121,7 @@ Under local-planning, one plan file moves through four stages. Each stage has a
 
 ### P1 — Plan-file artifact + config (#949)
 
-The plan file is a phase-doc-format markdown document. Its directory is `localPlanning.plansDir`, which defaults to `docs/phases/` (built-in default in `config.mjs`, mirrored in `extension-defaults.yaml`; `resolvePlansDir(config)` resolves it). Its required base authoring sections — `## Status`, `## Objective`, `## In scope`, `## Explicit non-goals` — and the validator `scripts/refine/validate-plan-file.mjs` (`validatePlanFile`, distinct `missing_*` codes per absent or empty section) are defined in the [Plan-file Contract](plan-file-contract.md).
+The plan file is a phase-doc-format markdown document. It lives under `docs/phases/`, the existing phase-docs directory. Its required base authoring sections — `## Status`, `## Objective`, `## In scope`, `## Explicit non-goals` — and the validator `scripts/refine/validate-plan-file.mjs` (`validatePlanFile`, distinct `missing_*` codes per absent or empty section) are defined in the [Plan-file Contract](plan-file-contract.md).
 
 ### P2 — Intake (#950)
 

package/.claude/skills/docs/copilot-loop-operations.md

@@ -188,7 +188,7 @@ Preferred defaults for this repo:
 - parent/subagent no-activity threshold for watcher-style runs: at least **15 minutes**
 - active-long-running notice threshold for watcher-style runs: about **30 minutes**
 
-These are the defaults built into `probe-copilot-review.mjs`, `run-watch-cycle.mjs`, and the `watchArgs` emitted by `copilot-pr-handoff.mjs`. Do not pass removed CLI policy flags (`--poll-interval-ms`, `--timeout-ms`, `--probe-only`) — helpers hard-error when they are provided. Timeouts and intervals are derived from `packages/core/src/loop/policy-constants.mjs`.
+These are the defaults built into `probe-copilot-review.mjs`, `run-watch-cycle.mjs`, and the `watchArgs` emitted by `copilot-pr-handoff.mjs`. Do not pass removed CLI policy flags (`--poll-interval-ms`, `--probe-only`): the scripts reject them as usage errors, but do not rely on that as a guaranteed hard stop in the `dev-loops gate …` path — the CLI retry-wrapper (`buildCorrectedArgs`) may strip an unrecognized/removed flag and silently retry with defaults, so passing one can quietly fall back to default behavior rather than failing. `probe-copilot-review.mjs` does accept `--timeout-ms` (watch budget in ms; `0` = single immediate idle check, no watch); timeouts and intervals are otherwise derived from `packages/core/src/loop/policy-constants.mjs`.
 
 ### Outer-loop checkpoint: canonical re-attachment artifact
 

package/.claude/skills/docs/cross-harness-regression-contract.md

@@ -0,0 +1,60 @@
+# Cross-Harness Regression Contract
+
+Canonical owner for harness-agnostic non-regression across Pi and Claude Code.
+
+## What counts as a harness-specific change
+
+A change is harness-specific when it touches a seam that branches by runtime harness (Pi vs Claude Code), including:
+
+- Runner coordination (`scripts/loop/pr-runner-coordination.mjs`, `scripts/loop/_pr-runner-coordination.mjs`)
+- Run-id injection / async-start semantics (`packages/core/src/loop/async-start-contract.mjs`, `packages/core/src/loop/run-context.mjs`)
+- Subagent / Task fan-out tool provisioning
+- Harness-specific environment variables (`PI_SUBAGENT_RUN_ID`, `DEVLOOPS_RUN_ID`)
+- Session/intercom wiring
+- TUI behavior
+- Any capability detection or `process.env` branch whose outcome differs per harness
+
+## Required cross-harness test coverage
+
+Every harness-specific change MUST add or keep a test that exercises the path of the harness it does not directly target. A pull request that alters behavior on one harness without any test evidence for the other harness fails this contract.
+
+## The additive/no-op bar
+
+State the bar symmetrically, in both directions:
+
+- A change additive on Pi MUST be a no-op on Claude Code, or its effect on Claude Code MUST be explicitly validated by a test.
+- A change additive on Claude Code MUST be a no-op on Pi, or its effect on Pi MUST be explicitly validated by a test.
+
+Definitions:
+
+- **No-op**: the existing test suite for the other harness passes unmodified — no assertion needed to change, no new test required, because the seam does not fire for that harness.
+- **Explicitly validated**: a new or updated test directly asserts the other harness's resulting behavior (not merely "did not throw"), covering both the case where the seam is inert and the case where it participates.
+
+## Claude-Code-path test inventory
+
+When a change targets a Claude-Code-specific seam, the following suites are the baseline that MUST stay green, and are the first place to add coverage for a Pi-originated change that must not regress Claude Code:
+
+- `npm run test:assets` — runs `test/contracts/*.test.mjs`, including `test/contracts/claude-assets-reproducible.test.mjs`, `test/contracts/claude-headless-smoke.test.mjs`, `test/contracts/claude-plugin-manifest.test.mjs`, `test/contracts/claude-plugin-marketplace.test.mjs`, `test/contracts/claude-hooks-settings.test.mjs`, and `test/contracts/cli-harness-agnostic.test.mjs`
+- `npm run smoke:headless` — runs `scripts/claude/headless-info-smoke.mjs`; this is a manual/local-only check, not part of `npm test` or `npm run verify` and not run by CI — run it directly when a change touches Claude Code headless-info behavior
+- `npm run test:core` — runs `packages/core/test/*.test.mjs`, including `packages/core/test/claude-headless-entry.test.mjs`, `packages/core/test/claude-hook-decisions.test.mjs`, `packages/core/test/run-context.test.mjs`, `packages/core/test/async-start-contract.test.mjs`
+
+Symmetrically, for a change targeting the Claude-Code-specific seam that must not regress Pi, `npm run test:extension` (which runs `test/extension-*.test.mjs`, including `test/extension-pi-adapter.test.mjs`, the Pi-side adapter inventory) is the baseline suite to check and extend.
+
+## How to add coverage
+
+1. Identify the harness-specific seam the change touches (see the surface list above).
+2. Locate the existing test file that already covers that seam for the harness being changed, and its counterpart for the other harness (from the inventory above, or the nearest analogous file).
+3. Add or extend a test asserting the other harness's behavior directly — do not rely on an untested assumption that the change is inert there.
+4. Run the relevant suite locally (`npm run test:assets`, `npm run test:core`, `npm run test:extension`, or `npm run smoke:headless` as applicable) before opening the pull request.
+
+## Non-goals
+
+- No new or expanded CI matrix: `npm run verify` (which CI runs on every pull request) already covers `test:assets`, `test:extension`, `test:scripts`, `test:core`, `test:docs`, and `test:dev-loop` — every suite named above except `npm run smoke:headless`, which is manual/local-only by design (see the test inventory above).
+- No bespoke cross-harness enforcement script: naming the required suites here, combined with CI already running them on every pull request, satisfies the coverage bar.
+- No rewriting of existing harness-specific code as part of adopting this contract.
+
+## Cross-references
+
+- [AGENTS.md](../../AGENTS.md)
+- [Dev Loop Skill](../dev-loop/SKILL.md)
+- [Public Dev Loop Contract](public-dev-loop-contract.md)

package/.claude/skills/docs/issue-intake-procedure.md

@@ -111,6 +111,7 @@ Preflight verdicts:
 - do not rely only on PR title/body containing a literal issue number
 - treat an open linked PR as the active implementation for this issue
 - once an open linked PR exists, that PR is the only canonical follow-up artifact for the issue; attach follow-up work to it and do not open another PR unless the prior PR was explicitly superseded and reconciled first
+- **follow-up-capture rule:** when a follow-up is discovered while working a PR/loop, note it on the originating issue (or the PR body); file a standalone issue only if the follow-up is genuinely independent of the PR **and** outlives it (a real separate bug/feature that would be lost as a note on a soon-closed issue). Prefer noting PR-scoped follow-ups on the originating artifact over spinning up standalone tracker items for work that is part of the same effort or will be resolved imminently. See [Sub-Issue Tree Contract](../../docs/sub-issue-tree-contract.md).
 - if a PR already exists, classify bootstrap-wait versus follow-up:
   `node <resolved-skill-scripts>/loop/detect-initial-copilot-pr-state.mjs --repo <resolved-repo> --issue <number>`
 - `waiting_for_initial_copilot_implementation`: keep waiting; in durable-auto mode use:

package/.claude/skills/docs/local-planning-flow.md

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

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

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

package/.claude/skills/docs/merge-preconditions.md

@@ -47,6 +47,22 @@ doing manually; it is not a general conflict-resolution engine.
 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)
 
+> 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
 
 The PR title is a contract surface, so a merge-blocking marker in the title is enforced
@@ -89,7 +105,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.
 

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/public-dev-loop-contract.md

@@ -437,7 +437,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`.
 

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

@@ -87,65 +87,87 @@ Callers have two supported integration options:
 
 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)
-```
+## Advisory findings — never a merge gate (issue #1077, Reading B)
+
+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`
+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
+   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.
+
+### 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 +184,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 +213,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/.claude/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/.claude/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