@vibecompass/vibecompass 0.14.0 → 0.16.0

package/src/scaffold.js

@@ -226,6 +226,7 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 - \`${rootRelativePath}/sessions/active/<lane-id>/session.yaml\` — lane metadata (including the recorded \`lane_marker\` when one exists)
 - \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\` — lane-local builder scratchpad
 - \`${rootRelativePath}/sessions/active/<lane-id>/handoff.md\` — lane-local builder/reviewer relay
+- \`${rootRelativePath}/sessions/active/<lane-id>/brief.md\` — generated session brief (D-359, D-364): the memory this lane should read first, written by \`start-session\` and \`continue-session\` when \`brief.enabled: true\` (opt-in, D-368) or on request with \`vibecompass brief --write\`; never hand-edit
 - \`.vibecompass-lane.yaml\` — worktree-local lane marker (D-280); lives outside the memory root, written only by \`vibecompass write-lane-marker\` or worktree provisioning, never synced
 - \`${rootRelativePath}/decisions/INDEX.md\` — derived grouped decision index; refresh with \`vibecompass refresh-decision-index\` (D-283, structure-preserving) instead of hand-editing rows
 
@@ -233,6 +234,7 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 - VibeCompass active builder sessions are named lanes. Use one lane per active feature or workstream.
 - \`vibecompass start-session\` requires \`--id <lane-id>\` so each active lane has a meaningful feature or workstream name.
 - The active lane scratch files live under \`${rootRelativePath}/sessions/active/<lane-id>/\`.
+- When \`${rootRelativePath}/project.yaml\` sets \`brief.enabled: true\` (opt-in, D-368), \`start-session\` and \`continue-session\` write the lane's generated \`brief.md\` (D-359, D-364): the task is the lane's working-on, the files its claims, and the features its feature slugs. A brief failure is reported as a warning or an incomplete brief and never fails the lifecycle command. \`--no-brief\` skips it for one command, \`vibecompass brief --session <lane-id> --write\` writes one on request whatever the setting, and \`brief.exclude\` lists root-relative globs the brief must never read.
 - Lane selection follows D-277: an explicit \`--session\` wins, then the nearest worktree lane marker (\`.vibecompass-lane.yaml\`, walking up from cwd), then the single active lane. With two or more active lanes there is no implicit current-lane fallback.
 - \`${rootRelativePath}/sessions/active/index.yaml\` is the lane inventory; its \`current\` pointer and the tool-specific Current session block are human-readable continuity summaries, not the lane-selection source of truth.
 - An active lane directory is an open session, not an unclosed crash (D-353). Resume it with \`vibecompass continue-session [<lane-id>]\`: the lane keeps its opening date and session number; the command records \`resumed_at\`/\`resume_count\` in \`session.yaml\`, appends a dated \`Resumed\` line to \`wip.md\`, moves the index \`current\` hint and the Current session block to the lane, and re-emits runtime, git-binding, and staleness warnings. \`start-session --id <existing-lane>\` fails closed and names \`continue-session\`.
@@ -276,7 +278,8 @@ ${renderWorkflowDefaults(workflow)}
 3. Inventory active lanes with \`vibecompass list-sessions\` (or read \`${rootRelativePath}/sessions/active/index.yaml\`), then follow the "Open, resume, or choose" protocol below to decide between opening a new lane and resuming one; select a lane from an explicit \`--session\`, the nearest worktree lane marker, or the single active lane (D-277).
 4. If present, read \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\`.
 5. If present, read \`${rootRelativePath}/sessions/active/<lane-id>/handoff.md\`.
-6. Read the relevant docs under \`${rootRelativePath}/architecture/\` and \`${rootRelativePath}/decisions/\`.
+6. If present, read \`${rootRelativePath}/sessions/active/<lane-id>/brief.md\` before planning: the generated session brief selects the architecture docs, decisions (with their declared successors), and notes for the lane's task. Its status line says whether it is complete, partial, incomplete (read the listed required reads first), or no-match; \`vibecompass brief --check\` reports whether it is stale.
+7. Read the relevant docs under \`${rootRelativePath}/architecture/\` and \`${rootRelativePath}/decisions/\`, starting from the brief's units and follow-up reads.
 
 ## Open, resume, or choose (D-353)
 Both \`start session\` and \`continue session\` begin with the active-lane inventory. Then:
@@ -284,7 +287,7 @@ Both \`start session\` and \`continue session\` begin with the active-lane inven
 - **Exactly one active lane, or a cwd bound to a lane by a worktree marker:** resume it with \`vibecompass continue-session\` without asking. Open a second lane only when the user is clearly asking for separate new work; never re-open a lane that already exists.
 - **Two or more active lanes, no marker, no lane named by the user:** do not guess. Present the inventory (lane id, working-on, opened date, resume count, branch/worktree, last log line) and ask which lane to continue or whether to open a new one. The index \`current\` pointer and the Current session block are continuity hints to mention, never defaults to adopt silently. Resume with \`vibecompass continue-session <lane-id>\` once the user answers (\`continue session <lane-id>\`).
 - **Lane named by the user:** \`continue session <lane-id>\` resumes that lane; an unknown id fails closed with the inventory.
-- After resuming, read the lane's \`wip.md\` (latest \`## Log\` entries and \`## Reviewer input needed\`), \`handoff.md\`, and the latest finalized note; treat resume-staleness warnings (new decisions past the lane snapshot, stale base revisions, newer finalized notes touching the lane scope, claim overlap) as required reading before editing.
+- After resuming, read the lane's \`wip.md\` (latest \`## Log\` entries and \`## Reviewer input needed\`), \`handoff.md\`, \`brief.md\` if present (with \`brief.enabled: true\`, continue-session keeps a current brief and regenerates a missing or stale one), and the latest finalized note; treat resume-staleness warnings (new decisions past the lane snapshot, stale base revisions, newer finalized notes touching the lane scope, claim overlap) as required reading before editing.
 - Run recovery (reconstruct a missing finalized note from git history) only when the Current session block date is in the past *and* no active lane exists *and* no finalized note covers that date. An active lane with a past date is simply resumable.
 
 ## Builder workflow
@@ -302,6 +305,8 @@ Session lane: <lane-id>
 
 ## Reviewer input needed
 
+## Context used
+
 ## Review log
 \`\`\`
 
@@ -330,6 +335,8 @@ Session lane: <lane-id>
 During the session:
 - append short summaries to \`wip.md\` after meaningful exchanges
 - keep \`handoff.md\` current after substantive work blocks
+- optionally list under \`wip.md\` \`## Context used\` the docs and decisions the lane actually relied on (path or D-number, and what for), so the brief's usefulness can be audited
+- refresh the lane brief with \`vibecompass brief --write\` after the lane's scope changes; \`vibecompass brief --check\` reports whether it is stale
 - run \`eval "$(vibecompass lane-env)"\` in a lane shell before starting dev servers or build tools so the lane's assigned port and temp dir are used (D-282); do not hardcode ports in lane work
 - run \`vibecompass docs-update --session <lane-id>\` whenever you need an ad hoc targeted documentation-maintenance plan for the current session delta
 - after substantive feature work, confirm affected architecture docs and decisions still match the implementation; if not, update them while the context is fresh — fold the changes into the doc's current-state sections (rewrite in place; no dated "update" sections, lane names in headings, or completed-task chronology; D-292)
@@ -588,6 +595,7 @@ Finalized session notes for ${projectConfig.name} live here.
 - \`active/<lane-id>/session.yaml\` — lane metadata, including the recorded \`lane_marker\` when one exists
 - \`active/<lane-id>/wip.md\` — builder scratchpad during an active lane
 - \`active/<lane-id>/handoff.md\` — reviewer/builder baton-pass during an active lane
+- \`active/<lane-id>/brief.md\` — generated session brief for the lane (D-359, D-364); regenerated, never hand-edited
 
 Those scratch files are session-scoped working artifacts, not finalized history.
 `;

