doctrina-cli 0.16.0 → 0.18.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.16.0 — current release. Zero runtime dependencies
+**Status:** v0.18.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -18,59 +18,31 @@ Requires Node.js 20.12 or later.
 
 ## Commands
 
+Start with `doctrina init` in your repository, then tell your AI agent to
+read `AGENTS.md` and run `doctrina next` — it drives the rest. The
+surface, by the moment you reach for it:
+
 ```
-doctrina init                              scaffold AGENTS.md + .doctrina/ in cwd
-doctrina intake [<file>]                   store the full description + bootstrap playbook (clarification gate)
-doctrina work "<prompt>"                   brief prompt -> scaffolded change + work playbook (clarification gate)
-doctrina work --resume <id>                reprint an open change's playbook (no new change)
-doctrina work --from-diff                  backfill a spec from working-tree changes (code-first)
-doctrina work "<prompt>" --chore           spec-less chore (infra/docs/build): no spec-delta steps
-doctrina spec new <capability>             create a capability spec
-doctrina spec list                         list specs with version, status, size
-doctrina spec set <cap> [--bump ...]       edit spec headers/criterion + resync index (no lockstep)
-doctrina change new <id> "<title>"         open a change proposal
-doctrina change apply <id>                 apply spec deltas (ADDED/REMOVED auto; MODIFIED ops block applies)
-doctrina change archive <id>               archive an applied change
-doctrina change abandon <id>               delete an open change + its index entry (ledgered)
-doctrina change diff <id>                  preview spec deltas (line diff for MODIFIED)
-doctrina contract new <name>               own the integration surface (ports, env, interfaces)
-doctrina contract check                    verify port collisions, env drift, referenced specs
-doctrina decision new "<title>"            create the next sequential ADR
-doctrina decision accept <num>             flip a proposed ADR to accepted
-doctrina decision land <num> [path...]     stamp an accepted ADR as implemented (non-mutating Landed:)
-doctrina decision supersede <num> "<t>"    supersede an existing ADR
-doctrina decision list                     list ADRs with status, date, title
-doctrina skill new <name>                  scaffold an on-demand procedural-memory skill
-doctrina skill list                        list skills with descriptions (read-only)
-doctrina skill sync                        mirror skill frontmatter descriptions into index.json
-doctrina analyze <change-id>               inspect a change folder before applying
-doctrina clarify <path>                    smell-test a Markdown file for ambiguity (--all: tree)
-doctrina context [<capability>]            print the context pack in read order (--concat)
-doctrina search <term> [...]               search artifacts, grouped by category (ranked)
-doctrina validate                          schema + artifact-existence + index-drift checks (--fix rebuilds)
-doctrina coverage                          acceptance criteria with linked evidence (--strict gates; skips = conditional)
-doctrina trace                             intent provenance: product intent -> specs (--strict gates)
-doctrina verify                            run project typecheck/test/build checks (the real gate)
-doctrina verify --clean                    reproducibility lint: clean-checkout footguns (dist/codegen)
-doctrina templates list                    enumerate shipped templates
-doctrina templates check                   compare project against recommended template shape
-doctrina templates update                  additive fixer for check findings (preview; --write applies)
-doctrina hooks install                     install pre-commit hook
-doctrina index rebuild                     regenerate index.json from the files (--check for CI)
-doctrina next                              print the recommended next workflow actions
-doctrina metrics                           local git-derived adoption metrics (no network)
-doctrina --help | -h                       print the command surface
-doctrina --version | -v                    print the package version
+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
+            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
+Maintain    upgrade · index rebuild · hooks install · watch · metrics · completion · ci · templates list
 ```
 
