doctrina-cli 0.1.1 → 0.2.0

package/README.md

@@ -21,17 +21,30 @@ Requires Node.js 20.12 or later.
 ```
 doctrina init                              scaffold AGENTS.md + .doctrina/ in cwd
 doctrina spec new <capability>             create a capability spec
+doctrina spec list                         list specs with version, status, size
 doctrina change new <id> "<title>"         open a change proposal
 doctrina change apply <id>                 apply spec deltas (ADDED/REMOVED auto)
 doctrina change archive <id>               archive an applied change
+doctrina change diff <id>                  preview spec deltas (line diff for MODIFIED)
 doctrina decision new "<title>"            create the next sequential ADR
+doctrina decision accept <num>             flip a proposed ADR to accepted
 doctrina decision supersede <num> "<t>"    supersede an existing ADR
+doctrina decision list                     list ADRs with status, date, title
+doctrina skill new <name>                  scaffold an on-demand procedural-memory skill
+doctrina skill list                        list skills with descriptions (read-only)
+doctrina skill sync                        mirror skill frontmatter descriptions into index.json
 doctrina analyze <change-id>               inspect a change folder before applying
-doctrina clarify <path>                    smell-test a Markdown file for ambiguity
+doctrina clarify <path>                    smell-test a Markdown file for ambiguity (--all: tree)
+doctrina context [<capability>]            print the context pack in read order (--concat)
+doctrina search <term> [...]               search artifacts, grouped by category
 doctrina validate                          schema + artifact-existence checks
 doctrina templates list                    enumerate shipped templates
 doctrina templates check                   compare project against recommended template shape
+doctrina templates update                  additive fixer for check findings (preview; --write applies)
 doctrina hooks install                     install pre-commit hook
+doctrina index rebuild                     regenerate index.json from the files (--check for CI)
+doctrina next                              print the recommended next workflow actions
+doctrina metrics                           local git-derived adoption metrics (no network)
 doctrina --help | -h                       print the command surface
 doctrina --version | -v                    print the package version
 ```
@@ -44,7 +57,7 @@ Per-command help is available with `doctrina <command> --help`.
 |------|---------|
 | `--project-name <name>` | Override the project name (defaults to cwd basename) |
 | `--project-description <text>` | One-sentence description (prompted if omitted) |
-| `--agent <name>` | Install adapter for `claude`, `codex`, `cursor`, or `all` |
+| `--agent <name>` | Install the adapter for one of the twelve supported agents (`claude`, `codex`, `cursor`, `copilot`, `gemini`, `aider`, `windsurf`, `continue`, `amp`, `devin`, `factory`, `jules`) or `all` |
 | `--date <YYYY-MM-DD>` | Override the system date in artifacts |
 | `--force` | Overwrite existing files |
 | `--non-interactive` | Fail instead of prompting for missing required values |
@@ -53,10 +66,12 @@ Per-command help is available with `doctrina <command> --help`.
 
 - `--agent claude` writes a `CLAUDE.md` at the project root that
   `@`-imports `AGENTS.md`. Claude Code picks it up automatically.
-- `--agent codex` installs nothing. OpenAI Codex CLI reads `AGENTS.md`
-  natively.
 - `--agent cursor` writes `.cursor/rules/00-doctrina.mdc` with
-  `alwaysApply: true` pointing at `AGENTS.md`.
+  `alwaysApply: true` pointing at `AGENTS.md`. `copilot`, `gemini`,
+  `aider`, `windsurf`, and `continue` follow the same thin-pointer
+  pattern at each agent's native path.
+- `--agent codex` (and `amp`, `devin`, `factory`, `jules`) installs
+  nothing: these agents read `AGENTS.md` natively.
 - `--agent all` installs every adapter.
 
 All adapter files are kept under 30 lines to avoid per-turn token tax
