faberun 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.7.0",
+  "version": "0.9.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/campaign/journal.mjs

@@ -11,6 +11,7 @@ import { JOURNAL_FILE, JOURNAL_TEXT_BYTES, JOURNAL_WATCH_CURSOR_DIR, JOURNAL_WAT
 import { boundedText, collapseLines } from "../util.mjs";
 import { campaignIdOf } from "./record.mjs";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { dirname, isAbsolute, join } from "node:path";
 import { requireText, requireTimestamp } from "../contract/assert.mjs";
 import { writeJsonAtomic } from "../run/store.mjs";
@@ -34,6 +35,7 @@ const JOURNAL_TYPES = new Set([
   "question.resolved",
   "retrospective",
   "liveness",
+  "seat.allowance",
 ]);
 const SESSION_REQUIRED_TYPES = new Set([
   "session.attached",
@@ -63,7 +65,9 @@ const ENTRY_SHAPES = {
   "question.resolved": ["at", "type", "eventId", "sessionId", "questionId", "text"],
   retrospective: ["at", "type", "eventId", "sessionId", "text"],
   liveness: ["at", "type", "eventId", "campaignId", "runId", "nodeId", "phase", "checkpointsDone", "checkpointsTotal", "runtime", "state", "lastProgressAt", "attention"],
+  "seat.allowance": ["at", "type", "eventId", "sample", "harness", "remaining", "limit", "resetsAt", "delta", "window"],
 };
+const SEAT_ALLOWANCE_SAMPLES = new Set(["start", "freeze"]);
 /**
  * Fields a liveness fact carried before the budget ceiling was removed. A
  * historical journal (like the live campaign's own) still has lines shaped
@@ -272,6 +276,7 @@ export function validateJournalEntry(entry) {
   // rejects an unexpected key; no deeper shape validation is needed for a type
   // nothing produces.
   if (type === "liveness") return;
+  if (type === "seat.allowance") return validateSeatAllowanceEntry(record);
   if (type === "session.attached") return validateSessionEntry(record);
   if (type === "run.registered") {
     requireText(record.runId, "entry.runId");
@@ -293,6 +298,49 @@ export function validateJournalEntry(entry) {
   }
   if (type === "outcome" && record.runId !== undefined) requireText(record.runId, "entry.runId");
 }
+/**
+ * @param {JsonObject} entry
+ */
+function validateSeatAllowanceEntry(entry) {
+  if (!SEAT_ALLOWANCE_SAMPLES.has(/** @type {string} */ (entry.sample))) {
+    throw new TypeError("seat.allowance sample must be start or freeze");
+  }
+  if (entry.harness !== null && typeof entry.harness !== "string") {
+    throw new TypeError("seat.allowance harness must be null or a string");
+  }
+  for (const field of ["remaining", "limit", "delta"]) {
+    if (entry[field] !== null && typeof entry[field] !== "number") {
+      throw new TypeError(`seat.allowance ${field} must be null or a number`);
+    }
+  }
+  if (entry.resetsAt !== null && typeof entry.resetsAt !== "string") {
+    throw new TypeError("seat.allowance resetsAt must be null or a string");
+  }
+  // Optional: a historical entry, and every call site not yet updated to
+  // sample it, carries no window at all.
+  if (entry.window !== undefined && entry.window !== null && typeof entry.window !== "string") {
+    throw new TypeError("seat.allowance window must be null or a string");
+  }
+}
+/**
+ * The one writer of `seat.allowance`: `campaign init` calls it for the
+ * `start` sample, `plan freeze` for the `freeze` sample. Kept as a single
+ * function, rather than two call sites building the literal themselves, so
+ * the field-ownership ratchet does not grow by one for every field this event
+ * carries.
+ *
+ * @param {string} campaignPath
+ * @param {{sample: "start"|"freeze", harness: string|null, remaining: number|null, limit: number|null, resetsAt: string|null, delta: number|null, window?: string|null}} allowance
+ * @returns {{entry: JournalEntry, deduplicated: boolean}}
+ */
+export function appendSeatAllowanceEvent(campaignPath, allowance) {
+  return appendJournal(campaignPath, {
+    type: "seat.allowance",
+    eventId: randomUUID(),
+    at: new Date().toISOString(),
+    ...allowance,
+  });
+}
 /**
  * @param {JsonObject} entry
  */

package/src/cli/brand.mjs

@@ -195,6 +195,9 @@ 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>]",
+    "plan <spec.md> --campaign <id> [--phase <phase>] [--review-rounds <n>] [--approve-below standard|high|none] [--runtime-defaults worker=<id>,judge=<id>] [--detach] [--json]",
     "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

@@ -12,12 +12,14 @@ import {
 } from "../campaign/index.mjs";
 import { lockStale, pidAlive, processStartToken, readLock } from "../run/lock.mjs";
 import { syncAgentSignal } from "../repo/signal.mjs";
-import { acknowledgeJournalEvent, appendJournal, readJournal, watchJournal } from "../campaign/journal.mjs";
+import { acknowledgeJournalEvent, appendJournal, appendSeatAllowanceEvent, readJournal, watchJournal } from "../campaign/journal.mjs";
 import { driveCampaignChain } from "../campaign/chain.mjs";
 import { unparkCampaign } from "../campaign/unpark.mjs";
 import { readCampaign } from "../campaign/record.mjs";
 import { notifyQueueFor } from "../engine/notify-queue.mjs";
 import { appendInbox, readInbox, wakeCapabilityNotice } from "../notify/index.mjs";
+import { allowanceEventFields, sampleAllowance } from "../seat/allowance.mjs";
+import { detectOperatorHarness } from "../seat/harnesses.mjs";
 import { detachArgv, detachSelf, waitForBootstrap } from "./launch.mjs";
 import { errorCode, readJsonTolerant } from "../util.mjs";
 
@@ -326,12 +328,23 @@ function watchLockStale(occupant) {
  * @param {string} campaignId
  * @param {CliValues} values
  */
-function init(campaignId, values) {
+async function init(campaignId, values) {
   const cwd = resolve(values.cwd ?? ".");
   const runsDir = join(cwd, ".runs");
   const goal = textValue(values.goal, "--goal");
   const contracts = contractManifest(values.contract);
   const created = initializeCampaign(runsDir, { campaignId, goal, contracts, landBranch: values.landBranch });
+  // The operator's own seat: whichever harness this CLI is running inside
+  // (env-marker detection, see seat/harnesses.mjs), the only harness whose
+  // allowance is meaningful at a point before any node runtime exists.
+  const harness = detectOperatorHarness();
+  const allowance = await sampleAllowance({ harness });
+  appendSeatAllowanceEvent(created.path, {
+    sample: "start",
+    harness,
+    delta: null,
+    ...allowanceEventFields(allowance),
+  });
   renderHandoff(created.path, runsDir);
   process.stdout.write(`[campaign] ${campaignId} initialized · ${created.path} · landBranch ${created.campaign.landBranch} · ${created.campaign.contracts.length} contract(s)\n`);
   if (syncAgentSignal(runsDir)) process.stdout.write(`[campaign] AGENTS.md signal updated\n`);
@@ -447,6 +460,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/plan.mjs

@@ -0,0 +1,142 @@
+/**
+ * `plan` argv: run the planning pipeline as successive ordinary runs (draft,
+ * review, revise up to a round budget) and freeze the result, or park it
+ * contested. This file only owns the wire — `src/plan/pipeline.mjs` owns the
+ * sequencing and every decision the pipeline makes.
+ */
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { detachArgv, detachSelf, waitForBootstrap } from "./launch.mjs";
+import { classifyRunProgress } from "../campaign/chain.mjs";
+import { runProgress } from "../engine/supervise.mjs";
+import { DISCOVERY_RUNTIME_DEFINITIONS } from "../engine/runtime-discovery.mjs";
+import { validateRuntime } from "../contract/runtime.mjs";
+import { delay } from "../util.mjs";
+import { runPlanningPipeline } from "../plan/pipeline.mjs";
+
+/** How often a foreground `plan` polls a launched stage's run directory. */
+const DEFAULT_POLL_MS = 1_000;
+
+/**
+ * `--runtime-defaults worker=<id>,judge=<id>`, either key optional, comma
+ * separated. Absent entirely, the pipeline falls through to plain
+ * availability discovery for every node.
+ *
+ * @param {string|undefined} value
+ * @returns {{worker?: string, judge?: string}}
+ */
+export function parseRuntimeDefaults(value) {
+  /** @type {{worker?: string, judge?: string}} */
+  const result = {};
+  if (value === undefined) return result;
+  for (const pair of value.split(",")) {
+    const eq = pair.indexOf("=");
+    if (eq < 0) throw new Error(`--runtime-defaults entries must be worker=<id> or judge=<id>: ${pair}`);
+    const role = pair.slice(0, eq).trim();
+    const id = pair.slice(eq + 1).trim();
+    if (role !== "worker" && role !== "judge") throw new Error(`--runtime-defaults role must be worker or judge: ${role}`);
+    if (!id) throw new Error(`--runtime-defaults ${role} needs a runtime id`);
+    result[role] = id;
+  }
+  return result;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number}
+ */
+function reviewRoundsOf(value) {
+  if (value === undefined) return 2;
+  const rounds = Number(value);
+  if (!Number.isInteger(rounds) || rounds < 1) throw new Error(`--review-rounds must be a positive integer: ${String(value)}`);
+  return rounds;
+}
+
+/**
+ * A `--runtimes <path>` catalogue: a JSON object in the same shape a
+ * contract's own `runtimes` field takes, validated entry-by-entry with the
+ * same validator `validateContract` uses, so a malformed catalogue is
+ * rejected before any planning stage launches rather than surfacing as an
+ * opaque failure deep inside the pipeline.
+ *
+ * @param {string} path
+ * @returns {Record<string, import("../contract/index.mjs").ValidatedRuntime>}
+ */
+export function loadRuntimesCatalogue(path) {
+  const resolved = resolve(path);
+  /** @type {unknown} */
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(resolved, "utf8"));
+  } catch (error) {
+    throw new Error(`--runtimes ${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`--runtimes ${path} must be a JSON object`);
+  /** @type {Record<string, import("../contract/index.mjs").ValidatedRuntime>} */
+  const runtimes = {};
+  for (const [id, runtime] of Object.entries(raw)) runtimes[id] = validateRuntime(id, runtime);
+  return runtimes;
+}
+
+/**
+ * @param {string} target
+ * @param {{campaign?: string, phase?: string, "review-rounds"?: string, "approve-below"?: string, "runtime-defaults"?: string, runtimes?: string, detach?: boolean, json?: boolean}} values
+ * @returns {Promise<void>}
+ */
+export async function planCli(target, values) {
+  const specPath = resolve(target);
+  if (typeof values.campaign !== "string" || !values.campaign) throw new Error("plan requires --campaign <id>");
+  const campaignId = values.campaign;
+  const phase = typeof values.phase === "string" && values.phase ? values.phase : "default";
+  const reviewRounds = reviewRoundsOf(values["review-rounds"]);
+  const approveBelow = /** @type {"standard"|"high"|"none"|undefined} */ (values["approve-below"]);
+  const runtimeDefaults = parseRuntimeDefaults(values["runtime-defaults"]);
+  const runtimes = typeof values.runtimes === "string" && values.runtimes
+    ? loadRuntimesCatalogue(values.runtimes)
+    : DISCOVERY_RUNTIME_DEFINITIONS;
+
+  if (values.detach === true) {
+    const argv = ["plan", specPath, "--campaign", campaignId, "--phase", phase, "--review-rounds", String(reviewRounds)];
+    if (approveBelow !== undefined) argv.push("--approve-below", approveBelow);
+    if (values["runtime-defaults"] !== undefined) argv.push("--runtime-defaults", values["runtime-defaults"]);
+    if (typeof values.runtimes === "string" && values.runtimes) argv.push("--runtimes", resolve(values.runtimes));
+    const child = detachArgv(argv);
+    if (child.pid === undefined) throw new Error("detached plan has no pid");
+    process.stdout.write(`[plan] detached · pid ${child.pid} · ${specPath}\n`);
+    return;
+  }
+
+  const result = await runPlanningPipeline({
+    specPath,
+    campaignId,
+    phase,
+    reviewRounds,
+    approveBelow,
+    runtimeDefaults,
+    runtimes,
+    launch: async (contractPath, contract) => {
+      const child = detachSelf("run", contractPath);
+      if (child.pid === undefined) throw new Error("detached planning run has no pid");
+      await waitForBootstrap(join(contract.cwd, ".runs", contract.id), child.pid, child);
+    },
+    wait: async (runDir) => {
+      for (;;) {
+        const progress = runProgress(runDir);
+        const classification = classifyRunProgress(progress);
+        if (classification !== "unfinished" && classification !== "waiting") return progress;
+        await delay(DEFAULT_POLL_MS);
+      }
+    },
+  });
+
+  if (values.json === true) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+  if (result.status === "contested") {
+    process.stdout.write(`[plan] ${campaignId} phase ${phase} contested after ${result.round} round(s) · ${result.findings.length} finding(s) · ${result.planPath}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`[plan] ${campaignId} phase ${phase} frozen · approved ${result.approved} · ${result.contractPath}\n`);
+}

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,8 @@ 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 { planCli } from "./cli/plan.mjs";
 import { METRICS_OPTIONS, renderCampaignMetrics } from "./campaign/metrics.mjs";
 import { runContract } from "./engine/scheduler.mjs";
 import { resumeRun } from "./engine/resume.mjs";
@@ -105,6 +107,16 @@ export const COMMAND_OPTIONS = {
   setup: { yes: { type: "boolean" }, harnesses: { type: "string" }, worker: { type: "string" }, judge: { type: "string" }, "no-skill": { type: "boolean" }, json: { type: "boolean" } },
   init: { cwd: { type: "string" }, yes: { type: "boolean" }, "no-skill": { type: "boolean" }, agentkit: { type: "boolean" }, greenfield: { type: "boolean" }, stable: { type: "boolean" }, json: { type: "boolean" } },
   metrics: METRICS_OPTIONS,
+  plan: {
+    campaign: { type: "string" },
+    phase: { type: "string" },
+    "review-rounds": { type: "string" },
+    "approve-below": { type: "string" },
+    "runtime-defaults": { type: "string" },
+    runtimes: { type: "string" },
+    detach: { type: "boolean" },
+    json: { type: "boolean" },
+  },
 };
 
 /**
@@ -209,6 +221,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;
@@ -419,6 +432,10 @@ async function main(argv) {
   }
   if (command === "metrics") { process.stdout.write(renderCampaignMetrics(target, values)); return; }
   if (command === "findings") { process.stdout.write(renderFindings(resolve(target))); return; }
+  if (command === "plan") {
+    await planCli(target, /** @type {Parameters<typeof planCli>[1]} */ (values));
+    return;
+  }
   if (command === "validate") { validateContractFile(resolve(target)); return; }
   usage();
 }

package/src/contract/task-packet.mjs

@@ -432,7 +432,7 @@ function renderDiscoveryPrompt(packet, nodeId) {
     ...bulletOrNone(packet.nonGoals),
     "",
     "## Required output",
-    'Return exactly one worker-result JSON object, with no markdown or prose. Set status to "done", missingContext to [], and artifacts to an array containing exactly one JSON-stringified execution task packet with every required taskPacket field. The packet readFiles and writeFiles must be non-empty and scoped to this repository.',
+    'Return exactly one worker-result JSON object, with no markdown or prose. Set status to "done", missingContext to [], and artifacts to an array containing exactly one JSON-stringified execution task packet with every required taskPacket field. The packet readFiles and writeFiles must be non-empty and scoped to this repository. Put structured findings meant to inform that packet in `output` (a JSON object, at most 65536 bytes); prose belongs in `summary`.',
     "",
     "## Verification",
     VERIFICATION_PARAGRAPH,