package/src/secret-prompt.js

@@ -0,0 +1,64 @@
+import { createInterface } from 'node:readline/promises';
+import { Writable } from 'node:stream';
+
+/**
+ * Hidden-input prompt for secrets (D-355). Typed characters are never echoed:
+ * readline runs in terminal mode against a muted output while the visible
+ * prompt text is written to the real stdout. A `runtime.prompt` adapter
+ * (tests, embedders) receives `{ type: 'password', message }` instead.
+ */
+export function canPromptSecret(io = {}, runtime = {}) {
+  if (typeof runtime.prompt === 'function') {
+    return true;
+  }
+  const input = runtime.stdin ?? io.stdin ?? process.stdin;
+  return Boolean(input?.isTTY);
+}
+
+export async function promptSecret(message, io = {}, runtime = {}) {
+  if (typeof runtime.prompt === 'function') {
+    return normalizeSecret(await runtime.prompt({ type: 'password', message }));
+  }
+
+  const input = runtime.stdin ?? io.stdin ?? process.stdin;
+  const output = io.stdout ?? process.stdout;
+  if (!input?.isTTY) {
+    throw new Error('Secret prompts require an interactive terminal. Pipe the value with --token-stdin instead.');
+  }
+
+  output.write(`${message}: `);
+  const muted = new Writable({
+    write(_chunk, _encoding, callback) {
+      callback();
+    },
+  });
+  const rl = createInterface({ input, output: muted, terminal: true });
+  try {
+    return normalizeSecret(await rl.question(''));
+  } finally {
+    rl.close();
+    output.write('\n');
+  }
+}
+
+/** Reads one secret from stdin: the first non-empty line, trimmed. */
+export async function readSecretFromStdin(io = {}, runtime = {}) {
+  const input = runtime.stdin ?? io.stdin ?? process.stdin;
+  if (typeof input?.setEncoding === 'function') {
+    input.setEncoding('utf8');
+  }
+  let data = '';
+  for await (const chunk of input) {
+    data += chunk;
+  }
+  const firstLine = data
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line !== '');
+  return firstLine ?? null;
+}
+
+function normalizeSecret(value) {
+  const trimmed = String(value ?? '').trim();
+  return trimmed === '' ? null : trimmed;
+}

