doctrina-cli 0.20.0 → 0.22.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.20.0 — current release. Zero runtime dependencies
+**Status:** v0.22.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -23,14 +23,14 @@ read `AGENTS.md` and run `doctrina next` — it drives the rest. The
 surface, by the moment you reach for it:
 
 ```
-Bootstrap   init · intake · adapter list|add|remove
+Bootstrap   init · ui · onboard · 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|card
+Change      triage · work · spec new|list|set · change new|apply|archive|check|tick|abandon|renumber|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|check|close
-Maintain    upgrade · index rebuild · hooks install · watch · metrics · completion · ci · templates list
+Orchestrate workspace init|add|attach|detach|list|tool|guard · delivery new|route|list|status|tick|check|close
+Maintain    upgrade · index rebuild|merge · hooks install · watch · metrics · completion · ci · templates list
 ```
 
 `doctrina --help` prints the same grouping with one line per command, and
@@ -44,7 +44,7 @@ code is in the
 |------|---------|
 | `--project-name <name>` | Override the project name (defaults to cwd basename) |
 | `--project-description <text>` | One-sentence description, with no intake. Without it on a terminal, `init` asks you to describe the project once and keeps the answer as the intake |
-| `--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` |
+| `--agent <name>` | Install the adapter for one of the 13 supported agents (`claude`, `codex`, `cursor`, `copilot`, `gemini`, `aider`, `windsurf`, `continue`, `amp`, `devin`, `factory`, `jules`, `kiro`) 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 |
@@ -57,7 +57,7 @@ code is in the
   `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
+- `--agent codex` (and `amp`, `devin`, `factory`, `jules`, `kiro`) installs
   nothing: these agents read `AGENTS.md` natively.
 - `--agent all` installs every adapter.
 

package/package.json

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

package/src/commands/adapter.js

@@ -2,6 +2,8 @@
 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,
@@ -137,6 +139,14 @@ 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` : "") +

package/src/commands/change.js

@@ -2,16 +2,16 @@
 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";
@@ -19,15 +19,19 @@ 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 { renumberChange } from "../lib/change-numbers.js";
+import { appliedDeltas, deltaFingerprint, deltaKey, pendingOps, recordAppliedDeltas } from "../lib/applied-deltas.js";
 import { parseOperation, parseCapabilityFromDelta, isUntouchedScaffold } from "../lib/doc-model.js";
 import { changeNew, addDeltaOps } from "../lib/change-ops.js";
+import { propertyShape } from "../lib/properties.js";
+import { scanText } from "../lib/clarify-scan.js";
 
-const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "abandon", "delta", "card"];
+const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "abandon", "renumber", "delta", "card"];
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
 // let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json", "all", "chore", "design", "force", "no-spec", "verbose"], string: ["reason", "requirement", "criterion", "bump", "op"] };
