dev-loops 0.4.0 → 0.5.0

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

@@ -0,0 +1,63 @@
+# Local-planning flow
+
+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/`.
+
+## Stages
+
+| Stage | Helper script | Pure logic |
+|---|---|---|
+| Validate | `scripts/refine/validate-plan-file.mjs` | `validatePlanFile` (in the helper script; not a `@dev-loops/core` export) |
+| Start | `scripts/loop/resolve-dev-loop-startup.mjs --plan-file <path>` | `evaluatePlanFileIntakeState` (`@dev-loops/core/loop/plan-file-intake-contract`) |
+| Refine | `scripts/refine/refine-plan-file.mjs` | `refinePlanFileInPlace` (`@dev-loops/core/loop/plan-file-refine-contract`) |
+| Promote | `scripts/refine/promote-plan.mjs` | `evaluatePromoteEligibility` / `buildPromotionPrBody` (`@dev-loops/core/loop/plan-file-promote-contract`) |
+
+## 1. Author and validate the plan
+
+Author a phase-doc-format plan under `docs/phases/` with the four base sections `## Status`, `## Objective`, `## In scope`, `## Explicit non-goals`. Check it against the base-section contract:
+
+```
+node scripts/refine/validate-plan-file.mjs --input docs/phases/phase-<n>.md --json
+```
+
+The JSON payload reports `{ checker: "validate-plan-file", ok, errors }`. Each absent or empty-body base section contributes one entry with a distinct `missing_*` code; `ok` is `true` when every base section is present with a non-empty body.
+
+## 2. Start the local-planning session
+
+Hand the plan to startup with `--plan-file` (mutually exclusive with `--issue`, `--pr`, and `--input`):
+
+```
+node scripts/loop/resolve-dev-loop-startup.mjs --plan-file docs/phases/phase-<n>.md
+```
+
+Startup validates the plan and threads an intake state onto its output. A plan with valid base sections and no refinement sections is `new_plan_needs_refinement`; the same plan once it also carries `Acceptance criteria` and `Definition of done` is `plan_refined_ready_for_promotion`. A base-valid plan that carries only one of the two refinement sections is reported as `ambiguous_fail_closed` with exit 0 and is not routed forward — the operator completes the missing section first. A plan that is missing/unreadable or fails the base validator makes startup fail closed (exit 1, no readiness bundle).
+
+## 3. Refine in place and stop at the local human-review checkpoint
+
+The refine step writes the refiner output back into the same plan file:
+
+```
+node scripts/refine/refine-plan-file.mjs --plan-file docs/phases/phase-<n>.md --payload <payload.json>
+```
+
+`refinePlanFileInPlace` appends the `Acceptance criteria` and `Definition of done` sections, a `Coverage matrix` section, and a `Docs-grill findings` section, then advances the intake state to `plan_refined_ready_for_promotion` and stops at the `local_human_review` checkpoint. The docs-grill runs as a step within refinement: each finding is classified with `classifyDocsGrillFinding` (see the [Docs-Grill Step](../../docs/docs-grill-step.md)) and the dispositions are recorded into the plan. The step makes no GitHub or network call; the human reviews the refined plan before anything is promoted.
+
+## 4. Promote to a single draft PR
+
+Once the human approves the refined plan, promote it:
+
+```
+node scripts/refine/promote-plan.mjs --plan-file docs/phases/phase-<n>.md
+```
+
+Promotion is PR-first: it commits the plan doc and opens exactly one draft PR via the canonical PR wrapper, and mints no GitHub issue. It records the plan↔PR link bidirectionally — the PR body references the committed plan-doc path, and the plan's front-matter gains a `prNumber:` entry. The committed plan doc is the spec-of-record; the draft PR enters the standard draft → pre-approval → human-merge flow. Promotion is idempotent: re-running on a plan that already carries `prNumber` resolves to `already_promoted` and opens nothing.
+
+## Relationship to other docs
+
+| Doc | Relationship |
+|---|---|
+| [Artifact Authority Contract](artifact-authority-contract.md) | Canonical model and per-phase contract details for the local-first flow |
+| [Plan-file Contract](plan-file-contract.md) | Plan-file format, base sections, validator, and the optional `prNumber` front-matter |
+| [Local-Planning Worked Example](local-planning-worked-example.md) | One plan file shown through every stage of this sequence |
+| [Docs-Grill Step](../../docs/docs-grill-step.md) | The in-loop grill that runs as a step within refinement |

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

