doctrina-cli 0.1.1 → 0.2.0

package/src/commands/metrics.js

@@ -0,0 +1,190 @@
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, read, relPath, write } from "../lib/fs-ops.js";
+import { today } from "../lib/dates.js";
+import { flagBool, flagString } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+
+// Local-only adoption metrics derived from git history. No network calls,
+// no telemetry: the numbers stay in the repository, versioned like any
+// other artifact. This is the tooling half of docs/en/validation.md.
+
+const REEDIT_WINDOW_DAYS = 21;
+
+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 probe = git(projectRoot, ["rev-parse", "--is-inside-work-tree"]);
+  if (probe.status !== 0) {
+    console.error(c.red("error:") + " not a git repository (metrics are derived from local git history)");
+    return 1;
+  }
+
+  const sinceRaw = flagString(flags, "since", "90");
+  const since = /^\d+$/.test(sinceRaw) ? `${sinceRaw} days ago` : sinceRaw;
+  const save = flagBool(flags, "save", false);
+
+  const log = git(projectRoot, [
+    "log", `--since=${since}`, "--date=unix",
+    "--pretty=format:@@%H|%ct|%s", "--name-only",
+  ]);
+  if (log.status !== 0) {
+    console.error(c.red("error:") + ` git log failed: ${log.stderr.trim()}`);
+    return 1;
+  }
+
+  const commits = parseLog(log.stdout);
+  console.log(c.bold("Doctrina metrics") + c.gray(` (local git history, window: ${since})`));
+  console.log("");
+  if (commits.length === 0) {
+    console.log(c.gray("no commits in the window; nothing to measure"));
+    return 0;
+  }
+
+  const snapshot = computeSnapshot(commits, since);
+  printReport(snapshot);
+
+  if (save) {
+    const dir = path.join(projectRoot, ".doctrina", "metrics");
+    const file = path.join(dir, `${today()}.json`);
+    const previous = latestSnapshot(dir, path.basename(file));
+    write(file, JSON.stringify(snapshot, null, 2) + "\n", { force: true });
+    console.log("");
+    console.log(c.green("saved") + ` ${relPath(projectRoot, file)}`);
+    if (previous) {
+      console.log("");
+      console.log(c.bold("Δ vs " + previous.generated + ":"));
+      printDelta("revert rate", previous.revert_rate, snapshot.revert_rate);
+      printDelta("fix share", previous.fix_share, snapshot.fix_share);
+      printDelta(`${REEDIT_WINDOW_DAYS}-day re-edit rate`, previous.reedit_rate, snapshot.reedit_rate);
+    }
+  }
+  return 0;
+}
+
+function computeSnapshot(commits, since) {
+  const total = commits.length;
+  const reverts = commits.filter((cm) => /^Revert\b/.test(cm.subject)).length;
+  const fixes = commits.filter((cm) => /^fix[(:!]/.test(cm.subject)).length;
+
+  // File churn: commits per file, top offenders first.
+  const churn = new Map();
+  for (const cm of commits) {
+    for (const f of cm.files) churn.set(f, (churn.get(f) ?? 0) + 1);
+  }
+  const topChurn = [...churn.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([file, count]) => ({ file, commits: count }));
+
+  // Re-edit proxy: a commit counts when it touches a file another commit
+  // already touched in the previous REEDIT_WINDOW_DAYS. This is a proxy
+  // for rework, not a verdict — iterative work also trips it.
+  const windowSec = REEDIT_WINDOW_DAYS * 86400;
+  const lastTouch = new Map();
+  let reedits = 0;
+  for (const cm of [...commits].sort((a, b) => a.ts - b.ts)) {
+    const isReedit = cm.files.some((f) => {
+      const prev = lastTouch.get(f);
+      return prev !== undefined && cm.ts - prev <= windowSec;
+    });
+    if (isReedit) reedits += 1;
+    for (const f of cm.files) lastTouch.set(f, cm.ts);
+  }
+
+  return {
+    generated: today(),
+    window: since,
+    commits: total,
+    reverts,
+    revert_rate: round(reverts / total),
+    fix_share: round(fixes / total),
+    reedit_window_days: REEDIT_WINDOW_DAYS,
+    reedit_rate: round(reedits / total),
+    top_churn: topChurn,
+  };
+}
+
+function printReport(s) {
+  console.log(`commits                ${s.commits}`);
+  console.log(`reverts                ${s.reverts} (${pct(s.revert_rate)})`);
+  console.log(`fix-typed commits      ${pct(s.fix_share)} of commits (Conventional Commits "fix")`);
+  console.log(`${s.reedit_window_days}-day re-edit rate     ${pct(s.reedit_rate)} of commits touch a file edited in the prior ${s.reedit_window_days} days`);
+  console.log(c.gray("                       (proxy for rework — iterative work also counts)"));
+  if (s.top_churn.length > 0) {
+    console.log("");
+    console.log("top churn:");
+    for (const t of s.top_churn) {
+      console.log(`  ${String(t.commits).padStart(4)}  ${t.file}`);
+    }
+  }
+}
+
+function printDelta(label, before, after) {
+  if (before === undefined || after === undefined) return;
+  const diff = after - before;
+  const arrow = diff > 0 ? c.red(`+${pct(diff)}`) : diff < 0 ? c.green(pct(diff)) : c.gray("±0");
+  console.log(`  ${label}: ${pct(before)} → ${pct(after)} (${arrow})`);
+}
+
+function latestSnapshot(dir, excludeBase) {
+  if (!isDir(dir)) return null;
+  const files = readdirSync(dir)
+    .filter((f) => /^\d{4}-\d{2}-\d{2}\.json$/.test(f) && f !== excludeBase)
+    .sort();
+  if (files.length === 0) return null;
+  try {
+    return JSON.parse(read(path.join(dir, files[files.length - 1])));
+  } catch {
+    return null;
+  }
+}
+
+function parseLog(stdout) {
+  const commits = [];
+  let current = null;
+  for (const line of stdout.split("\n")) {
+    if (line.startsWith("@@")) {
+      const [hash, ts, ...rest] = line.slice(2).split("|");
+      current = { hash, ts: Number(ts), subject: rest.join("|"), files: [] };
+      commits.push(current);
+    } else if (line.trim() !== "" && current) {
+      current.files.push(line.trim());
+    }
+  }
+  return commits;
+}
+
+function git(cwd, args) {
+  return spawnSync("git", args, { cwd, encoding: "utf8" });
+}
+
+function round(x) {
+  return Math.round(x * 1000) / 1000;
+}
+
+function pct(x) {
+  return `${(x * 100).toFixed(1)}%`;
+}
+
+export const help = `
+Usage: doctrina metrics [--since <days|date>] [--save]
+
+Derive adoption metrics from LOCAL git history: commit count, revert
+count and rate, Conventional-Commit fix share, top-churn files, and a
+${REEDIT_WINDOW_DAYS}-day re-edit proxy rate. No network calls; nothing leaves the repo.
+
+Flags:
+  --since <n|date>   Window: a day count (default 90) or any git-parseable
+                     date ("2026-01-01", "3 months ago").
+  --save             Write .doctrina/metrics/YYYY-MM-DD.json and print the
+                     deltas against the most recent prior snapshot.
+
+This is the tooling half of the empirical A/B protocol in
+docs/en/validation.md: snapshot before adopting Doctrina, snapshot each
+month after, compare.
+`;

package/src/commands/next.js

@@ -0,0 +1,108 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
+import * as idx from "../lib/index-json.js";
+import { deriveIndex, indexesMatch, listHeader } from "../lib/scan.js";
+import { c } from "../lib/colors.js";
+
+export async function run(_positional, _flags) {
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    console.log("1. doctrina init — this directory is not a Doctrina project yet");
+    return 0;
+  }
+
+  const actions = [];
+
+  // A pending intake is the very first thing to resolve: until it is
+  // converted, product.md and the specs are still empty scaffolding.
+  const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
+  if (isFile(intakePath)) {
+    const status = (listHeader(read(intakePath), "Status") ?? "pending").toLowerCase();
+    if (status !== "converted") {
+      actions.push("doctrina intake — a pending intake awaits conversion into product.md and specs");
+    }
+  }
+
+  // Open changes drive the loop: finish what is started before opening more.
+  const changesDir = path.join(projectRoot, ".doctrina", "changes");
+  if (isDir(changesDir)) {
+    for (const id of readdirSync(changesDir).sort()) {
+      if (id === "archive" || id.startsWith(".")) continue;
+      if (!isDir(path.join(changesDir, id))) continue;
+      const proposalPath = path.join(changesDir, id, "proposal.md");
+      if (!isFile(proposalPath)) {
+        actions.push(`add a proposal.md to .doctrina/changes/${id}/ (open changes need one)`);
+        continue;
+      }
+      const status = listHeader(read(proposalPath), "Status") ?? "proposed";
+      if (status === "applied") {
+        actions.push(`doctrina change archive ${id} — applied but not archived`);
+        continue;
+      }
+      const tasksPath = path.join(changesDir, id, "tasks.md");
+      const unchecked = isFile(tasksPath)
+        ? (read(tasksPath).match(/^-\s+\[ \]/gm) ?? []).length
+        : 0;
+      if (unchecked > 0) {
+        actions.push(`complete ${unchecked} open task${unchecked === 1 ? "" : "s"} in .doctrina/changes/${id}/tasks.md`);
+        continue;
+      }
+      const deltas = walk(path.join(changesDir, id, "specs")).filter((p) => p.endsWith("delta.md"));
+      if (deltas.length > 0) {
+        actions.push(`doctrina analyze ${id}, then doctrina change apply ${id} — tasks done, ${deltas.length} delta${deltas.length === 1 ? "" : "s"} ready`);
+      } else {
+        actions.push(`add spec deltas under .doctrina/changes/${id}/specs/, or apply as metadata-only: doctrina change apply ${id}`);
+      }
+    }
+  }
+
+  // ADRs stuck in proposed need a human decision.
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  for (const f of walk(adrDir)) {
+    if (!f.endsWith(".md")) continue;
+    const m = path.basename(f).match(/^(\d{4})-/);
+    if (!m) continue;
+    const status = listHeader(read(f), "Status");
+    if (status && status.toLowerCase() === "proposed") {
+      actions.push(`review ADR ${m[1]} (${relPath(projectRoot, f)}): doctrina decision accept ${m[1]}, or supersede it`);
+    }
+  }
+
+  // Index drift is silent rot; surface it last.
+  try {
+    const current = idx.load(projectRoot);
+    if (!indexesMatch(deriveIndex(projectRoot, current), current)) {
+      actions.push("doctrina index rebuild — index.json has drifted from the tree");
+    }
+  } catch {
+    actions.push("doctrina index rebuild — index.json is missing or unreadable");
+  }
+
+  if (actions.length === 0) {
+    console.log(c.green("ok") + " no open work.");
+    console.log("");
+    console.log("Start something:");
+    console.log(`  doctrina change new <id> "<title>"   open a change proposal`);
+    console.log(`  doctrina spec new <capability>       spec a new capability`);
+    return 0;
+  }
+
+  console.log(c.bold("Next actions") + c.gray(" (in priority order):"));
+  console.log("");
+  actions.forEach((a, i) => console.log(`${i + 1}. ${a}`));
+  return 0;
+}
+
+export const help = `
+Usage: doctrina next
+
+Inspect the .doctrina/ tree and print the recommended next workflow
+actions in priority order: open changes (missing proposal, unchecked
+tasks, deltas ready to apply, applied-but-unarchived), ADRs still in
+proposed status, and index drift. Read-only; always exits 0.
+
+Intended use: agents and humans run it to resume work without
+re-reading the whole tree.
+`;

