dev-loops 0.4.0 → 0.6.0

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

@@ -93,17 +93,48 @@ When `workflow.requireRetrospectiveGate` is enabled in `.devloops` at repo root,
 - 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)` in `packages/core/src/loop/pr-gate-coordination.mjs`, called from `evaluatePrGateCoordination` at each merge-ready boundary.
+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 fields | Allowed: proceeds to `FINAL_APPROVAL_READY` |
+| `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 |
-| Missing required fields (`followedWorkingAgreement`, `gateQualityAcceptable`, `drifts`, `mergeRecommendation`) | 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
@@ -111,8 +142,9 @@ The enforcement function is `evaluateRetrospectiveMergeApproval(checkpoint)` in
 ```yaml
 # .devloops at repo root
 workflow:
-  requireRetrospective: true        # startup/resume gate
-  requireRetrospectiveGate: true    # merge gate after pre_approval_gate
+  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)
 ```
 
 ## Durable artifact format
@@ -130,11 +162,25 @@ 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:
+
 ```json
 {
   "state": "complete",
   "completedAt": "2026-05-29T16:30:00.000Z",
-  "notes": "Loop followed working agreement; minor drift on thread resolution."
+  "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": []
+  }
 }
 ```
 
@@ -153,7 +199,9 @@ The checkpoint file is written by `.pi/extensions/dev-loop-behavioral-review.ts`
 | Artifact | Location |
 |---|---|
 | Checkpoint state machine | `packages/core/src/loop/retrospective-checkpoint.mjs` (internal core module; not part of the public package exports surface) |
