doctrina-cli 0.1.1 → 0.2.0

package/src/lib/diff.js

@@ -0,0 +1,103 @@
+// Minimal line diff (LCS-based) for `change diff`. Specs are capped at a
+// few hundred lines, so the O(n*m) table is fine and keeps us at zero deps.
+
+export function diffLines(aText, bText) {
+  const a = splitLines(aText);
+  const b = splitLines(bText);
+  const n = a.length;
+  const m = b.length;
+
+  // LCS length table.
+  const table = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      table[i][j] = a[i] === b[j]
+        ? table[i + 1][j + 1] + 1
+        : Math.max(table[i + 1][j], table[i][j + 1]);
+    }
+  }
+
+  // Backtrack into a flat op list.
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ type: "same", text: a[i] });
+      i += 1;
+      j += 1;
+    } else if (table[i + 1][j] >= table[i][j + 1]) {
+      ops.push({ type: "del", text: a[i] });
+      i += 1;
+    } else {
+      ops.push({ type: "add", text: b[j] });
+      j += 1;
+    }
+  }
+  while (i < n) ops.push({ type: "del", text: a[i++] });
+  while (j < m) ops.push({ type: "add", text: b[j++] });
+  return ops;
+}
+
+// Render ops as unified-style hunks with `context` lines around changes.
+export function formatUnified(ops, { context = 3, aLabel = "a", bLabel = "b" } = {}) {
+  const out = [`--- ${aLabel}`, `+++ ${bLabel}`];
+  const hunks = collectHunks(ops, context);
+  let aLine = 1;
+  let bLine = 1;
+  let cursor = 0;
+  for (const [start, end] of hunks) {
+    // Advance line counters across the skipped region.
+    for (; cursor < start; cursor++) {
+      if (ops[cursor].type !== "add") aLine += 1;
+      if (ops[cursor].type !== "del") bLine += 1;
+    }
+    let aLen = 0;
+    let bLen = 0;
+    for (let k = start; k < end; k++) {
+      if (ops[k].type !== "add") aLen += 1;
+      if (ops[k].type !== "del") bLen += 1;
+    }
+    out.push(`@@ -${aLine},${aLen} +${bLine},${bLen} @@`);
+    for (; cursor < end; cursor++) {
+      const op = ops[cursor];
+      const prefix = op.type === "add" ? "+" : op.type === "del" ? "-" : " ";
+      out.push(prefix + op.text);
+      if (op.type !== "add") aLine += 1;
+      if (op.type !== "del") bLine += 1;
+    }
+  }
+  if (hunks.length === 0) out.push("(no differences)");
+  return out.join("\n");
+}
+
+function collectHunks(ops, context) {
+  // Indices of changed ops.
+  const changed = [];
+  for (let k = 0; k < ops.length; k++) {
+    if (ops[k].type !== "same") changed.push(k);
+  }
+  if (changed.length === 0) return [];
+  const hunks = [];
+  let start = Math.max(0, changed[0] - context);
+  let end = Math.min(ops.length, changed[0] + context + 1);
+  for (let c = 1; c < changed.length; c++) {
+    const k = changed[c];
+    if (k - context <= end) {
+      end = Math.min(ops.length, k + context + 1);
+    } else {
+      hunks.push([start, end]);
+      start = Math.max(0, k - context);
+      end = Math.min(ops.length, k + context + 1);
+    }
+  }
+  hunks.push([start, end]);
+  return hunks;
+}
+
+function splitLines(text) {
+  const lines = text.split("\n");
+  // Drop a single trailing empty line produced by a final newline.
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}

package/src/lib/ears.js

