doctrina-cli 0.14.0 → 0.15.1

package/src/commands/verify.js

@@ -2,7 +2,7 @@
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { exists, isDir, isFile, read, write, relPath } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { today } from "../lib/dates.js";
@@ -25,7 +25,10 @@ const STARTER = {
     "doctrina verify runs each check below, in order, through your shell. " +
     "Replace the example with your real typecheck/test/build commands. A " +
     "non-zero exit fails the gate. This file is the project's executable " +
-    "definition of 'the code actually works'.",
+    "definition of 'the code actually works'. A check may add an \"expect\" " +
+    "block — {\"fail_if_output_matches\": \"<regex>\"} and/or " +
+    "{\"require_output_matches\": \"<regex>\"} — so that a run which exits 0 " +
+    "having executed NOTHING fails the gate instead of passing it.",
   checks: [
     { name: "example", run: "exit 1" },
   ],
@@ -99,6 +102,15 @@ export async function run(_positional, flags) {
       console.error(c.red("error:") + ` every check in ${CONFIG_REL} needs a non-empty "run" string (or "type": "manual")`);
       return 1;
     }
+    // An uncompilable expectation must fail LOUDLY at config time. Skipping
+    // it would leave a check that looks fail-closed and is not — the
+    // failure mode this whole feature exists to remove.
+    try {
+      parseExpectation(ch);
+    } catch (err) {
+      console.error(c.red("error:") + ` check "${ch.name ?? "?"}" declares an "expect" pattern that is not a valid regular expression: ${err.message}`);
+      return EXIT.USAGE;
+    }
   }
   if (checks.length === 0) {
     console.error(c.red("error:") + ` ${CONFIG_REL} declares zero checks — a verify gate with no checks proves nothing`);
@@ -141,6 +153,15 @@ export async function run(_positional, flags) {
     checks.forEach((ch, i) => {
       const what = ch.type === "manual" ? c.gray(`manual${ch.rubric ? " — " + ch.rubric : ""}`) : c.gray(ch.run);
       console.log(`  ${i + 1}. ${c.cyan((ch.name ?? "check").padEnd(16))} ${what}`);
+      // A fail-closed check must be visible as one: a reader auditing the
+      // gate needs to see which checks judge their own output.
+      const exp = parseExpectation(ch);
+      if (exp) {
+        const parts = [];
+        if (exp.failIfSource) parts.push(`fail if output matches /${exp.failIfSource}/`);
+        if (exp.requireSource) parts.push(`require output matches /${exp.requireSource}/`);
+        console.log(`     ${" ".repeat(16)} ${c.gray(parts.join("; "))}`);
+      }
     });
     return 0;
   }
@@ -177,14 +198,44 @@ export async function run(_positional, flags) {
     // monorepo target a sub-package, e.g. { run: "node --test", cwd:
     // "packages/api" } — the multi-service shape the contract artifact
     // also serves.
-    const res = spawnSync(ch.run, {
-      cwd: ch.cwd ? path.resolve(projectRoot, ch.cwd) : projectRoot,
-      shell: true,
-      stdio: "inherit",
-    });
-    const ok = !res.error && res.status === 0;
+    // A check that declares OUTPUT EXPECTATIONS must have its output READ,
+    // which is not the same as withholding it. The first cut ran such a
+    // check piped and echoed the whole buffer at the end — forty seconds of
+    // blank terminal on this project's own suite, and worse on anything
+    // slower. Reading and showing are independent: the tee streams every
+    // chunk as it arrives AND accumulates it for the match.
+    const expectation = parseExpectation(ch);
+    const res = expectation
+      ? await runTee(ch.run, ch.cwd ? path.resolve(projectRoot, ch.cwd) : projectRoot)
+      : spawnSync(ch.run, {
+        cwd: ch.cwd ? path.resolve(projectRoot, ch.cwd) : projectRoot,
+        shell: true,
+        stdio: "inherit",
+      });
+
+    let ok = !res.error && res.status === 0;
+    /** @type {string | null} */
+    let expectationNote = null;
+    if (ok && expectation) {
+      // THE FAIL-CLOSED RULE. A green exit code answers "did the runner
+      // crash", never "did the runner do anything". A suite whose filter
+      // matched nothing prints "0 scenarios" and exits 0, and every gate
+      // above this one calls that a pass. An expectation makes the run's
+      // own output part of the verdict.
+      // The tee already interleaves both streams in the order they arrived,
+      // which is the order a human read them in.
+      const output = res.output ?? `${res.stdout ?? ""}\n${res.stderr ?? ""}`;
+      const verdict = judgeOutput(expectation, output);
+      if (!verdict.ok) {
+        ok = false;
+        expectationNote = verdict.reason;
+      }
+    }
+
     if (res.error) {
       console.log(c.red(`✗ ${name}`) + c.gray(` — could not run: ${res.error.message}`));
+    } else if (expectationNote) {
+      console.log(c.red(`✗ ${name}`) + c.gray(` — exit 0, but ${expectationNote}`));
     } else {
       console.log(ok ? c.green(`✓ ${name}`) : c.red(`✗ ${name} (exit ${res.status})`));
     }
@@ -213,6 +264,88 @@ export async function run(_positional, flags) {
   return 1;
 }
 
+// Run a command, streaming its output to the terminal AS IT ARRIVES while
+// accumulating a copy for an expectation to match against.
+//
+// `spawnSync` cannot do this: it either inherits the streams (visible,
+// unreadable) or pipes them (readable, invisible until it exits). The async
+// spawn gives both, at the cost of this function existing.
+//
+// Both streams accumulate into ONE buffer in arrival order, so a pattern
+// spanning them matches the same text the operator saw, and stderr is
+// echoed to stderr so redirection still behaves.
+//
+// @returns {Promise<{status: number|null, output: string, error?: Error}>}
+function runTee(command, cwd) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, { cwd, shell: true, stdio: ["inherit", "pipe", "pipe"] });
+    } catch (err) {
+      resolve({ status: null, output: "", error: /** @type {Error} */ (err) });
+      return;
+    }
+
+    let output = "";
+    const tee = (stream, sink) => {
+      if (!stream) return;
+      stream.setEncoding("utf8");
+      stream.on("data", (chunk) => {
+        output += chunk;
+        sink.write(chunk);
+      });
+    };
+    tee(child.stdout, process.stdout);
+    tee(child.stderr, process.stderr);
+
+    child.on("error", (err) => resolve({ status: null, output, error: err }));
+    // "close" rather than "exit": it fires once the streams are drained, so
+    // no trailing output is dropped from the match or the terminal.
+    child.on("close", (status) => resolve({ status, output }));
+  });
+}
+
+// An `expect` block, normalised and compiled, or null when the check does
+// not declare one. Runner-agnostic by construction: Doctrina supplies no
+// patterns of its own and knows nothing about what the output means — the
+// project declares the line that proves its run was real.
+//
+//   "expect": {
+//     "fail_if_output_matches": "0 scenarios|0 features",
+//     "require_output_matches": "\\d+ scenarios? passed"
+//   }
+export function parseExpectation(check) {
+  const raw = check?.expect;
+  if (!raw || typeof raw !== "object") return null;
+  const out = {};
+  if (typeof raw.fail_if_output_matches === "string" && raw.fail_if_output_matches !== "") {
+    out.failIf = new RegExp(raw.fail_if_output_matches, "im");
+    out.failIfSource = raw.fail_if_output_matches;
+  }
+  if (typeof raw.require_output_matches === "string" && raw.require_output_matches !== "") {
+    out.requireMatch = new RegExp(raw.require_output_matches, "im");
+    out.requireSource = raw.require_output_matches;
+  }
+  return out.failIf || out.requireMatch ? out : null;
+}
+
+/** @returns {{ok: boolean, reason?: string}} */
+export function judgeOutput(expectation, output) {
+  if (expectation.failIf && expectation.failIf.test(output)) {
+    return {
+      ok: false,
+      reason: `its output matched /${expectation.failIfSource}/ — the check declares that shape a failure (a run that executed nothing exits 0 too)`,
+    };
+  }
+  if (expectation.requireMatch && !expectation.requireMatch.test(output)) {
+    return {
+      ok: false,
+      reason: `its output never matched /${expectation.requireSource}/ — the check requires that proof of a real run`,
+    };
+  }
+  return { ok: true };
+}
+
 // Static reproducibility lint: walk the project's package.json files and
 // report the two "works on my machine" footguns the review hit — a package
 // whose entry points live in a build-output dir with nothing that builds it