@@ -0,0 +1,139 @@
+# Local-planning worked example
+
+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/`).
+
+## Stage 1 — Authored
+
+The operator writes the four base sections. The file at this point:
+
+```markdown
+# phase-42 plan
+
+## Status
+
+draft
+
+## Objective
+
+Add a `--dry-run` flag to the queue dispatcher so an operator can preview the
+dispatch order without mutating the board.
+
+## In scope
+
+- Parse `--dry-run` in the queue dispatcher CLI.
+- Print the resolved dispatch order and exit 0 without any board mutation.
+
+## Explicit non-goals
+
+- Changing the dispatch ordering algorithm.
+- Any change to non-dry-run dispatch behavior.
+```
+
+Validation passes:
+
+```
+$ node scripts/refine/validate-plan-file.mjs --input docs/phases/phase-42.md --json
+{ "checker": "validate-plan-file", "ok": true, "errors": [] }
+```
+
+## Stage 2 — Started (intake state)
+
+Startup reads the plan and reports the intake state. With the four base sections present and no refinement sections yet, the state is `new_plan_needs_refinement`:
+
+```
+$ node scripts/loop/resolve-dev-loop-startup.mjs --plan-file docs/phases/phase-42.md
+# ... startup output carries planFileIntakeState: "new_plan_needs_refinement"
+```
+
+## Stage 3 — Refined in place
+
+`refine-plan-file.mjs` appends the refinement sections, the coverage matrix, and the recorded docs-grill findings to the same file, then stops at the `local_human_review` checkpoint. The file now reads (added sections shown):
+
+```markdown
+# phase-42 plan
+
+## Status
+
+draft
+
+## Objective
+
+Add a `--dry-run` flag to the queue dispatcher so an operator can preview the
+dispatch order without mutating the board.
+
+## In scope
+
+- Parse `--dry-run` in the queue dispatcher CLI.
+- Print the resolved dispatch order and exit 0 without any board mutation.
+
+## Explicit non-goals
+
+- Changing the dispatch ordering algorithm.
+- Any change to non-dry-run dispatch behavior.
+
+## Acceptance criteria
+
+- `--dry-run` prints the resolved dispatch order to stdout.
+- `--dry-run` performs zero board mutation (no Projects V2 writes).
+- Exit code is 0 on a successful dry-run preview.
+
+## Definition of done
+
+- CLI parses `--dry-run`; unit test covers the parse path.
+- A test asserts no board-mutation call fires under `--dry-run`.
+- The queue docs note the flag.
+
+## Coverage matrix
+
+| Item | Type | Status | Evidence | Notes |
+|---|---|---|---|---|
+| `--dry-run` prints dispatch order | AC | Unverified | pending implementation | |
+| `--dry-run` performs zero mutation | AC | Unverified | pending implementation | |
+| Exit code 0 on preview | AC | Unverified | pending implementation | |
+| No-mutation test | DoD | Unverified | pending test | |
+| Dispatch algorithm unchanged | Non-goal | Unverified | scope boundary | |
+
+## Docs-grill findings
+
+- [fix_in_place] (stale_reference) Queue docs example omits the new flag; add it on this branch.
+```
+
+The intake state for this file is now `plan_refined_ready_for_promotion`. The loop stops here for the operator to review the refined plan before promotion.
+
+## Stage 4 — Local human-review checkpoint
+
+The operator reads the refined plan, confirms the acceptance criteria and coverage matrix, and dispositions the docs-grill findings. No GitHub mutation has happened so far; the plan file is the only artifact. When the operator approves, the flow moves to promotion.
+
+## Stage 5 — Promoted to a draft PR
+
+`promote-plan.mjs` commits the plan doc, opens one draft PR, and writes the PR number back into the plan's front-matter. The file gains a leading front-matter block (the body is unchanged):
+
+```markdown
+---
+prNumber: 1234
+---
+# phase-42 plan
+
+## Status
+
+draft
+
+## Objective
+
+Add a `--dry-run` flag to the queue dispatcher so an operator can preview the
+dispatch order without mutating the board.
+
+# ... base, refinement, coverage-matrix, and docs-grill sections unchanged ...
+```
+
+The PR body references `docs/phases/phase-42.md` as the spec-of-record, completing the bidirectional plan↔PR link. No GitHub issue was minted. Re-running `promote-plan.mjs` on this file now resolves to `already_promoted` and opens nothing, because the front-matter already carries `prNumber`.
+
+## Relationship to other docs
+
+| Doc | Relationship |
+|---|---|
+| [Local-Planning Flow](local-planning-flow.md) | The operator sequence this example traces |
+| [Artifact Authority Contract](artifact-authority-contract.md) | Canonical model and per-phase contract details |
+| [Plan-file Contract](plan-file-contract.md) | Plan-file format, base sections, and the `prNumber` front-matter |

package/skills/docs/merge-preconditions.md

@@ -2,8 +2,43 @@
 
 Canonical owner for merge preconditions across all workflow families.
 
+## Conflict-free (mergeable) is a precondition at every gate
+
+A PR that conflicts with its base gets **no `pull_request` CI run** — GitHub can't
+compute the merge ref — so the gate silently stalls (green-less with no obvious
+cause). Conflict-free is therefore a required gate precondition, checked at **two
+seams**: before requesting CI/Copilot, and again before merge.
+
+- `gh pr view --json mergeable,mergeStateStatus` drives it. A `CONFLICTING` /
+  `DIRTY` / `BEHIND` PR does **not** pass any gate (`gateBoundary:
+  conflict_resolution`, `nextAction: resolve_merge_conflicts`).
+- `mergeable` is computed asynchronously, so a freshly-pushed head briefly reads
+  `UNKNOWN`. The detect layer **re-polls a bounded number of times**; if it never
+  settles, the gate **fails closed to a recheck** (`nextAction: wait_for_ci`) —
+  an unsettled merge state is never treated as clean.
+- `loop info` surfaces a **Mergeable:** line (mergeStateStatus included) so a
+  conflict is diagnosed immediately, never mistaken for missing CI.
+
+### Deterministic auto-resolve (additive CHANGELOG only)
+
+When a PR is behind/`CONFLICTING`, run the conservative resolver before resuming
+the gate path:
+
+```sh
+node scripts/loop/resolve-pr-conflicts.mjs [--base <branch>] [--push]
+```
+
+It merges `origin/<base>` into the PR branch and resolves **only the safe additive
+case** — a `CHANGELOG.md` conflict where both sides only ADD list/section entries
+(keep BOTH sides, in order) — then runs `npm run test:docs` and (with `--push`)
+pushes. **Any other conflicted path, or a non-additive CHANGELOG edit, FAILS
+CLOSED** naming the conflicted paths (no silent stall, no guessing — resolve those
+by hand). This encodes the exact additive-CHANGELOG resolution the loop has been
+doing manually; it is not a general conflict-resolution engine.
+
 ## Required before merge
 
+1. ✅ Conflict-free with base (`mergeable: MERGEABLE`; not `CONFLICTING`/`DIRTY`/`BEHIND`/`UNKNOWN`)
 1. ✅ CI green on current head (or crediblyGreen via `--local-validation-head-sha`)
 2. ✅ Draft gate satisfied (clean verdict)
 3. ✅ Pre-approval gate satisfied (clean verdict, current head)

package/skills/docs/plan-file-contract.md

@@ -0,0 +1,37 @@
+# Plan-file contract
+
+A plan file is the persisted markdown artifact that drives work in local-planning mode. It reuses the existing phase-doc format under `docs/phases/` (for example, `docs/phases/phase-<n>.md`). The artifact authority model that selects local-planning mode lives in the [Artifact Authority Contract](artifact-authority-contract.md); this document defines the file format and its required base sections.
+
+## 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/`.
+
+## Base authoring sections
+
+A plan file carries these base sections when it is authored, before refinement adds acceptance criteria and a definition of done:
+
+| Heading | Purpose |
+|---|---|
+| `## Status` | The current lifecycle state of the plan (for example, in progress, deferred). |
+| `## Objective` | What the plan sets out to achieve. |
+| `## In scope` | The bounded work this plan covers. |
+| `## Explicit non-goals` | What this plan leaves out. |
+
+Each base section has a non-empty body. Refinement is a later phase that adds acceptance criteria and a definition of done; those are outside the base authoring contract this document defines.
+
+## Validator
+
+`scripts/refine/validate-plan-file.mjs` checks a plan file against the base sections above. It exports a pure function `validatePlanFile(markdownText)` that returns `{ checker: "validate-plan-file", ok, errors }`, where each absent or empty-body base section contributes one entry with a distinct `missing_*` code. `ok` is `true` when every base section is present with a non-empty body.
+
+The thin CLI accepts `--input <path>`, `--json`, and `--help`. The validation verdict is reported in the JSON payload; the process exits non-zero for argument or path errors (house style — see the [Validation Policy](validation-policy.md)).
+
+## Optional front-matter (plan↔PR link)
+
+A plan file may carry an optional leading YAML front-matter block — a `---` line, `key: value` lines, a closing `---` line — before its first heading. It is additive: a plan without front-matter is unchanged and fully valid. The only key the tooling reads or writes today is `prNumber:`, the number of the draft PR a plan was promoted into (PR-FIRST promotion never mints an issue; the committed plan doc is the spec-of-record and the PR body links it). The link is recorded bidirectionally — the PR body references the committed plan-doc path; the plan's `prNumber` front-matter references the PR. Promotion (`scripts/refine/promote-plan.mjs`) writes `prNumber` and is idempotent on a plan that already carries one. The parser/serializer lives in the pure `@dev-loops/core/loop/plan-file-promote-contract` module.
+
+## Relationship to other docs
+
+| Doc | Relationship |
+|---|---|
+| [Artifact Authority Contract](artifact-authority-contract.md) | Owns the artifact-selection model; selects local-planning mode and points here for the plan-file format. |
+| [Validation Policy](validation-policy.md) | Owns the shared CLI verdict-versus-exit-code convention this validator follows. |

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.