doctrina-cli 0.1.1 → 0.2.0

package/src/commands/templates.js

@@ -1,11 +1,12 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, isFile, lineCount, read, walk } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, lineCount, read, relPath, walk, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir } from "../lib/templates.js";
+import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["list", "check"];
+const SUBCOMMANDS = ["list", "check", "update"];
 
 // Recommended sections per file kind. Adopters whose files lack these
 // headings get a warning from `templates check`; they are recommendations,
@@ -26,7 +27,7 @@ const PRODUCT_SECTIONS = [
 ];
 const INDEX_FIELDS = ["$schema_version", "project", "artifacts"];
 
-export async function run(positional, _flags) {
+export async function run(positional, flags) {
   const sub = positional[0];
   if (!SUBCOMMANDS.includes(sub)) {
     console.error(c.red("error:") + ` unknown templates subcommand "${sub ?? ""}"`);
@@ -37,9 +38,102 @@ export async function run(positional, _flags) {
     return 2;
   }
   if (sub === "list") return listTemplates();
+  if (sub === "update") return updateTemplates(flags);
   return checkTemplates();
 }
 
+// Additive-only updater: appends missing recommended sections and adds
+// missing index.json fields. Never rewrites or removes user content.
+// Preview is the default; --write applies. This is the opt-in semantic
+// the deferred register required before shipping any template updater.
+function updateTemplates(flags) {
+  const writeMode = flagBool(flags, "write", false);
+  const projectRoot = process.cwd();
+  if (!isDir(path.join(projectRoot, ".doctrina"))) {
+    console.error(c.red("error:") + " not a Doctrina project (no .doctrina/ in cwd)");
+    return 1;
+  }
+
+  const plan = [];
+
+  // Markdown files: append stub sections for missing recommended headings.
+  for (const [rel, sections] of [
+    ["AGENTS.md", AGENTS_SECTIONS],
+    [path.join(".doctrina", "product.md"), PRODUCT_SECTIONS],
+  ]) {
+    const filePath = path.join(projectRoot, rel);
+    if (!isFile(filePath)) continue;
+    const text = read(filePath);
+    const missing = sections.filter((h) => !hasHeading(text, h));
+    if (missing.length > 0) {
+      plan.push({
+        describe: missing.map((h) => `${rel}: append stub section "${h}"`),
+        apply() {
+          let updated = read(filePath);
+          if (!updated.endsWith("\n")) updated += "\n";
+          for (const h of missing) {
+            updated += `\n${h}\n\n<!-- added by doctrina templates update — fill in -->\n`;
+          }
+          write(filePath, updated, { force: true });
+        },
+      });
+    }
+  }
+
+  // index.json: add missing schema fields and artifact categories.
+  const indexPath = path.join(projectRoot, ".doctrina", "index.json");
+  if (isFile(indexPath)) {
+    try {
+      const idx = JSON.parse(read(indexPath));
+      const describe = [];
+      if (idx.$schema_version === undefined) describe.push('index.json: add "$schema_version": "0.1.0"');
+      if (idx.project === undefined) describe.push(`index.json: add "project": "${path.basename(projectRoot)}"`);
+      if (idx.artifacts === undefined) describe.push('index.json: add empty "artifacts" object');
+      const categories = ["specs", "decisions", "changes", "changes_archive", "skills"];
+      for (const cat of categories) {
+        if (idx.artifacts && idx.artifacts[cat] === undefined) {
+          describe.push(`index.json: add empty artifact category "${cat}"`);
+        }
+      }
+      if (describe.length > 0) {
+        plan.push({
+          describe,
+          apply() {
+            const current = JSON.parse(read(indexPath));
+            current.$schema_version ??= "0.1.0";
+            current.project ??= path.basename(projectRoot);
+            current.artifacts ??= {};
+            for (const cat of categories) current.artifacts[cat] ??= [];
+            write(indexPath, JSON.stringify(current, null, 2) + "\n", { force: true });
+          },
+        });
+      }
+    } catch {
+      console.error(c.red("error:") + " .doctrina/index.json failed to parse; fix it before updating");
+      return 1;
+    }
+  }
+
+  const steps = plan.flatMap((p) => p.describe);
+  if (steps.length === 0) {
+    console.log(c.green("ok") + " project already follows the current template shape");
+    return 0;
+  }
+
+  for (const s of steps) {
+    console.log((writeMode ? c.green("update ") : c.yellow("would  ")) + s);
+  }
+  console.log("");
+  if (!writeMode) {
+    console.log(`${steps.length} pending update${steps.length === 1 ? "" : "s"} (preview only — nothing written)`);
+    console.log(c.gray("hint: ") + "re-run with --write to apply");
+    return 1;
+  }
+  for (const p of plan) p.apply();
+  console.log(c.green("ok") + ` ${steps.length} update${steps.length === 1 ? "" : "s"} applied (additive only — review the stubs and fill them in)`);
+  return 0;
+}
+
 function listTemplates() {
   const dir = locateTemplatesDir();
   const files = walk(dir).filter((f) => !f.endsWith(".gitkeep"));
@@ -52,7 +146,7 @@ function listTemplates() {
   let maxLen = 0;
   const rows = [];
   for (const f of files) {
-    const rel = path.relative(dir, f).split(path.sep).join("/");
+    const rel = relPath(dir, f);
     const lines = lineCount(f);
     rows.push({ rel, lines });
     if (rel.length > maxLen) maxLen = rel.length;
@@ -155,6 +249,11 @@ Subcommands:
             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.
 
 Distinct from \`doctrina validate\`: validate answers "is this a
 well-formed Doctrina tree?"; templates check answers "does this

package/src/commands/validate.js

@@ -1,9 +1,11 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, isFile, lineCount, read, walk } from "../lib/fs-ops.js";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, lineCount, read, relPath, walk } from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
 import { c } from "../lib/colors.js";
 import { parseFrontmatter } from "./skill.js";
+import { checkEars, isEarsSpec } from "../lib/ears.js";
 
 export async function run(_positional, _flags) {
   const projectRoot = process.cwd();
@@ -20,6 +22,15 @@ export async function run(_positional, _flags) {
     else if (lines > 150) warnings.push(`AGENTS.md is ${lines} lines (>150 soft limit)`);
   }
 
+  // 1b. Nested AGENTS.md files ("nearest wins" hierarchy) obey the same
+  //     size caps as the root file.
+  for (const nested of findNestedAgentsMd(projectRoot)) {
+    const rel = relPath(projectRoot, nested);
+    const lines = lineCount(nested);
+    if (lines > 200) errors.push(`${rel} is ${lines} lines (>200, hard limit)`);
+    else if (lines > 150) warnings.push(`${rel} is ${lines} lines (>150 soft limit)`);
+  }
+
   // 2. product.md
   const productMd = path.join(projectRoot, ".doctrina", "product.md");
   if (!isFile(productMd)) errors.push(".doctrina/product.md missing");
@@ -50,6 +61,17 @@ export async function run(_positional, _flags) {
         const full = path.join(projectRoot, rel);
         if (!exists(full)) errors.push(`index.json references missing artifact: ${rel}`);
       }
+
+      // 4b. Spec version drift — the Version: header inside each spec
+      //     must match the version recorded in index.json.
+      for (const s of index.artifacts.specs ?? []) {
+        const full = path.join(projectRoot, s.path);
+        if (!isFile(full)) continue;
+        const m = read(full).match(/^\*\*Version:\*\*\s+(\S+)/m);
+        if (m && s.version && m[1] !== s.version) {
+          warnings.push(`${s.path} declares version ${m[1]} but index.json records ${s.version} (sync the index)`);
+        }
+      }
     }
   }
 
@@ -60,7 +82,7 @@ export async function run(_positional, _flags) {
       if (!f.endsWith(".md")) continue;
       const text = read(f);
       if (!/^-\s+\*\*Status:\*\*\s+\S+/m.test(text)) {
-        errors.push(`${path.relative(projectRoot, f)} missing or malformed Status: header`);
+        errors.push(`${relPath(projectRoot, f)} missing or malformed Status: header`);
       }
     }
   }
@@ -71,7 +93,7 @@ export async function run(_positional, _flags) {
     for (const f of walk(adaptersDir)) {
       if (!f.endsWith(".template")) continue;
       const lines = lineCount(f);
-      if (lines > 30) errors.push(`${path.relative(projectRoot, f)} is ${lines} lines (>30, adapter cap)`);
+      if (lines > 30) errors.push(`${relPath(projectRoot, f)} is ${lines} lines (>30, adapter cap)`);
     }
   }
 
@@ -96,7 +118,15 @@ export async function run(_positional, _flags) {
       const specPath = path.join(specsDir, cap, "spec.md");
       if (isFile(specPath)) {
         const lines = lineCount(specPath);
-        if (lines > 400) warnings.push(`${path.relative(projectRoot, specPath)} is ${lines} lines (>400 soft cap)`);
+        if (lines > 400) warnings.push(`${relPath(projectRoot, specPath)} is ${lines} lines (>400 soft cap)`);
+
+        // 8b. EARS grammar shape — section-appropriate When/While/Where/shall.
+        const text = read(specPath);
+        if (isEarsSpec(text)) {
+          for (const f of checkEars(text)) {
+            warnings.push(`${relPath(projectRoot, specPath)}:${f.line} ${f.message}`);
+          }
+        }
       }
     }
   }
@@ -106,7 +136,7 @@ export async function run(_positional, _flags) {
     for (const f of walk(adrDir)) {
       if (!f.endsWith(".md")) continue;
       const lines = lineCount(f);
-      if (lines > 300) warnings.push(`${path.relative(projectRoot, f)} is ${lines} lines (>300 soft cap)`);
+      if (lines > 300) warnings.push(`${relPath(projectRoot, f)} is ${lines} lines (>300 soft cap)`);
     }
   }
 
@@ -126,7 +156,7 @@ export async function run(_positional, _flags) {
           path.resolve(projectRoot, ref),
         ];
         if (!candidates.some(exists)) {
-          warnings.push(`${path.relative(projectRoot, f)} references missing path \`${ref}\``);
+          warnings.push(`${relPath(projectRoot, f)} references missing path \`${ref}\``);
         }
       }
     }
@@ -140,7 +170,7 @@ export async function run(_positional, _flags) {
       for (const cap of readdirSync(specsDir)) {
         const specPath = path.join(specsDir, cap, "spec.md");
         if (isFile(specPath) && !indexedSpecIds.has(cap)) {
-          warnings.push(`orphan spec ${path.relative(projectRoot, specPath)} (capability "${cap}" not in index.json)`);
+          warnings.push(`orphan spec ${relPath(projectRoot, specPath)} (capability "${cap}" not in index.json)`);
         }
       }
     }
@@ -150,7 +180,7 @@ export async function run(_positional, _flags) {
         if (!f.endsWith(".md")) continue;
         const m = path.basename(f).match(/^(\d{4})-/);
         if (m && !indexedAdrIds.has(m[1])) {
-          warnings.push(`orphan ADR ${path.relative(projectRoot, f)} (id "${m[1]}" not in index.json)`);
+          warnings.push(`orphan ADR ${relPath(projectRoot, f)} (id "${m[1]}" not in index.json)`);
         }
       }
     }