@@ -0,0 +1,108 @@
+// Structural EARS checks for capability specs. The clarify command catches
+// word-level smells; this catches grammar-shape problems per EARS section.
+// All findings are warnings: specs evolve, validation should not block.
+
+const SECTION_RULES = [
+  {
+    match: /^###\s+Ubiquitous/i,
+    name: "Ubiquitous",
+    check(req) {
+      if (/^when\b/i.test(req)) return "event-shaped requirement (starts with \"When\") — move to ### Event-driven";
+      if (/^while\b/i.test(req)) return "state-shaped requirement (starts with \"While\") — move to ### State-driven";
+      if (/^where\b/i.test(req)) return "optional-shaped requirement (starts with \"Where\") — move to ### Optional";
+      if (!/\bshall\b/i.test(req)) return "missing \"shall\" — ubiquitous form is \"The system shall ...\"";
+      return null;
+    },
+  },
+  {
+    match: /^###\s+Event-driven/i,
+    name: "Event-driven",
+    check(req) {
+      if (!/^when\b/i.test(req)) return "expected \"When <trigger>, the system shall ...\"";
+      if (!/\bshall\b/i.test(req)) return "missing \"shall\" after the When-trigger";
+      return null;
+    },
+  },
+  {
+    match: /^###\s+State-driven/i,
+    name: "State-driven",
+    check(req) {
+      if (!/^while\b/i.test(req)) return "expected \"While <state>, the system shall ...\"";
+      if (!/\bshall\b/i.test(req)) return "missing \"shall\" after the While-state";
+      return null;
+    },
+  },
+  {
+    match: /^###\s+Unwanted/i,
+    name: "Unwanted-behavior",
+    check(req) {
+      if (!/\bshall\b/i.test(req)) return "missing \"shall\" — unwanted-behavior form is \"The system shall not ...\"";
+      if (!/\b(not|no|never)\b/i.test(req)) return "missing a negation — unwanted-behavior requirements forbid something";
+      return null;
+    },
+  },
+  {
+    match: /^###\s+Optional/i,
+    name: "Optional",
+    check(req) {
+      if (!/^where\b/i.test(req)) return "expected \"Where <feature is present>, the system may ...\"";
+      if (!/\bmay\b/i.test(req)) return "missing \"may\" — optional requirements use may, not shall";
+      return null;
+    },
+  },
+];
+
+// Check one spec text. Returns [{ line, message }]. Only applies to specs
+// that declare a "## Requirements (EARS)" section; bug-shape specs and
+// free-form specs are skipped entirely.
+export function checkEars(text) {
+  const lines = text.split("\n");
+  const findings = [];
+
+  let inRequirements = false;
+  let rule = null;
+  let req = null; // { line, text }
+
+  const flush = () => {
+    if (req && rule) {
+      const message = rule.check(req.text.trim());
+      if (message) findings.push({ line: req.line, message: `${rule.name}: ${message}` });
+    }
+    req = null;
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (/^##\s+Requirements \(EARS\)/i.test(line)) {
+      inRequirements = true;
+      continue;
+    }
+    if (!inRequirements) continue;
+    if (/^##\s+/.test(line)) {
+      // Left the Requirements section.
+      flush();
+      break;
+    }
+    if (/^###\s+/.test(line)) {
+      flush();
+      rule = SECTION_RULES.find((r) => r.match.test(line)) ?? null;
+      continue;
+    }
+    if (/^-\s+/.test(line)) {
+      flush();
+      req = { line: i + 1, text: line.replace(/^-\s+/, "") };
+      continue;
+    }
+    // Continuation of the current bullet (indented text or nested bullet).
+    if (req && /^\s+\S/.test(line)) {
+      req.text += " " + line.trim();
+    }
+  }
+  flush();
+  return findings;
+}
+
+export function isEarsSpec(text) {
+  return /^##\s+Requirements \(EARS\)/im.test(text);
+}

package/src/lib/fs-ops.js

@@ -73,3 +73,15 @@ export function lineCount(p) {
   if (text.length === 0) return 0;
   return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
 }
+
+// Normalise a path to forward slashes for display and comparison. CLI
+// output is part of the contract (tests, docs, agents parse it), so it
+// must not change shape between platforms.
+export function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+
+// path.relative with stable, platform-independent forward slashes.
+export function relPath(from, to) {
+  return toPosix(path.relative(from, to));
+}

package/src/lib/scan.js