package/src/session.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { access, mkdir, readFile, readdir, realpath, rm, rmdir, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { refreshLaneBriefForLifecycle } from './brief-lifecycle.js';
 import { scanProjectMemory } from './project-memory.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { buildCloseSessionGuidance, resolveWorkflowSettings } from './workflow.js';
@@ -398,6 +399,16 @@ async function startProjectSessionLocked(normalized, options, markerContext) {
     rootDir: normalized.rootDir,
     toolingRootDir: normalized.toolingRootDir,
   });
+  // D-359/D-364/D-368: the opt-in lane brief is written only after every
+  // lifecycle write succeeded, still inside the memory-root lock; it never
+  // throws, so a brief failure cannot overturn the start.
+  const brief = await refreshLaneBriefForLifecycle({
+    trigger: 'start',
+    rootDir: normalized.rootDir,
+    laneId: sessionId,
+    disabled: options?.brief === false,
+    buildBrief: options?.briefBuilder,
+  });
 
   return {
     rootDir: normalized.rootDir,
@@ -420,7 +431,9 @@ async function startProjectSessionLocked(normalized, options, markerContext) {
       ...(gitBinding?.warnings ?? []),
       ...manifestRefresh.warnings,
       ...auditWarnings,
+      ...brief.warnings,
     ],
+    brief,
     ...(gitBinding
       ? {
           gitBinding: {
@@ -1145,6 +1158,18 @@ async function continueProjectSessionLocked(normalized, options, markerContext)
     rootDir: normalized.rootDir,
     toolingRootDir: normalized.toolingRootDir,
   });
+  // D-359/D-364: keep a current lane brief, regenerate a missing or stale
+  // one. `--source-root` (D-255 dogfood) is read only when named here; it is
+  // never inferred from the existing brief's header.
+  const brief = await refreshLaneBriefForLifecycle({
+    trigger: 'continue',
+    rootDir: normalized.rootDir,
+    laneId: lane.id,
+    disabled: options?.brief === false,
+    sourceRootDir: options?.sourceRootDir ? path.resolve(normalized.cwd, options.sourceRootDir) : undefined,
+    sourceSessionId: normalizeOptionalString(options?.sourceSessionId) ?? undefined,
+    buildBrief: options?.briefBuilder,
+  });
   const finalizedSessions = await listFinalizedSessions(normalized.sessionsDir);
   const latestFinalized = finalizedSessions.length > 0 ? finalizedSessions[finalizedSessions.length - 1] : null;
   // The returned inventory is the post-resume state (what list-sessions shows
@@ -1181,6 +1206,7 @@ async function continueProjectSessionLocked(normalized, options, markerContext)
     otherLanes: inventoryAfter.lanes.filter((item) => item.id !== lane.id),
     inventory: inventoryAfter,
     docsUpdatePlan: docsUpdate.plan,
+    brief,
     warnings: [
       ...markerContext.warnings,
       ...selection.warnings,
@@ -1196,6 +1222,7 @@ async function continueProjectSessionLocked(normalized, options, markerContext)
       }),
       ...docsUpdate.warnings,
       ...manifestRefresh.warnings,
+      ...brief.warnings,
     ],
     manifest: manifestRefresh.manifest,
     agentFileSync,