@@ -162,7 +192,7 @@ export async function run(_positional, _flags) {
     for (const f of walk(skillsDir)) {
       if (!f.endsWith(".md")) continue;
       const text = read(f);
-      const rel = path.relative(projectRoot, f);
+      const rel = relPath(projectRoot, f);
       const baseName = path.basename(f, ".md");
       const nameField = parseFrontmatter(text, "name");
       const descField = parseFrontmatter(text, "description");
@@ -176,6 +206,15 @@ export async function run(_positional, _flags) {
       const lines = lineCount(f);
       if (lines > 200) warnings.push(`${rel} is ${lines} lines (>200 soft cap)`);
       else if (lines > 150) warnings.push(`${rel} is ${lines} lines (>150 soft cap)`);
+
+      // 15. Skill description drift — index.json must mirror the
+      //     frontmatter description (run `doctrina skill sync`).
+      if (descField && index?.artifacts?.skills) {
+        const entry = index.artifacts.skills.find((s) => s.id === baseName);
+        if (entry && entry.description !== descField) {
+          warnings.push(`${rel} description differs from index.json (run \`doctrina skill sync\`)`);
+        }
+      }
     }
   }
 
@@ -193,6 +232,34 @@ export async function run(_positional, _flags) {
   return errors.length === 0 ? 0 : 1;
 }
 
+// Find AGENTS.md files below the root (the "nearest AGENTS.md wins"
+// hierarchy). Bounded walk: dependency, build, and VCS directories are
+// skipped so validate stays fast on large repositories.
+const NESTED_SKIP_DIRS = new Set([
+  ".git", "node_modules", ".doctrina", "vendor", "dist", "build", "out",
+  "target", ".venv", "venv", "__pycache__", ".next", "coverage",
+]);
+
+function findNestedAgentsMd(projectRoot) {
+  const found = [];
+  const stack = readdirSync(projectRoot)
+    .filter((e) => !NESTED_SKIP_DIRS.has(e) && !e.startsWith("."))
+    .map((e) => path.join(projectRoot, e))
+    .filter(isDir);
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const entry of readdirSync(dir)) {
+      const full = path.join(dir, entry);
+      if (isDir(full)) {
+        if (!NESTED_SKIP_DIRS.has(entry) && !entry.startsWith(".")) stack.push(full);
+      } else if (entry === "AGENTS.md") {
+        found.push(full);
+      }
+    }
+  }
+  return found.sort();
+}
+
 // Extract candidate file path references from Markdown text. Only
 // Markdown link targets `[text](path)` are checked — backtick spans
 // are descriptive prose and produce too many false positives.

