@seanmars/tospec 0.19.0-beta.7 → 0.20.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';
@@ -22,27 +14,36 @@ import * as fs from 'fs';
 import { resolveRootForCommand, toRootOutput, } from '../core/root-selection.js';
 import { loadTemplate } from '../core/artifact-graph/index.js';
 import { MarkdownParser, findSection } from '../core/parsers/markdown-parser.js';
-import { validateChangeName } from '../utils/change-utils.js';
+import { completeRootStructure, validateChangeName } from '../utils/change-utils.js';
 import { formatTimestamp } from '../utils/timestamp.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'];
-const 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,
+    root: null,
+};
+export const DECISION_LIST_FAILURE_PAYLOAD = {
+    decisions: null,
+    root: null,
+};
+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}$/;
+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)
@@ -85,9 +86,29 @@ function renderDecision(template, title, stamp, status) {
         .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.
+ *
+ * `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);
+    // 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 = /^(\d{4})(\d{2})(\d{2})_(\d{2})(\d{2})(\d{2})$/.exec(stamp);
+    const m = TIMESTAMP_PARTS_RE.exec(stamp);
     if (!m)
         return stamp;
     const [, y, mo, d, h, mi, s] = m;
@@ -107,22 +128,243 @@ function ensureIndex(decisionsDir, projectRoot) {
     }
     return indexPath;
 }
-// ponytail: append-only, no dedup by topic — two decisions on the same topic
-// still get two rows, one per file. The caller (decisionNewCommand) is what
-// keeps this one row per *file*: it skips this call when a write replaced an
-// existing file (--force) rather than creating a new one. 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.
-function appendIndexRow(indexPath, timestamp, title, summary, file) {
+// `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})`;
-    fs.appendFileSync(indexPath, `| ${timestamp} | ${indexCell(title)} | ${indexCell(summary)} | ${fileLink} |\n`, 'utf-8');
+    return `| ${timestamp} | ${indexCell(status)} | ${indexCell(title)} | ${indexCell(summary)} | ${fileLink} |`;
+}
+/** The header a current ledger carries; `status` is the column added below. */
+const INDEX_HEADER = '| timestamp | status | title | summary | file |';
+const INDEX_SEPARATOR = '| ----- | ----- | ----- | ----- | ----- |';
+/**
+ * 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 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) => {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            return line;
+        if (/^\|\s*timestamp\s*\|/i.test(trimmed))
+            return INDEX_HEADER;
+        if (/^[|\s-]+$/.test(trimmed))
+            return INDEX_SEPARATOR;
+        const cells = trimmed.slice(1, -1).split('|');
+        if (cells.length !== 4)
+            return line;
+        const fileMatch = /\]\(([^)]+)\)/.exec(cells[3]);
+        const status = fileMatch ? statusOfDecisionFile(decisionsDir, fileMatch[1]) : 'unknown';
+        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 {
+        const content = fs.readFileSync(path.join(decisionsDir, file), 'utf-8');
+        return parseStatus(new MarkdownParser(content).getSections());
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * 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, 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);
+    // 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, rather than growing
+    // a row one cell wider than its header.
+    if (!existing.includes('| status |')) {
+        lines = upgradeIndexColumns(lines, path.dirname(indexPath));
+    }
+    // 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 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');
+}
+/** 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 };
 }
-// -----------------------------------------------------------------------------
-// Command implementations (exported for tests)
-// -----------------------------------------------------------------------------
 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');
@@ -137,33 +379,29 @@ export async function decisionNewCommand(topic, options) {
         if (!TIMESTAMP_RE.test(stamp)) {
             throw new Error(`Invalid --date '${stamp}'. Expected project timestamp format: yyyyMMdd_HHmmss`);
         }
-        const root = await resolveRootForCommand(options, {
-            json: options.json,
-            failurePayload: { decision: null },
-        });
-        if (!root)
-            return;
+        if (!isRealTimestamp(stamp)) {
+            throw new Error(`Invalid --date '${stamp}'. That is not a real date and time.`);
+        }
         const decisionsDir = path.join(root.path, DECISIONS_SUBDIR);
         const fileName = `${stamp}-${topic}.md`;
         const filePath = path.join(decisionsDir, fileName);
-        // Only --force needs this read: its write path (below) is the plain 'w'
-        // flag, so it is the one case where "did the file already exist" cannot be
-        // recovered from the write's own outcome.
-        const existedBeforeWrite = options.force ? fs.existsSync(filePath) : false;
         const title = options.title ?? topic;
         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 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' });
             }
@@ -175,11 +413,9 @@ export async function decisionNewCommand(topic, options) {
             }
         }
         const indexPath = ensureIndex(decisionsDir, root.path);
-        // One row per decision file: a --force that replaced an existing file is
-        // not a new record, so it must not add a second row for the same file.
-        if (!existedBeforeWrite) {
-            appendIndexRow(indexPath, stampToHuman(stamp), title, summary, fileName);
-        }
+        // 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 },
             root: toRootOutput(root),
@@ -195,7 +431,7 @@ export async function decisionNewCommand(topic, options) {
     }
     catch (error) {
         if (options.json) {
-            emitFailure(true, { decision: null }, error, 'decision_error');
+            emitFailure(true, failurePayload(), error, 'decision_error');
             return;
         }
         throw error;
@@ -203,14 +439,36 @@ export async function decisionNewCommand(topic, options) {
 }
 export async function decisionListCommand(options) {
     try {
+        // 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,
-            failurePayload: { decisions: null },
+            allowImplicitRoot: false,
+            failurePayload: DECISION_LIST_FAILURE_PAYLOAD,
         });
         if (!root)
             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);
         }
@@ -219,39 +477,85 @@ 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;
         }
-        console.log('Date        | Status      | Title');
-        console.log('-----------|------------|-----');
+        // 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`);
+        console.log(`${'-'.repeat(dateWidth)}-|-${'-'.repeat(statusWidth)}-|------`);
         for (const e of entries) {
-            console.log(`${e.date} | ${e.status.padEnd(10)} | ${e.title}`);
+            console.log(`${e.date.padEnd(dateWidth)} | ${e.status.padEnd(statusWidth)} | ${e.title}`);
         }
     }
     catch (error) {
         if (options.json) {
-            emitFailure(true, { decisions: null }, error, 'decision_error');
+            emitFailure(true, DECISION_LIST_FAILURE_PAYLOAD, error, 'decision_error');
             return;
         }
         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')
@@ -270,8 +574,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
@@ -279,14 +585,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');
         }
     });
 }