doctrina-cli 0.17.0 → 0.20.0

package/src/lib/skill-candidates.js

@@ -0,0 +1,162 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read, walk } from "./fs-ops.js";
+import { git, GIT_STATE } from "./git.js";
+import { FIX_SHAPED, FIX_SHAPED_SUBJECT, skillSlug } from "./lexicon.js";
+
+// The lessons worth a skill, as DATA (change 0202). `skill suggest` listed
+// them and `close` printed that whole listing at the end of every close —
+// the same thirteen candidates, close after close, which a field review of
+// 0.17 called noise. The close now asks for the list and renders only what
+// THIS close produced, so the collection lives here, where both read it
+// (ADR 0025: commands render, lib decides).
+
+/**
+ * @typedef {object} SkillCandidate
+ * @property {string} id
+ * @property {string} slug
+ * @property {"change"|"commit"} source
+ * @property {string} [from]  archive folder name, for a change candidate
+ * @property {string} [ref]   short sha, for a commit candidate
+ * @property {string} [why]
+ */
+
+/**
+ * Fix-shaped lessons not yet captured as a skill, from the archive and the
+ * git history, deduped by slug.
+ *
+ * @param {string} projectRoot
+ * @param {{ since?: string, limit?: number }} [opts]
+ * @returns {SkillCandidate[]}
+ */
+export function skillCandidates(projectRoot, { since, limit = 200 } = {}) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  const existingFiles = isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")) : [];
+  const existing = new Set(existingFiles.map((f) => path.basename(f, ".md")));
+  // A lesson may already be captured under a DIFFERENT slug (0.11.0 field
+  // review item 11: the human names the skill after the lesson, not after the
+  // change id — "tela-preta-crash-de-render..." for change 0049). Two extra
+  // dedup signals: an existing skill whose body cites the candidate's change
+  // id / commit hash, and token-overlap similarity between the slugs.
+  const existingBodies = existingFiles.map((f) => ({ slug: path.basename(f, ".md"), body: read(f) }));
+  const captured = (cand) => {
+    if (existing.has(cand.slug)) return true;
+    for (const sk of existingBodies) {
+      if (cand.id && sk.body.includes(cand.id)) return true;
+      if (cand.from && sk.body.includes(cand.from)) return true;
+      if (slugSimilarity(cand.slug, sk.slug) >= 0.5) return true;
+    }
+    return false;
+  };
+
+  // Two deterministic sources, deduped by slug. `seen` guards against a lesson
+  // appearing twice (e.g. a fix committed and later archived as a change).
+  /** @type {SkillCandidate[]} */
+  const candidates = [];
+  const seen = new Set();
+
+  // Source 1 — archived change proposals with a fix-shaped folder name.
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  if (isDir(archiveDir)) {
+    for (const name of readdirSync(archiveDir).sort()) {
+      if (!isDir(path.join(archiveDir, name))) continue;
+      const id = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+      if (!FIX_SHAPED.test(id)) continue;
+      const slug = skillSlug(id);
+      if (seen.has(slug)) continue;
+      /** @type {SkillCandidate} */
+      const cand = { id, slug, source: "change", from: name };
+      if (captured(cand)) continue; // captured (any slug) or cited by an existing skill
+      const proposal = path.join(archiveDir, name, "proposal.md");
+      cand.why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
+      seen.add(slug);
+      candidates.push(cand);
+    }
+  }
+
+  // Source 2 — fix-shaped commits in the git history (ADR 0013). Archive wins a
+  // slug collision: a `## Why` paragraph is a richer seed than a subject line.
+  for (const cand of gitFixCommits(projectRoot, { since, limit })) {
+    if (seen.has(cand.slug) || captured(cand)) continue;
+    seen.add(cand.slug);
+    candidates.push(cand);
+  }
+
+  return candidates;
+}
+
+// Source 2 for `skill suggest`: fix-shaped commits in the git history (ADR
+// 0013). Deterministic — a regex on the subject, never a read of the diff
+// (ADR 0005 semantic-fidelity ceiling). Returns [] silently when this is not a
+// git repo, git is absent, or the --since ref is unknown, so the command
+// degrades to archive-only rather than erroring.
+function gitFixCommits(projectRoot, { since, limit }) {
+  // US (0x1f) between fields, RS (0x1e) between records — robust against any
+  // newline or punctuation inside a subject or body.
+  const format = "%H%x1f%s%x1f%b%x1e";
+  const args = ["log", "--no-merges", `--format=${format}`];
+  if (since) args.push(`${since}..HEAD`);
+  else args.push("-n", String(limit));
+
+  const r = git(projectRoot, args);
+  if (r.state !== GIT_STATE.OK || !r.stdout) return [];
+
+  /** @type {SkillCandidate[]} */
+  const out = [];
+  const seen = new Set();
+  for (const record of r.stdout.split("\x1e")) {
+    const [sha, subject = "", body = ""] = record.replace(/^\r?\n/, "").split("\x1f");
+    if (!sha || !sha.trim()) continue;
+    if (!FIX_SHAPED_SUBJECT.test(subject)) continue;
+    const slug = commitSlug(subject);
+    if (!slug || seen.has(slug)) continue; // first commit wins a duplicate lesson
+    seen.add(slug);
+    const firstBodyLine = body.split(/\r?\n/).map((l) => l.trim()).find(Boolean) ?? "";
+    out.push({
+      id: slug,
+      slug,
+      source: "commit",
+      ref: sha.trim().slice(0, 9),
+      why: subject.trim() + (firstBodyLine ? ` — ${firstBodyLine}` : ""),
+    });
+  }
+  return out;
+}
+
+// Derive a skill slug from a commit subject: drop a conventional-commit
+// "type(scope): " prefix and hand the rest to the shared slug, which folds.
+function commitSlug(subject) {
+  return skillSlug(subject.replace(/^[a-z]+(?:\([^)]*\))?!?\s*:\s*/i, ""));
+}
+
+// Token-overlap similarity between two kebab slugs (Jaccard over meaningful
+// tokens). "0049-fix-tela-preta-render" vs "tela-preta-crash-de-render-sem-
+// error-boundary" share tela/preta/render → high overlap even though the
+// human renamed the skill after the lesson. Deterministic; never semantic.
+function slugSimilarity(a, b) {
+  const toks = (s) => new Set(
+    String(s).split("-").filter((t) => t.length >= 3 && !/^\d+$/.test(t) && !SLUG_NOISE.has(t)),
+  );
+  const A = toks(a);
+  const B = toks(b);
+  if (A.size === 0 || B.size === 0) return 0;
+  let inter = 0;
+  for (const t of A) if (B.has(t)) inter += 1;
+  return inter / (A.size + B.size - inter);
+}
+
+// Fix-shaped verbs and connectives carry no lesson identity — without this,
+// every "fix-..." candidate looks 30% similar to every "fix-..." skill.
+const SLUG_NOISE = new Set([
+  "fix", "bug", "hotfix", "patch", "the", "and", "for", "with", "sem", "com",
+  "que", "nao", "por", "para", "una", "uma", "dos", "das",
+]);
+
+function firstWhyLine(proposalText) {
+  const m = proposalText.match(/##\s*Why\s*\r?\n+([^\r\n][^\r\n]*)/i);
+  if (!m) return "";
+  const line = m[1].trim();
+  return /^<!--/.test(line) ? "" : line;
+}
+

package/src/lib/skill-export.js

@@ -0,0 +1,95 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, pruneEmptyDirs, read, remove, write, walk } from "./fs-ops.js";
+import { parseFrontmatter } from "./doc-model.js";
+import { describeAdapter, ADAPTER_STATES } from "./adapters.js";
+
+// The project's skills, where the agent looks for skills (change 0212).
+//
+// A field review of an agent in Cursor: the editor's skill catalogue lists
+// `~/.cursor/skills` and plugins, never `.doctrina/skills/`, so a skill that
+// matched the task fired only when the request named its file. AGENTS.md
+// said "skills are on demand"; nothing said the editor would never offer
+// them. The agents now share a format — a folder per skill holding a
+// SKILL.md with `name` and `description` — and discover it on their own:
+// `.agents/skills/` (Cursor, Codex) and `.claude/skills/` (Claude Code;
+// Cursor reads it too). `.doctrina/skills/` stays the one source; the
+// exports are generated from it, marked as generated, and pruned with it.
+
+export const EXPORT_MARK = "<!-- doctrina:skill-export";
+const DESCRIPTION_MAX = 1024;
+
+/** Where this project's skills are exported, as project-relative roots. */
+export function exportRoots(projectRoot) {
+  const roots = [".agents/skills"];
+  if (describeAdapter(projectRoot, "claude").state === ADAPTER_STATES.INSTALLED) roots.push(".claude/skills");
+  return roots;
+}
+
+/** The SKILL.md a Doctrina skill becomes. */
+export function renderSkillExport(name, text) {
+  const body = text.replace(/\r\n/g, "\n");
+  const description = parseFrontmatter(body, "description") ?? name;
+  const when = parseFrontmatter(body, "when");
+  // The agent decides from the description alone, so the trigger goes in it.
+  const full = (when ? `${description} Use when: ${when}` : description).replace(/\s+/g, " ").trim();
+  const clipped = full.length > DESCRIPTION_MAX ? `${full.slice(0, DESCRIPTION_MAX - 1)}…` : full;
+  const rest = body.replace(/^---\n[\s\S]*?\n---\n/, "").replace(/^\n+/, "");
+  return [
+    "---",
+    `name: ${name}`,
+    `description: ${JSON.stringify(clipped)}`,
+    "---",
+    `${EXPORT_MARK} — generated from .doctrina/skills/${name}.md by \`doctrina index rebuild\`; edit that file, not this one. -->`,
+    "",
+    rest,
+  ].join("\n").replace(/\n*$/, "\n");
+}
+
+/**
+ * What the export would change: files to write (missing or different) and
+ * generated skill folders to remove (their source is gone). Folders not
+ * carrying the generated mark are someone else's and never touched.
+ *
+ * @param {string} projectRoot
+ * @returns {{ writes: Array<{ rel: string, body: string }>, removes: string[] }}
+ */
+export function planSkillExport(projectRoot) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  const skills = isDir(skillsDir)
+    ? walk(skillsDir).filter((f) => f.endsWith(".md") && path.dirname(f) === skillsDir)
+    : [];
+  const wanted = new Map(skills.map((f) => [path.basename(f, ".md"), read(f)]));
+  const writes = [];
+  const removes = [];
+  if (wanted.size === 0 && !exportRoots(projectRoot).some((r) => isDir(path.join(projectRoot, r)))) {
+    return { writes, removes };
+  }
+  for (const root of exportRoots(projectRoot)) {
+    for (const [name, text] of wanted) {
+      const rel = `${root}/${name}/SKILL.md`;
+      const body = renderSkillExport(name, text);
+      const abs = path.join(projectRoot, rel);
+      if (!isFile(abs) || read(abs).replace(/\r\n/g, "\n") !== body) writes.push({ rel, body });
+    }
+    const rootAbs = path.join(projectRoot, root);
+    if (!isDir(rootAbs)) continue;
+    for (const entry of readdirSync(rootAbs)) {
+      const skillFile = path.join(rootAbs, entry, "SKILL.md");
+      if (wanted.has(entry) || !isFile(skillFile)) continue;
+      if (read(skillFile).includes(EXPORT_MARK)) removes.push(`${root}/${entry}/SKILL.md`);
+    }
+  }
+  return { writes, removes };
+}
+
+/** Apply a plan; returns it. */
+export function applySkillExport(projectRoot, plan = planSkillExport(projectRoot)) {
+  for (const w of plan.writes) write(path.join(projectRoot, w.rel), w.body, { force: true });
+  for (const r of plan.removes) {
+    remove(path.join(projectRoot, r)); // the generated file only
+    pruneEmptyDirs(path.dirname(path.join(projectRoot, r)), projectRoot);
+  }
+  return plan;
+}