@@ -370,6 +503,23 @@ A manual check passes when it has been signed off and is otherwise reported
 as "pending" — non-blocking by default, failing only under --strict (so CI
 can require the sign-off). Sign-offs are stored in ${SIGNOFF_REL}.
 
+OUTPUT EXPECTATIONS — fail-closed on a run that did nothing. An exit code
+answers "did the runner crash", never "did the runner run anything": a suite
+whose filter matched no cases prints "0 scenarios" and exits 0, and every
+gate calls it a pass. Add an "expect" block to make the output part of the
+verdict:
+
+      { "name": "e2e", "run": "behave --tags @smoke",
+        "expect": { "fail_if_output_matches": "0 scenarios",
+                    "require_output_matches": "\\\\d+ scenarios? passed" } }
+
+Doctrina supplies no patterns of its own and knows nothing about what the
+output means — the project declares the line that proves its run was real,
+so this works for any runner in any language. An expect-carrying check
+still streams: its output is teed to the terminal as it arrives while a
+copy accumulates for the match. An "expect" pattern that is not a valid
+regular expression fails at config time, not silently.
+
 Flags:
   --init     Scaffold a starter ${CONFIG_REL} (refuses to overwrite without --force)
   --list     Print the configured checks without running them

package/src/commands/work.js