package/src/commands/work.js

@@ -0,0 +1,215 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { flagString } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { changeNew } from "./change.js";
+
+// `work` is the second half of the no-ceremony path (ADR 0005): a brief
+// prompt ("add login") becomes a fully scaffolded change plus a playbook
+// the host agent executes — context, spec deltas, tasks, implementation,
+// then the analyze → apply → archive → validate close. The CLI's own
+// language processing stops at slugging and term counting; everything
+// semantic is the agent's job.
+
+export async function run(positional, flags) {
+  const prompt = positional.join(" ").trim();
+  if (!prompt) {
+    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.");
+  }
+
+  const pinned = flagString(flags, "capability");
+  if (pinned && !/^[a-z][a-z0-9-]*$/.test(pinned)) {
+    console.error(c.red("error:") + ` invalid capability "${pinned}" (lowercase letters, digits, hyphens)`);
+    return 2;
+  }
+
+  const id = flagString(flags, "id") ?? `${nextChangeNumber(projectRoot)}-${slugify(prompt)}`;
+  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);
+  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.
+  const proposalPath = path.join(projectRoot, ".doctrina", "changes", id, "proposal.md");
+  if (isFile(proposalPath)) {
+    const txt = read(proposalPath);
+    // 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`);
+    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);
+  const capability = pinned ?? matches[0]?.id ?? null;
+
+  console.log("");
+  printPlaybook(projectRoot, { id, prompt, pinned, matches, capability });
+  return 0;
+}
+
+// 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) {
+  const changesDir = path.join(projectRoot, ".doctrina", "changes");
+  let max = 0;
+  const harvest = (name) => {
+    const m = name.match(/^(\d{1,4})-/) ?? name.match(/^(\d{1,4})$/);
+    if (m) max = Math.max(max, Number(m[1]));
+  };
+  if (isDir(changesDir)) {
+    for (const entry of readdirSync(changesDir)) {
+      if (entry === "archive" || entry.startsWith(".")) continue;
+      if (isDir(path.join(changesDir, entry))) harvest(entry);
+    }
+  }
+  const archiveDir = path.join(changesDir, "archive");
+  if (isDir(archiveDir)) {
+    for (const entry of readdirSync(archiveDir)) {
+      if (!isDir(path.join(archiveDir, entry))) continue;
+      harvest(entry.replace(/^\d{4}-\d{2}-\d{2}-/, ""));
+    }
+  }
+  return String(max + 1).padStart(4, "0");
+}
+
+// ASCII-folded kebab-case of the prompt ("Faça o login" -> "faca-o-login").
+export function slugify(text) {
+  let slug = text
+    .normalize("NFD")
+    .replace(/\p{M}+/gu, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (slug.length > 48) slug = slug.slice(0, 48).replace(/-+$/g, "");
+  return slug.length > 0 ? slug : "task";
+}
+
+// Deterministic term overlap: fold prompt and spec text to ASCII lowercase,
+// drop short/stop words, score name hits heavily and body hits lightly.
+// This is a hint for the agent, never a decision (ADR 0005).
+const STOPWORDS = new Set([
+  // en
+  "the", "and", "for", "with", "from", "that", "this", "into", "when",
+  "then", "shall", "should", "must", "can", "will", "make", "add", "new",
+  "use", "create", "implement", "feature", "system", "user", "users",
+  // pt (ASCII-folded)
+  "uma", "umas", "uns", "dos", "das", "nos", "nas", "por", "para", "com",
+  "que", "sem", "aos", "faca", "fazer", "criar", "crie", "novo", "nova",
+  "adicionar", "adicione", "implementar", "implemente", "funcionalidade",
+  "sistema", "usuario", "usuarios",
+]);
+
+function fold(text) {
+  return text.normalize("NFD").replace(/\p{M}+/gu, "").toLowerCase();
+}
+
+function promptTerms(prompt) {
+  return [...new Set(
+    fold(prompt)
+      .split(/[^a-z0-9]+/)
+      .filter((t) => t.length >= 3 && !STOPWORDS.has(t)),
+  )];
+}
+
+export function rankCapabilities(projectRoot, prompt) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const terms = promptTerms(prompt);
+  if (terms.length === 0 || !isDir(specsDir)) return [];
+
+  const ranked = [];
+  for (const cap of readdirSync(specsDir).sort()) {
+    const specPath = path.join(specsDir, cap, "spec.md");
+    if (!isFile(specPath)) continue;
+    const body = fold(read(specPath));
+    const nameTokens = cap.split("-");
+    let score = 0;
+    for (const term of terms) {
+      if (nameTokens.includes(term)) score += 5;
+      const hits = body.split(term).length - 1;
+      score += Math.min(hits, 5);
+    }
+    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);
+}
+
+function printPlaybook(projectRoot, { id, prompt, pinned, matches, capability }) {
+  const capToken = capability ?? "<capability>";
+  console.log(c.bold(`Work playbook — change ${id}`) + c.gray(" — agent-executed (ADR 0005)."));
+  console.log("");
+  console.log(`Prompt: "${prompt}"`);
+
+  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):");
+    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("");
+  console.log("Execute in order, in a single linear pass:");
+  console.log("");
+  console.log("1. Read the context pack and confirm (or correct) the capability:");
+  console.log(`       ${c.cyan(`doctrina context ${capToken} --concat`)}`);
+  console.log("");
+  console.log("2. If the capability has no spec yet:");
+  console.log(`       ${c.cyan("doctrina spec new <capability>")}`);
+  console.log("");
+  console.log("3. Write one delta per affected capability at");
+  console.log(`   .doctrina/changes/${id}/specs/<capability>/delta.md:`);
+  console.log(c.gray("       # Spec Delta — capability: <capability>"));
+  console.log(c.gray("       **Operation:** ADDED | MODIFIED | REMOVED"));
+  console.log(c.gray("       **Target spec on apply:** `.doctrina/specs/<capability>/spec.md`"));
+  console.log(c.gray("       ---"));
+  console.log(c.gray("       <EARS requirements: full spec body for ADDED, fragment for MODIFIED>"));
+  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).");
+  console.log("");
+  console.log("5. Implement task by task, checking each box as it lands. If the");
+  console.log("   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(`8. ${c.cyan(`doctrina change archive ${id}`)}`);
+  console.log(`9. ${c.cyan("doctrina validate")}, then ${c.cyan("doctrina next")} for the follow-up.`);
+}
+
+export const help = `
+Usage: doctrina work "<prompt>" [--capability <cap>] [--id <id>] [--force]
+
+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:
+context → spec delta → tasks → implement → analyze → apply → archive →
+validate. No natural-language interpretation happens in the CLI.
+
+Options:
+  --capability <cap>   Pin the capability instead of ranking matches
+  --id <id>            Override the derived change id
+  --force              Overwrite an existing change folder
+`;