package/src/commands/search.js

@@ -0,0 +1,93 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isDir, read, relPath, walk } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+
+// Category-aware full-text search across the artifact tree. Answers
+// "where is X specified / decided / proposed?" without knowing the
+// layout. Plain substring matching, every term must hit (AND).
+
+const MAX_MATCHES_PER_FILE = 5;
+
+export async function run(positional, flags) {
+  const terms = positional.map((t) => t.toLowerCase()).filter(Boolean);
+  if (terms.length === 0) {
+    console.error(c.red("error:") + " search requires at least one term");
+    return 2;
+  }
+  const includeArchive = flagBool(flags, "archive", false);
+  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 categories = [
+    { name: "specs", dir: path.join(".doctrina", "specs") },
+    { name: "decisions", dir: path.join(".doctrina", "decisions") },
+    { name: "changes", dir: path.join(".doctrina", "changes"), skip: (rel) => !includeArchive && rel.includes("/archive/") },
+    { name: "skills", dir: path.join(".doctrina", "skills") },
+    { name: "product", file: path.join(".doctrina", "product.md") },
+    { name: "rules", file: "AGENTS.md" },
+  ];
+
+  let totalMatches = 0;
+  let filesWithMatches = 0;
+
+  for (const cat of categories) {
+    const files = cat.file
+      ? [path.join(projectRoot, cat.file)].filter(exists)
+      : isDir(path.join(projectRoot, cat.dir))
+        ? walk(path.join(projectRoot, cat.dir)).filter((f) => f.endsWith(".md"))
+        : [];
+
+    const findings = [];
+    for (const f of files) {
+      const rel = relPath(projectRoot, f);
+      if (cat.skip && cat.skip(rel)) continue;
+      const lines = read(f).split("\n");
+      const hits = [];
+      for (let i = 0; i < lines.length; i++) {
+        const low = lines[i].toLowerCase();
+        if (terms.every((t) => low.includes(t))) {
+          hits.push({ line: i + 1, text: lines[i].trim() });
+          if (hits.length === MAX_MATCHES_PER_FILE) break;
+        }
+      }
+      if (hits.length > 0) findings.push({ rel, hits });
+    }
+
+    if (findings.length === 0) continue;
+    console.log(c.bold(cat.name));
+    for (const file of findings) {
+      filesWithMatches += 1;
+      for (const h of file.hits) {
+        totalMatches += 1;
+        console.log(`  ${c.cyan(file.rel)}:${h.line}: ${truncate(h.text, 100)}`);
+      }
+    }
+    console.log("");
+  }
+
+  if (totalMatches === 0) {
+    console.log(c.gray(`no matches for "${positional.join(" ")}"${includeArchive ? "" : " (archive excluded; pass --archive to include it)"}`));
+    return 1;
+  }
+  console.log(c.gray(`${totalMatches} match${totalMatches === 1 ? "" : "es"} in ${filesWithMatches} file${filesWithMatches === 1 ? "" : "s"}`));
+  return 0;
+}
+
+function truncate(s, n) {
+  return s.length > n ? s.slice(0, n - 1) + "…" : s;
+}
+
+export const help = `
+Usage: doctrina search <term> [<term> ...] [--archive]
+
+Case-insensitive substring search across the artifact tree, grouped
+by category (specs, decisions, changes, skills, product, AGENTS.md).
+Every term must match on the same line. The change archive is
+excluded unless --archive is passed.
+
+Exits 0 when matches are found, 1 otherwise. Read-only.
+`;