+export const flags = { boolean: ["json", "all", "chore", "design", "force", "no-spec", "verbose"], string: ["reason", "requirement", "criterion", "property", "bump", "op"] };
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -45,6 +49,8 @@ export async function run(positional, flags) {
       return changeTick(positional.slice(1), flags);
     case "abandon":
       return await changeAbandon(positional.slice(1), flags);
+    case "renumber":
+      return changeRenumber(positional.slice(1));
     case "delta":
       return changeDelta(positional.slice(1), flags);
     case "card":
@@ -88,7 +94,7 @@ function changeCard(args) {
   const { card, reason } = taskCard(projectRoot, id, ordinal);
   if (!card) {
     console.log(c.gray(reason));
-    return reason.startsWith("every task") ? EXIT.OK : EXIT.PRECONDITION;
+    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)" : ""));
@@ -103,8 +109,26 @@ function changeCard(args) {
   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} (cut to this task)`, "", s.text.trim());
+    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
@@ -223,21 +247,53 @@ function changeApply(args, flags) {
   const proposalPath = path.join(changeDir, "proposal.md");
   const alreadyApplied = isFile(proposalPath)
     && (getHeader(read(proposalPath), "Status") ?? "").trim().toLowerCase() === "applied";
+  const allDeltas = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
+  // WHICH deltas the stamp covers (change 0247). The stamp is the change's,
+  // and a change is not finished when it is stamped: a close that applied
+  // and then stopped at a later gate leaves it `applied`, and the fix for
+  // that gate is often one more delta. The stamp said "nothing to do", the
+  // close went on, and the change was archived naming a spec it had never
+  // touched. The record names each delta that was applied, with what it held.
+  /** @type {Map<string, Set<number> | null> | null} delta → the ops still to apply (null: the whole delta) */
+  let lateOnly = null;
   if (alreadyApplied && !flagBool(flags, "force", false)) {
-    console.log(c.gray("skip ") + `change "${id}" is already applied — nothing to do`);
-    console.log(c.gray("The ops verbs are additive: applying twice duplicates every"));
-    console.log(c.gray("requirement this delta carries. Re-apply anyway with --force"));
-    console.log(c.gray("only after reverting the specs to their pre-apply state."));
-    return 0;
+    const record = appliedDeltas(read(proposalPath));
+    const late = new Map();
+    const edited = [];
+    for (const p of record ? allDeltas : []) {
+      const recorded = record?.get(deltaKey(changeDir, p));
+      if (!recorded) {
+        late.set(p, null);
+        continue;
+      }
+      const { fresh, gone } = pendingOps(recorded, deltaFingerprint(read(p)));
+      if (gone) edited.push(p);
+      else if (fresh.length > 0) late.set(p, new Set(fresh));
+    }
+    if (edited.length > 0) {
+      console.error(c.red("error:") + ` ${edited.map((p) => relPath(changeDir, p)).join(", ")}: an op that was already applied changed or was removed — the spec holds what it wrote, and applying the delta again would add to that, not replace it`);
+      console.error(c.gray("hint: ") + "restore the op as it was applied and add the correction as a new op (`replace-requirement`, `replace-criterion`, `doctrina change delta`), or revert the spec to its pre-apply state and run `doctrina change apply " + id + " --force`");
+      return 1;
+    }
+    if (late.size === 0) {
+      console.log(c.gray("skip ") + `change "${id}" is already applied — nothing to do`);
+      console.log(c.gray("The ops verbs are additive: applying twice duplicates every"));
+      console.log(c.gray("requirement this delta carries. Re-apply anyway with --force"));
+      console.log(c.gray("only after reverting the specs to their pre-apply state."));
+      return 0;
+    }
+    const what = [...late].map(([p, ops]) => `${relPath(changeDir, p)}${ops ? ` (${ops.size} new op${ops.size === 1 ? "" : "s"})` : ""}`).join(", ");
+    console.log(c.gray("note: ") + `change "${id}" was applied before this was added — applying only ${what}`);
+    lateOnly = late;
   }
 
   // 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);
+  const applyGate = lateOnly ? { ok: true, forced: null } : 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 deltaFiles = lateOnly ? [...lateOnly.keys()] : allDeltas;
   const date = today();
   let errors = 0;
   let writes = 0;
@@ -291,7 +347,8 @@ function changeApply(args, flags) {
       // `ops` block (set-header / bump-version / set-criterion / ...; F3);
       // otherwise it falls back to the historical manual-merge pointer, so
       // prose deltas keep working unchanged.
-      const ops = extractOps(text);
+      const only = lateOnly?.get(deltaPath) ?? null;
+      const ops = extractOps(text).filter((_op, i) => only === null || only.has(i));
       if (ops.length === 0) {
         console.log(c.yellow("manual[MODIFIED]") + ` merge ${relPath(projectRoot, deltaPath)} into ${relPath(projectRoot, targetPath)} by hand (no ops block)`);
         manual += 1;
@@ -334,6 +391,10 @@ function changeApply(args, flags) {
         console.log(c.green("status") + " proposal.md → applied");
         flippedToApplied = true;
       }
+      // Every delta the proposal's stamp now covers, with what it held.
+      const stamped = read(proposalPath);
+      const withRecord = recordAppliedDeltas(stamped, allDeltas.map((p) => [deltaKey(changeDir, p), deltaFingerprint(read(p))]));
+      if (withRecord !== stamped) write(proposalPath, withRecord, { force: true });
     }
   }
 
@@ -417,6 +478,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"));
@@ -484,14 +552,20 @@ 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}`);
+  // A criterion that claims something of every input (change 0254): the
+  // mark is what makes coverage ask the cited test to be a property.
+  for (const r of flagAll(flags, "property")) lines.push(`append-criterion [property] ${r.replace(/^\[property\]\s*/i, "")}`);
+  lines.push(...raw);
   if (bump) lines.push(`bump-version ${bump}`);
 
   const r = addDeltaOps(projectRoot, id, capability, lines);
@@ -502,7 +576,23 @@ function changeDelta(args, flags) {
     return r.code;
   }
   console.log(c.green(r.created ? "created" : "updated") + ` ${r.deltaRel}` +
-    c.gray(` — ${lines.length} op${lines.length === 1 ? "" : "s"} added; the block now holds ${r.block.length} (${r.block.join(", ")}), and applies cleanly`));
+    c.gray(` — ${lines.length} op${lines.length === 1 ? "" : "s"} added; the block now holds ${(r.block ?? []).length} (${(r.block ?? []).join(", ")}), and applies cleanly`));
+  // The moment the requirement is written is the moment its proof is
+  // chosen (change 0254): one that claims something of every input is told
+  // so here, while the test for it does not exist yet.
+  if (flagAll(flags, "property").length === 0) {
+    let noted = 0;
+    for (const req of flagAll(flags, "requirement")) {
+      const shape = propertyShape(req.replace(/^[a-z-]+:\s*/i, ""));
+      if (!shape) continue;
+      noted++;
+      console.log(c.yellow("note: ") + `"${req.length > 70 ? req.slice(0, 69) + "…" : req}" reads as ${shape.id === "invariant" ? "an invariant" : shape.id} — ${shape.property}.`);
+    }
+    if (noted > 0) {
+      console.log(c.gray("  An example test proves the cases somebody thought of. If a failure here would be a bug, write a property test and claim it: ") +
+        c.cyan(`doctrina change delta ${id} ${capability} --property "<what holds for every input> — verified by \`<the property test>\`"`));
+    }
+  }
   console.log(c.gray("Preview the merge: ") + c.cyan(`doctrina change check ${id} --verbose`));
   return EXIT.OK;
 }
