dev-loops 0.4.0 → 0.6.0

package/.claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-loops",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Agent-harness-agnostic dev-loop: agents, skills, and hooks for GitHub/Copilot-driven development loops.",
   "author": {
     "name": "Manuel Fittko",

package/.claude/agents/dev-loop.md

@@ -22,7 +22,7 @@ The envelope is the primary handoff artifact — it is derived from resolver out
 
 **Construction sequence:**
 
-1. Run the deterministic startup resolver to produce the authoritative state bundle: `npx dev-loops@0.4.0 loop startup --issue <n>` for issues, or `npx dev-loops@0.4.0 loop startup --pr <n>` for PRs.
+1. Run the deterministic startup resolver to produce the authoritative state bundle: `npx dev-loops@0.6.0 loop startup --issue <n>` for issues, or `npx dev-loops@0.6.0 loop startup --pr <n>` for PRs.
 2. Pass the resolver output, resolved settings (merged from `.devloops` and `.pi/dev-loop/defaults.yaml`), and current gate state to `buildDevLoopHandoffEnvelope()`.
 3. **Validate the envelope** with `validateHandoffEnvelope()` before consuming any field. If validation returns `ok: false`, reject the handoff with the structured error — do not load requiredReads, do not execute nextAction, do not delegate.
 4. Read the envelope as the first artifact.

package/.claude/agents/refiner.md

@@ -44,6 +44,7 @@ For the active phase, require and produce:
 - Do not invent audit findings when no audit artifact was provided
 - when the phase includes watcher or predicate-driven behavior: explicit timeout semantics and negative-case expectations for non-target identities/events
 - when the phase relies on package-first shared helpers inside a source-loaded workspace: explicit integration expectations about whether local callers use published package imports or a thin source/workspace adapter during development
+- cross-check the phase's claims against the contracts and docs they reference (the autonomous docs-grill step, see ../docs/docs-grill-step.md): surface code-vs-doc drift, stale references, and contract-surface inaccuracies as refinement findings while the claims are still being verified
 
 ## Working style
 - Prefer parallel fresh-context fan-out/fan-in when it improves refinement quality or surfaces materially different variants.

package/.claude/commands/auto.md

@@ -0,0 +1,7 @@
+---
+description: "Run an autonomous dev loop on a GitHub issue until the human approval checkpoint."
+argument-hint: "<issue>"
+---
+<!-- GENERATED from commands/auto.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Run the `dev-loop` skill with the public intent `auto dev loop on issue $ARGUMENTS`. Resolve authoritative state first, then continue autonomously through the routed loop until a stop condition or the human approval checkpoint. Do not pick an internal strategy name yourself.

package/.claude/commands/continue.md

@@ -0,0 +1,15 @@
+---
+description: "Continue the dev loop — the current in-progress board item, or a given issue/PR."
+argument-hint: "[issue|pr]"
+---
+<!-- GENERATED from commands/continue.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Continue a dev loop. Two forms, both handed to the `dev-loop` skill — do NOT pick an internal strategy yourself.
+
+- With an argument (`$ARGUMENTS` is an issue or PR — `123`, `#123`, or a GitHub URL): run the `dev-loop` skill with the public intent `continue dev loop on $ARGUMENTS`. Resolve that artifact's authoritative state first, then route; ignore board position.
+
+- Bare (no `$ARGUMENTS`): pick up the single in-progress board item. Resolve the board's repo and project the same way the queue commands do, then run `node scripts/projects/resolve-active-board-item.mjs --repo <owner/name> --project <number>`.
+  - It returns `{ ok: true, target: { kind, number } }` for exactly one in-progress item → run the `dev-loop` skill with the public intent `continue dev loop on #<number>` (the resolved `target.number`), so the intent carries the concrete target instead of re-resolving board state.
+  - It returns `{ ok: false, reason }` when there are zero or more than one in-progress items → FAIL CLOSED: print the reason verbatim (it lists the items) and instruct the user to run `/continue #N` explicitly. Do NOT guess.
+
+Resolve authoritative state before routing. All paths terminate in the dev-loop skill's `loop startup` → build-envelope → route, stopping at the human-approval checkpoint as usual. No new routing logic here.

package/.claude/commands/info.md

@@ -0,0 +1,7 @@
+---
+description: "Show the read-only dev-loop state summary for an issue or PR."
+argument-hint: "<issue|pr>"
+---
+<!-- GENERATED from commands/info.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Resolve the read-only dev-loop state for `$ARGUMENTS` via the `loop info` shortcut — no full dev-loop run. If `$ARGUMENTS` is an issue number, run `npx dev-loops@0.6.0 loop info --issue $ARGUMENTS`; if it is a PR number, run `npx dev-loops@0.6.0 loop info --pr $ARGUMENTS`. Report the strategy, route, linked PR / branch, CI, and next action. Do not start implementation.

package/.claude/commands/start-spike.md

@@ -0,0 +1,16 @@
+---
+description: "Start a time-boxed dev-loop spike from a question (or a pre-authored findings file)."
+argument-hint: "<question> | --file <path>"
+---
+<!-- GENERATED from commands/start-spike.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Start a spike — a time-boxed exploration whose deliverable is a findings document. Two forms; both end in `loop startup --spike <path>` and hand the bundle to the `dev-loop` skill. Do NOT pick an internal strategy yourself, and do NOT invent new spike behavior — this wraps the shipped `--spike` intake (see `skills/docs/spike-mode-contract.md`).
+
+- Inline question (`$ARGUMENTS` is free text, not `--file ...`): scaffold a startable findings artifact, then enter spike mode.
+  - Pick a local spike path (e.g. `docs/spikes/<slug>.md` derived from the question; do not overwrite an existing file).
+  - Run `node scripts/refine/scaffold-spike-file.mjs --question "$ARGUMENTS" --out <path> --json`. It writes `## Question` (from the arg) plus stubbed `## Approach`/`## Findings` so the exploration scaffold passes `validateSpikeExplorationSections`; `## Recommendation` is left for the spike to fill in. It returns `{ ok: true, path, question }`.
+  - Then run `node scripts/loop/resolve-dev-loop-startup.mjs --spike <path>` and route the resulting bundle through the `dev-loop` skill.
+
+- Pre-authored file (`$ARGUMENTS` begins with `--file <path>`): skip scaffolding and run `node scripts/loop/resolve-dev-loop-startup.mjs --spike <path>` directly, then route. The file must already carry the exploration scaffold (Question/Approach/Findings).
+
+The spike runs under the relaxed `gates.spike` profile. When the exploration reaches a `## Recommendation`, conclude it with `node scripts/refine/exit-spike.mjs --spike-file <path> --disposition <discard|graduate> [--plan-file <path>]` per the spike-mode contract — discard leaves nothing behind, graduate emits a plan file into the local-planning flow. No new routing logic here.

package/.claude/commands/start.md

@@ -0,0 +1,7 @@
+---
+description: "Start a dev loop on a GitHub issue."
+argument-hint: "<issue>"
+---
+<!-- GENERATED from commands/start.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Run the `dev-loop` skill with the public intent `start dev loop on issue $ARGUMENTS`. Resolve authoritative state first, then route through the deterministic internal strategy. Do not pick an internal strategy name yourself.

package/.claude/commands/status.md

@@ -0,0 +1,6 @@
+---
+description: "Report dev-loop readiness (gh auth, git repo, subagent availability)."
+---
+<!-- GENERATED from commands/status.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Report dev-loop readiness for this environment. Check, in one pass: `gh` is installed (`command -v gh`), `gh` is authenticated (`gh auth status`), the working directory is inside a git repo (`git rev-parse --is-inside-work-tree`), and the `subagent`/`Agent` capability is available. Summarize which checks passed and the suggested next step. Read-only — do not start implementation.

package/.claude/hooks/_run-context.mjs

@@ -5,8 +5,14 @@
  * The dev-loop async path keys off the harness-neutral `DEVLOOPS_RUN_ID` env var to
  * identify an inspectable per-subagent run (runner ownership, async-start enforcement,
  * human-comment gating), and provides a mint-and-propagate path for harnesses (e.g. Claude
- * Code) that inject no native per-subagent run id. The harness sets `DEVLOOPS_RUN_ID` when
- * dispatching an async subagent.
+ * Code) that inject no native per-subagent run id. For those harnesses dev-loops itself mints
+ * and sets `DEVLOOPS_RUN_ID` when dispatching an async subagent.
+ *
+ * Other harnesses may already inject their own run-id var: the Pi runtime injects
+ * `PI_SUBAGENT_RUN_ID` (not `DEVLOOPS_RUN_ID`) into each async subagent's child env, so that
+ * name is honored as a recognized run-id alias (precedence after the neutral primary). It is
+ * an externally-injected Pi-runtime contract var, not a dev-loops-owned var — dev-loops still
+ * mints/propagates only the neutral `DEVLOOPS_RUN_ID`.
  *
  * This module is pure except for the explicit file/IO helpers (writeRunContext/readRunContext),
  * which take an injectable `fs` and `root` for testability.
