@seanmars/tospec 0.19.0-beta.8 → 0.21.0

package/dist/commands/decision.js

@@ -1,20 +1,12 @@
 /**
- * Decision (ADR) Command
+ * `tospec decision` — Architecture Decision Records. Unlike the `change`
+ * workflow these are permanent: one
+ * `tospec/decisions/<yyyyMMdd_HHmmss>-<topic>.md` file each.
  *
- * A dedicated command group for Architecture Decision Records. Unlike the
- * `change` workflow, decisions are permanent records: each one is a single
- * `tospec/decisions/<yyyyMMdd_HHmmss>-<topic>.md` file.
- *
- * `decision new` produces both files from the CLI's own templates: it writes the
- * dated decision file from `decision.md` (title / status / date pre-filled) and
- * appends a row to the persisted ledger `tospec/decisions/index.md`
- * (timestamp / title / summary), seeding it from `index.md` on first use. The
- * agent then fills the decision's prose sections.
- *
- * `decision list` derives a live status view from the files on disk.
- *
- * The `decision` schema (schemas/decision/) supplies both templates and the
- * required-sections contract; this command consumes them.
+ * `decision new` writes that file from the `decision` schema's template (title /
+ * status / date pre-filled) and appends a row to the ledger
+ * `tospec/decisions/index.md`, seeded from `index.md` on first use; the agent
+ * fills the prose sections. `decision list` derives a live view from disk.
  */
 import { Option } from 'commander';
 import path from 'path';
@@ -24,20 +16,13 @@ import { loadTemplate } from '../core/artifact-graph/index.js';
 import { MarkdownParser, findSection } from '../core/parsers/markdown-parser.js';
 import { completeRootStructure, validateChangeName } from '../utils/change-utils.js';
 import { formatTimestamp } from '../utils/timestamp.js';
-import { DEFAULT_SCHEMA } from './workflow/shared.js';
+import { DEFAULT_SCHEMA, DECISION_SCHEMA_NAME } from '../core/schema-names.js';
 import { emitSuccess, emitFailure } from './shared-output.js';
-// -----------------------------------------------------------------------------
-// Types
-// -----------------------------------------------------------------------------
+import { stripBom } from '../core/parsers/requirement-text.js';
 const DECISION_STATUSES = ['proposed', 'accepted', 'superseded'];
