doctrina-cli 0.11.0 → 0.13.0

package/src/commands/intent.js

@@ -0,0 +1,173 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+// Post-intake intent evolution (0.11.0 field review item 8). The intake is
+// converted once; capabilities born later — brainstorms, pivots, new asks —
+// had no way to gain a product anchor, so they inevitably ended at
+// `Realizes: n/a` and `trace` reported "14/14 ok" while blind to 40% of the
+// system. `intent add` appends a new [SC*] anchor bullet to product.md's
+// Success criteria (allocating the next number), so growth keeps provenance:
+// new intent gets an anchor, the new spec Realizes it, `trace` sees it.
+//
+// The CLI allocates and appends; WHAT the intent says is the human/agent's
+// words verbatim (ADR 0005).
+
+const SUBCOMMANDS = ["add", "list"];
+
+export async function run(positional, _flags) {
+  const sub = positional[0];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error(c.red("error:") + ` unknown intent subcommand "${sub ?? ""}"`);
+    const guess = suggest(sub, SUBCOMMANDS);
+    console.error(c.gray("hint: ") + (guess
+      ? `did you mean \`doctrina intent ${guess}\`?`
+      : `available: ${SUBCOMMANDS.join(", ")}`));
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+  if (sub === "list") return intentList(projectRoot);
+  return intentAdd(projectRoot, positional.slice(1).join(" ").trim());
+}
+
+function productPathOf(projectRoot) {
+  return path.join(projectRoot, ".doctrina", "product.md");
+}
+
+// Every "[A-Z]+\d+" anchor at the head of a bullet, in document order —
+// the same convention `trace` reads.
+function collectAnchors(text) {
+  const out = [];
+  const seen = new Set();
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\s*[-*]\s+\[([A-Z]+)(\d+)\]\s+(.*)$/);
+    if (m && !seen.has(m[1] + m[2])) {
+      seen.add(m[1] + m[2]);
+      out.push({ prefix: m[1], num: Number(m[2]), id: m[1] + m[2], text: m[3].trim(), line: i });
+    }
+  }
+  return out;
+}
+
+function intentList(projectRoot) {
+  const p = productPathOf(projectRoot);
+  if (!isFile(p)) {
+    console.error(c.red("error:") + " no .doctrina/product.md");
+    return 1;
+  }
+  const anchors = collectAnchors(read(p));
+  if (anchors.length === 0) {
+    console.log(c.gray("no intent anchors in product.md — tag bullets with `- [SC1] ...`, or add one: doctrina intent add \"<text>\""));
+    return 0;
+  }
+  console.log(c.bold("Intent anchors") + c.gray(" — product.md, document order:"));
+  console.log("");
+  for (const a of anchors) {
+    console.log(`  ${c.cyan(a.id.padEnd(6))} ${a.text}`);
+  }
+  console.log("");
+  console.log(c.gray(`${anchors.length} anchor${anchors.length === 1 ? "" : "s"}. Provenance: doctrina trace · doctrina why <id>`));
+  return 0;
+}
+
+function intentAdd(projectRoot, textArg) {
+  if (!textArg) {
+    console.error(c.red("error:") + " intent add requires the intent text (quote it)");
+    console.error(c.gray("hint: ") + `example: doctrina intent add "Risk map answers 'what should we test next?' in one read"`);
+    return 2;
+  }
+  const p = productPathOf(projectRoot);
+  if (!isFile(p)) {
+    console.error(c.red("error:") + " no .doctrina/product.md — run `doctrina init` / `doctrina intake` first");
+    return 1;
+  }
+  const original = read(p);
+  const anchors = collectAnchors(original);
+
+  // Accept "SC15: text" to pin an explicit id; otherwise allocate the next
+  // number for the dominant prefix (SC by default).
+  let id = null;
+  let text = textArg;
+  const pinned = textArg.match(/^([A-Z]+)(\d+)\s*:\s*(.+)$/);
+  if (pinned) {
+    id = pinned[1] + pinned[2];
+    text = pinned[3].trim();
+    if (anchors.some((a) => a.id === id)) {
+      console.error(c.red("error:") + ` anchor [${id}] already exists in product.md`);
+      return 1;
+    }
+  } else {
+    const prefix = anchors.length > 0 ? dominantPrefix(anchors) : "SC";
+    const maxNum = anchors.filter((a) => a.prefix === prefix).reduce((m, a) => Math.max(m, a.num), 0);
+    id = `${prefix}${maxNum + 1}`;
+  }
+
+  const lines = original.split(/\r?\n/);
+  const bullet = `- [${id}] ${text}`;
+
+  // Insertion point: after the LAST existing anchor bullet (keeps them
+  // contiguous); else at the end of "## Success criteria"; else appended as a
+  // new Success criteria section (a product.md without one gains it).
+  const samePrefix = anchors.length > 0;
+  let inserted = false;
+  if (samePrefix) {
+    const last = anchors[anchors.length - 1];
+    lines.splice(last.line + 1, 0, bullet);
+    inserted = true;
+  } else {
+    for (let i = 0; i < lines.length; i++) {
+      if (/^##\s+Success criteria\b/i.test(lines[i])) {
+        // Insert before the next "## " heading (or at EOF).
+        let j = i + 1;
+        while (j < lines.length && !/^##\s+/.test(lines[j])) j += 1;
+        // Trim trailing blank lines inside the section for a tidy append.
+        let k = j;
+        while (k > i + 1 && lines[k - 1].trim() === "") k -= 1;
+        lines.splice(k, 0, bullet);
+        inserted = true;
+        break;
+      }
+    }
+  }
+  if (!inserted) {
+    lines.push("", "## Success criteria", "", bullet);
+  }
+
+  write(p, lines.join("\n"), { force: true });
+  console.log(c.green("added") + ` [${id}] to ${relPath(projectRoot, p)}`);
+  console.log("");
+  console.log(`  ${c.cyan(id.padEnd(6))} ${text}`);
+  console.log("");
+  console.log(c.gray("Next: the spec that delivers this intent declares it —"));
+  console.log(`    ${c.cyan(`**Realizes:** ${id}`)}  ${c.gray("(in .doctrina/specs/<capability>/spec.md; `doctrina trace` closes the loop)")}`);
+  return 0;
+}
+
+function dominantPrefix(anchors) {
+  const counts = new Map();
+  for (const a of anchors) counts.set(a.prefix, (counts.get(a.prefix) ?? 0) + 1);
+  return [...counts.entries()].sort((x, y) => y[1] - x[1] || x[0].localeCompare(y[0]))[0][0];
+}
+
+export const help = `
+Usage: doctrina intent add "<text>"
+       doctrina intent add "SC15: <text>"
+       doctrina intent list
+
+Post-intake intent evolution. \`add\` appends a new intent anchor bullet
+(\`- [SC5] <text>\`) to product.md's Success criteria, allocating the next
+number automatically (or pin one with the "SC15: ..." form). New
+capabilities born after the intake — brainstorms, pivots — get an anchor
+to Realize instead of inevitably landing at "Realizes: n/a", so
+\`doctrina trace\` keeps seeing the whole system as it grows.
+
+\`list\` prints every anchor in document order (the same convention trace
+reads). The CLI allocates and appends; the intent's wording is yours,
+verbatim (ADR 0005).
+`;

package/src/commands/review.js

@@ -6,6 +6,7 @@ import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { rankCapabilitiesByDiff } from "./work.js";
+import { parseDependsOn } from "../lib/scan.js";
 import { summarize as coverageSummary } from "./coverage.js";
 import { summarize as traceSummary } from "./trace.js";
 
@@ -42,18 +43,38 @@ export async function run(_positional, flags) {
   const notes = [];  // advisory observations
 
   // 1. Code changed under a capability whose spec was NOT touched — the spec
-  //    may have drifted from the code it describes.
+  //    may have drifted from the code it describes. Touched = every capability
+  //    matched by the code diff (UNCAPPED — the top-3 hint truncation is how
+  //    this missed 5 of 8 in the 0.11.0 field session) UNIONED with every
+  //    capability whose spec.md itself changed.
   const specChanged = new Set(
     all.filter((f) => /(^|\/)\.doctrina\/specs\/[^/]+\/spec\.md$/.test(f.replace(/\\/g, "/")))
       .map((f) => f.replace(/\\/g, "/").match(/\.doctrina\/specs\/([^/]+)\/spec\.md$/)[1]),
   );
-  const ranked = rankCapabilitiesByDiff(projectRoot, sourceFiles);
+  const ranked = rankCapabilitiesByDiff(projectRoot, sourceFiles, { limit: Infinity });
+  const touched = new Set([...specChanged, ...ranked.map((m) => m.id)]);
   for (const m of ranked) {
     if (!specChanged.has(m.id)) {
       breaks.push(`code under capability "${m.id}" changed, but its spec was not updated — confirm \`.doctrina/specs/${m.id}/spec.md\` still describes the code (update it, or note why not)`);
     }
   }
 
+  // 1b. Dependents of touched capabilities (the machine-readable
+  //     **Depends on:** header): a spec that builds on something you changed
+  //     may silently no longer hold. Advisory — a pointer, not a verdict.
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (isDir(specsDir) && touched.size > 0) {
+    for (const cap of readdirSync(specsDir).sort()) {
+      if (touched.has(cap)) continue;
+      const specPath = path.join(specsDir, cap, "spec.md");
+      if (!isFile(specPath)) continue;
+      const deps = parseDependsOn(read(specPath)).filter((d) => touched.has(d));
+      if (deps.length > 0) {
+        notes.push(`capability "${cap}" depends on touched ${deps.map((d) => `"${d}"`).join(", ")} — confirm it still holds (\`doctrina why ${cap}\`)`);
+      }
+    }
+  }
+
   // 2. New source files that map to no capability at all — code with no home
   //    in any spec (a likely new, unspecced capability).
   if (ranked.length === 0 && sourceFiles.length > 0) {
@@ -83,8 +104,8 @@ export async function run(_positional, flags) {
 
   // --- Output ---
   console.log(c.gray(`${all.length} changed path(s); ${sourceFiles.length} source file(s) outside .doctrina/.`));
-  if (ranked.length > 0) {
-    console.log(c.gray("Capabilities touched: ") + ranked.map((m) => c.cyan(m.id)).join(", "));
+  if (touched.size > 0) {
+    console.log(c.gray("Capabilities touched: ") + [...touched].sort().map((id) => c.cyan(id)).join(", "));
   }
   console.log("");
 

package/src/commands/skill.js

@@ -61,9 +61,23 @@ function skillSuggest(args, flags) {
   const since = flagString(flags, "since");
 
   const skillsDir = path.join(projectRoot, ".doctrina", "skills");
-  const existing = new Set(
-    isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")).map((f) => path.basename(f, ".md")) : [],
-  );
+  const existingFiles = isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")) : [];
+  const existing = new Set(existingFiles.map((f) => path.basename(f, ".md")));
+  // A lesson may already be captured under a DIFFERENT slug (0.11.0 field
+  // review item 11: the human names the skill after the lesson, not after the
+  // change id — "tela-preta-crash-de-render..." for change 0049). Two extra
+  // dedup signals: an existing skill whose body cites the candidate's change
+  // id / commit hash, and token-overlap similarity between the slugs.
+  const existingBodies = existingFiles.map((f) => ({ slug: path.basename(f, ".md"), body: read(f) }));
+  const captured = (cand) => {
+    if (existing.has(cand.slug)) return true;
+    for (const sk of existingBodies) {
+      if (cand.id && sk.body.includes(cand.id)) return true;
+      if (cand.from && sk.body.includes(cand.from)) return true;
+      if (slugSimilarity(cand.slug, sk.slug) >= 0.5) return true;
+    }
+    return false;
+  };
 
   // Two deterministic sources, deduped by slug. `seen` guards against a lesson
   // appearing twice (e.g. a fix committed and later archived as a change).
@@ -78,18 +92,20 @@ function skillSuggest(args, flags) {
       const id = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
       if (!FIX_SHAPED.test(id)) continue;
       const slug = skillSlug(id);
-      if (existing.has(slug) || seen.has(slug)) continue; // captured or already queued
+      if (seen.has(slug)) continue;
+      const cand = { id, slug, source: "change", from: name };
+      if (captured(cand)) continue; // captured (any slug) or cited by an existing skill
       const proposal = path.join(archiveDir, name, "proposal.md");
-      const why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
+      cand.why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
       seen.add(slug);
-      candidates.push({ id, slug, why, source: "change", from: name });
+      candidates.push(cand);
     }
   }
 
   // Source 2 — fix-shaped commits in the git history (ADR 0013). Archive wins a
   // slug collision: a `## Why` paragraph is a richer seed than a subject line.
   for (const cand of gitFixCommits(projectRoot, { since, limit: GIT_LOG_LIMIT })) {
-    if (existing.has(cand.slug) || seen.has(cand.slug)) continue;
+    if (seen.has(cand.slug) || captured(cand)) continue;
     seen.add(cand.slug);
     candidates.push(cand);
   }
@@ -216,6 +232,29 @@ function skillSlug(id) {
   return slug.length > 40 ? slug.slice(0, 40).replace(/-+$/g, "") : (slug || "lesson");
 }
 
+// Token-overlap similarity between two kebab slugs (Jaccard over meaningful
+// tokens). "0049-fix-tela-preta-render" vs "tela-preta-crash-de-render-sem-
+// error-boundary" share tela/preta/render → high overlap even though the
+// human renamed the skill after the lesson. Deterministic; never semantic.
+function slugSimilarity(a, b) {
+  const toks = (s) => new Set(
+    String(s).split("-").filter((t) => t.length >= 3 && !/^\d+$/.test(t) && !SLUG_NOISE.has(t)),
+  );
+  const A = toks(a);
+  const B = toks(b);
+  if (A.size === 0 || B.size === 0) return 0;
+  let inter = 0;
+  for (const t of A) if (B.has(t)) inter += 1;
+  return inter / (A.size + B.size - inter);
+}
+
+// Fix-shaped verbs and connectives carry no lesson identity — without this,
+// every "fix-..." candidate looks 30% similar to every "fix-..." skill.
+const SLUG_NOISE = new Set([
+  "fix", "bug", "hotfix", "patch", "the", "and", "for", "with", "sem", "com",
+  "que", "nao", "por", "para", "una", "uma", "dos", "das",
+]);
+
 function firstWhyLine(proposalText) {
   const m = proposalText.match(/##\s*Why\s*\r?\n+([^\r\n][^\r\n]*)/i);
   if (!m) return "";

package/src/commands/spec.js

@@ -134,9 +134,10 @@ function specSet(args, flags) {
   const impl = flagString(flags, "implementation");
   const status = flagString(flags, "status");
   const bump = flagString(flags, "bump");
+  const versionExplicit = flagString(flags, "version");
   const criterion = flagString(flags, "criterion");
-  if (impl === undefined && status === undefined && bump === undefined && criterion === undefined) {
-    console.error(c.red("error:") + " spec set needs at least one of --implementation, --status, --bump, --criterion");
+  if (impl === undefined && status === undefined && bump === undefined && versionExplicit === undefined && criterion === undefined) {
+    console.error(c.red("error:") + " spec set needs at least one of --implementation, --status, --bump, --version, --criterion");
     console.error(c.gray("hint: ") + `example: doctrina spec set ${capability} --implementation "verified — \`src/x.js\`" --bump minor`);
     return 2;
   }
@@ -156,6 +157,10 @@ function specSet(args, flags) {
     if (!["major", "minor", "patch"].includes(bump)) errors.push(`--bump needs major|minor|patch (got "${bump}")`);
     else apply(bumpVersion(text, bump));
   }
+  if (versionExplicit !== undefined) {
+    if (!/^\d+\.\d+\.\d+$/.test(versionExplicit)) errors.push(`--version needs semver X.Y.Z (got "${versionExplicit}")`);
+    else apply(setHeader(text, "Version", versionExplicit));
+  }
   if (criterion !== undefined) {
     const m = String(criterion).match(/^(\d+)\s*:\s*(.+)$/);
     if (!m) errors.push(`--criterion needs "<n>:<mark>" (got "${criterion}")`);
@@ -183,7 +188,10 @@ function specSet(args, flags) {
   const derived = deriveIndex(projectRoot, index);
   derived.last_updated = date;
   idx.save(projectRoot, derived);
-  console.log(c.green("indexed") + ` spec "${capability}" synced`);
+  // Echo the SPEC's resulting version, not the framework's — the two look
+  // identical in output and the ambiguity was a field-review papercut.
+  const specVersion = specHeader(text, "Version") ?? "—";
+  console.log(c.green("indexed") + ` spec "${capability}" synced (spec version ${specVersion})`);
   return 0;
 }
 
@@ -214,6 +222,8 @@ Options:
   --implementation "..." With \`set\`: set the Implementation header.
   --status "..."         With \`set\`: set the Status header.
   --bump major|minor|patch  With \`set\`: bump the spec Version.
+  --version X.Y.Z        With \`set\`: set the spec Version explicitly
+                         (the output echoes the SPEC version, not the CLI's).
   --criterion "<n>:<mark>"  With \`set\`: set criterion n's [mark]
                          (e.g. --criterion "2:verified").
 `;

package/src/commands/templates.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import process from "node:process";
 import { exists, isDir, isFile, lineCount, read, relPath, walk, write } from "../lib/fs-ops.js";
-import { locateTemplatesDir } from "../lib/templates.js";
+import { locateTemplatesDir, loadTemplateTree } from "../lib/templates.js";
+import { surfaceBlock, findSurfaceBlock } from "../lib/commands.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
@@ -56,6 +57,50 @@ function updateTemplates(flags) {
 
   const plan = [];
 
+  // AGENTS.md command-surface block: the one CLI-OWNED span of the file
+  // (marker-delimited, generated from the command catalog). Three cases:
+  // markers present but stale -> regenerate the span; a legacy hand-written
+  // "## Doctrina command surface" section without markers -> replace that
+  // section with the managed block (the section was CLI-scaffolded content
+  // to begin with — this is the one sanctioned exception to additive-only,
+  // see ADR 0015); neither -> append the block. This is what makes
+  // `doctrina upgrade --write` actually refresh AGENTS.md when the CLI
+  // gains commands, instead of only bumping the stamp.
+  const agentsMdPath = path.join(projectRoot, "AGENTS.md");
+  if (isFile(agentsMdPath)) {
+    const text = read(agentsMdPath);
+    const block = findSurfaceBlock(text);
+    const fresh = surfaceBlock();
+    if (block) {
+      if (normalizeBlock(text.slice(block.start, block.end)) !== normalizeBlock(fresh)) {
+        plan.push({
+          describe: ["AGENTS.md: regenerate the doctrina:surface block (stale vs installed CLI)"],
+          apply() {
+            const cur = read(agentsMdPath);
+            const b = findSurfaceBlock(cur);
+            if (b) write(agentsMdPath, cur.slice(0, b.start) + fresh + cur.slice(b.end), { force: true });
+          },
+        });
+      }
+    } else {
+      const legacy = findLegacySurfaceSection(text);
+      plan.push({
+        describe: [legacy
+          ? "AGENTS.md: replace the hand-written \"## Doctrina command surface\" section with the generated doctrina:surface block"
+          : "AGENTS.md: append the generated doctrina:surface command block (agents discover commands through this file)"],
+        apply() {
+          const cur = read(agentsMdPath);
+          const l = findLegacySurfaceSection(cur);
+          if (l) {
+            write(agentsMdPath, cur.slice(0, l.start) + fresh + "\n\n" + cur.slice(l.end), { force: true });
+          } else {
+            write(agentsMdPath, cur + (cur.endsWith("\n") ? "" : "\n") + "\n" + fresh + "\n", { force: true });
+          }
+        },
+      });
+    }
+  }
+
   // Markdown files: append stub sections for missing recommended headings.
   for (const [rel, sections] of [
     ["AGENTS.md", AGENTS_SECTIONS],
@@ -178,6 +223,15 @@ function checkTemplates() {
       if (hasHeading(text, heading)) ok.push(`AGENTS.md: ${heading}`);
       else findings.push(`AGENTS.md missing recommended section "${heading}"`);
     }
+    // Command-surface block: present and current vs the installed catalog.
+    const block = findSurfaceBlock(text);
+    if (!block) {
+      findings.push("AGENTS.md has no doctrina:surface block — agents discover commands through this file (`templates update --write` adds it)");
+    } else if (normalizeBlock(text.slice(block.start, block.end)) !== normalizeBlock(surfaceBlock())) {
+      findings.push("AGENTS.md doctrina:surface block is stale vs the installed CLI (`templates update --write` or `doctrina upgrade --write` regenerates it)");
+    } else {
+      ok.push("AGENTS.md: doctrina:surface block current");
+    }
   } else {
     findings.push("AGENTS.md missing at project root");
   }
@@ -194,6 +248,32 @@ function checkTemplates() {
     findings.push(".doctrina/product.md missing");
   }
 
+  // Installed agent adapters: every adapter is a thin POINTER at AGENTS.md
+  // (that is why one `upgrade --write` refresh of the hub reaches every
+  // installed agent). Verify the contract holds for each adapter file the
+  // project actually has: it must still reference AGENTS.md. The shipped
+  // adapter template tree is the inventory, so a new adapter is covered
+  // automatically.
+  try {
+    const templatesDir = locateTemplatesDir();
+    const adaptersRoot = path.join(templatesDir, "adapters");
+    if (isDir(adaptersRoot)) {
+      for (const agent of walk(adaptersRoot).map((f) => relPath(adaptersRoot, f))) {
+        const posix = agent.replace(/\\/g, "/");
+        if (posix.endsWith("README.md") || posix.endsWith(".gitkeep")) continue;
+        const rel = posix.split("/").slice(1).join("/").replace(/\.template$/, "");
+        if (!rel) continue;
+        const installed = path.join(projectRoot, rel);
+        if (!isFile(installed)) continue; // not installed — nothing to check
+        if (read(installed).includes("AGENTS.md")) {
+          ok.push(`adapter ${rel}: points at AGENTS.md`);
+        } else {
+          findings.push(`adapter ${rel} no longer references AGENTS.md — agents loading it will miss the hub (restore the pointer, e.g. re-run \`doctrina init --agent <name> --force\`)`);
+        }
+      }
+    }
+  } catch { /* no templates dir (unusual install) — skip the adapter pass */ }
+
   // index.json schema fields
   const indexPath = path.join(projectRoot, ".doctrina", "index.json");
   if (isFile(indexPath)) {
@@ -227,6 +307,24 @@ function checkTemplates() {
   return 1;
 }
 
+// Whitespace/EOL-insensitive comparison for the surface block, so a CRLF
+// checkout is not eternally "stale".
+function normalizeBlock(s) {
+  return s.replace(/\r\n/g, "\n").replace(/[ \t]+$/gm, "").trim();
+}
+
+// A pre-marker AGENTS.md's hand-written surface section: from the
+// "## Doctrina command surface" heading up to (excluding) the next "## "
+// heading. The trailing "Continuous: ..." paragraph the old template put
+// after the bullets belongs to the section body, so it is replaced too.
+function findLegacySurfaceSection(text) {
+  const head = text.match(/^##\s+Doctrina command surface.*$/m);
+  if (!head) return null;
+  const after = text.slice(head.index + head[0].length);
+  const next = after.match(/^##\s+/m);
+  return { start: head.index, end: next ? head.index + head[0].length + next.index : text.length };
+}
+
 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).
@@ -245,15 +343,20 @@ Subcommands:
             their relative paths and line counts.
   check     Compare the current project's AGENTS.md, product.md,
             and index.json against the recommended sections and
-            schema fields shipped in this CLI version. Reports any
-            recommended section that is missing. Read-only; never
-            modifies any files. Exits 1 when recommendations exist,
-            0 when the project follows the current template shape.
-  update    Additive-only fixer for what check reports: appends
-            missing recommended sections as stubs and adds missing
-            index.json fields. Preview by default (exits 1 while
-            updates are pending); pass --write to apply. Never
-            rewrites or removes existing content.
+            schema fields shipped in this CLI version — including
+            whether the AGENTS.md doctrina:surface block (the
+            CLI-owned, generated command catalog) is present and
+            current. Read-only; never modifies any files. Exits 1
+            when recommendations exist, 0 otherwise.
+  update    Fixer for what check reports: appends missing
+            recommended sections as stubs, adds missing index.json
+            fields, and regenerates the AGENTS.md doctrina:surface
+            block from the installed command catalog. Preview by
+            default (exits 1 while updates are pending); pass
+            --write to apply. Additive-only outside the surface
+            block: the marker-delimited span is the one CLI-owned
+            region it rewrites (ADR 0015); your content is never
+            touched.
 
 Distinct from \`doctrina validate\`: validate answers "is this a
 well-formed Doctrina tree?"; templates check answers "does this

package/src/commands/upgrade.js

@@ -0,0 +1,133 @@
+import path from "node:path";
+import process from "node:process";
+import { exists } from "../lib/fs-ops.js";
+import * as idx from "../lib/index-json.js";
+import { deriveIndex, indexesMatch } from "../lib/scan.js";
+import { cliVersion } from "../lib/version.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { today } from "../lib/dates.js";
+import * as templates from "./templates.js";
+import * as validate from "./validate.js";
+
+// Bring an existing project up to the installed CLI (user-reported gap: you
+// `npm update doctrina-cli`, but the project you once `doctrina init`-ed
+// keeps its old scaffold — stale framework stamp, an AGENTS.md that predates
+// new commands, missing recommended sections). `upgrade` is the one command
+// that closes that window, and it is an ORCHESTRATOR over the pieces that
+// already exist — templates update (additive-only), index rebuild (stamp
+// migration), validate --fix — so there is exactly one definition of each
+// step. Preview by default; --write applies. Never rewrites user content
+// (the same additive-only bound as `templates update`).
+
+export async function run(_positional, flags) {
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+  const writeMode = flagBool(flags, "write", false);
+  const running = cliVersion();
+
+  // 1. Version gap: what the tree was last managed by vs what is installed.
+  let index = null;
+  let stamped = null;
+  try {
+    index = idx.load(projectRoot);
+    stamped = index.framework_version ?? null;
+  } catch {
+    index = null;
+  }
+  console.log(c.bold("doctrina upgrade") + c.gray(` — project ${stamped ?? "unstamped"} → CLI ${running}${writeMode ? "" : " (preview; --write applies)"}`));
+  console.log("");
+  if (stamped === running) {
+    console.log(c.gray("The framework stamp already matches the installed CLI — checking the scaffold anyway."));
+    console.log("");
+  }
+
+  let pending = 0;
+
+  // 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)"));
+  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
+
+  // 3. Index: rebuild from the tree, which also migrates the framework stamp.
+  console.log("");
+  console.log(c.gray("──── 2/3 index + framework stamp"));
+  try {
+    const current = idx.load(projectRoot);
+    const drifted = !indexesMatch(deriveIndex(projectRoot, current), current);
+    const staleStamp = (current.framework_version ?? null) !== running;
+    if (!drifted && !staleStamp) {
+      console.log(c.green("ok") + " index.json matches the tree and the stamp is current");
+    } else if (writeMode) {
+      const derived = deriveIndex(projectRoot, current);
+      derived.last_updated = today();
+      idx.save(projectRoot, derived); // save() stamps framework_version
+      console.log(c.green("rebuilt") + ` index.json${staleStamp ? ` — stamp ${current.framework_version ?? "unstamped"} → ${running}` : ""}`);
+    } else {
+      if (drifted) console.log(c.yellow("would  ") + "rebuild index.json from the tree (drifted)");
+      if (staleStamp) console.log(c.yellow("would  ") + `migrate framework stamp ${current.framework_version ?? "unstamped"} → ${running}`);
+      pending += 1;
+    }
+  } catch {
+    if (writeMode) {
+      console.log(c.red("error: ") + "index.json is missing or unreadable — run `doctrina index rebuild` manually");
+    } else {
+      console.log(c.yellow("would  ") + "rebuild index.json (missing or unreadable)");
+      pending += 1;
+    }
+  }
+
+  // 4. Full structural check — surfaces what the upgrade cannot fix by
+  //    itself (new validate checks the old scaffold fails, hand-authored
+  //    drift). The command surface in AGENTS.md is NOT in this bucket any
+  //    more: step 1 regenerates the doctrina:surface block from the
+  //    installed catalog (ADR 0015). --fix under --write so the mechanical
+  //    part self-heals.
+  console.log("");
+  console.log(c.gray("──── 3/3 validate" + (writeMode ? " --fix" : "")));
+  const vFlags = writeMode ? new Map([["fix", true]]) : new Map();
+  const vCode = await validate.run([], vFlags);
+
+  console.log("");
+  if (!writeMode) {
+    if (pending > 0) {
+      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) {
+    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."));
+  } else {
+    console.log(c.yellow("upgraded with findings") + " — resolve the validate errors above (they predate or exceed what an additive upgrade can fix).");
+  }
+  return vCode;
+}
+
+export const help = `
+Usage: doctrina upgrade [--write]
+
+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
+                          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
+                          append missing recommended sections / index.json
+                          fields (additive-only outside the block)
+  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.
+`;