@@ -2279,6 +2306,9 @@ ${options.workingOn}
 ## Reviewer input needed
 - None yet.
 
+## Context used
+- Optional: the docs and decisions this lane actually relied on (path or D-number, and what for) — an audit trail for the session brief; list what you used, not everything the brief showed.
+
 ## Review log
 `;
 }

package/src/status.js

@@ -5,6 +5,7 @@ import { sha256Text } from './hash.js';
 import { resolveLaneMarkerContext } from './lane-marker.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { resolveSyncBinding } from './sync-binding.js';
+import { describeCredentialSource, resolveSyncCredential } from './credential-store.js';
 import { inferToolingRootForMemoryRoot, listProjectSessions } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
 import { scanProjectMemory } from './project-memory.js';
@@ -68,6 +69,7 @@ export async function getProjectStatus(options = {}) {
       docsReview,
       agentFiles,
       projectMemory,
+      hostedSync,
     }),
   };
 }
@@ -125,6 +127,7 @@ export function renderStatusText(status) {
       : status.hostedSync?.status === 'unreachable'
         ? [`Hosted mode check: unreachable (${status.hostedSync.detail}).`]
         : []),
+    ...formatHostedSyncLines(status.hostedSync),
     `Root: ${status.rootDir}`,
     `Repos: ${status.project.repos.length > 0 ? status.project.repos.map((repo) => repo.id).join(', ') : 'None recorded'}`,
     `Active lanes: ${formatActiveLanes(status.sessions)}`,
@@ -207,16 +210,36 @@ async function readHostedModeCheck(projectFilePath, localMode, options = {}) {
   }
   if (!binding) return { status: 'not-configured' };
 
-  const env = options.env ?? process.env;
-  const credential = typeof env[binding.credentialEnvVar] === 'string'
-    ? env[binding.credentialEnvVar].trim()
-    : '';
+  const bindingSummary = {
+    apiUrl: binding.apiUrl,
+    projectId: binding.projectId,
+    target: binding.target ?? null,
+    credentialEnvVar: binding.credentialEnvVar,
+  };
+  // D-355: report only the source of the credential (env / keychain / file /
+  // missing), never its value.
+  const resolution = await resolveSyncCredential(binding, {
+    env: options.env ?? process.env,
+    ...(options.credentialStore ?? {}),
+  });
+  const credential = resolution.credential;
+  const credentialSource = credential ? resolution.source : 'missing';
+  const credentialSourceLabel = credential ? describeCredentialSource(resolution) : 'missing';
   if (!credential) {
-    return { status: 'no-credential', credentialEnvVar: binding.credentialEnvVar };
+    return {
+      status: 'no-credential',
+      credentialEnvVar: binding.credentialEnvVar,
+      credentialSource,
+      credentialSourceLabel,
+      ...(resolution.detail ? { detail: resolution.detail } : {}),
+      binding: bindingSummary,
+    };
   }
 
   const fetchImpl = options.fetch ?? globalThis.fetch;
-  if (typeof fetchImpl !== 'function') return { status: 'not-configured' };
+  if (typeof fetchImpl !== 'function') {
+    return { status: 'not-configured', credentialSource, credentialSourceLabel, binding: bindingSummary };
+  }
 
   const baseUrl = binding.apiUrl.endsWith('/') ? binding.apiUrl : `${binding.apiUrl}/`;
   const endpoint = new URL(
@@ -234,7 +257,7 @@ async function readHostedModeCheck(projectFilePath, localMode, options = {}) {
       signal: controller.signal,
     });
     if (!response.ok) {
-      return { status: 'unreachable', detail: `HTTP ${response.status}` };
+      return { status: 'unreachable', detail: `HTTP ${response.status}`, credentialSource, credentialSourceLabel, binding: bindingSummary };
     }
     const data = typeof response.json === 'function' ? await response.json() : {};
     const hostedMode = typeof data.mode === 'string' ? data.mode : null;
@@ -243,9 +266,12 @@ async function readHostedModeCheck(projectFilePath, localMode, options = {}) {
       hostedMode,
       localMode,
       mismatch: Boolean(hostedMode && localMode && hostedMode !== localMode),
+      credentialSource,
+      credentialSourceLabel,
+      binding: bindingSummary,
     };
   } catch (error) {
-    return { status: 'unreachable', detail: error?.message ?? 'network error' };
+    return { status: 'unreachable', detail: error?.message ?? 'network error', credentialSource, credentialSourceLabel, binding: bindingSummary };
   } finally {
     clearTimeout(timer);
   }
@@ -460,13 +486,32 @@ async function readProjectMemoryStatus(rootDir) {
   }
 }
 
-function buildRecommendations({ project, compatibility, sessions, docsReview, agentFiles, projectMemory }) {
+function formatHostedSyncLines(hostedSync) {
+  if (!hostedSync?.binding) {
+    return [];
+  }
+  const { binding } = hostedSync;
+  const where = `${binding.apiUrl} (project ${binding.projectId}${binding.target ? `, target ${binding.target}` : ''})`;
+  const credential = hostedSync.credentialSource === 'missing'
+    ? `missing${hostedSync.detail ? ` (${hostedSync.detail})` : ''} — run \`vibecompass login\` to sign in from this terminal`
+    : hostedSync.credentialSourceLabel ?? hostedSync.credentialSource;
+  return [
+    `Hosted sync: ${where}`,
+    `Sync credential: ${credential}`,
+  ];
+}
+
+function buildRecommendations({ project, compatibility, sessions, docsReview, agentFiles, projectMemory, hostedSync }) {
   const recommendations = [];
   if (project.status === 'unreadable') {
     recommendations.push('vibecompass init --guided');
     return recommendations;
   }
 
+  if (hostedSync?.status === 'no-credential') {
+    recommendations.push('vibecompass login');
+  }
+
   const packageStatus = compatibility.package.status;
   const stateStatus = compatibility.state.status;
   if (['legacy', 'behind', 'ahead', 'invalid'].includes(packageStatus) || ['missing', 'unreadable', 'unsupported'].includes(stateStatus)) {

package/src/sync.js

@@ -4,6 +4,11 @@ import { sha256Text } from './hash.js';
 import { writeStateManifest } from './manifest.js';
 import { withMemoryRootLock } from './serialization.js';
 import { parseSimpleYaml } from './simple-yaml.js';
+import {
+  credentialStoreOptionsFrom,
+  formatMissingCredentialError,
+  resolveSyncCredential,
+} from './credential-store.js';
 import {
   buildSyncStateWithCursor,
   readSyncCursor,
@@ -465,12 +470,14 @@ async function loadSyncContext(options, environment) {
     throw new Error('Hosted sync commands require sync.api_url, sync.project_id, and sync.credential_env_var in project.yaml (or a named target under sync.targets).');
   }
 
-  const credential = normalizeOptionalString((environment.env ?? process.env)[binding.credentialEnvVar]);
+  // D-355: env var override first, then the local credential store
+  // (keychain or per-user file). The resolved value is used only as the
+  // bearer credential and never written anywhere.
+  const resolution = await resolveSyncCredential(binding, credentialStoreOptionsFrom(environment));
+  const credential = resolution.credential;
   if (!credential) {
     throw new Error(
-      `Hosted sync command requires ${binding.credentialEnvVar}. New terminals do not inherit one-off exports: `
-      + `re-export it (export ${binding.credentialEnvVar}="<sync token>") or persist it in your shell profile (~/.zshenv or ~/.bashrc). `
-      + 'Lost the token? Rotate it on the hosted dashboard under Setup -> Hosted sync, then export the new value.',
+      formatMissingCredentialError(binding, { action: 'This hosted sync command', detail: resolution.detail }),
     );
   }
 
@@ -485,6 +492,7 @@ async function loadSyncContext(options, environment) {
     manifestPath,
     fetch: fetchImpl,
     credential,
+    credentialSource: resolution.source,
     apiUrl: binding.apiUrl,
     projectId: binding.projectId,
     syncTarget: binding.target,