dev-loops 0.5.0 → 0.7.1

package/skills/docs/release-runbook.md

@@ -0,0 +1,45 @@
+# Release runbook
+
+Releasing is fully automated from a tag. **Pushing a `v<version>` tag is the only
+manual step.** Everything after the tag is hands-off.
+
+## Procedure
+
+1. On `main` (merged, green), bump the version and add the matching
+   `## <version> - <date>` section to `CHANGELOG.md` (the empty `## Unreleased`
+   heading stays above the latest version).
+2. Tag the release commit and push the tag:
+
+   ```bash
+   git tag v<version>
+   git push origin v<version>
+   ```
+
+That is the whole manual flow. Do **not** create the GitHub Release by hand —
+the workflow does it (and is idempotent if you already created one).
+
+## What happens automatically
+
+- **`.github/workflows/release.yml`** fires on the `v*` tag push. It verifies the
+  tagged commit is on `origin/main`, extracts the `## <version>` block from
+  `CHANGELOG.md` via `scripts/release/extract-changelog-section.mjs`, and creates
+  the GitHub Release (`--latest`, notes = that CHANGELOG section). It is
+  **idempotent** (no-op if a Release for the tag already exists) and **fails
+  closed** if the version has no CHANGELOG section — an undocumented version never
+  gets an empty release.
+- **`.github/workflows/npm-publish.yml`** fires on `release: published` (created by
+  the step above) and publishes the packages to npm.
+
+## Failure modes
+
+- Tag not on `main`: the release workflow fails the on-main guard — re-tag the
+  correct commit.
+- Missing CHANGELOG section: the extraction step exits non-zero and no Release is
+  created. The workflow checks out the tagged commit, so editing `CHANGELOG.md`
+  alone is not enough — commit the `## <version>` section, then move the tag to
+  the new commit and re-push:
+
+  ```bash
+  git tag -f v<version>
+  git push --force origin v<version>
+  ```

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

