doctrina-cli 0.20.0 → 0.22.0

package/src/lib/prompt.js

@@ -25,7 +25,7 @@ export async function ask(question, { defaultValue = "" } = {}) {
 // Ask for consent. Off a terminal there is nobody to ask, so the answer is
 // `whenNonInteractive` — which callers set to false for destructive
 // operations: silence is not consent.
-export async function confirm(question, { defaultYes = false, whenNonInteractive = null } = {}) {
+export async function confirm(question, { defaultYes = false, whenNonInteractive = /** @type {boolean | null} */ (null) } = {}) {
   if (!isInteractive()) {
     return whenNonInteractive === null ? defaultYes : whenNonInteractive;
   }

package/src/lib/properties.js

@@ -0,0 +1,149 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { parseAcceptanceCriteria } from "./criteria.js";
+
+// A REQUIREMENT THAT IS AN INVARIANT ASKS FOR A PROPERTY (change 0254).
+//
+// "The system shall never return a code already in use" is a claim about
+// EVERY input, and the evidence a criterion cited for it was an example
+// test: three inputs somebody thought of. Coverage called that proven. A
+// property-based test generates the inputs — hundreds of them, the ones
+// nobody thought of — which is the kind of proof a universal claim wants.
+//
+// Kiro derives such tests from EARS requirements with a model. The CLI has
+// none and does not pretend to: it does the two deterministic halves. It
+// says WHICH requirements read as invariants (`coverage --properties`), and
+// it refuses to count a criterion marked `[property]` as proven unless the
+// test it cites really is a property-based one. Writing the property is the
+// agent's work, as writing the test always was.
+
+/** Marks a criterion whose proof must generate its inputs. */
+export const PROPERTY_MARKER = /^property\b/;
+
+/** What a property-based test looks like, per library. */
+const LIBRARIES = [
+  { name: "Hypothesis", re: /@given\s*\(|\bfrom\s+hypothesis\b|\bimport\s+hypothesis\b/ },
+  { name: "fast-check", re: /\bfc\.(assert|property|asyncProperty)\s*\(|["']fast-check["']/ },
+  { name: "jqwik", re: /@Property\b|\bnet\.jqwik\b/ },
+  { name: "proptest", re: /\bproptest!\s*\{/ },
+  { name: "quickcheck", re: /\bquickcheck!\s*\{|#\[quickcheck\]|\bquickCheck\b/ },
+  { name: "rapid", re: /\brapid\.Check\s*\(|\bquick\.Check\s*\(/ },
+  { name: "FsCheck", re: /\bProp\.ForAll\b|\[Property\b/ },
+  { name: "ScalaCheck", re: /\bforAll\s*[({]/ },
+];
+
+/** The property library a test file uses, or null when it generates nothing. */
+export function propertyLibraryIn(text) {
+  return LIBRARIES.find((lib) => lib.re.test(String(text)))?.name ?? null;
+}
+
+// The shapes a universal claim takes in a requirement, with the property
+// each one suggests. English and Portuguese, as the specs are.
+const SHAPES = [
+  { id: "round-trip",
+    re: /\b(round[- ]trip|and back\b|restor\w+ (?:the |its )?(?:original|same|previous)|revers(?:ible|ibly|es)\b|decod\w+|deserializ\w+|ida e volta|restaura\w* (?:o |a )?(?:original|mesm[oa]|anterior))/i,
+    property: "for any input x, undoing what was done to x gives x back" },
+  { id: "idempotence",
+    re: /\b(idempoten\w+|twice|a second time|more than once|applied again|run again|duas vezes|de novo|mais de uma vez|outra vez)\b/i,
+    property: "for any input x, doing it twice leaves what doing it once left" },
+  { id: "bound",
+    re: /\b(at most|at least (?!one\b)|no more than|no fewer than|not exceed|never exceed|within (?:\d|(?:\S+ ){0,3}(?:budget|limit|threshold|ratio|bound|quota|window|deadline)\b)|between \d|no máximo|pelo menos (?!um\b|uma\b)|no mínimo|não excede|entre \d)/i,
+    property: "for any input, the result stays inside the stated bound" },
+  { id: "uniqueness",
+    re: /(?<![\w-])(unique|distinct(?!ive| from)|no two|never the same|(?:not|never) .{0,40}already (?:in use|used|taken|issued|exist\w*|registered)|único|única|distint\w+|nunca .{0,20}repet\w+|já (?:em uso|usad\w+|exist\w+))/i,
+    property: "for any sequence of inputs, no two results collide" },
+  { id: "order",
+    re: /\b(sorted|ordered|in order(?! to\b)|ascending|descending|monoton\w+|ordenad\w+|em ordem|crescente|decrescente)\b/i,
+    property: "for any input, the output is in the stated order" },
+  { id: "invariant",
+    re: /\b(always|never|for every|for any|for all|whatever|sempre|nunca|para todo|para toda|para qualquer|qualquer que seja)\b/i,
+    property: "for any input, the stated condition holds" },
+];
+
+/** Every requirement bullet under `## Requirements`, with its section and ordinal. */
+export function requirementsOf(specText) {
+  const out = [];
+  let inside = false;
+  let section = null;
+  let n = 0;
+  let cur = null;
+  for (const line of String(specText).split(/\r?\n/)) {
+    if (/^##\s+/.test(line) && !/^###/.test(line)) {
+      inside = /^##\s+Requirements\b/i.test(line);
+      section = null;
+      cur = null;
+      continue;
+    }
+    if (!inside) continue;
+    const h = line.match(/^###\s+(\S+)/);
+    if (h) {
+      section = h[1].toLowerCase().replace(/[^a-z-]/g, "").split("-")[0];
+      n = 0;
+      cur = null;
+      continue;
+    }
+    if (section && /^-\s+\S/.test(line)) {
+      n += 1;
+      cur = { section, n, text: line.replace(/^-\s+/, "").trim() };
+      out.push(cur);
+    } else if (cur && /^\s+\S/.test(line)) {
+      cur.text += " " + line.trim();
+    } else if (line.trim() === "") {
+      cur = null;
+    }
+  }
+  return out;
+}
+
+/** The first shape a requirement's text takes, or null when it states no universal claim. */
+export function propertyShape(text) {
+  const prose = String(text).replace(/`[^`]*`/g, "");
+  return SHAPES.find((s) => s.re.test(prose)) ?? null;
+}
+
+/** The property library this project's manifests point at, with how sure that is. */
+export function projectPropertyLibrary(projectRoot) {
+  const text = (/** @type {string} */ rel) => (isFile(path.join(projectRoot, rel)) ? read(path.join(projectRoot, rel)) : "");
+  const py = text("pyproject.toml") + text("requirements.txt") + text("requirements-dev.txt") + text("setup.cfg") + text("Pipfile");
+  const js = text("package.json");
+  if (/\bhypothesis\b/i.test(py)) return { name: "Hypothesis", declared: true };
+  if (/"fast-check"/.test(js)) return { name: "fast-check", declared: true };
+  if (py.trim() !== "") return { name: "Hypothesis", declared: false };
+  if (js.trim() !== "") return { name: "fast-check", declared: false };
+  if (isFile(path.join(projectRoot, "pom.xml")) || isFile(path.join(projectRoot, "build.gradle")) || isFile(path.join(projectRoot, "build.gradle.kts"))) return { name: "jqwik", declared: false };
+  if (isFile(path.join(projectRoot, "Cargo.toml"))) return { name: "proptest", declared: false };
+  if (isFile(path.join(projectRoot, "go.mod"))) return { name: "rapid", declared: false };
+  return null;
+}
+
+/**
+ * Per capability: the requirements that read as invariants, and how many of
+ * its criteria are already properties.
+ * @param {string} projectRoot
+ * @param {{ only?: Set<string> | null }} [opts]
+ */
+export function propertyCandidates(projectRoot, { only = /** @type {Set<string> | null} */ (null) } = {}) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const out = [];
+  if (!isDir(specsDir)) return out;
+  for (const cap of readdirSync(specsDir).sort()) {
+    if (only && !only.has(cap)) continue;
+    const file = path.join(specsDir, cap, "spec.md");
+    if (!isFile(file)) continue;
+    const text = read(file);
+    const candidates = [];
+    for (const req of requirementsOf(text)) {
+      const shape = propertyShape(req.text);
+      if (shape) candidates.push({ ref: `${req.section} ${req.n}`, text: req.text, shape: shape.id, property: shape.property });
+    }
+    // The specific shapes first: "at most", "twice", "and back" name the
+    // property to write; a bare "always" only says that there is one.
+    const rank = (/** @type {string} */ id) => SHAPES.findIndex((s) => s.id === id);
+    candidates.sort((a, b) => rank(a.shape) - rank(b.shape));
+    const properties = parseAcceptanceCriteria(text).filter((row) => row.marker !== null && PROPERTY_MARKER.test(row.marker)).length;
+    out.push({ cap, candidates, properties });
+  }
+  return out;
+}

package/src/lib/runtime.js

@@ -203,7 +203,7 @@ export function readWorkflowEnv(text) {
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
     if (!line.trim() || /^\s*#/.test(line)) continue;
-    const indent = line.match(/^\s*/)[0].length;
+    const indent = (line.match(/^\s*/) ?? [""])[0].length;
 
     if (/^jobs:\s*$/.test(line)) {
       sawJobs = true;
@@ -681,17 +681,29 @@ function compileGlob(glob) {
  */
 export function filesMatching(projectRoot, glob) {
   const re = globToRegExp(glob);
+  const text = String(glob);
+  const segments = text.split("/");
   // Walk from the deepest literal directory prefix so a narrow glob never
-  // costs a full-tree walk.
-  const prefix = String(glob).split("/").filter((s) => !/[*?]/.test(s));
+  // costs a full-tree walk. The prefix ends at the first segment that is a
+  // pattern: taking every literal segment, wherever it stood, let
+  // `a/*/b/c.js` start from `a/b` when that directory existed.
   let base = projectRoot;
-  for (const seg of prefix) {
+  let consumed = 0;
+  for (const seg of segments) {
+    if (/[*?{]/.test(seg)) break;
     const next = path.join(base, seg);
-    if (isDir(next)) base = next;
-    else break;
+    if (!isDir(next)) break;
+    base = next;
+    consumed += 1;
   }
   if (!isDir(base)) return [];
-  return walk(base).filter((f) => re.test(relPath(projectRoot, f).replaceAll("\\", "/")));
+  // ...and no deeper than the pattern can reach (change 0249). A pattern
+  // with no `**` names a fixed number of levels; `tsconfig.json` names one.
+  // Without the bound, each root-level file a spec declared walked the whole
+  // repository — `node_modules` and `.git` included — to find it.
+  const spans = text.endsWith("/") || segments.includes("**") || /\{[^}]*\/[^}]*\}/.test(text);
+  const depth = spans ? Infinity : Math.max(1, segments.length - consumed);
+  return walk(base, { depth }).filter((f) => re.test(relPath(projectRoot, f).replaceAll("\\", "/")));
 }
 
 // ---------------------------------------------------------------------------

package/src/lib/scan.js

@@ -24,6 +24,7 @@ export function listHeader(text, name) {
   return getHeader(text, name);
 }
 
+/** @returns {string[]} */
 export function parseDependsOn(text) {
   const raw = specHeader(text, "Depends on");
   if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
@@ -77,6 +78,7 @@ function dirEntries(dir) {
 // The capabilities an ADR governs, from its optional "Scope:" header
 // (M4). Returns [] when absent, "n/a", or "—" — an unscoped ADR is global
 // and belongs in every pack, which is what keeps this backward compatible.
+/** @returns {string[]} */
 export function parseAdrScope(text) {
   const raw = listHeader(text, "Scope");
   if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
@@ -175,7 +177,7 @@ export function changeEntry(proposal, id, prev, date) {
 // carried the lane: an archived change lost the lane it was born in, so the
 // report's "Lanes" section counted the whole history as unknown (change
 // 0192), which is the question change 0042 recorded the lane to answer.
-export function archivedChangeEntry(proposal, { id, archiveName, applied, specsAffected, prev = null, title = undefined }) {
+export function archivedChangeEntry(proposal, { id, archiveName, applied, specsAffected, prev = /** @type {any} */ (null), title = /** @type {string | null | undefined} */ (undefined) }) {
   return {
     id,
     title: (title === undefined ? parseChangeTitle(proposal) : title) ?? prev?.title ?? id,
@@ -213,12 +215,12 @@ export function deriveIndex(projectRoot, current) {
         version: "0.1.0",
         last_updated: date,
       },
-      specs: [],
-      decisions: [],
-      changes: [],
-      changes_archive: [],
-      skills: [],
-      contracts: [],
+      specs: /** @type {any[]} */ ([]),
+      decisions: /** @type {any[]} */ ([]),
+      changes: /** @type {any[]} */ ([]),
+      changes_archive: /** @type {any[]} */ ([]),
+      skills: /** @type {any[]} */ ([]),
+      contracts: /** @type {any[]} */ ([]),
     },
   };
 
@@ -533,7 +535,10 @@ export function collectStagedIndexDrift(projectRoot) {
   const nothing = { ok: true, applicable: false, missing: [], unindexed: [], reason: null };
   if (!isRepo(projectRoot)) return { ...nothing, reason: "not a git repository" };
 
-  const blob = git(projectRoot, ["show", ":.doctrina/index.json"]);
+  // `:./` reads the path from the current directory. A bare `:.doctrina/…`
+  // is read from the top of the repository, so for a project in a subfolder
+  // the check answered "no staged index" for every commit (change 0250).
+  const blob = git(projectRoot, ["show", ":./.doctrina/index.json"]);
   if (blob.state !== GIT_STATE.OK || !blob.stdout.trim()) {
     // Not staged at all — this commit does not carry an index, so it cannot
     // carry one that disagrees with itself.

package/src/lib/shell.js

@@ -0,0 +1,45 @@
+// @ts-check
+import process from "node:process";
+
+// THE COMMANDS THE CLI PRINTS ARE RUN AS PRINTED (fourth audit, change 0235).
+//
+// `next`, `delivery status`, the playbooks and the hub hand an agent a line
+// to paste into its shell: `cd <repo> && doctrina work "<title>" --delivery
+// <id>`. The title comes from the tracker — text the delivery playbook calls
+// data, never an instruction — and it was interpolated between double quotes
+// as it came: a story titled `Fix $(curl … | sh)` became a command the agent
+// ran, and a repository under `~/my api/` became a `cd` into `~/my`.
+
+// Inside double quotes a POSIX shell still expands these.
+const DOUBLE_QUOTE_UNSAFE = /["`$\\!]/;
+const BARE_PATH = /^[A-Za-z0-9_./:\\~+@%=,-]+$/;
+
+/**
+ * One shell argument, quoted so the shell reads it back verbatim. Plain text
+ * keeps the double quotes every surface has always printed; text a double
+ * quote would still expand is single-quoted — POSIX `'\''` for an embedded
+ * quote, PowerShell's `''` on Windows.
+ * @param {string} value
+ * @param {NodeJS.Platform} [platform]
+ */
+export function qarg(value, platform = process.platform) {
+  const s = String(value ?? "");
+  if (!DOUBLE_QUOTE_UNSAFE.test(s)) return `"${s}"`;
+  const inner = platform === "win32" ? s.replace(/'/g, "''") : s.replace(/'/g, "'\\''");
+  return `'${inner}'`;
+}
+
+/**
+ * A path as a shell argument: bare when nothing in it needs quoting.
+ * @param {string} dir
+ * @param {NodeJS.Platform} [platform]
+ */
+export function qpath(dir, platform = process.platform) {
+  const s = String(dir ?? "");
+  return BARE_PATH.test(s) ? s : qarg(s, platform);
+}
+
+/** `cd <dir> && <command>`, with the directory quoted when it must be. */
+export function cdThen(dir, command) {
+  return `cd ${qpath(dir)} && ${command}`;
+}

package/src/lib/snapshot.js

@@ -155,7 +155,11 @@ export function openChanges(projectRoot) {
     // The capabilities its deltas target — what `prime` turns into the
     // exact read command for the change (change 0217).
     const capabilities = deltaCapabilities(path.join(changesDir, id));
-    out.push({ id, title, status, tasksDone, tasksTotal, unchecked, date, ageDays: ageInDays(date), capabilities });
+    // The delivery a change belongs to (change 0226): a session opened in the
+    // repository — an executor's, or a human's — sees it is one part of a
+    // larger item of work, not a change on its own.
+    const delivery = proposal ? (listHeader(proposal, "Delivery") ?? null) : null;
+    out.push({ id, title, status, tasksDone, tasksTotal, unchecked, date, ageDays: ageInDays(date), capabilities, delivery });
   }
   return out;
 }

package/src/lib/spec-ops.js

@@ -50,7 +50,7 @@ const HEADER_RE = (name) =>
 // 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"];
+export const CRITERION_MARKS = ["verified", "unverified", "orchestration", "property"];
 
 /** The state word of a header/mark value: the first token, note stripped. */
 export function stateWord(value) {
@@ -440,7 +440,7 @@ function locateRequirements(text) {
     if (h) {
       if (current) current.endIndex = i;
       const token = SECTIONS[h[1].toLowerCase().replace(/[^a-z-]/g, "")] ?? null;
-      current = { headingIndex: i, endIndex: lines.length, bullets: [] };
+      current = { headingIndex: i, endIndex: lines.length, bullets: /** @type {number[]} */ ([]) };
       if (token) sections[token] = current;
       continue;
     }

package/src/lib/task-card.js

@@ -1,9 +1,12 @@
 // @ts-check
 import path from "node:path";
-import { isFile, read } from "./fs-ops.js";
-import { parseChangeTitle, parseChecklist } from "./doc-model.js";
-import { listHeader, deltaCapabilities } from "./scan.js";
-import { sliceSpec } from "./context-slice.js";
+import { isDir, isFile, read, walk } from "./fs-ops.js";
+import { getSection, parseChangeTitle, parseChecklist } from "./doc-model.js";
+import { listHeader, deltaCapabilities, parseAdrScope } from "./scan.js";
+import { extractOps } from "./spec-ops.js";
+import { findWorkspace } from "./workspace.js";
+import { deliveryPath, resolveDeliveryId, sectionText } from "./delivery.js";
+import { sliceSpec, withoutComments } from "./context-slice.js";
 import { terms } from "./lexicon.js";
 
 // A TASK CARD (change 0222, ADR 0030): one task of a change, carrying what
@@ -55,7 +58,7 @@ function firstParagraph(text, heading) {
  * open one. Null `card` with a reason when there is none to give.
  * @returns {{ card: null, reason: string } | { card: object, reason: null }}
  */
-export function taskCard(projectRoot, changeId, ordinal = null) {
+export function taskCard(projectRoot, changeId, ordinal = /** @type {number | null} */ (null)) {
   const changeDir = path.join(projectRoot, ".doctrina", "changes", changeId);
   const tasksPath = path.join(changeDir, "tasks.md");
   if (!isFile(tasksPath)) return { card: null, reason: "the change has no tasks.md" };
@@ -64,6 +67,10 @@ export function taskCard(projectRoot, changeId, ordinal = null) {
   let box;
   if (ordinal === null) {
     box = boxes.find((b) => !b.checked && !b.placeholder);
+    // Only scaffold boxes left is not "every task is ticked" (third audit,
+    // change 0234): the planner was told to review and close a change
+    // whose tasks no one had written.
+    if (!box && boxes.some((b) => !b.checked && b.placeholder)) return { card: null, reason: "tasks.md holds only the scaffold's placeholder boxes — write the tasks as cards first" };
     if (!box) return { card: null, reason: "every task is ticked — the change is ready for review and close" };
   } else {
     box = boxes.find((b) => b.ordinal === ordinal);
@@ -73,14 +80,40 @@ export function taskCard(projectRoot, changeId, ordinal = null) {
   // CRLF on a Windows checkout: the Why is read paragraph by paragraph.
   const proposal = isFile(path.join(changeDir, "proposal.md")) ? read(path.join(changeDir, "proposal.md")).replace(/\r\n/g, "\n") : "";
   const fields = cardFields(box.details);
-  const query = terms([box.text, ...box.details].join(" "));
+  // What this change DOES to each spec (change 0231). The slice below is
+  // the spec as it stands — the current truth, before apply — so the
+  // requirement the executor is there to implement lived only in the delta,
+  // and reached the card only if the planner copied it into a line by hand.
+  const changes = [];
+  for (const cap of deltaCapabilities(changeDir)) {
+    const delta = path.join(changeDir, "specs", cap, "delta.md");
+    if (!isFile(delta)) continue;
+    for (const op of extractOps(read(delta))) {
+      if (op.verb === "append-requirement") changes.push({ capability: cap, line: `adds ${/^[aeiou]/.test(op.section) ? "an" : "a"} ${op.section} requirement: ${op.value}` });
+      else if (op.verb === "replace-requirement") changes.push({ capability: cap, line: `replaces ${op.section} requirement ${op.n} with: ${op.value}` });
+      else if (op.verb === "remove-requirement") changes.push({ capability: cap, line: `removes ${op.section} requirement ${op.n}` });
+      else if (op.verb === "append-criterion") changes.push({ capability: cap, line: `adds the criterion: ${op.value}` });
+      else if (op.verb === "replace-criterion") changes.push({ capability: cap, line: `replaces criterion ${op.n} with: ${op.value}` });
+      else if (op.verb === "remove-criterion") changes.push({ capability: cap, line: `removes criterion ${op.n}` });
+    }
+  }
+  // The task's words AND what the change writes into the spec (second
+  // audit, change 0233): a card for "lock the account on the third wrong
+  // password" cut the spec's only /login requirement, because the task never
+  // said "login" — the delta it implements did. Requirements only: a
+  // criterion's "[unverified] … — verified by `…`" matched any spec's
+  // placeholder on the boilerplate alone.
+  const query = terms([box.text, ...box.details, parseChangeTitle(proposal) ?? "", ...changes.filter((ch) => / requirement[^:]*: /.test(ch.line)).map((ch) => ch.line.slice(ch.line.indexOf(": ") + 2))].join(" "));
   const slices = [];
   for (const cap of deltaCapabilities(changeDir)) {
     const rel = `.doctrina/specs/${cap}/spec.md`;
     const specPath = path.join(projectRoot, rel);
     if (!isFile(specPath)) continue;
-    const slice = sliceSpec(read(specPath), query, rel);
-    if (slice) slices.push({ capability: cap, ...slice });
+    // Nothing in the spec matched the task: the whole spec, as `context`
+    // gives it (change 0231). Dropping it left a card with no spec at all.
+    const text = read(specPath);
+    const slice = sliceSpec(text, query, rel);
+    slices.push(slice ? { capability: cap, ...slice } : { capability: cap, text: withoutComments(text) ?? text, kept: null, total: null, whole: true });
   }
   return {
     card: {
@@ -96,7 +129,67 @@ export function taskCard(projectRoot, changeId, ordinal = null) {
       fields,
       why: firstParagraph(proposal, "Why"),
       slices,
+      changes,
+      story: deliveryStory(projectRoot, listHeader(proposal, "Delivery")),
+      decisions: bindingDecisions(projectRoot, deltaCapabilities(changeDir)),
     },
     reason: null,
   };
 }
+
+// The story the change serves, when it belongs to a delivery (change 0231):
+// its acceptance criteria are what the work is checked against, and they
+// live in the workspace, where an executor opened in the repository never
+// looks.
+const STORY_MAX_CHARS = 1500;
+function deliveryStory(projectRoot, deliveryId) {
+  if (!deliveryId) return null;
+  const found = findWorkspace(projectRoot);
+  if (!found) return null;
+  const id = resolveDeliveryId(found.dir, deliveryId.trim());
+  if (!id || !isFile(deliveryPath(found.dir, id))) return null;
+  const story = sectionText(read(deliveryPath(found.dir, id)), "Story");
+  if (!story) return null;
+  return story.length > STORY_MAX_CHARS ? `${story.slice(0, STORY_MAX_CHARS).replace(/\s+\S*$/, "")} …` : story;
+}
+
+// The accepted decisions that bind the capabilities the change touches:
+// those whose Scope names one, and the unscoped ones that cite one. A card
+// the executor follows without them is how an implementation re-decides
+// what an ADR settled.
+function bindingDecisions(projectRoot, capabilities) {
+  const dir = path.join(projectRoot, ".doctrina", "decisions");
+  if (!isDir(dir) || capabilities.length === 0) return { list: [], more: 0 };
+  /** @type {Array<{ id: string, title: string, decision: string, rank: number }>} */
+  const found = [];
+  for (const f of walk(dir).sort()) {
+    const m = path.basename(f).match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(f).replace(/\r\n/g, "\n");
+    if ((listHeader(text, "Status") ?? "").trim().toLowerCase() !== "accepted") continue;
+    const scope = parseAdrScope(text);
+    const cites = (/** @type {string} */ cap) => new RegExp(`(^|[^a-z0-9-])${cap.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^a-z0-9-]|$)`, "im").test(text);
+    // An unscoped ADR is GLOBAL — it binds every capability, as `decision
+    // scope` documents and the context pack loads it (sixth audit, change
+    // 0237). The card bound one only when its text named the capability, so
+    // a repository-wide rule ("error codes are MAIUSCULAS_SNAKE") never
+    // reached the executor, who reads nothing else. Scoped first, then the
+    // global ones that name the capability, then the rest.
+    const rank = scope.length > 0 ? (capabilities.some((cap) => scope.includes(cap)) ? 0 : -1) : (capabilities.some(cites) ? 1 : 2);
+    if (rank < 0) continue;
+    const decision = (getSection(text, "Decision") ?? "").replace(/<!--[\s\S]*?-->/g, "").replace(/\s+/g, " ").trim();
+    found.push({
+      id: m[1],
+      title: text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m)?.[1]?.trim() ?? path.basename(f),
+      decision: decision.length > DECISION_EXCERPT ? `${decision.slice(0, DECISION_EXCERPT).replace(/\s+\S*$/, "")} …` : decision,
+      rank,
+    });
+  }
+  const sorted = found.sort((a, b) => a.rank - b.rank || a.id.localeCompare(b.id));
+  return { list: sorted.slice(0, DECISIONS_ON_CARD), more: Math.max(0, sorted.length - DECISIONS_ON_CARD) };
+}
+
+// How many binding decisions a card names, and how much of each it quotes.
+const DECISIONS_ON_CARD = 8;
+const DECISION_EXCERPT = 240;
+

package/src/lib/templates-model.js

@@ -5,6 +5,7 @@
 // `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 { loadConfig } from "./config.js";
 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";
@@ -28,7 +29,7 @@ import { agentsMdBudget } from "./validation-model.js";
  * @returns {{ used: number, budget: number, slack: number, declared: boolean }}
  */
 export function surfaceBudget(projectRoot = null) {
-  const used = surfaceMarkdown().split("\n").length;
+  const used = surfaceMarkdown(projectRoot ? loadConfig(projectRoot).surface : "full").split("\n").length;
   const { value: budget, declared } = projectRoot
     ? declaredBudget(projectRoot, "surface-block-lines", SURFACE_LINE_BUDGET)
     : { value: SURFACE_LINE_BUDGET, declared: false };
@@ -129,7 +130,7 @@ export function collectFindings(projectRoot) {
     const block = findSurfaceBlock(text);
     if (!block) {
       findings.push({ message: "AGENTS.md has no doctrina:surface block — agents discover commands through this file", remedy: "doctrina upgrade --write" });
-    } else if (normalizeBlock(text.slice(block.start, block.end)) !== normalizeBlock(surfaceBlock())) {
+    } else if (normalizeBlock(text.slice(block.start, block.end)) !== normalizeBlock(surfaceBlock(loadConfig(projectRoot).surface))) {
       findings.push({ message: "AGENTS.md doctrina:surface block is stale vs the installed CLI", remedy: "doctrina upgrade --write" });
     } else {
       ok.push("AGENTS.md: doctrina:surface block current");

package/src/lib/triage-model.js

@@ -119,3 +119,78 @@ export function classify(prompt) {
 
   return { lane, scores: lanes, confident: best > 0 && best - runnerUp >= 2 };
 }
+
+// THE TRACKS, BY WHAT THE REQUEST CHANGES (change 0255).
+//
+// The three lanes above say what KIND of request it is. They never said how
+// much ceremony it earns, and the default answer was all of it: "fix the
+// typo in the README" opened a proposal, three tasks and a thirteen-step
+// close. `metrics` already printed "a one-line fix may rightly need none"
+// under its adherence rate — the rule existed, in a footnote.
+//
+// The measure is not the size of the diff. It is whether a sentence in a
+// spec becomes false, or one is missing: a one-line change of a timeout the
+// spec states is a change, and a two-hundred-line reformat is not.
+export const TRACKS = [
+  { id: "direct",
+    changes: "nothing a spec says — a typo, a comment, formatting, a fix that makes the code do what the spec already says",
+    path: "edit · doctrina verify · commit" },
+  { id: "chore",
+    changes: "the build, the tooling or the docs, worth a record — no spec changes",
+    path: 'doctrina work --chore "<request>"' },
+  { id: "change",
+    changes: "behaviour — a sentence in a spec becomes false, or one is missing",
+    path: 'doctrina work "<request>"' },
+];
+
+// What the words alone can settle. Each phrase names an edit that cannot
+// change behaviour; a bare "comment" or "formatting" is also the name of a
+// feature ("comment moderation", "date formatting"), so those need the word
+// that says which one is meant. A fix that restores what the spec already
+// says is direct too, and no word list can know it: that one is the
+// agent's call, by the rule the standing instructions state.
+export const DIRECT_SIGNALS = [
+  /\b(typos?|misspell\w*|spelling|grammar|whitespace|indentation|trailing (spaces?|whitespace|commas?|newlines?))\b/,
+  /\b(formatting only|reformat\w*|fix(ing)? (the )?formatting|code formatting)\b/,
+  /\b((code|stale|outdated|old|wrong|misleading) comments?|comments? only|dead code|unused (imports?|variables?))\b/,
+  // pt
+  /\b(erros? de digitacao|ortografia|gramatica|espacos? em branco|indentacao)\b/,
+  /\b(so (a )?formatacao|reformatar|corrigir (a )?formatacao|formatacao do codigo)\b/,
+  /\b(comentarios? (de codigo|antig\w+|obsolet\w+|desatualizad\w+|errad\w+)|so (o |os )?comentarios?|codigo morto|imports? nao usad\w+|variave(l|is) nao usad\w+)\b/,
+];
+
+/**
+ * The signals that make a prompt a direct edit, or none. A prompt that also
+ * carries a product or a runtime signal is not direct: "add" or "should"
+ * says behaviour is in play, and the ceremony is the safe side to err on.
+ * @param {string} prompt
+ * @param {ReturnType<typeof classify>} [verdict]
+ * @returns {string[]}
+ */
+export function directSignals(prompt, verdict = classify(prompt)) {
+  if (verdict.scores.product.total > 0 || verdict.scores.runtime.total > 0) return [];
+  const text = fold(prompt);
+  const hits = [];
+  for (const re of DIRECT_SIGNALS) {
+    const m = text.match(re);
+    if (m) hits.push(m[0]);
+  }
+  return hits;
+}
+
+/** The track a prompt reads as: direct, chore, change — or diagnosis, for a runtime problem. */
+export function trackOf(prompt, verdict = classify(prompt)) {
+  if (directSignals(prompt, verdict).length > 0) return "direct";
+  if (verdict.lane === "runtime") return "diagnosis";
+  return verdict.lane === "chore" ? "chore" : "change";
+}
+
+/** The three tracks as plain lines, for the commands that print them. */
+export function trackLines() {
+  const out = [];
+  for (const t of TRACKS) {
+    out.push(`  ${t.id.padEnd(7)} ${t.changes}`);
+    out.push(`          ${t.path}`);
+  }
+  return out;
+}