-Per-command help is available with `doctrina <command> --help`.
+`doctrina --help` prints the same grouping with one line per command, and
+`doctrina <command> --help` the flags of each. Every command, flag and exit
+code is in the
+[CLI reference](https://github.com/GCarin1/Doctrina/blob/main/docs/en/cli-reference.md).
 
 ## `init` flags
 
 | Flag | Purpose |
 |------|---------|
 | `--project-name <name>` | Override the project name (defaults to cwd basename) |
-| `--project-description <text>` | One-sentence description (prompted if omitted) |
+| `--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` |
 | `--date <YYYY-MM-DD>` | Override the system date in artifacts |
 | `--force` | Overwrite existing files |
@@ -100,43 +72,29 @@ For each spec delta found under `.doctrina/changes/<id>/specs/`:
 - **REMOVED:** deletes the target spec.
 - **MODIFIED:** when the delta carries a fenced ` ```ops ` block
   (`set-header` / `bump-version` / `set-criterion` / `replace-criterion`
-  / `append-criterion`), applies it mechanically to the target spec — all
+  / `append-criterion` / `append-requirement` / `replace-requirement` /
+  `remove-requirement` / `remove-criterion`),
+  applies it mechanically to the target spec — all
   ops or none — and regenerates the index (ADR 0007). Without an ops
   block it prints a manual-merge pointer and does not write: auto-merging
   arbitrary prose is the kind of implicit decision Doctrina avoids.
 
 On any spec write, the index is rebuilt from the tree so it never drifts
-from the applied spec. `doctrina change abandon <id>` is the inverse of
+from the applied spec. `doctrina change delta <id> <capability>` writes the
+ops lines for you (`--requirement`, `--criterion`, `--bump`), dry-run
+against the spec before anything is written. `doctrina change abandon <id>` is the inverse of
 `change new`: it deletes an open change and its index entry and ledgers
-the abandonment.
+the abandonment. `doctrina close <id>` runs apply together with verify,
+coverage, archive and validate in one attested pass — the definition of
+done.
 
 ## `validate` checks
 
-1. `AGENTS.md` exists at root and is ≤ 200 lines (warns at > 150).
-2. `.doctrina/product.md` exists.
-3. `.doctrina/index.json` parses and matches the v0.1 shape.
-4. Every artifact referenced in `index.json` exists.
-5. Every ADR has a parseable `Status:` header.
-6. Every adapter template under `.doctrina/templates/adapters/` is ≤ 30 lines.
-7. Every open change has a `proposal.md`.
-8. Capability specs are ≤ 400 lines (warns above).
-9. ADRs are ≤ 300 lines (warns above).
-10. Spec/ADR files on disk are present in `index.json` (orphan warn).
-11. Markdown links inside specs/ADRs resolve to real files (stale ref warn).
-12. Skills carry the required frontmatter triple (`name`, `description`, `when`).
-13. Skills are ≤ 200 lines (warns at > 150).
-14. Each skill's `name:` matches its filename slug.
-15. Indexed artifact metadata (spec/decision/change/contract) matches its
-    file — a mismatch is an **error** so a green `validate` can't hide the
-    drift `index rebuild --check` would catch (G5; `validate --fix` rebuilds).
-16. Each skill's frontmatter description matches `index.json` (drift warn; `skill sync` fixes).
-17. EARS grammar shape per section in specs declaring `## Requirements (EARS)` (warn).
-18. Nested `AGENTS.md` files obey the root size caps (warn > 150, error > 200).
-19. No two ADR files share the same `NNNN` number (merge-collision error).
-20. `index.json` records a `framework_version` matching the running CLI
-    (stamp-divergence warn; `index rebuild` migrates it).
-21. Accepted ADRs anchor to reality via `Evidence:` and/or `Landed:`; cited
-    paths must exist on disk (drift warn).
+Structure, schema, EARS grammar, index drift, size caps, links, skills,
+ADR anchoring and more — the full, numbered list with the reason for each
+check is in the
+[CLI reference](https://github.com/GCarin1/Doctrina/blob/main/docs/en/cli-reference.md#doctrina-validate).
+A second copy here fell behind it once; there is now one list.
 
 Exit code: 0 if no errors (warnings allowed), 1 otherwise. `--fix`
 regenerates `index.json` from the tree before validating.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [
@@ -15,7 +15,7 @@
   ],
   "type": "module",
   "bin": {
-    "doctrina": "./src/index.js"
+    "doctrina": "src/index.js"
   },
   "scripts": {
     "test": "node --test",
@@ -32,7 +32,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/gcarin1/doctrina.git",
+    "url": "git+https://github.com/GCarin1/Doctrina.git",
     "directory": "packages/doctrina-cli"
   },
   "publishConfig": {

package/src/commands/adapter.js

@@ -10,6 +10,7 @@ import { today } from "../lib/dates.js";
 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";
 
 // `doctrina adapter` — add, remove, and inventory agent adapters (audit
 // item C1).
@@ -96,7 +97,7 @@ function adapterAdd(projectRoot, name, cmdFlags) {
 
   const force = flagBool(cmdFlags, "force", false);
   const tokens = {
-    PROJECT_NAME: path.basename(projectRoot),
+    PROJECT_NAME: projectName(projectRoot),
     PROJECT_DESCRIPTION: "",
     DATE: today(),
   };
@@ -145,7 +146,7 @@ function adapterRemove(projectRoot, name, cmdFlags) {
   // Only delete files this adapter created AND that still match what it
   // would write. A file the user edited is theirs now; --force overrides.
   const force = flagBool(cmdFlags, "force", false);
-  const tokens = { PROJECT_NAME: path.basename(projectRoot), PROJECT_DESCRIPTION: "", DATE: today() };
+  const tokens = { PROJECT_NAME: projectName(projectRoot), PROJECT_DESCRIPTION: "", DATE: today() };
   let removed = 0;
   let kept = 0;
   // Directories a removed file lived in, innermost first. Only these are

package/src/commands/analyze.js

@@ -5,6 +5,7 @@ import { isDir, relPath } from "../lib/fs-ops.js";
 import { c } from "../lib/colors.js";
 import { collectAnalysis } from "../lib/analysis.js";
 import { EXIT } from "../lib/exit-codes.js";
+import { ensureDoctrinaProject, refuseChangeRef } from "../lib/project.js";
 
 // The findings themselves live in lib/analysis.js, where the gate map reads
 // them; this command is their renderer (audit finding F7).
@@ -23,6 +24,13 @@ export async function run(positional, _flags) {
   }
 
   const projectRoot = process.cwd();
+  // The project first, then the reference. Asked the other way round, a
+  // directory that is not a project at all answered `change "x" not found`
+  // — which points at creating a change somewhere there is nothing to
+  // create it in.
+  ensureDoctrinaProject(projectRoot);
+  const refused = refuseChangeRef(id);
+  if (refused !== null) return refused;
   const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
   if (!isDir(changeDir)) {
     console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);

package/src/commands/change.js

@@ -6,7 +6,7 @@ import { exists, isDir, isFile, lineCount, mkdirp, move, read, relPath, remove,
 import { diffLines, formatUnified } from "../lib/diff.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
-import { deriveIndex } from "../lib/scan.js";
+import { archivedChangeEntry, deriveIndex } 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";
@@ -17,16 +17,16 @@ import { appendLedgerLine, archivedLine, abandonedLine } from "../lib/ledger.js"
 import { suggest } from "../lib/suggest.js";
 import { confirm, isInteractive } from "../lib/prompt.js";
 import { EXIT } from "../lib/exit-codes.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { ensureDoctrinaProject, refuseChangeRef } from "../lib/project.js";
 import { parseOperation, parseCapabilityFromDelta, isUntouchedScaffold } from "../lib/doc-model.js";
-import { changeNew } from "../lib/change-ops.js";
+import { changeNew, addDeltaOps } from "../lib/change-ops.js";
 
-const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "diff", "abandon"];
+const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "abandon", "delta"];
 
 // 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"] };
+export const flags = { boolean: ["json", "all", "chore", "design", "force", "no-spec", "verbose"], string: ["reason", "requirement", "criterion", "bump", "op"] };
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -42,10 +42,10 @@ export async function run(positional, flags) {
         changeCheck(id, { verbose: flagBool(flags, "verbose", false) }));
     case "tick":
       return changeTick(positional.slice(1), flags);
-    case "diff":
-      return changeDiff(positional.slice(1), flags);
     case "abandon":
       return await changeAbandon(positional.slice(1), flags);
+    case "delta":
+      return changeDelta(positional.slice(1), flags);
     default:
       console.error(c.red("error:") + ` unknown change subcommand "${sub ?? ""}"`);
       const guess = suggest(sub, SUBCOMMANDS);
@@ -100,6 +100,8 @@ async function forEachId(ids, name, one) {
   }
   let worst = 0;
   for (const id of ids) {
+    const refused = refuseChangeRef(id);
+    if (refused !== null) { worst = Math.max(worst, refused); continue; }
     if (ids.length > 1) {
       console.log("");
       console.log(c.bold(`──── change ${name} ${id}`));
@@ -108,6 +110,14 @@ async function forEachId(ids, name, one) {
     try {
       code = await one(id);
     } catch (err) {
+      // A TYPED error is a condition of the RUN, not a verdict on this id:
+      // "not a Doctrina project" is equally true of every id, and the class
+      // it carries is the whole point of the contract. Flattening it to 1
+      // here made `change apply|archive|check` answer "fix your work and
+      // retry" where `change new`, one switch arm away, answered "run the
+      // setup command first" — same condition, same sentence, two codes.
+      // The entrypoint owns the mapping and prints the remedy; let it.
+      if (err && typeof err.exitCode === "number") throw err;
       console.error(c.red("error:") + ` ${err.message}`);
       code = 1;
     }
@@ -308,7 +318,7 @@ async function changeCheck(id, { verbose = false } = {}) {
   let failures = 0;
 
   // 1. Structural analysis — same checks analyze runs before an apply.
-  console.log(c.gray("──── 1/3 structure (analyze)"));
+  console.log(c.gray("──── 1/3 structure"));
   const analyze = await import("./analyze.js");
   if ((await analyze.run([id], new Map())) !== 0) failures += 1;
 
@@ -348,7 +358,7 @@ async function changeCheck(id, { verbose = false } = {}) {
   if (deltaFiles.length === 0) console.log(c.gray("- no spec deltas"));
   if (opsFindings > 0) failures += 1;
 
-  // --verbose: the same per-delta preview `change diff` prints. The dry-run
+  // --verbose: the per-delta preview the removed `change diff` printed. The dry-run
   // above says whether the ops WOULD apply; this says what the file would
   // look like afterwards, which is the question the separate command existed
   // to answer (change 0049).
@@ -390,12 +400,57 @@ async function changeCheck(id, { verbose = false } = {}) {
 // `tick <id> --all` checks everything (tasks.md + the proposal's
 // ## Verification). Ticking is a claim of completion — the honest gate is
 // still archive/verify; this only removes the mechanical friction.
+// `change delta <id> <capability> [ops]` — write ops lines into the change's
+// MODIFIED delta through the grammar `apply` reads (change 0205). Rendering
+// only; lib/change-ops.js decides.
+function changeDelta(args, flags) {
+  const [id, capability, ...rest] = args;
+  if (!id || !capability) {
+    console.error(c.red("error:") + " change delta requires <id> <capability> and at least one operation");
+    console.error(c.gray("hint: ") + "doctrina change delta <id> <capability> --requirement \"event: When <trigger>, the system shall <action>.\" --criterion \"[unverified] <signal> — verified by `<test>`\" --bump minor");
+    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;
+  }
+  // In the order a reader expects them: requirement, criterion, any raw op,
+  // and the bump last.
+  const lines = [];
+  const requirement = flagString(flags, "requirement");
+  const criterion = flagString(flags, "criterion");
+  const raw = flagString(flags, "op") ?? (rest.length > 0 ? rest.join(" ") : undefined);
+  const bump = flagString(flags, "bump");
+  if (requirement) lines.push(`append-requirement ${requirement}`);
+  if (criterion) lines.push(`append-criterion ${criterion}`);
+  if (raw) lines.push(raw);
+  if (bump) lines.push(`bump-version ${bump}`);
+
+  const r = addDeltaOps(projectRoot, id, capability, lines);
+  if (r.code !== EXIT.OK) {
+    console.error(c.red("error:") + ` ${r.error}`);
+    for (const d of r.details ?? []) console.error(`  - ${d}`);
+    if (r.hint) console.error(c.gray("hint: ") + r.hint);
+    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`));
+  console.log(c.gray("Preview the merge: ") + c.cyan(`doctrina change check ${id} --verbose`));
+  return EXIT.OK;
+}
+
 function changeTick(args, flags) {
   const id = args[0];
   if (!id) {
     console.error(c.red("error:") + " change tick requires <id> [ordinals... | --all]");
     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);
@@ -522,7 +577,7 @@ function changeArchive(args, flags) {
 
   // Verification gate. "Done" is a claim until it is checked. Archiving is
   // the act of declaring a change finished, so it must refuse while any
-  // task (including closing steps) or any declared verification item is
+  // task or any declared verification item is
   // still unchecked. This is the difference between "boxes marked" and
   // "verification passed" the framework was faulted for collapsing.
   // Preconditions from the shared map (C6): structure AND verification.
@@ -594,14 +649,10 @@ function changeArchive(args, flags) {
   console.log(c.green("ledger") + ` +1 line in ${relPath(projectRoot, ledgerFile)}`);
 
   const index = idx.load(projectRoot);
-  idx.moveChangeToArchive(index, id, {
-    id,
-    title,
-    path: `.doctrina/changes/archive/${archiveName}`,
-    status: "applied",
-    applied: date,
-    specs_affected: specsAffected,
-  });
+  idx.moveChangeToArchive(index, id, archivedChangeEntry(
+    exists(proposal) ? read(proposal) : "",
+    { id, archiveName, applied: date, specsAffected, title },
+  ));
   idx.touch(index, date);
   idx.save(projectRoot, index);
   console.log(c.green("indexed") + " change archived");
@@ -618,6 +669,8 @@ async function changeAbandon(args, flags) {
     console.error(c.red("error:") + " change abandon requires <id>");
     return 2;
   }
+  const refused = refuseChangeRef(id);
+  if (refused !== null) return refused;
   const projectRoot = process.cwd();
   ensureDoctrinaProject(projectRoot);
 
@@ -675,9 +728,9 @@ async function changeAbandon(args, flags) {
 // ADDED reports the body it would write, REMOVED the spec it would delete,
 // MODIFIED a line diff against the current spec.
 //
-// One renderer, two callers (change 0049): `change diff` is this and nothing
-// else, and `change check --verbose` prints it after its ops dry-run — which
-// is what makes the merge honest rather than a claim. Returns the number of
+// `change check --verbose` prints this after its ops dry-run. It was also
+// the whole of `change diff`, until that alias was retired (changes 0049,
+// 0175) — the one renderer is what made the merge honest. Returns the number of
 // deltas it could not read.
 export function printDeltaPreview(projectRoot, changeDir, deltaFiles) {
   let errors = 0;
@@ -725,33 +778,6 @@ export function printDeltaPreview(projectRoot, changeDir, deltaFiles) {
   return errors;
 }
 
-function changeDiff(args, _flags) {
-  const id = args[0];
-  if (!id) {
-    console.error(c.red("error:") + " change diff requires <id>");
-    return 2;
-  }
-  const projectRoot = process.cwd();
-  ensureDoctrinaProject(projectRoot);
-
-  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
-  if (!isDir(changeDir)) {
-    console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);
-    return EXIT.USAGE;
-  }
-
-  const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
-  if (deltaFiles.length === 0) {
-    console.log(c.gray("no spec deltas in this change; nothing to diff"));
-    return 0;
-  }
-
-  const errors = printDeltaPreview(projectRoot, changeDir, deltaFiles);
-  console.log("");
-  return errors > 0 ? 1 : 0;
-}
-
-
 function extractDeltaBody(text) {
   // The delta separates headers from the spec body with a `---` line.
   const idxSep = text.indexOf("\n---\n");
@@ -760,34 +786,6 @@ function extractDeltaBody(text) {
 }
 
 
-// Reasons a change is not finished enough to archive. Counts unchecked
-// GitHub-style checkboxes (`- [ ]`) in tasks.md (every task, including the
-// closing steps) and in the proposal's "## Verification" section. Returns
-// a list of human-readable blocker strings; empty means clear to archive.
-function collectArchiveBlockers(changeDir) {
-  const blockers = [];
-  const countUnchecked = (s) => (s.match(/^\s*-\s*\[ \]/gm) ?? []).length;
-
-  const tasksPath = path.join(changeDir, "tasks.md");
-  if (exists(tasksPath)) {
-    const n = countUnchecked(read(tasksPath));
-    if (n > 0) blockers.push(`${n} unchecked task${n === 1 ? "" : "s"} in tasks.md (closing steps count)`);
-  }
-
-  const proposalPath = path.join(changeDir, "proposal.md");
-  if (exists(proposalPath)) {
-    const n = countUnchecked(getSection(read(proposalPath), "Verification"));
-    if (n > 0) blockers.push(`${n} unmet verification item${n === 1 ? "" : "s"} in proposal.md (## Verification)`);
-  }
-  return blockers;
-}
-
-function ensureDoctrinaProject(projectRoot) {
-  if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw notADoctrinaProject();
-  }
-}
-
 export const help = `
 Usage: doctrina change <subcommand> [args]
 
@@ -805,7 +803,7 @@ Subcommands:
                          MODIFIED without one prints a manual-merge pointer.
                          On any spec write the index is rebuilt from the tree.
   archive <id...>        Move the change to .doctrina/changes/archive/YYYY-MM-DD-<id>/
-  check <id...>          Pre-close dry-run, read-only: analyze's structural
+  check <id...>          Pre-close dry-run, read-only: the structural
                          checks + every ops block executed in memory against
                          its target + the archive gate preview + an advisory
                          list of accepted ADRs citing the touched capabilities.
@@ -815,8 +813,13 @@ Subcommands:
                          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 "..."]).
-  diff <id>              Preview every spec delta: line diff for MODIFIED,
-                         summary for ADDED/REMOVED. Read-only.
+  delta <id> <capability> [--requirement "<section>: <text>"] [--criterion "<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.
 
 apply / archive / check accept multiple ids (batch close of a backlog); the
 exit code is the worst per-id result.
@@ -829,9 +832,12 @@ A MODIFIED delta may carry a fenced operations block that \`apply\` executes:
   append-criterion [unverified] new signal — verified by \`test/x.test.ts\`
   append-requirement event: When <trigger>, the system shall <action>.
   replace-requirement ubiquitous 2: The system shall <action>.
+  remove-requirement state 1: superseded by event 3
+  remove-criterion 4: proven by criterion 2 since 0.9
   \`\`\`
 append-* ops resolve numbering/position at apply time, so concurrent open
-changes appending to the same spec cannot collide.
+changes appending to the same spec cannot collide. \`change delta\` writes
+these lines for you, one call per addition.
 
 Options:
   --force                Overwrite existing files (where applicable)

package/src/commands/clarify.js

@@ -37,7 +37,14 @@ const RULES_EN = [
     // hid the one real finding among them ("name some of them", which said
     // nothing about how many). A gate that cries wolf teaches people to
     // ignore it.
-    re: /(?<!\bhow\s+)\b(many|few|some|several)\b(?!\s+\d)/gi,
+    //
+    // The quality adjectives sit here for the same reason the quantifiers do:
+    // "robust" names no threshold, so it cannot be met or missed. They were
+    // in the Portuguese lexicon and nowhere in this one, so the SAME sentence
+    // translated came back with three smells in one language and none in the
+    // other — and this project keeps its own pages in both. A smell test that
+    // answers differently per language is not testing the writing.
+    re: /(?<!\bhow\s+)\b(many|few|some|several|adequate|robust|scalable)\b(?!\s+\d)/gi,
     hint: "quantify (use a number or a precise scope)",
   },
   {