dev-loops 0.4.0 → 0.5.0

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

@@ -1,6 +1,6 @@
 {
   "name": "dev-loops",
-  "version": "0.4.0",
+  "version": "0.5.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.5.0 loop startup --issue <n>` for issues, or `npx dev-loops@0.5.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/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.5.0 loop startup --issue <n>` for issues, `npx dev-loops@0.5.0 loop startup --pr <n>` for PRs), then immediately build the handoff envelope via `npx dev-loops@0.5.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,20 @@ 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.5.0 loop info` (read-only; no full dev-loop run required):
+- `npx dev-loops@0.5.0 loop info --issue <n>` — human-readable issue state summary (strategy, route, linked PR, next action)
+- `npx dev-loops@0.5.0 loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
+- `npx dev-loops@0.5.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. **`gh … --jq` on a raw `gh` call** when no dev-loops script covers it.
+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 +124,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 |

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