dev-loops 0.4.0 → 0.5.0

package/scripts/refine/refine-plan-file.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+
+import { buildParseError, formatCliError, parseJsonText } from "../_core-helpers.mjs";
+import { requireTokenValue } from "../_cli-primitives.mjs";
+import { validatePlanFile } from "./validate-plan-file.mjs";
+import { extractSection, isDirectCliRun } from "./_refine-helpers.mjs";
+import {
+  refinePlanFileInPlace,
+  PLAN_FILE_REFINE_STOP,
+} from "@dev-loops/core/loop/plan-file-refine-contract";
+import { PLAN_FILE_REFINEMENT_SECTIONS } from "@dev-loops/core/loop/plan-file-intake-contract";
+import { classifyDocsGrillFinding } from "../loop/docs-grill-contract.mjs";
+
+const USAGE = `Usage:
+  refine-plan-file.mjs --plan-file <path> --payload <path> [--json]
+Refine a local plan file in place: write the refiner-produced Acceptance
+criteria, Definition of done, coverage matrix, and recorded docs-grill
+findings into the plan file, advance the intake state to
+plan_refined_ready_for_promotion, and stop at a local human-review
+checkpoint. Read-only against the tracker: no GitHub calls, no issue/PR/
+comment, no promotion.
+
+Required:
+  --plan-file <path>  Path to the phase-doc-format plan file to refine in place
+  --payload <path>    Path to a JSON file with the refiner output
+                      ({ acceptanceCriteria, definitionOfDone, coverageMatrix,
+                        grillFindings? })
+Optional:
+  --json              Machine-readable JSON output
+  --help              Show this help
+Exit codes:
+  0  Refinement succeeded; plan written in place; stop for local human review
+  1  Argument error, or fail-closed refine/grill/ambiguous state (no write)`.trim();
+
+const parseError = buildParseError(USAGE);
+
+export function parseRefinePlanFileCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      "plan-file": { type: "string" },
+      payload: { type: "string" },
+      json: { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = { help: false, planFile: undefined, payload: undefined, json: false };
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") continue;
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "plan-file") {
+      options.planFile = requireTokenValue(token, parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    if (token.name === "payload") {
+      options.payload = requireTokenValue(token, parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    if (token.name === "json") {
+      options.json = true;
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (typeof options.planFile !== "string" || options.planFile.trim().length === 0) {
+    throw parseError("refine-plan-file requires --plan-file <path>");
+  }
+  if (typeof options.payload !== "string" || options.payload.trim().length === 0) {
+    throw parseError("refine-plan-file requires --payload <path>");
+  }
+  return options;
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseRefinePlanFileCliArgs(argv);
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return { ok: true, help: true };
+  }
+
+  const planPath = path.resolve(options.planFile);
+  const markdownText = await readFile(planPath, "utf8");
+  const payload = parseJsonText(await readFile(path.resolve(options.payload), "utf8"));
+
+  // Read the section-presence facts with the P1 surfaces, then hand them to the
+  // pure refine contract. The contract owns the state-machine gate and the
+  // in-place rewrite; this script owns I/O only.
+  // The docs-grill runs as a step of refinement. Classify each finding here (this
+  // script owns the scripts/ boundary) with #948's classifier and pass the
+  // dispositions to the pure core contract; an invalid finding yields a null
+  // disposition, which the contract fails closed on (docs_grill_failed).
+  const rawFindings = Array.isArray(payload?.grillFindings) ? payload.grillFindings : [];
+  const grillDispositions = rawFindings.map((finding) => {
+    const classified = classifyDocsGrillFinding(finding);
+    return {
+      kind: finding?.kind,
+      summary: typeof finding?.summary === "string" ? finding.summary : "",
+      disposition: classified.ok ? classified.disposition : null,
+    };
+  });
+
+  const [acHeading, dodHeading] = PLAN_FILE_REFINEMENT_SECTIONS;
+  const result = refinePlanFileInPlace({
+    markdownText,
+    baseSectionsValid: validatePlanFile(markdownText).ok,
+    hasAcceptanceCriteria: extractSection(markdownText, acHeading) ? true : false,
+    hasDefinitionOfDone: extractSection(markdownText, dodHeading) ? true : false,
+    payload: { ...payload, grillDispositions },
+  });
+
+  if (!result.ok) {
+    // Fail closed: surface the reason, do not write, do not advance, do not promote.
+    if (options.json) {
+      stdout.write(`${JSON.stringify({ ok: false, reason: result.reason, planFileIntakeState: result.planFileIntakeState ?? null })}\n`);
+    } else {
+      stdout.write(`refine-plan-file: FAIL (${result.reason})\n`);
+    }
+    process.exitCode = 1;
+    return result;
+  }
+
+  // Write the refined plan back in place — the single canonical artifact.
+  await writeFile(planPath, result.refinedMarkdown, "utf8");
+
+  const summary = {
+    ok: true,
+    planFile: planPath,
+    planFileIntakeState: result.planFileIntakeState,
+    stop: result.stop,
+    grillDispositions: result.grillDispositions,
+  };
+  if (options.json) {
+    stdout.write(`${JSON.stringify(summary)}\n`);
+  } else {
+    stdout.write(
+      [
+        "refine-plan-file: PASS",
+        `  plan: ${planPath}`,
+        `  state: ${result.planFileIntakeState}`,
+        `  stop: ${result.stop.kind} (${PLAN_FILE_REFINE_STOP.LOCAL_HUMAN_REVIEW === result.stop.kind ? "stop for local human review; no tracker artifact created" : result.stop.kind})`,
+        `  grill findings recorded: ${result.grillDispositions.length}`,
+      ].join("\n") + "\n",
+    );
+  }
+  return summary;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/refine/validate-plan-file.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+import { formatCliError } from "../_core-helpers.mjs";
+import {
+  DEFAULT_USAGE_SUFFIX,
+  checkBaseSections,
+  parseCheckerCliArgs,
+  writeCheckerOutput,
+  isDirectCliRun,
+} from "./_refine-helpers.mjs";
+
+const USAGE = `Usage:
+  validate-plan-file.mjs --input <path> [--json]
+Validate the base authoring sections of a phase-doc-format plan file: Status, Objective, In scope, Explicit non-goals.${"\n"}${DEFAULT_USAGE_SUFFIX}`;
+
+/**
+ * Base authoring sections a phase doc carries before refinement adds AC/DoD.
+ * Heading → distinct missing_* error code. Single source of truth: the section
+ * list is derived from these keys so the validator and the exported list cannot
+ * drift.
+ */
+const SECTION_CODES = {
+  Status: "missing_status",
+  Objective: "missing_objective",
+  "In scope": "missing_in_scope",
+  "Explicit non-goals": "missing_explicit_non_goals",
+};
+
+/** Base authoring section headings, in order (derived from SECTION_CODES). */
+export const PLAN_FILE_BASE_SECTIONS = Object.keys(SECTION_CODES);
+
+/**
+ * Pure validator. Reports whether a plan file (phase-doc format) carries every
+ * base authoring section with a non-empty body. An absent or empty-body section
+ * is reported under that section's distinct missing_* code. No side effects.
+ *
+ * @param {string} markdownText
+ * @returns {{ checker: "validate-plan-file", ok: boolean, errors: { code: string, message: string }[] }}
+ */
+export function validatePlanFile(markdownText) {
+  // checkBaseSections reports each absent/empty section under its distinct
+  // missing_* code; an empty-body section is malformed here too.
+  return checkBaseSections(markdownText, "validate-plan-file", SECTION_CODES);
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseCheckerCliArgs(argv, USAGE, "validate-plan-file");
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return { ok: true, help: true };
+  }
+  const markdownText = await readFile(options.input, "utf8");
+  const result = validatePlanFile(markdownText);
+  writeCheckerOutput(result, { stdout, json: options.json });
+  return result;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/refine/validate-spike-file.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+import { formatCliError } from "../_core-helpers.mjs";
+import {
+  DEFAULT_USAGE_SUFFIX,
+  checkBaseSections,
+  parseCheckerCliArgs,
+  writeCheckerOutput,
+  isDirectCliRun,
+} from "./_refine-helpers.mjs";
+
+const USAGE = `Usage:
+  validate-spike-file.mjs --input <path> [--json]
+Validate the base authoring sections of a spike artifact: Question, Approach, Findings, Recommendation.${"\n"}${DEFAULT_USAGE_SUFFIX}`;
+
+/**
+ * Base authoring sections a spike artifact carries.
+ * Heading → distinct missing_* error code.
+ */
+const SECTION_CODES = {
+  Question: "missing_question",
+  Approach: "missing_approach",
+  Findings: "missing_findings",
+  Recommendation: "missing_recommendation",
+};
+
+export const SPIKE_FILE_BASE_SECTIONS = Object.keys(SECTION_CODES);
+
+/**
+ * Recommendation is the exit-marker section: present + non-empty means the
+ * spike has reached a recommendation and is ready for a discard/graduate exit
+ * decision. The exploration scaffold (Question/Approach/Findings) is what an
+ * in-progress spike must carry for `--spike` entry. (Mirrors the plan-file
+ * base-vs-refinement-section split.)
+ */
+export const SPIKE_FILE_EXIT_MARKER_SECTION = "Recommendation";
+export const SPIKE_FILE_EXPLORATION_SECTIONS = SPIKE_FILE_BASE_SECTIONS.filter(
+  (h) => h !== SPIKE_FILE_EXIT_MARKER_SECTION,
+);
+
+const EXPLORATION_SECTION_CODES = Object.fromEntries(
+  SPIKE_FILE_EXPLORATION_SECTIONS.map((h) => [h, SECTION_CODES[h]]),
+);
+
+/**
+ * Pure validator. Reports whether a spike artifact carries every base authoring
+ * section with a non-empty body. An absent or empty-body section is reported
+ * under that section's distinct missing_* code. No side effects.
+ *
+ * @param {string} markdownText
+ * @returns {{ checker: "validate-spike-file", ok: boolean, errors: { code: string, message: string }[] }}
+ */
+export function validateSpikeFile(markdownText) {
+  return checkBaseSections(markdownText, "validate-spike-file", SECTION_CODES);
+}
+
+/**
+ * Entry-gate validator for `--spike`: a spike is startable as soon as it carries
+ * the exploration scaffold (Question/Approach/Findings) with non-empty bodies;
+ * the Recommendation is filled in DURING the spike, not required to begin one.
+ *
+ * @param {string} markdownText
+ * @returns {{ checker: "validate-spike-file", ok: boolean, errors: { code: string, message: string }[] }}
+ */
+export function validateSpikeExplorationSections(markdownText) {
+  return checkBaseSections(markdownText, "validate-spike-file", EXPLORATION_SECTION_CODES);
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseCheckerCliArgs(argv, USAGE, "validate-spike-file");
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return { ok: true, help: true };
+  }
+  const markdownText = await readFile(options.input, "utf8");
+  const result = validateSpikeFile(markdownText);
+  writeCheckerOutput(result, { stdout, json: options.json });
+  return result;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/skills/dev-loop/SKILL.md

@@ -118,6 +118,16 @@ Info/handoff requests can be served directly via `node <dev-loops-package-root>/
 - `node <dev-loops-package-root>/cli/index.mjs loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
 - `node <dev-loops-package-root>/cli/index.mjs 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
 
 **Handoff envelope precedence:** The dev-loop builds the envelope immediately after authoritative-state resolution and treats it as the first handoff artifact. Read it first, load only `requiredReads`, execute `nextAction`. See [Resolve authoritative state](#resolve-authoritative-state). Derivation contract: [Workflow Handoff Contract](../docs/workflow-handoff-contract.md).
@@ -128,7 +138,7 @@ Info/handoff requests can be served directly via `node <dev-loops-package-root>/
 
 **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/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/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