doctrina-cli 0.14.0 → 0.15.0

package/src/commands/skill.js

@@ -7,7 +7,7 @@ import { exists, isDir, isFile, mkdirp, read, relPath, walk, write } from "../li
 import { readTemplate, locateTemplatesDir, substitute } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
-import { flagBool, flagString } from "../lib/args.js";
+import { flagBool, flagString, flagGivenWithoutValue } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
@@ -17,7 +17,7 @@ const SUBCOMMANDS = ["new", "list", "sync", "suggest"];
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
 // let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json", "force", "write"], string: ["since"] };
+export const flags = { boolean: ["json", "force", "write"], string: ["since", "from-error"] };
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -61,12 +61,187 @@ const FIX_SHAPED_SUBJECT =
 const GIT_LOG_LIMIT = 200;
 const MAX_SHOWN = 20;
 
+// A skill drafted from the ERROR that taught the lesson (change 0029).
+//
+// `suggest` used to fire only after the fact — a skill was born when the
+// agent remembered to write one, which is to say after the incident had
+// already cost a session. The moment the lesson actually exists is the
+// moment the error is on screen, and that text carries exactly what a
+// trigger needs: the paths, the identifiers, the message itself.
+//
+// The draft is a SEED, not a skill. It fills the trigger — the field a
+// human is least likely to write in a matchable form — and leaves the
+// procedure to the person who just solved it.
+const ERROR_STOP = new Set([
+  "the", "and", "for", "with", "that", "this", "from", "have", "has", "was",
+  "were", "not", "but", "you", "your", "are", "its", "it's", "can", "could",
+  "would", "should", "will", "when", "then", "than", "there", "their", "been",
+  "error", "warning", "failed", "failure", "exception", "traceback", "at",
+  "line", "file", "in", "on", "of", "to", "is", "a", "an", "no", "if",
+  // Stack-trace furniture and modal verbs: present in almost every error,
+  // distinctive in none, and they crowd out the words that identify one.
+  "most", "recent", "call", "calls", "last", "raise", "raised", "throw",
+  "thrown", "must", "one", "none", "self", "return", "returns", "def",
+  "module", "stack", "trace", "during", "handling", "above", "occurred",
+  "caused", "unexpected", "invalid", "expected", "got", "value", "values",
+]);
+
+export function draftFromError(text) {
+  const raw = String(text ?? "").trim();
+  if (raw === "") return null;
+
+  // Paths and file references: the most matchable thing an error carries.
+  const paths = [...new Set(
+    (raw.match(/[\w.@-]+(?:[/\\][\w.@-]+)+(?:\.\w{1,6})?|[\w-]+\.(?:py|js|mjs|cjs|ts|tsx|yml|yaml|json|feature|go|rb|java|rs|sh|toml|ini|env)\b/g) ?? [])
+      .map((p) => p.replace(/[.,;:)\]]+$/, "")),
+  )].slice(0, 4);
+
+  // ALL_CAPS identifiers: env vars, error codes, constants.
+  const identifiers = [...new Set(raw.match(/\b[A-Z][A-Z0-9_]{2,}\b/g) ?? [])].slice(0, 4);
+
+  // Quoted fragments are usually the operative part of the message — but a
+  // traceback quotes its own filenames, and repeating a path already
+  // captured above buys nothing.
+  const quoted = [...new Set(
+    [...raw.matchAll(/["'`]([^"'`\n]{4,60})["'`]/g)].map((m) => m[1].trim()),
+  )].filter((q) => !paths.includes(q)).slice(0, 2);
+
+  // Distinctive words, most frequent first — the fallback when an error
+  // carries no structure at all.
+  const counts = new Map();
+  for (const w of raw.toLowerCase().match(/[a-z][a-z0-9_-]{3,}/g) ?? []) {
+    if (ERROR_STOP.has(w)) continue;
+    counts.set(w, (counts.get(w) ?? 0) + 1);
+  }
+  const keywords = [...counts.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([w]) => w)
+    .slice(0, 6);
+
+  // The trigger, built to be MATCHED: concrete tokens first, prose second.
+  const anchors = [...quoted, ...identifiers, ...keywords.slice(0, 3)].slice(0, 4);
+  const wherePart = paths.length > 0 ? `, or work touches ${paths.slice(0, 2).map((p) => `\`${p}\``).join(" / ")}` : "";
+  const when = anchors.length > 0
+    ? `The task hits ${anchors.map((a) => `"${a}"`).join(" / ")}${wherePart}.`
+    : `The task reproduces: ${firstLine(raw).slice(0, 90)}.`;
+
+  // The slug seeds from identifiers first, then keywords — deduped on the
+  // NORMALISED token, so AXE_SEVERITY and the "axe_severity" the same error
+  // also mentions do not both land in the name.
+  const seedTokens = [];
+  const seenToken = new Set();
+  for (const token of [...identifiers.map((i) => i.toLowerCase()), ...keywords]) {
+    const norm = token.replace(/[^a-z0-9]/g, "");
+    if (norm === "" || seenToken.has(norm)) continue;
+    seenToken.add(norm);
+    seedTokens.push(token);
+    if (seedTokens.length === 4) break;
+  }
+  const slug = skillSlug(seedTokens.join("-") || firstLine(raw)) || "captured-error";
+
+  return {
+    slug,
+    when,
+    keywords,
+    paths,
+    identifiers,
+    excerpt: raw.split(/\r?\n/).slice(0, 12).join("\n"),
+    source: "error",
+  };
+}
+
+function firstLine(text) {
+  return String(text).split(/\r?\n/).find((l) => l.trim() !== "")?.trim() ?? "";
+}
+
+// Preview or scaffold one error-seeded draft.
+function writeErrorDraft(projectRoot, draft, doWrite) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  const target = path.join(skillsDir, `${draft.slug}.md`);
+
+  if (!doWrite) {
+    console.log(c.bold("Skill draft") + c.gray(" — seeded from the error you just hit:"));
+    console.log("");
+    console.log(`  ${c.cyan("slug")}   ${draft.slug}`);
+    console.log(`  ${c.cyan("when")}   ${draft.when}`);
+    if (draft.paths.length > 0) console.log(`  ${c.cyan("paths")}  ${draft.paths.join(", ")}`);
+    console.log("");
+    if (exists(target)) {
+      console.log(c.yellow("note: ") + `${relPath(projectRoot, target)} already exists — writing would skip it`);
+    }
+    console.log(c.gray("Scaffold it: ") + c.cyan("doctrina skill suggest --from-error <text|file> --write"));
+    console.log(c.gray("The trigger is drafted; the procedure is yours to write while you still remember it."));
+    return 0;
+  }
+
+  if (exists(target)) {
+    console.log(c.yellow("skip   ") + ` ${draft.slug} (already exists)`);
+    return 0;
+  }
+
+  const tpl = read(path.join(locateTemplatesDir(), "skill.md.template"));
+  let body = substitute(tpl, { SKILL_NAME: draft.slug });
+  // Fill the trigger — the field a human is least likely to write in a form
+  // anything can match, and the one `context` ranks on.
+  body = body.replace(
+    /^when: .*$/m,
+    `when: ${draft.when.replace(/\r?\n/g, " ")}`,
+  );
+  body += `\n<!-- Seeded from an error. The failure to capture:\n\n${draft.excerpt}\n-->\n`;
+
+  mkdirp(skillsDir);
+  write(target, body, { force: false });
+
+  const index = idx.load(projectRoot);
+  const date = today();
+  idx.addSkill(index, {
+    id: draft.slug,
+    path: `.doctrina/skills/${draft.slug}.md`,
+    description: parseFrontmatter(body, "description") ?? "<edit me — one-sentence summary>",
+    last_updated: date,
+  });
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+
+  console.log(c.green("created") + ` ${relPath(projectRoot, target)}`);
+  console.log(c.gray("The trigger is drafted from the error. Write the procedure while you still remember it,"));
+  console.log(c.gray("then fill `description:` — `doctrina validate` warns on a trigger nothing can match."));
+  return 0;
+}
+
 function skillSuggest(args, flags) {
   const projectRoot = process.cwd();
   ensureDoctrinaProject(projectRoot);
   const doWrite = flagBool(flags, "write", false);
   const since = flagString(flags, "since");
 
+  // --from-error: draft from the failure that is on screen RIGHT NOW,
+  // rather than waiting for the lesson to be remembered later. When given,
+  // it is the only source — this is a specific request, not a survey.
+  // A value-taking flag written without a value is a usage error, not a
+  // silent fall-through to the survey — `--from-error` with nothing after
+  // it would otherwise run the ordinary scan and look like it worked.
+  if (flagGivenWithoutValue(flags, "from-error")) {
+    console.error(c.red("error:") + " --from-error needs the error text, or a path to a file holding it");
+    return 2;
+  }
+  const fromError = flagString(flags, "from-error");
+  if (fromError !== undefined) {
+    if (fromError === "" || fromError === null) {
+      console.error(c.red("error:") + " --from-error needs the error text, or a path to a file holding it");
+      return 2;
+    }
+    // A path is read; anything else is taken as the text itself.
+    const asPath = path.resolve(projectRoot, fromError);
+    const text = isFile(asPath) ? read(asPath) : fromError;
+    const draft = draftFromError(text);
+    if (!draft) {
+      console.error(c.red("error:") + " --from-error was given nothing to draft from");
+      return 2;
+    }
+    return writeErrorDraft(projectRoot, draft, doWrite);
+  }
+
   const skillsDir = path.join(projectRoot, ".doctrina", "skills");
   const existingFiles = isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")) : [];
   const existing = new Set(existingFiles.map((f) => path.basename(f, ".md")));
@@ -423,7 +598,7 @@ Subcommands:
   sync          Copy each skill's frontmatter description into
                 .doctrina/index.json so the index never drifts
                 from the frontmatter (single source of truth).
-  suggest [--write] [--since <ref>]
+  suggest [--write] [--since <ref>] [--from-error <text|file>]
                 Surface fix-shaped lessons not yet captured as skills,
                 from two sources: archived change proposals and the git
                 commit history (ADR 0013). --write scaffolds a stub per
@@ -431,6 +606,14 @@ Subcommands:
                 --since <ref> scans commits in <ref>..HEAD instead of the
                 last 200 (e.g. --since v0.7.0).
 
+                --from-error <text|file> drafts ONE skill from the failure
+                on screen right now, instead of waiting for the lesson to
+                be remembered later. It fills the \`when:\` trigger from the
+                error's own paths, identifiers and message — the field a
+                human is least likely to write in a form anything can
+                match, and the one \`context\` ranks on. The procedure stays
+                yours to write. Add --write to scaffold it.
+
 Skills are written by humans, not generated. See docs/en/skills.md
 for the design rationale and the distinction from specs / AGENTS.md /
 the rejected memory/ folder.

package/src/commands/triage.js

@@ -0,0 +1,248 @@
+// @ts-check
+import path from "node:path";
+import process from "node:process";
+import { exists } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { emitJson } from "../lib/json-out.js";
+import { collectRuntimeFindings, checkLocalEnv } from "../lib/runtime.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
+
+// Classify BEFORE scaffolding.
+//
+// `doctrina work` was the default answer to every request, so a broken
+// workflow, an invalid env value, and a suite that ran nothing all became
+// changes with a proposal, tasks and a spec delta — half an hour of
+// artifact for a bug the YAML already explained, and a close that was
+// theatre on top of a diagnosis. Meanwhile the actual cause sat in a file
+// no gate read.
+//
+// Three lanes, because three kinds of request fail differently:
+//
+//   PRODUCT  behaviour changes -> `doctrina work` earns its ceremony: a
+//            spec delta is the point, because the truth is changing.
+//   RUNTIME  something is wired wrong, empty, or ran nothing. There is no
+//            spec delta to write — the requirement already exists and the
+//            implementation does not honour it. Diagnose first.
+//   CHORE    implementation-only work whose requirement is already
+//            specified: `doctrina work --chore`, no EARS delta.
+//
+// The classifier is deterministic term matching, and it is a HINT, not a
+// verdict — the same contract `work` already makes about its capability
+// guess. It never refuses; it names the lane and lets the agent decide.
+
+export const jsonNative = true;
+
+export const flags = { boolean: ["json", "env"], string: [] };
+
+// Signals that a request is about the running system rather than about what
+// the system should do. Weighted: a phrase that can only mean runtime counts
+// for more than a word that merely leans that way.
+const RUNTIME_SIGNALS = [
+  [3, /\b(workflow|pipeline|ci|github actions|actions run|job|runner)\b/i],
+  [3, /\b(env var|environment variable|dotenv|\.env|secret|secrets|vars)\b/i],
+  [3, /\b(0 (tests?|scenarios?|cases?)|no (tests?|scenarios?) ran|ran nothing|empty (run|suite|summary))\b/i],
+  [2, /\b(exit code|stack ?trace|traceback|logs?|step summary|artifact missing)\b/i],
+  [2, /\b(green but|passes but|silently|never (fires|applies|reaches|ran))\b/i],
+  [2, /\b(flaky|timeout|timed out|hangs?|crash(es|ed)?|broken build|failing build)\b/i],
+  [2, /\b(tag|selector|filter|dispatch)\b/i],
+  [1, /\b(config|configuration|wiring|wired|deploy(ment)?|docker|compose)\b/i],
+  [1, /\b(debug|diagnos(e|is)|investigate|why (is|does|did)|not working|doesn't work)\b/i],
+];
+
+const CHORE_SIGNALS = [
+  [3, /\b(bump|upgrade|pin|lockfile|dependency|dependencies|devdependenc)\b/i],
+  [2, /\b(rename|move|reorganis|reorganiz|refactor|tidy|cleanup|clean up|format(ting)?|lint)\b/i],
+  [2, /\b(typo|comment|readme|changelog|docs? only)\b/i],
+  [2, /\b(already (specified|in the spec)|wiring only|no behaviour change|no behavior change)\b/i],
+];
+
+const PRODUCT_SIGNALS = [
+  [3, /\b(add|introduce|support|allow|enable|implement|build)\b/i],
+  [3, /\b(should|shall|must|requirement|acceptance|criteri)\b/i],
+  [2, /\b(new (feature|capability|command|endpoint|screen|flow))\b/i],
+  [2, /\b(users? (can|should|want)|so that|in order to)\b/i],
+  [1, /\b(change|behaviour|behavior|spec)\b/i],
+];
+
+/**
+ * Score a prompt against each lane. Deterministic, explainable, and cheap:
+ * the caller gets the winning lane AND the signals that produced it, so a
+ * wrong guess is arguable rather than mysterious.
+ */
+export function classify(prompt) {
+  const text = String(prompt ?? "");
+  const score = (signals) => {
+    let total = 0;
+    const hits = [];
+    for (const [weight, re] of signals) {
+      const m = text.match(re);
+      if (m) {
+        total += weight;
+        hits.push(m[0].toLowerCase());
+      }
+    }
+    return { total, hits };
+  };
+
+  const lanes = {
+    runtime: score(RUNTIME_SIGNALS),
+    chore: score(CHORE_SIGNALS),
+    product: score(PRODUCT_SIGNALS),
+  };
+
+  // Product is the default: when nothing distinguishes the request, the
+  // ceremony that writes a spec delta is the safe one to fall into. Runtime
+  // must BEAT product to win, so an ordinary feature request mentioning a
+  // "job" does not get diverted into a diagnosis.
+  let lane = "product";
+  let best = lanes.product.total;
+  for (const name of ["runtime", "chore"]) {
+    if (lanes[name].total > best) {
+      lane = name;
+      best = lanes[name].total;
+    }
+  }
+  if (best === 0) lane = "product";
+
+  // Confidence is the MARGIN over the runner-up, not the winner's own score:
+  // a prompt that scores 5 for runtime and 4 for product is a coin toss the
+  // agent should see as one, and a clear product request must be able to read
+  // as confident too (comparing a lane against itself never could).
+  const runnerUp = Object.entries(lanes)
+    .filter(([name]) => name !== lane)
+    .reduce((max, [, v]) => Math.max(max, v.total), 0);
+
+  return { lane, scores: lanes, confident: best > 0 && best - runnerUp >= 2 };
+}
+
+export async function run(positional, cmdFlags) {
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw notADoctrinaProject();
+  }
+  const json = flagBool(cmdFlags, "json", false);
+  const withEnv = flagBool(cmdFlags, "env", false);
+  const prompt = positional.join(" ").trim();
+
+  const runtime = collectRuntimeFindings(projectRoot);
+  const envFindings = withEnv ? checkLocalEnv(projectRoot) : [];
+  const findings = [...runtime.findings, ...envFindings];
+  const errors = findings.filter((f) => f.level === "error");
+  const verdict = prompt ? classify(prompt) : null;
+
+  if (json) {
+    emitJson("triage", {
+      lane: verdict?.lane ?? null,
+      confident: verdict?.confident ?? null,
+      contracts: runtime.contracts,
+      declared: runtime.declared,
+      findings,
+      errors: errors.length,
+    });
+    return errors.length > 0 ? 1 : 0;
+  }
+
+  if (verdict) renderLane(prompt, verdict);
+  renderRuntime(runtime, envFindings, withEnv, Boolean(verdict));
+
+  return errors.length > 0 ? 1 : 0;
+}
+
+function renderLane(prompt, verdict) {
+  const LABEL = {
+    product: c.green("PRODUCT"),
+    runtime: c.yellow("RUNTIME"),
+    chore: c.cyan("CHORE"),
+  };
+  console.log(c.bold("Lane") + c.gray(" — deterministic term match; a hint, not a decision"));
+  console.log("");
+  console.log(`  ${LABEL[verdict.lane]}${verdict.confident ? "" : c.gray("  (weak signal — read the playbook and override if it is wrong)")}`);
+  const hits = verdict.scores[verdict.lane].hits;
+  if (hits.length > 0) console.log(c.gray(`  signals: ${[...new Set(hits)].slice(0, 6).join(", ")}`));
+  console.log("");
+
+  if (verdict.lane === "product") {
+    console.log("This changes what the system should DO — the ceremony is the point:");
+    console.log(`  ${c.cyan(`doctrina work "${truncate(prompt)}"`)}`);
+    console.log(c.gray("  spec delta -> tasks -> implement -> close"));
+  } else if (verdict.lane === "chore") {
+    console.log("The requirement already exists; only the implementation moves:");
+    console.log(`  ${c.cyan(`doctrina work --chore "${truncate(prompt)}"`)}`);
+    console.log(c.gray("  short proposal + patch + verify, no EARS delta"));
+    console.log(c.gray("  needing a spec delta means it was never a chore — reopen without --chore"));
+  } else {
+    console.log("Nothing here says the SPEC is wrong — the running system is.");
+    console.log("Diagnose before scaffolding anything:");
+    console.log(`  ${c.cyan("doctrina contract check")}   the declared wiring vs the workflow`);
+    console.log(`  ${c.cyan("doctrina triage --env")}     local .env vs the declared enums (names only)`);
+    console.log(`  ${c.cyan("doctrina verify")}           the real build gate, with its output expectations`);
+    console.log(c.gray("  Open a change only once the diagnosis shows the requirement itself is missing."));
+  }
+  console.log("");
+}
+
+function renderRuntime(runtime, envFindings, withEnv, hadLane) {
+  if (hadLane) console.log(c.bold("Runtime") + c.gray(" — the declared surface, checked"));
+  else console.log(c.bold("Runtime triage") + c.gray(" — the declared surface, checked"));
+  console.log("");
+
+  if (runtime.contracts === 0) {
+    console.log(c.gray("  no contracts in .doctrina/contracts/ — nothing declares the runtime surface"));
+    console.log(c.gray("  start one: ") + c.cyan("doctrina contract new system"));
+    console.log("");
+    return;
+  }
+  if (runtime.declared === 0) {
+    console.log(c.gray(`  ${runtime.contracts} contract${runtime.contracts === 1 ? "" : "s"}, 0 Wiring/Selectors rows — the runtime surface is UNCHECKED, not verified`));
+    console.log(c.gray("  declare what CI injects and what your selectors are, and this becomes a gate"));
+    console.log("");
+    return;
+  }
+
+  const all = [...runtime.findings, ...envFindings];
+  if (all.length === 0) {
+    console.log(c.green("  ok") + `  ${runtime.declared} declared row${runtime.declared === 1 ? "" : "s"} across ${runtime.contracts} contract${runtime.contracts === 1 ? "" : "s"} hold` + (withEnv ? " (including local .env)" : ""));
+    console.log("");
+    return;
+  }
+
+  for (const f of all) {
+    const mark = f.level === "error" ? c.red("  ✗") : c.yellow("  !");
+    console.log(`${mark}  ${f.message} ${c.gray(`[${f.code}]`)}`);
+    console.log(`      ${c.gray(`fix: ${f.remedy}`)}`);
+  }
+  console.log("");
+  const errors = all.filter((f) => f.level === "error").length;
+  const warns = all.length - errors;
+  if (errors > 0) console.log(c.red("fail") + ` ${errors} runtime error${errors === 1 ? "" : "s"}, ${warns} warning${warns === 1 ? "" : "s"} — fix the wiring, not the spec`);
+  else console.log(c.yellow("warn") + ` ${warns} advisory finding${warns === 1 ? "" : "s"}`);
+}
+
+function truncate(s, max = 60) {
+  return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
+export const help = `
+Usage: doctrina triage ["<prompt>"] [--env]
+
+Classify a request BEFORE scaffolding, and diagnose the running system.
+
+With a prompt, name the lane the request belongs to:
+  PRODUCT   behaviour changes -> doctrina work (the spec delta is the point)
+  RUNTIME   wired wrong, empty, or ran nothing -> diagnose; no delta to write
+  CHORE     implementation-only, already specified -> doctrina work --chore
+
+The classifier is deterministic term matching and prints the signals it
+matched: a HINT, like the capability guess in \`work\`. It never refuses.
+
+With or without a prompt, it also runs the runtime checks over every
+contract (the same checks as \`contract check\`, and the same verdict):
+declared wiring vs the workflow, empty-vs-unset consumer defaults,
+declared enums, and selectors that would match nothing.
+
+  --env    also check the local .env against the declared enums. Reports
+           NAMES and membership only — a rejected value is never printed.
+
+Exit 0 when no runtime errors (warnings allowed), 1 when any error stands.
+`;

package/src/commands/validate.js

@@ -17,6 +17,8 @@ import { checkEars, isEarsSpec } from "../lib/ears.js";
 import { specHeader, listHeader, deriveIndex, indexesMatch, stableStringify } from "../lib/scan.js";
 import { COMMAND_NAMES, referencedCommands } from "../lib/commands.js";
 import { parseAcceptanceCriteria, isVerified } from "../lib/criteria.js";
+import { parsePipeline, checkPipeline } from "../lib/pipeline.js";
+import { collectRuntimeFindings } from "../lib/runtime.js";
 
 // AGENTS.md is treated as a maintained doctrina-command catalog only once it
 // documents at least this many real commands; below it, the file defers to
@@ -30,7 +32,7 @@ const CATALOG_THRESHOLD = 8;
 // wrap it in the generic envelope.
 export const jsonNative = true;
 
-export const flags = { boolean: ["fix", "json"], string: [] };
+export const flags = { boolean: ["fix", "json", "runtime"], string: [] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -379,6 +381,17 @@ export async function run(_positional, flags) {
           }
         }
 
+        // 8b-ii. ORDERED requirements (change 0029). EARS states each
+        //     event-driven requirement independently and says nothing about
+        //     order, so a consumer step and its producer both pass while the
+        //     consumer reads last run's file. A `### Pipeline` block declares
+        //     the order and the artifact each step hands on; the invariant is
+        //     that a step may only require what an EARLIER step produced.
+        //     Opt-in: a spec without the block is never checked.
+        for (const f of checkPipeline(parsePipeline(text))) {
+          errors.push(`${relPath(projectRoot, specPath)}:${f.line} ${f.message} [${f.code}] — ${f.remedy}`);
+        }
+
         // 8c. Capability-state honesty (two-axis status). An "active"
         //     document that records no built capability is an inventory
         //     claim — the gap the framework is meant to make visible.
@@ -581,6 +594,22 @@ export async function run(_positional, flags) {
       if (nameField && nameField !== baseName) {
         warnings.push(`${rel} name "${nameField}" does not match filename slug "${baseName}"`);
       }
+
+      // 14b. A skill nothing can TRIGGER is a file, not a memory (change
+      //      0029). `context` lists a skill's `when:` so an agent can fire
+      //      the right one without loading any of them — but a trigger
+      //      written as pure prose ("when it makes sense", "as needed")
+      //      gives it nothing to match on, and the skill is never loaded by
+      //      anyone who did not already know it existed. A usable trigger
+      //      names something concrete: a keyword, a path, a command, an
+      //      error string.
+      if (whenField && !hasDetectableTrigger(whenField)) {
+        warnings.push(
+          `${rel} frontmatter "when" has no detectable trigger — name a concrete ` +
+          `keyword, path, command or error string, or nothing can match it ` +
+          `(got: "${whenField.length > 60 ? `${whenField.slice(0, 59)}…` : whenField}")`,
+        );
+      }
       const lines = lineCount(f);
       if (lines > 200) warnings.push(`${rel} is ${lines} lines (>200 soft cap)`);
       else if (lines > 150) warnings.push(`${rel} is ${lines} lines (>150 soft cap)`);
@@ -628,6 +657,22 @@ export async function run(_positional, flags) {
   // survives sessions because it is an artifact, not a memory.
   for (const line of checkProjectRules(projectRoot)) errors.push(line);
 
+  // 18. --runtime folds the RUNTIME gate into the structural one, so a
+  //     single call covers both halves of the truth: the shape of the
+  //     artifacts, and whether what they declare about the running system
+  //     still holds. Opt-in because it reads files outside .doctrina/
+  //     (workflows, consumers, test sources) and a structural validate
+  //     should stay cheap. Delegates to lib/runtime.js — the same checks
+  //     `contract check`, `triage` and `doctor` render, so the four can
+  //     never disagree.
+  if (flagBool(flags, "runtime", false)) {
+    for (const f of collectRuntimeFindings(projectRoot).findings) {
+      const line = `${f.contract}: ${f.message} [${f.code}] — ${f.remedy}`;
+      if (f.level === "error") errors.push(line);
+      else warnings.push(line);
+    }
+  }
+
   // Output
   if (flagBool(flags, "json", false)) {
     emitJson("validate", { ok: errors.length === 0, errors, warnings });
@@ -646,6 +691,28 @@ export async function run(_positional, flags) {
   return errors.length === 0 ? 0 : 1;
 }
 
+// Does a skill's `when:` give anything to MATCH on? A trigger written as
+// pure prose ("when it seems relevant", "as needed") reads fine and can
+// never fire: `context` ranks skills by comparing the trigger against the
+// task, and there is nothing there to compare. A usable trigger names
+// something concrete — a path or glob, a command, a quoted error string, a
+// file extension, an ALL_CAPS identifier, or simply enough distinctive
+// keywords to match on.
+const VAGUE_TRIGGER = /^(?:when(?:ever)?\s+)?(?:it|this|you|the agent)?\s*(?:is\s+)?(?:seems?|feels?|looks?)?\s*(?:relevant|appropriate|needed|necessary|useful|applicable|as needed|if needed)\.?$/i;
+
+export function hasDetectableTrigger(when) {
+  const text = String(when ?? "").trim();
+  if (text === "" || VAGUE_TRIGGER.test(text)) return false;
+  // Anything structural is inherently matchable.
+  if (/[\/\]|\*|`|"|'|\.\w{2,4}|[A-Z][A-Z0-9_]{2,}/.test(text)) return true;
+  // Otherwise: enough distinctive words to rank on. Stopwords do not count.
+  const STOP = new Set(["when", "whenever", "the", "a", "an", "is", "are", "you", "your",
+    "it", "its", "this", "that", "and", "or", "to", "of", "in", "on", "for", "with",
+    "any", "some", "need", "needs", "needed", "should", "must", "at", "as", "by", "be"]);
+  const words = text.toLowerCase().match(/[a-z][a-z0-9-]{2,}/g) ?? [];
+  return words.filter((w) => !STOP.has(w)).length >= 2;
+}
+
 // Enforce .doctrina/rules.json — permanent project constraints as
 // forbid-regexes over glob-scoped paths:
 //   { "rules": [ { "id": "white-label", "forbid": "\\bAcmeCorp\\b",
@@ -846,13 +913,33 @@ function isLikelyPath(s) {
 }
 
 export const help = `
-Usage: doctrina validate [--fix] [--json]
+Usage: doctrina validate [--fix] [--runtime] [--json]
 
 Run schema, artifact-existence, and structural checks against the
 .doctrina/ tree in the current working directory. Exits 0 if no errors
 (warnings allowed), 1 otherwise.
 
+Two structural checks worth naming:
+
+  Pipeline    a spec's optional "### Pipeline" block declares ordered
+              steps and the artifact each hands on:
+                1. run-suite — produces \`results.json\`
+                2. analyse — requires \`results.json\`, produces \`analysis.md\`
+              A step may only require what an EARLIER step produced.
+              EARS states each event-driven requirement independently, so
+              without this a consumer and its producer both pass while the
+              consumer reads the previous run's file. Mark inputs from
+              outside the pipeline \`(external)\`.
+
+  Triggers    a skill whose frontmatter "when:" names nothing concrete
+              (no keyword, path, command or error string) can never be
+              matched, so nothing ever loads it.
+
 Flags:
-  --fix    Rebuild index.json from the tree before checking (heals drift).
-  --json   Emit { ok, errors, warnings } as JSON (stable shape for agents/CI).
+  --fix       Rebuild index.json from the tree before checking (heals drift).
+  --runtime   Also run the RUNTIME gate: the declared wiring, enums and
+              selectors checked against the workflows and code that are
+              supposed to honour them (the same checks as \`contract check\`).
+              Opt-in because it reads files outside .doctrina/.
+  --json      Emit { ok, errors, warnings } as JSON (stable shape for agents/CI).
 `;