doctrina-cli 0.15.1 → 0.17.0

package/src/commands/close.js

@@ -2,24 +2,32 @@
 import path from "node:path";
 import process from "node:process";
 import { appendFileSync } from "node:fs";
-import { exists, isFile, read, walk } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, read, walk } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
-import { parseCapabilityFromDelta } from "./change.js";
-import { printAdrCheckpoint } from "../lib/adr-guard.js";
-import { checkDocsImpact } from "../lib/docs-impact.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { parseCapabilityFromDelta } from "../lib/doc-model.js";
+import { printAdrCheckpoint, acceptedDecisionCount } from "../lib/adr-guard.js";
+import { docsRemedy, checkDocsImpact, checkChangelogImpact } from "../lib/docs-impact.js";
+import { collectRuntimeFindings } from "../lib/runtime.js";
+import { derivedImplementations, implementationMismatch, summarize } from "../lib/coverage-model.js";
+import { specHeader, dependentsOf } from "../lib/scan.js";
+import { sequence, sequenceLabels, stepRerun } from "../lib/gates.js";
+import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
+import { refuseChangeRef } from "../lib/project.js";
 import * as analyze from "./analyze.js";
 import * as change from "./change.js";
 import * as verify from "./verify.js";
 import * as coverage from "./coverage.js";
 import * as trace from "./trace.js";
 import * as validate from "./validate.js";
+import * as indexRebuild from "./index-rebuild.js";
+import { appendLedgerLine, docsGapLine, ledgerPath as ledgerFile } from "../lib/ledger.js";
+import * as review from "./review.js";
 import * as skill from "./skill.js";
 
 // One-command close (review 2026-06-27 passive-user feature #2). The work
-// playbook lists the closing sequence — analyze → apply → verify → coverage →
-// trace → archive → validate — and the agent runs it step by step, which is
+// playbook lists the closing sequence — analyze → apply → runtime → verify →
+// coverage → trace → archive → validate — and the agent runs it step by step, which is
 // exactly where a gate gets skipped. `close` runs the whole sequence in one
 // pass, in-process, stopping at the first failure with the exact command to
 // rerun, so the agent makes one call and the human approves once. It is a
