doctrina-cli 0.14.0 → 0.15.0

package/src/commands/verify.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,46 @@ 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.
+    // A check that declares OUTPUT EXPECTATIONS must have its output read,
+    // so it runs piped and is echoed straight through — the operator still
+    // sees everything, just at the end of the check rather than streaming.
+    // Only checks that opt in pay that cost.
+    const expectation = parseExpectation(ch);
     const res = spawnSync(ch.run, {
       cwd: ch.cwd ? path.resolve(projectRoot, ch.cwd) : projectRoot,
       shell: true,
-      stdio: "inherit",
+      stdio: expectation ? "pipe" : "inherit",
+      encoding: expectation ? "utf8" : undefined,
+      // A suite's output can be large; the default 1MB cap would truncate
+      // the very line an expectation is looking for.
+      maxBuffer: expectation ? 64 * 1024 * 1024 : undefined,
     });
-    const ok = !res.error && res.status === 0;
+    if (expectation) {
+      if (res.stdout) process.stdout.write(res.stdout);
+      if (res.stderr) process.stderr.write(res.stderr);
+    }
+
+    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.
+      const 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 +266,47 @@ export async function run(_positional, flags) {
   return 1;
 }
 
+// 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 +464,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. A check with an "expect"
+block runs piped (its output is echoed through when it finishes, rather
+than streaming); every other check still streams. 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,13 @@ 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 = {
+  "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.",

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;
+}