@@ -87,6 +102,13 @@ For each spec delta found under `.doctrina/changes/<id>/specs/`:
 9. ADRs are ≤ 300 lines (warns above).
 10. Spec/ADR files on disk are present in `index.json` (orphan warn).
 11. Markdown links inside specs/ADRs resolve to real files (stale ref warn).
+12. Skills carry the required frontmatter triple (`name`, `description`, `when`).
+13. Skills are ≤ 200 lines (warns at > 150).
+14. Each skill's `name:` matches its filename slug.
+15. Each spec's `Version:` header matches the version in `index.json` (drift warn).
+16. Each skill's frontmatter description matches `index.json` (drift warn; `skill sync` fixes).
+17. EARS grammar shape per section in specs declaring `## Requirements (EARS)` (warn).
+18. Nested `AGENTS.md` files obey the root size caps (warn > 150, error > 200).
 
 Exit code: 0 if no errors (warnings allowed), 1 otherwise.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/analyze.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, isFile, read, walk } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
 import { c } from "../lib/colors.js";
 
 export async function run(positional, _flags) {
@@ -13,11 +13,11 @@ export async function run(positional, _flags) {
   const projectRoot = process.cwd();
   const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
   if (!isDir(changeDir)) {
-    console.error(c.red("error:") + ` change "${id}" not found at ${path.relative(projectRoot, changeDir)}`);
+    console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);
     return 1;
   }
 
-  console.log(`analyzing ${path.relative(projectRoot, changeDir)}/`);
+  console.log(`analyzing ${relPath(projectRoot, changeDir)}/`);
   console.log("");
 
   const results = [];
@@ -56,7 +56,7 @@ export async function run(positional, _flags) {
   } else {
     results.push(pass(`${deltaFiles.length} spec delta${deltaFiles.length === 1 ? "" : "s"}:`));
     for (const deltaPath of deltaFiles) {
-      const rel = path.relative(projectRoot, deltaPath);
+      const rel = relPath(projectRoot, deltaPath);
       const text = read(deltaPath);
       const opMatch = text.match(/^\*\*Operation:\*\*\s*([A-Z]+)/m);
       const op = opMatch ? opMatch[1] : null;
@@ -72,7 +72,7 @@ export async function run(positional, _flags) {
         continue;
       }
       const targetSpec = path.join(projectRoot, ".doctrina", "specs", cap, "spec.md");
-      const targetRel = path.relative(projectRoot, targetSpec);
+      const targetRel = relPath(projectRoot, targetSpec);
       if (op === "ADDED") {
         if (exists(targetSpec)) {
           results.push(fail(`  ${cap} (ADDED) but target ${targetRel} already exists`, "  "));

package/src/commands/change.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, mkdirp, move, read, remove, walk, write } from "../lib/fs-ops.js";
+import { exists, isDir, lineCount, mkdirp, move, read, relPath, remove, walk, write } from "../lib/fs-ops.js";
+import { diffLines, formatUnified } from "../lib/diff.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
@@ -8,7 +9,7 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["new", "apply", "archive"];
+const SUBCOMMANDS = ["new", "apply", "archive", "diff"];
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -19,6 +20,8 @@ export async function run(positional, flags) {
       return changeApply(positional.slice(1), flags);
     case "archive":
       return changeArchive(positional.slice(1), flags);
+    case "diff":
+      return changeDiff(positional.slice(1), flags);
     default:
       console.error(c.red("error:") + ` unknown change subcommand "${sub ?? ""}"`);
       const guess = suggest(sub, SUBCOMMANDS);
@@ -47,7 +50,7 @@ function changeNew(args, flags) {
 
   const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
   if (exists(changeDir) && !force) {
-    console.error(c.red("error:") + ` change "${id}" already exists at ${path.relative(projectRoot, changeDir)}`);
+    console.error(c.red("error:") + ` change "${id}" already exists at ${relPath(projectRoot, changeDir)}`);
     return 1;
   }
 
@@ -59,7 +62,7 @@ function changeNew(args, flags) {
   for (const entry of tree) {
     if (entry.relativePath === "spec-delta.md.template") continue;
     const written = materialiseEntry(entry, changeDir, tokens, { force });
-    console.log(c.green("created") + ` ${path.relative(projectRoot, written)}`);
+    console.log(c.green("created") + ` ${relPath(projectRoot, written)}`);
   }
   mkdirp(path.join(changeDir, "specs"));
 
@@ -85,7 +88,7 @@ function changeApply(args, _flags) {
 
   const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
   if (!isDir(changeDir)) {
-    console.error(c.red("error:") + ` change "${id}" not found at ${path.relative(projectRoot, changeDir)}`);
+    console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);
     return 1;
   }
 
@@ -100,7 +103,7 @@ function changeApply(args, _flags) {
   }
 
   for (const deltaPath of deltaFiles) {
-    const rel = path.relative(changeDir, deltaPath);
+    const rel = relPath(changeDir, deltaPath);
     const text = read(deltaPath);
     const op = parseOperation(text);
     const capability = parseCapabilityFromDelta(text, deltaPath);
@@ -113,24 +116,24 @@ function changeApply(args, _flags) {
 
     if (op === "ADDED") {
       if (exists(targetPath)) {
-        console.error(c.red("error:") + ` ADDED delta targets existing spec ${path.relative(projectRoot, targetPath)} — refusing to overwrite`);
+        console.error(c.red("error:") + ` ADDED delta targets existing spec ${relPath(projectRoot, targetPath)} — refusing to overwrite`);
         errors += 1;
         continue;
       }
       const body = extractDeltaBody(text);
       write(targetPath, body, { force: false });
       writes += 1;
-      console.log(c.green("applied[ADDED]") + ` ${path.relative(projectRoot, targetPath)}`);
+      console.log(c.green("applied[ADDED]") + ` ${relPath(projectRoot, targetPath)}`);
     } else if (op === "REMOVED") {
       if (!exists(targetPath)) {
-        console.log(c.yellow("warn:") + ` REMOVED delta targets missing spec ${path.relative(projectRoot, targetPath)} — skipping`);
+        console.log(c.yellow("warn:") + ` REMOVED delta targets missing spec ${relPath(projectRoot, targetPath)} — skipping`);
         continue;
       }
       remove(targetPath);
       writes += 1;
-      console.log(c.green("applied[REMOVED]") + ` ${path.relative(projectRoot, targetPath)}`);
+      console.log(c.green("applied[REMOVED]") + ` ${relPath(projectRoot, targetPath)}`);
     } else if (op === "MODIFIED") {
-      console.log(c.yellow("manual[MODIFIED]") + ` merge ${path.relative(projectRoot, deltaPath)} into ${path.relative(projectRoot, targetPath)} by hand`);
+      console.log(c.yellow("manual[MODIFIED]") + ` merge ${relPath(projectRoot, deltaPath)} into ${relPath(projectRoot, targetPath)} by hand`);
       manual += 1;
     } else {
       console.error(c.red("error:") + ` unknown Operation "${op}" in ${rel}`);
@@ -201,7 +204,7 @@ function changeArchive(args, _flags) {
 
   const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
   if (!isDir(changeDir)) {
-    console.error(c.red("error:") + ` change "${id}" not found at ${path.relative(projectRoot, changeDir)}`);
+    console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);
     return 1;
   }
 
@@ -209,11 +212,11 @@ function changeArchive(args, _flags) {
   const archiveName = `${date}-${id}`;
   const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive", archiveName);
   if (exists(archiveDir)) {
-    console.error(c.red("error:") + ` archive target already exists: ${path.relative(projectRoot, archiveDir)}`);
+    console.error(c.red("error:") + ` archive target already exists: ${relPath(projectRoot, archiveDir)}`);
     return 1;
   }
   move(changeDir, archiveDir);
-  console.log(c.green("archived") + ` ${path.relative(projectRoot, archiveDir)}`);
+  console.log(c.green("archived") + ` ${relPath(projectRoot, archiveDir)}`);
 
   // Collect affected specs from delta files for the index entry
   const deltaFiles = walk(path.join(archiveDir, "specs")).filter((p) => p.endsWith("delta.md"));
@@ -228,11 +231,31 @@ function changeArchive(args, _flags) {
   // Title from proposal
   const proposal = path.join(archiveDir, "proposal.md");
   if (exists(proposal)) {
-    const firstLine = read(proposal).split("\n", 1)[0] ?? "";
-    const m = firstLine.match(/^#\s+Change\s+[^—-]+[—-]\s*(.+)$/);
+    // First line may end in \r on Windows checkouts (autocrlf); split on
+    // either ending so the title regex is not defeated by a stray \r.
+    const firstLine = read(proposal).split(/\r?\n/, 1)[0] ?? "";
+    // The id itself may contain hyphens (NNNN-slug), so match it as \S+
+    // and split on the em-dash/hyphen separator that follows whitespace.
+    const m = firstLine.match(/^#\s+Change\s+\S+\s*[—-]\s*(.+)$/);
     if (m) title = m[1].trim();
   }
 
+  // Append a one-line summary to the archive ledger so history stays
+  // scannable without opening folders (the archive is out of the default
+  // read path; the ledger is the cheap way back in).
+  const ledgerPath = path.join(projectRoot, ".doctrina", "changes", "archive", "LEDGER.md");
+  if (!exists(ledgerPath)) {
+    write(ledgerPath,
+      "# Change ledger\n\n" +
+      "One line per archived change, newest last. Appended by\n" +
+      "`doctrina change archive`; edit freely, the CLI only appends.\n\n");
+  }
+  const specsSummary = specsAffected.length > 0
+    ? ` (specs: ${specsAffected.map((s) => `${s.capability} ${s.operation}`).join(", ")})`
+    : "";
+  write(ledgerPath, read(ledgerPath) + `- ${date} — ${id} — ${title}${specsSummary}\n`, { force: true });
+  console.log(c.green("ledger") + ` +1 line in ${relPath(projectRoot, ledgerPath)}`);
+
   const index = idx.load(projectRoot);
   idx.moveChangeToArchive(index, id, {
     id,
@@ -248,6 +271,74 @@ function changeArchive(args, _flags) {
   return 0;
 }
 
+function changeDiff(args, _flags) {
+  const id = args[0];
+  if (!id) {
+    console.error(c.red("error:") + " change diff requires <id>");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+  if (!isDir(changeDir)) {
+    console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);
+    return 1;
+  }
+
+  const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
+  if (deltaFiles.length === 0) {
+    console.log(c.gray("no spec deltas in this change; nothing to diff"));
+    return 0;
+  }
+
+  let errors = 0;
+  for (const deltaPath of deltaFiles) {
+    const rel = relPath(changeDir, deltaPath);
+    const text = read(deltaPath);
+    const op = parseOperation(text);
+    const capability = parseCapabilityFromDelta(text, deltaPath);
+    if (!op || !capability) {
+      console.error(c.red("error:") + ` cannot parse Operation or capability in ${rel}`);
+      errors += 1;
+      continue;
+    }
+    const targetPath = path.join(projectRoot, ".doctrina", "specs", capability, "spec.md");
+    const targetRel = relPath(projectRoot, targetPath);
+    const body = extractDeltaBody(text);
+    const bodyLines = body.split("\n").filter((l, i, a) => !(i === a.length - 1 && l === "")).length;
+
+    console.log("");
+    if (op === "ADDED") {
+      const conflict = exists(targetPath) ? c.red(" (conflict: target already exists)") : "";
+      console.log(c.green(`ADDED`) + ` ${targetRel} (+${bodyLines} lines)${conflict}`);
+    } else if (op === "REMOVED") {
+      if (!exists(targetPath)) {
+        console.log(c.yellow("REMOVED") + ` ${targetRel} (target already missing)`);
+      } else {
+        console.log(c.red("REMOVED") + ` ${targetRel} (-${lineCount(targetPath)} lines)`);
+      }
+    } else {
+      if (!exists(targetPath)) {
+        console.error(c.red("error:") + ` MODIFIED delta targets missing spec ${targetRel}`);
+        errors += 1;
+        continue;
+      }
+      console.log(c.yellow("MODIFIED") + ` ${targetRel}`);
+      console.log(c.gray("note: the delta body is a fragment to merge — '-' lines are current"));
+      console.log(c.gray("      spec content absent from the delta, not necessarily removals."));
+      const out = formatUnified(diffLines(read(targetPath), body), {
+        aLabel: targetRel,
+        bLabel: relPath(projectRoot, deltaPath),
+      });
+      console.log(out);
+    }
+  }
+
+  console.log("");
+  return errors > 0 ? 1 : 0;
+}
+
 function parseOperation(text) {
   const m = text.match(/^\*\*Operation:\*\*\s*([A-Z]+)/m);
   if (!m) return null;
@@ -286,7 +377,13 @@ Subcommands:
   new <id> "<title>"     Open a new change proposal at .doctrina/changes/<id>/
   apply <id>             Apply spec deltas (ADDED writes, REMOVED deletes, MODIFIED is manual)
   archive <id>           Move the change to .doctrina/changes/archive/YYYY-MM-DD-<id>/
+  diff <id>              Preview every spec delta: line diff for MODIFIED,
+                         summary for ADDED/REMOVED. Read-only.
 
 Options:
   --force                Overwrite existing files (where applicable)
 `;
+
+// Re-export parsers so scan.js (index rebuild) can reuse them, and the
+// scaffold so `work` can open a change without duplicating the logic.
+export { parseOperation, parseCapabilityFromDelta, changeNew };

package/src/commands/clarify.js

@@ -1,6 +1,8 @@
 import path from "node:path";
 import process from "node:process";
-import { isFile, read } from "../lib/fs-ops.js";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 
 const RULES = [
@@ -25,22 +27,90 @@ const RULES = [
   },
 ];
 
-export async function run(positional, _flags) {
+export async function run(positional, flags) {
+  const projectRoot = process.cwd();
+
+  if (flagBool(flags, "all", false)) return clarifyAll(projectRoot);
+
   const target = positional[0];
   if (!target) {
-    console.error(c.red("error:") + " clarify requires a path to a Markdown file");
+    console.error(c.red("error:") + " clarify requires a path to a Markdown file (or --all)");
     return 2;
   }
-  const projectRoot = process.cwd();
   const fullPath = path.resolve(projectRoot, target);
   if (!isFile(fullPath)) {
     console.error(c.red("error:") + ` file not found: ${target}`);
     return 1;
   }
 
-  console.log(`clarify ${path.relative(projectRoot, fullPath)}`);
+  console.log(`clarify ${relPath(projectRoot, fullPath)}`);
+  console.log("");
+
+  const smells = scanFile(fullPath);
+  for (const s of smells) {
+    console.log(`${c.yellow("⚠")} line ${s.line}: ${s.rule} "${s.token}" — ${s.hint}`);
+  }
+
+  console.log("");
+  if (smells.length === 0) {
+    console.log(c.green("ok") + " no smells found");
+    return 0;
+  }
+  const word = smells.length === 1 ? "smell" : "smells";
+  console.log(c.red("fail") + ` ${smells.length} ${word}`);
+  return 1;
+}
+
+// Walk every living document — product, specs, open changes, skills —
+// and clarify each. ADRs are immutable and the archive is history, so
+// neither is included; AGENTS.md is dense command text, a different
+// register from prose specs.
+function clarifyAll(projectRoot) {
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+  const files = [];
+  const productPath = path.join(projectRoot, ".doctrina", "product.md");
+  if (isFile(productPath)) files.push(productPath);
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (isDir(specsDir)) {
+    for (const cap of readdirSync(specsDir).sort()) {
+      const p = path.join(specsDir, cap, "spec.md");
+      if (isFile(p)) files.push(p);
+    }
+  }
+  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;
+      files.push(...walk(path.join(changesDir, id)).filter((f) => f.endsWith(".md")));
+    }
+  }
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  files.push(...walk(skillsDir).filter((f) => f.endsWith(".md")));
+
+  let total = 0;
+  for (const f of files) {
+    const smells = scanFile(f);
+    if (smells.length === 0) continue;
+    total += smells.length;
+    const rel = relPath(projectRoot, f);
+    for (const s of smells) {
+      console.log(`${c.yellow("⚠")} ${rel}:${s.line}: ${s.rule} "${s.token}" — ${s.hint}`);
+    }
+  }
+
   console.log("");
+  if (total === 0) {
+    console.log(c.green("ok") + ` no smells in ${files.length} living document${files.length === 1 ? "" : "s"}`);
+    return 0;
+  }
+  console.log(c.red("fail") + ` ${total} smell${total === 1 ? "" : "s"} across ${files.length} documents`);
+  return 1;
+}
 
+function scanFile(fullPath) {
   const text = read(fullPath);
   const skippedRanges = collectSkippedRanges(text);
   const smells = [];
@@ -80,19 +150,7 @@ export async function run(positional, _flags) {
   }
 
   smells.sort((a, b) => a.line - b.line);
-
-  for (const s of smells) {
-    console.log(`${c.yellow("⚠")} line ${s.line}: ${s.rule} "${s.token}" — ${s.hint}`);
-  }
-
-  console.log("");
-  if (smells.length === 0) {
-    console.log(c.green("ok") + " no smells found");
-    return 0;
-  }
-  const word = smells.length === 1 ? "smell" : "smells";
-  console.log(c.red("fail") + ` ${smells.length} ${word}`);
-  return 1;
+  return smells;
 }
 
 // Build ranges to skip: fenced code blocks, HTML comments, inline backticks.
@@ -135,12 +193,17 @@ function findAcceptanceLine(text) {
 
 export const help = `
 Usage: doctrina clarify <path>
+       doctrina clarify --all
 
 Read a Markdown file and report weasel words, vague quantifiers,
 placeholders, and empty Acceptance criteria sections. Exits 0 when
 no smells are found, 1 otherwise. Matches inside fenced code
 blocks, HTML comments, and inline backtick spans are skipped.
 
+With --all, every living document is scanned in one pass:
+product.md, capability specs, open changes, and skills. ADRs
+(immutable) and the archive (history) are excluded. CI-friendly.
+
 Intended use: run before \`doctrina change apply\` or before
 opening a PR. The command never modifies files.
 `;

package/src/commands/context.js

@@ -0,0 +1,129 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, lineCount, read, relPath, walk } from "../lib/fs-ops.js";
+import { listHeader } from "../lib/scan.js";
+import { parseFrontmatter } from "./skill.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+
+// Materialise the AGENTS.md read order as a command: print the exact
+// context pack for a task, in the order an agent should read it. This is
+// the context-engineering thesis turned into tooling — selection over
+// dumping, ranked by the documented read order.
+
+export async function run(positional, flags) {
+  const capability = positional[0] ?? null;
+  const concat = flagBool(flags, "concat", 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.");
+  }
+
+  if (capability && !/^[a-z][a-z0-9-]*$/.test(capability)) {
+    console.error(c.red("error:") + ` invalid capability "${capability}" (lowercase letters, digits, hyphens)`);
+    return 2;
+  }
+
+  const pack = [];
+  const pushFile = (rel, note) => {
+    const full = path.join(projectRoot, rel);
+    if (isFile(full)) pack.push({ rel, lines: lineCount(full), note });
+  };
+
+  // 1-2. Root rules and product truth — always first. Displayed paths are
+  // POSIX strings (path.join would emit backslashes on Windows).
+  pushFile("AGENTS.md", "root rules");
+  pushFile(".doctrina/product.md", "product truth");
+
+  // 3. The capability spec under work.
+  let specMissing = false;
+  if (capability) {
+    const specRel = `.doctrina/specs/${capability}/spec.md`;
+    if (isFile(path.join(projectRoot, specRel))) {
+      pushFile(specRel, `spec: ${capability}`);
+    } else {
+      specMissing = true;
+    }
+  }
+
+  // 4. Open changes (their proposal, tasks, and deltas).
+  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;
+      for (const f of walk(path.join(changesDir, id))) {
+        if (!f.endsWith(".md")) continue;
+        pushFile(relPath(projectRoot, f), `open change: ${id}`);
+      }
+    }
+  }
+
+  // 5. Accepted ADRs only — superseded/withdrawn stay out of the pack.
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  for (const f of walk(adrDir)) {
+    if (!f.endsWith(".md")) continue;
+    const status = (listHeader(read(f), "Status") ?? "").toLowerCase();
+    if (status === "accepted") pushFile(relPath(projectRoot, f), "accepted ADR");
+  }
+
+  // 6. Skills are on-demand: list name + description, never the body.
+  const onDemand = [];
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  for (const f of walk(skillsDir)) {
+    if (!f.endsWith(".md")) continue;
+    const text = read(f);
+    onDemand.push({
+      rel: relPath(projectRoot, f),
+      name: parseFrontmatter(text, "name") ?? path.basename(f, ".md"),
+      description: parseFrontmatter(text, "description") ?? "<missing description>",
+    });
+  }
+
+  if (concat) {
+    for (const item of pack) {
+      console.log(`===== ${item.rel} (${item.note}) =====`);
+      console.log("");
+      console.log(read(path.join(projectRoot, item.rel)).trimEnd());
+      console.log("");
+    }
+  } else {
+    console.log(c.bold("Context pack") + (capability ? c.gray(` (capability: ${capability})`) : "") + c.gray(" — read in this order:"));
+    console.log("");
+    pack.forEach((item, i) => {
+      console.log(`${i + 1}. ${c.cyan(item.rel.padEnd(56))} ${String(item.lines).padStart(4)} lines  ${c.gray(item.note)}`);
+    });
+    const total = pack.reduce((sum, item) => sum + item.lines, 0);
+    console.log("");
+    console.log(c.gray(`${pack.length} files, ${total} lines total · archive excluded by design`));
+    if (onDemand.length > 0) {
+      console.log("");
+      console.log(c.bold("On-demand skills") + c.gray(" (load the body only when the task matches):"));
+      for (const s of onDemand) {
+        console.log(`   ${c.cyan(s.name.padEnd(24))} ${s.description}  ${c.gray(s.rel)}`);
+      }
+    }
+  }
+
+  if (specMissing) {
+    console.error("");
+    console.error(c.yellow("warn:") + ` no spec for capability "${capability}" — create one with \`doctrina spec new ${capability}\``);
+  }
+  return 0;
+}
+
+export const help = `
+Usage: doctrina context [<capability>] [--concat]
+
+Print the exact context pack for a task, in the documented read
+order: AGENTS.md, product.md, the capability spec (when given), open
+changes, accepted ADRs. Skills are listed name + description only —
+they are on-demand by design. The change archive is excluded.
+
+Flags:
+  --concat   Print the file contents (with separators) instead of the
+             file list — ready to pipe into an agent.
+
+Read-only; always exits 0.
+`;