@vibecompass/vibecompass 0.10.8 → 0.11.0

package/src/compatibility.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { resolveLaneMarkerContext } from './lane-marker.js';
 import { STATE_VERSION } from './manifest.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { PACKAGE_VERSION } from './version.js';
@@ -10,12 +11,21 @@ import { PACKAGE_VERSION } from './version.js';
  */
 export async function inspectProjectCompatibility(options = {}) {
   const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
-  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  const rootResolution = await resolveInspectionRootDir(cwd, options.rootDir);
+  const rootDir = rootResolution.rootDir;
   const cliPackageVersion = normalizePackageVersion(options.packageVersion ?? PACKAGE_VERSION);
   const projectFilePath = path.join(rootDir, 'project.yaml');
   const manifestPath = path.join(rootDir, 'state', 'manifest.json');
   const warnings = [];
 
+  if (rootResolution.markerError) {
+    warnings.push(warning({
+      code: 'lane-marker-unreadable',
+      message: `A lane marker near ${cwd} could not be resolved (${rootResolution.markerError}); inspecting ${rootDir} instead. Lane-scoped commands will fail closed on it.`,
+      errorMessage: rootResolution.markerError,
+    }));
+  }
+
   const project = await readProjectStamp(projectFilePath);
   const manifest = await readManifestState(manifestPath);
   const packageStatus = project.status === 'unreadable'
@@ -101,6 +111,29 @@ export function formatCompatibilityWarnings(result) {
   return (result?.warnings ?? []).map((warning) => warning.message);
 }
 
+/**
+ * D-280: read-only inspection adopts the nearest valid marker's memory root
+ * the same way lane-scoped commands do, so a worktree cwd is inspected
+ * against the root it is bound to instead of a nonexistent `cwd/.compass`.
+ * The preflight must never block a command, so marker resolution failures
+ * fall back to the cwd default — the command that follows surfaces the
+ * marker error itself.
+ */
+async function resolveInspectionRootDir(cwd, explicitRootDir) {
+  if (explicitRootDir) {
+    return { rootDir: path.resolve(cwd, explicitRootDir), markerError: null };
+  }
+
+  try {
+    return { rootDir: (await resolveLaneMarkerContext({ cwd })).rootDir, markerError: null };
+  } catch (error) {
+    return {
+      rootDir: path.resolve(cwd, '.compass'),
+      markerError: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
 async function readProjectStamp(projectFilePath) {
   try {
     const config = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {

package/src/decision-index.js

@@ -0,0 +1,386 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { formatDecisionId, listDecisionFileNames } from './decisions.js';
+import { resolveLaneSelection } from './lane-marker.js';
+import { listProjectSessions } from './session.js';
+import { withMemoryRootLock } from './serialization.js';
+
+/**
+ * Grouped structure-preserving decisions/INDEX.md generator (D-283).
+ *
+ * The existing index file is the source of structure: hand-authored session
+ * group headings ("## 2026-07-03 — Session 1 (lane-x lane)") are editorial
+ * history no canonical entry records, so regeneration preserves every
+ * existing line verbatim and only appends missing rows. Anything the parser
+ * cannot round-trip byte-identically fails closed with named findings — the
+ * hand-maintained file is never "repaired" by regeneration.
+ */
+
+const INDEX_H1 = '# Decision Index';
+const TABLE_HEADER = '| # | Decision | Domain |';
+const TABLE_SEPARATOR = '|---|----------|--------|';
+const TABLE_SEPARATOR_PATTERN = /^\|-+\|-+\|-+\|$/;
+const GROUP_HEADING_PATTERN = /^## (.+)$/;
+const INDEX_ROW_PATTERN = /^\| (D-\d{3,}) \| (.*) \| \[([A-Za-z0-9_-]+)\]\(([A-Za-z0-9_.-]+)\) \|$/;
+const CANONICAL_DECISION_PATTERN = /^###\s+D-(\d+)\s+—\s+(.+)$/gm;
+const HYPHEN_ONLY_DECISION_PATTERN = /^###\s+D-(\d+)\s+-\s+(.+)$/gm;
+
+/**
+ * Conservative predicate for the flat-generator quarantine (D-209/D-255):
+ * any `## ` heading marks the content as grouped-shaped, including malformed
+ * grouped files — a broken grouped index must survive a flat overwrite too.
+ */
+export function looksLikeGroupedDecisionIndex(content) {
+  return typeof content === 'string' && /^## /m.test(content);
+}
+
+/** Strict structural parse. Returns { ok, problems, lines, groups }. */
+export function parseGroupedDecisionIndex(content) {
+  const problems = [];
+
+  if (typeof content !== 'string' || content.trim() === '') {
+    return { ok: false, problems: ['decisions/INDEX.md is empty or unreadable.'], lines: [], groups: [] };
+  }
+
+  if (content.includes('\r')) {
+    return { ok: false, problems: ['decisions/INDEX.md uses CRLF line endings; the grouped generator preserves LF files only.'], lines: [], groups: [] };
+  }
+
+  const lines = content.split('\n');
+  const groups = [];
+  const firstNonEmpty = lines.find((line) => line.trim() !== '');
+  if (firstNonEmpty !== INDEX_H1) {
+    problems.push(`decisions/INDEX.md does not start with the "${INDEX_H1}" title.`);
+  }
+
+  let index = 0;
+  // Preamble: everything before the first group heading, kept verbatim.
+  for (; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (GROUP_HEADING_PATTERN.test(line)) {
+      break;
+    }
+    if (line.startsWith('|')) {
+      problems.push(`Line ${index + 1} is a table row outside any "## <date> — <session>" group (flat-index shape?).`);
+    }
+  }
+
+  while (index < lines.length) {
+    const headingMatch = lines[index].match(GROUP_HEADING_PATTERN);
+    if (!headingMatch) {
+      problems.push(`Line ${index + 1} ("${truncate(lines[index])}") was not recognized inside the grouped index structure.`);
+      index += 1;
+      continue;
+    }
+
+    const group = { label: headingMatch[1], headingLineIndex: index, rows: [], lastRowLineIndex: -1 };
+    index += 1;
+    while (index < lines.length && lines[index].trim() === '') {
+      index += 1;
+    }
+
+    if (lines[index] !== TABLE_HEADER) {
+      problems.push(`Group "${group.label}" is missing the exact "${TABLE_HEADER}" header row (line ${index + 1}).`);
+    } else {
+      index += 1;
+      if (!TABLE_SEPARATOR_PATTERN.test(lines[index] ?? '')) {
+        problems.push(`Group "${group.label}" is missing the table separator row (line ${index + 1}).`);
+      } else {
+        index += 1;
+        while (index < lines.length && lines[index].startsWith('|')) {
+          const rowMatch = lines[index].match(INDEX_ROW_PATTERN);
+          if (!rowMatch) {
+            problems.push(`Group "${group.label}" row on line ${index + 1} ("${truncate(lines[index])}") does not match the "| D-NNN | <title> | [<domain>](<domain>.md) |" shape.`);
+          } else if (rowMatch[4] !== `${rowMatch[3]}.md`) {
+            problems.push(`Group "${group.label}" row ${rowMatch[1]} links [${rowMatch[3]}] to ${rowMatch[4]}; domain links must be [<domain>](<domain>.md).`);
+          } else {
+            group.rows.push({
+              id: Number(rowMatch[1].slice(2)),
+              idText: rowMatch[1],
+              title: unescapeRowTitle(rowMatch[2]),
+              domain: rowMatch[3],
+              lineIndex: index,
+            });
+            group.lastRowLineIndex = index;
+          }
+          index += 1;
+        }
+        if (group.rows.length === 0) {
+          problems.push(`Group "${group.label}" has no decision rows.`);
+        }
+      }
+    }
+
+    // Only blank lines may separate a group's table from the next heading.
+    while (index < lines.length && !GROUP_HEADING_PATTERN.test(lines[index])) {
+      if (lines[index].trim() !== '') {
+        problems.push(`Line ${index + 1} ("${truncate(lines[index])}") was not recognized inside the grouped index structure.`);
+      }
+      index += 1;
+    }
+
+    groups.push(group);
+  }
+
+  if (groups.length === 0) {
+    problems.push('decisions/INDEX.md has no "## <date> — <session>" groups; the grouped generator only maintains the grouped shape.');
+  }
+
+  return { ok: problems.length === 0, problems, lines, groups };
+}
+
+/**
+ * Collects canonical decisions from the domain files using the strict
+ * em-dash heading form. Hyphen-only headings cannot be indexed and are
+ * reported, never silently dropped (D-283).
+ */
+export async function collectCanonicalDecisions(rootDir) {
+  const decisionsDir = path.join(rootDir, 'decisions');
+  const decisions = [];
+  const problems = [];
+  const seen = new Map();
+
+  for (const fileName of await listDecisionFileNames(decisionsDir)) {
+    const content = await readFile(path.join(decisionsDir, fileName), 'utf8');
+    const strictIds = new Set();
+    for (const match of content.matchAll(CANONICAL_DECISION_PATTERN)) {
+      const id = Number(match[1]);
+      strictIds.add(id);
+      const domain = path.basename(fileName, '.md');
+      const previous = seen.get(id);
+      if (previous) {
+        problems.push(`Canonical decision ${formatDecisionId(id)} appears in both ${previous} and ${fileName}; repair the duplicate before regenerating the index (D-276).`);
+        continue;
+      }
+      seen.set(id, fileName);
+      decisions.push({ id, title: match[2].trim(), domain });
+    }
+    for (const match of content.matchAll(HYPHEN_ONLY_DECISION_PATTERN)) {
+      if (!strictIds.has(Number(match[1]))) {
+        problems.push(`Decision heading "D-${match[1]}" in ${fileName} uses "-" instead of "—" and cannot be indexed; fix the canonical heading.`);
+      }
+    }
+  }
+
+  decisions.sort((left, right) => left.id - right.id);
+  return { decisions, problems };
+}
+
+/**
+ * Canonical↔index correspondence: every canonical decision exactly once with
+ * a matching title and domain link; no orphan or duplicate rows. Returns the
+ * mismatch findings plus the canonical decisions absent from the index.
+ */
+function diffIndexAgainstCanonical(parsed, decisions) {
+  const problems = [];
+  const canonicalById = new Map(decisions.map((decision) => [decision.id, decision]));
+  const rowsById = new Map();
+
+  for (const group of parsed.groups) {
+    for (const row of group.rows) {
+      if (rowsById.has(row.id)) {
+        problems.push(`Index row ${row.idText} appears more than once (groups "${rowsById.get(row.id).groupLabel}" and "${group.label}").`);
+        continue;
+      }
+      rowsById.set(row.id, { ...row, groupLabel: group.label });
+
+      const canonical = canonicalById.get(row.id);
+      if (!canonical) {
+        problems.push(`Index row ${row.idText} ("${truncate(row.title)}") has no canonical decision entry.`);
+        continue;
+      }
+      if (canonical.title !== row.title) {
+        problems.push(`Index row ${row.idText} title ("${truncate(row.title)}") does not match the canonical heading ("${truncate(canonical.title)}").`);
+      }
+      if (canonical.domain !== row.domain) {
+        problems.push(`Index row ${row.idText} links domain [${row.domain}] but the canonical entry lives in ${canonical.domain}.md.`);
+      }
+    }
+  }
+
+  const missing = decisions.filter((decision) => !rowsById.has(decision.id));
+  return { problems, missing, rowCount: rowsById.size };
+}
+
+/** Read-only validation (`refresh-decision-index --check`). */
+export async function checkGroupedDecisionIndex(options) {
+  const rootDir = requireRootDir(options);
+  const indexPath = path.join(rootDir, 'decisions', 'INDEX.md');
+  const content = await readFile(indexPath, 'utf8').catch(() => null);
+  if (content === null) {
+    return { ok: false, indexPath, problems: [`No decisions/INDEX.md exists at ${indexPath}.`], stats: null };
+  }
+
+  const parsed = parseGroupedDecisionIndex(content);
+  const canonical = await collectCanonicalDecisions(rootDir);
+  const problems = [...parsed.problems, ...canonical.problems];
+  let stats = null;
+
+  if (parsed.ok) {
+    const diff = diffIndexAgainstCanonical(parsed, canonical.decisions);
+    problems.push(...diff.problems);
+    for (const decision of diff.missing) {
+      problems.push(`Canonical decision ${formatDecisionId(decision.id)} ("${truncate(decision.title)}") is missing from the index.`);
+    }
+    stats = {
+      groupCount: parsed.groups.length,
+      rowCount: diff.rowCount,
+      decisionCount: canonical.decisions.length,
+    };
+  }
+
+  return { ok: problems.length === 0, indexPath, problems, stats };
+}
+
+/**
+ * Structure-preserving refresh: appends canonical decisions missing from the
+ * index to the group named by `groupLabel` (created at the tail when absent).
+ * Existing lines are preserved verbatim; with nothing missing the file is not
+ * rewritten, so a no-op refresh is byte-idempotent. Any parse or
+ * correspondence problem refuses the write with named findings.
+ */
+export async function refreshGroupedDecisionIndex(options) {
+  const rootDir = requireRootDir(options);
+  return withMemoryRootLock(rootDir, 'refresh-decision-index', () => refreshGroupedDecisionIndexLocked(rootDir, options));
+}
+
+async function refreshGroupedDecisionIndexLocked(rootDir, options) {
+  const indexPath = path.join(rootDir, 'decisions', 'INDEX.md');
+  const groupLabel = normalizeOptionalString(options.groupLabel);
+  const result = {
+    indexPath,
+    refreshed: false,
+    upToDate: false,
+    added: [],
+    groupLabel,
+    problems: [],
+    warnings: [],
+  };
+
+  const content = await readFile(indexPath, 'utf8').catch(() => null);
+  if (content === null) {
+    result.problems.push(
+      `No decisions/INDEX.md exists at ${indexPath}; the grouped generator preserves an existing index and never creates one from scratch (D-283).`,
+    );
+    return result;
+  }
+
+  const parsed = parseGroupedDecisionIndex(content);
+  const canonical = await collectCanonicalDecisions(rootDir);
+  result.problems.push(...parsed.problems);
+  // Duplicate canonical IDs refuse the refresh; hyphen-heading findings are
+  // reported as warnings but do not block indexing the decisions that parse.
+  const duplicateProblems = canonical.problems.filter((problem) => problem.includes('appears in both'));
+  const headingWarnings = canonical.problems.filter((problem) => !problem.includes('appears in both'));
+  result.problems.push(...duplicateProblems);
+  result.warnings.push(...headingWarnings);
+  if (result.problems.length > 0) {
+    return result;
+  }
+
+  const diff = diffIndexAgainstCanonical(parsed, canonical.decisions);
+  result.problems.push(...diff.problems);
+  if (result.problems.length > 0) {
+    return result;
+  }
+
+  if (diff.missing.length === 0) {
+    result.upToDate = true;
+    return result;
+  }
+
+  if (!groupLabel) {
+    result.problems.push(
+      `${diff.missing.length} decision(s) are missing from the index but no group label was determined; pass --group "<date> — Session <N> (<lane-id> lane)" or run with a resolvable lane (D-283).`,
+    );
+    return result;
+  }
+
+  const rowLines = diff.missing.map(renderIndexRow);
+  const lines = [...parsed.lines];
+  const targetGroups = parsed.groups.filter((group) => group.label === groupLabel);
+  if (targetGroups.length > 0) {
+    const target = targetGroups[targetGroups.length - 1];
+    lines.splice(target.lastRowLineIndex + 1, 0, ...rowLines);
+  } else {
+    // New trailing group. The file ends with a trailing newline, so the last
+    // split element is an empty string — insert before it to keep the EOF
+    // byte layout unchanged.
+    const insertAt = lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
+    lines.splice(insertAt, 0, '', `## ${groupLabel}`, '', TABLE_HEADER, TABLE_SEPARATOR, ...rowLines);
+  }
+
+  await writeFile(indexPath, lines.join('\n'), 'utf8');
+  result.refreshed = true;
+  result.added = diff.missing;
+  return result;
+}
+
+/**
+ * Default group label per D-283: `<session_date> — Session <N> (<lane-id>
+ * lane)` for the lane resolved by the shared D-277/D-280 selection order.
+ * Returns null when the resolved lane cannot supply a date/number; callers
+ * that need a label anyway surface the refresh problem. The marker is passed
+ * in from the caller's already-resolved command context (so a worktree
+ * marker's root has already been adopted); this function only selects the
+ * lane and does not re-resolve the root — re-resolving with the defaulted
+ * root would null a valid marker as a root mismatch (D-280).
+ */
+export async function resolveDefaultIndexGroupLabel(options) {
+  const rootDir = requireRootDir(options);
+  const sessions = await listProjectSessions({ rootDir, cwd: options.cwd });
+  const selection = resolveLaneSelection({
+    explicitSessionId: options.sessionId ?? null,
+    marker: options.marker ?? null,
+    laneIds: sessions.lanes.map((lane) => lane.id),
+    rootDir,
+    purpose: 'label the decision index group for',
+  });
+
+  if (!selection.sessionId) {
+    return null;
+  }
+
+  const lane = sessions.lanes.find((item) => item.id === selection.sessionId);
+  if (!lane?.sessionDate || !lane.sessionNumber) {
+    return null;
+  }
+
+  return {
+    label: `${lane.sessionDate} — Session ${lane.sessionNumber} (${lane.id} lane)`,
+    sessionId: selection.sessionId,
+    warnings: [...selection.warnings],
+  };
+}
+
+function renderIndexRow(decision) {
+  return `| ${formatDecisionId(decision.id)} | ${escapeRowTitle(decision.title)} | [${decision.domain}](${decision.domain}.md) |`;
+}
+
+function escapeRowTitle(title) {
+  return title.replace(/\|/g, '\\|');
+}
+
+function unescapeRowTitle(title) {
+  return title.replace(/\\\|/g, '|');
+}
+
+function truncate(value, max = 80) {
+  const text = String(value);
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+function requireRootDir(options) {
+  if (typeof options?.rootDir !== 'string' || options.rootDir.trim() === '') {
+    throw new Error('The grouped decision index requires a rootDir.');
+  }
+  return options.rootDir;
+}
+
+function normalizeOptionalString(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}

package/src/decisions.js

@@ -0,0 +1,195 @@
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { withMemoryRootLock } from './serialization.js';
+
+/**
+ * Canonical decision-log primitives (D-276).
+ *
+ * D-numbers are allocated from the current shared root at write time, never
+ * reserved ahead of a write. `appendDecisionEntry` is the mediated atomic
+ * append path: it allocates and appends under the memory-root lock as one
+ * operation. `readNextDecisionId` exists for advisory previews and for the
+ * allocation step itself; callers outside the lock must treat its result as
+ * informational only.
+ */
+
+const DECISION_HEADING_PATTERN = /^###\s+D-(\d+)\b/gm;
+
+/**
+ * Canonical headings use zero-padded D-NNN (the manifest scanner rejects
+ * shorter forms); IDs past 999 grow naturally.
+ */
+export function formatDecisionId(id) {
+  return `D-${String(id).padStart(3, '0')}`;
+}
+const NEXT_ID_PLACEHOLDER_PATTERN = /^###\s+D-NEXT\s+(—|-)\s+\S/m;
+const EXCLUDED_DECISION_FILES = ['INDEX.md', 'README.md', 'EXAMPLE.md'];
+
+export async function listDecisionFileNames(decisionsDir) {
+  try {
+    return (await readdir(decisionsDir))
+      .filter((fileName) => fileName.endsWith('.md') && !EXCLUDED_DECISION_FILES.includes(fileName))
+      .sort((left, right) => left.localeCompare(right));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+export async function readNextDecisionId(rootDir) {
+  const decisionsDir = path.join(rootDir, 'decisions');
+  let max = 0;
+
+  for (const fileName of await listDecisionFileNames(decisionsDir)) {
+    const content = await readFile(path.join(decisionsDir, fileName), 'utf8');
+    for (const match of content.matchAll(DECISION_HEADING_PATTERN)) {
+      max = Math.max(max, Number(match[1]));
+    }
+  }
+
+  return max + 1;
+}
+
+/**
+ * Scans every canonical decision file and returns duplicate D-number usage as
+ * `[{ id, occurrences: ["file.md", ...] }]`. Duplicates block close-session
+ * for human repair (D-276); they are never auto-renumbered.
+ */
+export async function findDuplicateDecisionIds(rootDir) {
+  const decisionsDir = path.join(rootDir, 'decisions');
+  const occurrencesById = new Map();
+
+  for (const fileName of await listDecisionFileNames(decisionsDir)) {
+    const content = await readFile(path.join(decisionsDir, fileName), 'utf8');
+    for (const match of content.matchAll(DECISION_HEADING_PATTERN)) {
+      const id = Number(match[1]);
+      const occurrences = occurrencesById.get(id) ?? [];
+      occurrences.push(fileName);
+      occurrencesById.set(id, occurrences);
+    }
+  }
+
+  return [...occurrencesById.entries()]
+    .filter(([, occurrences]) => occurrences.length > 1)
+    .map(([id, occurrences]) => ({ id, occurrences }))
+    .sort((left, right) => left.id - right.id);
+}
+
+/**
+ * Atomically appends a staged decision entry to a canonical domain file.
+ *
+ * The staged entry must open with `### D-NEXT — <title>`; the placeholder is
+ * replaced with the D-number allocated at write time under the memory-root
+ * lock. Returns the allocated ID plus a derived-index reminder, because the
+ * grouped `decisions/INDEX.md` refresh stays with the closer until a
+ * structure-preserving generator exists (S4).
+ */
+export async function appendDecisionEntry(options) {
+  const rootDir = requireNonEmptyString(options?.rootDir, 'append-decision requires a rootDir.');
+  const targetName = normalizeTargetName(options?.target);
+  const entrySource = requireNonEmptyString(options?.entryContent, 'append-decision requires non-empty staged entry content.').trim();
+
+  if (!NEXT_ID_PLACEHOLDER_PATTERN.test(entrySource)) {
+    throw new Error(
+      'Staged decision entries must start with a "### D-NEXT — <title>" heading. ' +
+        'The D-number is allocated at write time (D-276); do not pre-assign one.',
+    );
+  }
+
+  const warnings = [];
+  if (!/\*\*Timestamp:\*\*/.test(entrySource)) {
+    warnings.push('Staged entry has no "**Timestamp:**" line; canonical decisions should carry a real timestamp.');
+  }
+  if (!/\*\*Rationale:\*\*/.test(entrySource)) {
+    warnings.push('Staged entry has no "**Rationale:**" line; canonical decisions should record why.');
+  }
+
+  return withMemoryRootLock(rootDir, 'append-decision', async () => {
+    const targetPath = path.join(rootDir, 'decisions', targetName);
+    const existing = await readFile(targetPath, 'utf8').catch((error) => {
+      if (error?.code === 'ENOENT') {
+        throw new Error(
+          `Decision target ${targetName} does not exist under ${path.join(rootDir, 'decisions')}. ` +
+            'Create the domain file first (or pick an existing domain).',
+        );
+      }
+      throw error;
+    });
+
+    const decisionId = await readNextDecisionId(rootDir);
+    const entry = entrySource.replace(/^(###\s+)D-NEXT\b/m, `$1${formatDecisionId(decisionId)}`);
+    const separator = existing.endsWith('\n') ? '\n---\n\n' : '\n\n---\n\n';
+    await writeFile(targetPath, `${existing}${separator}${entry}\n`, 'utf8');
+
+    const duplicates = await findDuplicateDecisionIds(rootDir);
+    if (duplicates.length > 0) {
+      warnings.push(
+        `Duplicate decision IDs detected after append: ${duplicates
+          .map((duplicate) => `${formatDecisionId(duplicate.id)} (${duplicate.occurrences.join(', ')})`)
+          .join('; ')}. Repair by hand before close-session; duplicates are never auto-renumbered.`,
+      );
+    }
+
+    // D-283: when the caller supplies a structure-preserving index refresher
+    // (a group label was determinable), the derived index is refreshed inside
+    // this same lock (D-276 — reentrant for the holder). The canonical append
+    // never fails because of the index: a refusal degrades to a warning plus
+    // the hand-refresh reminder.
+    let indexReminder =
+      'decisions/INDEX.md is derived; add the grouped index row for this entry by hand (or run `vibecompass refresh-decision-index`).';
+    if (typeof options.indexRefresher === 'function') {
+      // The canonical entry is already written above; the derived-index
+      // refresh must never make append-decision report failure. A structural
+      // refusal returns problems (degraded below); an fs error (EACCES,
+      // ENOSPC, an unreadable domain file) would otherwise throw here after
+      // the append landed and make a retry duplicate the entry, so wrap it and
+      // degrade the throw to the same named warning (D-283).
+      let refresh = null;
+      try {
+        refresh = await options.indexRefresher({ decisionId });
+      } catch (error) {
+        warnings.push(
+          `decisions/INDEX.md was not refreshed (D-283): the grouped index refresh failed after the canonical entry was appended — ${error instanceof Error ? error.message : String(error)}. The decision was recorded; do not re-run append-decision — refresh the index by hand with \`vibecompass refresh-decision-index\`.`,
+        );
+      }
+      warnings.push(...(refresh?.warnings ?? []));
+      if (refresh?.refreshed) {
+        indexReminder = `decisions/INDEX.md refreshed (structure-preserving, D-283): added ${refresh.added
+          .map((decision) => formatDecisionId(decision.id))
+          .join(', ')} under "## ${refresh.groupLabel}".`;
+      } else if (refresh?.upToDate) {
+        indexReminder = 'decisions/INDEX.md already lists this entry (structure-preserving refresh found nothing missing).';
+      } else if (refresh) {
+        warnings.push(
+          `decisions/INDEX.md was not refreshed (D-283 fail-closed): ${refresh.problems[0] ?? 'unknown refusal'}`,
+        );
+      }
+    }
+
+    return {
+      decisionId,
+      target: targetName,
+      targetPath,
+      warnings,
+      indexReminder,
+    };
+  });
+}
+
+function normalizeTargetName(value) {
+  const raw = requireNonEmptyString(value, 'append-decision requires a --target decision domain file.');
+  const name = path.basename(raw);
+  if (!name.endsWith('.md') || EXCLUDED_DECISION_FILES.includes(name) || name !== raw.replace(/^decisions\//, '')) {
+    throw new Error(
+      `Invalid decision target "${raw}". Use a domain file name such as "cross-cutting.md" (optionally prefixed with "decisions/").`,
+    );
+  }
+  return name;
+}
+
+function requireNonEmptyString(value, message) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(message);
+  }
+  return value;
+}