@@ -0,0 +1,185 @@
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read, walk } from "./fs-ops.js";
+import { today } from "./dates.js";
+import { parseFrontmatter } from "../commands/skill.js";
+import { parseOperation, parseCapabilityFromDelta } from "../commands/change.js";
+
+// Parse a spec-style header line: **Name:** value
+export function specHeader(text, name) {
+  const m = text.match(new RegExp(`^\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
+  return m ? m[1].trim() : null;
+}
+
+// Parse an ADR/proposal-style header line: - **Name:** value
+export function listHeader(text, name) {
+  const m = text.match(new RegExp(`^-\\s+\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
+  return m ? m[1].trim() : null;
+}
+
+function dirEntries(dir) {
+  if (!isDir(dir)) return [];
+  return readdirSync(dir).filter((e) => !e.startsWith(".")).sort();
+}
+
+// Regenerate the index object from the artifacts on disk. The files are
+// the source of truth; fields with no on-disk source (project name,
+// framework_version, product metadata) are carried over from `current`.
+export function deriveIndex(projectRoot, current) {
+  const dot = path.join(projectRoot, ".doctrina");
+  const date = today();
+  const cur = current?.artifacts ?? {};
+
+  const out = {
+    $schema_version: current?.$schema_version ?? "0.1.0",
+    project: current?.project ?? path.basename(projectRoot),
+    framework_version: current?.framework_version ?? "0.0.0",
+    last_updated: current?.last_updated ?? date,
+    artifacts: {
+      product: cur.product ?? {
+        path: ".doctrina/product.md",
+        status: "active",
+        version: "0.1.0",
+        last_updated: date,
+      },
+      specs: [],
+      decisions: [],
+      changes: [],
+      changes_archive: [],
+      skills: [],
+    },
+  };
+
+  // Specs — headers inside each spec.md win over the previous index.
+  const specsDir = path.join(dot, "specs");
+  for (const cap of dirEntries(specsDir)) {
+    const p = path.join(specsDir, cap, "spec.md");
+    if (!isFile(p)) continue;
+    const text = read(p);
+    const prev = (cur.specs ?? []).find((s) => s.id === cap);
+    out.artifacts.specs.push({
+      id: cap,
+      path: `.doctrina/specs/${cap}/spec.md`,
+      status: specHeader(text, "Status") ?? prev?.status ?? "active",
+      version: specHeader(text, "Version") ?? prev?.version ?? "0.1.0",
+      last_updated: specHeader(text, "Last updated") ?? prev?.last_updated ?? date,
+    });
+  }
+
+  // Decisions — NNNN-slug.md files; Status/Date headers win.
+  const adrDir = path.join(dot, "decisions");
+  for (const f of walk(adrDir)) {
+    const base = path.basename(f);
+    const m = base.match(/^(\d{4})-.*\.md$/);
+    if (!m) continue;
+    const text = read(f);
+    const prev = (cur.decisions ?? []).find((d) => d.id === m[1]);
+    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+    const entry = {
+      id: m[1],
+      path: `.doctrina/decisions/${base}`,
+      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? base,
+      status: listHeader(text, "Status") ?? prev?.status ?? "proposed",
+      date: listHeader(text, "Date") ?? prev?.date ?? date,
+    };
+    const supersedes = listHeader(text, "Supersedes");
+    if (supersedes && supersedes !== "—") entry.supersedes = supersedes;
+    const supersededBy = listHeader(text, "Superseded by");
+    if (supersededBy && supersededBy !== "—") entry.superseded_by = supersededBy;
+    out.artifacts.decisions.push(entry);
+  }
+
+  // Open changes — every directory except archive/.
+  const changesDir = path.join(dot, "changes");
+  for (const id of dirEntries(changesDir)) {
+    if (id === "archive") continue;
+    if (!isDir(path.join(changesDir, id))) continue;
+    const prev = (cur.changes ?? []).find((c) => c.id === id);
+    const proposalPath = path.join(changesDir, id, "proposal.md");
+    const proposal = isFile(proposalPath) ? read(proposalPath) : "";
+    const titleMatch = proposal.match(/^#\s+Change\s+\S+\s*[—-]\s*(.+)$/m);
+    out.artifacts.changes.push({
+      id,
+      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? id,
+      path: `.doctrina/changes/${id}`,
+      status: listHeader(proposal, "Status") ?? prev?.status ?? "proposed",
+      opened: listHeader(proposal, "Date") ?? prev?.opened ?? date,
+    });
+  }
+
+  // Archived changes — folder name carries the applied date and id.
+  const archiveDir = path.join(changesDir, "archive");
+  for (const name of dirEntries(archiveDir)) {
+    const m = name.match(/^(\d{4}-\d{2}-\d{2})-(.+)$/);
+    if (!m || !isDir(path.join(archiveDir, name))) continue;
+    const prev = (cur.changes_archive ?? []).find((c) => c.path?.endsWith(name));
+    const proposalPath = path.join(archiveDir, name, "proposal.md");
+    const proposal = isFile(proposalPath) ? read(proposalPath) : "";
+    const titleMatch = proposal.match(/^#\s+Change\s+\S+\s*[—-]\s*(.+)$/m);
+    const specsAffected = [];
+    for (const deltaPath of walk(path.join(archiveDir, name, "specs"))) {
+      if (!deltaPath.endsWith("delta.md")) continue;
+      const text = read(deltaPath);
+      const capability = parseCapabilityFromDelta(text, deltaPath);
+      if (capability) {
+        specsAffected.push({ capability, operation: parseOperation(text) ?? "MODIFIED" });
+      }
+    }
+    out.artifacts.changes_archive.push({
+      id: m[2],
+      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? m[2],
+      path: `.doctrina/changes/archive/${name}`,
+      status: "applied",
+      applied: m[1],
+      specs_affected: specsAffected,
+    });
+  }
+
+  // Skills — frontmatter description wins.
+  const skillsDir = path.join(dot, "skills");
+  for (const f of walk(skillsDir)) {
+    if (!f.endsWith(".md")) continue;
+    const id = path.basename(f, ".md");
+    const prev = (cur.skills ?? []).find((s) => s.id === id);
+    out.artifacts.skills.push({
+      id,
+      path: `.doctrina/skills/${id}.md`,
+      description: parseFrontmatter(read(f), "description")
+        ?? prev?.description ?? "<edit me — one-sentence summary>",
+      last_updated: prev?.last_updated ?? date,
+    });
+  }
+
+  return out;
+}
+
+// Deterministic stringify (sorted keys) so two indexes compare by content,
+// not by key insertion order.
+export function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(value[k])).join(",") + "}";
+  }
+  return JSON.stringify(value);
+}
+
+// Content equality ignoring the root last_updated timestamp. Absent
+// artifact categories compare equal to empty ones so pre-skills indexes
+// are not flagged for a purely structural difference.
+export function indexesMatch(a, b) {
+  if (!a || !b) return false;
+  const normalize = (x) => {
+    const clone = { ...x };
+    delete clone.last_updated;
+    const arts = { ...(clone.artifacts ?? {}) };
+    for (const cat of ["specs", "decisions", "changes", "changes_archive", "skills"]) {
+      arts[cat] = arts[cat] ?? [];
+    }
+    clone.artifacts = arts;
+    return clone;
+  };
+  return stableStringify(normalize(a)) === stableStringify(normalize(b));
+}

package/src/lib/templates.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { read, walk, write } from "./fs-ops.js";
+import { read, toPosix, walk, write } from "./fs-ops.js";
 
 // Resolve the path to the .doctrina/templates/ directory shipped with this
 // package. The package layout is:
@@ -59,7 +59,7 @@ export function loadTemplateTree(templatesDir, subdir) {
   const root = path.join(templatesDir, subdir);
   const files = walk(root);
   return files.map((templatePath) => {
-    const relativePath = path.relative(root, templatePath);
+    const relativePath = toPosix(path.relative(root, templatePath));
     const body = templatePath.endsWith(".gitkeep") ? "" : read(templatePath);
     return { templatePath, relativePath, body };
   });

package/templates/AGENTS.md.template

@@ -11,6 +11,21 @@ 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).
+
 ## Stack and tooling
 
 <!-- Replace with the project's actual stack. Keep this section short. -->

package/templates/README.md

@@ -38,18 +38,33 @@ doctrina/                                  the .doctrina/ skeleton
   changes/.gitkeep
   changes/archive/.gitkeep
   decisions/.gitkeep
+  skills/.gitkeep
   templates/.gitkeep
-spec.md.template                           one capability spec
+spec.md.template                           one capability spec (EARS)
+spec-bug.md.template                       bug-shape capability spec
+skill.md.template                          one on-demand skill
 change/
   proposal.md.template
   tasks.md.template
   design.md.template
   spec-delta.md.template
 decision.md.template                       one ADR (Nygard/MADR)
+hooks/
+  pre-commit.sample                        installed by `doctrina hooks install`
+  watch.sample                             on-save validation wrapper (manual wiring)
 adapters/
   claude/CLAUDE.md.template
   codex/README.md
-  cursor/rules/00-doctrina.mdc.template
+  cursor/.cursor/rules/00-doctrina.mdc.template
+  copilot/.github/copilot-instructions.md.template
+  gemini/GEMINI.md.template
+  aider/CONVENTIONS.md.template
+  windsurf/.windsurfrules.template
+  continue/.continue/rules/00-doctrina.md.template
+  amp/README.md
+  devin/README.md
+  factory/README.md
+  jules/README.md
 ```
 
 ## Adapter strategy
@@ -59,6 +74,12 @@ adapters/
 | `claude` | `CLAUDE.md` at project root with `@AGENTS.md` import | Claude Code reads `CLAUDE.md` natively and supports `@file` includes. |
 | `codex` | nothing | OpenAI Codex CLI reads `AGENTS.md` natively; an adapter file would only add drift surface. |
 | `cursor` | `.cursor/rules/00-doctrina.mdc` with `alwaysApply: true` | Cursor's `.mdc` rules live in a dedicated directory; the file is a thin pointer. |
+| `copilot` | `.github/copilot-instructions.md` | GitHub Copilot's repository-level custom instructions path. |
+| `gemini` | `GEMINI.md` at project root | Gemini CLI's native context file. |
+| `aider` | `CONVENTIONS.md` at project root | Aider reads CONVENTIONS.md as cached read-only context. |
+| `windsurf` | `.windsurfrules` at project root | Windsurf's rules file convention. |
+| `continue` | `.continue/rules/00-doctrina.md` | Continue.dev's rules directory. |
+| `amp` / `devin` / `factory` / `jules` | nothing | AGENTS.md-native (same posture as `codex`); the directory marks the support contract and gives future per-agent affordances a home. |
 
 Adapter files stay under 30 lines so they cannot meaningfully drift from
 `AGENTS.md` and so they do not pay a noticeable per-turn token tax.

package/templates/doctrina/index.json.template

@@ -13,6 +13,7 @@
     "specs": [],
     "decisions": [],
     "changes": [],
-    "changes_archive": []
+    "changes_archive": [],
+    "skills": []
   }
 }