package/src/lib/snapshot.js

@@ -4,7 +4,7 @@ import { readdirSync } from "node:fs";
 import { isDir, isFile, read, walk } from "./fs-ops.js";
 import { projectName } from "./project.js";
 import * as idx from "./index-json.js";
-import { deriveIndex, indexesMatch, specHeader, listHeader } from "./scan.js";
+import { deriveIndex, indexesMatch, specHeader, listHeader, deltaCapabilities } from "./scan.js";
 import { cliVersion } from "./version.js";
 import { summarize as coverageSummary } from "./coverage-model.js";
 import { summarize as traceSummary } from "./trace-model.js";
@@ -15,6 +15,7 @@ import { parseChangeTitle, checklistProgress } from "./doc-model.js";
 import { summarizeSignoffs } from "./signoff.js";
 import { gitWindow, historyState, windowCutoff } from "./git.js";
 import { collectMetrics } from "./metrics-model.js";
+import { today } from "./dates.js";
 
 // ONE collector, several views (audit finding F7).
 //
@@ -71,6 +72,7 @@ export function collectSnapshot(projectRoot, { actions = true } = {}) {
     decisions: countDecisions(projectRoot),
     skills: countSkills(projectRoot),
     openChanges: openChanges(projectRoot),
+    recentlyClosed: recentlyClosed(projectRoot),
     adrs: acceptedDecisions(projectRoot),
     nonGoals: productSection(projectRoot, "Non-goals"),
     hasNonGoalsSection: hasProductSection(projectRoot, "Non-goals"),
@@ -149,11 +151,83 @@ export function openChanges(projectRoot) {
     const tasksTotal = progress.total;
     const tasksDone = progress.done;
     const unchecked = progress.open.map((t) => t || "(unwritten task — the scaffold's placeholder)");
-    out.push({ id, title, status, tasksDone, tasksTotal, unchecked });
+    const date = proposal ? (listHeader(proposal, "Date") ?? null) : null;
+    // The capabilities its deltas target — what `prime` turns into the
+    // exact read command for the change (change 0217).
+    const capabilities = deltaCapabilities(path.join(changesDir, id));
+    out.push({ id, title, status, tasksDone, tasksTotal, unchecked, date, ageDays: ageInDays(date), capabilities });
   }
   return out;
 }
 
