doctrina-cli 0.6.0 → 0.8.0

package/src/commands/why.js

@@ -0,0 +1,182 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
+import { specHeader, listHeader } from "../lib/scan.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+// Provenance explainer (review 2026-06-27 passive-user feature #5): answer
+// "why does this capability exist / why was it built this way?" by assembling
+// the chain the framework already records — product intent (the [SC1] anchors
+// it Realizes) → the capability's purpose → the acceptance criteria that prove
+// it → the accepted ADRs that decided it — into one read. The human (or agent)
+// asks; the tool answers from the artifacts, instead of grepping by hand.
+// Read-only. Builds on the Realizes:/trace provenance (ADR 0006/0011).
+
+export async function run(positional, _flags) {
+  const cap = positional[0];
+  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 specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const known = isDir(specsDir) ? readdirSync(specsDir).filter((e) => isFile(path.join(specsDir, e, "spec.md"))) : [];
+
+  if (!cap) {
+    console.error(c.red("error:") + " why requires a <capability>");
+    if (known.length) console.error(c.gray("known: ") + known.sort().join(", "));
+    return 2;
+  }
+  const specPath = path.join(specsDir, cap, "spec.md");
+  if (!isFile(specPath)) {
+    console.error(c.red("error:") + ` no spec for capability "${cap}"`);
+    const guess = suggest(cap, known);
+    if (guess) console.error(c.gray("hint: ") + `did you mean "${guess}"?`);
+    else if (known.length) console.error(c.gray("known: ") + known.sort().join(", "));
+    return 1;
+  }
+
+  const text = read(specPath);
+  console.log(c.bold(`Why "${cap}"`) + c.gray(" — provenance chain (intent → capability → proof → decisions)"));
+  console.log("");
+
+  // 1. Product intent it realizes.
+  const realizesRaw = specHeader(text, "Realizes");
+  const anchorIds = realizesRaw ? (realizesRaw.match(/[A-Z]+\d+/g) ?? []) : [];
+  console.log(c.bold("  Product intent"));
+  if (realizesRaw && /^n\/a\b/i.test(realizesRaw.trim())) {
+    console.log(`    ${c.gray("n/a — " + realizesRaw.trim().replace(/^n\/a\s*[—-]?\s*/i, ""))}`);
+  } else if (anchorIds.length === 0) {
+    console.log(`    ${c.yellow("none declared")} ${c.gray("— add a **Realizes:** header (doctrina trace)")}`);
+  } else {
+    const anchors = productAnchors(projectRoot);
+    for (const id of anchorIds) {
+      const line = anchors.get(id);
+      console.log(`    ${c.cyan(id)}  ${line ? line : c.yellow("(no matching anchor in product.md)")}`);
+    }
+  }
+
+  // 2. The capability itself.
+  console.log("");
+  console.log(c.bold("  Capability"));
+  const status = specHeader(text, "Status") ?? "—";
+  const impl = specHeader(text, "Implementation") ?? "—";
+  console.log(`    ${c.gray("status:")} ${status}   ${c.gray("implementation:")} ${impl}`);
+  const purpose = sectionParagraph(text, "Purpose");
+  if (purpose) console.log("    " + purpose.replace(/\s+/g, " ").trim());
+
+  // 3. The proof (acceptance criteria with cited evidence).
+  console.log("");
+  console.log(c.bold("  Proof"));
+  const criteria = acceptanceWithEvidence(text);
+  if (criteria.length === 0) {
+    console.log(`    ${c.gray("no acceptance criteria declared")}`);
+  } else {
+    for (const cr of criteria) {
+      const proof = cr.proof.length ? c.gray(cr.proof.map((p) => `\`${p}\``).join(", ")) : c.yellow("no evidence cited");
+      console.log(`    ${cr.mark} #${cr.n}  ${proof}`);
+    }
+  }
+
+  // 4. The decisions that shaped it (accepted ADRs naming the capability).
+  console.log("");
+  console.log(c.bold("  Decisions"));
+  const adrs = decisionsMentioning(projectRoot, cap);
+  if (adrs.length === 0) {
+    console.log(`    ${c.gray("no accepted ADR names this capability")}`);
+  } else {
+    for (const a of adrs) console.log(`    ${c.cyan("ADR " + a.id)}  ${a.title}`);
+  }
+
+  return 0;
+}
+
+// Map of anchor id -> the product.md bullet text that declares it.
+function productAnchors(projectRoot) {
+  const out = new Map();
+  const p = path.join(projectRoot, ".doctrina", "product.md");
+  if (!isFile(p)) return out;
+  for (const line of read(p).split(/\r?\n/)) {
+    const m = line.match(/^\s*[-*]\s+\[([A-Z]+\d+)\]\s+(.+)$/);
+    if (m && !out.has(m[1])) out.set(m[1], m[2].trim());
+  }
+  return out;
+}
+
+// First non-comment paragraph under a "## <name>" heading.
+function sectionParagraph(text, name) {
+  const lines = text.split(/\r?\n/);
+  let inSection = false;
+  const buf = [];
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      if (inSection) break;
+      if (new RegExp(`^##\\s+${name}\\b`, "i").test(line)) inSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    if (/^\s*<!--/.test(line) || /-->/.test(line)) continue;
+    if (line.trim() === "") {
+      if (buf.length) break;
+      continue;
+    }
+    buf.push(line.trim());
+  }
+  return buf.join(" ");
+}
+
+// Numbered acceptance criteria with their [mark] and any backtick proof paths.
+function acceptanceWithEvidence(text) {
+  const lines = text.split(/\r?\n/);
+  let inSection = false;
+  const out = [];
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      inSection = /^##\s+Acceptance criteria\b/i.test(line);
+      continue;
+    }
+    if (!inSection) continue;
+    const m = line.match(/^\s*(\d+)\.\s+(.*)$/);
+    if (!m) continue;
+    const body = m[2];
+    const markMatch = body.match(/^\[([^\]]+)\]/);
+    const mark = markMatch
+      ? (/^verified/i.test(markMatch[1]) ? c.green("✓") : c.yellow("○"))
+      : c.gray("·");
+    const proof = [...body.matchAll(/`([^`]+)`/g)].map((x) => x[1]).filter((s) => s.includes("/") || /\.[a-z0-9]{1,8}$/i.test(s));
+    out.push({ n: m[1], mark, proof });
+  }
+  return out;
+}
+
+// Accepted ADRs whose body names the capability (word-ish boundary).
+function decisionsMentioning(projectRoot, cap) {
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  const out = [];
+  if (!isDir(adrDir)) return out;
+  const re = new RegExp(`\\b${cap.replace(/[-]/g, "[- ]?")}\\b`, "i");
+  for (const f of readdirSync(adrDir).sort()) {
+    const m = f.match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(path.join(adrDir, f));
+    const status = (listHeader(text, "Status") ?? "").toLowerCase();
+    if (status !== "accepted") continue;
+    if (!re.test(text)) continue;
+    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+    out.push({ id: m[1], title: titleMatch ? titleMatch[1].trim() : f });
+  }
+  return out;
+}
+
+export const help = `
+Usage: doctrina why <capability>
+
+Explain a capability's provenance by assembling the chain Doctrina already
+records into one read: the product intent it **Realizes:** ([SC1] anchors),
+the capability's purpose and status, the acceptance criteria that prove it
+(with cited evidence), and the accepted ADRs that name it. Read-only.
+
+Builds on the intent provenance (ADR 0006/0011) — answer "why was X built,
+and built this way?" without grepping the tree by hand.
+`;

package/src/commands/work.js

@@ -333,6 +333,8 @@ function printChorePlaybook(projectRoot, { id, prompt }) {
   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")}.`);