-/**
- * Exported so `new change` can refuse it by name. The decision schema backs
- * this command's ADR writer, not the change graph: its artifact lands in
- * `tospec/decisions/`, so a change created against it produced a directory
- * under `tospec/changes/` that `decision list` never saw, with no ticket and
- * no `type`.
- */
-export const DECISION_SCHEMA_NAME = 'decision';
+// Re-exported for callers that reached it here; defined in core/schema-names so
+// workflow/shared.ts no longer has to import this command module.
+export { DECISION_SCHEMA_NAME };
 /** The `--json` null-shapes; shared by the commander table and the catch sites. */
 export const DECISION_NEW_FAILURE_PAYLOAD = {
     decision: null,
@@ -51,18 +36,14 @@ const SCHEMA_NAME = DECISION_SCHEMA_NAME;
 const DECISIONS_SUBDIR = path.join('tospec', 'decisions');
 // Aligns with the project-wide CLI timestamp (formatTimestamp): yyyyMMdd_HHmmss.
 const TIMESTAMP_RE = /^\d{8}_\d{6}$/;
-/** The same shape, split into fields for calendar checking and display. */
 const TIMESTAMP_PARTS_RE = /^(\d{4})(\d{2})(\d{2})_(\d{2})(\d{2})(\d{2})$/;
 const FILE_RE = /^(\d{8}_\d{6})-(.+)\.md$/;
-// -----------------------------------------------------------------------------
-// Helpers
-// -----------------------------------------------------------------------------
 /** Title = the H1 heading; falls back to the topic derived from the filename. */
 function parseTitle(sections, fallback) {
     const h1 = sections.find((s) => s.level === 1);
     return h1?.title.trim() || fallback;
 }
-/** Status = the first ASCII-word bullet under the `Status` section (the `Date:` bullet comes after it, so first-match wins). */
+/** Status = the first ASCII-word bullet under `Status` (the `Date:` bullet follows it). */
 function parseStatus(sections) {
     const statusSection = findSection(sections, 'Status');
     if (!statusSection)
@@ -100,33 +81,34 @@ export function readDecisionEntries(decisionsDir) {
 }
 /** Fills CLI-owned fields (title / date / status) into the schema template. */
 function renderDecision(template, title, stamp, status) {
+    // Function replacers: a string replacement expands `$&`, `$'` and `` $` ``, so
+    // a `--title` containing one wrote pieces of the template into the heading.
     return template
-        .replace(/^# .*$/m, `# ${title}`)
-        .replace('[yyyyMMdd_HHmmss]', stamp)
-        .replace(/^- proposed$/m, `- ${status}`);
+        .replace(/^# .*$/m, () => `# ${title}`)
+        .replace('[yyyyMMdd_HHmmss]', () => stamp)
+        .replace(/^- proposed$/m, () => `- ${status}`);
 }
-/** `20260722_161825` -> `2026-07-22 16:18:25` for the index row (falls back to the raw stamp). */
 /**
  * Whether a shape-valid stamp also names a real instant.
  *
- * The regex alone accepts `20261345_996199` — month 13, day 45, hour 99 — and
- * `--date` is the only place a timestamp comes from outside `formatTimestamp`.
- * The bad value then became the filename, the ledger's human date
- * (`2026-13-45 99:61:99`), and the sort key `decision list --sort date` orders
- * by, where it outranks every real record.
- *
- * Round-tripped rather than range-checked per field, so month lengths and leap
- * days come from the calendar instead of a second implementation of it.
+ * `TIMESTAMP_RE` alone accepts `20261345_996199`, and that value becomes the
+ * filename, the ledger's date and the `--sort date` key. Round-tripped rather
+ * than range-checked per field, so month lengths and leap days come from the
+ * calendar.
  */
 function isRealTimestamp(stamp) {
     const m = TIMESTAMP_PARTS_RE.exec(stamp);
     if (!m)
         return false;
     const [, y, mo, d, h, mi, sec] = m.map(Number);
-    const date = new Date(y, mo - 1, d, h, mi, sec);
-    return (date.getFullYear() === y && date.getMonth() === mo - 1 && date.getDate() === d
-        && date.getHours() === h && date.getMinutes() === mi && date.getSeconds() === sec);
+    // UTC, not local time: the stamp is a calendar label, and a local round-trip
+    // rejected the hour a DST transition skips (02:30 on the spring-forward day
+    // in a DST zone), making a `--date` valid on one machine and not another.
+    const date = new Date(Date.UTC(y, mo - 1, d, h, mi, sec));
+    return (date.getUTCFullYear() === y && date.getUTCMonth() === mo - 1 && date.getUTCDate() === d
+        && date.getUTCHours() === h && date.getUTCMinutes() === mi && date.getUTCSeconds() === sec);
 }
+/** `20260722_161825` -> `2026-07-22 16:18:25`, or the raw stamp if unparseable. */
 function stampToHuman(stamp) {
     const m = TIMESTAMP_PARTS_RE.exec(stamp);
     if (!m)
@@ -148,11 +130,9 @@ function ensureIndex(decisionsDir, projectRoot) {
     }
     return indexPath;
 }
-// Limitation: no dedup by topic — two decisions on different dates for the same
-// topic are two files and so two rows. Dedup by topic if the ledger ever grows
-// noisy enough to matter.
-// `file` is the sibling filename (index.md lives in the same decisions dir), so
-// a relative markdown link resolves straight to the decision doc.
+// `file` is the sibling filename (index.md lives in the decisions dir), so the
+// relative link resolves straight to the decision doc.
+// Limitation: no dedup by topic — two dates for one topic are two rows.
 function indexRow(timestamp, status, title, summary, file) {
     const fileLink = `[${indexCell(file)}](${file})`;
     return `| ${timestamp} | ${indexCell(status)} | ${indexCell(title)} | ${indexCell(summary)} | ${fileLink} |`;
@@ -161,19 +141,12 @@ function indexRow(timestamp, status, title, summary, file) {
 const INDEX_HEADER = '| timestamp | status | title | summary | file |';
 const INDEX_SEPARATOR = '| ----- | ----- | ----- | ----- | ----- |';
 /**
- * Brings a pre-status ledger up to the current five-column shape.
- *
- * Round 4 report 14: `index.md` recorded timestamp/title/summary/file, so a
- * superseded decision was indistinguishable from a live one in the file people
- * and agents actually read — the decision skill even tells the author to flip an
- * older record's status, and nothing about the ledger changed when they did.
+ * Brings a pre-status ledger up to the current five-column shape. Without the
+ * column a superseded decision is indistinguishable from a live one.
  *
- * Each existing row's status is read from the decision file its link points at,
- * rather than left blank: the value is on disk already, and a column of empties
- * would be a new way to not know. Rows whose file is gone keep the `unknown`
- * that `decision list` reports for the same case. Everything else in the row is
- * preserved — this is a column insert, not a rebuild, so hand-written cells
- * survive.
+ * Each row's status is read from the file its link points at rather than left
+ * blank; a missing file keeps the `unknown` `decision list` reports. A column
+ * insert, not a rebuild, so hand-written cells survive.
  */
 function upgradeIndexColumns(lines, decisionsDir) {
     return lines.map((line) => {
@@ -192,6 +165,39 @@ function upgradeIndexColumns(lines, decisionsDir) {
         return `|${cells[0]}| ${status} |${cells[1]}|${cells[2]}|${cells[3]}|`;
     });
 }
+/**
+ * Re-reads every row's status from the decision file it links to, on every index
+ * write. A status changes on a *different* row than the one being written: the
+ * decision skill tells the author to flip an older record to `superseded` and
+ * forbids hand-editing `index.md`.
+ *
+ * Only the status cell is touched; hand-edited cells survive, and so does a row
+ * whose file is gone — see the guard below.
+ */
+function refreshIndexStatuses(lines, decisionsDir) {
+    return lines.map((line) => {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            return line;
+        if (/^\|\s*timestamp\s*\|/i.test(trimmed))
+            return line;
+        if (/^[|\s-]+$/.test(trimmed))
+            return line;
+        const cells = trimmed.slice(1, -1).split('|');
+        if (cells.length !== 5)
+            return line;
+        const fileMatch = /\]\(([^)]+)\)/.exec(cells[4]);
+        if (!fileMatch)
+            return line;
+        // A row whose file no longer exists is left exactly as it is: rewriting it
+        // to `unknown` would overwrite the last surviving record of that decision,
+        // and would count as a refresh on a row that never drifted.
+        if (!fs.existsSync(path.join(decisionsDir, fileMatch[1])))
+            return line;
+        const status = statusOfDecisionFile(decisionsDir, fileMatch[1]);
+        return `|${cells[0]}| ${status} |${cells[2]}|${cells[3]}|${cells[4]}|`;
+    });
+}
 /** The status recorded in a decision file, or `unknown` when it cannot be read. */
 function statusOfDecisionFile(decisionsDir, file) {
     try {
@@ -203,47 +209,164 @@ function statusOfDecisionFile(decisionsDir, file) {
     }
 }
 /**
- * Write this decision's row, replacing the existing one for the same file.
- *
- * One row per file, so `--force` must not append a second — but it must not
- * leave the old one either. Skipping the write entirely was the previous
- * behaviour, and it let `--force` change a decision's title and status in the
- * file while the ledger kept advertising the old ones: `decision list` reads the
- * files and index.md is read by people, so the two silently disagreed with no
- * way to tell which was current.
+ * Writes this decision's row, replacing the existing one for the same file: one
+ * row per file, so `--force` must neither append a second nor leave the old one
+ * advertising a title and status the file no longer has.
  *
- * Matched on the filename rather than the title, because the title is exactly
- * what a rewrite is likely to change.
+ * Matched on the filename, not the title — the title is what a rewrite changes.
  */
 function writeIndexRow(indexPath, timestamp, status, title, summary, file) {
     const row = indexRow(timestamp, status, title, summary, file);
-    let existing = fs.readFileSync(indexPath, 'utf-8');
-    // Preserve whatever endings the ledger already uses (see the CRLF note in
-    // CONVENTIONS): split tolerantly, rejoin with what was found.
+    // BOM stripped so the rewritten ledger comes out BOM-free and the
+    // `| status |` header test below cannot be defeated by one.
+    const existing = stripBom(fs.readFileSync(indexPath, 'utf-8'));
+    // Preserve whatever endings the ledger already uses.
     const eol = existing.includes('\r\n') ? '\r\n' : '\n';
     let lines = existing.split(/\r?\n/);
-    // A ledger written before the status column gets it here, filled from the
-    // decision files, rather than growing a row one cell wider than its header.
+    // A ledger written before the status column gets it here, rather than growing
+    // a row one cell wider than its header.
     if (!existing.includes('| status |')) {
         lines = upgradeIndexColumns(lines, path.dirname(indexPath));
-        existing = lines.join(eol);
-        fs.writeFileSync(indexPath, existing, 'utf-8');
     }
+    // Every other row's status is brought up to date in the same write. The row
+    // being written is excluded by construction — it is replaced with `row` below.
+    lines = refreshIndexStatuses(lines, path.dirname(indexPath));
     const linkTarget = `](${file})`;
     const index = lines.findIndex((line) => line.startsWith('|') && line.includes(linkTarget));
     if (index === -1) {
-        const separator = existing.length > 0 && !existing.endsWith('\n') ? eol : '';
-        fs.appendFileSync(indexPath, separator + row + eol, 'utf-8');
+        const body = lines.join(eol);
+        const separator = body.length > 0 && !body.endsWith('\n') ? eol : '';
+        fs.writeFileSync(indexPath, body + separator + row + eol, 'utf-8');
         return;
     }
     lines[index] = row;
     fs.writeFileSync(indexPath, lines.join(eol), 'utf-8');
 }
-// -----------------------------------------------------------------------------
-// Command implementations (exported for tests)
-// -----------------------------------------------------------------------------
+/** The decision file an index row links to, or null for a non-row line. */
+function indexRowFile(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|'))
+        return null;
+    return /\]\(([^)]+)\)/.exec(trimmed)?.[1] ?? null;
+}
+/**
+ * A data row's timestamp cell, or null for the header, the separator and prose.
+ * `yyyy-MM-dd HH:mm:ss` sorts lexicographically in chronological order, so the
+ * string is its own comparison key — no date parsing, and a hand-edited cell
+ * compares as text rather than throwing.
+ */
+function indexRowTimestamp(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|'))
+        return null;
+    if (/^\|\s*timestamp\s*\|/i.test(trimmed))
+        return null;
+    if (/^[|\s-]+$/.test(trimmed))
+        return null;
+    const cells = trimmed.slice(1, -1).split('|');
+    if (cells.length !== 5)
+        return null;
+    return cells[0].trim();
+}
+/**
+ * Splices recovered rows into the ledger in timestamp order rather than onto the
+ * end: a row recovered by `--reindex` is dated whenever it was actually decided,
+ * so appending left index.md disagreeing with the sorted `decision list`.
+ *
+ * Existing rows are never reordered, only inserted between, so a hand-arranged
+ * ledger keeps its arrangement.
+ */
+function spliceRowsByTimestamp(body, additions) {
+    const result = [...body];
+    for (const addition of additions) {
+        const at = result.findIndex((line) => {
+            const stamp = indexRowTimestamp(line);
+            return stamp !== null && stamp > addition.timestamp;
+        });
+        if (at === -1)
+            result.push(addition.row);
+        else
+            result.splice(at, 0, addition.row);
+    }
+    return result;
+}
+/**
+ * Rows whose linked decision file is gone, read without touching the ledger.
+ *
+ * Split out of `reindexDecisionIndex` so a plain `decision list` can report the
+ * same rot: `list` reads the decision files, so a row naming a deleted one is
+ * invisible to it, and the rot was only surfaced by `--reindex` — a flag whose
+ * name is about writing, which nobody reaches for to ask a question.
+ */
+export function findDanglingIndexRows(decisionsDir) {
+    const indexPath = path.join(decisionsDir, 'index.md');
+    if (!fs.existsSync(indexPath))
+        return [];
+    const lines = stripBom(fs.readFileSync(indexPath, 'utf-8')).split(/\r?\n/);
+    const linked = new Set(lines.map((line) => indexRowFile(line)).filter((file) => file !== null));
+    return [...linked].filter((file) => !fs.existsSync(path.join(decisionsDir, file)));
+}
+/**
+ * Brings `index.md` back in line with the decision files without creating one.
+ * Three ways a ledger falls behind:
+ *
+ * 1. A stale status cell. Rewritten from the file it links to.
+ * 2. A decision file with no row (how one arrives from another branch).
+ *    Inserted in timestamp order.
+ * 3. A row whose file is gone. Named in the result, never removed — the ledger
+ *    is a historical record.
+ */
+export function reindexDecisionIndex(decisionsDir) {
+    const empty = { statusesRefreshed: 0, rowsAdded: [], danglingRows: [] };
+    const indexPath = path.join(decisionsDir, 'index.md');
+    if (!fs.existsSync(indexPath))
+        return empty;
+    const existing = stripBom(fs.readFileSync(indexPath, 'utf-8'));
+    const eol = existing.includes('\r\n') ? '\r\n' : '\n';
+    const lines = existing.split(/\r?\n/);
+    const refreshed = refreshIndexStatuses(lines, decisionsDir);
+    const statusesRefreshed = refreshed.reduce((count, line, i) => (line === lines[i] ? count : count + 1), 0);
+    const linked = new Set(refreshed.map((line) => indexRowFile(line)).filter((file) => file !== null));
+    const danglingRows = [...linked].filter((file) => !fs.existsSync(path.join(decisionsDir, file)));
+    // Oldest first, so recovered rows land in the order the ledger would have
+    // grown had they never gone missing.
+    const missing = readDecisionEntries(decisionsDir)
+        .filter((entry) => !linked.has(entry.file))
+        .sort((a, b) => a.date.localeCompare(b.date));
+    const added = missing.map((entry) => ({
+        timestamp: stampToHuman(entry.date),
+        // Summary left empty: no file carries it, and reusing the title would put
+        // text in the ledger nobody wrote.
+        row: indexRow(stampToHuman(entry.date), entry.status, entry.title, '', entry.file),
+    }));
+    if (statusesRefreshed > 0 || added.length > 0) {
+        const body = [...refreshed];
+        // Trailing blank lines are the file's ending, not rows; splice above them.
+        while (body.length > 0 && body[body.length - 1].trim() === '')
+            body.pop();
+        fs.writeFileSync(indexPath, spliceRowsByTimestamp(body, added).join(eol) + eol, 'utf-8');
+    }
+    return { statusesRefreshed, rowsAdded: missing.map((entry) => entry.file), danglingRows };
+}
 export async function decisionNewCommand(topic, options) {
+    // Root first, as `new change` does: an argument failure still happened
+    // somewhere, and `root: null` could not say where.
+    let resolvedRoot = null;
+    const failurePayload = () => ({
+        decision: null,
+        root: resolvedRoot ? toRootOutput(resolvedRoot) : null,
+    });
     try {
+        // Same rule as `new change`: a writing command never scaffolds a root in
+        // an uninitialised directory; that is `tospec init`'s job.
+        resolvedRoot = await resolveRootForCommand(options, {
+            json: options.json,
+            allowImplicitRoot: false,
+            failurePayload: failurePayload(),
+        });
+        if (!resolvedRoot)
+            return;
+        const root = resolvedRoot;
         if (!topic)
             throw new Error('Missing required argument <topic>');
         const nameValidation = validateChangeName(topic, 'Topic');
@@ -261,12 +384,6 @@ export async function decisionNewCommand(topic, options) {
         if (!isRealTimestamp(stamp)) {
             throw new Error(`Invalid --date '${stamp}'. That is not a real date and time.`);
         }
-        const root = await resolveRootForCommand(options, {
-            json: options.json,
-            failurePayload: DECISION_NEW_FAILURE_PAYLOAD,
-        });
-        if (!root)
-            return;
         const decisionsDir = path.join(root.path, DECISIONS_SUBDIR);
         const fileName = `${stamp}-${topic}.md`;
         const filePath = path.join(decisionsDir, fileName);
@@ -274,24 +391,19 @@ export async function decisionNewCommand(topic, options) {
         const summary = options.summary ?? title;
         const template = loadTemplate(SCHEMA_NAME, 'decision.md', root.path);
         const content = renderDecision(template, title, stamp, status);
-        // CLI produces both files: the dated decision file from its template, and
-        // the ledger (seeded from index.md on first use) with a row for this record.
-        //
-        // The root is completed first, not just `decisions/`. This command accepts an
-        // implicit root, so it can be what creates `tospec/` — and creating only the
-        // one subdirectory it needs left a half-root that every other command then
-        // resolved as a project, making `validate --all` and `status --all` report a
-        // clean sweep over somewhere that had never been one. `new change` has always
-        // completed the root for this reason; they now share the one implementation.
+        // The whole root, not just `decisions/`. The root above is always an
+        // explicit `tospec/` (allowImplicitRoot: false), but it may be a partial
+        // one — a `tospec/` with only `changes/` — and creating just `decisions/`
+        // inside it would leave a half-root that every other command resolves as
+        // a project. Directories only; no config.yaml is written here.
         await completeRootStructure(root.path, DEFAULT_SCHEMA);
         fs.mkdirSync(decisionsDir, { recursive: true });
         if (options.force) {
             fs.writeFileSync(filePath, content, 'utf-8');
         }
         else {
-            // 'wx' makes the create atomic: the filesystem itself enforces the
-            // guard, closing the check-then-write window a separate existsSync
-            // check would leave open between two concurrent invocations.
+            // 'wx' makes the create atomic, closing the check-then-write window a
+            // separate existsSync would leave open.
             try {
                 fs.writeFileSync(filePath, content, { encoding: 'utf-8', flag: 'wx' });
             }
@@ -303,9 +415,8 @@ export async function decisionNewCommand(topic, options) {
             }
         }
         const indexPath = ensureIndex(decisionsDir, root.path);
-        // Written unconditionally: one row per decision file, and a --force that
-        // rewrote the file has to carry its new title and summary into the ledger
-        // rather than leave the previous ones standing.
+        // Unconditional: a --force that rewrote the file has to carry its new title
+        // and summary into the ledger.
         writeIndexRow(indexPath, stampToHuman(stamp), status, title, summary, fileName);
         const payload = {
             decision: { topic, title, date: stamp, status, summary, path: filePath, indexPath },
@@ -322,7 +433,7 @@ export async function decisionNewCommand(topic, options) {
     }
     catch (error) {
         if (options.json) {
-            emitFailure(true, DECISION_NEW_FAILURE_PAYLOAD, error, 'decision_error');
+            emitFailure(true, failurePayload(), error, 'decision_error');
             return;
         }
         throw error;
@@ -330,11 +441,9 @@ export async function decisionNewCommand(topic, options) {
 }
 export async function decisionListCommand(options) {
     try {
-        // No implicit root, for the reason `list`, `status --all` and `validate --all`
-        // refuse one: this is a batch query, and on a directory that is not a project
-        // it answered "no decisions here" with exit 0 — a clean report about somewhere
-        // never examined. A named lookup cannot fail that way, which is why `show` and
-        // `validate <item>` still accept an implicit root; a listing can.
+        // No implicit root, like `list` / `status --all` / `validate --all`: a batch
+        // query outside a project would answer "no decisions here" with exit 0, a
+        // clean report about somewhere never examined.
         const root = await resolveRootForCommand(options, {
             json: options.json,
             allowImplicitRoot: false,
@@ -344,6 +453,24 @@ export async function decisionListCommand(options) {
             return;
         const decisionsDir = path.join(root.path, DECISIONS_SUBDIR);
         let entries = readDecisionEntries(decisionsDir);
+        // Taken before the filter, so the empty-state message can tell "nothing
+        // recorded" from "nothing matching".
+        const totalEntries = entries.length;
+        // The only write this command can perform, behind an explicit flag so a
+        // query never rewrites a tracked file unasked.
+        let reindexed = {
+            statusesRefreshed: 0,
+            rowsAdded: [],
+            danglingRows: [],
+        };
+        if (options.reindex) {
+            reindexed = reindexDecisionIndex(decisionsDir);
+        }
+        else {
+            // Read-only: a query reports the rot it can see without rewriting a
+            // tracked file.
+            reindexed = { ...reindexed, danglingRows: findDanglingIndexRows(decisionsDir) };
+        }
         if (options.status) {
             entries = entries.filter((e) => e.status === options.status);
         }
@@ -352,20 +479,69 @@ export async function decisionListCommand(options) {
             entries.sort((a, b) => a.topic.localeCompare(b.topic));
         }
         else {
-            // date desc (newest first); tie-break by topic for stability
+            // Newest first; tie-break by topic for stability.
             entries.sort((a, b) => b.date.localeCompare(a.date) || a.topic.localeCompare(b.topic));
         }
         if (options.json) {
-            emitSuccess({ decisions: entries }, toRootOutput(root));
+            emitSuccess({
+                decisions: entries,
+                ...(options.reindex
+                    ? {
+                        // `reindexedRows` keeps its original meaning (status cells
+                        // rewritten); the other two drifts get their own fields.
+                        reindexedRows: reindexed.statusesRefreshed,
+                        addedRows: reindexed.rowsAdded,
+                        danglingRows: reindexed.danglingRows,
+                    }
+                    : // Without --reindex the write counters would be a constant zero
+                        // that reads as "checked, nothing to do"; only the drift this
+                        // query actually looked for is reported, and only when there is
+                        // some.
+                        reindexed.danglingRows.length > 0
+                            ? { danglingRows: reindexed.danglingRows }
+                            : {}),
+            }, toRootOutput(root));
             return;
         }
+        // Posix separators throughout: `DECISIONS_SUBDIR` is a `path.join`, so on
+        // Windows appending `/index.md` printed `tospec\decisions/index.md`.
+        const ledger = `${DECISIONS_SUBDIR.split(path.sep).join('/')}/index.md`;
+        const hasDangling = reindexed.danglingRows.length > 0;
+        if (options.reindex) {
+            const done = [];
+            if (reindexed.statusesRefreshed > 0) {
+                done.push(`refreshed ${reindexed.statusesRefreshed} status cell(s)`);
+            }
+            if (reindexed.rowsAdded.length > 0) {
+                done.push(`added ${reindexed.rowsAdded.length} missing row(s): ${reindexed.rowsAdded.join(', ')}`);
+            }
+            if (done.length > 0) {
+                console.log(`${ledger}: ${done.join('; ')}.`);
+            }
+            else if (!hasDangling) {
+                // The all-clear is withheld while a row points at a file that is gone:
+                // saying the ledger agrees with the decision files and then naming rows
+                // that do not is two answers to one question.
+                console.log(`${ledger} is already in sync with the decision files.`);
+            }
+            else {
+                console.log(`${ledger}: no status cell or row needed rewriting, but it is not clean:`);
+            }
+        }
+        if (hasDangling) {
+            console.log(`Warning: ${reindexed.danglingRows.length} row(s) in ${ledger} link to a decision file that no longer exists: ${reindexed.danglingRows.join(', ')}.`);
+            console.log(options.reindex
+                ? 'Their status reads "unknown". Restore the file or remove the row by hand.'
+                : 'Restore the file or remove the row by hand; `tospec decision list --reindex` reports them without deleting any.');
+        }
         if (entries.length === 0) {
-            console.log('No decisions found. Create one with: tospec decision new <topic>');
+            console.log(options.status && totalEntries > 0
+                ? `No decisions with status '${options.status}' (${totalEntries} recorded). Drop --status to see them all.`
+                : 'No decisions found. Create one with: tospec decision new <topic>');
             return;
         }
-        // Widths derived from the data, not guessed: the header was padded to 12
-        // and 13 while a `yyyyMMdd_HHmmss` stamp is 15, so no row ever lined up
-        // with the rule beneath it.
+        // Widths derived from the data: a hardcoded width never lined a
+        // `yyyyMMdd_HHmmss` stamp up with the rule beneath it.
         const dateWidth = Math.max('Date'.length, ...entries.map((e) => e.date.length));
         const statusWidth = Math.max('Status'.length, ...entries.map((e) => e.status.length));
         console.log(`${'Date'.padEnd(dateWidth)} | ${'Status'.padEnd(statusWidth)} | Title`);
@@ -382,14 +558,6 @@ export async function decisionListCommand(options) {
         throw error;
     }
 }
-// -----------------------------------------------------------------------------
-// Registration
-// -----------------------------------------------------------------------------
-/**
- * Register the `decision` command group and its subcommands.
- *
- * @param program - The Commander program instance
- */
 export function registerDecisionCommand(program) {
     const decisionCmd = program
         .command('decision')
@@ -408,8 +576,10 @@ export function registerDecisionCommand(program) {
             await decisionNewCommand(topic, options);
         }
         catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exitCode = 1;
+            // The command already emitted its own JSON envelope; this catch only
+            // reaches the human path, which uses the same `Error:` line as every
+            // other command.
+            emitFailure(false, {}, error, 'decision_error');
         }
     });
     decisionCmd
@@ -417,14 +587,14 @@ export function registerDecisionCommand(program) {
         .description('List decisions as an index table')
         .addOption(new Option('--status <status>', 'Filter by status').choices(DECISION_STATUSES))
         .addOption(new Option('--sort <mode>', 'Sort order').choices(['date', 'name']).default('date'))
+        .option('--reindex', "Rewrite decisions/index.md's status column from the decision files")
         .option('--json', 'Output as JSON')
         .action(async (options) => {
         try {
             await decisionListCommand(options);
         }
         catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exitCode = 1;
+            emitFailure(false, {}, error, 'decision_error');
         }
     });
 }