@vibecompass/vibecompass 0.10.8 → 0.11.0

package/src/cli.js

@@ -6,7 +6,12 @@ import { connectHostedProjectMemory, initializeProjectMemory, setDefaultSyncTarg
 import { preflightDocsReview } from './docs-review.js';
 import { planDocsUpdate, renderDocsUpdatePlan } from './docs-update.js';
 import { resolveConnectHostedCliOptions, resolveInitCliOptions } from './setup.js';
-import { closeProjectSession, listProjectSessions, startProjectSession, switchProjectSession } from './session.js';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { closeProjectSession, listProjectSessions, readLaneEnvironment, rebuildActiveSessionIndex, startProjectSession, switchProjectSession, writeLaneMarkerForSession } from './session.js';
+import { appendDecisionEntry, formatDecisionId, readNextDecisionId } from './decisions.js';
+import { checkGroupedDecisionIndex, refreshGroupedDecisionIndex, resolveDefaultIndexGroupLabel } from './decision-index.js';
+import { resolveLaneMarkerContext, resolveLaneSelection } from './lane-marker.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
 import { getProjectStatus, renderStatusText, toStatusJson } from './status.js';
 import { refreshWorkflow } from './refresh-workflow.js';
@@ -130,11 +135,52 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     io.stdout.write(`Updated ${result.claudePath}\n`);
     io.stdout.write(`Created ${result.wipFilePath}\n`);
     io.stdout.write(`Created ${result.handoffFilePath}\n`);
+    if (result.gitBinding) {
+      io.stdout.write(`Git binding: branch "${result.gitBinding.branch}"\n`);
+      for (const repo of result.gitBinding.repos) {
+        const location = repo.worktreePath ? ` at ${repo.worktreePath}` : '';
+        io.stdout.write(`- ${repo.repoId}: ${repo.mode === 'reuse' ? 'reused existing branch' : 'created branch'}${location} (base ${repo.baseRevision.slice(0, 12)})\n`);
+      }
+      if (result.gitBinding.markerPath) {
+        io.stdout.write(`Lane marker: ${result.gitBinding.markerPath}\n`);
+        const firstWorktree = result.gitBinding.repos.find((repo) => repo.worktreePath);
+        if (firstWorktree) {
+          io.stdout.write(`Next: cd ${firstWorktree.worktreePath} — commands run from inside a worktree need no --root or --session (lane marker).\n`);
+        }
+      }
+    }
+    if (result.runtime) {
+      io.stdout.write(`Runtime: port ${result.runtime.port}, temp dir ${result.runtime.tmpDir}\n`);
+      io.stdout.write('Export into a shell with: eval "$(vibecompass lane-env)" (D-282; pass --session <lane-id> when multiple lanes are active).\n');
+    }
     writeWarnings(io, result.warnings);
     writeAgentFileSyncResult(io, result.agentFileSync);
     return 0;
   }
 
