faberun 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
   "type": "module",
   "bin": {

package/skills/faberun/SKILL.md

@@ -10,6 +10,7 @@ Read [rules](references/rules.md) first.
 
 | Action | Read |
 | --- | --- |
+| Write or validate a spec | [spec-format](references/spec-format.md) |
 | Author a contract (fallback) | [contract](references/contract.md), [engineering](references/engineering.md) |
 | Launch and resume | [workflow](references/workflow.md), [operations](references/operations.md) |
 | Dispatch a node | [handoffs](references/handoffs.md) |

package/skills/faberun/references/spec-format.md

@@ -0,0 +1,87 @@
+# Spec format reference
+
+Format version `1`. A spec is the free-form input the operator hands the
+planner; this is the structured shape it validates against
+(`faberun spec validate`, no model invoked). A document without the front
+matter below is classified `legacy` and accepted, not rejected — the
+validator says so explicitly, so old campaign records keep working.
+
+## Front matter
+
+```yaml
+---
+id: kebab-case-campaign-id
+title: "Human-readable title"
+version: 1.1.0
+status: draft
+date: 2026-09-17
+owner: Author Name
+target: org/repo
+baseline: <git sha the spec was measured against>
+---
+```
+
+`id`, `title`, `version`, `status`, `date`, `owner`, `target`, `baseline` are
+required. `derived_from` and `followed_by` are optional cross-references to
+other spec ids (a prior spec this one revises, or the campaign meant to
+follow it).
+
+## Sections
+
+Mandatory, in order: **Intent**, **Requirements**, **Non-goals**. The
+reference proposal
+(`docs/campaigns/spec-format-and-planning-stages/spec/PROPOSAL.md`) writes
+these as `Intenção`, `Requisitos`, `Não-objetivos` — the section role is what
+matters, not the language of the heading text.
+
+- **Intent** — prose: why this work, what problem, what it unblocks.
+- **Requirements** — one `### R<n>. <title>` block per requirement (see
+  below).
+- **Non-goals** — a bullet list of what this spec explicitly excludes, so a
+  planner never infers scope from silence.
+
+Optional sections, any subset, any order after Non-goals:
+
+- **Constraints** — bullets binding every requirement at once (e.g. "no node
+  runs the full suite").
+- **Success criteria** — a table with at least a `Baseline` column, so
+  validation can catch a metric nobody measured before claiming a delta.
+- **Risks** — a table of risk / impact / mitigation.
+
+## Requirement shape
+
+```markdown
+### R7. Repo facts are deterministic and carry measured duration
+
+- **statement:** the target repo inventory is generated without invoking a
+  model, is identical across two runs at the same HEAD, and every candidate
+  verification command carries a duration measured by
+  `preflight --time-verification`.
+- **proof:** command: node --test --test-name-pattern="repo facts"
+```
+
+`R<n>` is a stable id — never renumbered once referenced elsewhere (a
+comparative arm, a follow-up spec). `statement` is the testable claim.
+`proof` is exactly one of:
+
+- `command: <shell command>` — re-run it, exit zero proves the requirement.
+- `path: <repo-relative path>` — the file or directory must exist.
+- `judgment: true` — no deterministic check; a reviewer decides.
+
+A requirement may add its own `- **constraints:** ...` line for a rule
+scoped to it alone, distinct from the spec-wide Constraints section.
+
+## What `faberun spec validate` checks
+
+Deterministic, no model call. Rejects:
+
+- a requirement without a stable id, or without a `proof` line;
+- a spec with no Non-goals section;
+- a Success criteria table row with no Baseline value;
+- a `target` or `baseline` that does not resolve to a real commit.
+
+These are **advisory** by default — recorded as findings, spec still
+validates — and become **blocking** under `--strict-traceability`, which
+fails validation on any of the above. A `legacy`-class document (no front
+matter) is exempt from every check above; it is accepted and labeled, never
+scored against these rules.

package/src/campaign/index.mjs

@@ -1,4 +1,5 @@
 import {
+  copyFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -9,7 +10,7 @@ import { join, resolve } from "node:path";
 import { writeJsonAtomic } from "../run/store.mjs";
 import { requireId, requirePacketHash, requireString, requireTimestamp } from "../contract/assert.mjs";
 import { promoteRun } from "../repo/integrate.mjs";
-import { CAMPAIGN_FILE, GOAL_TEXT_BYTES, PROJECTION_FILE, campaignDir, campaignsDir } from "./layout.mjs";
+import { CAMPAIGN_FILE, GOAL_TEXT_BYTES, JOURNAL_FILE, PROJECTION_FILE, campaignDir, campaignsDir } from "./layout.mjs";
 import { readCampaign } from "./record.mjs";
 import { appendJournal, normalizeText, readJournalForDedupe } from "./journal.mjs";
 import { readProjectionState } from "./projection.mjs";
@@ -122,7 +123,7 @@ export function resolveCampaign(runsDir, campaignId) {
 /**
  * @param {string} campaignPath
  * @param {{at?: string, eventId?: string}} options
- * @returns {{path: string, campaign: Campaign}}
+ * @returns {{path: string, campaign: Campaign, ledgerFiles: string[]}}
  */
 export function closeCampaign(campaignPath, { at = new Date().toISOString(), eventId = randomUUID() } = {}) {
   requireTimestamp(at, "at");
@@ -131,10 +132,52 @@ export function closeCampaign(campaignPath, { at = new Date().toISOString(), eve
   if (!readJournalForDedupe(campaignPath).some((entry) => entry.type === "retrospective")) {
     throw new Error(`campaign ${campaign.id} has no recorded retrospective; record one with note --kind retrospective before close`);
   }
+  const repoRoot = resolve(campaignPath, "..", "..", "..");
+  const ledgerFiles = preserveCampaignLedger(campaignPath, repoRoot);
   const closed = /** @type {Campaign} */ ({ ...campaign, status: "closed", closedAt: at, updatedAt: at });
   writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), closed);
   appendJournal(campaignPath, { type: "campaign.closed", at, eventId });
-  return { path: campaignPath, campaign: closed };
+  return { path: campaignPath, campaign: closed, ledgerFiles };
+}
+
+/**
+ * Copy a campaign's journal, record and each linked run's usage into
+ * `<repoRoot>/docs/campaigns/<id>/ledger/` so the comparative arm of the
+ * planner has a session-side baseline even after `.runs/` (gitignored) is
+ * pruned. Nothing in this tree redacts token counts, costs or operator notes
+ * before this point, so the copy is verbatim; the pre-commit secret scan is
+ * the guard against anything that should not land in git.
+ *
+ * Idempotent: re-running it (a second `close` on an already-closed campaign
+ * cannot reach this, but a direct call can) overwrites the same destination
+ * files rather than duplicating them. A linked run without a `usage.jsonl`
+ * (never launched, or pruned) is skipped rather than thrown.
+ *
+ * @param {string} campaignPath
+ * @param {string} repoRoot
+ * @returns {string[]}
+ */
+export function preserveCampaignLedger(campaignPath, repoRoot) {
+  const campaign = readCampaign(campaignPath);
+  const runsDir = resolve(campaignPath, "..", "..");
+  const ledgerDir = join(repoRoot, "docs", "campaigns", campaign.id, "ledger");
+  mkdirSync(ledgerDir, { recursive: true });
+  const written = [];
+  for (const name of [JOURNAL_FILE, CAMPAIGN_FILE]) {
+    const source = join(campaignPath, name);
+    if (!existsSync(source)) continue;
+    const destination = join(ledgerDir, name);
+    copyFileSync(source, destination);
+    written.push(destination);
+  }
+  for (const runId of campaign.linkedRunIds) {
+    const source = join(runsDir, runId, "usage.jsonl");
+    if (!existsSync(source)) continue;
+    const destination = join(ledgerDir, `${runId}.usage.jsonl`);
+    copyFileSync(source, destination);
+    written.push(destination);
+  }
+  return written;
 }
 
 /**

package/src/cli/brand.mjs

@@ -195,6 +195,8 @@ export function renderUsage() {
     "next [--cwd <dir>] [--json]",
     "bulk-read --question <text> --paths <a,b,c> [--json]",
     "contract validate <contract.json>",
+    "spec validate <file> [--strict-traceability] [--json]",
+    "spec scaffold <path> [--id <id>]",
     "metrics <campaign-id> [--cwd <dir>] [--json]",
     "campaign <init|watch|attach|note|resolve|close|supervise|show|list|sync|ack> ...",
     "seat <start|attach|status|stop> [<campaign-id>] [--cwd <dir>] ...",

package/src/cli/campaign.mjs

@@ -447,6 +447,7 @@ function close(campaignId, values) {
   const closed = closeCampaign(path, { eventId: values.eventId ?? randomUUID() });
   renderHandoff(path, runsDir);
   process.stdout.write(`[campaign] ${closed.campaign.id} closed\n`);
+  process.stdout.write(`[campaign] ledger · docs/campaigns/${closed.campaign.id}/ledger · ${closed.ledgerFiles.length} files\n`);
   if (syncAgentSignal(runsDir)) process.stdout.write(`[campaign] AGENTS.md signal updated\n`);
 }
 

package/src/cli/manual.mjs

@@ -14,6 +14,7 @@ import CAMPAIGN_OPERATIONS from "./campaign.mjs";
 import SEAT_OPERATIONS from "./seat.mjs";
 import CONTRACT_OPERATIONS from "./contract.mjs";
 import SKILLS_OPERATIONS from "./skills.mjs";
+import SPEC_OPERATIONS from "./spec.mjs";
 
 /** @typedef {{type: "string"|"boolean", multiple?: boolean}} FlagSpec */
 /** @typedef {{flags?: Record<string, FlagSpec>, operations?: Record<string, Record<string, FlagSpec>>}} VerbSurface */
@@ -22,7 +23,7 @@ import SKILLS_OPERATIONS from "./skills.mjs";
 const MANUAL_PATH = fileURLToPath(new URL("../../docs/COMMANDS.md", import.meta.url));
 
 /**
- * `campaign`, `seat`, `contract` and `skills` are dispatched before
+ * `campaign`, `seat`, `contract`, `skills` and `spec` are dispatched before
  * `COMMAND_OPTIONS` is ever consulted (`cli.mjs` routes them by `argv[0]`), so
  * they carry no flags of their own — only the operations their own module
  * declares. Their top-level `## faberun <verb>` section is therefore never
@@ -35,6 +36,7 @@ const CONTAINER_OPERATIONS = {
   seat: SEAT_OPERATIONS,
   contract: CONTRACT_OPERATIONS,
   skills: SKILLS_OPERATIONS,
+  spec: SPEC_OPERATIONS,
 };
 
 /**

package/src/cli/spec.mjs

@@ -0,0 +1,119 @@
+/**
+ * `spec` argv: validate and scaffold a spec document. Both operations are
+ * deterministic — `src/plan/spec.mjs` invokes no model — so this file only
+ * owns the wire, the same split every other verb module in this directory
+ * uses.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs as parseFlags } from "node:util";
+import { validateSpec } from "../plan/spec.mjs";
+
+/** @typedef {import("../plan/spec.mjs").SpecValidation} SpecValidation */
+
+/** Flags are scoped to the operation that declares them; all others are rejected. */
+/** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
+const OPERATION_OPTIONS = {
+  validate: { "strict-traceability": { type: "boolean" }, json: { type: "boolean" } },
+  scaffold: { id: { type: "string" } },
+};
+
+const SCAFFOLD_TEMPLATE = `---
+id: <id>
+title: "<title>"
+version: 1.0.0
+status: draft
+date: <yyyy-mm-dd>
+owner: <owner>
+target: <org/repo>
+baseline: <git sha>
+---
+
+# <title>
+
+## Intent
+
+<Why this work, what problem, what it unblocks.>
+
+## Requirements
+
+### R1. <title>
+
+- **statement:** <the testable claim>
+- **proof:** \`command: <shell command>\`
+
+## Non-goals
+
+- <what this spec explicitly excludes>
+`;
+
+/**
+ * @param {string[]} args
+ * @returns {void}
+ */
+export function specCli(args) {
+  const operation = args[0];
+  if (!operation || !Object.hasOwn(OPERATION_OPTIONS, operation)) return usage();
+  let parsed;
+  try {
+    parsed = parseFlags({ args: args.slice(1), options: OPERATION_OPTIONS[operation], allowPositionals: true, strict: true });
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return usage();
+  }
+  const target = parsed.positionals[0];
+  if (!target || parsed.positionals.length > 1) return usage();
+  const values = /** @type {{"strict-traceability"?: boolean, json?: boolean, id?: string}} */ (parsed.values);
+  if (operation === "validate") {
+    validateSpecFile(resolve(target), { strict: values["strict-traceability"] === true, json: values.json === true });
+    return;
+  }
+  try {
+    scaffoldSpec(resolve(target), typeof values.id === "string" ? values.id : undefined);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}
+
+/**
+ * Validate a spec file and print its class, its overall verdict, and one
+ * line per finding. Exits `1` when the verdict is not `ok`.
+ *
+ * @param {string} path
+ * @param {{strict: boolean, json: boolean}} options
+ * @returns {SpecValidation}
+ */
+export function validateSpecFile(path, { strict, json }) {
+  const result = validateSpec(readFileSync(path, "utf8"), { cwd: process.cwd(), strict });
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } else {
+    process.stdout.write(`${result.class} · ${result.class === "legacy" ? "accepted" : result.ok ? "ok" : "not ok"}\n`);
+    for (const finding of result.findings) process.stdout.write(`[${finding.severity}] ${finding.rule}: ${finding.message}\n`);
+  }
+  if (!result.ok) process.exitCode = 1;
+  return result;
+}
+
+/**
+ * Write an empty document in the spec format at `path`. Refuses to overwrite
+ * an existing file.
+ *
+ * @param {string} path
+ * @param {string} [id]
+ * @returns {void}
+ */
+export function scaffoldSpec(path, id) {
+  if (existsSync(path)) throw new Error(`refusing to overwrite an existing file: ${path}`);
+  writeFileSync(path, id ? SCAFFOLD_TEMPLATE.replace("<id>", id) : SCAFFOLD_TEMPLATE);
+  process.stdout.write(`scaffolded ${path}\n`);
+}
+
+/** @returns {void} */
+function usage() {
+  process.stderr.write("usage: faberun spec <validate|scaffold> <path> [--strict-traceability] [--json] [--id <value>]\n");
+  process.exitCode = 2;
+}
+
+export default OPERATION_OPTIONS;

package/src/cli.mjs

@@ -31,6 +31,7 @@ import { setupCommand } from "./cli/setup.mjs";
 import { skillsCli } from "./cli/skills.mjs";
 import { updateCommand } from "./cli/update.mjs";
 import { contractCli, validateContractFile } from "./cli/contract.mjs";
+import { specCli } from "./cli/spec.mjs";
 import { METRICS_OPTIONS, renderCampaignMetrics } from "./campaign/metrics.mjs";
 import { runContract } from "./engine/scheduler.mjs";
 import { resumeRun } from "./engine/resume.mjs";
@@ -209,6 +210,7 @@ async function main(argv) {
   if (argv[0] === "seat") { seatCli(argv.slice(1)); return; }
   if (argv[0] === "skills") { skillsCli(argv.slice(1)); return; }
   if (argv[0] === "contract") { contractCli(argv.slice(1)); return; }
+  if (argv[0] === "spec") { specCli(argv.slice(1)); return; }
   const parsed = parseCli(argv);
   if (!parsed) { usage(); return; }
   const { command, values } = parsed;

package/src/plan/freeze.mjs

@@ -0,0 +1,97 @@
+/**
+ * Freezing a plan: the boundary between a session's draft and a contract the
+ * engine can execute. `freezePlan` writes the plan's nodes as a validated
+ * contract.json, plus a plan.json carrying that contract's digest and the
+ * full provenance of how it was produced — the two files travel together so
+ * a later launch and this record agree on exactly what was reviewed.
+ * `verifyFrozenPlan` is the one check that the pair still agree.
+ *
+ * Nothing here invokes a model or the engine; it only writes and hashes
+ * bytes, so freezing a plan can never be mistaken for starting a run.
+ */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION, contractDigest, validateContract } from "../contract/index.mjs";
+
+/** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
+
+/** @typedef {{runtimeId: string, model: string}} PlanParticipant */
+/** @typedef {{id: string, severity: "minor"|"major"|"critical", nodeId?: string, text: string}} PlanFinding */
+/** @typedef {{targetGitHead: string|null, planner: PlanParticipant, reviewer: PlanParticipant, sizing: unknown, findings: PlanFinding[]}} PlanProvenanceInput */
+/** @typedef {PlanProvenanceInput & {packageVersion: string, schemaVersion: number, contractVersion: string}} PlanProvenance */
+/** @typedef {{formatVersion: number, contractDigest: string, provenance: PlanProvenance}} FrozenPlan */
+/** @typedef {{ok: boolean, digest: string, expectedDigest: string}} FrozenPlanVerdict */
+
+const PLAN_FORMAT_VERSION = 1;
+
+/** @returns {string} the installed package's own version, read once per call so a freeze always names the toolchain that produced it */
+function packageVersion() {
+  const packageJsonPath = fileURLToPath(new URL("../../package.json", import.meta.url));
+  return JSON.parse(readFileSync(packageJsonPath, "utf8")).version;
+}
+
+/**
+ * Validate `plan` as a contract and, only once it is valid, write it and a
+ * sibling plan.json naming its digest and provenance. `plan` supplies
+ * `schemaVersion`/`contractVersion` itself; when it does not, this fills in
+ * the runner's own current values.
+ *
+ * contract.json is written before validation runs, because a packet may
+ * declare `readFiles: ["contract.json"]` — an execution packet's own file,
+ * self-referenced the same way every fixture in this codebase already does.
+ * A validation failure removes that file again, so a caller never observes a
+ * contract.json that failed its own check.
+ *
+ * @param {JsonObject} plan
+ * @param {{outDir: string, provenance: PlanProvenanceInput}} options
+ * @returns {FrozenPlan}
+ */
+export function freezePlan(plan, { outDir, provenance }) {
+  mkdirSync(outDir, { recursive: true });
+  const contractPath = join(outDir, "contract.json");
+  const raw = /** @type {JsonObject} */ ({
+    schemaVersion: PROTOCOL_SCHEMA_VERSION,
+    contractVersion: CONTRACT_VERSION,
+    ...plan,
+  });
+  writeFileSync(contractPath, `${JSON.stringify(raw, null, 2)}\n`);
+  try {
+    validateContract(raw, contractPath);
+  } catch (error) {
+    rmSync(contractPath, { force: true });
+    throw error;
+  }
+  const frozen = /** @type {FrozenPlan} */ ({
+    formatVersion: PLAN_FORMAT_VERSION,
+    contractDigest: contractDigest(raw),
+    provenance: {
+      packageVersion: packageVersion(),
+      schemaVersion: /** @type {number} */ (raw.schemaVersion),
+      contractVersion: /** @type {string} */ (raw.contractVersion),
+      targetGitHead: provenance.targetGitHead,
+      planner: provenance.planner,
+      reviewer: provenance.reviewer,
+      sizing: provenance.sizing,
+      findings: provenance.findings,
+    },
+  });
+  writeFileSync(join(outDir, "plan.json"), `${JSON.stringify(frozen, null, 2)}\n`);
+  return frozen;
+}
+
+/**
+ * Recompute contract.json's digest from the bytes on disk and compare it
+ * with the digest plan.json recorded at freeze time. A single byte changed
+ * in either file — the contract re-authored after review, or the plan
+ * record itself tampered with — is a mismatch.
+ *
+ * @param {string} outDir
+ * @returns {FrozenPlanVerdict}
+ */
+export function verifyFrozenPlan(outDir) {
+  const raw = JSON.parse(readFileSync(join(outDir, "contract.json"), "utf8"));
+  const plan = JSON.parse(readFileSync(join(outDir, "plan.json"), "utf8"));
+  const digest = contractDigest(raw);
+  return { ok: digest === plan.contractDigest, digest, expectedDigest: plan.contractDigest };
+}

package/src/plan/repo-facts.mjs

@@ -0,0 +1,148 @@
+/**
+ * Repo facts: a deterministic, bounded inventory of the target repository —
+ * tracked paths, declared scripts, timed verification candidates, and which
+ * test file covers which source module — collected without invoking a model.
+ * A planning stage's draft is authored against exactly this JSON instead of
+ * the session reading the repository by hand.
+ *
+ * Sorting and the absence of any clock in the output itself (only inside an
+ * injected measurer's own numbers) is what makes two calls at the same HEAD
+ * byte-identical.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { timeVerificationCommands } from "../host/preflight.mjs";
+import { boundedGitSync, gitHead } from "../repo/worktree.mjs";
+
+/** @typedef {{argv: string[], measuredMs: number, eligible: boolean}} VerificationCandidate */
+/** @typedef {{path: string, covers: string|null}} TestFileEntry */
+/** @typedef {{formatVersion: number, gitHead: string|null, paths: string[], truncated: boolean, scripts: Record<string, string>, verificationCandidates: VerificationCandidate[], testFiles: TestFileEntry[]}} RepoFacts */
+/** @typedef {{now?: () => number, run?: typeof import("node:child_process").spawnSync}} MeasureProbes */
+
+const FORMAT_VERSION = 1;
+const DEFAULT_MAX_PATHS = 2000;
+const ELIGIBLE_MS_CEILING = 600_000;
+const CANDIDATE_TIMEOUT_SEC = ELIGIBLE_MS_CEILING / 1_000;
+
+/**
+ * Every path git tracks at HEAD, sorted. The bounded spawn is the same
+ * pattern `src/repo/source-identity.mjs` uses for its own git reads: a
+ * `boundedGitSync` call, thrown on a non-zero exit or a killed process,
+ * never a raw `spawnSync`.
+ *
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function listTrackedPaths(cwd) {
+  const result = boundedGitSync(["-C", cwd, "ls-files"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  if (result.error || result.status !== 0) throw result.error ?? new Error(`git ls-files exited ${result.status}`);
+  return String(result.stdout).split("\n").filter(Boolean).sort();
+}
+
+/** @param {string} cwd @returns {Record<string, string>} */
+function readScripts(cwd) {
+  const packagePath = join(cwd, "package.json");
+  if (!existsSync(packagePath)) return {};
+  const parsed = JSON.parse(readFileSync(packagePath, "utf8"));
+  return parsed.scripts && typeof parsed.scripts === "object" ? parsed.scripts : {};
+}
+
+/**
+ * The first-level directories under test/ that any tracked path is nested
+ * inside. `node --test <dir>` recurses through everything below it, so one
+ * candidate per directory is the whole layout, not one per file.
+ *
+ * @param {string[]} paths
+ * @returns {string[]}
+ */
+function testDirectories(paths) {
+  /** @type {Set<string>} */
+  const directories = new Set();
+  for (const path of paths) {
+    const match = /^test\/([^/]+)\//u.exec(path);
+    if (match) directories.add(`test/${match[1]}`);
+  }
+  return [...directories].sort();
+}
+
+/**
+ * @param {string[]} paths
+ * @param {Set<string>} pathSet
+ * @returns {TestFileEntry[]}
+ */
+function testFileEntries(paths, pathSet) {
+  return paths
+    .filter((path) => path.startsWith("test/") && path.endsWith(".test.mjs"))
+    .map((path) => {
+      const modulePath = `src/${path.slice("test/".length, -".test.mjs".length)}.mjs`;
+      return { path, covers: pathSet.has(modulePath) ? modulePath : null };
+    });
+}
+
+/**
+ * @param {Record<string, string>} scripts
+ * @param {string[]} paths
+ * @returns {{argv: string[]}[]}
+ */
+function candidateCommands(scripts, paths) {
+  const commands = testDirectories(paths).map((directory) => ({ argv: ["node", "--test", directory] }));
+  for (const name of ["check", "typecheck"]) {
+    if (typeof scripts[name] === "string") commands.push({ argv: ["npm", "run", name] });
+  }
+  return commands;
+}
+
+/**
+ * Time every candidate through `timeVerificationCommands`'s own probe —
+ * real `spawnSync` and `Date.now` by default, or the caller's fake — instead
+ * of re-implementing the spawn, ceiling and ENOENT handling it already owns.
+ * That function calls `now()` exactly twice per command, in order (start,
+ * then stop); wrapping it to record every mark it produces is how the real
+ * elapsed ms is recovered without parsing its human-readable report.
+ *
+ * @param {string} cwd
+ * @param {{argv: string[]}[]} commands
+ * @param {MeasureProbes} probes
+ * @returns {VerificationCandidate[]}
+ */
+function measureCandidates(cwd, commands, probes) {
+  if (commands.length === 0) return [];
+  const now = probes.now ?? (() => Date.now());
+  /** @type {number[]} */
+  const marks = [];
+  const contract = /** @type {import("../contract/index.mjs").ValidatedContract} */ (/** @type {any} */ ({
+    cwd,
+    nodes: commands.map((command, index) => ({
+      id: `repo-facts-${index}`,
+      taskPacket: { verification: [{ argv: command.argv, timeoutSec: CANDIDATE_TIMEOUT_SEC }] },
+    })),
+  }));
+  timeVerificationCommands(contract, { ...probes, now: () => { const mark = now(); marks.push(mark); return mark; } });
+  return commands.map((command, index) => {
+    const measuredMs = marks[index * 2 + 1] - marks[index * 2];
+    return { argv: command.argv, measuredMs, eligible: measuredMs <= ELIGIBLE_MS_CEILING };
+  });
+}
+
+/**
+ * @param {string} cwd
+ * @param {{measure?: MeasureProbes, maxPaths?: number}} [options]
+ * @returns {RepoFacts}
+ */
+export function collectRepoFacts(cwd, options = {}) {
+  const maxPaths = options.maxPaths ?? DEFAULT_MAX_PATHS;
+  const allPaths = listTrackedPaths(cwd);
+  const pathSet = new Set(allPaths);
+  const scripts = readScripts(cwd);
+  const commands = candidateCommands(scripts, allPaths);
+  const truncated = allPaths.length > maxPaths;
+  return {
+    formatVersion: FORMAT_VERSION,
+    gitHead: gitHead(cwd),
+    paths: truncated ? allPaths.slice(0, maxPaths) : allPaths,
+    truncated,
+    scripts,
+    verificationCandidates: measureCandidates(cwd, commands, options.measure ?? {}),
+    testFiles: testFileEntries(allPaths, pathSet),
+  };
+}

package/src/plan/routing.mjs

@@ -0,0 +1,200 @@
+/**
+ * Declarative runtime routing: cross a taskKind/riskTier table with live
+ * discovery availability to assign a worker and a judge runtime to each of a
+ * plan's draft nodes. Separate from runtime-discovery.mjs because that module
+ * resolves a *contract's* already-declared runtimes; a plan's draft node
+ * never names one (the constitution reserves model choice to runtimes,
+ * runtimeDefaults, or an explicit node override) — this module is what turns
+ * a taskKind/riskTier classification into one of those three.
+ */
+
+import { cheapest, strongest } from "../engine/runtime-discovery.mjs";
+
+/** @typedef {{available: boolean, exhaustedUntil: string|null, [key: string]: unknown}} RoutingAvailability */
+/** @typedef {{vendor: string, tier?: number|string, costRank?: number, fallback?: string, [key: string]: unknown}} RoutingRuntime */
+/** @typedef {{id: string, taskKind?: string, riskTier?: string}} RoutingNode */
+/** @typedef {{taskKind?: string, riskTier?: string}} RoutingWhen */
+/** @typedef {{name?: string, when: RoutingWhen, prefer: string[], role: "worker"|"judge"}} RoutingRule */
+/** @typedef {{worker?: string, judge?: string}} RoutingRoleMap */
+/** @typedef {{table?: RoutingRule[], runtimes: Record<string, RoutingRuntime>, availability?: Record<string, RoutingAvailability>, runtimeDefaults?: RoutingRoleMap, overrides?: Record<string, RoutingRoleMap>}} RoutingConfig */
+/** @typedef {{worker: string|null, judge: string|null, rule: {worker: string, judge: string}}} RoutingAssignment */
+/** @typedef {{nodeId: string, role: "worker"|"judge", rule: string}} RoutingUnmet */
+/** @typedef {{assignments: Record<string, RoutingAssignment>, unmet: RoutingUnmet[]}} RoutingResult */
+
+/**
+ * @param {RoutingNode[]} nodes
+ * @param {RoutingConfig} config
+ * @param {{partial?: boolean}} [options]
+ * @returns {RoutingResult}
+ */
+export function resolveRuntimes(nodes, config, options = {}) {
+  const table = config.table ?? [];
+  const runtimes = config.runtimes ?? {};
+  const availability = config.availability ?? {};
+  const runtimeDefaults = config.runtimeDefaults ?? {};
+  const overrides = config.overrides ?? {};
+
+  /** @type {Record<string, RoutingAssignment>} */
+  const assignments = {};
+  /** @type {RoutingUnmet[]} */
+  const unmet = [];
+
+  for (const node of nodes) {
+    const override = overrides[node.id] ?? {};
+    const worker = resolveRole(node, "worker", { runtimes, availability, runtimeDefaults, table, override, forbiddenVendors: EMPTY_VENDORS });
+    if (worker.runtimeId === null) unmet.push({ nodeId: node.id, role: "worker", rule: worker.rule });
+    // The judge's forbidden vendors follow the worker runtime that was
+    // actually chosen, never the row that named it — a worker unmet leaves
+    // nothing to conflict with, so the judge resolves without restriction.
+    const forbiddenVendors = worker.runtimeId ? forbiddenJudgeVendors(worker.runtimeId, runtimes) : EMPTY_VENDORS;
+    const judge = resolveRole(node, "judge", { runtimes, availability, runtimeDefaults, table, override, forbiddenVendors });
+    if (judge.runtimeId === null) unmet.push({ nodeId: node.id, role: "judge", rule: judge.rule });
+    assignments[node.id] = { worker: worker.runtimeId, judge: judge.runtimeId, rule: { worker: worker.rule, judge: judge.rule } };
+  }
+
+  if (unmet.length && options.partial !== true) {
+    const detail = unmet.map(({ nodeId, role, rule }) => `${nodeId}.${role} (rule: ${rule})`).join("; ");
+    throw new Error(`runtime_routing_unmet: ${detail}`);
+  }
+
+  return { assignments, unmet };
+}
+
+/** @type {ReadonlySet<string>} */
+const EMPTY_VENDORS = Object.freeze(new Set());
+
+/**
+ * Precedence for one role on one node: an explicit node override, then the
+ * operator's runtimeDefaults, then the first table row whose `when` matches
+ * this node's classification, then plain discovery. A row or default that
+ * names an unavailable or vendor-forbidden runtime is unmet by that rule —
+ * it does not fall through to a lower-precedence source, since falling
+ * through would silently discard an explicit declaration; only the
+ * candidates *within* a row's `prefer` list, and within discovery, are
+ * skipped for exhaustion or vendor conflict.
+ *
+ * @param {RoutingNode} node
+ * @param {"worker"|"judge"} role
+ * @param {{runtimes: Record<string, RoutingRuntime>, availability: Record<string, RoutingAvailability>, runtimeDefaults: RoutingRoleMap, table: RoutingRule[], override: RoutingRoleMap, forbiddenVendors: ReadonlySet<string>}} context
+ * @returns {{runtimeId: string|null, rule: string}}
+ */
+function resolveRole(node, role, context) {
+  const { runtimes, availability, runtimeDefaults, table, override, forbiddenVendors } = context;
+
+  if (override[role] !== undefined) {
+    const id = override[role];
+    return { runtimeId: admits(id, runtimes, availability, forbiddenVendors) ? id : null, rule: "override" };
+  }
+
+  if (runtimeDefaults[role] !== undefined) {
+    const id = runtimeDefaults[role];
+    return { runtimeId: admits(id, runtimes, availability, forbiddenVendors) ? id : null, rule: "runtimeDefaults" };
+  }
+
+  const row = table.find((candidate) => candidate.role === role
+    && (candidate.when.taskKind === undefined || candidate.when.taskKind === node.taskKind)
+    && (candidate.when.riskTier === undefined || candidate.when.riskTier === node.riskTier));
+  if (row) {
+    const rule = ruleLabel(row);
+    const id = row.prefer.find((candidate) => admits(candidate, runtimes, availability, forbiddenVendors)) ?? null;
+    return { runtimeId: id, rule };
+  }
+
+  const discovered = role === "worker"
+    ? cheapestAvailable(runtimes, availability, forbiddenVendors)
+    : strongestAvailable(runtimes, availability, forbiddenVendors);
+  return { runtimeId: discovered, rule: "discovery" };
+}
+
+/**
+ * @param {string} id
+ * @param {Record<string, RoutingRuntime>} runtimes
+ * @param {Record<string, RoutingAvailability>} availability
+ * @param {ReadonlySet<string>} forbiddenVendors
+ * @returns {boolean}
+ */
+function admits(id, runtimes, availability, forbiddenVendors) {
+  const runtime = runtimes[id];
+  if (!runtime) return false;
+  if (forbiddenVendors.has(runtime.vendor)) return false;
+  return isAvailable(availability[id]);
+}
+
+/** @param {RoutingAvailability|undefined} entry @returns {boolean} */
+function isAvailable(entry) {
+  if (!entry) return false;
+  if (entry.available === true) return !entry.exhaustedUntil || Date.parse(entry.exhaustedUntil) <= Date.now();
+  return Boolean(entry.exhaustedUntil && Date.parse(entry.exhaustedUntil) <= Date.now());
+}
+
+/**
+ * Every vendor a judge may not carry: the worker's own vendor, plus the
+ * vendor of each runtime reachable through the worker's declared `fallback`
+ * chain — the same independence the contract validator enforces statically
+ * once a worker is actually chosen dynamically here.
+ *
+ * @param {string} workerId
+ * @param {Record<string, RoutingRuntime>} runtimes
+ * @returns {Set<string>}
+ */
+function forbiddenJudgeVendors(workerId, runtimes) {
+  const vendors = new Set();
+  const seen = new Set();
+  /** @type {string|undefined} */
+  let id = workerId;
+  while (id !== undefined && runtimes[id] && !seen.has(id)) {
+    seen.add(id);
+    vendors.add(runtimes[id].vendor);
+    id = runtimes[id].fallback;
+  }
+  return vendors;
+}
+
+/** @param {RoutingRule} row @returns {string} */
+function ruleLabel(row) {
+  if (row.name) return row.name;
+  return `table:${row.role}:${row.when.taskKind ?? "*"}:${row.when.riskTier ?? "*"}`;
+}
+
+/**
+ * @param {Record<string, RoutingRuntime>} runtimes
+ * @param {Record<string, RoutingAvailability>} availability
+ * @param {ReadonlySet<string>} forbiddenVendors
+ * @returns {{id: string, runtime: RoutingRuntime, order: number}[]}
+ */
+function candidateEntries(runtimes, availability, forbiddenVendors) {
+  return Object.entries(runtimes)
+    .map(([id, runtime], order) => ({ id, runtime, order }))
+    .filter(({ id, runtime }) => !forbiddenVendors.has(runtime.vendor) && isAvailable(availability[id]));
+}
+
+/**
+ * The plain discovery default for a worker: `runtime-discovery.mjs`'s own
+ * cheapest-first ranking, over candidates already filtered to what's
+ * available and vendor-permitted here. The ranking lives there, not here, so
+ * a contract's default and a plan's routed default never drift apart.
+ *
+ * @param {Record<string, RoutingRuntime>} runtimes
+ * @param {Record<string, RoutingAvailability>} availability
+ * @param {ReadonlySet<string>} forbiddenVendors
+ * @returns {string|null}
+ */
+function cheapestAvailable(runtimes, availability, forbiddenVendors) {
+  return cheapest(candidateEntries(runtimes, availability, forbiddenVendors))?.id ?? null;
+}
+
+/**
+ * The plain discovery default for a judge: `runtime-discovery.mjs`'s own
+ * strongest-first ranking, over candidates already filtered to exclude the
+ * worker's vendor and fallback-chain vendors — `strongest`'s own single-vendor
+ * exclusion is passed the empty string, no runtime's actual vendor label, so
+ * it is a no-op on top of the filtering already done here.
+ *
+ * @param {Record<string, RoutingRuntime>} runtimes
+ * @param {Record<string, RoutingAvailability>} availability
+ * @param {ReadonlySet<string>} forbiddenVendors
+ * @returns {string|null}
+ */
+function strongestAvailable(runtimes, availability, forbiddenVendors) {
+  return strongest(candidateEntries(runtimes, availability, forbiddenVendors), "")?.id ?? null;
+}

package/src/plan/spec.mjs

@@ -0,0 +1,320 @@
+/**
+ * The spec format (skills/faberun/references/spec-format.md): parsing and
+ * deterministic validation of the document a spec author hands the planner.
+ * Separate from `contract/` because a spec is pre-planning input, never an
+ * authored contract, and from `engine/` because nothing here dispatches,
+ * schedules, or reaches a provider — this module invokes no model.
+ */
+import { git } from "../repo/worktree.mjs";
+
+/** @typedef {"command"|"path"|"judgment"} ProofKind */
+/** @typedef {{kind: ProofKind, ref?: string}} SpecProof */
+/** @typedef {{id: string|null, title: string, statement: string|null, proof: SpecProof|null, constraints: string|null, line: number}} SpecRequirement */
+/** @typedef {Record<string, string>} SpecFrontMatter */
+/** @typedef {{heading: string, body: string, line: number}} SpecSection */
+/** @typedef {{frontMatter: SpecFrontMatter|null, sections: Map<string, SpecSection>, requirements: SpecRequirement[]}} ParsedSpec */
+/** @typedef {{rule: string, severity: "advisory"|"blocking", message: string, line: number}} SpecFinding */
+/** @typedef {{class: "structured"|"legacy", ok: boolean, findings: SpecFinding[]}} SpecValidation */
+
+/**
+ * Section headings the format recognizes, in the language the reference
+ * proposal actually writes them (skills/faberun/references/spec-format.md):
+ * the section's role is what a rule checks, never the language of the
+ * heading text.
+ */
+const SECTION_ALIASES = new Map([
+  ["intenção", "intent"],
+  ["intencao", "intent"],
+  ["requisitos", "requirements"],
+  ["não-objetivos", "non-goals"],
+  ["nao-objetivos", "non-goals"],
+  ["restrições", "constraints"],
+  ["restricoes", "constraints"],
+  ["critério de sucesso", "success criteria"],
+  ["criterio de sucesso", "success criteria"],
+  ["riscos", "risks"],
+]);
+
+/** @param {string} raw @returns {string} */
+function normalizeHeading(raw) {
+  const key = raw.trim().toLowerCase();
+  return SECTION_ALIASES.get(key) ?? key;
+}
+
+/**
+ * @param {string[]} lines
+ * @returns {{data: SpecFrontMatter, end: number}|null}
+ */
+function extractFrontMatter(lines) {
+  if (lines[0]?.trim() !== "---") return null;
+  let end = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === "---") { end = i; break; }
+  }
+  if (end === -1) return null;
+  /** @type {SpecFrontMatter} */
+  const data = {};
+  for (let i = 1; i < end; i += 1) {
+    const match = /^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/u.exec(lines[i]);
+    if (!match) continue;
+    data[match[1]] = unquote(match[2].trim());
+  }
+  return { data, end };
+}
+
+/** @param {string} value @returns {string} */
+function unquote(value) {
+  return value.length >= 2 && value.startsWith("\"") && value.endsWith("\"") ? value.slice(1, -1) : value;
+}
+
+/**
+ * Every level-2 (`## `) section from `startIndex` to the end of the document.
+ * A level-3 (`### `) heading, which a requirement block owns, is left inside
+ * its parent section's body.
+ *
+ * @param {string[]} lines
+ * @param {number} startIndex
+ * @returns {Map<string, SpecSection>}
+ */
+function extractSections(lines, startIndex) {
+  /** @type {Map<string, SpecSection>} */
+  const sections = new Map();
+  let i = startIndex;
+  while (i < lines.length) {
+    const match = /^##\s+(.+?)\s*$/u.exec(lines[i]);
+    if (!match) { i += 1; continue; }
+    const heading = match[1];
+    const bodyStart = i + 1;
+    let end = bodyStart;
+    while (end < lines.length && !/^##\s+/u.test(lines[end])) end += 1;
+    sections.set(normalizeHeading(heading), { heading, body: lines.slice(bodyStart, end).join("\n"), line: bodyStart + 1 });
+    i = end;
+  }
+  return sections;
+}
+
+/**
+ * A `- **key:** value` bullet, and any following non-blank, non-bullet line as
+ * its wrapped continuation.
+ *
+ * @param {string[]} lines
+ * @returns {Map<string, string>}
+ */
+function parseBullets(lines) {
+  /** @type {Map<string, string>} */
+  const bullets = new Map();
+  let currentKey = null;
+  for (const line of lines) {
+    const match = /^-\s+\*\*([a-zA-Z-]+):\*\*\s?(.*)$/u.exec(line);
+    if (match) {
+      currentKey = match[1].toLowerCase();
+      bullets.set(currentKey, match[2].trim());
+      continue;
+    }
+    const trimmed = line.trim();
+    if (!trimmed) { currentKey = null; continue; }
+    if (currentKey && !trimmed.startsWith("-")) bullets.set(currentKey, `${bullets.get(currentKey)} ${trimmed}`.trim());
+  }
+  return bullets;
+}
+
+/**
+ * `command: <shell command>`, `path: <repo-relative path>`, or
+ * `judgment: true`, optionally wrapped in one pair of backticks (the shape
+ * the reference proposal writes).
+ *
+ * @param {string|undefined} raw
+ * @returns {SpecProof|null}
+ */
+function parseProof(raw) {
+  if (!raw) return null;
+  const unwrapped = /^`(.*)`$/u.exec(raw.trim());
+  const value = unwrapped ? unwrapped[1] : raw.trim();
+  const match = /^(command|path|judgment):\s*(.*)$/u.exec(value);
+  if (!match) return null;
+  const kind = /** @type {ProofKind} */ (match[1]);
+  return kind === "judgment" ? { kind } : { kind, ref: match[2].trim() };
+}
+
+/**
+ * @param {SpecSection|undefined} section
+ * @returns {SpecRequirement[]}
+ */
+function extractRequirements(section) {
+  if (!section) return [];
+  const lines = section.body.split("\n");
+  /** @type {SpecRequirement[]} */
+  const requirements = [];
+  let i = 0;
+  while (i < lines.length) {
+    const match = /^###\s+(.+?)\s*$/u.exec(lines[i]);
+    if (!match) { i += 1; continue; }
+    const heading = match[1];
+    const blockLine = section.line + i + 1;
+    let end = i + 1;
+    while (end < lines.length && !/^###\s+/u.test(lines[end])) end += 1;
+    const bullets = parseBullets(lines.slice(i + 1, end));
+    const idMatch = /^(R\d+)\.\s*(.*)$/u.exec(heading);
+    requirements.push({
+      id: idMatch ? idMatch[1] : null,
+      title: idMatch ? idMatch[2].trim() : heading,
+      statement: bullets.get("statement") ?? null,
+      proof: parseProof(bullets.get("proof")),
+      constraints: bullets.get("constraints") ?? null,
+      line: blockLine,
+    });
+    i = end;
+  }
+  return requirements;
+}
+
+/**
+ * Parse a spec document into its front matter, sections and requirements.
+ * Pure text processing: no file I/O, no git, no model.
+ *
+ * @param {string} text
+ * @returns {ParsedSpec}
+ */
+export function parseSpec(text) {
+  const lines = text.split("\n");
+  const frontMatter = extractFrontMatter(lines);
+  const sections = extractSections(lines, frontMatter ? frontMatter.end + 1 : 0);
+  const requirements = extractRequirements(sections.get("requirements"));
+  return { frontMatter: frontMatter?.data ?? null, sections, requirements };
+}
+
+/**
+ * @param {string} body
+ * @returns {string[]}
+ */
+function tableRows(body) {
+  return body.split("\n").filter((line) => line.trim().startsWith("|"));
+}
+
+/** @param {string} row @returns {string[]} */
+function splitRow(row) {
+  return row.trim().replace(/^\|/u, "").replace(/\|$/u, "").split("|").map((cell) => cell.trim());
+}
+
+/**
+ * A Success criteria table with no Baseline column at all, or a data row
+ * whose Baseline cell is empty or a bare dash.
+ *
+ * @param {SpecSection} section
+ * @returns {SpecFinding[]}
+ */
+function baselineColumnFindings(section) {
+  const rows = tableRows(section.body);
+  if (rows.length < 2) return [];
+  const header = splitRow(rows[0]);
+  const baselineIndex = header.findIndex((cell) => /baseline/iu.test(cell));
+  if (baselineIndex === -1) {
+    return [{ rule: "success-criteria-missing-baseline", severity: "advisory", message: "Success criteria table has no Baseline column", line: section.line }];
+  }
+  /** @type {SpecFinding[]} */
+  const findings = [];
+  for (let i = 2; i < rows.length; i += 1) {
+    const value = splitRow(rows[i])[baselineIndex]?.trim();
+    if (!value || value === "-" || value === "—") {
+      findings.push({ rule: "success-criteria-missing-baseline", severity: "advisory", message: `Success criteria row ${i - 1} has no Baseline value`, line: section.line + i });
+    }
+  }
+  return findings;
+}
+
+/**
+ * `git@host:owner/repo.git` and `https://host/owner/repo.git` both reduce to
+ * the same lowercase `owner/repo` suffix for comparison.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+function normalizeRemoteUrl(url) {
+  return url.trim().replace(/\.git$/u, "").replace(/^git@([^:]+):/u, "https://$1/").toLowerCase();
+}
+
+/**
+ * Whether `ref` names a commit that actually exists in `cwd`. `git rev-parse
+ * <ref>` alone is not enough: given a 40-hex string it echoes the string back
+ * unverified even when no such object exists, so this peels it as `^{commit}`
+ * instead, which fails for an absent or non-commit object.
+ *
+ * @param {string} cwd
+ * @param {string} ref
+ * @returns {boolean}
+ */
+function resolvesToCommit(cwd, ref) {
+  try {
+    git(cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether `target` (an `owner/repo` slug) names the repository this `cwd`'s
+ * `origin` remote points at. Checked against the remote name only, never a
+ * network call.
+ *
+ * @param {string} cwd
+ * @param {string} target
+ * @returns {boolean}
+ */
+function targetMatchesOrigin(cwd, target) {
+  let url;
+  try {
+    url = git(cwd, ["remote", "get-url", "origin"]);
+  } catch {
+    return false;
+  }
+  return normalizeRemoteUrl(url).endsWith(`/${target.toLowerCase()}`);
+}
+
+/**
+ * Validate a spec's traceability rules: no model call, ever
+ * (skills/faberun/references/spec-format.md). A document without front matter
+ * is classified `legacy` and accepted outright, exempt from every rule below.
+ *
+ * Advisory by default — every violation is recorded and `ok` stays `true` —
+ * and blocking under `strict`, where any violation makes `ok` `false`.
+ *
+ * @param {string} text
+ * @param {{cwd?: string, strict?: boolean}} [options]
+ * @returns {SpecValidation}
+ */
+export function validateSpec(text, options = {}) {
+  const parsed = parseSpec(text);
+  if (!parsed.frontMatter) {
+    return {
+      class: "legacy",
+      ok: true,
+      findings: [{ rule: "legacy-document", severity: "advisory", message: "no front matter: accepted as a legacy-class document, not scored against the structured rules", line: 1 }],
+    };
+  }
+  const cwd = options.cwd ?? process.cwd();
+  const strict = options.strict === true;
+  /** @type {SpecFinding[]} */
+  const findings = [];
+  if (!parsed.sections.has("non-goals")) {
+    findings.push({ rule: "missing-non-goals", severity: "advisory", message: "spec has no Non-goals section", line: 1 });
+  }
+  for (const requirement of parsed.requirements) {
+    if (!requirement.id) {
+      findings.push({ rule: "requirement-missing-id", severity: "advisory", message: `requirement "${requirement.title}" has no stable R<n> id`, line: requirement.line });
+    }
+    if (!requirement.proof) {
+      findings.push({ rule: "requirement-missing-proof", severity: "advisory", message: `requirement ${requirement.id ?? requirement.title} has no proof`, line: requirement.line });
+    }
+  }
+  const successCriteria = parsed.sections.get("success criteria");
+  if (successCriteria) findings.push(...baselineColumnFindings(successCriteria));
+  if (typeof parsed.frontMatter.baseline === "string" && !resolvesToCommit(cwd, parsed.frontMatter.baseline)) {
+    findings.push({ rule: "baseline-unresolved", severity: "advisory", message: `baseline "${parsed.frontMatter.baseline}" does not resolve to a commit`, line: 1 });
+  }
+  if (typeof parsed.frontMatter.target === "string" && !targetMatchesOrigin(cwd, parsed.frontMatter.target)) {
+    findings.push({ rule: "target-unresolved", severity: "advisory", message: `target "${parsed.frontMatter.target}" does not match the origin remote`, line: 1 });
+  }
+  const graded = findings.map((finding) => (strict ? { ...finding, severity: /** @type {const} */ ("blocking") } : finding));
+  return { class: "structured", ok: !graded.some((finding) => finding.severity === "blocking"), findings: graded };
+}