@vibecompass/vibecompass 0.15.0 → 0.16.0

package/src/cli.js

@@ -5,6 +5,9 @@ import { pathToFileURL } from 'node:url';
 import { connectHostedProjectMemory, initializeProjectMemory, setDefaultSyncTarget } from './init.js';
 import { preflightDocsReview } from './docs-review.js';
 import { planDocsUpdate, renderDocsUpdatePlan } from './docs-update.js';
+import { buildSessionBrief, resolveBriefRequest } from './brief.js';
+import { generateLaneBrief, inspectLaneBrief } from './brief-lifecycle.js';
+import { renderBrief } from './brief-render.js';
 import { resolveConnectHostedCliOptions, resolveInitCliOptions } from './setup.js';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -167,6 +170,7 @@ export async function runCli(argv, io = createDefaultIo(), 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; use --worktree for independently runnable same-repo lanes).\n');
     }
+    writeLifecycleBriefResult(io, result.brief);
     writeWarnings(io, result.warnings);
     writeAgentFileSyncResult(io, result.agentFileSync);
     return 0;
@@ -314,6 +318,94 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'brief' && (parsed.options.write || parsed.options.check)) {
+    // Lane brief (D-364): --write regenerates the lane's brief.md under the
+    // lane root's lock; --check reports its freshness and writes nothing. A
+    // --source-root is only ever read.
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const cwd = runtime.cwd ? path.resolve(runtime.cwd) : process.cwd();
+    const request = await resolveBriefRequest({
+      rootDir: parsed.options.rootDir,
+      sessionId: parsed.options.sessionId,
+      cwd,
+    });
+    if (!request.laneId) {
+      throw new Error(`brief ${parsed.options.write ? '--write' : '--check'} needs an active lane: pass --session <lane-id>, or run it from a lane worktree.`);
+    }
+    const sourceRootDir = parsed.options.sourceRootDir ? path.resolve(cwd, parsed.options.sourceRootDir) : undefined;
+    if (parsed.options.check) {
+      const inspection = await inspectLaneBrief({
+        rootDir: request.rootDir,
+        laneId: request.laneId,
+        sourceRootDir,
+        sourceSessionId: parsed.options.sourceSessionId,
+      });
+      if (parsed.options.json) {
+        io.stdout.write(`${JSON.stringify({
+          lane_id: request.laneId,
+          path: inspection.path,
+          exists: inspection.exists,
+          stale: inspection.stale,
+          reasons: inspection.reasons,
+          status: inspection.status,
+          generated_at: inspection.generatedAt,
+        }, null, 2)}\n`);
+      } else {
+        const state = !inspection.exists ? 'missing' : inspection.stale ? 'stale' : 'current';
+        io.stdout.write(`Brief: ${state}${inspection.status ? ` (status ${inspection.status}${inspection.generatedAt ? `, generated ${inspection.generatedAt}` : ''})` : ''} — ${inspection.path}\n`);
+        for (const reason of inspection.exists ? inspection.reasons : []) {
+          io.stdout.write(`- ${reason}\n`);
+        }
+      }
+      writeWarnings(io, request.warnings);
+      return 0;
+    }
+
+    const generated = await generateLaneBrief({
+      rootDir: request.rootDir,
+      laneId: request.laneId,
+      sourceRootDir,
+      sourceSessionId: parsed.options.sourceSessionId,
+      ...(parsed.options.budget !== undefined ? { budget: parsed.options.budget } : {}),
+    });
+    if (parsed.options.json) {
+      io.stdout.write(`${JSON.stringify({ lane_id: request.laneId, ...generated }, null, 2)}\n`);
+    } else {
+      const from = generated.source?.adapter ? ` from ${generated.source.root_dir}` : '';
+      io.stdout.write(`Brief: ${generated.status}${generated.state === 'written' ? '' : ` (${generated.state}: ${generated.reason})`} — wrote ${generated.path}${from}\n`);
+    }
+    writeWarnings(io, [...request.warnings, ...generated.warnings]);
+    return generated.state === 'written' ? 0 : 1;
+  }
+
+  if (parsed.command === 'brief') {
+    // Strictly read-only (plan task A3): no manifest refresh, state write,
+    // lane write, or agent-file sync, so it is safe against a legacy root.
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const request = await resolveBriefRequest({
+      rootDir: parsed.options.rootDir,
+      sessionId: parsed.options.sessionId,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    const result = await buildSessionBrief({
+      rootDir: request.rootDir,
+      laneId: request.laneId,
+      task: parsed.options.task,
+      files: parsed.options.files,
+      featureSlugs: parsed.options.featureSlugs,
+      claims: parsed.options.claims,
+      budget: parsed.options.budget,
+    });
+    const markdown = renderBrief(result);
+    if (parsed.options.json) {
+      io.stdout.write(`${JSON.stringify({ ...result, lane_source: request.laneSource, cli_warnings: request.warnings, markdown }, null, 2)}\n`);
+    } else {
+      io.stdout.write(markdown);
+    }
+    writeWarnings(io, request.warnings);
+    return 0;
+  }
+
   if (parsed.command === 'close-session' || parsed.command === 'end-session') {
     await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await closeProjectSession({
@@ -360,6 +452,9 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
       io.stdout.write('Read next:\n');
       io.stdout.write(`- ${result.wipFilePath}\n`);
       io.stdout.write(`- ${result.handoffFilePath}\n`);
+      if (result.brief?.path && result.brief.state !== 'off' && !(result.brief.state === 'failed' && !result.brief.status)) {
+        io.stdout.write(`- ${result.brief.path} (session brief — read before planning)\n`);
+      }
       if (result.latestFinalizedSessionPath) {
         io.stdout.write(`- ${result.latestFinalizedSessionPath} (latest finalized note)\n`);
       }
@@ -377,6 +472,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
           io.stdout.write(`- ${lane.id}: ${lane.workingOn ?? 'No summary recorded'}\n`);
         }
       }
+      writeLifecycleBriefResult(io, result.brief);
     }
     writeWarnings(io, result.warnings);
     writeAgentFileSyncResult(io, result.agentFileSync);
@@ -824,6 +920,10 @@ export function parseCliArgs(argv) {
       return parseDocsUpdateArgs(rest);
     }
 
+    if (command === 'brief') {
+      return parseBriefArgs(rest);
+    }
+
     if (command === 'close-session' || command === 'end-session') {
       return parseCloseSessionArgs(rest);
     }
@@ -1100,6 +1200,10 @@ function parseStartSessionArgs(argv) {
     if (token.startsWith('--worktree=')) {
       throw new Error('Flag "--worktree" takes no value; the worktree container is fixed to <workspace>/worktrees/<lane-id> (D-279).');
     }
+    if (token === '--no-brief') {
+      parsed.brief = false;
+      continue;
+    }
 
     const value = argv[index + 1];
     if (value === undefined) {
@@ -1857,6 +1961,105 @@ function parseDocsUpdateArgs(argv) {
   };
 }
 
+function parseBriefArgs(argv) {
+  const parsed = {
+    files: [],
+    featureSlugs: [],
+    claims: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--json') {
+      parsed.json = true;
+      continue;
+    }
+    if (token === '--write' || token === '--check') {
+      parsed[token.slice(2)] = true;
+      continue;
+    }
+
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+      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 '--source-root':
+        parsed.sourceRootDir = value;
+        break;
+      case '--source-session':
+        parsed.sourceSessionId = value;
+        break;
+      case '--task':
+        parsed.task = value;
+        break;
+      case '--files':
+      case '--file':
+        // `--files a b c` and repeated `--files a --files b` both work.
+        parsed.files.push(value);
+        while (argv[index + 1] !== undefined && !argv[index + 1].startsWith('--')) {
+          index += 1;
+          parsed.files.push(argv[index]);
+        }
+        break;
+      case '--feature':
+        parsed.featureSlugs.push(value);
+        break;
+      case '--claim':
+        parsed.claims.push(value);
+        break;
+      case '--budget':
+        if (!/^\d+$/.test(value)) {
+          throw new Error(`--budget must be a whole number of estimated tokens (got "${value}").`);
+        }
+        parsed.budget = Number(value);
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  if (parsed.write && parsed.check) {
+    throw new Error('Choose one of --write (regenerate the lane brief) or --check (report its freshness).');
+  }
+  if (parsed.write || parsed.check) {
+    const laneDerived = [
+      parsed.task !== undefined && '--task',
+      parsed.files.length > 0 && '--files',
+      parsed.featureSlugs.length > 0 && '--feature',
+      parsed.claims.length > 0 && '--claim',
+      parsed.check && parsed.budget !== undefined && '--budget',
+    ].filter(Boolean);
+    if (laneDerived.length > 0) {
+      throw new Error(
+        `${laneDerived.join(', ')} cannot be combined with ${parsed.write ? '--write' : '--check'}: a lane brief takes its task from the lane's working-on, its files from the lane's claims, and its features from the lane's feature slugs (update them with continue-session --working-on or the lane metadata).`,
+      );
+    }
+  } else if (parsed.sourceRootDir || parsed.sourceSessionId) {
+    throw new Error('--source-root and --source-session apply only to --write or --check; to print a brief of another root, pass --root.');
+  }
+  if (parsed.sourceSessionId && !parsed.sourceRootDir) {
+    throw new Error('--source-session requires --source-root.');
+  }
+
+  return {
+    command: 'brief',
+    options: parsed,
+  };
+}
+
 function parseListSessionsArgs(argv) {
   const parsed = {};
 
@@ -2130,6 +2333,10 @@ function parseContinueSessionArgs(argv) {
       parsed.json = true;
       continue;
     }
+    if (token === '--no-brief') {
+      parsed.brief = false;
+      continue;
+    }
 
     const value = argv[index + 1];
     if (value === undefined) {
@@ -2147,6 +2354,12 @@ function parseContinueSessionArgs(argv) {
       case '--session':
         parsed.sessionId = value;
         break;
+      case '--source-root':
+        parsed.sourceRootDir = value;
+        break;
+      case '--source-session':
+        parsed.sourceSessionId = value;
+        break;
       case '--working-on':
         parsed.workingOn = value;
         break;
@@ -2179,6 +2392,13 @@ function parseContinueSessionArgs(argv) {
     parsed.sessionId = positional[0];
   }
 
+  if (parsed.brief === false && (parsed.sourceRootDir || parsed.sourceSessionId)) {
+    throw new Error('--no-brief cannot be combined with --source-root or --source-session.');
+  }
+  if (parsed.sourceSessionId && !parsed.sourceRootDir) {
+    throw new Error('--source-session requires --source-root.');
+  }
+
   return {
     command: 'continue-session',
     options: parsed,
@@ -2890,6 +3110,31 @@ function writeWarnings(io, warnings = []) {
   }
 }
 
+/** One status line for the lifecycle brief (D-364); failures also arrive as warnings. */
+function writeLifecycleBriefResult(io, brief) {
+  if (!brief) return;
+  const location = brief.path ? ` — ${brief.path}` : '';
+  const from = brief.source?.adapter ? ` (from ${brief.source.root_dir})` : '';
+  switch (brief.state) {
+    case 'off':
+      io.stdout.write(`Brief: off (${brief.reason})\n`);
+      return;
+    case 'kept':
+      io.stdout.write(`Brief: current, kept (status ${brief.status ?? 'unknown'}${brief.generatedAt ? `, generated ${brief.generatedAt}` : ''})${location}\n`);
+      return;
+    case 'regenerated':
+      io.stdout.write(`Brief: regenerated, ${brief.status}${from} (was stale: ${(brief.staleReasons ?? []).join('; ') || 'unknown'})${location}\n`);
+      return;
+    case 'written':
+      io.stdout.write(`Brief: ${brief.status}${from}${location}\n`);
+      return;
+    default:
+      io.stdout.write(brief.status
+        ? `Brief: incomplete (${brief.state}: ${brief.reason})${location}\n`
+        : 'Brief: not written (see warning)\n');
+  }
+}
+
 function splitAssignment(value, flagName) {
   const separatorIndex = value.indexOf('=');
   if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
@@ -2919,10 +3164,14 @@ 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> [--branch <name> [--worktree]] [options]',
+    '  vibecompass brief --task <text> [--files <repo:path>...] [--feature <slug>] [--claim <path>] [--session <lane-id>] [--budget <n>] [--json] [options]',
+    '                                        Read-only session brief: relevant memory, packed into an estimated token budget',
+    '  vibecompass brief --write|--check [--session <lane-id>] [--source-root <path> [--source-session <lane-id>]] [--budget <n>] [--json] [options]',
+    '                                        Regenerate the lane\'s sessions/active/<lane-id>/brief.md, or report whether it is stale (D-364)',
+    '  vibecompass start-session --id <lane-id> --working-on <text> [--branch <name> [--worktree]] [--no-brief] [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 continue-session [<lane-id>] [--session <lane-id>] [--working-on <text>] [--json] [options]',
+    '  vibecompass continue-session [<lane-id>] [--session <lane-id>] [--working-on <text>] [--no-brief | --source-root <path>] [--json] [options]',
     '  vibecompass list-sessions [--json] [options]',
     '  vibecompass switch-session <id> [options]',
     '  vibecompass rebuild-active-index [--current <lane-id>] [options]',
@@ -3048,6 +3297,7 @@ function usageText() {
     '  --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',
+    '  --no-brief                           Skip the lane brief for this command (sessions/active/<lane-id>/brief.md; D-359, D-364); lifecycle commands write it only when project.yaml sets brief.enabled: true (opt-in, D-368)',
     '',
     'Close-session options (also accepted by end-session):',
     '  --root <path>                        Project-memory root. Explicit --root wins; otherwise the nearest worktree lane marker supplies it, else .compass',
@@ -3075,7 +3325,23 @@ function usageText() {
     '  --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',
-    '  --json                               Print the resume result (lane, paths, runtime, other lanes, warnings) as JSON',
+    '  --json                               Print the resume result (lane, paths, runtime, other lanes, brief, warnings) as JSON',
+    '  --no-brief                           Leave the lane brief as it is; with project.yaml brief.enabled: true (opt-in, D-368) resume keeps a current brief and regenerates a missing or stale one',
+    '  --source-root <path>                 D-255 dual-root dogfood: build the brief from this memory root\'s matching lane (same id, session date, and number) and write it only into this lane; the source root is only read',
+    '  --source-session <lane-id>           With --source-root: the source lane id, which must equal the resumed lane',
+    '',
+    'Brief options:',
+    '  --root <path>                        Project-memory root. Explicit --root wins; otherwise the nearest worktree lane marker supplies it, else .compass',
+    '  --session <lane-id>                  Lane to brief. Omitted: nearest worktree lane marker, else the single active lane; 2+ active lanes require --session or a marker (D-277)',
+    '  --task <text>                        Task text (print mode). Omitted: the lane\'s working-on',
+    '  --files <repo:path>...               Files the task touches (print mode)',
+    '  --feature <slug>, --claim <path>     Repeatable feature slug and path claim (print mode)',
+    '  --budget <n>                         Estimated-token budget (default 6000, minimum 800)',
+    '  --write                              Regenerate the lane\'s brief.md from its working-on, claims, and feature slugs, under the root lock',
+    '  --check                              Report whether the lane\'s brief.md is current or stale against its header bindings; writes nothing',
+    '  --source-root <path>                 With --write/--check: read this memory root\'s matching lane instead (D-255 dogfood); never written',
+    '  --source-session <lane-id>           With --source-root: the source lane id, which must equal the lane being briefed',
+    '  --json                               Print the result as JSON',
     '',
     'List/switch-session options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',