@@ -9,8 +9,9 @@ import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
 import { assessBrief } from "../lib/clarity.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 import { changeNew } from "./change.js";
+import { classify } from "./triage.js";
 
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
 // prompt ("add login") becomes a fully scaffolded change plus a playbook
@@ -72,6 +73,31 @@ export async function run(positional, flags) {
     }
   }
 
+  // LANE CHECK (change 0029). `work` was the default answer to every
+  // request, so a broken workflow or a suite that ran nothing became a
+  // change with a proposal, tasks and a spec delta — ceremony spent on a
+  // diagnosis, and a close that attested to nothing. A runtime-shaped
+  // prompt is stopped here, once, with the diagnosis path named. It is a
+  // deterministic term match and it can be wrong, so --force proceeds and
+  // the message says so.
+  if (!fromDiff && !chore && !flagBool(flags, "force", false)) {
+    const verdict = classify(prompt);
+    if (verdict.lane === "runtime" && verdict.confident) {
+      console.error(c.yellow("hold:") + " this reads as a RUNTIME problem, not a change of behaviour");
+      console.error(c.gray(`signals: ${[...new Set(verdict.scores.runtime.hits)].slice(0, 6).join(", ")}`));
+      console.error("");
+      console.error("Nothing here says the spec is wrong — diagnose the running system first:");
+      console.error(`  ${c.cyan(`doctrina triage "${prompt.length > 60 ? `${prompt.slice(0, 59)}…` : prompt}"`)}`);
+      console.error("");
+      console.error(c.gray("If the requirement really is missing, open the change anyway:"));
+      console.error(c.gray("  doctrina work --force \"<prompt>\"   ·   or --chore for wiring already specified"));
+      // PRECONDITION: the work may be perfectly valid; this project has
+      // simply not been diagnosed yet. A gate code (1) would read as
+      // "the prompt is bad" and invite rewording it forever.
+      return EXIT.PRECONDITION;
+    }
+  }
+
   const pinned = flagString(flags, "capability");
   if (pinned && !/^[a-z][a-z0-9-]*$/.test(pinned)) {
     console.error(c.red("error:") + ` invalid capability "${pinned}" (lowercase letters, digits, hyphens)`);
@@ -545,6 +571,14 @@ Options:
                        prompt needed) and print a code-first playbook (F8)
   --chore, --no-spec   Open a spec-less chore change (infra/docs/build) with a
                        playbook that skips the spec-delta steps (F9)
-  --force              Open a new change even when one is open, and overwrite
-                       an existing change folder
+  --force              Open a new change even when one is open, overwrite an
+                       existing change folder, and proceed past the lane hold
+                       below
+
+A prompt that reads as a RUNTIME problem — a workflow, an env value, a run
+that executed nothing — is HELD before anything is scaffolded, and pointed
+at \`doctrina triage\` instead (exit 3: a precondition, not a bad prompt).
+The classifier is deterministic term matching and can be wrong; --force
+opens the change anyway, and --chore is the lane for wiring the spec
+already covers.
 `;