-| Tests | `packages/core/test/retrospective-checkpoint.test.mjs` |
+| 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` |
 | 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

@@ -0,0 +1,237 @@
+# 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).
+
+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.
+
+The spike track shipped across three phases: P1 (#964) the `--spike` intake state machine, P2 (#965) the relaxed gate profile and the discard/graduate exits, P3 (#966) this doc.
+
+## Shipped surfaces
+
+| Stage | Helper script | Pure logic |
+|---|---|---|
+| Validate | `scripts/refine/validate-spike-file.mjs` | `validateSpikeFile` / `validateSpikeExplorationSections` (in the helper script) |
+| Start | `scripts/loop/resolve-dev-loop-startup.mjs --spike <path>` | `buildSpikeInput` (in the script) + `evaluateSpikeIntakeState` (`@dev-loops/core/loop/spike-intake-contract`) |
+| Exit | `scripts/refine/exit-spike.mjs` | `evaluateSpikeExit` / `buildGraduatedPlanBody` (`@dev-loops/core/loop/spike-exit-contract`) |
+
+The spike findings artifact carries four authoring sections (`scripts/refine/validate-spike-file.mjs`, `SPIKE_FILE_BASE_SECTIONS`):
+
+- `## Question` — what the spike investigates
+- `## Approach` — how the exploration was carried out
+- `## Findings` — the evidence gathered
+- `## Recommendation` — the exit marker
+
+The first three (`SPIKE_FILE_EXPLORATION_SECTIONS`) are the exploration scaffold required to **start** a spike. `Recommendation` (`SPIKE_FILE_EXIT_MARKER_SECTION`) is filled in during the spike; once it is present and non-empty, the intake state flips to ready-for-exit.
+
+## Intake states
+
+`evaluateSpikeIntakeState` (`packages/core/src/loop/spike-intake-contract.mjs`) classifies the artifact into one of three `SPIKE_INTAKE_STATE` values from two facts — whether the exploration scaffold is valid, and whether a Recommendation is present:
+
+| State | Meaning |
+|---|---|
+| `spike_in_progress` | Scaffold (Question/Approach/Findings) valid; no Recommendation yet |
+| `spike_ready_for_exit` | Scaffold valid and a non-empty Recommendation is present; an exit decision can be made |
+| `ambiguous_fail_closed` | Scaffold invalid (a missing or empty base section); fail closed, no routing |
+
+## Operator sequence
+
+### 1. Author the exploration scaffold
+
+Write a findings artifact carrying `## Question`, `## Approach`, and `## Findings` with non-empty bodies. `## Recommendation` is left for the spike to fill in. Check the full set of base sections with the validator:
+
+```
+node scripts/refine/validate-spike-file.mjs --input <spike.md> --json
+```
+
+The payload is `{ checker: "validate-spike-file", ok, errors }`, with a distinct `missing_*` code per absent or empty section (`missing_question`, `missing_approach`, `missing_findings`, `missing_recommendation`). An in-progress spike reports `missing_recommendation` here and is still startable, because startup gates on the exploration scaffold (`validateSpikeExplorationSections`), which omits the Recommendation.
+
+### 2. Start the spike
+
+Hand the artifact to startup with `--spike` (mutually exclusive with `--issue`, `--pr`, `--input`, `--plan-file`):
+
+```
+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`).
+
+### 3. Run under the relaxed gate profile
+
+A spike runs under `gates.spike`, a lighter angle set than the production draft → pre-approval gates. See [Relaxed gate profile](#relaxed-gate-profile) below.
+
+### 4. Reach a Recommendation, then exit
+
+When the exploration concludes, fill in `## Recommendation`. The intake state is now `spike_ready_for_exit`, and `exit-spike.mjs` can conclude the spike. It recomputes the intake facts (`validateSpikeExplorationSections` for the scaffold, `extractSection` for the Recommendation), runs `evaluateSpikeExit`, and routes to one of two dispositions.
+
+```
+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.
+
+## Exit dispositions
+
+The two dispositions are `SPIKE_EXIT_DISPOSITION.DISCARD` (`"discard"`) and `SPIKE_EXIT_DISPOSITION.GRADUATE` (`"graduate"`).
+
+### 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.
+
+### 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:
+
+- `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).
+
+## 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`:
+
+```yaml
+gates:
+  spike:
+    angles:
+      - scope
+      - docs
+    excludeAngles: []
+    required: false
+    requireCi: false
+    mandatoryAngles: []
+```
+
+| Knob | Spike value | Production draft/pre-approval | Why for a spike |
+|---|---|---|---|
+| `angles` | `scope`, `docs` | the full production angle set | A findings doc needs a scope check and a docs check, so the angle set is small and docs-first |
+| `required` | `false` | `true` | The spike's record is the findings doc, so the gate is advisory and the loop proceeds without a passing verdict |
+| `requireCi` | `false` | `true` (pre-approval always requires CI) | A spike produces no production code to run CI against |
+
+`gates.spike` resolves through the same config-merge layering and the same `resolveGateConfig(config, "spike")` path as `draft` and `preApproval` (`packages/core/src/config/config.mjs`) — no new strategy→knob resolver. It is `optional()` in the schema (`packages/core/src/config/config.mjs`, `schemas/dev-loop-config.schema.json`) and absent for non-spike work, so production gates are unaffected. A repo `.devloops` can override any of these knobs.
+
+## Worked example
+
+One spike, `spike-cache.md`, from question to a Recommendation, shown through both exits.
+
+### Authored scaffold
+
+```markdown
+# Spike: response cache
+
+## Question
+
+Would an in-process LRU cache on the metadata fetch measurably cut p95 latency?
+
+## Approach
+
+Add a throwaway `@lru_cache` wrapper behind a flag, replay a captured request
+trace, and compare p95 with and without the cache.
+
+## Findings
+
+The trace replay shows p95 dropping from 240ms to 90ms with the cache, with a
+~3MB steady-state memory cost and no correctness regressions on the replay set.
+```
+
+Validation reports the spike is still in progress — the Recommendation is not yet written, so the full-section validator flags it while the scaffold itself is complete:
+
+```
+$ node scripts/refine/validate-spike-file.mjs --input spike-cache.md --json
+{ "checker": "validate-spike-file", "ok": false, "errors": [ { "code": "missing_recommendation", "message": "..." } ] }
+```
+
+Startup accepts it anyway, because the entry gate is the exploration scaffold:
+
+```
+$ node scripts/loop/resolve-dev-loop-startup.mjs --spike spike-cache.md
+# ... startup output carries spikeIntakeState: "spike_in_progress"
+```
+
+### Recommendation reached
+
+The operator fills in the exit marker:
+
+```markdown
+## Recommendation
+
+Adopt the cache behind a default-on flag; the latency win is large and the
+memory cost is small. Ship it as a follow-up plan.
+```
+
+The intake state is now `spike_ready_for_exit`, so the spike is exitable.
+
+### Exit A — discard (leaves nothing behind)
+
+Had the findings come out the other way — say the latency win was within noise — the recommendation would be "don't pursue", and the operator discards:
+
+```
+$ node scripts/refine/exit-spike.mjs --spike-file spike-cache.md --disposition discard --json
+{ "ok": true, "action": "discard", "spikeFile": "/abs/spike-cache.md" }
+```
+
+No plan file is written, no GitHub artifact is created, and no tracker entry is made. The `spike-cache.md` findings doc on disk is the entire record of the exploration.
+
+### Exit B — graduate (emits a plan file)
+
+With the "adopt it" recommendation above, the operator graduates the spike into a plan file:
+
+```
+$ node scripts/refine/exit-spike.mjs --spike-file spike-cache.md --disposition graduate --plan-file docs/phases/phase-43.md --json
+{ "ok": true, "action": "graduate", "spikeFile": "/abs/spike-cache.md", "planFile": "/abs/docs/phases/phase-43.md" }
+```
+
+`docs/phases/phase-43.md` is written with the spike's sections mapped onto the plan-file base sections:
+
+```markdown
+# Graduated spike plan
+
+## Status
+
+Draft (graduated from a spike). Needs refinement before promotion.
+
+## Objective
+
+Act on the spike's recommendation. The spike asked: Would an in-process LRU
+cache on the metadata fetch measurably cut p95 latency?
+
+Approach explored:
+
+Add a throwaway `@lru_cache` wrapper behind a flag, replay a captured request
+trace, and compare p95 with and without the cache.
+
+## In scope
+
+Adopt the cache behind a default-on flag; the latency win is large and the
+memory cost is small. Ship it as a follow-up plan.
+
+Supporting findings from the spike:
+
+The trace replay shows p95 dropping from 240ms to 90ms with the cache, with a
+~3MB steady-state memory cost and no correctness regressions on the replay set.
+
+## Explicit non-goals
+
+- Re-running the spike's exploration; that question is concluded.
+- Work beyond the recommendation above.
+```
+
+This plan file passes `validatePlanFile`, so it enters the local-planning flow as a new plan needing refinement: refine it, hold the local human-review checkpoint, then `promote-plan.mjs` opens the draft PR (see the [Local-Planning Worked Example](local-planning-worked-example.md)). Re-running the graduate exit reproduces the same plan body, because `buildGraduatedPlanBody` is pure.
+
+## Relationship to other docs
+
+| Doc | Relationship |
+|---|---|
+| [Artifact Authority Contract](artifact-authority-contract.md) | Canonical artifact model; a graduated spike feeds the local-planning tier |
+| [Local-Planning Flow](local-planning-flow.md) | The operator sequence a graduated plan file then follows |
+| [Local-Planning Worked Example](local-planning-worked-example.md) | One plan file through promotion, where a graduated spike lands |
+| [Plan-file Contract](plan-file-contract.md) | Plan-file format and base sections the graduated body satisfies |
+| [Public Dev Loop Contract](public-dev-loop-contract.md) | Canonical routing contract; `--spike` is one startup input |
+
+## Non-goals
+
+- Changing spike intake, exit, or gate behavior (this is a docs-only surface).
+- Defining a tracker-backed spike — a spike is local by construction.
+- A discard that records a tracker artifact — discard is zero-mutation by contract.

package/skills/docs/ui-e2e-scoping-step.md

@@ -0,0 +1,102 @@
+# 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.
+
+## 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/local-implementation/SKILL.md

@@ -512,7 +512,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: