doctrina-cli 0.18.0 → 0.21.0

package/README.md

@@ -3,7 +3,7 @@
 > CLI for the Doctrina framework. The package is published as
 > `doctrina-cli`; the executable it installs is `doctrina`.
 
-**Status:** v0.18.0 — current release. Zero runtime dependencies
+**Status:** v0.21.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -25,10 +25,11 @@ surface, by the moment you reach for it:
 ```
 Bootstrap   init · intake · adapter list|add|remove
 Orient      prime · next · status · context · show · search · why · handoff
-Change      triage · work · spec new|list|set · change new|apply|archive|check|tick|abandon|delta
+Change      triage · work · spec new|list|set · change new|apply|archive|check|tick|abandon|delta|card
             contract new|list|check · decision new|accept|land|supersede|list|scope
             skill new|list|suggest · intent add|list
 Gate        clarify · validate · coverage · trace · review · verify · close · doctor
+Orchestrate workspace init|add|attach|detach|list|tool|guard · delivery new|route|list|status|tick|check|close
 Maintain    upgrade · index rebuild · hooks install · watch · metrics · completion · ci · templates list
 ```
 

package/package.json

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

package/src/commands/adapter.js

@@ -2,8 +2,11 @@
 import path from "node:path";
 import process from "node:process";
 import { exists, isFile, mkdirp, pruneEmptyDirs, read, relPath, remove, write } from "../lib/fs-ops.js";
+import { applyAdapterMigration, planAdapterMigration } from "../lib/adapters.js";
+import { relinkShadow, shadowRootOf } from "../lib/workspace.js";
 import {
   ADAPTER_STATES, adapterFiles, describeAdapter, listAdapterNames, renderAdapterFile,
+  isMergedConfig, mergeJson, unmergeJson, containsJson, holdsAnyOf,
 } from "../lib/adapters.js";
 import { flagBool } from "../lib/args.js";
 import { today } from "../lib/dates.js";
@@ -11,6 +14,7 @@ import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { projectName } from "../lib/project.js";
+import { applySkillExport } from "../lib/skill-export.js";
 
 // `doctrina adapter` — add, remove, and inventory agent adapters (audit
 // item C1).
@@ -109,6 +113,21 @@ function adapterAdd(projectRoot, name, cmdFlags) {
   let skipped = 0;
   for (const file of spec.files) {
     const dest = path.join(projectRoot, file.relativePath);
+    // A shared settings file is merged, never overwritten nor skipped
+    // (change 0211): the user's own keys stay, ours are added once.
+    if (isMergedConfig(file) && exists(dest)) {
+      const merged = mergeInto(dest, renderAdapterFile(file, tokens));
+      if (merged === null) {
+        console.log(c.yellow("skip   ") + ` ${file.relativePath} (not valid JSON — add the entries by hand)`);
+        skipped += 1;
+      } else if (merged) {
+        console.log(c.green("merged ") + ` ${file.relativePath}`);
+        written += 1;
+      } else {
+        console.log(c.gray("ok     ") + ` ${file.relativePath} (already holds the doctrina entries)`);
+      }
+      continue;
+    }
     if (exists(dest) && !force) {
       console.log(c.yellow("skip   ") + ` ${file.relativePath} (already present; --force overwrites)`);
       skipped += 1;
@@ -120,10 +139,24 @@ function adapterAdd(projectRoot, name, cmdFlags) {
     written += 1;
   }
 
+  // An adapter installed before its files moved (change 0238): the copies
+  // the CLI wrote under the old paths go, an edited one stays and is named.
+  const filesRoot = shadowRootOf(projectRoot) ?? projectRoot;
+  const moves = planAdapterMigration(projectRoot, tokens, filesRoot);
+  const gone = applyAdapterMigration(filesRoot, moves);
+  relinkShadow(projectRoot, gone);
+  for (const g of gone) console.log(c.green("removed") + ` ${g.rel} (replaced by its skill)`);
+  for (const rel of moves.kept) console.log(c.yellow("kept   ") + ` ${rel} (edited since install — Cursor now reads the skill; remove it once your edits are moved)`);
   console.log("");
   console.log(`${c.bold("Adapter " + name)} — ${written} file${written === 1 ? "" : "s"} written` +
     (skipped > 0 ? `, ${skipped} left alone` : "") +
     (spec.source === "project" ? c.gray(" (from .doctrina/templates/adapters/)") : ""));
+  // The project's skills follow the agent in (change 0212): with the claude
+  // adapter, `.claude/skills/` becomes an export root.
+  const exported = applySkillExport(projectRoot);
+  if (exported.writes.length > 0) {
+    console.log(c.green("export ") + ` ${exported.writes.length} skill file${exported.writes.length === 1 ? "" : "s"} where the agent discovers skills`);
+  }
   console.log(c.gray("Additive only: AGENTS.md and .doctrina/product.md were not touched."));
   return 0;
 }
@@ -156,6 +189,29 @@ function adapterRemove(projectRoot, name, cmdFlags) {
   for (const file of spec.files) {
     const dest = path.join(projectRoot, file.relativePath);
     if (!isFile(dest)) continue;
+    // A shared settings file loses only the entries this adapter added;
+    // the file goes only when nothing of the user's is left in it.
+    if (isMergedConfig(file)) {
+      const left = unmergeFrom(dest, renderAdapterFile(file, tokens));
+      if (left === undefined) {
+        console.log(c.yellow("kept   ") + ` ${file.relativePath} (not valid JSON — remove the doctrina entries by hand)`);
+        kept += 1;
+        continue;
+      }
+      if (left === UNTOUCHED) {
+        console.log(c.gray("kept   ") + ` ${file.relativePath} (holds no doctrina entries — yours)`);
+        continue;
+      }
+      if (left !== null) {
+        console.log(c.green("updated") + ` ${file.relativePath} (doctrina entries removed; yours kept)`);
+        continue;
+      }
+      remove(dest);
+      console.log(c.green("removed") + ` ${file.relativePath}`);
+      removed += 1;
+      vacated.add(path.dirname(dest));
+      continue;
+    }
     const pristine = normalise(read(dest)) === normalise(renderAdapterFile(file, tokens));
     if (!pristine && !force) {
       console.log(c.yellow("kept   ") + ` ${file.relativePath} (edited since install; --force removes it)`);
@@ -191,6 +247,34 @@ function adapterRemove(projectRoot, name, cmdFlags) {
   return 0;
 }
 
+// Merge the rendered template into an existing JSON file. Returns true when
+// the file changed, false when it already held every entry, null when the
+// file is not JSON this command can safely rewrite.
+function mergeInto(dest, rendered) {
+  let theirs;
+  try { theirs = JSON.parse(read(dest)); } catch { return null; }
+  const ours = JSON.parse(rendered);
+  if (containsJson(theirs, ours)) return false;
+  write(dest, JSON.stringify(mergeJson(theirs, ours), null, 2) + "\n", { force: true });
+  return true;
+}
+
+const UNTOUCHED = Symbol("untouched");
+
+// Take the rendered template's entries back out of a JSON file. Returns what
+// is left (written back), null when nothing is (the caller removes the
+// file), undefined when the file is not JSON.
+function unmergeFrom(dest, rendered) {
+  let theirs;
+  try { theirs = JSON.parse(read(dest)); } catch { return undefined; }
+  // A file holding none of our entries was never ours, or was rewritten by
+  // the user since: it is theirs, and stays as it is.
+  if (!holdsAnyOf(theirs, JSON.parse(rendered))) return UNTOUCHED;
+  const left = unmergeJson(theirs, JSON.parse(rendered));
+  if (left !== null) write(dest, JSON.stringify(left, null, 2) + "\n", { force: true });
+  return left;
+}
+
 function normalise(text) {
   return text.replace(/\r\n/g, "\n").trim();
 }

package/src/commands/analyze.js

@@ -1,7 +1,9 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { isDir, relPath } from "../lib/fs-ops.js";
+import { isDir, isFile, read, relPath } from "../lib/fs-ops.js";
+import { listHeader } from "../lib/scan.js";
+import { stripAnsi } from "../lib/json-out.js";
 import { c } from "../lib/colors.js";
 import { collectAnalysis } from "../lib/analysis.js";
 import { EXIT } from "../lib/exit-codes.js";
@@ -40,13 +42,22 @@ export async function run(positional, _flags) {
   console.log(`analyzing ${relPath(projectRoot, changeDir)}/`);
   console.log("");
 
-  const results = collectAnalysis(projectRoot, changeDir);
+  // An APPLIED change is asked only what still means something (change
+  // 0221): its pre-apply checks read the spec the apply wrote as a conflict,
+  // and a close stopped after its apply could never be rerun. The integrity
+  // checks — the set `archive` asks — still count.
+  const proposal = path.join(changeDir, "proposal.md");
+  const applied = isFile(proposal) && (listHeader(read(proposal), "Status") ?? "").toLowerCase() === "applied";
+  const results = collectAnalysis(projectRoot, changeDir)
+    .map((r) => applied && r.kind === "fail" && r.scope === "pre-apply"
+      ? { ...r, kind: "info", line: c.gray("- " + stripAnsi(r.line).replace(/^✗\s*/, "") + " (already applied — a pre-apply check, not asked again)") }
+      : r);
   for (const r of results) console.log(r.line);
   console.log("");
 
   const failed = results.filter((r) => r.kind === "fail").length;
   if (failed === 0) {
-    console.log(c.green("ok") + ` ready to apply`);
+    console.log(c.green("ok") + (applied ? " already applied — resuming: the integrity checks pass" : ` ready to apply`));
   } else {
     console.log(c.red("fail") + ` ${failed} issue${failed === 1 ? "" : "s"}`);
   }

package/src/commands/change.js

@@ -2,26 +2,28 @@
 import { parseChecklist, getSection, getHeader, parseChangeTitle } from "../lib/doc-model.js";
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, isFile, lineCount, mkdirp, move, read, relPath, remove, walk, write } from "../lib/fs-ops.js";
+import { eolOf, exists, isDir, isFile, lineCount, mkdirp, move, read, relPath, remove, walk, withEol, 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 { archivedChangeEntry, deriveIndex } from "../lib/scan.js";
+import { archivedChangeEntry, deriveIndex, listHeader } from "../lib/scan.js";
 import { extractOps, applyOps } from "../lib/spec-ops.js";
 import { printAdrCheckpoint } from "../lib/adr-guard.js";
 import { GATES, TRANSITIONS, checkTransition, recordForcedGap } from "../lib/gates.js";
 import { today } from "../lib/dates.js";
-import { flagBool, flagString } from "../lib/args.js";
+import { flagAll, flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { appendLedgerLine, archivedLine, abandonedLine } from "../lib/ledger.js";
 import { suggest } from "../lib/suggest.js";
 import { confirm, isInteractive } from "../lib/prompt.js";
+import { taskCard } from "../lib/task-card.js";
 import { EXIT } from "../lib/exit-codes.js";
 import { ensureDoctrinaProject, refuseChangeRef } from "../lib/project.js";
 import { parseOperation, parseCapabilityFromDelta, isUntouchedScaffold } from "../lib/doc-model.js";
 import { changeNew, addDeltaOps } from "../lib/change-ops.js";
+import { scanText } from "../lib/clarify-scan.js";
 
-const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "abandon", "delta"];
+const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "abandon", "delta", "card"];
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
@@ -46,6 +48,8 @@ export async function run(positional, flags) {
       return await changeAbandon(positional.slice(1), flags);
     case "delta":
       return changeDelta(positional.slice(1), flags);
+    case "card":
+      return changeCard(positional.slice(1));
     default:
       console.error(c.red("error:") + ` unknown change subcommand "${sub ?? ""}"`);
       const guess = suggest(sub, SUBCOMMANDS);
@@ -56,6 +60,82 @@ export async function run(positional, flags) {
   }
 }
 
+// `change card <id> [<n>]` (change 0222, ADR 0030): one task as an executor
+// receives it — the task and the lines under it, the change's why, the spec
+// cut to the task, and what to do when done. The executor does not see the
+// planner's conversation; the card is its whole context.
+function changeCard(args) {
+  const id = args[0];
+  if (!id) {
+    console.error(c.red("error:") + " change card requires <id> [task number]");
+    return EXIT.USAGE;
+  }
+  const refused = refuseChangeRef(id);
+  if (refused !== null) return refused;
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  if (!isDir(path.join(projectRoot, ".doctrina", "changes", id))) {
+    console.error(c.red("error:") + ` change "${id}" not found at .doctrina/changes/${id}`);
+    return EXIT.USAGE;
+  }
+  let ordinal = null;
+  if (args[1] !== undefined) {
+    ordinal = Number(args[1]);
+    if (!Number.isInteger(ordinal) || ordinal < 1) {
+      console.error(c.red("error:") + ` task number must be a positive integer (got "${args[1]}")`);
+      return EXIT.USAGE;
+    }
+  }
+  const { card, reason } = taskCard(projectRoot, id, ordinal);
+  if (!card) {
+    console.log(c.gray(reason));
+    return reason.startsWith("every task") ? EXIT.OK : EXIT.PRECONDITION;
+  }
+  const L = [];
+  L.push(`# Task card — ${card.change}, task ${card.ordinal} of ${card.total}` + (card.checked ? " (already ticked)" : ""));
+  L.push("");
+  L.push(`Change: ${card.title}` + (card.delivery ? ` · delivery ${card.delivery}` : ""));
+  L.push(`Repository: ${projectRoot}`);
+  L.push("");
+  L.push("## Task");
+  L.push("");
+  L.push(card.text);
+  for (const d of card.details) L.push(`- ${d}`);
+  if (card.why) {
+    L.push("", "## Why the change exists", "", card.why);
+  }
+  if (card.story) {
+    L.push("", `## The story (delivery ${card.delivery})`, "", card.story);
+  }
+  // What the change does to the spec — the requirement the card implements
+  // is here, not in the spec as it stands (change 0231).
+  if (card.changes.length > 0) {
+    L.push("", "## What this change does to the spec", "");
+    for (const ch of card.changes) L.push(`- ${ch.capability} ${ch.line}`);
+  }
+  for (const s of card.slices) {
+    L.push("", `## Spec — ${s.capability} as it stands (${s.whole ? "whole: nothing in it matched the task" : "cut to this task"})`, "", s.text.trim());
+  }
+  if (card.decisions.list.length > 0) {
+    L.push("", "## Decisions that bind it", "");
+    for (const d of card.decisions.list) {
+      L.push(`- ADR ${d.id} — ${d.title} (\`doctrina show ${d.id}\`)`);
+      if (d.decision) L.push(`  ${d.decision}`);
+    }
+    if (card.decisions.more > 0) L.push(`- … and ${card.decisions.more} more accepted global decisions — \`doctrina prime --rules\``);
+    L.push("", "Where the story or the task contradicts one of these, stop and report it: the decision stands until the planner supersedes it.");
+  }
+  L.push("", "## When done", "");
+  L.push(card.fields.verify
+    ? `1. Run the card's check: \`${card.fields.verify}\` — it must pass.`
+    : "1. Run the project's check: `doctrina verify` — it must pass.");
+  L.push(`2. Tick the box: \`doctrina change tick ${card.change} ${card.ordinal}\`.`);
+  L.push("3. Report back: the files you changed, the commands you ran and what they printed.");
+  L.push("Stay inside this card: do not open, close or archive a change, and do not edit `.doctrina/` — the planner does.");
+  for (const line of L) console.log(line);
+  return EXIT.OK;
+}
+
 // Enforce a lifecycle transition's preconditions from the shared gate map.
 // One implementation, so every driver of a transition refuses — and
 // explains, and forces — identically (C6).
@@ -153,9 +233,6 @@ function changeApply(args, flags) {
   // and exit 0 — through the very analyze → apply path the docs prescribe.
   // The preconditions now come from the shared map, so what guards a
   // transition does not depend on which command drove it.
-  const applyGate = enforceTransition(projectRoot, id, changeDir, "apply", flags);
-  if (!applyGate.ok) return 1;
-
   // Applying twice is silent corruption. The ops verbs are ADDITIVE —
   // `append-requirement` appends, `bump-version` bumps — so a second pass
   // duplicates every requirement and criterion the delta carries and bumps
@@ -173,6 +250,12 @@ function changeApply(args, flags) {
     return 0;
   }
 
+  // The skip above comes FIRST (change 0221): the apply gate is a pre-apply
+  // question, and on an applied change its ADDED check reads the content the
+  // apply wrote as a conflict — which refused the resume of a killed close.
+  const applyGate = enforceTransition(projectRoot, id, changeDir, "apply", flags);
+  if (!applyGate.ok) return 1;
+
   const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
   const date = today();
   let errors = 0;
@@ -353,6 +436,13 @@ async function changeCheck(id, { verbose = false } = {}) {
       opsFindings += 1;
     } else {
       console.log(c.green("✓ ") + `${rel}: ${result.applied.length} op${result.applied.length === 1 ? "" : "s"} would apply cleanly`);
+      // What clarify will say about the spec once this lands (change 0232):
+      // the smells the merged spec has and the current one does not.
+      // Advisory — clarify is not a close gate — but a project that runs
+      // `clarify --all` in its build learned about the word mid-close.
+      for (const smell of newSmells(read(targetPath), result.text, projectRoot)) {
+        console.log(c.yellow("! ") + `${rel}: writes ${smell.rule} "${smell.token}" into ${capability}'s spec — ${smell.hint} (\`clarify\` flags it after apply)`);
+      }
     }
   }
   if (deltaFiles.length === 0) console.log(c.gray("- no spec deltas"));
@@ -420,14 +510,17 @@ function changeDelta(args, flags) {
   }
   // In the order a reader expects them: requirement, criterion, any raw op,
   // and the bump last.
+  // `--requirement`, `--criterion` and `--op` repeat (change 0228): each
+  // occurrence is one op, in the order given. The parser keeps the last
+  // value of a repeated flag, so reading them with flagString wrote one op
+  // and reported success for a command line that asked for three.
   const lines = [];
-  const requirement = flagString(flags, "requirement");
-  const criterion = flagString(flags, "criterion");
-  const raw = flagString(flags, "op") ?? (rest.length > 0 ? rest.join(" ") : undefined);
+  const raw = flagAll(flags, "op");
+  if (raw.length === 0 && rest.length > 0) raw.push(rest.join(" "));
   const bump = flagString(flags, "bump");
-  if (requirement) lines.push(`append-requirement ${requirement}`);
-  if (criterion) lines.push(`append-criterion ${criterion}`);
-  if (raw) lines.push(raw);
+  for (const r of flagAll(flags, "requirement")) lines.push(`append-requirement ${r}`);
+  for (const r of flagAll(flags, "criterion")) lines.push(`append-criterion ${r}`);
+  lines.push(...raw);
   if (bump) lines.push(`bump-version ${bump}`);
 
   const r = addDeltaOps(projectRoot, id, capability, lines);
@@ -550,11 +643,12 @@ function changeTick(args, flags) {
     byPath.get(box.file.path).push(box);
   }
   for (const [filePath, hits] of byPath) {
-    const lines = read(filePath).split(/\r?\n/);
+    const before = read(filePath);
+    const lines = before.split(/\r?\n/);
     for (const box of hits) {
       lines[box.lineIndex] = lines[box.lineIndex].replace(/\[ \]/, "[x]");
     }
-    write(filePath, lines.join("\n"), { force: true });
+    write(filePath, withEol(lines.join("\n"), eolOf(before)), { force: true });
   }
   console.log(c.green("ticked ") + `${picked.length} box${picked.length === 1 ? "" : "es"} in ${byPath.size} file${byPath.size === 1 ? "" : "s"}`);
   return 0;
@@ -707,13 +801,22 @@ async function changeAbandon(args, flags) {
 
   const reason = flagString(flags, "reason") ?? "";
   const date = today();
+  // The delivery it belonged to stays on record (third audit, change 0234):
+  // the proposal that carried it is deleted, and the delivery's status went
+  // back to "no change yet", as if the planner had never decided anything.
+  const proposalFile = path.join(changeDir, "proposal.md");
+  const delivery = isFile(proposalFile) ? (listHeader(read(proposalFile), "Delivery") ?? "").trim() : "";
+  const recorded = delivery ? `${reason ? `${reason} ` : ""}(delivery ${delivery})` : reason;
 
   remove(changeDir);
   console.log(c.green("removed") + ` ${relPath(projectRoot, changeDir)}`);
 
   // Ledger line so the abandonment is part of the visible history.
-  const ledgerFile = appendLedgerLine(projectRoot, abandonedLine(id, reason, date));
+  const ledgerFile = appendLedgerLine(projectRoot, abandonedLine(id, recorded, date));
   console.log(c.green("ledger") + ` +1 line in ${relPath(projectRoot, ledgerFile)}`);
+  if (delivery) {
+    console.log(c.gray("hint: ") + `it was this repository's part of delivery ${delivery} — from the workspace, re-route the delivery without this repository (\`doctrina delivery route ${delivery} <the others>\`) or open a new change here with \`doctrina work "<title>" --delivery ${delivery}\``);
+  }
 
   // Drop the change entry; rebuild from the tree so nothing drifts.
   const current = idx.load(projectRoot);
@@ -766,6 +869,26 @@ export function printDeltaPreview(projectRoot, changeDir, deltaFiles) {
         continue;
       }
       console.log(c.yellow("MODIFIED") + ` ${targetRel}`);
+      // A delta with an ops block is previewed as the spec it produces (change
+      // 0228): the ops run in memory, as apply runs them, and the diff is the
+      // spec before against the spec after. Diffing the spec against the
+      // delta FILE printed every line of the spec as a '-' — three hundred
+      // lines of noise around the four that change.
+      const ops = extractOps(text);
+      if (ops.length > 0) {
+        const current = read(targetPath);
+        const after = applyOps(current, ops);
+        if (after.errors.length > 0) {
+          for (const e of after.errors) console.error(c.red("error:") + ` ${rel}: ${e}`);
+          errors += 1;
+          continue;
+        }
+        console.log(formatUnified(diffLines(current, after.text), {
+          aLabel: targetRel,
+          bLabel: `${targetRel} (after apply)`,
+        }));
+        continue;
+      }
       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), {
@@ -786,6 +909,22 @@ function extractDeltaBody(text) {
 }
 
 
+// The smells `after` has that `before` does not, matched by rule, token and
+// the line's own text — line numbers shift when a delta inserts a line.
+function newSmells(before, after, projectRoot) {
+  const key = (/** @type {string} */ text, /** @type {{ line: number, rule: string, token: string }} */ sm) =>
+    `${sm.rule}|${sm.token.toLowerCase()}|${text.split("\n")[sm.line - 1] ?? ""}`;
+  const seen = new Map();
+  for (const sm of scanText(before, projectRoot)) seen.set(key(before, sm), (seen.get(key(before, sm)) ?? 0) + 1);
+  const out = [];
+  for (const sm of scanText(after, projectRoot)) {
+    const k = key(after, sm);
+    if ((seen.get(k) ?? 0) > 0) seen.set(k, seen.get(k) - 1);
+    else out.push(sm);
+  }
+  return out;
+}
+
 export const help = `
 Usage: doctrina change <subcommand> [args]
 
@@ -808,6 +947,7 @@ Subcommands:
                          its target + the archive gate preview + an advisory
                          list of accepted ADRs citing the touched capabilities.
                          Everything close would refuse, listed BEFORE it runs.
+                         --verbose also prints each delta as it would land.
   tick <id> [n... |--all]  List the unchecked boxes (tasks.md + proposal
                          ## Verification) with ordinals; tick the given ones,
                          or every one with --all. No args = list only.
@@ -819,7 +959,14 @@ Subcommands:
                          capability — created from the template when absent —
                          parsed by the grammar apply reads and dry-run against
                          the spec first: nothing is written unless the whole
-                         block applies. A second --bump replaces the first.
+                         block applies. --requirement, --criterion and --op
+                         repeat, one op each, in order; a second --bump
+                         replaces the first.
+  card <id> [<n>]        Print task <n> (default: the next open one) as a
+                         self-contained card for an executor: the task and the
+                         lines indented under it (Files:, Requirement:, Verify:),
+                         the change's Why, the spec cut to the task, and the
+                         tick command. Exit 0 with a note when every task is done.
 
 apply / archive / check accept multiple ids (batch close of a backlog); the
 exit code is the worst per-id result.