package/src/commands/skill.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, mkdirp, read, walk, write } from "../lib/fs-ops.js";
+import { exists, isDir, mkdirp, read, relPath, walk, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
@@ -8,7 +8,7 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["new", "list"];
+const SUBCOMMANDS = ["new", "list", "sync"];
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -21,6 +21,7 @@ export async function run(positional, flags) {
     return 2;
   }
   if (sub === "new") return skillNew(positional.slice(1), flags);
+  if (sub === "sync") return skillSync();
   return skillList();
 }
 
@@ -38,7 +39,7 @@ function skillNew(args, flags) {
   mkdirp(skillsDir);
   const targetPath = path.join(skillsDir, `${name}.md`);
   if (exists(targetPath) && !force) {
-    console.error(c.red("error:") + ` ${path.relative(projectRoot, targetPath)} already exists (pass --force to overwrite)`);
+    console.error(c.red("error:") + ` ${relPath(projectRoot, targetPath)} already exists (pass --force to overwrite)`);
     return 1;
   }
 
@@ -46,7 +47,7 @@ function skillNew(args, flags) {
   const tplPath = path.join(templatesDir, "skill.md.template");
   const body = substitute(read(tplPath), { SKILL_NAME: name });
   write(targetPath, body, { force });
-  console.log(c.green("created") + ` ${path.relative(projectRoot, targetPath)}`);
+  console.log(c.green("created") + ` ${relPath(projectRoot, targetPath)}`);
 
   const date = today();
   const index = idx.load(projectRoot);
@@ -60,7 +61,56 @@ function skillNew(args, flags) {
   idx.save(projectRoot, index);
   console.log(c.green("indexed") + ` skill "${name}"`);
   console.log("");
-  console.log(c.gray("hint: ") + "fill the description and when frontmatter fields, then update index.json description by hand");
+  console.log(c.gray("hint: ") + "fill the description and when frontmatter fields, then run `doctrina skill sync` to update index.json");
+  return 0;
+}
+
+function skillSync() {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  if (!isDir(skillsDir)) {
+    console.log(c.gray("no skills directory; nothing to sync"));
+    return 0;
+  }
+
+  const files = walk(skillsDir).filter((f) => f.endsWith(".md"));
+  const index = idx.load(projectRoot);
+  const date = today();
+  let synced = 0;
+
+  for (const f of files) {
+    const id = path.basename(f, ".md");
+    const desc = parseFrontmatter(read(f), "description");
+    if (!desc) {
+      console.log(c.yellow("skip   ") + ` ${id} (no description frontmatter)`);
+      continue;
+    }
+    const entry = (index.artifacts.skills ?? []).find((s) => s.id === id);
+    if (!entry) {
+      idx.addSkill(index, {
+        id,
+        path: `.doctrina/skills/${id}.md`,
+        description: desc,
+        last_updated: date,
+      });
+      console.log(c.green("indexed") + ` ${id}`);
+      synced += 1;
+    } else if (entry.description !== desc) {
+      entry.description = desc;
+      entry.last_updated = date;
+      console.log(c.green("synced ") + ` ${id}`);
+      synced += 1;
+    }
+  }
+
+  if (synced > 0) {
+    idx.touch(index, date);
+    idx.save(projectRoot, index);
+  }
+  console.log("");
+  console.log(c.green("ok") + ` ${synced} skill${synced === 1 ? "" : "s"} synced, ${files.length - synced} already up to date`);
   return 0;
 }
 
@@ -120,6 +170,9 @@ Subcommands:
                 it. Name must match [a-z][a-z0-9-]*.
   list          Print one line per skill with name + description.
                 Read-only.
+  sync          Copy each skill's frontmatter description into
+                .doctrina/index.json so the index never drifts
+                from the frontmatter (single source of truth).
 
 Skills are written by humans, not generated. See docs/en/skills.md
 for the design rationale and the distinction from specs / AGENTS.md /

package/src/commands/spec.js

@@ -1,14 +1,16 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, read, write } from "../lib/fs-ops.js";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, lineCount, read, relPath, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
+import { specHeader } from "../lib/scan.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["new"];
+const SUBCOMMANDS = ["new", "list"];
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -20,6 +22,7 @@ export async function run(positional, flags) {
       : `available: ${SUBCOMMANDS.join(", ")}`));
     return 2;
   }