@@ -61,6 +69,16 @@ export async function run(positional, flags) {
 }
 
 async function closeOne(projectRoot, id, flags) {
+  const refused = refuseChangeRef(id);
+  if (refused !== null) return refused;
+  // A change id that does not resolve is the USAGE class, before any step
+  // is sequenced (change 0114) — every sibling that takes a change id
+  // answers 2; `close` answered 1 through the analyze step it ran first.
+  if (!isDir(path.join(projectRoot, ".doctrina", "changes", id))) {
+    console.error(c.red("error:") + ` change "${id}" not found at .doctrina/changes/${id}`);
+    console.error(c.gray("hint: ") + "open changes: `doctrina next`");
+    return EXIT.USAGE;
+  }
   const force = flagBool(flags, "force", false);
   const archiveFlags = force ? new Map([["force", true]]) : new Map();
   // Set by the docs gate when it fails, so a --force close can record the
@@ -82,67 +100,256 @@ async function closeOne(projectRoot, id, flags) {
     coverageRerun = `doctrina coverage --strict --only ${touched.join(",")}`;
   }
 
-  // Each step: a label, the command that runs it, and the literal command to
-  // rerun on failure. verify is conditional (skipped, with a loud note, when no
-  // verify.json is declared — a project may not have wired the real gate yet).
+  // How each declared step actually runs, keyed by the step id in
+  // SEQUENCES.close. The DECLARATION owns which steps exist, in what order,
+  // and how hard each bites (lib/gates.js, audit finding F1); this table owns
+  // only how to execute one in-process. A step declared with no runner here
+  // falls back to spawning its declared `argv`, so a gate added to the
+  // sequence appears in `close` — and in `doctor` and the CI action —
+  // without a second edit; a drift test pins the two together.
+  //
+  // Each runner returns an exit code and may replace the step's label or
+  // rerun line with a context-aware one (the coverage scope, the --force
+  // archive), which is rendering, not sequencing.
   const verifyConfigured = isFile(path.join(projectRoot, ".doctrina", "verify.json"));
-  const steps = [
-    { label: "analyze", rerun: `doctrina analyze ${id}`, run: () => analyze.run([id], new Map()) },
+  const runners = {
+    analyze: { run: () => analyze.run([id], new Map()) },
+
     // ADR checkpoint (operator review §4.6): the playbook's "record an ADR"
     // step was skippable in silence. Advisory — it names the accepted ADRs
     // whose text cites the touched capabilities and the amend commands, but
     // an ADR merely mentioning a capability is normal, so it never blocks.
-    {
-      label: "ADR checkpoint (advisory)",
-      rerun: "doctrina decision list",
+    "adr-checkpoint": {
       run: async () => {
         if (printAdrCheckpoint(projectRoot, touched, { c }) === 0) {
-          console.log(c.green("ok") + " no accepted ADR cites the touched capabilities");
+          // "No ADR cites these capabilities" is conformance only when there
+          // ARE accepted ADRs to cite them. With none on disk the sentence is
+          // vacuously true, and printing it as `ok` reads as a decision
+          // checked rather than a checkbox with nothing behind it (0089).
+          const accepted = acceptedDecisionCount(projectRoot);
+          if (accepted === 0) {
+            console.log(c.gray("·      no accepted ADR in the tree — nothing to check the change against"));
+          } else {
+            console.log(c.green("ok") + ` no accepted ADR cites the touched capabilities (${accepted} checked)`);
+          }
+        }
+        return 0;
+      },
+    },
+
+    // The review runs against the working tree, which for a close IS the
+    // change's diff: the work is done and not yet archived. Its exit code is
+    // discarded on purpose — the step is declared advisory, and an advisory
+    // step that could still move the close's result would be advisory in name
+    // only. A crash is caught by the loop and reported the same way.
+    review: {
+      run: async () => {
+        await review.run([], new Map());
+        return 0;
+      },
+    },
+
+    apply: { run: () => change.run(["apply", id], new Map()) },
+
+    // The RUNTIME gate (audit finding F2). RT01–RT05 live in lib/runtime.js
+    // and no default driver ran them: `close` did not, `validate` only under
+    // --runtime, and the published action not at all — so the one class of
+    // break every structural gate is blind to (the declaration that no
+    // longer matches the running system) reached production green. It sits
+    // after `apply`, because the deltas the apply just merged are what may
+    // have moved the surface the contract describes. A driver over
+    // lib/runtime.js: the same findings `contract check`, `triage` and
+    // `doctor` render, so the five can never disagree.
+    //
+    // Severity decides the level: an `error` blocks the close, a `warn` is
+    // reported and the close continues. A project with no contracts — or
+    // with contracts that declare no Wiring/Selectors rows — is not passing,
+    // it is UNCHECKED, and saying so is what stops silence from reading as
+    // proof.
+    runtime: {
+      run: async () => {
+        const { findings, contracts, declared } = collectRuntimeFindings(projectRoot);
+        if (contracts === 0) {
+          console.log(c.gray("·      no contracts — nothing declares a runtime surface"));
+          return 0;
+        }
+        for (const f of findings) {
+          const mark = f.level === "error" ? c.red("  ✗ ") : c.yellow("  ! ");
+          console.log(mark + `${f.contract}: ${f.message}` + c.gray(` [${f.code}]`));
+          console.log(`      ${c.gray(`fix: ${f.remedy}`)}`);
+        }
+        const errs = findings.filter((f) => f.level === "error").length;
+        if (errs > 0) {
+          console.error(c.red("error:") + ` ${errs} contract finding${errs === 1 ? "" : "s"} block${errs === 1 ? "s" : ""} the close — the same ${errs === 1 ? "one" : "ones"} \`doctrina contract check\` reports`);
+          return 1;
+        }
+        if (declared === 0) {
+          console.log(c.yellow("warn:  ") +
+            `${contracts} contract${contracts === 1 ? "" : "s"}, 0 Wiring/Selectors rows — the runtime surface is unchecked`);
+          return 0;
+        }
+        const warns = findings.length;
+        console.log(c.green("ok") + ` ${declared} declared row${declared === 1 ? " holds" : "s hold"}` +
+          (warns > 0 ? c.gray(`; ${warns} advisory finding${warns === 1 ? "" : "s"} above`) : ""));
+        return 0;
+      },
+    },
+
+    // The Implementation header, PROPOSED rather than remembered (audit
+    // finding F10). The `work` playbook asked the agent twice to advance a
+    // field whose correct value coverage had already computed one file over.
+    // Advisory and non-mutating by design: the close prints the `set-header`
+    // op for the capabilities this change touched, and a human — or
+    // `spec set --implementation auto` — applies it. A gate that rewrote the
+    // claim it checks would be marking its own homework.
+    implementation: {
+      run: async () => {
+        const scope = touched.length > 0 ? new Set(touched) : null;
+        const derived = derivedImplementations(projectRoot, { only: scope });
+        const proposals = [];
+        for (const [cap, row] of derived) {
+          const specPath = path.join(projectRoot, ".doctrina", "specs", cap, "spec.md");
+          if (!isFile(specPath)) continue;
+          const mismatch = implementationMismatch(specHeader(read(specPath), "Implementation"), row.derived);
+          if (mismatch) proposals.push({ cap, row, mismatch });
+        }
+        if (derived.size === 0) {
+          // "Every touched spec matches" over ZERO specs is vacuously true.
+          // A chore in a project with no capability spec reached this and was
+          // told its implementation headers were in order (change 0089).
+          console.log(c.gray("·      no spec to check — the change touches no capability"));
+          return 0;
+        }
+        if (proposals.length === 0) {
+          console.log(c.green("ok") + ` every touched spec's Implementation header matches its coverage (${derived.size} checked)`);
+          return 0;
+        }
+        for (const { cap, row, mismatch } of proposals) {
+          console.log(c.yellow("  ! ") + `${cap}: Implementation is "${mismatch.written}" but ` +
+            `${row.covered}/${row.total} criteria have resolving proof`);
+          console.log(`      ${c.gray("delta op: ")}${c.cyan(mismatch.op)}`);
+          console.log(`      ${c.gray("or:       ")}${c.cyan(`doctrina spec set ${cap} --implementation auto`)}`);
         }
         return 0;
       },
     },
-    { label: "apply", rerun: `doctrina change apply ${id}`, run: () => change.run(["apply", id], new Map()) },
-    verifyConfigured
-      ? { label: "verify", rerun: "doctrina verify", run: () => verify.run([], new Map()) }
-      : { label: "verify", skip: "no .doctrina/verify.json — declare the real gate with `doctrina verify --init`" },
-    {
+
+    // verify is conditional: skipped with a loud note when no verify.json is
+    // declared, because a project may not have wired the real gate yet.
+    verify: verifyConfigured
+      ? { run: () => verify.run([], new Map()) }
+      : { skip: "no .doctrina/verify.json — declare the real gate with `doctrina verify --init`" },
+
+    coverage: {
       label: touched.length > 0 ? `coverage (scoped: ${touched.join(", ")})` : "coverage",
       rerun: coverageRerun,
-      run: () => coverage.run([], coverageFlags),
+      run: async () => {
+        const code = await coverage.run([], coverageFlags);
+        reportDependentCoverage(projectRoot, touched);
+        return code;
+      },
     },
+
     // trace is advisory (provenance is a warning, not a hard gate): report it,
     // never let it block the close.
-    { label: "trace", rerun: "doctrina trace", run: async () => { await trace.run([], new Map()); return 0; } },
+    trace: { run: async () => { await trace.run([], new Map()); return 0; } },
+
     // Docs ship inside the change (D2): a change that alters a documented
     // surface — a command, a flag, an exit code — closes only with the
     // documentation that describes it. A blocking gate, because a docs
     // phase scheduled after the work never happens; --force is the same
     // escape hatch archive offers, and records the gap in the ledger.
-    {
-      label: "docs",
-      forceable: true,
-      rerun: "edit docs/ (EN + PT), then rerun",
+    docs: {
       run: async () => {
-        const r = checkDocsImpact(projectRoot, path.join(projectRoot, ".doctrina", "changes", id));
+        const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+        const r = checkDocsImpact(projectRoot, changeDir);
         if (r.ok) {
           console.log(c.green("ok") + ` ${r.reason}`);
-          return 0;
+          // Documentation says how it works; the changelog says that it
+          // changed. Asking only the first is how thirteen changes closed in
+          // one session with an empty `## [Unreleased]` behind them.
+          const log = checkChangelogImpact(projectRoot, changeDir);
+          if (log.ok) {
+            console.log(c.green("ok") + ` ${log.reason}`);
+            return 0;
+          }
+          console.error(c.red("error:") + ` this change ${log.reason}:`);
+          for (const s of log.signals) console.error(`  - ${s}`);
+          console.error(c.gray("hint: ") + "add an entry under the changelog's unreleased heading" +
+            ", or pass --force to close anyway (records the gap)");
+          docsGap = log;
+          return 1;
         }
         console.error(c.red("error:") + ` this change ${r.reason}:`);
         for (const s of r.signals) console.error(`  - ${s}`);
-        console.error(c.gray("hint: ") +
-          "document it in docs/en/ AND docs/pt/ (the `keep-docs-en-pt-parity` skill), " +
-          "or pass --force to close anyway (records the gap)");
+        // The remedy comes out of the project being checked, never out of
+        // Doctrina's own repository (change 0058): an adopting project with
+        // no `docs/` was being told to write English AND Portuguese and to
+        // read a skill it does not have.
+        console.error(c.gray("hint: ") + docsRemedy(projectRoot) + ".");
+        // THE SECOND ANSWER, NAMED WHERE IT IS NEEDED.
+        //
+        // The gate reads names, and a name is all it can see: a change that
+        // explains an effect, or a Scope boundaries line saying what it does
+        // NOT touch, reads exactly like one that alters the command. When the
+        // only remedy on offer was `--force`, an author looking at a false
+        // positive took the worst of the two exits — the ledger fills with
+        // gaps that were never gaps, and a real one stops standing out.
+        //
+        // The declaration exists for precisely this (change 0139) and was
+        // named nowhere the author would be looking.
+        console.error(c.gray("      ") + "if the names above are only MENTIONED, say so on the record: " +
+          "add `- **Documented surface:** n/a — <why>` to the proposal.");
+        console.error(c.gray("      ") + "or pass --force to close anyway (records the gap).");
         docsGap = r;
         return 1;
       },
     },
-    { label: "archive", rerun: `doctrina change archive ${id}${force ? " --force" : ""}`, run: () => change.run(["archive", id], archiveFlags) },
-    { label: "validate", rerun: "doctrina validate", run: () => validate.run([], new Map()) },
-  ];
 
-  console.log(c.bold(`Closing change ${id}`) + c.gray(" — analyze → ADR checkpoint → apply → verify → coverage → trace → docs → archive → validate"));
+    archive: {
+      rerun: `doctrina change archive ${id}${force ? " --force" : ""}`,
+      run: () => change.run(["archive", id], archiveFlags),
+    },
+
+    // In-process, like every other runner here: the close starts no subprocess
+    // of its own binary, and a criterion holds it to that.
+    "index-drift": { run: () => indexRebuild.run(["rebuild"], new Map([["check", true]])) },
+
+    validate: { run: () => validate.run([], new Map()) },
+  };
+
+  const steps = sequence("close").map((step) => {
+    const runner = runners[step.id] ?? {};
+    return {
+      id: step.id,
+      label: runner.label ?? step.label,
+      rerun: runner.rerun ?? stepRerun(step, id),
+      forceable: step.level === "forceable",
+      advisory: step.level === "advisory",
+      skip: runner.skip,
+      // A step declared with no in-process runner is a gap in THIS file, and
+      // it is reported as one — the same answer `doctor` gives (change 0060).
+      // The close used to shell out to its own binary here instead, which was
+      // the second integration style change 0045 removed from `doctor`; every
+      // declared step has a runner and a test holds it that way, so the
+      // fallback was a second answer to a question nobody could reach.
+      run: runner.run ?? (() => missingRunner(step)),
+    };
+  });
+
+  // The banner is the declaration read aloud, so it cannot fall behind the
+  // sequence it announces the way a hand-maintained string did.
+  console.log(c.bold(`Closing change ${id}`) +
+    c.gray(` — ${sequence("close").map((s) => s.label.replace(" (advisory)", "")).join(" → ")}`));
+
+  // What the closing line is allowed to claim. A step that was SKIPPED was
+  // not performed, and the conclusion used to say "verified, archived, and
+  // validated" as a fixed string — including on a close whose own step 7 had
+  // just printed `skip   no .doctrina/verify.json`. The final line is the one
+  // sentence a human reads before approving; a word it did not earn is the
+  // most expensive claim in the tree (change 0089).
+  const ran = new Set();
+  const skippedSteps = [];
 
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
@@ -150,6 +357,7 @@ async function closeOne(projectRoot, id, flags) {
     console.log(c.gray(`──── ${i + 1}/${steps.length} ${step.label}`));
     if (step.skip) {
       console.log(c.yellow("skip   ") + step.skip);
+      skippedSteps.push(step);
       continue;
     }
     let code;
@@ -160,6 +368,13 @@ async function closeOne(projectRoot, id, flags) {
       console.error(c.red("error:") + ` ${err.message}`);
     }
     if (code !== 0) {
+      // The declared level decides, not the runner: an advisory step reports
+      // and the close carries on, which is what "advisory" means in
+      // lib/gates.js and what the surfaces must agree on.
+      if (step.advisory) {
+        console.log(c.yellow("warn:") + ` "${step.label}" reported findings (advisory — the close continues)`);
+        continue;
+      }
       // A forceable gate under --force warns and continues, matching how
       // `change archive --force` handles incomplete verification: the gap
       // is recorded, not hidden.
@@ -174,14 +389,17 @@ async function closeOne(projectRoot, id, flags) {
       console.log(`    ${c.cyan(`doctrina close ${id}`)}`);
       return 1;
     }
+    ran.add(step.id);
   }
 
   // Record a forced docs gap in the ledger, so history shows the change
   // shipped without its documentation rather than showing nothing.
   if (docsGap) {
-    const ledgerPath = path.join(projectRoot, ".doctrina", "changes", "archive", "LEDGER.md");
+    const ledgerPath = ledgerFile(projectRoot);
     if (isFile(ledgerPath)) {
-      appendFileSync(ledgerPath, `  - docs gap: ${id} closed with --force; ${docsGap.signals.join("; ")} documented nowhere\n`);
+      // Written in the ledger's own entry grammar (change 0046): a waived
+      // gate no reader can find is the same as an unrecorded one.
+      appendLedgerLine(projectRoot, docsGapLine(id, docsGap.signals));
       console.log(c.yellow("ledger") + " recorded the docs gap");
     }
   }
@@ -197,13 +415,74 @@ async function closeOne(projectRoot, id, flags) {
   } catch { /* advisory only */ }
 
   console.log("");
-  console.log(c.green(`✓ change ${id} closed`) + c.gray(" — verified, archived, and validated."));
+  console.log(c.green(`✓ change ${id} closed`) + c.gray(closingClaim(ran, skippedSteps)));
   console.log(c.gray("Next: ") + c.cyan("doctrina next"));
   return 0;
 }
 
+// A step the sequence declares and this file does not implement. The gate map
+// is the single source of truth for what a close runs (ADR 0017), so a step
+// with no runner here is a defect in this file — not a reason to start a
+// second process and not a reason to pass silently. `doctor` reaches the same
+// conclusion for its own reporters; the two drivers now give one answer.
+// The closing sentence, built from the steps that actually ran.
+//
+// Each word names one step: `verify` -> verified, `archive` -> archived,
+// `validate` -> validated. A step that was skipped loses its word and is
+// named instead, so the line can never claim more than the run performed.
+function closingClaim(ran, skippedSteps) {
+  const words = [
+    ["verify", "verified"],
+    ["archive", "archived"],
+    ["validate", "validated"],
+  ].filter(([stepId]) => ran.has(stepId)).map(([, word]) => word);
+
+  const claimed = words.length === 0
+    ? ""
+    : words.length === 1
+      ? ` — ${words[0]}.`
+      : ` — ${words.slice(0, -1).join(", ")} and ${words[words.length - 1]}.`;
+
+  const skipped = skippedSteps.map((s) => s.label.replace(" (advisory)", ""));
+  if (skipped.length === 0) return claimed || " — no gate ran.";
+  return `${claimed || " —"} ${skipped.length === 1 ? "Skipped" : "Skipped"}: ${skipped.join(", ")}.`;
+}
+
+function missingRunner(step) {
+  console.error(c.red("error:") +
+    ` "${step.label}" is declared in the close sequence but has no runner here`);
+  if (step.argv) {
+    console.error(c.gray("hint: ") + `run it directly: doctrina ${step.argv.join(" ")}`);
+  }
+  return 1;
+}
+
 // The capabilities this change's deltas target — the honest scope for its
 // coverage gate. Read from the change folder's specs/**/delta.md files.
+// The capabilities that DECLARE a dependency on what this change touched,
+// with their coverage — advisory, never part of the verdict (change 0046).
+//
+// The scope exists because one deliberately deferred spec elsewhere in the
+// tree must not block a change that never went near it, and widening the gate
+// to dependents would give that problem straight back. What a closing agent
+// actually needs is the pointer: this change moved ground something else
+// stands on, and here is how well that something is proven today.
+function reportDependentCoverage(projectRoot, touched) {
+  if (touched.length === 0) return;
+  const dependents = dependentsOf(projectRoot, touched);
+  if (dependents.length === 0) return;
+  const byCap = new Map(summarize(projectRoot).perCap.map((r) => [r.cap, r]));
+  console.log(c.gray("  dependents of the touched capabilities (advisory — not part of this gate):"));
+  for (const dep of dependents) {
+    const row = byCap.get(dep.capability);
+    const proof = row && row.total > 0
+      ? `${row.covered}/${row.total} criteria proven` + (row.dangling ? `, ${row.dangling} dangling` : "")
+      : "no acceptance criteria";
+    console.log(`    ${c.cyan(dep.capability)} depends on ${dep.dependsOn.join(", ")} — ${proof}` +
+      c.gray(`  (doctrina why ${dep.capability})`));
+  }
+}
+
 function touchedCapabilities(projectRoot, id) {
   const specsDir = path.join(projectRoot, ".doctrina", "changes", id, "specs");
   const caps = new Set();
@@ -215,24 +494,49 @@ function touchedCapabilities(projectRoot, id) {
   return [...caps].sort();
 }
 
+// The sequence is DECLARED once, in lib/gates.js, and rendered here. It used
+// to be typed out in this string, which is how the help came to name ten
+// steps of thirteen — review, implementation, docs and the index-drift check
+// were added over time and the paragraph was not.
+const SEQUENCE = wrapArrows(sequenceLabels("close"), 70, "  ");
+
+function wrapArrows(labels, width, indent) {
+  const lines = [];
+  let line = "";
+  for (const label of labels) {
+    const piece = line === "" ? label : `${line} → ${label}`;
+    if (piece.length + indent.length > width && line !== "") {
+      lines.push(indent + line + " →");
+      line = label;
+    } else line = piece;
+  }
+  if (line !== "") lines.push(indent + line);
+  return lines.join("\n");
+}
+
 export const help = `
 Usage: doctrina close <id...> [--force]
 
 Run the whole closing sequence for a change in one pass, stopping at the
 first failure with the exact command to rerun:
 
-  analyze → ADR checkpoint (advisory) → change apply → verify → coverage
-  --strict (scoped to the change's touched capabilities) → trace → change
-  archive → validate → skill suggest (advisory)
+${SEQUENCE}
+
+then a closing skill-suggest listing (advisory).
 
 The coverage gate is scoped to the capabilities the change's deltas touch,
 so a deliberately deferred spec elsewhere cannot block an unrelated close;
-a change with no deltas gates on the whole tree. verify is skipped (with a
-note) when no .doctrina/verify.json is declared; trace, the ADR checkpoint
+a change with no deltas gates on the whole tree. The runtime gate holds the
+contracts' declared wiring, enums and selectors to the implementation (the
+RT01-RT05 checks \`contract check\` renders): an error blocks, a warning is
+reported and the close continues, and a project with no contracts — or with
+contracts declaring no rows — is reported UNCHECKED rather than passing.
+verify is skipped (with a note) when no .doctrina/verify.json is declared;
+trace, the ADR checkpoint
 (accepted ADRs citing the touched capabilities — amend via \`decision
 supersede\`, not silence), and the closing skill-suggest listing are
 advisory (reports, never blockers). This is a driver over the existing
-commands so the agent makes one call instead of nine and the human
+commands so the agent makes one call instead of thirteen and the human
 approves once.
 
 Multiple ids close in sequence, each independently; the exit code is the

package/src/commands/completion.js

@@ -1,15 +1,21 @@
 // @ts-check
-import { OPERATIONS, COMMAND_NAMES } from "../lib/commands.js";
+import { DEPRECATED, OPERATIONS } from "../lib/commands.js";
 import { c } from "../lib/colors.js";
 
 // Shell completions, generated from the same OPERATIONS catalog that feeds
 // `--help` and the docs drift tests — so the completion script can never
 // know a different surface than the CLI ships. Static output by design:
 // paste it into your shell config once; regenerate after upgrading.
+//
+// Deprecated operations are left out (change 0188): they still run, with a
+// notice, for a script that already types them — but tab completion is how
+// a person discovers the surface, and it should offer the replacement only.
+const LIVE = OPERATIONS.filter(([op]) => !DEPRECATED[op]);
+const COMMAND_NAMES = [...new Set(LIVE.map(([op]) => op.split(" ")[0]))];
 
 function subcommandMap() {
   const map = new Map();
-  for (const [op] of OPERATIONS) {
+  for (const [op] of LIVE) {
     const [cmd, sub] = op.split(" ");
     if (!sub) continue;
     if (!map.has(cmd)) map.set(cmd, []);