+// How far back `prime` and the pulse look for closed changes (change 0214).
+export const RECENT_CLOSE_DAYS = 7;
+
+/**
+ * Changes archived in the last RECENT_CLOSE_DAYS, newest first: what the
+ * human may ask for again without knowing it is done. A field review: the
+ * close moved the work to `changes/archive/`, out of every default read, and
+ * the next request was to "create the doctrina work" for it.
+ *
+ * @param {string} projectRoot
+ * @param {{ limit?: number }} [opts]
+ * @returns {Array<{ id: string, title: string|null, date: string, path: string, ageDays: number|null }>}
+ */
+export function recentlyClosed(projectRoot, { limit = 3 } = {}) {
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  if (!isDir(archiveDir)) return [];
+  const out = [];
+  for (const name of readdirSync(archiveDir).sort().reverse()) {
+    const m = name.match(/^(\d{4}-\d{2}-\d{2})-(.+)$/);
+    if (!m || !isDir(path.join(archiveDir, name))) continue;
+    const ageDays = ageInDays(m[1]);
+    if (ageDays === null || ageDays > RECENT_CLOSE_DAYS) break;
+    const proposal = path.join(archiveDir, name, "proposal.md");
+    out.push({
+      id: m[2], date: m[1], ageDays,
+      title: isFile(proposal) ? parseChangeTitle(read(proposal)) : null,
+      path: `.doctrina/changes/archive/${name}/`,
+    });
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+// How old a change has to be before "still open" is worth saying on its own.
+export const STALE_CHANGE_DAYS = 7;
+
+/**
+ * The open changes worth a line at the end of someone else's close (change
+ * 0201): a change that LOOKS finished — applied, or every task ticked — and
+ * was never closed, and a change open for a week or more. A field review of
+ * 0.17 found change 0078 shipped and left open, and no later close said so:
+ * the close is the moment someone is looking, so it is where to say it.
+ *
+ * @param {string} projectRoot
+ * @param {{ exclude?: string[] }} [opts]
+ */
+export function unfinishedChanges(projectRoot, { exclude = [] } = {}) {
+  const skip = new Set(exclude);
+  const out = [];
+  for (const ch of openChanges(projectRoot)) {
+    if (skip.has(ch.id)) continue;
+    const finished = ch.status === "applied" ||
+      (ch.tasksTotal > 0 && ch.tasksDone === ch.tasksTotal);
+    const old = ch.ageDays !== null && ch.ageDays >= STALE_CHANGE_DAYS;
+    const reason = ch.status === "applied"
+      ? "applied but never closed"
+      : finished ? "every task ticked, never closed" : old ? "still open" : null;
+    out.push({ ...ch, finished, old, reason });
+  }
+  return out;
+}
+
+function ageInDays(date) {
+  if (!date || !/^\d{4}-\d{2}-\d{2}$/.test(date)) return null;
+  const ms = Date.parse(`${today()}T00:00:00Z`) - Date.parse(`${date}T00:00:00Z`);
+  return Number.isFinite(ms) ? Math.max(0, Math.round(ms / 86400000)) : null;
+}
+
 function countSpecs(projectRoot) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   const impl = {};

package/src/lib/spec-ops.js

@@ -117,6 +117,40 @@ function matchOpsBlock(text) {
   return null;
 }
 
+/** One op line, parsed by the grammar `apply` reads: `{ verb, ... }` or `{ verb, error }`. */
+export function parseOp(line) {
+  return parseOpLine(String(line).trim());
+}
+
+/**
+ * Append op lines to a delta's live `ops` block — creating the block at the
+ * end when there is none (change 0205). A `bump-version` line replaces the
+ * block's existing one instead of stacking a second bump on it. Pure.
+ *
+ * @param {string} deltaText
+ * @param {string[]} lines  already validated with `parseOp`
+ * @returns {string}
+ */
+export function insertOps(deltaText, lines) {
+  const ranges = commentRanges(deltaText);
+  const fenceRe = /^([ \t]*```[ \t]*ops[ \t]*\r?\n)([\s\S]*?)(^[ \t]*```[ \t]*$)/gm;
+  const bumps = lines.some((l) => parseOp(l).verb === "bump-version");
+  let m;
+  while ((m = fenceRe.exec(deltaText))) {
+    if (isInsideComment(ranges, m.index)) continue;
+    const kept = m[2].split(/\r?\n/).filter((l) => l.trim() !== "")
+      .filter((l) => !(bumps && parseOp(l).verb === "bump-version"));
+    // The bump goes last, where a reader looks for it.
+    const ordered = [...kept, ...lines].sort((a, b) =>
+      Number(parseOp(a).verb === "bump-version") - Number(parseOp(b).verb === "bump-version"));
+    const block = `${m[1]}${ordered.join("\n")}\n${m[3]}`;
+    return deltaText.slice(0, m.index) + block + deltaText.slice(m.index + m[0].length);
+  }
+  const ordered = [...lines].sort((a, b) =>
+    Number(parseOp(a).verb === "bump-version") - Number(parseOp(b).verb === "bump-version"));
+  return `${deltaText.replace(/\s*$/, "")}\n\n\`\`\`ops\n${ordered.join("\n")}\n\`\`\`\n`;
+}
+
 function parseOpLine(line) {
   // `<verb> <rest>` — the verb is the first whitespace-delimited token.
   const sp = line.indexOf(" ");
@@ -178,6 +212,24 @@ function parseOpLine(line) {
       if (!value) return { verb, error: `replace-requirement ${n} is missing the requirement text` };
       return { verb, section, n, value };
     }
+    case "remove-requirement": {
+      // remove-requirement <section> <n>[: <why>] — the reason is for the
+      // reader of the delta; the spec loses the bullet either way.
+      const colon = rest.indexOf(":");
+      const head = (colon < 0 ? rest : rest.slice(0, colon)).trim().split(/\s+/);
+      const n = Number(head[head.length - 1]);
+      const section = normalizeSection(head.slice(0, -1).join(" "));
+      if (!section) return { verb, error: `remove-requirement: unknown section "${head.slice(0, -1).join(" ")}" (use ${SECTION_TOKENS})` };
+      if (!Number.isInteger(n) || n < 1) return { verb, error: `remove-requirement needs "<section> <n>" with a positive bullet number (got "${rest}")` };
+      return { verb, section, n };
+    }
+    case "remove-criterion": {
+      // remove-criterion <n>[: <why>]
+      const colon = rest.indexOf(":");
+      const n = Number((colon < 0 ? rest : rest.slice(0, colon)).trim());
+      if (!Number.isInteger(n) || n < 1) return { verb, error: `remove-criterion needs a positive criterion number (got "${rest}")` };
+      return { verb, n };
+    }
     default:
       return { verb: null, error: `unknown operation "${verb}"` };
   }
@@ -238,6 +290,10 @@ function applyOne(text, op) {
       return appendRequirement(text, op.section, op.value);
     case "replace-requirement":
       return replaceRequirement(text, op.section, op.n, op.value);
+    case "remove-requirement":
+      return removeRequirement(text, op.section, op.n);
+    case "remove-criterion":
+      return removeCriterion(text, op.n);
     default:
       return { error: `unknown operation "${op.verb}"` };
   }
@@ -334,10 +390,33 @@ export function replaceCriterion(text, n, value) {
   if (!loc) return { error: "replace-criterion: spec has no '## Acceptance criteria' section" };
   const item = loc.items.find((it) => it.n === n);
   if (!item) return { error: `replace-criterion: no criterion #${n} found` };
-  loc.lines[item.lineIndex] = `${item.indent}${n}. ${value}`;
+  // The whole item, continuation lines included (change 0206) — the lesson
+  // `replace-requirement` learned, which this verb never picked up: a
+  // criterion wrapped over three lines kept its old second and third lines
+  // under the new first one, so the spec stated a proof and then the
+  // previous proof's tail.
+  loc.lines.splice(item.lineIndex, endOfItem(loc.lines, item.lineIndex) - item.lineIndex + 1, `${item.indent}${n}. ${value}`);
   return { text: loc.lines.join("\n"), summary: `replace-criterion ${n}` };
 }
 
+// remove-criterion <n> — delete criterion n, continuation lines included,
+// and renumber the ones after it so the list stays 1..N (change 0206). A
+// spec only ever grew: there was no verb to take a criterion out, so a
+// superseded one stayed beside its replacement for good.
+export function removeCriterion(text, n) {
+  const loc = locateCriteria(text);
+  if (!loc) return { error: "remove-criterion: spec has no '## Acceptance criteria' section" };
+  const item = loc.items.find((it) => it.n === n);
+  if (!item) return { error: `remove-criterion: no criterion #${n} found` };
+  const end = endOfItem(loc.lines, item.lineIndex);
+  const lines = loc.lines;
+  for (const it of loc.items) {
+    if (it.n > n) lines[it.lineIndex] = lines[it.lineIndex].replace(/^(\s*)\d+\./, `$1${it.n - 1}.`);
+  }
+  lines.splice(item.lineIndex, end - item.lineIndex + 1);
+  return { text: lines.join("\n"), summary: `remove-criterion ${n} (${loc.items.length - n} renumbered)` };
+}
+
 // The `### <Section>` blocks under `## Requirements (EARS)`. Returns
 // { lines, sections: { <token>: { headingIndex, endIndex, bullets: [lineIndex] } } }
 // or null when the Requirements section is absent. A section's token is the
@@ -505,6 +584,23 @@ export function replaceRequirement(text, section, n, value) {
   return { text: loc.lines.join("\n"), summary: `replace-requirement ${section} ${n}` };
 }
 
+// remove-requirement <section> <n> — delete the nth bullet (1-based) of the
+// EARS subsection, continuation lines included (change 0206). The heading
+// stays even when it empties: `append-requirement` can fill it again.
+export function removeRequirement(text, section, n) {
+  const loc = locateRequirements(text);
+  if (!loc) return { error: "remove-requirement: spec has no '## Requirements (EARS)' section" };
+  const sec = loc.sections[section];
+  if (!sec) return { error: `remove-requirement: no '### ${section}...' subsection found under Requirements` };
+  const real = sec.bullets.filter((i) => !/^\s*-\s*$/.test(loc.lines[i]));
+  if (n > real.length) {
+    return { error: `remove-requirement: section "${section}" has ${real.length} requirement${real.length === 1 ? "" : "s"}, no #${n}` };
+  }
+  const start = real[n - 1];
+  loc.lines.splice(start, endOfItem(loc.lines, start) - start + 1);
+  return { text: loc.lines.join("\n"), summary: `remove-requirement ${section} ${n}` };
+}
+
 // append-criterion <text> — add a new numbered criterion after the last one
 // in the section.
 export function appendCriterion(text, value) {
@@ -523,3 +619,23 @@ export function appendCriterion(text, value) {
   loc.lines.splice(endOfItem(loc.lines, last.lineIndex) + 1, 0, `${last.indent}${nextN}. ${value}`);
   return { text: loc.lines.join("\n"), summary: `append-criterion ${nextN}` };
 }
+
+/**
+ * The size of a spec, as `work --consolidate` reports it (change 0206):
+ * lines, real requirement bullets per EARS subsection, and criteria.
+ * @param {string} text
+ */
+export function specShape(text) {
+  const req = locateRequirements(text);
+  const sections = {};
+  let requirements = 0;
+  for (const token of EARS_ORDER) {
+    const sec = req?.sections[token];
+    if (!sec) continue;
+    const n = sec.bullets.filter((i) => !/^\s*-\s*$/.test(req.lines[i])).length;
+    sections[token] = n;
+    requirements += n;
+  }
+  const crit = locateCriteria(text);
+  return { lines: text.split(/\r?\n/).length, requirements, sections, criteria: crit ? crit.items.length : 0 };
+}

package/src/lib/task-card.js

@@ -0,0 +1,102 @@
+// @ts-check
+import path from "node:path";
+import { isFile, read } from "./fs-ops.js";
+import { parseChangeTitle, parseChecklist } from "./doc-model.js";
+import { listHeader, deltaCapabilities } from "./scan.js";
+import { sliceSpec } from "./context-slice.js";
+import { terms } from "./lexicon.js";
+
+// A TASK CARD (change 0222, ADR 0030): one task of a change, carrying what
+// an executor needs to do it ALONE — the task, the lines indented under it
+// (files, requirement, verify command), why the change exists, and the spec
+// cut to the task. A subagent does not see the planner's conversation, so
+// the card is the whole of its context; a card that needs the conversation
+// is a card the planner has not finished writing.
+
+/**
+ * The tasks.md boxes, each with the indented lines under it.
+ * Ordinals are the same ones `change tick` uses (tasks.md comes first).
+ */
+export function taskBoxes(tasksText) {
+  const lines = String(tasksText).replace(/\r\n/g, "\n").split("\n");
+  return parseChecklist(tasksText).map((box, i) => {
+    const indent = (lines[box.line].match(/^\s*/)?.[0] ?? "").length;
+    const details = [];
+    for (let j = box.line + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (l.trim() === "") {
+        if (details.length) break;
+        continue;
+      }
+      if ((l.match(/^\s*/)?.[0] ?? "").length <= indent) break;
+      details.push(l.trim().replace(/^[-*]\s+/, ""));
+    }
+    return { ordinal: i + 1, text: box.text, checked: box.checked, placeholder: box.placeholder, details };
+  });
+}
+
+/** The `Field: value` lines of a card's details, keyed by lowercased field. */
+export function cardFields(details) {
+  const out = {};
+  for (const d of details) {
+    const m = d.match(/^([A-Za-z][A-Za-z ]{0,20}):\s*(.+)$/);
+    if (m) out[m[1].trim().toLowerCase()] = m[2].trim();
+  }
+  return out;
+}
+
+function firstParagraph(text, heading) {
+  const m = String(text).match(new RegExp(`^## ${heading}\\s*\\n+([\\s\\S]*?)(?:\\n\\s*\\n|\\n## |$)`, "m"));
+  return m ? m[1].replace(/<!--[\s\S]*?-->/g, "").trim() : "";
+}
+
+/**
+ * The card for task `ordinal` of a change — or, with no ordinal, the first
+ * open one. Null `card` with a reason when there is none to give.
+ * @returns {{ card: null, reason: string } | { card: object, reason: null }}
+ */
+export function taskCard(projectRoot, changeId, ordinal = null) {
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", changeId);
+  const tasksPath = path.join(changeDir, "tasks.md");
+  if (!isFile(tasksPath)) return { card: null, reason: "the change has no tasks.md" };
+  const boxes = taskBoxes(read(tasksPath));
+  if (boxes.length === 0) return { card: null, reason: "tasks.md has no task box" };
+  let box;
+  if (ordinal === null) {
+    box = boxes.find((b) => !b.checked && !b.placeholder);
+    if (!box) return { card: null, reason: "every task is ticked — the change is ready for review and close" };
+  } else {
+    box = boxes.find((b) => b.ordinal === ordinal);
+    if (!box) return { card: null, reason: `no task ${ordinal} (tasks.md has ${boxes.length})` };
+  }
+  if (box.placeholder) return { card: null, reason: `task ${box.ordinal} is a scaffold placeholder — write the task first` };
+  // CRLF on a Windows checkout: the Why is read paragraph by paragraph.
+  const proposal = isFile(path.join(changeDir, "proposal.md")) ? read(path.join(changeDir, "proposal.md")).replace(/\r\n/g, "\n") : "";
+  const fields = cardFields(box.details);
+  const query = terms([box.text, ...box.details].join(" "));
+  const slices = [];
+  for (const cap of deltaCapabilities(changeDir)) {
+    const rel = `.doctrina/specs/${cap}/spec.md`;
+    const specPath = path.join(projectRoot, rel);
+    if (!isFile(specPath)) continue;
+    const slice = sliceSpec(read(specPath), query, rel);
+    if (slice) slices.push({ capability: cap, ...slice });
+  }
+  return {
+    card: {
+      change: changeId,
+      title: parseChangeTitle(proposal) ?? changeId,
+      delivery: listHeader(proposal, "Delivery") ?? null,
+      ordinal: box.ordinal,
+      total: boxes.length,
+      done: boxes.filter((b) => b.checked).length,
+      checked: box.checked,
+      text: box.text,
+      details: box.details,
+      fields,
+      why: firstParagraph(proposal, "Why"),
+      slices,
+    },
+    reason: null,
+  };
+}

package/src/lib/validation-model.js

@@ -509,7 +509,7 @@ export function collectValidation(projectRoot, { fix = false, runtime = false }
       const specPath = path.join(specsDir, cap, "spec.md");
       if (isFile(specPath)) {
         const lines = lineCount(specPath);
-        if (lines > 400) warnings.push(`${relPath(projectRoot, specPath)} is ${lines} lines (>400 soft cap)`);
+        if (lines > 400) warnings.push(`${relPath(projectRoot, specPath)} is ${lines} lines (>400 soft cap) — consolidate it: \`doctrina work --consolidate ${path.basename(path.dirname(specPath))}\``);
 
         // 8b. EARS grammar shape — section-appropriate When/While/Where/shall.
         const text = read(specPath);