+  if (parsed.command === 'lane-env') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const result = await readLaneEnvironment({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    if (parsed.options.json) {
+      io.stdout.write(`${JSON.stringify({
+        root_dir: result.rootDir,
+        lane_id: result.sessionId,
+        port: result.port,
+        tmp_dir: result.tmpDir,
+        env: result.env,
+      }, null, 2)}\n`);
+    } else {
+      for (const [name, value] of Object.entries(result.env)) {
+        io.stdout.write(`export ${name}=${shellQuoteSingle(value)}\n`);
+      }
+    }
+    writeWarnings(io, result.warnings);
+    return 0;
+  }
+
   if (parsed.command === 'connect-hosted') {
     await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const connectPlan = await resolveConnectHostedCliOptions(parsed.options, {
@@ -232,6 +278,8 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     io.stdout.write(`Closed session ${result.sessionDate}-${result.sessionNumber}\n`);
     io.stdout.write(`Wrote ${result.sessionFilePath}\n`);
     io.stdout.write(`Updated ${result.claudePath}\n`);
+    writeWorktreeCleanupResult(io, result.worktreeCleanup);
+    writeRuntimeCleanupResult(io, result.runtimeCleanup);
     if (result.docsUpdatePlan) {
       io.stdout.write(renderDocsUpdatePlan(result.docsUpdatePlan));
     }
@@ -446,6 +494,133 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'rebuild-active-index') {
+    const result = await rebuildActiveSessionIndex({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    if (result.removed) {
+      io.stdout.write('No active lanes; removed sessions/active/index.yaml.\n');
+    } else {
+      io.stdout.write(`Rebuilt ${result.indexPath}\n`);
+      io.stdout.write(`Current lane: ${result.current}\n`);
+      for (const lane of result.lanes) {
+        io.stdout.write(`- ${lane.id}${lane.workingOn ? `: ${lane.workingOn}` : ''}\n`);
+      }
+    }
+    return 0;
+  }
+
+  if (parsed.command === 'write-lane-marker') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const result = await writeLaneMarkerForSession({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    io.stdout.write(`Wrote lane marker for "${result.sessionId}" at ${result.markerPath}\n`);
+    io.stdout.write(`Recorded the marker in the lane's session.yaml (token-matched removal at close-session).\n`);
+    writeWarnings(io, result.warnings);
+    return 0;
+  }
+
+  if (parsed.command === 'append-decision') {
+    const cwd = runtime.cwd ? path.resolve(runtime.cwd) : process.cwd();
+    if (!parsed.options.entryPath) {
+      throw new Error('append-decision requires --entry <staged-entry-file>.');
+    }
+    // D-280 marker-aware root: an explicit --root wins, else the nearest
+    // worktree lane marker supplies the root, so a builder appending a
+    // decision mid-lane from inside a worktree needs neither --root nor
+    // --session (matching lane-env / close-session).
+    const markerContext = await resolveDecisionCommandContext(cwd, parsed.options);
+    const rootDir = markerContext.rootDir;
+    const entryContent = await readFile(path.resolve(cwd, parsed.options.entryPath), 'utf8');
+    // D-283: refresh the grouped index when a group label is determinable —
+    // explicit --group wins, else the resolvable lane context labels the
+    // group. With neither, the append keeps the hand-refresh reminder.
+    const labelResult = parsed.options.groupLabel
+      ? { label: parsed.options.groupLabel, warnings: [] }
+      : await resolveIndexGroupLabelSafely({ rootDir, cwd, sessionId: parsed.options.sessionId ?? null, marker: markerContext.marker });
+    const groupLabel = labelResult.label;
+    const result = await appendDecisionEntry({
+      rootDir,
+      target: parsed.options.target,
+      entryContent,
+      ...(groupLabel
+        ? { indexRefresher: () => refreshGroupedDecisionIndex({ rootDir, groupLabel }) }
+        : {}),
+    });
+    io.stdout.write(`Appended ${formatDecisionId(result.decisionId)} to ${result.targetPath}\n`);
+    for (const warning of uniqueStrings([...markerContext.warnings, ...labelResult.warnings, ...result.warnings])) {
+      io.stdout.write(`Warning: ${warning}\n`);
+    }
+    io.stdout.write(`${result.indexReminder}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'refresh-decision-index') {
+    const cwd = runtime.cwd ? path.resolve(runtime.cwd) : process.cwd();
+    // D-280 marker-aware root, matching lane-env / close-session, so the
+    // command works from inside a provisioned worktree with no flags.
+    const markerContext = await resolveDecisionCommandContext(cwd, parsed.options);
+    const rootDir = markerContext.rootDir;
+
+    if (parsed.options.check) {
+      const result = await checkGroupedDecisionIndex({ rootDir });
+      writeWarnings(io, markerContext.warnings);
+      if (result.ok) {
+        io.stdout.write(
+          `Grouped decision index check: clean (${result.stats.rowCount} rows in ${result.stats.groupCount} groups; ${result.stats.decisionCount} canonical decisions)\n`,
+        );
+        return 0;
+      }
+      io.stderr.write(`Grouped decision index check failed for ${result.indexPath}:\n`);
+      for (const problem of result.problems) {
+        io.stderr.write(`- ${problem}\n`);
+      }
+      return 1;
+    }
+
+    // Resolve the group label tolerantly: a no-op refresh (nothing missing)
+    // must not fail just because 2+ lanes are active with no marker/--session.
+    // The label is only load-bearing when rows are actually missing, and
+    // refreshGroupedDecisionIndex raises the actionable "pass --group" problem
+    // in exactly that case.
+    const labelResult = parsed.options.groupLabel
+      ? { label: parsed.options.groupLabel, warnings: [] }
+      : await resolveIndexGroupLabelSafely({ rootDir, cwd, sessionId: parsed.options.sessionId ?? null, marker: markerContext.marker });
+    const result = await refreshGroupedDecisionIndex({ rootDir, groupLabel: labelResult.label });
+    writeWarnings(io, uniqueStrings([...markerContext.warnings, ...labelResult.warnings, ...result.warnings]));
+    if (result.problems.length > 0) {
+      io.stderr.write(`Grouped decision index refresh refused for ${result.indexPath} (D-283 fail-closed):\n`);
+      for (const problem of result.problems) {
+        io.stderr.write(`- ${problem}\n`);
+      }
+      return 1;
+    }
+    if (result.upToDate) {
+      io.stdout.write(`decisions/INDEX.md is up to date (nothing missing).\n`);
+    } else {
+      io.stdout.write(`Refreshed ${result.indexPath} (structure-preserving, D-283)\n`);
+      io.stdout.write(`Added under "## ${result.groupLabel}":\n`);
+      for (const decision of result.added) {
+        io.stdout.write(`- ${formatDecisionId(decision.id)} | ${decision.title} | ${decision.domain}.md\n`);
+      }
+    }
+    return 0;
+  }
+
+  if (parsed.command === 'next-decision-id') {
+    const cwd = runtime.cwd ? path.resolve(runtime.cwd) : process.cwd();
+    const rootDir = path.resolve(cwd, parsed.options.rootDir ?? '.compass');
+    const nextId = await readNextDecisionId(rootDir);
+    io.stdout.write(`Advisory next decision ID: ${formatDecisionId(nextId)}\n`);
+    io.stdout.write(
+      'Allocation happens at write time under the memory-root lock (D-276). Use `vibecompass append-decision`, or re-read the log immediately before appending by hand.\n',
+    );
+    return 0;
+  }
+
   throw new Error(`Unknown command "${parsed.command}".`);
 }
 
@@ -497,6 +672,30 @@ export function parseCliArgs(argv) {
       return parseSwitchSessionArgs(rest);
     }
 
+    if (command === 'rebuild-active-index') {
+      return parseRebuildActiveIndexArgs(rest);
+    }
+
+    if (command === 'write-lane-marker') {
+      return parseWriteLaneMarkerArgs(rest);
+    }
+
+    if (command === 'lane-env') {
+      return parseLaneEnvArgs(rest);
+    }
+
+    if (command === 'append-decision') {
+      return parseAppendDecisionArgs(rest);
+    }
+
+    if (command === 'refresh-decision-index') {
+      return parseRefreshDecisionIndexArgs(rest);
+    }
+
+    if (command === 'next-decision-id') {
+      return parseNextDecisionIdArgs(rest);
+    }
+
     if (command === 'sync-agents') {
       return parseSyncAgentsArgs(rest);
     }
@@ -712,6 +911,16 @@ function parseStartSessionArgs(argv) {
       throw new Error(`Unexpected argument "${token}".`);
     }
 
+    // Boolean flags first (D-281): --worktree takes no value — the container
+    // location is fixed to <workspace>/worktrees/<lane-id> per D-279.
+    if (token === '--worktree') {
+      parsed.worktree = true;
+      continue;
+    }
+    if (token.startsWith('--worktree=')) {
+      throw new Error('Flag "--worktree" takes no value; the worktree container is fixed to <workspace>/worktrees/<lane-id> (D-279).');
+    }
+
     const value = argv[index + 1];
     if (value === undefined) {
       throw new Error(`Flag "${token}" requires a value.`);
@@ -740,6 +949,9 @@ function parseStartSessionArgs(argv) {
       case '--claim':
         parsed.claims = [...(parsed.claims ?? []), value];
         break;
+      case '--branch':
+        parsed.branch = value;
+        break;
       case '--date':
         parsed.date = value;
         break;
@@ -763,6 +975,50 @@ function parseStartSessionArgs(argv) {
   };
 }
 
+function parseLaneEnvArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    if (token === '--json') {
+      parsed.json = true;
+      continue;
+    }
+
+    if (token === '--no-conventional') {
+      parsed.conventionalAliases = false;
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--session':
+        parsed.sessionId = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'lane-env',
+    options: parsed,
+  };
+}
+
 function parseConnectHostedArgs(argv) {
   const parsed = {};
 
@@ -1071,6 +1327,228 @@ function parseListSessionsArgs(argv) {
   };
 }
 
+function parseRebuildActiveIndexArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--current':
+        parsed.current = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return { command: 'rebuild-active-index', options: parsed };
+}
+
+function parseWriteLaneMarkerArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--session':
+        parsed.sessionId = value;
+        break;
+      case '--dir':
+        parsed.dir = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return { command: 'write-lane-marker', options: parsed };
+}
+
+function parseAppendDecisionArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--target':
+        parsed.target = value;
+        break;
+      case '--entry':
+        parsed.entryPath = value;
+        break;
+      case '--group':
+        parsed.groupLabel = value;
+        break;
+      case '--session':
+        parsed.sessionId = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return { command: 'append-decision', options: parsed };
+}
+
+function parseRefreshDecisionIndexArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    if (token === '--check') {
+      parsed.check = true;
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--session':
+        parsed.sessionId = value;
+        break;
+      case '--group':
+        parsed.groupLabel = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return { command: 'refresh-decision-index', options: parsed };
+}
+
+/**
+ * D-280 marker-aware root resolution for the decision-log commands
+ * (append-decision, refresh-decision-index): an explicit --root wins, else the
+ * nearest worktree lane marker supplies the memory root, else cwd/.compass.
+ * Returns the resolved root plus any marker warnings.
+ */
+async function resolveDecisionCommandContext(cwd, options) {
+  const markerContext = await resolveLaneMarkerContext({
+    cwd,
+    explicitRootDir: options.rootDir ?? null,
+    explicitSessionId: options.sessionId ?? null,
+  });
+  const rootDir = markerContext.rootDir;
+  const warnings = [...markerContext.warnings];
+
+  // D-277/D-280: validate an explicit selection signal up front, before the
+  // command decides whether it needs a group label. A `--session` naming a
+  // non-active lane, or a resolved worktree marker that is stale (names a
+  // non-active lane), must fail the command closed even when an explicit
+  // `--group` skips label resolution and even for read-only `--check`. The
+  // 2+-lane no-selection ambiguity carries no explicit signal and is left for
+  // tolerant label handling (a no-op refresh must still succeed there).
+  if (options.sessionId || markerContext.marker) {
+    const sessions = await listProjectSessions({ rootDir, cwd });
+    const selection = resolveLaneSelection({
+      explicitSessionId: options.sessionId ?? null,
+      marker: markerContext.marker,
+      laneIds: sessions.lanes.map((lane) => lane.id),
+      rootDir,
+      purpose: 'run this decision-log command in',
+    });
+    warnings.push(...selection.warnings);
+  }
+
+  return { rootDir, marker: markerContext.marker, warnings };
+}
+
+/**
+ * D-283 auto-labeling for the decision-log commands. Tolerance is narrow: only
+ * the "2+ active lanes with no explicit selection" ambiguity degrades to "no
+ * label" (so a no-op refresh still succeeds and an append still lands with the
+ * hand-refresh reminder). An *explicit* selection signal — a `--session` value
+ * or a resolved worktree marker — must still fail closed on a bad selection
+ * (a `--session` typo naming a non-active lane, or a stale marker) per
+ * D-277/D-280; swallowing those would let `append-decision --session <typo>`
+ * silently append a canonical decision against the wrong/no lane. Selection
+ * warnings are returned so they are no longer discarded.
+ */
+async function resolveIndexGroupLabelSafely(options) {
+  const hasExplicitSelection = Boolean(options.sessionId) || Boolean(options.marker);
+  if (hasExplicitSelection) {
+    // Let a bad explicit selection propagate and fail the command closed.
+    const resolved = await resolveDefaultIndexGroupLabel(options);
+    return { label: resolved?.label ?? null, warnings: resolved?.warnings ?? [] };
+  }
+
+  try {
+    const resolved = await resolveDefaultIndexGroupLabel(options);
+    return { label: resolved?.label ?? null, warnings: resolved?.warnings ?? [] };
+  } catch {
+    // Only the 2+-lane no-selection ambiguity reaches here.
+    return { label: null, warnings: [] };
+  }
+}
+
+function parseNextDecisionIdArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return { command: 'next-decision-id', options: parsed };
+}
+
 function parseSwitchSessionArgs(argv) {
   const parsed = {};
   const positional = [];
@@ -1545,6 +2023,85 @@ function writeRefreshWorkflowResult(io, result) {
   writeAgentFileSyncResult(io, result.agentFileSync);
 }
 
+// D-281 close-side worktree cleanup summary. Status lines stay on stdout;
+// the actionable per-worktree guidance travels on result.warnings (stderr).
+const SURVIVING_WORKTREE_REASON_LABELS = {
+  'container-unverified': 'container marker unverified',
+  'outside-container': 'outside the lane container',
+  'cwd-inside': 'current working directory is inside it',
+  'not-absolute': 'recorded path not absolute',
+  dirty: 'uncommitted changes',
+  'status-unknown': 'cleanliness unknown',
+  'no-source-recorded': 'no recorded source repo',
+  'git-refused': 'git refused the removal',
+};
+
+function writeWorktreeCleanupResult(io, worktreeCleanup) {
+  if (!worktreeCleanup) {
+    return;
+  }
+
+  io.stdout.write('Worktree cleanup:\n');
+  for (const removed of worktreeCleanup.removed) {
+    io.stdout.write(`- ${removed.repoId}: removed ${removed.worktreePath}\n`);
+  }
+  for (const surviving of worktreeCleanup.surviving) {
+    const label = SURVIVING_WORKTREE_REASON_LABELS[surviving.reason] ?? surviving.reason;
+    io.stdout.write(`- ${surviving.repoId}: kept ${surviving.worktreePath} (${label})\n`);
+  }
+  if (worktreeCleanup.markerRemoved) {
+    io.stdout.write('- lane marker removed (token-matched)\n');
+  } else if (worktreeCleanup.markerKept) {
+    io.stdout.write('- lane marker kept while worktrees survive (D-281)\n');
+  }
+  if (worktreeCleanup.containerRemoved) {
+    io.stdout.write('- container removed (empty)\n');
+  }
+  if (worktreeCleanup.branch) {
+    io.stdout.write(`- branch "${worktreeCleanup.branch}" left in place (close-session never deletes branches; D-281)\n`);
+  }
+}
+
+// D-282 close-side lane temp-dir cleanup summary. A missing recorded dir is
+// benign crash residue and prints nothing, matching recorded-but-missing
+// worktrees; guard refusals print the kept path with a short label while the
+// actionable guidance travels on result.warnings (stderr).
+const KEPT_LANE_TMP_REASON_LABELS = {
+  'not-absolute': 'recorded path not absolute',
+  'outside-namespace': 'outside the lane temp namespace',
+  'lane-id-mismatch': "does not end in the lane's id",
+  'cwd-inside': 'current working directory is inside it',
+  'remove-failed': 'removal failed',
+};
+
+function writeRuntimeCleanupResult(io, runtimeCleanup) {
+  if (!runtimeCleanup) {
+    return;
+  }
+
+  if (runtimeCleanup.removed) {
+    io.stdout.write(`Lane temp dir: removed ${runtimeCleanup.tmpDir}\n`);
+    return;
+  }
+
+  if (runtimeCleanup.reason === 'missing') {
+    return;
+  }
+
+  const label = KEPT_LANE_TMP_REASON_LABELS[runtimeCleanup.reason] ?? runtimeCleanup.reason;
+  io.stdout.write(`Lane temp dir: kept ${runtimeCleanup.tmpDir} (${label})\n`);
+}
+
+function shellQuoteSingle(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+/** Preserves order, drops duplicate warning strings (D-283 eager validation
+ * can surface the same selection warning twice). */
+function uniqueStrings(items) {
+  return [...new Set(items)];
+}
+
 function writeDocumentMaintenanceCheckpoint(io, documentMaintenance) {
   if (!documentMaintenance) {
     return;
@@ -1606,11 +2163,17 @@ function usageText() {
     '  vibecompass status [options]',
     '  vibecompass refresh-workflow [--dry-run|--apply] [options]',
     '  vibecompass docs-update [--session <lane-id>] [options]',
-    '  vibecompass start-session --id <lane-id> --working-on <text> [options]',
+    '  vibecompass start-session --id <lane-id> --working-on <text> [--branch <name> [--worktree]] [options]',
     '  vibecompass close-session --title <text> --completed <text> --architecture-docs <status> --decision-log <status> --session-maintenance <status> [options]',
     '  vibecompass end-session --title <text> --completed <text> --architecture-docs <status> --decision-log <status> --session-maintenance <status> [options]  # alias',
     '  vibecompass list-sessions [options]',
     '  vibecompass switch-session <id> [options]',
+    '  vibecompass rebuild-active-index [--current <lane-id>] [options]',
+    '  vibecompass write-lane-marker --session <lane-id> [--dir <path>] [options]',
+    '  vibecompass lane-env [--session <lane-id>] [--json] [--no-conventional] [options]',
+    '  vibecompass append-decision --target <domain.md> --entry <staged-entry.md> [--group <label>] [options]',
+    '  vibecompass refresh-decision-index [--check] [--session <lane-id>] [--group <label>] [options]',
+    '  vibecompass next-decision-id [options]',
     '  vibecompass sync-agents [options]',
     '  vibecompass push [options]',
     '  vibecompass pull-preview [options]',
@@ -1672,30 +2235,32 @@ function usageText() {
     '  --allow-downgrade-templates          Allow applying templates with a CLI older than the root stamp',
     '',
     'Docs-update options:',
-    '  --root <path>                        Project-memory root. Defaults to .compass',
-    '  --session <lane-id>                  Active session lane to inspect; defaults to current lane',
+    '  --root <path>                        Project-memory root. Explicit --root wins; otherwise the nearest worktree lane marker supplies it, else .compass',
+    '  --session <lane-id>                  Active session lane to inspect. Omitted: nearest worktree lane marker, else the single active lane; 2+ active lanes require --session or a marker (D-277)',
     '  --changed <repo:path|path>           Repeatable explicit changed path; defaults to git status when omitted',
     '  --json                               Print the typed docs-update plan as JSON',
     '',
     'Start-session options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
-    '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd',
+    '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd; follows the memory root placement when a marker supplies the root or cwd has no CLAUDE.md under an explicit --root',
     '  --working-on <text>                  Required active-session summary',
     '  --id <lane-id>                       Required active session lane ID',
     '  --feature <slug>                     Repeatable feature slug for the lane',
     '  --repo <id>                          Repeatable repo ID for the lane',
     '  --claim <path>                       Repeatable path claim for overlap warnings',
+    '  --branch <name>                      Opt-in git binding (D-281): create or reuse this branch in every bound --repo; requires at least one --repo',
+    '  --worktree                           With --branch: provision per-repo worktrees under <workspace>/worktrees/<lane-id>/<repo-id> (D-279) and write the lane marker into the container',
     '  --date <YYYY-MM-DD>                  Optional explicit session date',
     '  --last-thing-completed <text>        Optional override for the CLAUDE.md current-session block',
     '  --blockers <text>                    Optional current blockers summary',
     '  --next-session-should <text>         Optional current-session handoff summary',
     '',
     'Close-session options (also accepted by end-session):',
-    '  --root <path>                        Project-memory root. Defaults to .compass',
-    '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd',
+    '  --root <path>                        Project-memory root. Explicit --root wins; otherwise the nearest worktree lane marker supplies it, else .compass',
+    '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd; follows the memory root placement when a marker supplies the root or cwd has no CLAUDE.md under an explicit --root',
     '  --title <text>                       Required display title for the finalized session note',
     '  --worked-on <text>                   Optional override for "What we worked on"',
-    '  --session <lane-id>                  Active session lane to close',
+    '  --session <lane-id>                  Active session lane to close. Omitted: nearest worktree lane marker, else the single active lane; 2+ active lanes require --session or a marker (D-277)',
     '  --completed <text>                   Repeatable completed item',
     '  --decision <text>                    Repeatable decision reference or summary',
     '  --model <text>                       Optional repeatable model contribution entry',
@@ -1711,6 +2276,35 @@ function usageText() {
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --session <lane-id>                  Lane ID for switch-session; positional ID is also accepted',
     '',
+    'Rebuild-active-index options:',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --current <lane-id>                  Explicit current-lane selection; required when multiple lanes are active and the existing pointer is invalid',
+    '',
+    'Write-lane-marker options (D-280):',
+    '  --session <lane-id>                  Required active lane the marker binds to',
+    '  --dir <path>                         Marker target directory; defaults to cwd. Must be path-disjoint from the memory root',
+    '  --root <path>                        Project-memory root. Explicit --root wins; otherwise the nearest worktree lane marker supplies it, else .compass',
+    '',
+    'Lane-env options (D-282):',
+    '  --root <path>                        Project-memory root. Explicit --root wins; otherwise the nearest worktree lane marker supplies it, else .compass',
+    '  --session <lane-id>                  Lane to export. Omitted: nearest worktree lane marker, else the single active lane; 2+ active lanes require --session or a marker (D-277)',
+    '  --json                               Print the runtime assignment as JSON instead of shell export lines',
+    '  --no-conventional                    Omit the conventional PORT/TMPDIR alias exports',
+    '                                        Consume with: eval "$(vibecompass lane-env)"; defaults come from project.yaml runtime.{port_base,port_step,tmp_base}',
+    '',
+    'Decision-log options (append-decision / next-decision-id):',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --target <domain.md>                 Decision domain file under decisions/ (e.g. cross-cutting.md); never INDEX.md',
+    '  --entry <path>                       Staged entry file starting with "### D-NEXT — <title>"; the D-number is allocated atomically at write time (D-276)',
+    '  --group <label>                      Grouped index group label for the D-283 refresh (e.g. "2026-07-03 — Session 3 (lane-x lane)"); defaults to the resolvable lane context',
+    '',
+    'Refresh-decision-index options (D-283):',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --check                              Validate the grouped index against canonical decision entries without writing',
+    '  --session <lane-id>                  Lane whose date/session/id labels a new group; defaults to the D-277 lane resolution',
+    '  --group <label>                      Explicit group label for appended rows; wins over the lane-derived label',
+    '                                        Structure-preserving: existing groups/rows are kept verbatim; unparseable structure fails closed',
+    '',
     'Sync-agents options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Directory where agent files are written. Defaults to cwd',