doctrina-cli 0.15.1 → 0.17.0

package/src/commands/trace.js

@@ -8,6 +8,11 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { emitJson } from "../lib/json-out.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { summarize, collectAnchors, collectAnchorDuplicates, collectSpecs } from "../lib/trace-model.js";
+
+// The provenance arithmetic lives in lib/trace-model.js, which `status`,
+// `review` and the project snapshot read too (audit finding F7).
+export { summarize } from "../lib/trace-model.js";
 
 // Intent-provenance report (ADR 0006). `coverage` proves a criterion has a
 // test; `trace` proves a capability traces to a stated intent. Together they
@@ -48,9 +53,23 @@ export async function run(_positional, flags) {
 
   const anchors = collectAnchors(projectRoot); // [{ id }], in document order
   const specs = collectSpecs(projectRoot); // [{ cap, status, realizes: [id] }]
+  // An id declared twice is two intents under one name (change 0108): the
+  // collector keeps the first, so the second is invisible everywhere unless
+  // named here. A gap, like a dropped anchor — `validate` reports it as an
+  // error as well.
+  const duplicates = collectAnchorDuplicates(projectRoot); // [{ id, lines }]
 
   const anchorIds = new Set(anchors.map((a) => a.id));
-  const anyRealizes = specs.some((s) => s.realizes !== null);
+  // A spec OPTED IN when it cites at least one anchor id. The header alone
+  // is not opting in: `spec new` scaffolds `**Realizes:** n/a — <reason>`,
+  // which parses to an empty id list and used to count as participation.
+  // One scaffolded spec was therefore enough to take a project out of the
+  // never-opted-in branch and into the normal report, where zero anchors
+  // rendered as `ok 0 of 0 intent anchors realized` — a green verdict over
+  // nothing, on the very first read a new project gets about itself, while
+  // `doctor` read the same collection and warned (change 0083). Absence is
+  // not approval — the half change 0057 fixed in `coverage` and not here.
+  const anyRealizes = specs.some((s) => s.realizes !== null && s.realizes.length > 0);
 
   // The feature is unused: do not nag a project that never opted in.
   if (anchors.length === 0 && !anyRealizes) {
@@ -88,8 +107,8 @@ export async function run(_positional, flags) {
 
   if (json) {
     const rows = anchors.map((a) => ({ id: a.id, realizedBy: (realizedBy.get(a.id) ?? []).sort() }));
-    const clean = rows.every((r) => r.realizedBy.length > 0) && dangling.length === 0 && untraceable.length === 0;
-    emitJson("trace", { anchors: rows, dangling, untraceable, summary: summarize(projectRoot) });
+    const clean = rows.every((r) => r.realizedBy.length > 0) && dangling.length === 0 && untraceable.length === 0 && duplicates.length === 0;
+    emitJson("trace", { anchors: rows, dangling, untraceable, duplicates, summary: summarize(projectRoot) });
     return clean ? 0 : strict ? 1 : 0;
   }
 
@@ -107,7 +126,10 @@ export async function run(_positional, flags) {
     }
   }
 
-  if (dangling.length > 0 || untraceable.length > 0) console.log("");
+  if (dangling.length > 0 || untraceable.length > 0 || duplicates.length > 0) console.log("");
+  for (const d of duplicates) {
+    console.log(`  ${c.red("✗")} duplicate anchor [${d.id}] — declared at product.md lines ${d.lines.join(" and ")}; only the first is read, give the second its own id`);
+  }
   for (const d of dangling) {
     console.log(`  ${c.yellow("!")} dangling: spec "${d.cap}" realizes ${d.id} (no such anchor in product.md)`);
   }
@@ -117,10 +139,16 @@ export async function run(_positional, flags) {
 
   const dropped = anchors.length - realized;
   console.log("");
-  const summary =
-    `${realized} of ${anchors.length} intent anchor${anchors.length === 1 ? "" : "s"} realized` +
-    `; ${dropped} dropped, ${dangling.length} dangling, ${untraceable.length} untraceable`;
-  const clean = dropped === 0 && dangling.length === 0 && untraceable.length === 0;
+  const summary = anchors.length === 0
+    ? `no intent anchors declared in product.md` +
+      `; ${dangling.length} dangling, ${untraceable.length} untraceable`
+    : `${realized} of ${anchors.length} intent anchor${anchors.length === 1 ? "" : "s"} realized` +
+      `; ${dropped} dropped, ${dangling.length} dangling, ${untraceable.length} untraceable` +
+      (duplicates.length > 0 ? `, ${duplicates.length} duplicate` : "");
+  // Reaching the report with no anchors at all is never clean: there is
+  // nothing to have realized, and a ratio over zero says nothing true.
+  const clean = anchors.length > 0
+    && dropped === 0 && dangling.length === 0 && untraceable.length === 0 && duplicates.length === 0;
   if (clean) {
     console.log(c.green("ok") + " " + summary);
     return 0;
@@ -130,69 +158,6 @@ export async function run(_positional, flags) {
   return strict ? 1 : 0;
 }
 
-// Pure summary of intent provenance, for other commands (`status`, `review`)
-// that need the numbers without the report output.
-export function summarize(projectRoot) {
-  const anchors = collectAnchors(projectRoot);
-  const specs = collectSpecs(projectRoot);
-  const anchorIds = new Set(anchors.map((a) => a.id));
-  const realizedBy = new Map();
-  let dangling = 0;
-  for (const s of specs) {
-    if (s.realizes === null) continue;
-    for (const id of s.realizes) {
-      if (anchorIds.has(id)) {
-        if (!realizedBy.has(id)) realizedBy.set(id, []);
-        realizedBy.get(id).push(s.cap);
-      } else {
-        dangling += 1;
-      }
-    }
-  }
-  const untraceable = specs.filter((s) => s.realizes === null && s.status === "active").length;
-  let realized = 0;
-  for (const a of anchors) if ((realizedBy.get(a.id) ?? []).length > 0) realized += 1;
-  return {
-    anchors: anchors.length,
-    realized,
-    dropped: anchors.length - realized,
-    dangling,
-    untraceable,
-  };
-}
-
-// Every "[A-Z]+\d+" tag at the head of a bullet in product.md is an intent
-// anchor. Section-agnostic so Success-criteria and In-scope bullets both work.
-function collectAnchors(projectRoot) {
-  const productPath = path.join(projectRoot, ".doctrina", "product.md");
-  if (!isFile(productPath)) return [];
-  const out = [];
-  const seen = new Set();
-  for (const line of read(productPath).split(/\r?\n/)) {
-    const m = line.match(/^\s*[-*]\s+\[([A-Z]+\d+)\]\s+/);
-    if (m && !seen.has(m[1])) {
-      seen.add(m[1]);
-      out.push({ id: m[1] });
-    }
-  }
-  return out;
-}
-
-function collectSpecs(projectRoot) {
-  const specsDir = path.join(projectRoot, ".doctrina", "specs");
-  if (!isDir(specsDir)) return [];
-  const out = [];
-  for (const cap of readdirSync(specsDir).sort()) {
-    const specPath = path.join(specsDir, cap, "spec.md");
-    if (!isFile(specPath)) continue;
-    const text = read(specPath);
-    const realizesRaw = specHeader(text, "Realizes");
-    const realizes = realizesRaw === null ? null : (realizesRaw.match(ANCHOR_RE) ?? []);
-    const status = (specHeader(text, "Status") ?? "active").trim().toLowerCase();
-    out.push({ cap, status, realizes });
-  }
-  return out;
-}
 
 export const help = `
 Usage: doctrina trace [--strict]

package/src/commands/triage.js

@@ -4,6 +4,10 @@ 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 { classify } from "../lib/triage-model.js";
+
+// The classifier is shared with `work`; see lib/triage-model.js.
+export { classify } from "../lib/triage-model.js";
 import { emitJson } from "../lib/json-out.js";
 import { collectRuntimeFindings, checkLocalEnv } from "../lib/runtime.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
@@ -35,96 +39,14 @@ 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],
-  // AUTHORING VERBS. Both lanes above match domain NOUNS, which turned out
-  // to misread work ON the machinery as an incident IN it: "declare the
-  // release workflow wiring in a contract" scored RUNTIME on "workflow" and
-  // "wiring", and "so an intentional rename stops warning" scored CHORE on
-  // "rename" — a noun, not the act. Neither prompt was a diagnosis; both
-  // were someone sitting down to write an artifact.
-  //
-  // These are the verbs of authoring. A prompt whose verb is "declare" or
-  // "document" is describing work on the tree, whatever nouns surround it.
-  [3, /\b(declare|declaring|document|documenting|record|recording|specify|specifying|define|defining)\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();

package/src/commands/upgrade.js

@@ -9,6 +9,7 @@ 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 { collectFindings } from "../lib/templates-model.js";
 import * as templates from "./templates.js";
 import * as validate from "./validate.js";
 
@@ -56,11 +57,23 @@ export async function run(_positional, flags) {
   // 2. Additive template updates (missing recommended sections in AGENTS.md /
   //    product.md, missing index.json fields). Reuses `templates update`
   //    verbatim: preview without --write, apply with it.
-  console.log(c.gray("──── 1/3 scaffold shape (templates update)"));
+  console.log(c.gray("──── 1/3 scaffold shape"));
   const tplFlags = writeMode ? new Map([["write", true]]) : new Map();
   const tplCode = await templates.run(["update"], tplFlags);
   if (tplCode !== 0 && !writeMode) pending += 1; // preview exits 1 when updates are pending
 
+  // What the additive update cannot fix — a drifted adapter, a broken
+  // playbook, an index schema it does not know — used to be visible only to
+  // `templates check`. Printed here, each with its own remedy, so the one
+  // command that brings a project up to date also says what is left for a
+  // person (change 0178: the check and the update became this step).
+  const manual = collectFindings(projectRoot).findings
+    .filter((f) => !/upgrade --write|index rebuild/.test(f.remedy ?? ""));
+  for (const f of manual) {
+    console.log(c.yellow("✗ ") + f.message);
+    console.log(c.gray("    fix: ") + (f.remedy ? c.cyan(f.remedy) : c.gray("manual repair — no command can fix this")));
+  }
+
   // 3. Index: rebuild from the tree, which also migrates the framework stamp.
   console.log("");
   console.log(c.gray("──── 2/3 index + framework stamp"));
@@ -101,14 +114,22 @@ export async function run(_positional, flags) {
   const vCode = await validate.run([], vFlags);
 
   console.log("");
+  if (manual.length > 0) {
+    console.log(c.yellow("manual") + ` ${manual.length} finding${manual.length === 1 ? "" : "s"} the upgrade cannot repair — see step 1`);
+  }
   if (!writeMode) {
-    if (pending > 0) {
+    if (pending > 0 || manual.length > 0) {
+      if (pending === 0) return 1;
       console.log(c.yellow("pending") + ` upgrade steps found — apply them: ${c.cyan("doctrina upgrade --write")}`);
       return 1;
     }
     console.log(c.green("ok") + " nothing to upgrade — the project matches the installed CLI");
     return vCode;
   }
+  if (vCode === 0 && manual.length > 0) {
+    console.log(c.yellow(`upgraded to ${running} with manual repairs left`) + " — each finding in step 1 names its fix.");
+    return 1;
+  }
   if (vCode === 0) {
     console.log(c.green(`✓ project upgraded to ${running}`) + c.gray(" — review any warnings above; new commands: `doctrina --help`."));
     console.log(c.gray("AGENTS.md's doctrina:surface block was regenerated from the installed catalog, so agents reading the hub now discover the current commands."));
@@ -125,16 +146,20 @@ Bring an existing project up to the installed CLI after an npm update.
 The project keeps the scaffold of the version that init-ed it; this is
 the one command that closes the gap, orchestrating the existing pieces:
 
-  1. templates update   — regenerate the AGENTS.md doctrina:surface block
+  1. scaffold shape     — regenerate the AGENTS.md doctrina:surface block
                           from the installed command catalog (the block is
                           CLI-owned, ADR 0015 — this is how agents reading
-                          the hub discover commands added since init), and
+                          the hub discover commands added since init),
                           append missing recommended sections / index.json
-                          fields (additive-only outside the block)
+                          fields (additive-only outside the block), and
+                          list what no command can repair (a drifted
+                          adapter, a broken playbook), each with its fix
   2. index rebuild      — regenerate index.json from the tree and migrate
                           the framework_version stamp to the running CLI
   3. validate (--fix)   — surface anything the upgrade cannot fix
                           (hand-authored drift, new validate checks)
 
-Preview by default (exits 1 when steps are pending); --write applies.
+Preview by default (exits 1 when steps are pending or a manual repair is
+left); --write applies. The preview is what \`templates check\` reported
+and --write what \`templates update --write\` did — both deprecated.
 `;