doctrina-cli 0.13.0 → 0.15.0

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/upgrade.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
@@ -7,6 +8,7 @@ import { cliVersion } from "../lib/version.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { today } from "../lib/dates.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 import * as templates from "./templates.js";
 import * as validate from "./validate.js";
 
@@ -20,10 +22,15 @@ import * as validate from "./validate.js";
 // step. Preview by default; --write applies. Never rewrites user content
 // (the same additive-only bound as `templates update`).
 
+// 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", "write"], string: [] };
+
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
   const writeMode = flagBool(flags, "write", false);
   const running = cliVersion();

package/src/commands/validate.js

@@ -1,26 +1,45 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
-import { exists, isDir, isFile, lineCount, read, relPath, walk } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, lineCount, read, relPath, walk , write} from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
 import { SCHEMA_VERSION } from "../lib/index-json.js";
 import { cliVersion } from "../lib/version.js";
 import { today } from "../lib/dates.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { kindFromPath, nonConformingHeaders, repairHeaders } from "../lib/doc-model.js";
+import { emitJson } from "../lib/json-out.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { parseFrontmatter } from "./skill.js";
 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
 // `doctrina --help` and is never nagged about omissions.
 const CATALOG_THRESHOLD = 8;
 
+// 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).
+// This command builds its own JSON payload; the entrypoint must not
+// wrap it in the generic envelope.
+export const jsonNative = true;
+
+export const flags = { boolean: ["fix", "json", "runtime"], string: [] };
+
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
+  // Outside a Doctrina project this is a PRECONDITION, not a pile of
+  // gate failures about missing files: the remedy is `doctrina init`,
+  // not editing artifacts that do not exist yet (C7).
+  if (!isDir(path.join(projectRoot, ".doctrina"))) throw notADoctrinaProject();
   const errors = [];
   const warnings = [];
 
@@ -87,6 +106,45 @@ export async function run(_positional, flags) {
   const productMd = path.join(projectRoot, ".doctrina", "product.md");
   if (!isFile(productMd)) errors.push(".doctrina/product.md missing");
 
+  // Header repair (M3). One grammar means a non-canonical header can be
+  // REWRITTEN, not just reported: `- **Status**: x` becomes
+  // `- **Status:** x`, and a spec written with list-style headers is
+  // normalised to the bare-bold form its kind uses. Content is never
+  // touched — only the header's own punctuation and style.
+  const doFix = flagBool(flags, "fix", false);
+  {
+    const artifacts = [];
+    const dot = path.join(projectRoot, ".doctrina");
+    for (const f of walk(dot)) {
+      if (!f.endsWith(".md")) continue;
+      const rel = relPath(projectRoot, f).replace(/\\/g, "/");
+      if (rel.includes("/changes/archive/")) continue; // history is immutable
+      artifacts.push({ file: f, rel, kind: kindFromPath(rel) });
+    }
+    let repairedFiles = 0;
+    for (const a of artifacts) {
+      const text = read(a.file);
+      const bad = nonConformingHeaders(text, a.kind);
+      if (bad.length === 0) continue;
+      if (doFix) {
+        const { text: fixed, repaired } = repairHeaders(text, a.kind);
+        if (repaired > 0 && fixed !== text) {
+          write(a.file, fixed, { force: true });
+          repairedFiles += 1;
+        }
+      } else {
+        for (const h of bad) {
+          warnings.push(
+            `${a.rel}:${h.line} header "${h.name}" is ${h.wrongStyle ? `in ${h.style} style but a ${a.kind} uses ${h.expectedStyle} style` : "not in canonical form"} — run \`doctrina validate --fix\``,
+          );
+        }
+      }
+    }
+    if (doFix && repairedFiles > 0) {
+      console.log(c.green("fixed") + ` normalised headers in ${repairedFiles} artifact${repairedFiles === 1 ? "" : "s"}`);
+    }
+  }
+
   // 3. index.json
   let index = null;
   try {
@@ -323,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.
@@ -525,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)`);
@@ -572,9 +657,25 @@ 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)) {
-    console.log(JSON.stringify({ ok: errors.length === 0, errors, warnings }, null, 2));
+    emitJson("validate", { ok: errors.length === 0, errors, warnings });
     return errors.length === 0 ? 0 : 1;
   }
   for (const w of warnings) console.log(c.yellow("warn:  ") + w);
@@ -590,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",
@@ -790,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).
 `;