@@ -18,9 +24,10 @@ import path from "node:path";
 
 /**
  * Env var names that carry the async-context run id, in resolution precedence order.
- * The neutral `DEVLOOPS_RUN_ID` is the sole marker.
+ * The neutral `DEVLOOPS_RUN_ID` is primary; `PI_SUBAGENT_RUN_ID` is the alias the Pi
+ * runtime injects into async-subagent child envs (the only run-id marker present under Pi).
  */
-export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID"]);
+export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID", "PI_SUBAGENT_RUN_ID"]);
 
 /** Neutral env var name used when minting/propagating a run id. */
 export const NEUTRAL_RUN_ID_VAR = "DEVLOOPS_RUN_ID";

package/.claude/skills/dev-loop/SKILL.md

@@ -25,7 +25,7 @@ Required installed runtime contract docs are shared bundled copies under `../doc
 
 > Under the Claude Code harness the dev-loop runs as a single agent: run these steps directly — no read-only boundary and no separate async-subagent dispatch. See [Main Agent Contract](../docs/main-agent-contract.md).
 
-Resolve authoritative state via the startup resolver (`npx dev-loops@0.4.0 loop startup --issue <n>` for issues, `npx dev-loops@0.4.0 loop startup --pr <n>` for PRs), then immediately build the handoff envelope via `npx dev-loops@0.4.0 loop build-envelope --input <resolver-output.json>`. The envelope determines `requiredReads`, `nextAction`, `stopRules`, and `acceptance` — load only those files, execute only that bounded task. It is the first handoff artifact consumed before loading any route pack. See [Workflow Handoff Contract](../docs/workflow-handoff-contract.md) for the derivation contract.
+Resolve authoritative state via the startup resolver (`npx dev-loops@0.6.0 loop startup --issue <n>` for issues, `npx dev-loops@0.6.0 loop startup --pr <n>` for PRs), then immediately build the handoff envelope via `npx dev-loops@0.6.0 loop build-envelope --input <resolver-output.json>`. The envelope determines `requiredReads`, `nextAction`, `stopRules`, and `acceptance` — load only those files, execute only that bounded task. It is the first handoff artifact consumed before loading any route pack. See [Workflow Handoff Contract](../docs/workflow-handoff-contract.md) for the derivation contract.
 
 **Retrospective checkpoint gate:** the resolver reads `.pi/dev-loop-retrospective-checkpoint.json` and injects the state. When the checkpoint is `missing` and the repo config `workflow.requireRetrospective` (set via `.devloops` at repo root) is `true`, the resolver returns `needs_reconcile`. Complete or explicitly skip the retrospective before starting.
 
@@ -99,10 +99,25 @@ When `@dev-loops/core` is available again, switch back to the full helper. The f
 
 ## Read-only info shortcut
 
-Info/handoff requests can be served directly via `npx dev-loops@0.4.0 loop info` (read-only; no full dev-loop run required):
-- `npx dev-loops@0.4.0 loop info --issue <n>` — human-readable issue state summary (strategy, route, linked PR, next action)
-- `npx dev-loops@0.4.0 loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
-- `npx dev-loops@0.4.0 loop info --issue <n> --json` — machine-readable JSON output
+Info/handoff requests can be served directly via `npx dev-loops@0.6.0 loop info` (read-only; no full dev-loop run required):
+- `npx dev-loops@0.6.0 loop info --issue <n>` — human-readable issue state summary (strategy, route, linked PR, next action)
+- `npx dev-loops@0.6.0 loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
+- `npx dev-loops@0.6.0 loop info --issue <n> --json` — machine-readable JSON output
+
+## Reading tool output (token-economical convention)
+
+When you need a fact from a dev-loops JSON-emitting script, climb this ladder and stop at the first rung that answers the question — never read more output than you need:
+
+1. **Prefer the dev-loops subcommand / concise mode.** Use `loop info` or a script's `--concise`/`--summary` mode (e.g. `run-watch-cycle.mjs --concise`, `probe-copilot-review.mjs --concise`) for a human-readable digest. The concise modes surface loop state, Copilot round count, unresolved/actionable thread counts, round-cap-clean eligibility, CI status, next action, and the current round's new Copilot comment bodies.
+2. **`--silent` / `-s` for a yes/no check.** Reads ZERO output: `… --jq '<predicate>' --silent; echo $?` exits `0` for true / `1` for false. Without `--jq`, `--silent` maps the script's success (`ok:true`) to exit `0`, failure to `1`. Example: `probe-copilot-review.mjs --repo o/r --pr N --jq '.status=="idle"' -s`.
+3. **`--jq <filter>` to extract a single field.** The `--jq`-wired scripts (`probe-copilot-review.mjs`, `capture-review-threads.mjs`, `upsert-checkpoint-verdict.mjs`, the `scripts/projects/*` queue scripts) accept a gh-style `--jq` filter (jq subset: field access, `.[]`/`.[N]`, `|`, `select(...)`, `==`/`!=`/`<`/`<=`/`>`/`>=`, `length`, `keys`). It prints only the filtered value. An invalid filter fails closed (stderr + exit `2`), distinct from a clean predicate-false (silent exit `1`).
+4. **Use a dev-loops wrapper for `gh` reads — never an agent-level raw `gh`.** With `workflow.requireRetrospectiveInternalTooling: true`, a raw `gh` call is a recorded retro violation (fail-closed). If no script covers the read you need, treat it as a tooling gap: file/build a thin wrapper (reuse `scripts/lib/jq-output.mjs`, like the three below), don't shell out. The reads that already have wrappers:
+   - CI run-log tail (a failing PR's job log) → `scripts/github/fetch-ci-logs.mjs --repo <o/r> --pr <n> [--failed-only] [--tail <n>]`, **never raw `gh run view --log`/`--log-failed`**. (`probe-ci-status.mjs` names the failed checks; this returns the LOG.)
+   - Issue list/filter → `scripts/github/list-issues.mjs --repo <o/r> [--state <open|closed|all>] [--label <l>] [--limit <n>]`, **never raw `gh issue list`**. (The queue tool lists the project board; this is for arbitrary issue queries.)
+   - Issue comment → `scripts/github/comment-issue.mjs --repo <o/r> --issue <n> (--body <text> | --body-file <path>)`, **never raw `gh issue comment`**. Returns `{ ok, commentUrl }`.
+
+   All three accept the same `--jq`/`--silent` output flags as the other JSON-emitting scripts.
+5. **NEVER `| python3` or `node -e`** to parse tool JSON. If a field you need is missing from a script's output, add it to the script (or its concise mode), not an inline parser.
 
 ## Guard rules
 
@@ -114,7 +129,7 @@ Info/handoff requests can be served directly via `npx dev-loops@0.4.0 loop info`
 
 **Bounded async task contract:** Break work into discrete tasks with clear inputs, explicit outputs, bounded scope. No shell polling — use `run-watch-cycle.mjs` or `gh run watch`.
 
-**Round-cap budget check (enforced):** After every watch cycle, fix pass, or reply-resolve, check whether completed Copilot review rounds have reached the maximum (default: 5). Stop re-requesting Copilot review when the limit is reached — never re-request after the cap.
+**Round-cap budget check (enforced):** After every watch cycle, fix pass, or reply-resolve, check whether completed Copilot review rounds have reached the maximum (default: 5). Stop re-requesting Copilot review when the limit is reached — never re-request after the cap. Read these gate-cadence facts via the token-economical convention above (`run-watch-cycle.mjs --concise`, or `--jq`/`--silent` for a single field/predicate) — never `| python3` or `node -e`.
 
 ## Shorthand issue-based auto trigger contract
 

package/.claude/skills/dev-loop/templates/slides-story-review.md

@@ -0,0 +1,54 @@
+# Slides content & storytelling review prompt template
+
+Use this template when running the bounded slides-story reviewer mode behind `dev-loop`.
+
+You are a public-audience storytelling reviewer judging a deck's **narrative**, not its pixels. The visual designer/vision loop owns layout, spacing, and contrast; you own arc, message, sequencing, and audience fit.
+
+## Inputs
+
+- `acceptanceCriteria`: required list of slice-level acceptance criteria the review is judging
+- `storytellingBrief`: required short focus brief (audience, intended takeaway, what to watch for)
+- `deckBundle.deckSourcePath`: required path to the deck source (e.g. the Slidev `.md`)
+- `deckBundle.slideScreenshots[]`: optional captured slides from the UI smoke harness
+  - `slideId`
+  - `screenshotPath`
+
+## Review lens (public audience)
+
+1. **Arc**: hook → tension → resolution. Does slide 1 make a stranger care?
+2. **One message per slide**: each slide has a single takeaway; titles state the claim, not the topic.
+3. **Sequencing**: order builds understanding; no forward references; jargon introduced before it is used.
+4. **Audience calibration**: a public/non-insider reader can follow it — internal enum names, state-machine identifiers, and pills are translated or earn their keep, not dumped raw.
+5. **Cut / merge / reorder**: explicit recommendations — which slides to drop, combine, or move.
+6. **Close**: a memorable takeaway, not a feature list.
+
+## Review policy
+
+1. Fail closed on any missing, ambiguous, or unreadable required input — do not guess the narrative.
+2. Ground every finding in a specific `slideId` (and a `screenshotPath` when available).
+3. Return only deterministic findings tied to the brief and acceptance criteria; do not invent content.
+
+## Required output format
+
+Allowed enum values:
+- `outcome`: `"story_review_satisfied"` | `"needs_iteration"`
+- `severity`: `"high"` | `"medium"` | `"low"`
+
+Return strict JSON with this shape (example uses concrete values):
+
+```json
+{
+  "outcome": "needs_iteration",
+  "summary": "short overall verdict on whether the deck lands",
+  "findings": [
+    {
+      "severity": "high",
+      "slideId": "hero",
+      "problem": "what is wrong with the narrative on this slide and why it fails the public audience",
+      "correctiveAction": "what to change next (cut/merge/reorder/reword)"
+    }
+  ]
+}
+```
+
+When `outcome` is `"needs_iteration"`, `findings` must be non-empty.

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

@@ -1,6 +1,6 @@
 # Artifact authority contract
 
-This document is the canonical authority for the artifact-selection model: when work originates from a GitHub issue (tracker-first) vs a persisted markdown plan file (local-planning).
+This document is the canonical authority for the artifact-selection model: whether a work item originates from a GitHub issue (tracker-first) or from a persisted markdown plan file (local-planning).
 
 This canonical owner lives in the shipped `skills/docs/` surface because installed skill/runtime consumers reliably own the skills subtree. In installed layouts, read the same contract via [Artifact Authority Contract](../docs/artifact-authority-contract.md) from the installed skill directory.
 
@@ -8,9 +8,11 @@ Other repo docs may summarize or link this contract, but they should not redefin
 
 ## Two-tier model
 
-dev-loops supports two mutually exclusive artifact authority modes. Every work item must originate from exactly one authoritative artifact — a GitHub issue or a persisted markdown plan file. No work may originate from a PR or direct local change unless explicitly requested.
+dev-loops supports two mutually exclusive artifact authority modes. Every work item originates from exactly one authoritative artifact: a GitHub issue or a persisted markdown plan file. Work originates from a PR or a direct local change only when explicitly requested.
 
-### Tracker-first (default)
+The shipped extension default selects local-planning; see [Shipped default posture](#shipped-default-posture) below. The mode names that follow describe the two tiers; "default" in their headings refers to the github-first code-level fallback in `BUILT_IN_DEFAULTS`, which the shipped extension layer overrides to local-first.
+
+### Tracker-first
 
 **GitHub issues are the authoritative artifact store.** Work originates from a GitHub issue. A linked PR is the execution artifact. GitHub is the canonical source of truth for issue identity, acceptance criteria, scope, and lifecycle state.
 
@@ -25,12 +27,12 @@ Key contract:
 - When an open linked PR exists, reuse it rather than opening another
 - Implementation may proceed through either the GitHub-first routed path or the local implementation strategy (see [Public Dev Loop Contract](public-dev-loop-contract.md) `targetPreference`)
 
-### Local-planning (opt-out)
+### Local-planning
 
-**Persisted markdown plan files are the authoritative artifact store.** Work originates from a markdown plan file committed to the repository. No GitHub issue is required. GitHub PRs are still used for review and merge, but the plan file is the canonical spec.
+**Persisted markdown plan files are the authoritative artifact store.** Work originates from a local markdown plan file in the repo working tree, and no GitHub issue is required. The plan file stays uncommitted through authoring, refinement, and local review; promotion is the step that commits it (the helper sequence commits it as part of opening the PR). GitHub PRs carry review and merge while the plan file stays the canonical spec.
 
 Artifacts:
-- **Planning artifact:** Persisted markdown plan file (e.g., `docs/phases/phase-<n>.md`)
+- **Planning artifact:** Persisted markdown plan file (e.g., `docs/phases/phase-<n>.md`); its format and required base sections are defined in the [Plan-file Contract](plan-file-contract.md)
 - **Execution artifact:** Local branch and associated GitHub PR (created during implementation)
 - **No GitHub issue:** The plan file replaces the issue as the canonical spec
 
@@ -41,10 +43,10 @@ Key contract:
 
 ### Mode selection table
 
-| Mode | Canonical artifact | GitHub issue required | Settings values |
+| Mode | Canonical artifact | GitHub issue required | Settings value |
 |---|---|---|---|
-| Tracker-first (default) | GitHub issue | Yes | `strategy.default: github-first` |
-| Local-planning (opt-out) | Markdown plan file | No | `strategy.default: local-first` |
+| Tracker-first | GitHub issue | Yes | `strategy.default: github-first` |
+| Local-planning (shipped default) | Markdown plan file | No | `strategy.default: local-first` |
 
 `inputSource.default` further disambiguates local-first startup:
 | inputSource | Meaning |
@@ -54,62 +56,115 @@ Key contract:
 
 ## Settings mechanism
 
-Artifact authority mode is controlled by `.devloops` at repo root:
+The repo's default artifact-authority posture is declared by `strategy.default`, set in `.devloops` at repo root and resolved against the layered config defaults:
 
 ```yaml
 # .devloops
 strategy:
-  default: github-first   # tracker-first (GitHub issue required)
-  # default: local-first  # local-planning (markdown plan file)
+  default: local-first    # local-planning (markdown plan file)
+  # default: github-first # tracker-first (GitHub issue required)
 inputSource:
   default: tracker        # spec source for local-first: tracker (issue body) or phase-docs
 ```
 
-The `strategy.default` key serves dual purpose:
-1. It selects the artifact authority mode (tracker-first vs local-planning)
-2. It sets the default routing preference for `targetPreference` in dev-loop startup
+The `strategy.default` key carries two jobs:
+1. It declares the repo's default artifact-authority posture (local-planning under `local-first`, tracker-first under `github-first`).
+2. It sets the routing preference (`targetPreference`) in dev-loop startup — `prefer_local` under `local-first`, `prefer_github_first` under `github-first`.
+
+The authoritative artifact for a given run is selected by the explicit startup input. `scripts/loop/resolve-dev-loop-startup.mjs` takes `--issue` / `--pr` / `--input` / `--plan-file` (mutually exclusive), and `strategy.default` supplies the default routing preference; it does not force the artifact per invocation.
 
 The `inputSource.default` key disambiguates local-first startup:
-- `tracker` (default): local agent implements from the GitHub issue body; the issue is canonical spec
-- `phase-docs`: local agent implements from persisted phase docs; no tracker issue required
+- `tracker` (default): the local agent implements from the GitHub issue body; the issue is the canonical spec
+- `phase-docs`: the local agent implements from persisted phase docs; no tracker issue required
+
+### Shipped default posture
 
-These keys are already defined in `.pi/dev-loop/defaults.yaml` (shipped with dev-loops) and may be overridden in `.devloops` (per-repo).
+The effective default for a consumer comes from the config-merge layering in `packages/core/src/config/config.mjs`. Precedence, low to high:
 
-### Defaults resolution
+1. `BUILT_IN_DEFAULTS` (frozen in `config.mjs`) — `strategy.default: github-first`. This is the code-level fallback when no other layer sets the key.
+2. Extension-packaged defaults (`packages/core/src/config/extension-defaults.yaml`, loaded as the `extensionDefaults` layer) — `strategy.default: local-first`. This is the opinion the package ships and the layer that wins over the built-in fallback.
+3. Repo-local `.pi/dev-loop/defaults.*` (legacy) — applied when present.
+4. Repo `.devloops` at repo root — the per-repo override, highest precedence. When `.devloops` is absent, the legacy `.pi/dev-loop/settings.*` / `overrides.*` apply at this position instead.
 
-1. `.pi/dev-loop/defaults.yaml` — shipped default (`github-first`)
-2. `.devloops` — per-repo override (takes precedence)
+With nothing but the shipped package in place, the extension layer resolves `strategy.default` to `local-first`, so the shipped default posture is local-planning (epic #947, decision #7). A repo opts back into tracker-first by setting `strategy.default: github-first` in its own `.devloops`.
+
+Two legacy repo-local layers also exist under `.pi/dev-loop/` (the package no longer ships a `.pi/dev-loop/defaults.yaml`). They differ in how they load: `.pi/dev-loop/defaults.*` is always applied when present, between the extension defaults and `.devloops`; `.pi/dev-loop/settings.*` (and the older `overrides.*`) load only when no `.devloops` is present — when `.devloops` exists it is authoritative and those files are ignored (with a deprecation warning). The full precedence, low to high, is: `BUILT_IN_DEFAULTS` < extension defaults < `.pi/dev-loop/defaults.*` < repo `.devloops` (or, when `.devloops` is absent, `.pi/dev-loop/settings.*` / `overrides.*`).
 
 ### Explicit non-knobs
 
 These are not valid artifact authority mode selectors:
-- `strategy.default: copilot` — not a valid mode; must be `github-first` or `local-first`
+- `strategy.default: copilot` — not a valid mode; the enum accepts only `github-first` or `local-first` (`packages/core/src/config/config.mjs`)
 - Free-form string values — fail closed
-- Omitting `strategy.default` entirely — defaults to `github-first` from the shipped defaults
+- Omitting `strategy.default` from every layer — resolves to `github-first` from `BUILT_IN_DEFAULTS`; with the shipped extension layer present it resolves to `local-first`
+
+## Local-first plan-file flow end to end
+
+Under local-planning, one plan file moves through four stages. Each stage has a shipped helper script; the start, refine, and promote stages also expose their pure logic as an `@dev-loops/core` contract, while the validate stage's `validatePlanFile` lives in its helper script (`scripts/refine/validate-plan-file.mjs`). The [Local-Planning Flow](local-planning-flow.md) skill doc walks the same sequence as operator steps, and the [Local-Planning Worked Example](local-planning-worked-example.md) shows one plan file evolving through every stage.
+
+### P1 — Plan-file artifact + config (#949)
+
+The plan file is a phase-doc-format markdown document. Its directory is `localPlanning.plansDir`, which defaults to `docs/phases/` (built-in default in `config.mjs`, mirrored in `extension-defaults.yaml`; `resolvePlansDir(config)` resolves it). Its required base authoring sections — `## Status`, `## Objective`, `## In scope`, `## Explicit non-goals` — and the validator `scripts/refine/validate-plan-file.mjs` (`validatePlanFile`, distinct `missing_*` codes per absent or empty section) are defined in the [Plan-file Contract](plan-file-contract.md).
+
+### P2 — Intake (#950)
+
+`scripts/loop/resolve-dev-loop-startup.mjs` accepts `--plan-file <path>` (mutually exclusive with `--issue`, `--pr`, `--input`). It validates the plan and threads an intake state onto its output. The pure contract `@dev-loops/core/loop/plan-file-intake-contract` (`packages/core/src/loop/plan-file-intake-contract.mjs`) defines `evaluatePlanFileIntakeState` and the three `PLAN_FILE_INTAKE_STATE` values:
+
+| State | Meaning |
+|---|---|
+| `new_plan_needs_refinement` | Base sections valid; the refinement sections are not yet present |
+| `plan_refined_ready_for_promotion` | Base sections valid and both `PLAN_FILE_REFINEMENT_SECTIONS` (`Acceptance criteria`, `Definition of done`) present |
+| `ambiguous_fail_closed` | Base sections invalid, or only one refinement section present — the resolver does not route the plan forward |
+
+In the CLI, a base-valid plan carrying only one refinement section is reported as `ambiguous_fail_closed` with exit 0 (the operator completes the missing section before refine/promote); a missing/unreadable plan, or one that fails the base-section validator, makes startup exit 1 with no readiness bundle.
+
+### P3 — Local refine + review checkpoint (#951)
+
+`scripts/refine/refine-plan-file.mjs` drives the refine step; the pure contract `@dev-loops/core/loop/plan-file-refine-contract` (`packages/core/src/loop/plan-file-refine-contract.mjs`) exports `refinePlanFileInPlace`, which writes the refiner payload back into the single canonical plan file in place — the `Acceptance criteria` and `Definition of done` sections, a `Coverage matrix` section (`COVERAGE_MATRIX_HEADING`), and a `Docs-grill findings` section (`DOCS_GRILL_FINDINGS_HEADING`) — then stops at the `local_human_review` checkpoint (`PLAN_FILE_REFINE_STOP.LOCAL_HUMAN_REVIEW`) with the intake state advanced to `plan_refined_ready_for_promotion`. The module performs no GitHub mutation, no network calls, and no filesystem I/O; the caller reads and writes the plan file. The docs-grill runs as a step within refinement: the CLI classifies each finding with `classifyDocsGrillFinding` (`scripts/loop/docs-grill-contract.mjs`) and the contract records the dispositions. See the [Docs-Grill Step](../../docs/docs-grill-step.md).
+
+### P4 — Promotion + authority transfer (#952)
+
+`scripts/refine/promote-plan.mjs` promotes a refined plan; the pure contract `@dev-loops/core/loop/plan-file-promote-contract` (`packages/core/src/loop/plan-file-promote-contract.mjs`) exports `evaluatePromoteEligibility` and `buildPromotionPrBody`. 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. The plan↔PR link is bidirectional — the PR body carries the committed plan-doc path (the spec-of-record) and the plan front-matter carries `prNumber:` (`PLAN_FILE_PR_FRONT_MATTER_KEY`). Promotion is idempotent: a plan that already carries `prNumber` resolves to `already_promoted` (`PLAN_FILE_PROMOTE_ACTION.ALREADY_PROMOTED`) and opens nothing. The optional `prNumber` front-matter and its parser/serializer are described in the [Plan-file Contract](plan-file-contract.md).
+
+### P5 — Local-first noise profile (#953)
+
+The shipped extension layer pairs local-first with a low-noise posture, in `packages/core/src/config/extension-defaults.yaml`:
+
+| Key | Shipped value | Why |
+|---|---|---|
+| `strategy.default` | `local-first` | The shipped default posture (decision #7) |
+| `autonomy.humanMergeOnly` | `true` | Local-first never auto-merges; a human always merges |
+| `queue.maxAutoFiledIssues` | `1` | Local-first is PR-first, so auto-filing issues is near-zero; a low cap keeps tracker noise minimal |
+| `gates.postFindingsComments` | `true` | Gate findings live on the PR (the spec-of-record and human-review surface) as evidence |
+
+These values come from the existing config-merge layering, so no new resolver is involved: `BUILT_IN_DEFAULTS` keeps the github-first posture (`humanMergeOnly: false`, `maxAutoFiledIssues: 10`), and the extension layer sets the local-first values above. A repo `.devloops` can override any of them.
 
 ## dev-loops own mode
 
-dev-loops is **tracker-first (opted in, GitHub backend).**
+dev-loops runs **local-planning**, set in its repo-root `.devloops`.
 
-- **Mode:** Tracker-first
-- **Settings:** `.pi/dev-loop/defaults.yaml` sets `strategy.default: github-first`
-- **Artifact authority:** GitHub issues are the canonical spec for all work in this repository
-- **No local-planning override:** This repo does not opt out to local-planning mode
-- **Why tracker-first:** All work in this repo originates from GitHub issues. The public dev-loop contract, Copilot follow-up state machines, and gate pipeline all assume issues are the primary artifact. Self-improvement work on dev-loops itself follows the same tracker-first contract.
+- **Mode:** Local-planning
+- **Settings:** repo-root `.devloops` sets `strategy.default: local-first` and `inputSource.default: tracker`
+- **Artifact authority:** the canonical spec for a work item is its plan artifact; the repo dogfoods the same local-first posture the package ships as default
+- **Per-run input:** with `inputSource.default: tracker`, a local-first session can still implement from a GitHub issue body when one is supplied (the issue is the spec source for that run); `phase-docs` switches the source to a committed plan file
+- **Why local-planning:** the repo runs the local-first plan-file flow (plan-file → refine → review → promote) on its own work so the shipped default posture is exercised end to end.
 
 ## Relationship to other docs
 
 | Doc | Relationship |
 |---|---|
 | [Public Dev Loop Contract](public-dev-loop-contract.md) | This contract is the canonical entrypoint; artifact authority contract defines the artifact model it assumes |
-| [Tracker-First Loop State](tracker-first-loop-state.md) | That doc defines the PR-level state machine for tracker-first PR workflows — it is about execution state, not artifact authority |
+| [Plan-file Contract](plan-file-contract.md) | Defines the plan-file format (phase-doc format) and its required base sections for local-planning mode |
+| [Local-Planning Flow](local-planning-flow.md) | Operator sequence for the local-first flow: validate → start → refine → promote, naming the shipped helper scripts |
+| [Local-Planning Worked Example](local-planning-worked-example.md) | One plan file shown through every stage, with the file content evolving |
+| [Spike-mode Contract](spike-mode-contract.md) | Time-boxed exploratory runs; a graduated spike emits a plan file that enters this local-planning tier |
+| [Tracker-First Loop State](tracker-first-loop-state.md) | Defines the PR-level state machine for tracker-first PR workflows; that is execution state, separate from artifact authority |
 | [Main Agent Contract](main-agent-contract.md) | Defines the delegation boundary; artifact authority defines which artifacts govern work |
 | AGENTS.md | Repo constitution; cites the work-origin rule and points to this contract |
 | [Dev Loop Skill](../dev-loop/SKILL.md) | Public entrypoint skill; cites the work-origin rule and points to this contract |
 
 ### Distinction: artifact authority vs tracker-first PR workflow
 
-`tracker-first-loop-state.md` defines a state machine for PR lifecycle management when a tracker item (e.g., Shortcut story) drives a GitHub PR. That is a **PR-level workflow contract**, not the artifact authority model. The term "tracker-first" in that doc refers to tracker-driven PR state transitions — it does not redefine the artifact authority contract defined here.
+`tracker-first-loop-state.md` defines a state machine for PR lifecycle management when a tracker item (e.g., Shortcut story) drives a GitHub PR. It is a **PR-level workflow contract**. The term "tracker-first" there refers to tracker-driven PR state transitions, a separate concern from the artifact authority model this doc defines.
 
 ## Non-goals
 

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