+  console.log(c.gray("   If this fix taught a lesson worth not relearning, capture it: ") +
+    c.cyan("doctrina skill new <slug>") + c.gray("."));
 }
 
 function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, clarity, fromDiff = false, diffMatches = [] }) {
@@ -385,6 +387,10 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   console.log("");
   console.log("2. If the capability has no spec yet:");
   console.log(`       ${c.cyan("doctrina spec new <capability>")}`);
+  console.log(c.gray("   Trace it to product intent: tag the product.md success-criteria bullet"));
+  console.log(c.gray("   it serves with an anchor (\"- [SC1] ...\") and set the spec's"));
+  console.log(c.gray("   \"**Realizes:** SC1\" header (or \"n/a — <why>\"). `doctrina validate` warns"));
+  console.log(c.gray("   on an active spec with no Realizes; `doctrina trace` reports the link."));
   console.log("");
   console.log("3. Write one delta per affected capability at");
   console.log(`   .doctrina/changes/${id}/specs/<capability>/delta.md:`);
@@ -413,11 +419,14 @@ function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability, c
   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`);
+  console.log(`       ${c.cyan("doctrina trace")}      — the capability traces to product intent`);
   console.log("   Then check the proposal's ## Verification boxes and every task,");
   console.log("   closing steps included, and bump Implementation to verified.");
   console.log("");
   console.log(`9. ${c.cyan(`doctrina change archive ${id}`)}`);
   console.log(`10. ${c.cyan("doctrina validate")}, then ${c.cyan("doctrina next")} for the follow-up.`);
+  console.log(c.gray("    If this change taught a reusable lesson (a fix you'd hate to relearn,"));
+  console.log(c.gray("    a recurring convention), capture it: ") + c.cyan("doctrina skill new <slug>") + c.gray("."));
 }
 
 export const help = `

package/src/index.js

@@ -26,11 +26,17 @@ 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";
+import * as status from "./commands/status.js";
+import * as close from "./commands/close.js";
+import * as review from "./commands/review.js";
+import * as watch from "./commands/watch.js";
+import * as why from "./commands/why.js";
 
 const COMMANDS = {
   init, spec, change, decision, validate, hooks, analyze, clarify,
   templates, skill, index: indexCmd, next, metrics, context, search,
   intake, work, coverage, verify, contract, trace,
+  status, close, review, watch, why,
 };
 
 const TOP_HELP = `
@@ -56,6 +62,7 @@ Commands:
   skill new            Scaffold an on-demand procedural memory skill
   skill list           List skills with their descriptions
   skill sync           Mirror skill frontmatter descriptions into index.json
+  skill suggest        Surface fix-shaped lessons worth a skill (--write scaffolds)
   analyze              Inspect a change folder before applying
   clarify              Smell-test a Markdown file for ambiguity (--all for the tree)
   context              Print the context pack for a task in read order
@@ -63,12 +70,17 @@ Commands:
   validate             Run schema and structural checks
   coverage             Report acceptance criteria with linked evidence (--strict gates)
   trace                Report intent provenance: product intent → specs (--strict gates)
+  review               Conformance review of your changes vs specs/ADRs/contracts
   verify               Run project-declared typecheck/test/build checks (the real gate)
+  close                Run the whole close sequence for a change in one pass
+  status               One-glance project health dashboard
+  why                  Explain a capability's provenance (intent → proof → ADRs)
   templates list       List the templates shipped by the installed CLI
   templates check      Compare the project against the recommended template shape
   hooks install        Install the pre-commit hook
   index rebuild        Regenerate index.json from the artifacts on disk
   next                 Print the recommended next workflow actions
+  watch                Re-run validate --fix + next on every change (--once for one pass)
   metrics              Local git-derived adoption metrics (no network)
 
 Global flags:
@@ -78,7 +90,7 @@ Global flags:
 
 async function main(argv) {
   const { positional, flags } = parseArgs(argv, {
-    boolean: ["help", "h", "version", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive", "strict", "list", "init"],
+    boolean: ["help", "h", "version", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive", "strict", "list", "init", "fix", "once", "clean"],
   });
 
   if (flags.get("version") || flags.get("v")) {

package/templates/AGENTS.md.template

@@ -11,20 +11,47 @@ This repository uses the Doctrina framework for spec-driven, AGENTS.md
 native multi-agent development. The full framework artifacts live under
 `.doctrina/`.
 
-## Working from intent
-
-- **Bootstrap.** If `.doctrina/intake.md` exists with `Status: pending`,
-  the specs have not been written yet. Before anything else, run
-  `doctrina intake` and execute the printed bootstrap playbook in one
-  linear pass: fill `product.md`, derive capabilities, author one EARS
-  spec each, run the quality gates (`doctrina clarify --all`,
-  `doctrina validate`), then flip the intake to `Status: converted`. Ask
-  the user only when the intake is genuinely ambiguous. After conversion
-  the specs are the only source of truth — never edit `intake.md` to
-  change requirements.
-- **Day-to-day.** Turn a brief request into a scaffolded change with
-  `doctrina work "<prompt>"`, then follow the printed work playbook
-  (spec delta → tasks → implement → analyze → apply → archive → validate).
+## Working from intent (you drive; the human stays passive)
+
+You — the AI agent — run the Doctrina commands. The human gives a brief
+prompt and approves; do not make them run the CLI or hand-author artifacts.
+
+- **Bootstrap.** If `.doctrina/intake.md` is `Status: pending`, the specs
+  are not written yet: run `doctrina intake` and execute the printed
+  playbook in one pass (fill `product.md`, derive capabilities, one EARS
+  spec each, `doctrina clarify --all` + `doctrina validate`, then flip the
+  intake to `Status: converted`). After conversion the specs are the only
+  source of truth — never edit `intake.md` to change requirements.
+- **Day-to-day.** Turn any request into a change with `doctrina work
+  "<prompt>"` and follow the printed playbook (spec delta → tasks →
+  implement → analyze → apply → archive → validate). Unsure what to do
+  next? Run `doctrina next`. Need to read? Run `doctrina context`. Ask the
+  human only on genuine ambiguity.
+
+## Doctrina command surface (reach for these — don't hand-author)
+
+The CLI scaffolds from canonical templates and keeps `index.json` in sync,
+so prefer it over writing artifacts by hand. Full list: `doctrina --help`.
+
+- **Read / orient (any task, first & last):** `doctrina status` (health) ·
+  `doctrina context [<cap>] --concat` (read pack) · `doctrina next` (what's
+  next) · `doctrina why <cap>` (provenance) · `doctrina spec list` ·
+  `doctrina decision list` · `doctrina search <query>`
+- **Start:** `doctrina work "<prompt>"` · `--from-diff` (backfill from
+  existing code) · `--chore` (no-spec infra/docs/build)
+- **Scaffold (manual creation stays available):** `doctrina spec new <cap>`
+  (`--bug`) · `doctrina decision new "<title>"` · `doctrina change new <id>`
+  · `doctrina contract new <id>` · `doctrina skill new <slug>`
+- **Advance / close:** `doctrina change apply|archive|diff <id>` · `doctrina
+  decision accept|land|supersede <n>` · `doctrina spec set <cap> [...]` ·
+  `doctrina close <id>` (whole close in one pass)
+- **Gates (ground truth, not guesses):** `doctrina validate` (`--fix`) ·
+  `doctrina verify` · `doctrina review` (conformance vs specs/ADRs) ·
+  `doctrina coverage --strict` · `doctrina trace --strict` · `doctrina
+  contract check` · `doctrina clarify --all` · `doctrina analyze <id>`
+
+Continuous: `doctrina watch` re-syncs and re-orients on every save.
+Capture lessons: `doctrina skill suggest` surfaces skills worth writing.
 
 ## Stack and tooling
 
@@ -86,14 +113,14 @@ before considering work done.
 
 ## How to read context efficiently
 
-1. Read this `AGENTS.md`.
-2. Read `.doctrina/product.md`.
-3. Read the relevant `.doctrina/specs/<capability>/spec.md`.
-4. Read any open `.doctrina/changes/<id>/`.
-5. Read `.doctrina/decisions/` filtered by `Status: accepted`.
-6. If the task matches a skill in `.doctrina/skills/`, load the
-   relevant skill on demand (read its `description:` / `when:`
-   frontmatter; load the full body only when the trigger fires).
+`doctrina context [<capability>] --concat` assembles the read pack in one
+call, in order: this `AGENTS.md` → `.doctrina/product.md` → the capability
+spec → open `.doctrina/changes/<id>/` → `.doctrina/decisions/` filtered to
+`Status: accepted`. Run it for ANY task, not only `doctrina work`; it skips
+`changes/archive/` (history — read only when debugging it).
+
+On demand only: if the task matches a skill in `.doctrina/skills/`, read its
+`description:` / `when:` frontmatter; load the full body when the trigger fires.
 
 Keep this file under 150 lines. Density beats prose. Use exact commands.
 

package/templates/hooks/pre-commit.sample

@@ -1,7 +1,24 @@
 #!/usr/bin/env sh
 # Doctrina pre-commit hook.
-# Installed by `doctrina hooks install`. Runs validate and blocks the
-# commit if it exits non-zero. Edit freely after install; the CLI will
-# not overwrite without --force.
+# Installed by `doctrina hooks install`. Edit freely after install; the CLI
+# will not overwrite without --force.
+#
+# Runs `doctrina validate --fix`:
+#   1. --fix regenerates index.json from the tree (repairs metadata drift and
+#      migrates the framework_version stamp) BEFORE checking, so the single
+#      most common gate failure — a hand-edited header that drifted the index —
+#      is healed at commit time instead of blocking the commit.
+#   2. validate still exits non-zero (and blocks the commit) on real errors a
+#      rebuild cannot heal: missing artifacts, duplicate ADR numbers, broken
+#      EARS, ledger/index disagreement, and so on.
+#
+# To gate without auto-repairing (CI-style, fail on any drift), replace the
+# line below with a bare `doctrina validate`.
 
-doctrina validate
+doctrina validate --fix || exit 1
+
+# Re-stage the index if --fix rewrote it, so the repaired index lands in this
+# commit rather than as a leftover unstaged change. Harmless when unchanged.
+if [ -f .doctrina/index.json ]; then
+  git add .doctrina/index.json
+fi

package/templates/spec.md.template

@@ -3,6 +3,7 @@
 **Capability:** {{CAPABILITY}}
 **Status:** draft
 **Implementation:** planned
+**Realizes:** <product.md success-criteria anchors this delivers, or "n/a — <why>">
 **Last updated:** {{DATE}}
 **Version:** 0.1.0
 
@@ -18,9 +19,12 @@ behind it, and `doctrina validate` warns. To record a deliberate gap and
 silence the warning, add a note after the value, e.g.
 "**Implementation:** planned — backend deferred to Q3, see ADR 0007".
 
-Optional: trace this capability to product intent by adding a header
-"**Realizes:** SC1, SC3" that names the product.md anchors it delivers
-(`doctrina trace`; ADR 0006).
+Realizes ties this capability to product intent (`doctrina trace`;
+ADR 0006). Tag product.md success-criteria bullets with an anchor —
+"- [SC1] ..." — and list the ones this spec delivers above. An "active"
+spec with no Realizes: header warns under `doctrina validate`; if the
+capability genuinely maps to no product anchor (internal tooling), keep
+the header and write "n/a — <why>" to record that on purpose.
 -->
 
 ## Purpose