package/src/index.js

@@ -17,28 +17,51 @@ import * as analyze from "./commands/analyze.js";
 import * as clarify from "./commands/clarify.js";
 import * as templates from "./commands/templates.js";
 import * as skill from "./commands/skill.js";
+import * as indexCmd from "./commands/index-rebuild.js";
+import * as next from "./commands/next.js";
+import * as metrics from "./commands/metrics.js";
+import * as context from "./commands/context.js";
+import * as search from "./commands/search.js";
+import * as intake from "./commands/intake.js";
+import * as work from "./commands/work.js";
 
-const COMMANDS = { init, spec, change, decision, validate, hooks, analyze, clarify, templates, skill };
+const COMMANDS = {
+  init, spec, change, decision, validate, hooks, analyze, clarify,
+  templates, skill, index: indexCmd, next, metrics, context, search,
+  intake, work,
+};
 
 const TOP_HELP = `
 Usage: doctrina <command> [options]
 
 Commands:
   init                 Scaffold AGENTS.md and .doctrina/ in the current directory
+  intake               Store the full project description; print the bootstrap playbook
+  work                 Brief prompt -> scaffolded change + guided work playbook
   spec new             Create a new capability spec (--bug for bug-shape)
+  spec list            List specs with version, status, and size
   change new           Open a change proposal
   change apply         Apply spec deltas (ADDED/REMOVED auto, MODIFIED manual)
   change archive       Archive an applied change
+  change diff          Preview spec deltas (line diff for MODIFIED)
   decision new         Create the next sequentially numbered ADR
+  decision accept      Flip a proposed ADR to accepted
   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
   skill list           List skills with their descriptions
+  skill sync           Mirror skill frontmatter descriptions into index.json
   analyze              Inspect a change folder before applying
-  clarify              Smell-test a Markdown file for ambiguity
+  clarify              Smell-test a Markdown file for ambiguity (--all for the tree)
+  context              Print the context pack for a task in read order
+  search               Search the artifact tree, grouped by category
   validate             Run schema and structural checks
   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
+  metrics              Local git-derived adoption metrics (no network)
 
 Global flags:
   --help, -h           Show this message (or per-command help if after a command)
@@ -47,7 +70,7 @@ Global flags:
 
 async function main(argv) {
   const { positional, flags } = parseArgs(argv, {
-    boolean: ["help", "h", "version", "v", "force", "non-interactive"],
+    boolean: ["help", "h", "version", "v", "force", "non-interactive", "check", "save", "bug", "write", "all", "concat", "archive"],
   });
 
   if (flags.get("version") || flags.get("v")) {