doctrina-cli 0.15.1 → 0.16.0

package/src/lib/doc-model.js

@@ -18,6 +18,9 @@
 //     a non-canonical form is REPORTED (so `validate --fix` can repair it)
 //     rather than silently accepted or silently missed.
 //   STRICT ON WRITE.  One canonical form per artifact kind, always.
+import path from "node:path";
+import { read } from "./fs-ops.js";
+import { locateTemplatesDir } from "./templates.js";
 
 // Artifact kinds and the header form each one canonically uses. Specs and
 // contracts use bare bold; ADRs, proposals, and the intake use list items.
@@ -285,3 +288,326 @@ export function parseArtifact(text, { kind = ARTIFACT_KIND.UNKNOWN } = {}) {
     nonConforming: nonConformingHeaders(text, kind),
   };
 }
+
+// ---------------------------------------------------------------------------
+// The rest of the on-disk grammar (ADR 0021, change 0043)
+// ---------------------------------------------------------------------------
+//
+// ADR 0021 declares ONE document model that owns how a Doctrina artifact is
+// read off disk. Three parsers lived outside it — skill frontmatter in a
+// command module, and the two delta parsers in another — and `lib/scan.js`
+// imported them FROM `commands/`, inverting the dependency the layering
+// depends on. Change 0037 broke that edge by moving them into lib/; this is
+// the second half: they belong to the module the ADR names, not to two more
+// libraries beside it.
+//
+// Pure text predicates, all of them. Nothing here reads a file.
+
+export function parseFrontmatter(text, key) {
+  // Match frontmatter blocks bounded by `---` lines at start of file.
+  const fmMatch = text.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+  if (!fmMatch) return null;
+  const block = fmMatch[1];
+  const lineRe = new RegExp(`^${key}\\s*:\\s*(.+)$`, "m");
+  const m = block.match(lineRe);
+  return m ? m[1].trim() : null;
+}
+
+export function parseOperation(text) {
+  const m = text.match(/^\*\*Operation:\*\*\s*([A-Z]+)/m);
+  if (!m) return null;
+  const op = m[1];
+  if (op === "ADDED" || op === "MODIFIED" || op === "REMOVED") return op;
+  return null;
+}
+
+export function parseCapabilityFromDelta(text, deltaPath) {
+  // Prefer the explicit header "# Spec Delta — capability: <name>"
+  const m = text.match(/^#\s+Spec Delta\s*[—-]\s*capability:\s*([a-z][a-z0-9-]*)/m);
+  if (m) return m[1];
+  // Fall back to the parent directory name of the delta file
+  const parent = path.basename(path.dirname(deltaPath));
+  if (/^[a-z][a-z0-9-]*$/.test(parent)) return parent;
+  return null;
+}
+
+/**
+ * The value a shipped template writes for `name`, or null when the template
+ * cannot be located (an unusual install) or does not carry that header.
+ *
+ * @param {string} templateName  e.g. "spec.md.template"
+ * @param {string} name
+ * @returns {string|null}
+ */
+export function templateHeaderValue(templateName, name) {
+  try {
+    return getHeader(read(path.join(locateTemplatesDir(), templateName)), name);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is this header value still the scaffold's placeholder?
+ *
+ * A check written to catch a MISSING header is dead in the normal flow when
+ * the scaffold writes a value for it: the escape hatch arrives pre-armed
+ * (change 0057). The templates mark a placeholder by wrapping the whole
+ * value in angle brackets, so that is the portable rule; when the templates
+ * can be located, the template's own value settles it exactly.
+ *
+ * @param {string|null|undefined} value
+ * @param {{ template?: string, name?: string }} [opts]
+ * @returns {boolean}
+ */
+export function isPlaceholderHeaderValue(value, opts = {}) {
+  if (value === null || value === undefined) return true;
+  const v = String(value).trim();
+  if (v === "") return true;
+  // `<...>` wrapping the WHOLE value — the templates' placeholder convention.
+  // A real value may still contain angle brackets ("n/a — <why>" does not,
+  // but a prose value could), which is why the whole value must be wrapped.
+  if (/^<[\s\S]*>$/.test(v)) return true;
+  if (opts.template && opts.name) {
+    const tpl = templateHeaderValue(opts.template, opts.name);
+    if (tpl !== null && tpl.trim() === v) return true;
+  }
+  return false;
+}
+
+/**
+ * Every GitHub-style checkbox in `text`, in reading order.
+ *
+ * One owner for the box grammar (ADR 0021). It had six, and they disagreed:
+ * `snapshot.js` required TEXT after the box (`\[[ xX]\]\s+(.*)`), so the three
+ * empty placeholders `work` scaffolds were invisible to it and `prime` printed
+ * "tasks 0/3" for a change with six open boxes — the three it counted being
+ * the closing steps, not the work. `gates.js` required no text and counted
+ * six; `change tick` counted eight, adding the proposal's Verification boxes.
+ * Three numbers for the same file, side by side in the same session.
+ *
+ * Each entry carries whether the box is a scaffold PLACEHOLDER — a box with
+ * nothing written after it — because that is a real distinction (`analyze`
+ * refuses a change that still has them) and it is the one the counters must
+ * agree to make explicitly rather than by accident.
+ *
+ * @param {string} text
+ * @param {{ section?: string|null }} [opts] limit to one `## ` section
+ * @returns {Array<{ line: number, checked: boolean, text: string, placeholder: boolean }>}
+ */
+export function parseChecklist(text, opts = {}) {
+  const section = opts.section ?? null;
+  const lines = String(text).split(/\r?\n/);
+  const out = [];
+  let inSection = section === null;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) {
+      if (section !== null) {
+        inSection = new RegExp(`^##\\s+${section.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i")
+          .test(lines[i]);
+      }
+      continue;
+    }
+    if (!inSection) continue;
+    // Any Markdown bullet marker opens a box (change 0104): `* [ ]` and
+    // `+ [ ]` are task items to every renderer, and a box the grammar
+    // cannot see is one `tick` cannot tick and the archive gate cannot
+    // count — an unchecked task that closes green.
+    const m = /^\s*[-*+]\s*\[([ xX])\]\s*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    const body = m[2].trim();
+    out.push({ line: i, checked: m[1] !== " ", text: body, placeholder: body === "" });
+  }
+  return out;
+}
+
+/**
+ * How many boxes a checklist holds and how many are done — the pair every
+ * progress line prints. Placeholders count: a box nobody wrote is a box
+ * nobody finished, and hiding it is what made "0/3" mean six.
+ *
+ * @param {string} text
+ * @param {{ section?: string|null }} [opts]
+ * @returns {{ total: number, done: number, open: string[], placeholders: number }}
+ */
+export function checklistProgress(text, opts = {}) {
+  const boxes = parseChecklist(text, opts);
+  return {
+    total: boxes.length,
+    done: boxes.filter((b) => b.checked).length,
+    open: boxes.filter((b) => !b.checked).map((b) => b.text),
+    placeholders: boxes.filter((b) => b.placeholder).length,
+  };
+}
+
+/**
+ * Is this section still the shipped template's — empty, or nothing but the
+ * template's own instructional comment and placeholder?
+ *
+ * The framework writes artifacts from templates and then trusts that someone
+ * filled them in. Exactly one gate checked that (`analyze`, over a change
+ * proposal); everything else took the mould for a decision (change 0065).
+ * This is the same ruler `isPlaceholderHeaderValue` applies to a header,
+ * applied to a section body: an HTML comment is annotation (change 0055), so
+ * a section that is only annotation is a section nobody wrote.
+ *
+ * @param {string} text          the whole artifact
+ * @param {string} name          the `## ` section name
+ * @param {{ template?: string }} [opts]  template file to compare against
+ * @returns {boolean}
+ */
+export function isUnwrittenSection(text, name, opts = {}) {
+  const body = getSection(text, name);
+  if (body === null) return true;
+  const prose = maskComments(body).trim();
+  if (prose === "") return true;
+  // A body that is nothing but the template's placeholder bullets or an
+  // angle-bracket placeholder is unwritten too.
+  const stripped = prose.replace(/^[-*]\s*$/gm, "").trim();
+  if (stripped === "") return true;
+  if (/^<[\s\S]*>$/.test(stripped)) return true;
+  if (opts.template) {
+    try {
+      const tpl = read(path.join(locateTemplatesDir(), opts.template));
+      const tplBody = getSection(tpl, name);
+      if (tplBody !== null && maskComments(tplBody).trim() === prose) return true;
+    } catch {
+      // No templates dir — the checks above already carry the common cases.
+    }
+  }
+  return false;
+}
+
+/**
+ * The named sections of `text` that nobody has written yet, in order.
+ *
+ * @param {string} text
+ * @param {string[]} names
+ * @param {{ template?: string }} [opts]
+ * @returns {string[]}
+ */
+export function unwrittenSections(text, names, opts = {}) {
+  return names.filter((name) => isUnwrittenSection(text, name, opts));
+}
+
+// Is the on-disk spec still the untouched `spec new <cap>` scaffold? Precise
+// check: render the shipped capability template for the same capability and
+// compare, ignoring the date-bearing "Last updated" line and whitespace
+// normalisation. When the template cannot be located (unusual installs),
+// fall back to the scaffold's own placeholder fingerprints — text no real
+// spec keeps. Used by `change apply` so an ADDED delta can replace a
+// scaffold (the canonical spec-new → delta flow) without ever clobbering a
+// spec that carries real content.
+export function isUntouchedScaffold(specText, capability) {
+  const normalize = (s) =>
+    s.replace(/\r\n/g, "\n")
+      .split("\n")
+      .filter((line) => !/^\*\*Last updated:\*\*/.test(line))
+      .join("\n")
+      .trim();
+  try {
+    const tplPath = path.join(locateTemplatesDir(), "spec.md.template");
+    const rendered = read(tplPath)
+      .replace(/\{\{CAPABILITY\}\}/g, capability)
+      .replace(/\{\{DATE\}\}/g, "");
+    if (normalize(rendered) === normalize(specText)) return true;
+  } catch {
+    // fall through to the fingerprint heuristic
+  }
+  // Fingerprints: the Purpose placeholder comment AND an empty Ubiquitous
+  // section survive only in a scaffold nobody edited.
+  return (
+    specText.includes("<!-- One paragraph: what this capability does and why it exists. -->") &&
+    /##\s+Requirements \(EARS\)[\s\S]*?### Ubiquitous\s*\n\s*-\s*\n/.test(specText)
+  );
+}
+
+
+/**
+ * The byte ranges every HTML comment occupies in `text`, in file order.
+ *
+ * A comment is annotation, not content: the scaffolded spec carries the
+ * five-line EARS legend inside one, and the guessed delta (change 0044)
+ * carries its `RANKED GUESS` note inside another. Every reader of an
+ * on-disk artifact has to agree on that, so the ranges are computed HERE
+ * and nowhere else (ADR 0021 — one owner for the on-disk grammar).
+ *
+ * @param {string} text
+ * @returns {Array<[number, number]>}
+ */
+export function commentRanges(text) {
+  /** @type {Array<[number, number]>} */
+  const ranges = [];
+  for (const m of text.matchAll(/<!--[\s\S]*?-->/g)) {
+    ranges.push([m.index ?? 0, (m.index ?? 0) + m[0].length]);
+  }
+  return ranges;
+}
+
+/**
+ * Is this offset inside one of `ranges`?
+ *
+ * @param {Array<[number, number]>} ranges
+ * @param {number} offset
+ * @returns {boolean}
+ */
+export function isInsideComment(ranges, offset) {
+  return ranges.some(([a, b]) => offset >= a && offset < b);
+}
+
+/**
+ * `text` with every HTML comment blanked out — same length, same line
+ * count, same offset for every character that survives.
+ *
+ * This is the skip-by-position rule of `spec-ops.matchOpsBlock` in a form
+ * a line- or regex-oriented scanner can use directly: a bullet inside a
+ * comment stops looking like a bullet, and a command name inside one stops
+ * looking like a reference, WITHOUT any surviving character moving. Masking
+ * is for SCANNING only. Never write the masked text back to disk, and never
+ * derive an authored value from it — a delta whose `append-criterion` value
+ * legitimately contains `<!-- illustrative -->` must land with the marker
+ * intact, which is why `applyOps` still works on the raw text.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function maskComments(text) {
+  let out = text;
+  for (const [a, b] of commentRanges(text)) {
+    const blanked = text.slice(a, b).replace(/[^\r\n]/g, " ");
+    out = out.slice(0, a) + blanked + out.slice(b);
+  }
+  return out;
+}
+
+/**
+ * The title a change proposal's H1 states, or null.
+ *
+ * The H1 the template writes is `# Change <id> — <title>`, and the id itself
+ * contains hyphens (`NNNN-slug`) — which is what four separate copies of this
+ * regex kept getting wrong in four slightly different ways. The one that read
+ * `[^—-]*` for the id stopped at the FIRST hyphen, which in any multi-word id
+ * is the id's own, so `prime`, `handoff` and `report` printed the slug glued
+ * in front of the title on every change `work` had ever generated. The ones
+ * that read `\s*[—-]\s*` accepted a bare hyphen with no spaces around it, so
+ * an H1 with no separator at all had its last segment read as the title.
+ *
+ * The separator is a dash WITH whitespace on both sides; an id's hyphens
+ * never have that, which is the whole ambiguity, resolved. Both the em dash
+ * and the plain hyphen are accepted, because the character was never the
+ * problem — a hand-written H1 using `-` reads exactly as clearly.
+ *
+ * The `Change <id> —` prefix is optional: an H1 written without it is a title
+ * in its own right and is returned whole (ADR 0021 — one owner for the
+ * on-disk grammar).
+ *
+ * @param {string} text  the proposal, or just its first line
+ * @returns {string|null}
+ */
+export function parseChangeTitle(text) {
+  const first = String(text ?? "").split(/\r?\n/).find((l) => /^#\s+\S/.test(l));
+  if (!first) return null;
+  const m = first.match(/^#\s+(?:Change\s+\S+\s+[—-]\s+)?(.+)$/);
+  const title = m?.[1]?.trim();
+  return title ? title : null;
+}

package/src/lib/docs-impact.js

@@ -1,9 +1,12 @@
 // @ts-check
 import path from "node:path";
-import { spawnSync } from "node:child_process";
-import { isFile, read, walk } from "./fs-ops.js";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read, walk } from "./fs-ops.js";
 import { COMMAND_NAMES } from "./commands.js";
 import { locateTemplatesDir } from "./templates.js";
+import { changedFiles, isRepo } from "./git.js";
+import { maskComments, getSection } from "./doc-model.js";
+import { listHeader } from "./scan.js";
 
 // "Docs ship inside the change, never after it" (audit item D2).
 //
@@ -46,11 +49,81 @@ function scaffoldLines() {
   return lines;
 }
 
+function escapeRe(x) {
+  return x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// The names THIS project declares as its integration surface, read from its
+// own contracts: the variables of the Environment and Wiring tables, the
+// services of the Ports table, and the backticked tokens of Interfaces.
+//
+// A contract is the right home for this. It is where a project already states
+// what an external consumer integrates against, it is versioned beside the
+// code, and `contract check` already holds parts of it to the implementation
+// (ADR 0023 — the runtime surface is declared, never inferred). The same
+// principle, applied to documentation: declared, never guessed.
+//
+// Returns [] for a project with no contracts, which is what keeps the change
+// backward compatible: that project's gate behaves exactly as it did.
+export function declaredSurfaceNames(projectRoot) {
+  const dir = path.join(projectRoot, ".doctrina", "contracts");
+  if (!isDir(dir)) return [];
+  const names = new Set();
+  for (const file of walk(dir)) {
+    if (!file.endsWith(".md")) continue;
+    const text = maskComments(read(file));
+
+    // First column of a table, for the sections whose first column IS the name.
+    for (const section of ["Ports", "Environment", "Wiring", "Selectors", "Budgets"]) {
+      const body = getSection(text, section);
+      if (!body) continue;
+      for (const line of body.split(/\r?\n/)) {
+        const m = /^\s*\|\s*([A-Za-z][\w.-]*)\s*\|/.exec(line);
+        if (!m) continue;
+        const cell = m[1];
+        // Skip the header row and the template's own placeholder rows.
+        if (/^(service|variable|selector|limit|name)$/i.test(cell)) continue;
+        if (/^-+$/.test(cell)) continue;
+        names.add(cell);
+      }
+    }
+
+    // Interfaces is prose with backticked tokens: endpoints, flags, shapes.
+    const interfaces = getSection(text, "Interfaces");
+    if (interfaces) {
+      for (const m of interfaces.matchAll(/`([^`\n]{2,60})`/g)) {
+        const token = m[1].trim();
+        // A command with a subcommand ("ledgerly reconcile") is exactly the
+        // shape worth declaring, so single internal spaces are allowed —
+        // anything with punctuation or prose in it is not a name.
+        if (/^[\w./:@+-]+(?: [\w./:@+-]+)*$/.test(token)) names.add(token);
+      }
+    }
+  }
+  return [...names];
+}
+
 // Does this change alter something the documentation makes promises about?
 // Read from the change's own artifacts — the deltas it will merge into
 // specs, plus the proposal that states its shape. Returns the list of
 // signals found (empty when the change touches no documented surface).
-export function documentedSurfaceSignals(changeDir) {
+// Drop the proposal's `## Verification` section before reading it for
+// surface signals. That section answers "how will you know this landed", so
+// the commands it names are the ones the author will RUN — the same reason
+// the template's own checklist lines are subtracted below. Running a gate is
+// not changing it (change 0088).
+function withoutVerification(text) {
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) skipping = /^##\s+Verification\b/i.test(line);
+    if (!skipping) out.push(line);
+  }
+  return out.join("\n");
+}
+
+export function documentedSurfaceSignals(changeDir, projectRoot = null) {
   const signals = [];
   const known = new Set(COMMAND_NAMES);
 
@@ -59,15 +132,39 @@ export function documentedSurfaceSignals(changeDir) {
   // and `doctrina coverage` — so scanning the raw file made every change look
   // like it touched a documented surface. A gate that fires on everything is
   // a gate that gets ignored, so the template's lines are subtracted first.
+  // An HTML comment is annotation, not authored surface. The guessed delta
+  // change 0044 scaffolds carries a `RANKED GUESS` note that names
+  // `doctrina work` — not template text, so the subtraction below never
+  // reaches it, and every change on the default path arrived at the docs
+  // gate carrying a phantom `commands: work`. Comments are blanked FIRST,
+  // by the document model, which is the one owner of that rule.
   const boilerplate = scaffoldLines();
-  const authored = (text) => text
+  const authored = (text) => maskComments(text)
     .split(/\r?\n/)
     .filter((line) => !boilerplate.has(normaliseScaffoldLine(line)))
     .join("\n");
 
   const sources = [];
   const proposal = path.join(changeDir, "proposal.md");
-  if (isFile(proposal)) sources.push(authored(read(proposal)));
+  if (isFile(proposal)) {
+    const text = read(proposal);
+
+    // A CHORE declares that no behaviour changes and no spec moves — that is
+    // what the lane means, and `analyze` already reads it that way ("0 spec
+    // deltas, metadata-only change"). Asking such a change to document a
+    // surface it declared it does not touch contradicts its own lane. The
+    // declaration is the author's, recorded in the proposal header and the
+    // index (change 0042), so it is auditable rather than invisible.
+    //
+    // This is the case that mattered: of the archived changes, every chore
+    // names a command in code context and none of them changes one. Change
+    // 0085 reorganised headings in AGENTS.md and was refused for "commands:
+    // close, templates" — the two commands its own proposal cited to describe
+    // the finding — and had to close with --force (change 0088).
+    if (/chore/i.test(listHeader(text, "Lane") ?? "")) return signals;
+
+    sources.push(authored(withoutVerification(text)));
+  }
   for (const p of walk(path.join(changeDir, "specs"))) {
     if (p.endsWith("delta.md")) sources.push(authored(read(p)));
   }
@@ -89,12 +186,52 @@ export function documentedSurfaceSignals(changeDir) {
     signals.push(`commands: ${[...commands].sort().join(", ")}`);
   }
 
+  // The surface the PROJECT declares, matched by name (change 0075's sibling
+  // problem, found in the second audit). Matching commands against Doctrina's
+  // own catalog made the gate maximally sensitive inside this repository and
+  // inert everywhere else: in an adopting project a new command, a public HTTP
+  // endpoint, a renamed environment variable and a changed config key all
+  // produced ZERO signals, and the change closed with no documentation and no
+  // complaint. The vocabulary was already in the right place — the contract
+  // declares Ports, Environment, Wiring, Selectors and Interfaces — so the gate
+  // reads it instead of carrying a catalog that only fits its author.
+  const declared = projectRoot === null ? [] : declaredSurfaceNames(projectRoot);
+  const hit = declared.filter((name) => new RegExp(`\\b${escapeRe(name)}\\b`).test(code));
+  // Report the most specific declaration only: "ledgerly reconcile" says more
+  // than the bare service name it starts with.
+  const touchedDeclared = hit.filter((a) => !hit.some((b) => b !== a && b.includes(a)));
+  if (touchedDeclared.length > 0) {
+    signals.push(`declared surface: ${touchedDeclared.sort().slice(0, 8).join(", ")}`);
+  }
+
   const flags = new Set();
   for (const m of code.matchAll(/--([a-z][a-z0-9-]{2,})/g)) flags.add(`--${m[1]}`);
   if (flags.size > 0) {
     signals.push(`flags: ${[...flags].sort().slice(0, 8).join(", ")}`);
   }
 
+  // Surface SHAPES, for the surface a change is ADDING — which by definition
+  // is not in the contract yet, and is the case the declared-name match cannot
+  // reach. Deterministic and language-agnostic (ADR 0005): a route path, an
+  // HTTP method in front of one, an environment-variable identifier. Read from
+  // code spans only, so prose that happens to contain a slash is not a signal.
+  const routes = new Set();
+  for (const m of code.matchAll(/(?:^|[\s`"'(])((?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+)?(\/[a-z][\w.-]*(?:\/[\w.:{}$<>-]+)+)/gi)) {
+    routes.add(((m[1] ?? "").toUpperCase().trim() + " " + m[2]).trim());
+  }
+  if (routes.size > 0) {
+    signals.push(`endpoints: ${[...routes].sort().slice(0, 6).join(", ")}`);
+  }
+
+  const envVars = new Set();
+  for (const m of code.matchAll(/\b([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)\b/g)) {
+    // Not twice: a declared variable is already reported by name above.
+    if (!touchedDeclared.includes(m[1])) envVars.add(m[1]);
+  }
+  if (envVars.size > 0) {
+    signals.push(`environment: ${[...envVars].sort().slice(0, 8).join(", ")}`);
+  }
+
   if (/\bexit\s+code|\bexits?\s+(?:with\s+)?[0-4]\b/i.test(text)) {
     signals.push("exit codes");
   }
@@ -116,38 +253,70 @@ export function documentedSurfaceSignals(changeDir) {
 // all, and attributing a hunk to a change would need guesswork the rest of
 // the framework refuses to do (ADR 0005).
 export function docsTouched(projectRoot) {
-  const git = (args) => {
-    const r = spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
-    if (r.error || r.status !== 0) return [];
-    return r.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
-  };
-  const set = new Set();
-  for (const f of git(["diff", "--name-only", "HEAD"])) set.add(f);
-  for (const f of git(["ls-files", "--others", "--exclude-standard"])) set.add(f);
-  for (const base of ["main", "master"]) {
-    const mb = git(["merge-base", "HEAD", base]);
-    if (mb.length > 0) {
-      for (const f of git(["diff", "--name-only", `${mb[0]}..HEAD`])) set.add(f);
-      break;
-    }
-  }
-  return [...set]
-    .map((f) => f.replace(/\\/g, "/"))
+  // mergeBase: a branch's EARLIER commits count as documentation that moved
+  // with the change — the gate asks "did docs ship with this work", not "did
+  // docs change since the last commit".
+  return changedFiles(projectRoot, { mergeBase: true })
+    .files
     .filter((f) => DOC_PATHS.some((re) => re.test(f)));
 }
 
 export function isGitRepo(projectRoot) {
-  const r = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
-    cwd: projectRoot, encoding: "utf8",
-  });
-  return !r.error && r.status === 0;
+  return isRepo(projectRoot);
+}
+
+// Where THIS project keeps its documentation, read off its own tree.
+//
+// The gate is portable; the instruction it printed was not. It named
+// `docs/en/` AND `docs/pt/` and a skill that exists only in Doctrina's own
+// repository, so an adopting project with neither read that it had to
+// translate (change 0058). The gate itself never asked for any of that — it
+// accepts anything under `docs/` or a README — so the remedy is derived from
+// what the checked project actually has.
+//
+// Returns the documentation homes in reading order, or [] for a project that
+// has none yet.
+export function documentationHomes(projectRoot) {
+  const homes = [];
+  const docsDir = path.join(projectRoot, "docs");
+  // Only a directory that holds prose is somewhere to write prose: naming
+  // `docs/assets/` — an SVG and nothing else — turned change 0058's portable
+  // hint into a five-item list with a wrong item in it.
+  const holdsMarkdown = (dir) => walk(dir).some((f) => f.endsWith(".md"));
+  if (isDir(docsDir)) {
+    // A per-language or per-audience split is a convention, not a rule: name
+    // the subdirectories this project HAS, and fall back to `docs/` itself.
+    const subs = readdirSync(docsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+      .filter((e) => holdsMarkdown(path.join(docsDir, e.name)))
+      .map((e) => `docs/${e.name}/`)
+      .sort();
+    if (subs.length > 0) homes.push(...subs);
+    else if (holdsMarkdown(docsDir)) homes.push("docs/");
+  }
+  for (const readme of ["README.md", "README.pt.md"]) {
+    if (isFile(path.join(projectRoot, readme))) homes.push(readme);
+  }
+  return homes;
+}
+
+// The hint the docs gate prints when it refuses. Names the places this
+// project documents in, and says "a README" when it documents nowhere yet —
+// never a path the checked project does not have.
+export function docsRemedy(projectRoot) {
+  const homes = documentationHomes(projectRoot);
+  if (homes.length === 0) return "document it in a README, or under docs/";
+  if (homes.length === 1) return `document it in ${homes[0]}`;
+  const last = homes[homes.length - 1];
+  return `document it in ${homes.slice(0, -1).join(", ")} or ${last}` +
+    (homes.length > 2 ? " — whichever this change belongs in" : "");
 }
 
 // The gate itself: { ok, signals, touched, reason }. `ok` is true when the
 // change touches no documented surface, when documentation moved with it,
 // or when git cannot answer.
 export function checkDocsImpact(projectRoot, changeDir) {
-  const signals = documentedSurfaceSignals(changeDir);
+  const signals = documentedSurfaceSignals(changeDir, projectRoot);
   if (signals.length === 0) {
     return { ok: true, signals, touched: [], reason: "touches no documented surface" };
   }

package/src/lib/flag-catalog.js

@@ -2,7 +2,6 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { COMMAND_NAMES } from "./commands.js";
 
 // One catalog of "which flags does command X accept", with two consumers:
 //
@@ -64,12 +63,6 @@ export async function declaredFlags(commandName) {
   ]);
 }
 
-export async function loadAllFlagSpecs() {
-  const out = new Map();
-  for (const name of COMMAND_NAMES) out.set(name, await loadFlagSpec(name));
-  return out;
-}
-
 // Flag names a source file READS, by scanning its call sites:
 //   flagBool(flags, "x")  flagString(flags, "x")  flags.has("x")  flags.get("x")
 // Deterministic text scan, not execution — it sees every branch, including
@@ -92,15 +85,6 @@ export function readCommandSource(commandName) {
   return readFileSync(modulePathFor(commandName), "utf8");
 }
 
-// Flags a command's `help` string documents: every `--flag` token in it.
-// The docs gate compares prose against this too, so help and reference
-// cannot drift apart from the declaration.
-export function scanHelpFlags(helpText) {
-  const out = new Set();
-  for (const m of String(helpText ?? "").matchAll(/--([a-z][a-z0-9-]*)/g)) out.add(m[1]);
-  return out;
-}
-
 function pathToUrl(p) {
   return "file:///" + p.replace(/\\/g, "/");
 }