package/src/index.js

@@ -47,6 +47,7 @@ import * as completion from "./commands/completion.js";
 import * as intent from "./commands/intent.js";
 import * as upgrade from "./commands/upgrade.js";
 import * as adapter from "./commands/adapter.js";
+import * as triage from "./commands/triage.js";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
@@ -54,7 +55,7 @@ const COMMANDS = {
   intake, work, coverage, verify, contract, trace,
   status, close, review, watch, why, constitution,
   prime, handoff, show, doctor, report, completion,
-  intent, upgrade, adapter,
+  intent, upgrade, adapter, triage,
 };
 
 const TOP_HELP = `

package/src/lib/commands.js

@@ -12,7 +12,7 @@
 // Keep this sorted by the workflow order used in `--help`, not alphabetically.
 export const COMMAND_NAMES = [
   // bootstrap / day-to-day
-  "init", "intake", "work",
+  "init", "intake", "triage", "work",
   // authoring
   "spec", "change", "contract", "decision", "skill", "intent", "adapter",
   // read / orient
@@ -36,6 +36,7 @@ export const COMMAND_NAMES = [
 export const OPERATIONS = [
   ["init", "Scaffold AGENTS.md and .doctrina/ in the current directory"],
   ["intake", "Store the full project description; print the bootstrap playbook"],
+  ["triage", "Classify a request into a lane, and check the runtime surface"],
   ["work", "Brief prompt -> scaffolded change + guided work playbook"],
   ["spec new", "Create a new capability spec (--bug for bug-shape)"],
   ["spec list", "List specs with version, status, and size"],
@@ -127,7 +128,8 @@ export const COMMAND_META = {
   constitution: { moment: "Orient",     when: "you need the standing rules before deciding something", purpose: "accepted ADRs and product non-goals" },
   handoff:      { moment: "Orient",     when: "BEFORE compaction or handing over to another session", purpose: "a resume note: open work, task state, next command" },
 
-  work:         { moment: "Change",     when: "any request arrives that changes behaviour", purpose: "scaffold a change and print the playbook to execute" },
+  triage:       { moment: "Change",     when: "a request arrives — BEFORE scaffolding, especially if it smells like an incident", purpose: "classify the lane (product/runtime/chore) and check the declared runtime surface" },
+  work:         { moment: "Change",     when: "a request arrives that changes behaviour (triage says PRODUCT)", purpose: "scaffold a change and print the playbook to execute" },
   spec:         { moment: "Change",     when: "a capability needs creating or its headers advancing", purpose: "create, list, and edit capability specs" },
   change:       { moment: "Change",     when: "driving a change through its lifecycle by hand", purpose: "new / apply / archive / check / tick / diff / abandon" },
   decision:     { moment: "Change",     when: "the change decides something a later session must not relitigate", purpose: "record, accept, land, scope, and supersede ADRs" },
@@ -232,9 +234,12 @@ export function surfaceMarkdown() {
   const lines = [
     "## Doctrina command surface (generated — reach for these, don't hand-author)",
     "",
+    // Two lines, not three. This block is always-loaded context inside a
+    // file with a hard 150-line budget, so its own preamble competes with
+    // the commands it introduces — and a command an agent never discovers
+    // costs more than a sentence of prose ever saves.
     "Every command, with the moment you reach for it. The CLI scaffolds from",
-    "canonical templates and keeps `index.json` in sync — prefer it over",
-    "hand-authoring. Flags and detail: `doctrina <command> --help`.",
+    "canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.",
   ];
   for (const moment of MOMENTS) {
     const cmds = COMMAND_NAMES.filter((n) => COMMAND_META[n]?.moment === moment);
@@ -397,6 +402,19 @@ export const AGENT_CHANGELOG_END = "<!-- doctrina:changed:end -->";
 // introduced it. Only entries that alter what an agent should DO belong
 // here — a bug fix nobody's behaviour depends on does not.
 export const AGENT_CHANGELOG = {
+  // Each entry lists only ITS OWN delta. The series carries the rest
+  // forward (see agentChangelogEntries), so a patch never has to restate
+  // the minor that introduced the commands, and never silently erases it.
+  "0.15.1": [
+    "Exporting a variable under a name that is not its source's is routine — declare it in the Wiring row's Origin cell as `<origin>:<source>` (e.g. `secrets:NPM_TOKEN`) and RT02 stays silent until either side moves.",
+  ],
+  "0.15.0": [
+    "`doctrina triage \"<prompt>\"` — classify a request as PRODUCT / RUNTIME / CHORE BEFORE scaffolding. `work` now holds a runtime-shaped prompt with exit 3 and points here; `--force` opens the change anyway.",
+    "`contract check` now holds the declared wiring to the implementation: a `vars`/`secrets` variable no workflow exports, a default an empty CI value never triggers, an unvalidated enum, a selector matching zero targets (RT01-RT05).",
+    "A `verify` check may declare `expect`, so a run that exits 0 having executed NOTHING fails the gate; an `[orchestration]` acceptance criterion is proven by citing such a guarded check (`verify:<name>`), not by a citation that merely resolves.",
+    "A spec may declare an ordered `### Pipeline`; `validate` refuses a step that requires what a later step produces. `validate --runtime` adds the runtime gate.",
+    "`skill suggest --from-error <text|file>` drafts a skill from the failure on screen; `context --for` now ranks skills by their trigger.",
+  ],
   "0.14.0": [
     "`doctrina adapter add|remove|list` — add an agent without re-scaffolding; `init --force` no longer overwrites authored AGENTS.md/product.md.",
     "`doctrina change apply` now refuses what `analyze` refuses; `change check` previews a close, `change tick` checks boxes in bulk.",
@@ -408,9 +426,54 @@ export const AGENT_CHANGELOG = {
 
 // The block written into AGENTS.md for a given version. Empty string when
 // that version has no agent-visible changes.
+// How many bullets the block may carry. Not a style preference: AGENTS.md
+// is always-loaded context under a hard 150-line budget, and at the current
+// template size five bullets is exactly what fits. Raising this means
+// cutting elsewhere — see the `agents-md-lines` budget in the contract.
+export const AGENT_CHANGELOG_MAX_BULLETS = 5;
+
+/**
+ * The bullets an agent arriving at `version` needs, newest first.
+ *
+ * Keyed per version, but rendered per MINOR SERIES. The block REPLACES its
+ * predecessor in AGENTS.md rather than accumulating, so rendering only the
+ * current version's own entry meant every patch silently erased the minor
+ * that introduced the commands: an agent upgrading 0.14.0 -> 0.15.1 would
+ * read one bug fix and never learn `triage` exists. The alternative —
+ * making each patch author restate the whole minor by hand — worked once
+ * and does not scale, because the restating is invisible and the third
+ * patch quietly drops a line to fit the cap.
+ *
+ * So the series carries itself, newest first, and the cap truncates the
+ * OLDEST. A fact that must outlive its series does not belong here: it
+ * belongs in the surface block or the docs, which is the honest place for
+ * something permanent.
+ */
+export function agentChangelogEntries(version) {
+  const series = String(version).split(".").slice(0, 2).join(".");
+  const versions = Object.keys(AGENT_CHANGELOG)
+    .filter((v) => v.split(".").slice(0, 2).join(".") === series && compareVersions(v, version) <= 0)
+    .sort((a, b) => compareVersions(b, a));
+  const out = [];
+  for (const v of versions) out.push(...(AGENT_CHANGELOG[v] ?? []));
+  return out.slice(0, AGENT_CHANGELOG_MAX_BULLETS);
+}
+
+// Numeric semver comparison — "0.15.10" must sort above "0.15.9", which a
+// string compare gets wrong.
+function compareVersions(a, b) {
+  const pa = String(a).split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => Number.parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
 export function agentChangelogMarkdown(version) {
-  const entries = AGENT_CHANGELOG[version];
-  if (!entries || entries.length === 0) return "";
+  const entries = agentChangelogEntries(version);
+  if (entries.length === 0) return "";
   return [
     `## What changed in ${version}`,
     "",

package/src/lib/gates.js

@@ -34,6 +34,28 @@ export const GATES = {
     },
   },
 
+  // Integrity: the subset of the structural questions that are true at
+  // EVERY point in a change's life — the proposal says why and what, the
+  // tasks are real, the deltas parse. Everything `structure` asks except
+  // the handful that only mean something before an apply.
+  //
+  // This exists because excluding `structure` wholesale from `archive` (to
+  // dodge the post-apply false positive documented below) also excluded the
+  // hollow-proposal check, which has no such problem. A change could then be
+  // archived — and stamped "applied" — with `## What` still holding nothing
+  // but its scaffold comment, after `apply` had refused it for exactly that.
+  // Observed on change 0030 of this repository, one release after the
+  // history recorded six hollow proposals reaching the archive.
+  integrity: {
+    label: "integrity",
+    rerun: (id) => `doctrina analyze ${id}`,
+    blockers(projectRoot, changeDir) {
+      return collectAnalysis(projectRoot, changeDir)
+        .filter((r) => r.kind === "fail" && r.scope !== "pre-apply")
+        .map((r) => stripAnsi(r.line).replace(/^✗\s*/, "").trim());
+    },
+  },
+
   // Verification: the work is claimed complete. Every checkbox in
   // tasks.md (closing steps included) and in the proposal's
   // "## Verification" section.
@@ -72,9 +94,15 @@ export const GATES = {
 // content the delta just wrote, so re-asking at archive time reports a
 // conflict that is the proof the apply worked. A gate must be asked at the
 // point its question is meaningful.
+//
+// `archive` therefore requires INTEGRITY — that same structural question
+// set minus the pre-apply-only checks — rather than nothing structural at
+// all. Excluding the whole gate to dodge three checks also excluded the
+// hollow-proposal check, and a change refused by `apply` for an unwritten
+// `## What` could still be archived and stamped "applied".
 export const TRANSITIONS = {
   apply: { label: "change apply", gates: ["structure"] },
-  archive: { label: "change archive", gates: ["verification"] },
+  archive: { label: "change archive", gates: ["integrity", "verification"] },
 };
 
 // Evaluate a transition's gates. Returns { ok, blockers, gates } where

package/src/lib/pipeline.js

@@ -0,0 +1,161 @@
+// @ts-check
+import { getSection } from "./doc-model.js";
+
+// ORDERED requirements: what EARS cannot say.
+//
+// EARS event-driven requirements are individually true and mutually
+// unordered. "When the run finishes, the system shall append a summary" and
+// "When the analysis completes, the system shall publish the dashboard" both
+// pass every gate, and neither says the dashboard needs the analysis to have
+// run first. So "the dashboard includes this run's analysis" gets read as
+// "call the renderer at the end" without anyone checking whether the thing
+// it renders exists yet — and the failure is a published dashboard that is
+// silently one run stale, which no structural check can see.
+//
+// A Pipeline block states the order and the artifact each step hands on:
+//
+//   ### Pipeline
+//
+//   1. run-suite — produces `reports/results.json`
+//   2. analyse — requires `reports/results.json`, produces `reports/analysis.md`
+//   3. publish — requires `reports/analysis.md`
+//
+// The invariant is the one an ordered list cannot enforce on its own: a step
+// may only require what an EARLIER step produced. Requiring something a
+// later step produces is the inversion; requiring something no step produces
+// is the missing producer. Both are errors, and both are exactly the bug
+// that ships as "green, and a run behind".
+//
+// Artifacts that genuinely come from outside are marked `(external)`.
+
+/**
+ * @typedef {object} PipelineStep
+ * @property {number} number    The declared ordinal.
+ * @property {string} name
+ * @property {string[]} requires
+ * @property {string[]} produces
+ * @property {string[]} external  Requirements declared as coming from outside.
+ * @property {number} line        1-based line within the spec.
+ */
+
+/**
+ * Parse the `### Pipeline` block of a spec. Returns null when the spec
+ * declares none — the block is opt-in, so every spec written before it
+ * existed parses to null and is never checked.
+ *
+ * @returns {PipelineStep[] | null}
+ */
+export function parsePipeline(text) {
+  const section = getSection(text, "Pipeline", { level: 3 });
+  if (!section || !section.trim()) return null;
+
+  const all = String(text).split(/\r?\n/);
+  const offset = all.findIndex((l) => /^###\s+Pipeline\s*$/.test(l));
+
+  const steps = [];
+  const lines = section.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\s*(\d+)\.\s+(.*\S)\s*$/);
+    if (!m) continue;
+    const number = Number.parseInt(m[1], 10);
+    const body = m[2];
+
+    // The step name is everything up to the first clause separator.
+    const name = body.split(/\s+[—-]\s+|\s*,\s*(?=requires|produces)/)[0].trim();
+
+    steps.push({
+      number,
+      name,
+      requires: clause(body, "requires").filter((a) => !a.external).map((a) => a.name),
+      external: clause(body, "requires").filter((a) => a.external).map((a) => a.name),
+      produces: clause(body, "produces").map((a) => a.name),
+      line: offset >= 0 ? offset + 1 + i + 1 : i + 1,
+    });
+  }
+  return steps;
+}
+
+// The artifacts named by one clause: `requires \`a\`, \`b\` (external)`.
+// Backticks are how a spec already marks a path, so they are the anchor.
+function clause(body, keyword) {
+  const re = new RegExp(`${keyword}\\s+([^;]*?)(?=(?:\\brequires\\b|\\bproduces\\b|$))`, "i");
+  const m = body.match(re);
+  if (!m) return [];
+  const out = [];
+  for (const artifact of m[1].matchAll(/`([^`]+)`(\s*\(external\))?/g)) {
+    out.push({ name: artifact[1].trim(), external: Boolean(artifact[2]) });
+  }
+  return out;
+}
+
+/**
+ * Check the ordering invariant.
+ * @param {PipelineStep[]} steps
+ * @returns {Array<{code: string, level: "error"|"warn", message: string, remedy: string, line: number}>}
+ */
+export function checkPipeline(steps) {
+  /** @type {Array<{code: string, level: "error"|"warn", message: string, remedy: string, line: number}>} */
+  const findings = [];
+  if (!steps || steps.length === 0) return findings;
+
+  // Numbering first: an out-of-order list is not a pipeline, and every
+  // check below reads the declared order as the real one.
+  for (let i = 0; i < steps.length; i++) {
+    if (steps[i].number !== i + 1) {
+      findings.push({
+        code: "PL01",
+        level: "error",
+        message: `pipeline step ${i + 1} is numbered ${steps[i].number} ("${steps[i].name}") — the order a pipeline declares must be the order it reads in`,
+        remedy: "renumber the Pipeline steps 1..n in execution order",
+        line: steps[i].line,
+      });
+    }
+  }
+
+  // Everything produced at or before each index, which is what "earlier"
+  // means. Built as we walk, so a step can never satisfy itself.
+  const producedBefore = new Set();
+  const producedBy = new Map();
+  for (const step of steps) {
+    for (const artifact of step.produces) {
+      if (!producedBy.has(artifact)) producedBy.set(artifact, step);
+    }
+  }
+
+  for (const step of steps) {
+    for (const artifact of step.requires) {
+      if (producedBefore.has(artifact)) continue;
+
+      const producer = producedBy.get(artifact);
+      if (producer && producer.number > step.number) {
+        // The inversion: the consumer runs first and reads last run's file.
+        findings.push({
+          code: "PL02",
+          level: "error",
+          message: `step ${step.number} ("${step.name}") requires \`${artifact}\`, which step ${producer.number} ("${producer.name}") produces LATER — this step can only ever read the previous run's copy`,
+          remedy: `move "${producer.name}" before "${step.name}", or make the dependency explicit and drop the requirement`,
+          line: step.line,
+        });
+      } else if (producer && producer.number === step.number) {
+        findings.push({
+          code: "PL02",
+          level: "error",
+          message: `step ${step.number} ("${step.name}") both requires and produces \`${artifact}\``,
+          remedy: `split the step, or mark the input \`${artifact}\` (external) if it comes from outside the pipeline`,
+          line: step.line,
+        });
+      } else {
+        findings.push({
+          code: "PL03",
+          level: "error",
+          message: `step ${step.number} ("${step.name}") requires \`${artifact}\`, which no step produces — the step runs against a file nothing in this pipeline creates`,
+          remedy: `add the producing step, or mark it \`${artifact}\` (external) to declare it comes from outside`,
+          line: step.line,
+        });
+      }
+    }
+    for (const artifact of step.produces) producedBefore.add(artifact);
+  }
+
+  return findings;
+}