doctrina-cli 0.16.0 → 0.18.0

package/src/lib/verify-cache.js

@@ -0,0 +1,76 @@
+// @ts-check
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { git, GIT_STATE, worktreeFingerprint } from "./git.js";
+import { cliVersion } from "./version.js";
+
+// A green verify, remembered for the exact code it ran on (change 0203).
+//
+// A field review of 0.17 put the fixed cost of a small change at the close
+// running the whole suite — 2.5 to 4 minutes — and an agent typically runs
+// `doctrina verify` itself right before `doctrina close`, so the same suite
+// ran twice on the same code. In a batch close it ran once per id, on a tree
+// whose only difference between ids was the artifacts the previous close
+// archived.
+//
+// The fingerprint is the CODE: the working tree (tracked, untracked, edits,
+// .gitignore respected) minus `.doctrina/`, plus the verify.json that
+// defines the checks and the CLI version that runs them. `.doctrina/` is
+// left out on purpose — the close's apply and archive move it between the
+// verify a person ran and the one the close would run — and the artifact
+// tree is proven by the close's own steps (coverage, trace, index drift,
+// validate), which always run.
+//
+// The record lives in the git directory, never in the tree: it is a fact
+// about this checkout, not an artifact to commit or review.
+
+const RECORD = "doctrina-verify-green.json";
+
+/**
+ * @param {string} projectRoot
+ * @param {string} configText  the verify.json the checks come from
+ * @returns {string | null}    null when git cannot fingerprint the tree
+ */
+export function verifyFingerprint(projectRoot, configText) {
+  const tree = worktreeFingerprint(projectRoot, { exclude: [".doctrina"] });
+  if (tree === null) return null;
+  return createHash("sha256").update(`${tree}\n${configText}\n${cliVersion()}`).digest("hex");
+}
+
+function recordPath(projectRoot) {
+  const dir = git(projectRoot, ["rev-parse", "--absolute-git-dir"]);
+  return dir.state === GIT_STATE.OK ? path.join(dir.stdout.trim(), RECORD) : null;
+}
+
+/**
+ * Remember that every check passed on this fingerprint.
+ * @param {string} projectRoot
+ * @param {string} fingerprint
+ * @param {string[]} checks
+ */
+export function recordGreen(projectRoot, fingerprint, checks) {
+  const file = recordPath(projectRoot);
+  if (!file) return;
+  try {
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ fingerprint, checks, at: new Date().toISOString() }, null, 2) + "\n");
+  } catch { /* a cache that cannot be written is a cache miss, never an error */ }
+}
+
+/**
+ * The last green run, when it covered exactly this fingerprint.
+ * @param {string} projectRoot
+ * @param {string} fingerprint
+ * @returns {{ fingerprint: string, checks: string[], at: string } | null}
+ */
+export function reusableGreen(projectRoot, fingerprint) {
+  const file = recordPath(projectRoot);
+  if (!file) return null;
+  try {
+    const rec = JSON.parse(readFileSync(file, "utf8"));
+    return rec && rec.fingerprint === fingerprint ? rec : null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/views.js

@@ -2,6 +2,7 @@
 import { c } from "./colors.js";
 import { today } from "./dates.js";
 import { churnByCapability } from "./ledger.js";
+import { STALE_CHANGE_DAYS } from "./snapshot.js";
 
 // Executed proof and signed proof are different claims (change 0039). One
 // phrasing, used by every view, so none of them can quietly add the two
@@ -182,7 +183,11 @@ export function prime(s) {
   } else {
     for (const ch of s.openChanges) {
       const tasks = ch.tasksTotal > 0 ? ` · tasks ${ch.tasksDone}/${ch.tasksTotal}` : "";
-      out.push(`  ${c.cyan(ch.id)}  ${ch.title ?? ""}${c.gray(` (${ch.status}${tasks})`)}`);
+      // The age, once it is news (change 0201): a change opened today and
+      // one forgotten for three weeks used to read identically.
+      const age = ch.ageDays !== null && ch.ageDays !== undefined && ch.ageDays >= STALE_CHANGE_DAYS
+        ? ` · open ${ch.ageDays}d` : "";
+      out.push(`  ${c.cyan(ch.id)}  ${ch.title ?? ""}${c.gray(` (${ch.status}${tasks}${age})`)}`);
     }
   }
 
@@ -222,6 +227,9 @@ export function handoff(s) {
     out.push("## Open work");
     out.push("");
     out.push("- none — the tree is at rest; start with `doctrina work \"<prompt>\"`");
+    // The note is pasted into another session, so the section has to END like
+    // the loop below ends: a heading glued to a list item is not a heading.
+    out.push("");
   } else {
     for (const ch of s.openChanges) {
       out.push(`## Open change \`${ch.id}\`${ch.title ? ` — ${ch.title}` : ""}`);
@@ -405,6 +413,6 @@ export function report(s, { days = 7, cutoffIso = "", git = null, gitState = nul
   }
 
   out.push("");
-  out.push(`*Generated read-only by \`doctrina report --since ${days}\`; deeper numbers: \`doctrina metrics\`.*`);
+  out.push(`*Generated read-only by \`doctrina status --view report --since ${days}\`; deeper numbers: \`doctrina metrics\`.*`);
   return out;
 }

package/src/lib/work-model.js

@@ -21,29 +21,74 @@ export function rankCapabilitiesByDiff(projectRoot, files, { limit = 3 } = {}) {
   if (!files || files.length === 0 || !isDir(specsDir)) return [];
   const norm = files.map((f) => f.replace(/\\/g, "/"));
 
-  const ranked = [];
+  const specs = [];
   for (const cap of readdirSync(specsDir).sort()) {
     const specPath = path.join(specsDir, cap, "spec.md");
     if (!isFile(specPath)) continue;
-    const specText = read(specPath);
-    // A DECLARED glob outranks every inference: the spec said this code is
-    // its own, and a declaration is not a guess (change 0077).
-    const declared = parseSourceGlobs(specText).map((g) => globToRegExp(g));
-    let score = 0;
-    for (const f of norm) {
-      if (declared.some((re) => re.test(f))) score += 10;     // the spec claims it
-      if (f.split("/").includes(cap)) score += 3;            // src/<cap>/... etc.
-      if (specText.includes(f)) score += 5;                  // file cited in the spec
-      else if (specText.includes(path.basename(f))) score += 2; // filename cited
+    const text = read(specPath);
+    specs.push({ cap, text, declared: parseSourceGlobs(text).map((g) => globToRegExp(g)) });
+  }
+
+  // Per file, the strongest answer the tree holds wins, and a weaker one is
+  // never added on top of it (change 0200, ADR 0027):
+  //   1. the specs whose `**Source:**` claims the file — a declaration;
+  //   2. else the specs citing the exact path (a proof or a pointer);
+  //   3. else the path/basename inferences, and only from specs that declare
+  //      NO Source — a spec that stated what it owns has said all it owns.
+  // The old sum added every signal from every spec, so a file claimed by
+  // `health` still "belonged" to `cloud` because cloud's spec mentioned an
+  // `index.ts`, and every close warned about a spec the change never touched.
+  const scores = new Map();
+  const add = (cap, n) => scores.set(cap, (scores.get(cap) ?? 0) + n);
+  for (const f of norm) {
+    const claimed = specs.filter((s) => s.declared.some((re) => re.test(f)));
+    if (claimed.length > 0) {
+      for (const s of claimed) add(s.cap, 10);
+      continue;
+    }
+    const citing = specs.filter((s) => s.text.includes(f));
+    if (citing.length > 0) {
+      for (const s of citing) add(s.cap, 5);
+      continue;
+    }
+    for (const s of specs) {
+      if (s.declared.length > 0) continue;
+      if (f.split("/").includes(s.cap)) add(s.cap, 3);            // src/<cap>/... etc.
+      if (s.text.includes(path.basename(f))) add(s.cap, 2);       // filename cited
     }
-    if (score > 0) ranked.push({ id: cap, score, path: `.doctrina/specs/${cap}/spec.md` });
   }
+  const ranked = [...scores].map(([id, score]) => ({ id, score, path: `.doctrina/specs/${id}/spec.md` }));
   // `limit` keeps the work-playbook hint short (top 3); review passes
   // Infinity — truncating there is how it missed 5 of 8 touched capabilities
   // in the 0.11.0 field session.
   return ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, limit);
 }
 
+/**
+ * The capabilities whose `Source:` header CLAIMS a file — ADR 0027's question
+ * asked directly, with no inference in the answer.
+ *
+ * `rankCapabilitiesByDiff` deliberately falls back to inferences so a project
+ * that has not declared anything still gets a hint. That makes it the wrong
+ * function to enforce the declaration with: a file no spec names still comes
+ * back with an owner, scored 5 instead of 10, and a test asking "does this
+ * have an owner" cannot tell the two apart. `lib/names.js` sat undeclared
+ * behind exactly that.
+ */
+export function declaredOwners(projectRoot, file) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (!isDir(specsDir)) return [];
+  const norm = String(file).replace(/\\/g, "/");
+  const owners = [];
+  for (const cap of readdirSync(specsDir).sort()) {
+    const specPath = path.join(specsDir, cap, "spec.md");
+    if (!isFile(specPath)) continue;
+    const globs = parseSourceGlobs(read(specPath)).map((g) => globToRegExp(g));
+    if (globs.some((re) => re.test(norm))) owners.push(cap);
+  }
+  return owners;
+}
+
 // Deterministic term overlap: fold prompt and spec text with the SHARED
 // lexicon, then score. This is a hint for the agent, never a decision
 // (ADR 0005).

package/templates/AGENTS.md.template

@@ -46,13 +46,12 @@ canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
 - `doctrina triage` — classify the lane (product/runtime/chore) and check the declared runtime surface. *When:* a request arrives — BEFORE scaffolding, especially if it smells like an incident.
 - `doctrina work "<prompt>" (--capability · --chore · --from-diff · --quiet)` — scaffold a change and print the playbook to execute. *When:* a request arrives that changes behaviour (triage says PRODUCT).
 - `doctrina spec new|list|set` — create, list, and edit capability specs. *When:* a capability needs creating or its headers advancing.
-- `doctrina change new|apply|archive|check|tick|abandon` — new / apply / archive / check (--verbose) / tick / abandon. *When:* driving a change through its lifecycle by hand.
+- `doctrina change new|apply|archive|check|tick|abandon|delta` — drive a change by hand — check --verbose previews every delta. *When:* driving a change through its lifecycle by hand.
 - `doctrina contract new|list|check` — own and verify the integration surface. *When:* the change touches ports, env vars, or public endpoints.
 - `doctrina decision new|accept|land|supersede|list|scope` — record, accept, land, scope, and supersede ADRs. *When:* the change decides something a later session must not relitigate.
-- `doctrina skill new|list|sync|suggest` — capture on-demand procedural memory. *When:* a lesson is worth not relearning.
+- `doctrina skill new|list|suggest` — capture on-demand procedural memory. *When:* a lesson is worth not relearning.
 - `doctrina intent add|list` — append and list product intent anchors. *When:* new product intent appears after the intake.
 **Gate**
-- `doctrina analyze` — structural pre-flight on a change folder. *When:* before applying a change.
 - `doctrina clarify --all (--lang pt|en)` — smell-test Markdown for ambiguity. *When:* before applying, or before opening a PR.
 - `doctrina validate (--fix)` — schema, structure, EARS, and index drift. *When:* after any artifact edit, and before considering work done.
 - `doctrina coverage --strict` — acceptance criteria against cited evidence. *When:* before claiming a capability is proven.
@@ -61,7 +60,7 @@ canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
 - `doctrina verify` — the project's declared typecheck/test/build checks. *When:* the real build gate must run.
 - `doctrina close <id...>` — the whole closing sequence in one attested pass. *When:* a change is implemented and ready to finish.
 - `doctrina doctor` — aggregate diagnostic with per-finding remedies. *When:* something looks wrong and you do not know which gate to ask.
-**Maintain** (triggers: `doctrina <command> --help`) — `doctrina templates list|check|update` · `doctrina hooks install` · `doctrina index rebuild` · `doctrina watch` · `doctrina metrics` · `doctrina report` · `doctrina completion` · `doctrina upgrade --write` · `doctrina ci --emit github`
+**Maintain** (triggers: `doctrina <command> --help`) — `doctrina templates list` · `doctrina hooks install` · `doctrina index rebuild` · `doctrina watch` · `doctrina metrics` · `doctrina completion` · `doctrina upgrade --write` · `doctrina ci --emit github`
 <!-- doctrina:surface:end -->
 
 ## Stack and tooling

package/templates/README.md

@@ -45,6 +45,7 @@ loops in it.
 | `{{CAPABILITY_BLOCK}}` | The pinned capability, the ranked hints, or "no match" | required in `work` |
 | `{{DIFF_MATCHES}}` | Capabilities the working tree touched | empty |
 | `{{STEP3_INTRO}}` | The delta step's opening, pinned or not | required in `work` |
+| `{{SHAPE}}` | The spec's measured size — lines, requirements per EARS subsection, criteria | required in `consolidate` |
 | `{{FROM_DIFF_DELTA_NOTE}}` | The backfill caveat on writing the delta | empty |
 | `{{MISSING_SPECS_WARNING}}` | Warning that `.doctrina/specs/` is absent | empty |
 
@@ -68,6 +69,7 @@ README.md                                  this file
 playbooks/work.md.template                 the work / backfill playbook
 playbooks/chore.md.template                the spec-less chore playbook
 playbooks/bootstrap.md.template            the intake -> specs playbook
+playbooks/consolidate.md.template          the spec consolidation playbook
 AGENTS.md.template                         root rules for the target repo
 doctrina/                                  the .doctrina/ skeleton
   product.md.template

package/templates/adapters/claude/.claude/commands/doctrina-work.md.template

@@ -9,9 +9,12 @@ Drive the Doctrina spec-driven workflow for **{{PROJECT_NAME}}**.
    (No prompt, but you already edited code? Use `doctrina work --from-diff`.)
 2. Execute the printed playbook in order: read the pack with
    `doctrina context <capability> --concat`, write the spec delta, fill
-   `tasks.md`, implement, then `doctrina analyze <id>` → `doctrina change apply <id>`.
-3. Close it: `doctrina close <id>` (verify → coverage → archive → validate) and
-   resolve every `error:` before reporting the work done.
+   `tasks.md`, implement. `doctrina change check <id>` previews everything
+   the close would refuse.
+3. Close it: `doctrina close <id>` — one attested pass over every gate. The
+   sequence is declared in one place and printed by `doctrina close --help`;
+   read it there rather than from a copy. Resolve every `error:` before
+   reporting the work done.
 
 Reach for the CLI instead of hand-authoring artifacts. Ask the human only on
 genuine ambiguity.

package/templates/adapters/cursor/.cursor/commands/doctrina-work.md.template

@@ -5,8 +5,9 @@ Turn the request into a Doctrina change and drive it through the gates.
 1. Run `doctrina work "<the request>"` (or `doctrina work --from-diff` if you
    already edited code) and follow the printed playbook.
 2. `doctrina context <capability> --concat` → write the spec delta → fill
-   `tasks.md` → implement → `doctrina analyze <id>` → `doctrina change apply <id>`.
-3. `doctrina close <id>` (verify → coverage → archive → validate); resolve
-   every `error:` before reporting the work done.
+   `tasks.md` → implement → `doctrina change check <id>` (the close's preview).
+3. `doctrina close <id>` — one attested pass over every gate; the sequence is
+   declared in one place and printed by `doctrina close --help`, so read it
+   there and not from a copy. Resolve every `error:` before reporting done.
 
 Prefer the CLI over hand-authoring artifacts. Ask only on genuine ambiguity.

package/templates/change/proposal.md.template

@@ -6,6 +6,21 @@
 - **Lane:**
 - **Affects specs:**
 
+<!--
+Optional, and usually absent. The closing docs gate reads COMMAND and FLAG
+names out of the prose below and asks for documentation when it finds any.
+It cannot tell a change from a mention: explaining an effect, or writing a
+Scope boundaries line about what this deliberately does NOT touch, names
+things just as loudly as changing them would.
+
+When that happens, say so on the record instead of forcing the close:
+
+- **Documented surface:** n/a — names two commands to explain an effect; alters neither
+
+`none` reads the same as `n/a`, and a BARE one silences nothing — the
+reason is the declaration.
+-->
+
 ## Why
 
 <!-- The user-visible or technical reason this change exists. -->

package/templates/change/spec-delta.md.template

@@ -24,6 +24,8 @@ typical delta applies mechanically end to end; only free-prose rewrites
   ```
 
 Requirement sections: ubiquitous | event | state | unwanted | optional.
+To take one out: `remove-requirement <section> <n>` / `remove-criterion <n>`
+(the criteria after it renumber; write removals highest number first).
 append-* ops resolve numbering/position at APPLY time, so several open
 changes appending to the same spec never collide on numbers — order of
 application decides.

package/templates/change/tasks.md.template

@@ -2,16 +2,11 @@
 
 <!--
 Each task is a single checkable item. Keep tasks small (under a few hours
-of work). The change is done when every box is checked, including the
-three closing steps at the bottom.
+of work). The change is done when every box is checked and
+`doctrina close {{CHANGE_ID}}` succeeds — the close applies the deltas,
+archives the change and updates the index, so those are not boxes here.
 -->
 
 - [ ]
 - [ ]
 - [ ]
-
-## Closing steps
-
-- [ ] Apply the change: merge each delta into the corresponding spec.
-- [ ] Archive the change folder to `.doctrina/changes/archive/{{DATE}}-{{CHANGE_ID}}/`.
-- [ ] Update `.doctrina/index.json` with new or modified artifacts.

package/templates/contract.md.template

@@ -107,8 +107,8 @@ Example (Behave): features/**/*.feature with pattern @([a-z0-9_-]+)
 <!--
 Ceilings that are a CONTRACT, not a preference: token limits, payload
 caps, timeouts. Direction distinguishes what goes IN from what comes
-OUT, because they fail differently — and `doctrina analyze` refuses a
-change that "fixes" an overflow by raising an OUTPUT ceiling, which
+OUT, because they fail differently — and `doctrina change check` and the
+close refuse a change that "fixes" an overflow by raising an OUTPUT ceiling, which
 buys headroom by truncating what mattered rather than sending less.
 -->
 

package/templates/hooks/pre-commit.sample

@@ -26,3 +26,13 @@ $DOCTRINA validate --fix || exit 1
 if [ -f .doctrina/index.json ]; then
   git add .doctrina/index.json
 fi
+
+# ...and then check that the index this commit carries describes THIS COMMIT.
+#
+# Everything above reads the working tree. index.json is derived from the
+# whole tree, so it cannot describe a subset of one: stage part of
+# .doctrina/ and the index that just got staged names artifacts the commit
+# does not contain. On your disk they are all still there, so `validate`,
+# `index rebuild --check` and the close all pass — and the checkout in CI
+# fails with "index.json references missing artifact".
+$DOCTRINA index rebuild --check --staged || exit 1

package/templates/playbooks/bootstrap.md.template

@@ -35,8 +35,12 @@ Execute in order, in a single linear pass:
    If something in the intake is genuinely ambiguous, ask the user
    before assuming.
 
-7. Mark the intake consumed: in .doctrina/intake.md flip
-   "- **Status:** pending" to "- **Status:** converted".
+7. Mark the intake consumed — through the CLI, not by hand:
+       [[c]]doctrina intake --converted[[/c]]
+[[g]]   `next` branches on that header and `validate` refuses any other[[/g]]
+[[g]]   value, because every word but the two declared ones used to read[[/g]]
+[[g]]   as pending in silence. It refuses while `validate` reports an[[/g]]
+[[g]]   error — the step-6 gates are what "done" means.[[/g]]
 
 8. [[c]]doctrina next[[/c]] — follow the recommendation. Implementation then
    flows through [[c]]doctrina work "<brief prompt>"[[/c]], one change at a time.

package/templates/playbooks/chore.md.template

@@ -6,14 +6,19 @@ Execute in order, in a single linear pass:
 
 1. Replace the placeholder tasks in .doctrina/changes/{{CHANGE_ID}}/tasks.md
    with small, checkable steps; implement them, checking each box.
-[[g]]   (Do it before implementing — analyze/close refuse leftover scaffold[[/g]]
+[[g]]   (Do it before implementing — the close refuses leftover scaffold[[/g]]
 [[g]]   placeholders, and `change tick` will not tick an empty box.)[[/g]]
-2. Prove it (archive refuses unchecked boxes):
+2. Prove it (the close refuses unchecked boxes):
        [[c]]doctrina verify[[/c]]     — the project's typecheck/test/build gate
        [[c]]doctrina verify --clean[[/c]] — clean-checkout reproducibility lint
    Then check the proposal's ## Verification boxes and every task.
 3. This is a chore: no spec changes. If you find yourself needing a
    spec delta, it is not a chore — reopen with [[c]]doctrina work "<prompt>"[[/c]].
-4. [[c]]doctrina change apply {{CHANGE_ID}}[[/c]]  (zero deltas → flips to applied).
-5. [[c]]doctrina change archive {{CHANGE_ID}}[[/c]], then [[c]]doctrina validate[[/c]].
+4. Close in one attested pass — the same close as any change; a chore
+   simply has no delta to apply:
+       [[c]]doctrina close {{CHANGE_ID}}[[/c]]
+[[g]]   It stops at the first failure with the exact rerun command, and the[[/g]]
+[[g]]   sequence is printed by the close itself. A chore that alters a[[/g]]
+[[g]]   documented surface still owes the docs and a changelog entry — or[[/g]]
+[[g]]   `- **Documented surface:** n/a — <why>` in the proposal.[[/g]]
 [[g]]   If this fix taught a lesson worth not relearning, capture it: [[/g]][[c]]doctrina skill new <slug>[[/c]][[g]].[[/g]]

package/templates/playbooks/consolidate.md.template

@@ -0,0 +1,28 @@
+[[b]]Consolidation playbook — change {{CHANGE_ID}}[[/b]][[g]] — agent-executed (ADR 0005); the spec shrinks, the behaviour does not change.[[/g]]
+
+Capability: [[c]]{{CAPABILITY}}[[/c]] — {{SHAPE}}
+
+Execute in order, in a single linear pass:
+
+1. Read the spec and its history:
+       [[c]]doctrina context {{CAPABILITY}} --concat[[/c]]
+       [[c]]doctrina why {{CAPABILITY}}[[/c]]
+2. Find what the spec says more than once: a requirement a later one
+   superseded, two requirements stating the same rule, a criterion proven
+   by another one, a bullet describing behaviour that no longer exists.
+   You decide; the CLI only measures. Keep every rule the code still
+   honours — consolidating removes words, never guarantees.
+3. Write the delta with the ops (the scaffold is at
+   .doctrina/changes/{{CHANGE_ID}}/specs/{{CAPABILITY}}/delta.md):
+       [[c]]doctrina change delta {{CHANGE_ID}} {{CAPABILITY}} --op "remove-requirement <section> <n>: <why>"[[/c]]
+       [[c]]doctrina change delta {{CHANGE_ID}} {{CAPABILITY}} --op "replace-requirement <section> <n>: <merged text>"[[/c]]
+       [[c]]doctrina change delta {{CHANGE_ID}} {{CAPABILITY}} --op "remove-criterion <n>: <why>"[[/c]]
+       [[c]]doctrina change delta {{CHANGE_ID}} {{CAPABILITY}} --bump minor[[/c]]
+[[g]]   Ops run in order and a removal renumbers what follows it: write the[[/g]]
+[[g]]   removals of one section highest number first. Every kept criterion[[/g]]
+[[g]]   must still cite proof that exists — coverage gates the close.[[/g]]
+[[g]]   Preview the merged spec: [[/g]][[c]]doctrina change check {{CHANGE_ID}} --verbose[[/c]]
+4. Fill the proposal's What (what was merged or removed, and why each) and
+   replace the placeholder tasks; no code changes.
+5. Close in one attested pass:
+       [[c]]doctrina close {{CHANGE_ID}}[[/c]]

package/templates/playbooks/work.md.template

@@ -40,12 +40,15 @@ Execute in order, in a single linear pass:
 [[g]]   append-* ops number/position at APPLY time, so concurrent changes[[/g]]
 [[g]]   appending to the same spec never collide. Only free-prose rewrites[[/g]]
 [[g]]   (Purpose, Maturity, ...) stay a by-hand merge.[[/g]]
+[[g]]   Or let the CLI write the lines and dry-run them against the spec:[[/g]]
+[[g]]       doctrina change delta {{CHANGE_ID}} <capability> --requirement "event: ..." \[[/g]]
+[[g]]         --criterion "[unverified] ... — verified by `...`" --bump minor[[/g]]
 {{FROM_DIFF_DELTA_NOTE}}
 
 4. Replace the placeholder tasks in .doctrina/changes/{{CHANGE_ID}}/tasks.md
    with small, checkable implementation tasks (a few hours each, max),
    and record the change's What/Scope in its proposal.md. Do this BEFORE
-   implementing — analyze and close refuse a change whose scaffold
+   implementing — `change check` and close refuse a change whose scaffold
    placeholders were never replaced, and `change tick` will not tick them.
 
 5. Implement task by task, checking each box as it lands. Advance the
@@ -67,9 +70,16 @@ Execute in order, in a single linear pass:
 [[g]]   It self-reviews on the way through: the close runs `doctrina review`[[/g]]
 [[g]]   before the apply, where its findings can still change what gets[[/g]]
 [[g]]   written. Advisory — it reports and the close continues.[[/g]]
-[[g]]   (equivalent, step by step: [[/g]][[g]]analyze → change apply → verify → coverage → trace → change archive → validate)[[/g]]
+[[g]]   The sequence is declared in one place and printed by the close itself,[[/g]]
+[[g]]   so read it there rather than from a copy that goes stale.[[/g]]
    Before it: check the proposal's ## Verification boxes and every task,
-   closing steps included, and bump Implementation to verified.
+   and bump Implementation to verified.
+   Two gates ask for WRITING, and both refuse late if you leave them:
+   a change that alters a documented surface needs the documentation to
+   move with it, AND an entry in the project's changelog — one says how it
+   works, the other says that it changed. If the command and flag names in
+   your prose are only MENTIONED, declare it instead of forcing:
+   [[c]]- **Documented surface:** n/a — <why>[[/c]] in the proposal.
 
 8. [[c]]doctrina next[[/c]] for the follow-up.
 [[g]]   If this change taught a reusable lesson (a fix you'd hate to relearn,[[/g]]

package/src/commands/constitution.js

@@ -1,68 +0,0 @@
-// @ts-check
-import path from "node:path";
-import process from "node:process";
-import { readdirSync } from "node:fs";
-import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
-import { listHeader } from "../lib/scan.js";
-import { c } from "../lib/colors.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
-import { acceptedDecisions, productSection } from "../lib/constitution-model.js";
-import { collectSnapshot } from "../lib/snapshot.js";
-import { renderView } from "../lib/views.js";
-
-// Read by the project snapshot as well; see lib/constitution-model.js.
-export { acceptedDecisions, productSection } from "../lib/constitution-model.js";
-
-// The project's standing rules in one read — Spec Kit parity for its
-// `constitution.md`, but ASSEMBLED, not a new home for facts. Doctrina's
-// constitution is its accepted ADRs (the immutable decisions that govern how
-// the codebase evolves) plus the product's declared non-goals. Both already
-// own those facts elsewhere; this is a read-only digest that gathers them so a
-// human or agent (especially one migrating from Spec Kit, which expects a
-// single constitution) can see "the rules" without reading the whole tree.
-//
-// To change a principle, supersede its ADR; to change a non-goal, edit
-// product.md. The command never writes — it has nothing of its own to own.
-
-// 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"], string: [] };
-
-export async function run(_positional, _flags) {
-  const projectRoot = process.cwd();
-  if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw notADoctrinaProject();
-  }
-  // Deprecated (change 0049): the standing rules are a VIEW of the shared
-  // collection, and `prime --rules` renders it. This command prints the same
-  // lines — not a similar set, the same ones — so the deprecation is a
-  // rename with a warning rather than a loss.
-  for (const line of renderView("rules", collectSnapshot(projectRoot))) console.log(line);
-  return 0;
-}
-
-function projectName(projectRoot) {
-  try {
-    return JSON.parse(read(path.join(projectRoot, ".doctrina", "index.json"))).project
-      ?? path.basename(projectRoot);
-  } catch {
-    return path.basename(projectRoot);
-  }
-}
-
-
-export const help = `
-Usage: doctrina constitution
-
-Print the project's standing rules in one read: the accepted ADRs (the
-immutable decisions that govern how the codebase evolves) and the product's
-declared non-goals. Read-only — it assembles facts the ADRs and product.md
-already own; it never writes.
-
-This is the Spec Kit \`constitution.md\` analogue: a single place to see the
-non-negotiables. To change one, supersede the ADR or edit product.md.
-
-DEPRECATED: use \`doctrina prime --rules\`, which prints exactly these lines.
-This name keeps working and will be removed in a future minor.
-`;