doctrina-cli 0.15.0 → 0.16.0

package/src/lib/spec-ops.js

@@ -1,4 +1,5 @@
 // @ts-check
+import { commentRanges, isInsideComment } from "./doc-model.js";
 // Structured spec operations (ADR 0007 / review F3). A MODIFIED spec delta
 // historically carried prose ("flip criterion 2 to verified", "bump to
 // 0.3.0") that a human merged by hand — the single most error-prone step in
@@ -39,6 +40,40 @@
 const HEADER_RE = (name) =>
   new RegExp(`^(\\s*(?:-\\s+)?\\*\\*${escapeRe(name)}:\\*\\*)\\s*(.*)$`, "m");
 
+// The ENUMS behind the two machine-read headers and the criterion mark
+// (change 0102). `--version` and `--bump` always validated their input;
+// `--status`, `--implementation` and `--criterion` wrote whatever string they
+// were given, synced it into the index, and `validate` passed it — so a spec
+// could say `Status: bogus` and `prime` would report "1 banana" without
+// finding anything odd. A header every gate branches on has a domain, and
+// this is it. A note after the state word stays legal ("planned — deferred,
+// see ADR 0007"): only the WORD is checked.
+export const STATUS_VALUES = ["draft", "active", "deprecated"];
+export const IMPLEMENTATION_VALUES = ["planned", "partial", "implemented", "verified"];
+export const CRITERION_MARKS = ["verified", "unverified", "orchestration"];
+
+/** The state word of a header/mark value: the first token, note stripped. */
+export function stateWord(value) {
+  const first = String(value ?? "").trim().split(/\s+/)[0] ?? "";
+  return first.replace(/[—:-]+$/, "").toLowerCase();
+}
+
+/** null when `value` is a legal value for `name`; otherwise the error text. */
+export function headerValueError(name, value) {
+  const allowed = name === "Status" ? STATUS_VALUES : name === "Implementation" ? IMPLEMENTATION_VALUES : null;
+  if (!allowed) return null;
+  const word = stateWord(value);
+  if (allowed.includes(word)) return null;
+  return `${name} must be one of ${allowed.join("|")} (got "${String(value).trim()}") — a note may follow the value, the value itself does not change`;
+}
+
+/** null when `mark` is a legal criterion mark; otherwise the error text. */
+export function criterionMarkError(mark) {
+  const word = stateWord(mark);
+  if (CRITERION_MARKS.includes(word)) return null;
+  return `a criterion mark must be one of ${CRITERION_MARKS.join("|")} (got "${String(mark).trim()}")`;
+}
+
 function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -71,11 +106,8 @@ export function extractOps(deltaText) {
 // contain a comment (an `<!-- illustrative -->` marker inside an
 // append-criterion landed in the spec with the marker silently gutted).
 function matchOpsBlock(text) {
-  const commentRanges = [];
-  for (const m of text.matchAll(/<!--[\s\S]*?-->/g)) {
-    commentRanges.push([m.index, m.index + m[0].length]);
-  }
-  const insideComment = (offset) => commentRanges.some(([a, b]) => offset >= a && offset < b);
+  const ranges = commentRanges(text);
+  const insideComment = (offset) => isInsideComment(ranges, offset);
 
   const fenceRe = /^[ \t]*```[ \t]*ops[ \t]*\r?\n([\s\S]*?)^[ \t]*```[ \t]*$/gm;
   let m;
@@ -219,6 +251,12 @@ export function setHeader(text, name, value) {
   if (!re.test(text)) {
     return { error: `set-header: no "**${name}:**" header in the spec to set` };
   }
+  // The domain is the SPEC's (bare bold header). The list form
+  // (`- **Status:** proposed`) is a proposal's or an ADR's, whose Status
+  // has a lifecycle of its own (proposed -> applied, accepted, superseded).
+  const listForm = /^\s*-/.test(text.match(re)?.[1] ?? "");
+  const domain = listForm ? null : headerValueError(name, value);
+  if (domain) return { error: `set-header: ${domain}` };
   const next = text.replace(re, (_m, prefix) => `${prefix} ${value}`.replace(/\s+$/, ""));
   return { text: next, summary: `set ${name}: ${value}` };
 }
@@ -273,6 +311,8 @@ export function setCriterionMark(text, n, markRaw) {
   const item = loc.items.find((it) => it.n === n);
   if (!item) return { error: `set-criterion: no criterion #${n} found` };
   const mark = markRaw.replace(/^\[|\]$/g, "").trim();
+  const domain = criterionMarkError(mark);
+  if (domain) return { error: `set-criterion: ${domain}` };
   const line = loc.lines[item.lineIndex];
   let next;
   if (/\[[^\]]*\]/.test(line)) {
@@ -454,6 +494,11 @@ export function appendCriterion(text, value) {
   if (loc.items.length === 0) {
     return { error: "append-criterion: no existing numbered criterion to append after" };
   }
+  const leadingMark = String(value).match(/^\s*\[([^\]]*)\]/);
+  if (leadingMark) {
+    const domain = criterionMarkError(leadingMark[1]);
+    if (domain) return { error: `append-criterion: ${domain}` };
+  }
   const last = loc.items[loc.items.length - 1];
   const nextN = Math.max(...loc.items.map((it) => it.n)) + 1;
   loc.lines.splice(endOfItem(loc.lines, last.lineIndex) + 1, 0, `${last.indent}${nextN}. ${value}`);

package/src/lib/templates-model.js

@@ -0,0 +1,262 @@
+// @ts-check
+// The template-shape FINDINGS.
+//
+// `doctor` reports these as one of its rows and used to import them out of
+// `commands/templates.js` (audit finding F7). Collecting is not rendering, so
+// the collection lives here and both surfaces read it.
+import path from "node:path";
+import { exists, isDir, isFile, lineCount, read, relPath, walk, write } from "./fs-ops.js";
+import { adapterFiles, isHubPointer, listAdapterNames } from "./adapters.js";
+import { readTemplate } from "./templates.js";
+import { PLAYBOOKS } from "./playbook.js";
+import { COMMAND_META, COMMAND_NAMES, SURFACE_LINE_BUDGET, surfaceBlock, surfaceMarkdown, findSurfaceBlock } from "./commands.js";
+import { declaredBudget } from "./runtime.js";
+import { agentsMdBudget } from "./validation-model.js";
+/**
+ * The surface-block budget: how many lines the generated block spends, the
+ * ceiling it spends them against, and what is left.
+ *
+ * This number is COUPLED to `agents-md-lines`: the block is written into
+ * AGENTS.md, so one command added to the catalog spends a line of both.
+ * Every caller that reports on it reads it HERE, so `templates check` and
+ * `doctor` can never quote two different sizes for one block — the second
+ * count is how the two AGENTS.md numbers drifted before change 0059, and
+ * this budget had no owner at all until 0072.
+ *
+ * @param {string|null} [projectRoot] The project whose contract may declare
+ *   the ceiling; omit to measure against the shipped default alone.
+ * @returns {{ used: number, budget: number, slack: number, declared: boolean }}
+ */
+export function surfaceBudget(projectRoot = null) {
+  const used = surfaceMarkdown().split("\n").length;
+  const { value: budget, declared } = projectRoot
+    ? declaredBudget(projectRoot, "surface-block-lines", SURFACE_LINE_BUDGET)
+    : { value: SURFACE_LINE_BUDGET, declared: false };
+  return { used, budget, slack: budget - used, declared };
+}
+
+// What one appended stub section costs AGENTS.md: a blank line, the heading,
+// a blank line and the fill-me comment. Kept beside the writer that emits
+// that shape (`templates update --write`) so the estimate and the write
+// cannot drift.
+export const STUB_SECTION_LINES = 4;
+
+/**
+ * What appending stub sections to AGENTS.md would cost, against what the
+ * file has left of its declared ceiling.
+ *
+ * `templates check` recommends the sections and `agents-md-lines` caps the
+ * file, and the two never spoke: following the recommendation on this very
+ * repository took AGENTS.md from 147 to 155 lines, past a ceiling `analyze`
+ * refuses to raise because the budget is declared OUTPUT. A recommendation
+ * that cannot say what it costs is a recommendation that sends you into
+ * another gate's refusal (change 0078).
+ *
+ * @param {string} projectRoot
+ * @param {string[]} missing The recommended headings AGENTS.md does not have.
+ * @returns {{ cost: number, slack: number, fits: boolean, over: number }}
+ */
+export function agentsSectionCost(projectRoot, missing) {
+  const cost = missing.length * STUB_SECTION_LINES;
+  const { slack } = agentsMdBudget(projectRoot);
+  return { cost, slack, fits: cost <= slack, over: Math.max(0, cost - slack) };
+}
+// Recommended sections per file kind. Adopters whose files lack these
+// headings get a warning from `templates check`; they are recommendations,
+// not hard requirements (validate handles the hard requirements).
+export const AGENTS_SECTIONS = [
+  "## Stack",
+  "## Commands",
+  "## Repository structure",
+  "## Conventions and boundaries",
+  "## How to read context",
+];
+export const INDEX_FIELDS = ["$schema_version", "project", "artifacts"];
+export const PRODUCT_SECTIONS = [
+  "## Vision",
+  "## Problem",
+  "## Target users",
+  "## Scope",
+  "## Success criteria",
+];
+
+// The findings `templates check` reports, as structured records with an
+// executable remedy. Exported so a test can seed each finding, run the
+// remedy it names, and assert the finding clears — a remedy that cannot
+// resolve its own finding is not a remedy (C2).
+export function collectFindings(projectRoot) {
+  const findings = [];
+  const ok = [];
+
+
+  // AGENTS.md sections
+  const agentsPath = path.join(projectRoot, "AGENTS.md");
+  if (isFile(agentsPath)) {
+    const text = read(agentsPath);
+    const missingSections = AGENTS_SECTIONS.filter((h) => !hasHeading(text, h));
+    const budget = agentsSectionCost(projectRoot, missingSections);
+    for (const heading of AGENTS_SECTIONS) {
+      if (hasHeading(text, heading)) {
+        ok.push(`AGENTS.md: ${heading}`);
+        continue;
+      }
+      // The recommendation names its price. When the stubs do not fit, the
+      // remedy names the CUT first — appending them anyway would clear this
+      // finding by breaching a ceiling `analyze` refuses to raise, which is
+      // one gate sending you into another's refusal.
+      findings.push({
+        message: `AGENTS.md missing recommended section "${heading}"` +
+          (budget.fits
+            ? ``
+            : ` — the ${missingSections.length} missing stub(s) cost ${budget.cost} lines and ` +
+              `AGENTS.md has ${budget.slack} left of its declared ceiling`),
+        remedy: budget.fits
+          ? "doctrina templates update --write"
+          : `cut ${budget.over} line(s) of prose from AGENTS.md, then \`doctrina templates update --write\``,
+      });
+    }
+    // Command-surface block: present and current vs the installed catalog.
+    const block = findSurfaceBlock(text);
+    if (!block) {
+      findings.push({ message: "AGENTS.md has no doctrina:surface block — agents discover commands through this file", remedy: "doctrina templates update --write" });
+    } else if (normalizeBlock(text.slice(block.start, block.end)) !== normalizeBlock(surfaceBlock())) {
+      findings.push({ message: "AGENTS.md doctrina:surface block is stale vs the installed CLI", remedy: "doctrina templates update --write" });
+    } else {
+      ok.push("AGENTS.md: doctrina:surface block current");
+    }
+  } else {
+    findings.push({ message: "AGENTS.md missing at project root", remedy: "doctrina init --force" });
+  }
+
+  // product.md sections
+  const productPath = path.join(projectRoot, ".doctrina", "product.md");
+  if (isFile(productPath)) {
+    const text = read(productPath);
+    for (const heading of PRODUCT_SECTIONS) {
+      if (hasHeading(text, heading)) ok.push(`product.md: ${heading}`);
+      else findings.push({ message: `.doctrina/product.md missing recommended section "${heading}"`, remedy: "doctrina templates update --write" });
+    }
+  } else {
+    findings.push({ message: ".doctrina/product.md missing", remedy: "doctrina init --force" });
+  }
+
+  // Installed agent adapters: a HUB POINTER file must still reference
+  // AGENTS.md (that is why one `upgrade --write` refresh of the hub reaches
+  // every installed agent). Only files whose template declares the
+  // {{AGENTS_MD_PATH}} token are pointers; a slash-command shim reaches the
+  // hub through its parent pointer file and is not checked (C2).
+  for (const name of listAdapterNames(projectRoot)) {
+    const spec = adapterFiles(projectRoot, name);
+    if (!spec) continue;
+    for (const file of spec.files) {
+      const installed = path.join(projectRoot, file.relativePath);
+      if (!isFile(installed)) continue; // not installed — nothing to check
+      if (!isHubPointer(file)) continue; // command shim, not a pointer
+      if (read(installed).includes("AGENTS.md")) {
+        ok.push(`adapter ${file.relativePath}: points at AGENTS.md`);
+      } else {
+        findings.push({
+          message: `adapter ${file.relativePath} no longer references AGENTS.md — agents loading it will miss the hub`,
+          // Executable and verified: `adapter add --force` rewrites exactly
+          // this file from its template. A remedy that cannot resolve the
+          // finding it is attached to is not a remedy (C2).
+          remedy: `doctrina adapter add ${name} --force`,
+        });
+      }
+    }
+  }
+
+  // M2: a command that cannot state its trigger has not earned a place on
+  // the surface. The block is an agent's only discovery surface, so both
+  // fields are required and the block has a declared size budget.
+  for (const name of COMMAND_NAMES) {
+    const meta = COMMAND_META[name];
+    if (!meta || !meta.purpose || !meta.when) {
+      findings.push({
+        message: `command "${name}" declares no ${!meta ? "purpose or when" : (!meta.purpose ? "purpose" : "when")} — the surface block cannot say when to reach for it`,
+        remedy: null,
+      });
+    }
+  }
+  const surface = surfaceBudget(projectRoot);
+  if (surface.used > surface.budget) {
+    findings.push({
+      message: `the generated surface block is ${surface.used} lines (budget ${surface.budget}) — cut commands rather than raising the budget`,
+      remedy: null,
+    });
+  } else {
+    ok.push(`surface block within budget (${surface.used}/${surface.budget} lines)`);
+  }
+
+  // index.json schema fields
+  const indexPath = path.join(projectRoot, ".doctrina", "index.json");
+  if (isFile(indexPath)) {
+    try {
+      const idx = JSON.parse(read(indexPath));
+      for (const field of INDEX_FIELDS) {
+        if (idx[field] !== undefined) ok.push(`index.json: ${field}`);
+        else findings.push({ message: `.doctrina/index.json missing field "${field}"`, remedy: "doctrina templates update --write" });
+      }
+      if (idx.$schema_version && idx.$schema_version !== "0.1.0") {
+        findings.push({ message: `.doctrina/index.json $schema_version is "${idx.$schema_version}" (expected "0.1.0")`, remedy: null });
+      }
+    } catch (err) {
+      findings.push({ message: `.doctrina/index.json failed to parse: ${err.message}`, remedy: null });
+    }
+  } else {
+    findings.push({ message: ".doctrina/index.json missing", remedy: "doctrina index rebuild" });
+  }
+
+  // Output
+  // The playbooks (change 0038). A playbook is the procedure the agent
+  // actually executes, and since it became a template an adopter can replace
+  // it — which means it can also be MISSING or malformed, and a playbook that
+  // does not render is a broken session, not a cosmetic gap. Each is checked
+  // for resolution and for the shape every playbook must have: a title line
+  // and the ordered steps.
+  for (const name of PLAYBOOKS) {
+    const rel = `playbooks/${name}.md.template`;
+    let body = null;
+    try {
+      body = readTemplate(projectRoot, rel).body;
+    } catch {
+      body = null;
+    }
+    if (body === null) {
+      findings.push({
+        message: `playbook "${name}" does not resolve (${rel} is missing from the project AND the installed CLI)`,
+        remedy: "reinstall doctrina-cli, or restore .doctrina/templates/" + rel,
+      });
+      continue;
+    }
+    const problems = [];
+    if (body.trim() === "") problems.push("it is empty");
+    if (!/^\s*1\./m.test(body)) problems.push("it has no numbered first step");
+    for (const [open, close] of [["[[c]]", "[[/c]]"], ["[[g]]", "[[/g]]"], ["[[b]]", "[[/b]]"], ["[[y]]", "[[/y]]"]]) {
+      const opens = body.split(open).length - 1;
+      const closes = body.split(close).length - 1;
+      if (opens !== closes) problems.push(`${opens} ${open} spans but ${closes} ${close}`);
+    }
+    if (problems.length > 0) {
+      findings.push({
+        message: `playbook "${name}" is malformed: ${problems.join("; ")}`,
+        remedy: `fix .doctrina/templates/${rel}, or delete it to fall back to the bundled playbook`,
+      });
+    } else {
+      ok.push(`playbook: ${name}`);
+    }
+  }
+
+  return { findings, ok };
+}
+
+export function normalizeBlock(s) {
+  return s.replace(/\r\n/g, "\n").replace(/[ \t]+$/gm, "").trim();
+}
+
+export function hasHeading(text, heading) {
+  // Match an exact h2 heading at line start (case-insensitive for the body
+  // after "## ", so "## Vision" matches "## VISION" or "## vision" too).
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped}\\b`, "im").test(text);
+}

package/src/lib/trace-model.js

@@ -0,0 +1,95 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { specHeader } from "./scan.js";
+
+// The trace MODEL: product intent anchors, the specs that realize them, and
+// the provenance arithmetic over the two. Lifted out of `commands/trace.js`
+// so `status`, `review` and the snapshot read it directly instead of
+// importing out of a command module (audit finding F7). Nothing here prints.
+
+const ANCHOR_RE = /[A-Z]+\d+/g;
+
+// 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.
+export 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;
+}
+
+// Anchor ids declared MORE THAN ONCE in product.md (change 0108). The
+// collector above keeps the first bullet per id, which is right for the
+// graph and wrong as the only reading: the second intent under the same id
+// vanished from trace, why, intent list and every pack, with `trace
+// --strict` green. Returned as {id, lines} so trace can name both bullets.
+export function collectAnchorDuplicates(projectRoot) {
+  const productPath = path.join(projectRoot, ".doctrina", "product.md");
+  if (!isFile(productPath)) return [];
+  const lines = new Map();
+  const rows = read(productPath).split(/\r?\n/);
+  for (let i = 0; i < rows.length; i++) {
+    const m = rows[i].match(/^\s*[-*]\s+\[([A-Z]+\d+)\]\s+/);
+    if (!m) continue;
+    if (!lines.has(m[1])) lines.set(m[1], []);
+    lines.get(m[1]).push(i + 1);
+  }
+  return [...lines].filter(([, at]) => at.length > 1).map(([id, at]) => ({ id, lines: at }));
+}
+
+export 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;
+}

package/src/lib/triage-model.js

@@ -0,0 +1,121 @@
+// @ts-check
+import { fold } from "./lexicon.js";
+// The lane CLASSIFIER (ADR 0024).
+//
+// `work` asks the same question `triage` answers — is this request PRODUCT,
+// RUNTIME or CHORE — and imported the answer out of the command module
+// (audit finding F7). One classifier, read by both.
+
+// The prompt is FOLDED before matching (change 0107): accents stripped,
+// lower-cased — the same `fold` `work` and `context --for` retrieve with
+// (ADR 0040). Every pattern below is written in folded (ASCII) form, and
+// the Portuguese half of each list sits next to the English half: the
+// lexicon was English-only, so "the build is broken in CI, DATABASE_URL
+// never reaches the process" was held as RUNTIME with exit 3 while the
+// same sentence in Portuguese opened a change. A project whose prompts
+// arrive in Portuguese (this one) had no guard at all.
+export 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],
+  // pt
+  [3, /\b(atualizar (a |as )?dependencia|dependencias|fixar (a )?versao)\b/i],
+  [2, /\b(renomear|mover|reorganizar|refatorar|arrumar|limpeza|limpar|formatar|formatacao)\b/i],
+  [2, /\b(erro de digitacao|comentario|so (a )?doc(umentacao)?)\b/i],
+  [2, /\b(ja (esta )?(especificad[oa]|na spec)|so (a )?fiacao|sem mudanca de comportamento)\b/i],
+];
+export 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],
+  // pt
+  [3, /\b(adicionar|introduzir|suportar|permitir|habilitar|implementar|construir|criar)\b/i],
+  [3, /\b(deve|devera|requisito|aceite|aceitacao|criterio)\b/i],
+  [3, /\b(declarar|declarando|documentar|documentando|registrar|registrando|especificar|especificando|definir|definindo)\b/i],
+  [2, /\b(nov[oa] (feature|funcionalidade|capability|capacidade|comando|endpoint|tela|fluxo))\b/i],
+  [2, /\b(usuari[oa]s? (pode|podem|deve|devem|quer|querem)|para que|de modo que|a fim de)\b/i],
+  [1, /\b(mudanca|comportamento)\b/i],
+];
+// 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.
+export 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],
+  // pt
+  [3, /\b(execucao d[oa]s? actions|esteira)\b/i],
+  [3, /\b(variavel de ambiente|variaveis de ambiente|segredo|segredos)\b/i],
+  [3, /\b(0 (testes?|cenarios?|casos?)|nenhum (teste|cenario|caso) (rodou|correu|executou)|(rodou|correu|executou) nada|(execucao|suite|resumo) vazi[oa])\b/i],
+  [2, /\b(codigo de saida|resumo d[oa] (step|etapa)|artefato (ausente|faltando|sumiu))\b/i],
+  [2, /\b(verde mas|passa mas|silenciosamente|em silencio|nunca (dispara|aplica|chega|rodou|correu|executou))\b/i],
+  [2, /\b(intermitente|estourou o tempo|trava|travou|crashou|build (quebrad[oa]|falhando|falhou))\b/i],
+  [2, /\b(seletor|filtro|despacho)\b/i],
+  [1, /\b(configuracao|fiacao|implantacao)\b/i],
+  [1, /\b(depurar|diagnostic(o|ar)|investigar|por que (esta|e|nao)|nao funciona|nao esta funcionando)\b/i],
+];
+
+export function classify(prompt) {
+  const text = fold(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 };
+}

package/src/lib/usage.js

@@ -1,10 +1,12 @@
 // @ts-check
 // Audit item M8: instrument the command surface before shrinking it.
 //
-// The surface is 36 commands and 59 operations. The audit's charge is that
-// some of them exist because they were easy to add, not because anybody
-// reaches for them — and the honest way to find out which is to MEASURE,
-// not to guess from the outside. Guessing is how `prime`, `handoff` and
+// How big the surface is, this module does not say: `COMMAND_NAMES` and
+// `OPERATIONS` in lib/commands.js own that number, and a copy of it here
+// would be one more count to rot (change 0059 found four, all disagreeing).
+// The audit's charge is that some of those commands exist because they were
+// easy to add, not because anybody reaches for them — and the honest way to
+// find out which is to MEASURE, not to guess from the outside. Guessing is how `prime`, `handoff` and
 // `doctor` were nearly cut in 0.13.0, right before the operator review
 // found they had gone unused only because AGENTS.md never named them.
 //