doctrina-cli 0.3.0 → 0.6.0

package/src/commands/work.js

@@ -1,9 +1,12 @@
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
-import { flagString } from "../lib/args.js";
+import { flagString, flagBool } from "../lib/args.js";
+import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
+import { assessBrief } from "../lib/clarity.js";
 import { changeNew } from "./change.js";
 
 // `work` is the second half of the no-ceremony path (ADR 0005): a brief
@@ -16,15 +19,49 @@ import { changeNew } from "./change.js";
 
 export async function run(positional, flags) {
   const prompt = positional.join(" ").trim();
-  if (!prompt) {
+  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.");
+  }
+
+  // --resume <id>: reprint the playbook for an existing open change rather than
+  // open a new one (review G1 — `work "continue"` used to slug the word and
+  // fabricate a junk `NNNN-continue` change the operator had to delete).
+  if (flags.has("resume")) {
+    return resumeChange(projectRoot, flagString(flags, "resume"));
+  }
+
+  // --from-diff backfills from code already written (review F8): the
+  // working-tree changes are the input, so no prompt is required.
+  const fromDiff = flagBool(flags, "from-diff", false);
+  const chore = flagBool(flags, "chore", false) || flagBool(flags, "no-spec", false);
+  let files = [];
+  if (fromDiff) {
+    files = changedFiles(projectRoot);
+    if (files.length === 0) {
+      console.error(c.red("error:") + " --from-diff found no working-tree changes to backfill from");
+      console.error(c.gray("hint: ") + "make (or stage) the code changes first, then run `doctrina work --from-diff`");
+      return 1;
+    }
+  }
+
+  if (!prompt && !fromDiff) {
     console.error(c.red("error:") + " work requires a prompt (quote it if it contains spaces)");
     console.error(c.gray("hint: ") + "example: doctrina work \"add login with email and password\"");
     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.");
+  // A thin, resume-shaped prompt ("continue", "prossiga", ...) while a change
+  // is open is almost certainly "finish what's open", not "start a change named
+  // after that word". Suggest resuming instead of creating noise; --force opens
+  // a new change anyway. The match is a deterministic stoplist, not language
+  // understanding (still ADR 0005).
+  if (!fromDiff && !flagBool(flags, "force", false) && isResumeIntent(prompt)) {
+    const open = openChanges(projectRoot);
+    if (open.length > 0) {
+      printResumeSuggestion(open);
+      return 0;
+    }
   }
 
   const pinned = flagString(flags, "capability");
@@ -33,37 +70,74 @@ export async function run(positional, flags) {
     return 2;
   }
 
-  const id = flagString(flags, "id") ?? `${nextChangeNumber(projectRoot)}-${slugify(prompt)}`;
+  const effPrompt = prompt || `backfill specs from ${files.length} changed file${files.length === 1 ? "" : "s"}`;
+  const slug = prompt ? slugify(prompt) : "backfill";
+  const id = flagString(flags, "id") ?? `${nextChangeNumber(projectRoot)}-${slug}`;
   if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
     console.error(c.red("error:") + ` invalid change id "${id}" (lowercase letters, digits, hyphens)`);
     return 2;
   }
 
-  const code = changeNew([id, prompt], flags);
+  const code = changeNew([id, effPrompt], flags);
   if (code !== 0) return code;
 
   // Record the prompt verbatim as the change's Why — the raw intent has
-  // one home, and it is the proposal, not the playbook output.
+  // one home, and it is the proposal, not the playbook output. For --from-diff,
+  // also record the changed files so the backfill's input is in the artifact.
   const proposalPath = path.join(projectRoot, ".doctrina", "changes", id, "proposal.md");
   if (isFile(proposalPath)) {
     const txt = read(proposalPath);
+    let why = effPrompt;
+    if (fromDiff) {
+      const list = files.slice(0, 30).map((f) => `- \`${f}\``).join("\n");
+      const more = files.length > 30 ? `\n- … and ${files.length - 30} more` : "";
+      why = `${effPrompt}\n\nBackfilled from working-tree changes:\n${list}${more}`;
+    }
     // CRLF-tolerant: templates may be checked out with \r\n on Windows.
-    let updated = txt.replace(/(## Why\r?\n\r?\n)<!--[\s\S]*?-->[ \t]*\r?\n?/, `$1${prompt}\n`);
-    if (updated === txt) updated = txt.replace(/(## Why\r?\n)/, `$1\n${prompt}\n`);
+    let updated = txt.replace(/(## Why\r?\n\r?\n)<!--[\s\S]*?-->[ \t]*\r?\n?/, `$1${why}\n`);
+    if (updated === txt) updated = txt.replace(/(## Why\r?\n)/, `$1\n${why}\n`);
     if (pinned) {
       updated = updated.replace(/^(-\s+\*\*Affects specs:\*\*).*$/m, `$1 ${pinned}`);
     }
     if (updated !== txt) write(proposalPath, updated, { force: true });
   }
 
-  const matches = pinned ? [] : rankCapabilities(projectRoot, prompt);
+  // Capability hint: term overlap for a prompt, changed-file overlap for a diff
+  // (review F10 — rank by what the working tree touched, not just prompt words).
+  const allChanged = fromDiff ? files : changedFiles(projectRoot);
+  const diffMatches = pinned ? [] : rankCapabilitiesByDiff(projectRoot, allChanged);
+  const matches = pinned ? [] : (fromDiff ? diffMatches : rankCapabilities(projectRoot, effPrompt));
   const capability = pinned ?? matches[0]?.id ?? null;
+  const clarity = assessBrief(effPrompt, { kind: "prompt" });
 
   console.log("");
-  printPlaybook(projectRoot, { id, prompt, pinned, matches, capability });
+  if (chore) {
+    printChorePlaybook(projectRoot, { id, prompt: effPrompt });
+  } else {
+    printPlaybook(projectRoot, {
+      id, prompt: effPrompt, pinned, matches, capability, clarity,
+      fromDiff, diffMatches: fromDiff ? [] : diffMatches,
+    });
+  }
   return 0;
 }
 
+// Changed files in the working tree (tracked + untracked), for the diff-based
+// capability hint and `--from-diff` backfill. Empty outside a git repo or with
+// no changes. Read-only: never invokes a mutating git command.
+function changedFiles(projectRoot) {
+  const run = (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([
+    ...run(["diff", "--name-only", "HEAD"]),                 // tracked, staged + unstaged
+    ...run(["ls-files", "--others", "--exclude-standard"]),  // untracked
+  ]);
+  return [...set];
+}
+
 // Next sequential NNNN across open changes and the archive, so work-driven
 // ids stay ordered no matter how earlier changes were named.
 function nextChangeNumber(projectRoot) {
@@ -89,6 +163,70 @@ function nextChangeNumber(projectRoot) {
   return String(max + 1).padStart(4, "0");
 }
 
+// Open (non-archived) changes from the index — the set `work --resume` and
+// the thin-prompt guard offer to continue.
+function openChanges(projectRoot) {
+  try {
+    return idx.load(projectRoot).artifacts?.changes ?? [];
+  } catch {
+    return [];
+  }
+}
+
+// A deterministic stoplist of "carry on" prompts (en + pt). Folded and
+// stripped to letters so "go on" / "keep going" / "continuação" all match.
+// Not language understanding — just the words that mean "resume", which is
+// exactly when slugging the prompt produces a junk change (G1).
+const RESUME_WORDS = new Set([
+  "continue", "continua", "continuar", "continuacao", "continuemos", "continuando",
+  "prossiga", "prosseguir", "prossegue", "proceed", "resume", "resumir",
+  "retomar", "retoma", "segue", "seguir", "go", "goon", "next", "keepgoing",
+  "vamos", "more", "mais",
+]);
+
+function isResumeIntent(prompt) {
+  return RESUME_WORDS.has(fold(prompt).replace(/[^a-z0-9]+/g, ""));
+}
+
+function printResumeSuggestion(open) {
+  console.log(c.yellow(`open change${open.length === 1 ? "" : "s"} detected`) +
+    " — did you mean to continue one of these?");
+  console.log("");
+  for (const ch of open) {
+    console.log(`    ${c.cyan(ch.id)}  ${c.gray((ch.title ?? "").slice(0, 60))}  ${c.gray(`[${ch.status ?? "open"}]`)}`);
+  }
+  console.log("");
+  console.log("Resume the existing change (reprints its playbook):");
+  console.log(`    ${c.cyan(`doctrina work --resume ${open[0].id}`)}`);
+  console.log("Or open a new change anyway:");
+  console.log(`    ${c.cyan(`doctrina work "<prompt>" --force`)}`);
+}
+
+// Reprint the work playbook for an already-open change, ranking capabilities
+// from its recorded title (the original prompt). Creates nothing.
+function resumeChange(projectRoot, resumeId) {
+  const open = openChanges(projectRoot);
+  if (!resumeId || resumeId === true) {
+    console.error(c.red("error:") + " --resume needs a change id");
+    if (open.length) console.error(c.gray("open: ") + open.map((ch) => ch.id).join(", "));
+    return 2;
+  }
+  const entry = open.find((ch) => ch.id === resumeId);
+  if (!entry && !isDir(path.join(projectRoot, ".doctrina", "changes", resumeId))) {
+    console.error(c.red("error:") + ` no open change "${resumeId}"`);
+    if (open.length) console.error(c.gray("open: ") + open.map((ch) => ch.id).join(", "));
+    return 1;
+  }
+  const prompt = entry?.title ?? resumeId;
+  const matches = rankCapabilities(projectRoot, prompt);
+  const capability = matches[0]?.id ?? null;
+  const clarity = assessBrief(prompt, { kind: "prompt" });
+  console.log(c.bold(`Resuming change ${resumeId}`) + c.gray(" — agent-executed (ADR 0005)."));
+  console.log("");
+  printPlaybook(projectRoot, { id: resumeId, prompt, pinned: null, matches, capability, clarity });
+  return 0;
+}
+
 // ASCII-folded kebab-case of the prompt ("Faça o login" -> "faca-o-login").
 export function slugify(text) {
   let slug = text
@@ -150,23 +288,93 @@ export function rankCapabilities(projectRoot, prompt) {
   return ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, 3);
 }
 
-function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability }) {
+// Rank capabilities by the working tree, not the prompt (review F10): a changed
+// file scores its capability when the file sits under a path segment named for
+// it, or when the spec cites the file as evidence. A deterministic overlap
+// hint for the agent — never a decision (ADR 0005).
+export function rankCapabilitiesByDiff(projectRoot, files) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (!files || files.length === 0 || !isDir(specsDir)) return [];
+  const norm = files.map((f) => f.replace(/\\/g, "/"));
+
+  const ranked = [];
+  for (const cap of readdirSync(specsDir).sort()) {
+    const specPath = path.join(specsDir, cap, "spec.md");
+    if (!isFile(specPath)) continue;
+    const specText = read(specPath);
+    let score = 0;
+    for (const f of norm) {
+      if (f.split("/").includes(cap)) score += 3;            // src/<cap>/... etc.
+      if (specText.includes(f)) score += 5;                  // file cited in the spec
+      else if (specText.includes(path.basename(f))) score += 2; // filename cited
+    }
+    if (score > 0) ranked.push({ id: cap, score, path: `.doctrina/specs/${cap}/spec.md` });
+  }
+  return ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, 3);
+}
+
+// A chore is a spec-less change (review F9): the playbook drops the spec-delta
+// steps and goes straight to implement → verify → archive → validate, so the
+// agent is not prompted to invent a delta for infra/docs/build work.
+function printChorePlaybook(projectRoot, { id, prompt }) {
+  console.log(c.bold(`Chore playbook — change ${id}`) + c.gray(" — agent-executed (ADR 0005); no spec deltas."));
+  console.log("");
+  console.log(`Prompt: "${prompt}"`);
+  console.log("");
+  console.log("Execute in order, in a single linear pass:");
+  console.log("");
+  console.log(`1. Replace the placeholder tasks in .doctrina/changes/${id}/tasks.md`);
+  console.log("   with small, checkable steps; implement them, checking each box.");
+  console.log("2. Prove it (archive refuses unchecked boxes):");
+  console.log(`       ${c.cyan("doctrina verify")}     — the project's typecheck/test/build gate`);
+  console.log(`       ${c.cyan("doctrina verify --clean")} — clean-checkout reproducibility lint`);
+  console.log("   Then check the proposal's ## Verification boxes and every task.");
+  console.log("3. This is a chore: no spec changes. If you find yourself needing a");
+  console.log(`   spec delta, it is not a chore — reopen with ${c.cyan("doctrina work \"<prompt>\"")}.`);
+  console.log(`4. ${c.cyan(`doctrina change apply ${id}`)}  (zero deltas → flips to applied).`);
+  console.log(`5. ${c.cyan(`doctrina change archive ${id}`)}, then ${c.cyan("doctrina validate")}.`);
+}
+
+function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, clarity, fromDiff = false, diffMatches = [] }) {
   const capToken = capability ?? "<capability>";
-  console.log(c.bold(`Work playbook — change ${id}`) + c.gray(" — agent-executed (ADR 0005)."));
+  const title = fromDiff ? "Backfill playbook" : "Work playbook";
+  console.log(c.bold(`${title} — change ${id}`) + c.gray(" — agent-executed (ADR 0005)."));
   console.log("");
   console.log(`Prompt: "${prompt}"`);
+  if (fromDiff) {
+    console.log(c.gray("Code-first: write the spec that describes what the working tree already does."));
+  }
+
+  // Clarification gate (review Topic A): a thin prompt is the moment to ask
+  // the user, not to invent a spec. Advisory — the change is still scaffolded
+  // (it is a draft), but the agent is told to resolve the gaps first.
+  if (clarity?.thin && !fromDiff) {
+    console.log("");
+    console.log(c.yellow("⚠ thin prompt — clarify with the user before writing spec deltas:"));
+    for (const r of clarity.reasons) console.log(`    - ${r}`);
+  }
 
   if (pinned) {
     const hasSpec = isFile(path.join(projectRoot, ".doctrina", "specs", pinned, "spec.md"));
     console.log(`Capability (pinned): ${c.cyan(pinned)}` +
       (hasSpec ? "" : c.yellow(" — no spec yet; create it in step 2")));
   } else if (matches.length > 0) {
-    console.log("Likely capabilities (deterministic term match — a hint, not a decision):");
+    const how = fromDiff ? "touched by your working tree" : "deterministic term match";
+    console.log(`Likely capabilities (${how} — a hint, not a decision):`);
     for (const m of matches) {
       console.log(`    ${c.cyan(m.id.padEnd(20))} score ${String(m.score).padStart(3)}   ${c.gray(m.path)}`);
     }
   } else {
-    console.log(c.gray("No existing spec matches the prompt — likely a new capability."));
+    console.log(c.gray(fromDiff
+      ? "No existing spec matches the changed files — likely a new capability."
+      : "No existing spec matches the prompt — likely a new capability."));
+  }
+
+  // Extra signal (review F10): even for a prompt-driven change, show which
+  // capabilities the working tree touched — often the truer hint.
+  if (!fromDiff && diffMatches.length > 0) {
+    console.log(c.gray("Also touched by your working tree: ") +
+      diffMatches.map((m) => c.cyan(m.id)).join(", "));
   }
 
   console.log("");
@@ -187,6 +395,11 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability })
   console.log(c.gray("       <EARS body. Keep the two axes honest (Status vs Implementation),"));
   console.log(c.gray("        keep aspiration under ## Maturity → Future, and cite the proof per"));
   console.log(c.gray("        criterion: \"1. [unverified] <signal> — verified by `path/to/test`\">"));
+  if (fromDiff) {
+    console.log(c.gray("   --from-diff: the code already exists — describe its CURRENT behaviour, and"));
+    console.log(c.gray("   mark each criterion [unverified] until a test proves it (don't assume the"));
+    console.log(c.gray("   diff is tested). The changed files are listed in the proposal's ## Why."));
+  }
   console.log("");
   console.log(`4. Replace the placeholder tasks in .doctrina/changes/${id}/tasks.md`);
   console.log("   with small, checkable implementation tasks (a few hours each, max).");
@@ -196,7 +409,7 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability })
   console.log("   If the prompt is genuinely ambiguous, ask the user before assuming.");
   console.log("");
   console.log(`6. ${c.cyan(`doctrina analyze ${id}`)} — fix every ✗ before applying.`);
-  console.log(`7. ${c.cyan(`doctrina change apply ${id}`)}   (MODIFIED deltas are merged by hand).`);
+  console.log(`7. ${c.cyan(`doctrina change apply ${id}`)}   (MODIFIED with an ops block applies mechanically; prose merges by hand).`);
   console.log("8. Prove it before declaring done (archive refuses unchecked boxes):");
   console.log(`       ${c.cyan("doctrina verify")}     — the project's typecheck/test/build gate`);
   console.log(`       ${c.cyan("doctrina coverage")}   — each acceptance criterion cites a real test`);
@@ -214,13 +427,24 @@ Turn a brief prompt into a scaffolded change plus the work playbook the
 host AI agent executes (see ADR 0005). The CLI derives a sequential
 change id (NNNN-<slug>) from the prompt, opens the change folder,
 records the prompt under the proposal's "## Why", ranks existing specs
-by term overlap as a capability hint, and prints the ordered steps:
+by term overlap as a capability hint, flags a thin/under-specified prompt
+so you clarify before writing deltas (advisory), and prints the steps:
 context → spec delta → tasks → implement → analyze → apply → verify
 (verify + coverage) → archive → validate. No natural-language
 interpretation happens in the CLI.
 
+When the prompt is a bare "continue"/"prossiga"/"next" and a change is
+already open, work suggests resuming it instead of opening a junk change
+named after that word (review G1). Use --resume to do so directly.
+
 Options:
   --capability <cap>   Pin the capability instead of ranking matches
   --id <id>            Override the derived change id
-  --force              Overwrite an existing change folder
+  --resume <id>        Reprint the playbook for an open change; create nothing
+  --from-diff          Backfill: scaffold from the working-tree changes (no
+                       prompt needed) and print a code-first playbook (F8)
+  --chore, --no-spec   Open a spec-less chore change (infra/docs/build) with a
+                       playbook that skips the spec-delta steps (F9)
+  --force              Open a new change even when one is open, and overwrite
+                       an existing change folder
 `;

package/src/index.js

@@ -1,11 +1,9 @@
 #!/usr/bin/env node
 import process from "node:process";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { readFileSync } from "node:fs";
 import { parseArgs } from "./lib/args.js";
 import { c } from "./lib/colors.js";
 import { suggest } from "./lib/suggest.js";
+import { cliVersion } from "./lib/version.js";
 
 import * as init from "./commands/init.js";
 import * as spec from "./commands/spec.js";
@@ -27,11 +25,12 @@ import * as work from "./commands/work.js";
 import * as coverage from "./commands/coverage.js";
 import * as verify from "./commands/verify.js";
 import * as contract from "./commands/contract.js";
+import * as trace from "./commands/trace.js";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
   templates, skill, index: indexCmd, next, metrics, context, search,
-  intake, work, coverage, verify, contract,
+  intake, work, coverage, verify, contract, trace,
 };
 
 const TOP_HELP = `
@@ -51,6 +50,7 @@ Commands:
   contract check       Verify port collisions, env drift, referenced specs
   decision new         Create the next sequentially numbered ADR
   decision accept      Flip a proposed ADR to accepted
+  decision land        Record that an accepted ADR is now implemented (non-mutating)
   decision supersede   Create a new ADR that supersedes an existing one
   decision list        List ADRs with status, date, and title
   skill new            Scaffold an on-demand procedural memory skill
@@ -62,6 +62,7 @@ Commands:
   search               Search the artifact tree, grouped by category
   validate             Run schema and structural checks
   coverage             Report acceptance criteria with linked evidence (--strict gates)
+  trace                Report intent provenance: product intent → specs (--strict gates)
   verify               Run project-declared typecheck/test/build checks (the real gate)
   templates list       List the templates shipped by the installed CLI
   templates check      Compare the project against the recommended template shape
@@ -81,7 +82,7 @@ async function main(argv) {
   });
 
   if (flags.get("version") || flags.get("v")) {
-    console.log(readVersion());
+    console.log(cliVersion());
     return 0;
   }
 
@@ -119,14 +120,4 @@ async function main(argv) {
   }
 }
 