+  if (sub === "list") return specList();
 
   const capability = positional[1];
   if (!capability || !/^[a-z][a-z0-9-]*$/.test(capability)) {
@@ -35,7 +38,7 @@ export async function run(positional, flags) {
   const targetDir = path.join(projectRoot, ".doctrina", "specs", capability);
   const targetPath = path.join(targetDir, "spec.md");
   if (exists(targetPath) && !force) {
-    console.error(c.red("error:") + ` ${path.relative(projectRoot, targetPath)} already exists (pass --force to overwrite)`);
+    console.error(c.red("error:") + ` ${relPath(projectRoot, targetPath)} already exists (pass --force to overwrite)`);
     return 1;
   }
 
@@ -45,7 +48,7 @@ export async function run(positional, flags) {
   const date = today();
   const body = substitute(read(tplPath), { CAPABILITY: capability, DATE: date });
   write(targetPath, body, { force });
-  console.log(c.green("created") + ` ${path.relative(projectRoot, targetPath)}${bug ? " (bug-spec shape)" : ""}`);
+  console.log(c.green("created") + ` ${relPath(projectRoot, targetPath)}${bug ? " (bug-spec shape)" : ""}`);
 
   const index = idx.load(projectRoot);
   idx.addSpec(index, {
@@ -61,6 +64,40 @@ export async function run(positional, flags) {
   return 0;
 }
 
+function specList() {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const rows = [];
+  if (isDir(specsDir)) {
+    for (const cap of readdirSync(specsDir).sort()) {
+      const p = path.join(specsDir, cap, "spec.md");
+      if (!isFile(p)) continue;
+      const text = read(p);
+      rows.push({
+        id: cap,
+        version: specHeader(text, "Version") ?? "—",
+        status: specHeader(text, "Status") ?? "active",
+        lines: lineCount(p),
+        updated: specHeader(text, "Last updated") ?? "—",
+      });
+    }
+  }
+  if (rows.length === 0) {
+    console.log(c.gray("no specs found in .doctrina/specs/"));
+    return 0;
+  }
+  console.log(c.bold("Specs:"));
+  console.log("");
+  for (const r of rows) {
+    console.log(`  ${c.cyan(r.id.padEnd(20))} ${r.version.padEnd(8)} ${r.status.padEnd(10)} ${String(r.lines).padStart(4)} lines  ${r.updated}`);
+  }
+  console.log("");
+  console.log(c.gray(`${rows.length} spec${rows.length === 1 ? "" : "s"}`));
+  return 0;
+}
+
 function ensureDoctrinaProject(projectRoot) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
@@ -68,10 +105,15 @@ function ensureDoctrinaProject(projectRoot) {
 }
 
 export const help = `
-Usage: doctrina spec new <capability> [--bug] [--force]
+Usage: doctrina spec <subcommand>
 
-Create a new capability spec under .doctrina/specs/<capability>/spec.md
-and add an entry to .doctrina/index.json.
+Subcommands:
+  new <capability> [--bug] [--force]   Create a capability spec under
+                                       .doctrina/specs/<capability>/spec.md
+                                       and index it.
+  list                                 One line per spec: id, version,
+                                       status, line count, last updated.
+                                       Read-only.
 
 Options:
   --bug      Scaffold the bug-shape template (current / expected /