@@ -614,11 +704,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;
@@ -771,13 +862,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);
@@ -788,6 +888,34 @@ async function changeAbandon(args, flags) {
   return 0;
 }
 
+// Give an open change the next free number (change 0242): two branches that
+// each opened a change took the same one, and the merge holds both.
+function changeRenumber(args) {
+  const id = args[0];
+  if (!id) {
+    console.error(c.red("error:") + " change renumber requires <id>");
+    return 2;
+  }
+  const refused = refuseChangeRef(id);
+  if (refused !== null) return refused;
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+  if (!isDir(changeDir)) {
+    console.error(c.red("error:") + ` change "${id}" is not an open change (${relPath(projectRoot, changeDir)} not found) — an archived change keeps its number`);
+    return EXIT.USAGE;
+  }
+  const { to, rewritten } = renumberChange(projectRoot, id);
+  console.log(c.green("renumbered") + ` ${id} → ${to}`);
+  if (rewritten.length > 0) console.log(c.gray(`  the id was rewritten in ${rewritten.join(", ")}`));
+  const derived = deriveIndex(projectRoot, idx.load(projectRoot));
+  derived.last_updated = today();
+  idx.save(projectRoot, derived);
+  console.log(c.green("indexed") + ` change "${to}" in index.json`);
+  console.log(c.gray("next: ") + `name ${to} wherever the old number was written outside the change — a commit message, a branch, a task card already handed out`);
+  return 0;
+}
+
 // The per-delta preview: what applying this delta would do to its target.
 // ADDED reports the body it would write, REMOVED the spec it would delete,
 // MODIFIED a line diff against the current spec.
@@ -830,6 +958,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), {
@@ -850,6 +998,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]
 
@@ -872,18 +1036,29 @@ 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.
   abandon <id>           Delete an open change folder and its index entry, and
                          record the abandonment in the ledger ([--reason "..."]).
+  renumber <id>          Give an open change the next free number: the folder
+                         moves and the id is rewritten in its own files. For
+                         the merge that brought together two changes opened
+                         on two branches under one number — \`validate\` names it.
   delta <id> <capability> [--requirement "<section>: <text>"] [--criterion "<text>"]
-        [--bump major|minor|patch] [--op "<op line>" | <op line>]
+        [--property "<text>"] [--bump major|minor|patch] [--op "<op line>" | <op line>]
                          Write ops into the change's MODIFIED delta for the
                          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. --property writes a criterion
+                         marked [property]: a claim about every input, which
+                         coverage counts only when the test it cites is
+                         property-based (\`doctrina coverage --properties\`
+                         lists the requirements that read as one).
   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:),