-function readVersion() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  const pkgPath = path.resolve(here, "..", "package.json");
-  try {
-    return JSON.parse(readFileSync(pkgPath, "utf8")).version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
-
 main(process.argv.slice(2)).then((code) => process.exit(code ?? 0));

package/src/lib/clarity.js

@@ -0,0 +1,49 @@
+// Deterministic under-specification detector for free-text briefs and
+// intakes — the clarification gate (review Topic A). It does NOT judge
+// meaning (that stays the agent's job, ADR 0005); it flags input that is
+// structurally too thin to spec from, so `intake` and `work` prompt the
+// agent to clarify with the user before speculating a spec or change out of
+// too little. Advisory only: it surfaces the gap, it does not block.
+
+const WEASEL = /\b(might|could|perhaps|maybe|probably|somehow|approximately|roughly|etc)\b/gi;
+const VAGUE = /\b(some|several|various|appropriate|robust|scalable|nice|good|better|fast|simple|stuff|things?)\b/gi;
+
+// Generic verbs/nouns that carry no capability information on their own. A
+// brief made only of these ("add the feature", "do the thing") names nothing
+// concrete to build.
+const FILLER = new Set([
+  "the", "and", "for", "with", "this", "that", "something", "anything",
+  "make", "add", "create", "build", "implement", "feature", "thing",
+  "things", "stuff", "task", "work", "please", "just", "some", "any",
+]);
+
+// Assess a brief/intake. `kind` tunes the thresholds: a one-line work prompt
+// is held to a lower bar than a full project intake.
+export function assessBrief(text, { kind = "prompt" } = {}) {
+  const clean = String(text ?? "").replace(/\s+/g, " ").trim();
+  const tokens = clean ? clean.split(" ") : [];
+  const words = tokens.length;
+  const vague = (clean.match(VAGUE) ?? []).length + (clean.match(WEASEL) ?? []).length;
+  const meaningful = tokens
+    .map((t) => t.toLowerCase().replace(/[^a-z0-9]/g, ""))
+    .filter((t) => t.length >= 3 && !FILLER.has(t));
+
+  const minWords = kind === "intake" ? 20 : 3;
+  const maxVague = kind === "intake" ? 4 : 2;
+
+  const reasons = [];
+  if (words < minWords) {
+    reasons.push(
+      `only ${words} word${words === 1 ? "" : "s"} — say what the behaviour is, ` +
+        `what the inputs are, and how you'll know it's done`,
+    );
+  }
+  if (words > 0 && meaningful.length === 0) {
+    reasons.push("no concrete terms once filler words are removed — name the actual capability or behaviour");
+  }
+  if (vague >= maxVague) {
+    reasons.push(`${vague} vague/weasel term${vague === 1 ? "" : "s"} — replace with definite, checkable wording`);
+  }
+
+  return { thin: reasons.length > 0, words, reasons };
+}

package/src/lib/index-json.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import { read, write, exists } from "./fs-ops.js";
+import { cliVersion } from "./version.js";
 
-const SCHEMA_VERSION = "0.1.0";
+export const SCHEMA_VERSION = "0.1.0";
 
 export function indexPath(projectRoot) {
   return path.join(projectRoot, ".doctrina", "index.json");
@@ -21,6 +22,11 @@ export function load(projectRoot) {
 }
 
 export function save(projectRoot, index) {
+  // Stamp the managing framework version on every write (3.6): the index
+  // records which CLI last wrote it, so a stale stamp (an index written by an
+  // older CLI) is detectable by `doctrina validate` and migrated by
+  // `doctrina index rebuild`.
+  index.framework_version = cliVersion();
   const p = indexPath(projectRoot);
   const text = JSON.stringify(index, null, 2) + "\n";
   write(p, text, { force: true });
@@ -30,7 +36,7 @@ export function blank(projectName, date) {
   return {
     $schema_version: SCHEMA_VERSION,
     project: projectName,
-    framework_version: "0.0.0",
+    framework_version: cliVersion(),
     last_updated: date,
     artifacts: {
       product: {

package/src/lib/scan.js

@@ -81,6 +81,12 @@ export function deriveIndex(projectRoot, current) {
     const implRaw = specHeader(text, "Implementation");
     const impl = implRaw ? implRaw.trim() : prev?.implementation;
     if (impl) entry.implementation = impl;
+    // Realizes: the product intent anchors this capability delivers (ADR
+    // 0006). Stored as an id list so the provenance link is queryable, not
+    // just prose. Header wins over the previous index, like Implementation.
+    const realizesRaw = specHeader(text, "Realizes");
+    const realizes = realizesRaw ? (realizesRaw.match(/[A-Z]+\d+/g) ?? []) : prev?.realizes;
+    if (realizes && realizes.length) entry.realizes = realizes;
     out.artifacts.specs.push(entry);
   }
 
@@ -104,6 +110,8 @@ export function deriveIndex(projectRoot, current) {
     if (supersedes && supersedes !== "—") entry.supersedes = supersedes;
     const supersededBy = listHeader(text, "Superseded by");
     if (supersededBy && supersededBy !== "—") entry.superseded_by = supersededBy;
+    const landed = listHeader(text, "Landed");
+    if (landed && landed !== "—") entry.landed = landed;
     out.artifacts.decisions.push(entry);
   }