@@ -0,0 +1,134 @@
+# UI e2e scoping step
+
+Canonical owner for **when the shared UI/mobile e2e loop is required**. Inclusion
+is **path-triggered and deterministic** — it does not depend on a human annotating
+the PR or a phase doc.
+
+## Trigger: a rendered-artifact change requires UI e2e coverage
+
+A PR that **adds or modifies a rendered HTML artifact** MUST run the shared UI e2e
+assertions (mobile + desktop) AND register that artifact in the e2e suite. A
+"rendered artifact" is anything that renders to a served page or component:
+
+- a presentation deck — `docs/presentations/*.html` (registered in `DECK_REGISTRY`)
+- an article page — `docs/articles/*.html` (registered in `ARTICLE_REGISTRY`; the
+  intro article is the published landing page)
+- the inspect-run viewer's served page/component — `scripts/loop/inspect-run-viewer.mjs`
+
+The trigger is the PR's **changed-file set** matched against these explicit globs.
+It is conservative on purpose (issue #976 scope): only artifacts that render to a
+page/component, matched by exact directory + single-segment `*.html` globs (no
+recursion) and the viewer source path.
+
+Registration is keyed on the **full repo-relative path**, not the basename, so
+`docs/articles/X.html` and `docs/presentations/X.html` (which share basenames,
+e.g. `introducing-dev-loops.html`) are **distinct** artifacts and can never alias
+onto each other — editing the article never counts as deck coverage and vice versa.
+
+### Examples — required
+
+- `docs/presentations/introducing-dev-loops.html` edited → UI e2e **required**
+  (deck-smoke CI job runs the deck fit specs).
+- `docs/articles/introducing-dev-loops.html` (the landing page) edited → UI e2e
+  **required** (article-smoke CI job runs the article fit specs); it is its own
+  registration, NOT covered by the same-named deck.
+- A new `docs/articles/new-page.html` added → UI e2e **required**, and because the
+  new page is not yet in `ARTICLE_REGISTRY` the gate **fails closed** until it is
+  registered (add an entry + a thin spec calling `defineArticleSuite`).
+- `scripts/loop/inspect-run-viewer.mjs` edited → UI e2e **required** (the viewer is
+  registered in `VIEWER_REGISTRY`).
+
+### Examples — not required
+
+- `packages/core/src/loop/copilot-loop-state.mjs`, `README.md`, `*.test.mjs`,
+  `docs/articles/foo.md` (not `.html`), or a nested `docs/articles/sub/x.html`
+  (the glob is single-segment) → UI e2e **not required**; the gate passes through.
+
+## Register the artifact in the suite
+
+"Registered" means the artifact appears in the shared registries:
+
+- decks → `DECK_REGISTRY` in `test/playwright/harness/deck-fit-harness.mjs`
+  (served from `docs/presentations/<deck>`) with a thin spec calling `defineDeckSuite`.
+- articles → `ARTICLE_REGISTRY` in `test/playwright/harness/deck-fit-harness.mjs`
+  (served from `docs/articles/<file>`) with a thin spec calling `defineArticleSuite`
+  (shared fit/CSP/no-horizontal-scroll assertions, minus the deck's per-section
+  named captures).
+- the viewer → `VIEWER_REGISTRY` in
+  `test/playwright/harness/inspect-run-viewer-harness.mjs`.
+
+The deterministic membership list the gate checks against lives in
+`packages/core/src/loop/ui-e2e-scoping.mjs` (`REGISTERED_ARTIFACT_PATHS`, keyed by
+full repo-relative path; `VIEWER_ARTIFACT_ID`). A sync test keeps
+`REGISTERED_ARTIFACT_PATHS` from drifting from `DECK_REGISTRY` + `ARTICLE_REGISTRY`;
+the single-valued `VIEWER_ARTIFACT_ID` is not import-checked against `VIEWER_REGISTRY`
+(that harness pulls `@playwright/test` into core), so keep the two in sync by hand.
+
+## Fail-closed semantics
+
+The check is wired as a gate precondition in `evaluatePrGateCoordination`
+(`packages/core/src/loop/pr-gate-coordination.mjs`), at a seam distinct from the
+mergeability (#980) and retrospective (#982) preconditions. It fails closed:
+
+- **Unregistered rendered artifact touched** → gate blocks with
+  `nextAction: run_ui_e2e_suite`, reason naming the artifact and that it needs
+  registration in the suite.
+- **Registered, but UI e2e suite did not pass for this head** (`uiE2ePassed` is
+  `false`/unknown) → gate blocks with the same action, reason that the suite must
+  run and pass first.
+- **Non-UI change** → `required: false`, gate passes through untouched.
+
+The detect layer reads the changed-file set from `gh pr view --json files` and
+derives `uiE2ePassed` from the `statusCheckRollup` UI e2e check(s)
+(`UI_E2E_CHECK_NAMES`): present UI e2e checks must all be `SUCCESS`; if none is
+present the value is unknown and the gate fails closed.
+
+Each rendered-artifact family has a stable, satisfiable CI job in
+`.github/workflows/ci.yml`, path/diff-conditioned in the `changes` job and named
+to match `UI_E2E_CHECK_NAMES` so the gate can read a real signal:
+
+- `viewer-smoke` → inspect-run viewer spec (triggered by the viewer source set).
+- `deck-smoke` → both presentation deck fit specs (triggered by
+  `docs/presentations/**` and the deck specs/harness/configs).
+- `article-smoke` → both article fit specs (triggered by `docs/articles/**` and the
+  article specs/harness/configs).
+
+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
+only the conservative path-glob + registry-membership + passing-coverage check.

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
 

package/skills/local-implementation/SKILL.md

@@ -43,11 +43,17 @@ Treat missing optional files as normal bootstrap conditions, not errors.
 
 ### Tracker-backed local implementation
 
-Local implementation supports two durable spec inputs:
+Local implementation supports these spec-of-record inputs. The first two are durable/committed artifacts; the third is a spec-of-record that is NOT a durable committed artifact:
+
+Durable/committed spec artifacts:
 
 - phase-doc-backed local sessions ([Phase Plan](../../docs/phases/phase-x.md) is canonical)
 - tracker-backed local sessions (the tracker issue is canonical)
 
+Non-durable spec-of-record (no committed plan artifact):
+
+- lightweight PR-body-as-spec sessions (`--lightweight`; the PR description is the canonical spec-of-record but NOT a durable committed artifact — the resolver output carries `canonicalSpecSource: pr_body` and the derived handoff envelope carries `specSource: pr_body`; no phase/plan doc minted or committed). Same gate sequence as the phase-doc path; only the backing artifact differs. See [Artifact Authority Contract](../docs/artifact-authority-contract.md) "Lightweight (PR-body-as-spec)".
+
 Tracker-backed local implementation stays inside the existing `local_implementation` path. For sub-issue tree decomposition, see [Sub-Issue Tree Contract](../../docs/sub-issue-tree-contract.md) (this is a source-repo reference; it is not part of the bundled `../docs/` runtime contract surface for installed skill copies). It does not introduce a new routing mode.
 
 When the local spec already lives in a tracker issue:
@@ -130,33 +136,33 @@ Follow [Anti-patterns](../docs/anti-patterns.md) for the general tooling-interna
 
 Apply [Structural Quality](../docs/structural-quality.md) from the `deep` review angle.
 
-## Light mode (small changes) — config-only
+## Light mode (small changes)
+
+Light mode is wired into gate dispatch. A PR that is **under threshold** (≤ `maxLines` lines changed AND ≤ `maxFiles` files, per `.devloops` field `localImplementation.lightMode` — this repo sets `maxLines: 20`, `maxFiles: 2`; the shipped built-in default has light mode disabled (`enabled: false`); if enabled without explicit values it falls back to `maxFiles: 3` / `maxLines: 200`) AND carries no `gate:full` label collapses BOTH `draft_gate` and `pre_approval_gate` to a single inline single-agent correctness + no-op check. The Copilot review request and its polling are skipped.
 
-Light mode is currently **config-only**: the schema, resolver, and scope detector are implemented, but no functional wiring exists yet in the local-implementation flow. When scope is small enough, the intent is to skip fan-out/fan-in and use a single review pass instead. Light mode will still require validation and pre-approval gate once wired.
+**Escalation:**
+1. Auto-escalate — if the inline check surfaces any finding whose severity is in the gate's `blockCleanOnFindingSeverities` (i.e. ≥ `worth-fixing-now`), dispatch escalates to full fan-out.
+2. Label override — the `gate:full` label forces full fan-out regardless of PR size.
 
-**Eligibility:** ≤3 files AND ≤200 lines changed (configurable via `.devloops` field `localImplementation.lightMode`).
+The `draft_gate` boundary (draft → ready) is still recorded because `requireDraftFirst` is honored: light mode only changes HOW the gate runs (inline vs fan-out), not WHETHER the draft boundary exists.
 
-Use `scripts/loop/detect-change-scope.mjs` to determine eligibility:
+Dispatch is resolved deterministically via `resolveGateDispatchMode(config, gate, { scope, hasFullLabel, inlineFindingSeverities })` from `@dev-loops/core/config`. `scripts/loop/resolve-gate-dispatch.mjs` is the CLI wrapper the orchestrator calls, combining `detect-change-scope.mjs` output with the `gate:full` label fact.
+
+Use `scripts/loop/detect-change-scope.mjs` to determine scope:
 ```sh
 node scripts/loop/detect-change-scope.mjs
 ```
 
-**Planned light mode path (not yet wired):**
-1. Validation (`npm run verify`)
-2. Single review pass (not multi-angle fan-out)
-3. Pre-approval gate
-4. Finalization
-
 **Override threshold:**
 ```yaml
 localImplementation:
   lightMode:
     enabled: true
-    maxFiles: 5
-    maxLines: 300
+    maxFiles: 2
+    maxLines: 20
 ```
 
-Disabled by default (opt-in). Scope above threshold falls back to full fan-out/fan-in path.
+Scope above threshold falls back to the full fan-out/fan-in path.
 
 ## Deterministic logging structure
 
@@ -264,6 +270,10 @@ For the **current phase only**, run this loop before implementation.
 
 ### 1. Create or update the durable phase doc and tmp scaffold
 
+**Lightweight (PR-body-as-spec) exception:** when the session is lightweight — the resolver output carries `canonicalSpecSource: pr_body` and the derived handoff envelope carries `specSource: pr_body` (started via `resolve-dev-loop-startup.mjs --issue <n> --lightweight`) — SKIP the durable phase-doc mint entirely. The PR description is the spec-of-record; do NOT create or commit any `docs/phases/*.md` for this session. The ephemeral `tmp/phases/` scaffold may still be used for local execution state. All other steps (read prior learning, plan, implement) proceed unchanged, and the gate sequence (draft → pre-approval fanout → detect-evidence → human merge) is identical. See [Artifact Authority Contract](../docs/artifact-authority-contract.md) "Lightweight (PR-body-as-spec)".
+
+Otherwise (default phase-doc path), create or update the durable phase doc.
+
 Use paths like:
 - `docs/phases/phase-0.md`
 - `tmp/phases/phase-0/`
@@ -512,7 +522,7 @@ After the phase plan passes review:
 3. Run local validation:
    - `npm run verify`
    - when a narrower local check is more honest for the touched slice, say so explicitly and run the narrowest justified subset instead of pretending the full verify path was unnecessary
-   - for user-facing HTML/UI/component slices when the user opts in, add a bounded deterministic browser smoke harness (prefer fixture-backed Playwright WebKit plus screenshot capture); use `npm run test:playwright:viewer` when that viewer/browser surface is part of the slice, and wire it into CI once it becomes required validation for that slice
+   - for a *rendered* HTML artifact (a deck `docs/presentations/*.html`, an article `docs/articles/*.html`, or the inspect-run viewer source) UI e2e coverage is **required and auto-scoped** — not opt-in. Touching one obliges you to register it in the shared harness and have a passing UI e2e suite, or the gate fails closed (see [UI e2e scoping step](../docs/ui-e2e-scoping-step.md)); run the matching shared suite locally, e.g. `npm run test:playwright:intro-deck` / `:intro-article` / `:viewer`. For a bespoke local UI surface that is not a registered rendered artifact, the WebKit smoke seam (fixture-backed Playwright WebKit plus screenshot capture) remains available without being mandatory
    - **Commit immediately after validation passes.** Once `npm run verify` (or the narrowest justified validation subset) is green, stage and commit the current slice of work with an atomic commit message. For tracker-backed sessions, also push the commit. In non-interactive subagent sessions, commit authorization is implicit — the subagent was dispatched to implement and must commit before exiting. In interactive sessions, wait for coordination agent authorization. Do not defer commits — uncommitted changes when the session terminates are a workflow defect.
 4. Review the implementation against the merged phase plan.
 5. Run the default pre-approval gate as a full review / fix loop on the branch before calling it review-complete, approval-ready, merge-ready, or ready for final handoff:
@@ -643,6 +653,7 @@ See [Stop Conditions](../docs/stop-conditions.md). Local-specific stops: phase c
 - PR creation always goes through `dev-loops pr create`, which is ALWAYS draft and always assigned — self-assigned by default (`--assignee @me` when none is given; honors an explicit `--assignee <login>` / `-a <login>`), never via raw `gh pr create`, and the PR body must contain `Closes #N` (or `Fixes #N`) for the linked issue so GitHub auto-closes it on merge. When `.devloops` sets `workflow.requireDraftFirst` to true, use `dev-loops pr create --assignee @me ...`. Do not create a fresh PR directly in ready-for-review state unless the user explicitly overrides that policy for the current PR scope. The draft gate inspection is a real workflow boundary, so a new PR must exist in draft before `gh pr ready` is eligible.
 - When authorization is pending, record the phase as `awaiting-finalization` and describe the exact missing step.
 - For phase-doc-backed sessions, merge the fully reviewed, locally validated branch back into local `main` when authorized.
+- Behind-branch integration before merge (for example a sibling PR merged first and both touch shared files): prefer a merge commit (`git merge origin/main`) over rebase + force-push. Since dev-loop PRs are squash-merged, intermediate branch history is discarded at merge time, so a merge commit lands an identical result on `main` while avoiding a non-fast-forward push to the remote. Force-push (`--force-with-lease` only, never bare `--force`) remains acceptable only for a branch the loop solely owns and where no integration alternative exists (rare); document that carve-out rather than leaving it implicit. After any integration that changes the head SHA, re-verify gate evidence at the new head (existing behavior — see [Merge Preconditions](../docs/merge-preconditions.md#required-before-merge)).
 
 ## Commit policy