@vibecompass/vibecompass 0.2.0 → 0.3.0

package/src/session.js

@@ -1,5 +1,6 @@
 import { access, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { scanProjectMemory } from './project-memory.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { buildCloseSessionGuidance, resolveWorkflowSettings } from './workflow.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
@@ -36,6 +37,18 @@ export async function startProjectSession(options) {
   const claude = await readClaudeFile(normalized.claudePath);
   const sessionId = await resolveStartSessionId(normalized, options);
   const lanePaths = getLanePaths(normalized, sessionId);
+  const features = normalizeStringArray(options?.features);
+  const repos = normalizeStringArray(options?.repos);
+  const claims = normalizeStringArray(options?.claims);
+  const existingLanes = await listActiveSessionLanes(normalized);
+  const overlapWarnings = buildOverlapWarnings({
+    sessionId,
+    features,
+    repos,
+    claims,
+    existingLanes,
+  });
+  const highestDecisionId = await readHighestDecisionId(normalized.rootDir);
 
   const nextSessionNumber = await getNextSessionNumber(normalized.sessionsDir, sessionDate);
   const currentSession = parseCurrentSessionBlock(claude.content);
@@ -68,9 +81,10 @@ export async function startProjectSession(options) {
       sessionDate,
       sessionNumber: nextSessionNumber,
       workingOn,
-      features: normalizeStringArray(options?.features),
-      repos: normalizeStringArray(options?.repos),
-      claims: normalizeStringArray(options?.claims),
+      features,
+      repos,
+      claims,
+      highestDecisionId,
     }),
     'utf8',
   );
@@ -99,6 +113,12 @@ export async function startProjectSession(options) {
     status: 'active',
     workingOn,
   }, { current: sessionId });
+  const auditWarnings = await buildDocsReviewWarnings(normalized);
+  const metadataWarnings = collectLaneMetadataWarnings(existingLanes);
+  const agentFileSync = await syncAgentInstructionFilesSafely({
+    rootDir: normalized.rootDir,
+    toolingRootDir: normalized.toolingRootDir,
+  });
 
   return {
     rootDir: normalized.rootDir,
@@ -110,6 +130,12 @@ export async function startProjectSession(options) {
     handoffFilePath: lanePaths.handoffFilePath,
     sessionDate,
     sessionNumber: nextSessionNumber,
+    warnings: [
+      ...metadataWarnings,
+      ...overlapWarnings,
+      ...auditWarnings,
+    ],
+    agentFileSync,
   };
 }
 
@@ -185,9 +211,10 @@ export async function closeProjectSession(options) {
   );
 
   const hadHandoff = await fileExists(lanePaths.handoffFilePath);
+  let activeSessionIndex = null;
   if (sessionId) {
     await rm(lanePaths.laneDir, { recursive: true, force: true });
-    await removeActiveSessionFromIndex(normalized, sessionId);
+    activeSessionIndex = await removeActiveSessionFromIndex(normalized, sessionId);
   } else {
     await rm(lanePaths.wipFilePath, { force: true });
     if (hadHandoff) {
@@ -195,16 +222,22 @@ export async function closeProjectSession(options) {
     }
   }
 
-  const updatedClaude = replaceCurrentSessionBlock(claude.content, {
-    date: `${activeSession.sessionDate} (session ${activeSession.sessionNumber})`,
-    workingOn: 'Session closed. Ready for the next builder session.',
-    lastThingCompleted:
-      normalizeOptionalString(options?.lastThingCompleted) ??
-      `Closed session ${activeSession.sessionNumber} and wrote \`${sessionRelativePath}\`.`,
-    blockers: blockers.length > 0 ? summarizeList(blockers) : 'No blocker remains.',
-    nextSessionShould:
-      normalizeOptionalString(options?.nextSessionShould) ?? summarizeOrderedList(nextSteps),
-  });
+  const closedSummary = `Closed session ${activeSession.sessionNumber} and wrote \`${sessionRelativePath}\`.`;
+  const updatedClaude = replaceCurrentSessionBlock(
+    claude.content,
+    activeSessionIndex?.current
+      ? buildCurrentSessionFieldsForLane(activeSessionIndex.lanes.find((lane) => lane.id === activeSessionIndex.current), {
+          lastThingCompleted: normalizeOptionalString(options?.lastThingCompleted) ?? closedSummary,
+        })
+      : {
+          date: `${activeSession.sessionDate} (session ${activeSession.sessionNumber})`,
+          workingOn: 'Session closed. Ready for the next builder session.',
+          lastThingCompleted: normalizeOptionalString(options?.lastThingCompleted) ?? closedSummary,
+          blockers: blockers.length > 0 ? summarizeList(blockers) : 'No blocker remains.',
+          nextSessionShould:
+            normalizeOptionalString(options?.nextSessionShould) ?? summarizeOrderedList(nextSteps),
+        },
+  );
 
   await writeFile(normalized.claudePath, updatedClaude, 'utf8');
   const agentFileSync = await syncAgentInstructionFilesSafely({
@@ -248,17 +281,35 @@ export async function switchProjectSession(options = {}) {
   const normalized = normalizeSessionPaths(options);
   const sessionId = validateLaneId(requireNonEmptyString(options?.sessionId, 'switch-session requires a session ID.'));
   const lanes = await listActiveSessionLanes(normalized);
+  const lane = lanes.find((item) => item.id === sessionId);
 
-  if (!lanes.some((lane) => lane.id === sessionId)) {
+  if (!lane) {
     throw new Error(`Active session lane "${sessionId}" does not exist.`);
   }
 
   await upsertActiveSessionIndex(normalized, null, { current: sessionId });
+  const claude = await readClaudeFile(normalized.claudePath);
+  await writeFile(
+    normalized.claudePath,
+    replaceCurrentSessionBlock(
+      claude.content,
+      buildCurrentSessionFieldsForLane(lane, {
+        lastThingCompleted: `Switched current lane to ${sessionId}.`,
+      }),
+    ),
+    'utf8',
+  );
+  const agentFileSync = await syncAgentInstructionFilesSafely({
+    rootDir: normalized.rootDir,
+    toolingRootDir: normalized.toolingRootDir,
+  });
 
   return {
     rootDir: normalized.rootDir,
+    claudePath: normalized.claudePath,
     current: sessionId,
     lanes,
+    agentFileSync,
   };
 }
 
@@ -284,6 +335,26 @@ async function syncAgentInstructionFilesSafely(options) {
   }
 }
 
+async function buildDocsReviewWarnings(normalized) {
+  const markerPath = path.join(normalized.rootDir, 'state', 'docs-review.json');
+  try {
+    const marker = JSON.parse(await readFile(markerPath, 'utf8'));
+    if (marker && marker.status === 'completed') {
+      return [];
+    }
+  } catch (error) {
+    if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')) {
+      return [
+        `Docs-review marker at ${markerPath} is unreadable. Starter docs are not a comprehensive architecture review; run "vibecompass docs-review --guided" before risky implementation work.`,
+      ];
+    }
+  }
+
+  return [
+    `No docs-review marker found at ${markerPath}. Starter docs are not a comprehensive architecture review; run "vibecompass docs-review --guided" before risky implementation work.`,
+  ];
+}
+
 function normalizeSessionPaths(options) {
   const cwd = options?.cwd ? path.resolve(options.cwd) : process.cwd();
   const rootDir = path.resolve(cwd, options?.rootDir ?? '.compass');
@@ -397,6 +468,26 @@ function replaceCurrentSessionBlock(content, fields) {
   return `${content.slice(0, sessionFence.bodyStart)}${blockBody}${content.slice(sessionFence.bodyEnd)}`;
 }
 
+function buildCurrentSessionFieldsForLane(lane, overrides = {}) {
+  if (!lane) {
+    throw new Error('Cannot update the Current session block without active lane metadata.');
+  }
+
+  const sessionDate = lane.sessionDate ?? normalizeSessionDate();
+  const sessionNumber = lane.sessionNumber || 0;
+  const workingOn = lane.workingOn ?? 'No summary recorded.';
+
+  return {
+    date: `${sessionDate} (session ${sessionNumber}, lane ${lane.id})`,
+    workingOn: `${workingOn} [${lane.id}]`,
+    lastThingCompleted:
+      overrides.lastThingCompleted ?? 'Current lane selected from `sessions/active/index.yaml`.',
+    blockers: overrides.blockers ?? 'No blocker recorded for the selected lane.',
+    nextSessionShould:
+      overrides.nextSessionShould ?? 'Continue the selected active lane from `sessions/active/index.yaml`.',
+  };
+}
+
 async function getNextSessionNumber(sessionsDir, sessionDate) {
   const sessions = await listFinalizedSessions(sessionsDir);
   const activeSessions = await listActiveSessionLanes({ sessionsDir, activeSessionsDir: path.join(sessionsDir, 'active') });
@@ -414,18 +505,13 @@ async function resolveStartSessionId(normalized, options) {
     return validateLaneId(explicitId);
   }
 
-  const lanes = await listActiveSessionLanes(normalized);
-  if (lanes.length > 0) {
-    throw new Error('Active session lanes already exist. Pass --id to start another lane explicitly.');
-  }
-
   if ((await fileExists(normalized.wipFilePath)) || (await fileExists(normalized.handoffFilePath))) {
     throw new Error(
       `Legacy active session scratch files already exist under ${normalized.sessionsDir}. Close or recover that session before starting a lane.`,
     );
   }
 
-  return 'default';
+  throw new Error('start-session requires --id <lane-id> so each active lane has a meaningful name.');
 }
 
 async function resolveExistingSessionId(normalized, options) {
@@ -466,6 +552,9 @@ async function listActiveSessionLanes(normalized) {
         features: metadata.features,
         repos: metadata.repos,
         claims: metadata.claims,
+        startedAt: metadata.startedAt,
+        decisionSnapshot: metadata.decisionSnapshot,
+        warnings: metadata.warnings,
         sessionDate: metadata.sessionDate ?? wipSession?.sessionDate ?? null,
         sessionNumber: metadata.sessionNumber ?? wipSession?.sessionNumber ?? 0,
       });
@@ -499,18 +588,30 @@ async function readLaneMetadata(sessionFilePath) {
       features: normalizeStringArray(data.feature_slugs),
       repos: normalizeStringArray(data.repos),
       claims: normalizeStringArray(data.claimed_paths),
+      startedAt: normalizeOptionalString(data.started_at),
+      decisionSnapshot: {
+        highestDecisionId: parseNullableNumber(data.decision_snapshot?.highest_decision_id),
+      },
       sessionDate: normalizeOptionalString(data.session_date),
       sessionNumber: typeof data.session_number === 'number' ? data.session_number : Number(data.session_number) || null,
+      warnings: [],
     };
-  } catch {
+  } catch (error) {
     return {
       status: null,
       workingOn: null,
       features: [],
       repos: [],
       claims: [],
+      startedAt: null,
+      decisionSnapshot: {
+        highestDecisionId: null,
+      },
       sessionDate: null,
       sessionNumber: null,
+      warnings: [
+        `Could not parse ${sessionFilePath}: ${error instanceof Error ? error.message : String(error)}`,
+      ],
     };
   }
 }
@@ -547,16 +648,28 @@ async function upsertActiveSessionIndex(normalized, lane, options = {}) {
   await writeFile(normalized.activeSessionsIndexPath, renderActiveSessionIndex(current, [...laneMap.values()]), 'utf8');
 }
 
+/**
+ * Removes a closed lane from the active index and returns the surviving lane
+ * state used to refresh the Current session block. `lanes` contains the full
+ * lane metadata read from each sibling lane's `session.yaml` / `wip.md`.
+ */
 async function removeActiveSessionFromIndex(normalized, sessionId) {
   const index = await readActiveSessionIndex(normalized);
   const lanes = (await listActiveSessionLanes(normalized)).filter((lane) => lane.id !== sessionId);
   const current = index.current === sessionId ? lanes[0]?.id ?? null : index.current;
   if (lanes.length === 0) {
     await rm(normalized.activeSessionsIndexPath, { force: true });
-    return;
+    return {
+      current: null,
+      lanes,
+    };
   }
 
   await writeFile(normalized.activeSessionsIndexPath, renderActiveSessionIndex(current, lanes), 'utf8');
+  return {
+    current,
+    lanes,
+  };
 }
 
 async function listFinalizedSessions(sessionsDir) {
@@ -721,9 +834,9 @@ function renderLaneMetadata(options) {
     renderYamlArray('feature_slugs', options.features),
     renderYamlArray('repos', options.repos),
     renderYamlArray('claimed_paths', options.claims),
-    `started_at: ${new Date().toISOString()}`,
+    `started_at: ${formatLocalDateTime(new Date())}`,
     'decision_snapshot:',
-    '  highest_decision_id: null',
+    `  highest_decision_id: ${options.highestDecisionId ?? 'null'}`,
     '',
   ].join('\n');
 }
@@ -835,6 +948,124 @@ function normalizeSessionDate(value) {
   ].join('-');
 }
 
+async function readHighestDecisionId(rootDir) {
+  try {
+    const scanResult = await scanProjectMemory(rootDir);
+    const decisionIds = scanResult.documents.flatMap((document) => document.extracted?.decision_ids ?? []);
+    return decisionIds.reduce((max, id) => Math.max(max, id), 0) || null;
+  } catch {
+    return null;
+  }
+}
+
+function buildOverlapWarnings(options) {
+  const warnings = [];
+  for (const lane of options.existingLanes) {
+    const sharedFeatures = intersect(options.features, lane.features ?? []);
+    if (sharedFeatures.length > 0) {
+      warnings.push(
+        `Active session lane "${options.sessionId}" overlaps "${lane.id}" on feature(s): ${sharedFeatures.join(', ')}.`,
+      );
+    }
+
+    const claimOverlaps = findClaimOverlaps(options.claims, lane.claims ?? []);
+    for (const overlap of claimOverlaps) {
+      warnings.push(
+        `Active session lane "${options.sessionId}" overlaps "${lane.id}" on claimed path ${overlap.repo}:${overlap.path}.`,
+      );
+    }
+
+    const sharedRepos = intersect(options.repos, lane.repos ?? []);
+    if (sharedRepos.length > 0 && options.claims.length === 0 && (lane.claims ?? []).length === 0) {
+      warnings.push(
+        `Active session lane "${options.sessionId}" shares repo(s) ${sharedRepos.join(', ')} with "${lane.id}" without path claims; add --claim values to clarify ownership.`,
+      );
+    }
+  }
+
+  return warnings;
+}
+
+function collectLaneMetadataWarnings(lanes) {
+  return lanes.flatMap((lane) => lane.warnings ?? []);
+}
+
+function intersect(left, right) {
+  const rightSet = new Set(right);
+  return left.filter((item) => rightSet.has(item));
+}
+
+function findClaimOverlaps(leftClaims, rightClaims) {
+  const overlaps = [];
+  for (const left of leftClaims.map(parseClaim).filter(Boolean)) {
+    for (const right of rightClaims.map(parseClaim).filter(Boolean)) {
+      if (left.repo !== right.repo) {
+        continue;
+      }
+
+      if (pathPrefixesOverlap(left.path, right.path)) {
+        overlaps.push({
+          repo: left.repo,
+          path: left.path.length <= right.path.length ? left.path : right.path,
+        });
+      }
+    }
+  }
+
+  return overlaps;
+}
+
+function parseClaim(value) {
+  const separatorIndex = value.indexOf(':');
+  if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
+    return null;
+  }
+
+  return {
+    repo: value.slice(0, separatorIndex),
+    path: normalizeClaimPath(value.slice(separatorIndex + 1)),
+  };
+}
+
+function normalizeClaimPath(value) {
+  return value.replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+function pathPrefixesOverlap(left, right) {
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+function parseNullableNumber(value) {
+  if (value === null || value === undefined) {
+    return null;
+  }
+
+  const number = typeof value === 'number' ? value : Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function formatLocalDateTime(date) {
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const absOffset = Math.abs(offsetMinutes);
+  const offset = `${sign}${String(Math.floor(absOffset / 60)).padStart(2, '0')}:${String(absOffset % 60).padStart(2, '0')}`;
+
+  return [
+    date.getFullYear(),
+    '-',
+    String(date.getMonth() + 1).padStart(2, '0'),
+    '-',
+    String(date.getDate()).padStart(2, '0'),
+    'T',
+    String(date.getHours()).padStart(2, '0'),
+    ':',
+    String(date.getMinutes()).padStart(2, '0'),
+    ':',
+    String(date.getSeconds()).padStart(2, '0'),
+    offset,
+  ].join('');
+}
+
 function requireNonEmptyString(value, message) {
   const normalized = normalizeOptionalString(value);
   if (!normalized) {

package/src/setup.js

@@ -40,6 +40,10 @@ export async function resolveInitCliOptions(options, environment = {}) {
     throw new Error('init requires --session-working-on when --start-session is used without guided setup.');
   }
 
+  if (resolved.startSession && !resolved.sessionId) {
+    throw new Error('init requires --session-id when --start-session is used.');
+  }
+
   return {
     initOptions: {
       rootDir: resolved.rootDir,
@@ -62,6 +66,7 @@ export async function resolveInitCliOptions(options, environment = {}) {
     guidedSummary,
     sessionPlan: resolved.startSession
       ? {
+          sessionId: resolved.sessionId,
           workingOn: resolved.sessionWorkingOn,
         }
       : null,
@@ -278,6 +283,15 @@ async function completeGuidedInitOptions(options, environment) {
     if (!resolved.sessionWorkingOn) {
       resolved.sessionWorkingOn = await askInput(prompter, 'What are you working on?');
     }
+
+    if (!resolved.sessionId) {
+      resolved.sessionId = await askInput(prompter, 'Session lane id', {
+        defaultValue: suggestLaneId(resolved.sessionWorkingOn),
+        validate(value) {
+          return validateLaneIdForPrompt(value);
+        },
+      });
+    }
   }
 
   if (resolved.closeSessionGitPublish === undefined && (resolved.bootstrap.workflow || resolved.startSession)) {
@@ -669,6 +683,46 @@ function suggestRepoId(value) {
   return slug || 'repo';
 }
 
+function suggestLaneId(value) {
+  const slug = String(value ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 63)
+    .replace(/-+$/g, '');
+
+  return slug.length >= 3 ? slug : 'builder-session';
+}
+
+function validateLaneIdForPrompt(value) {
+  if (!/^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/.test(value)) {
+    return 'Lane id must be 3-64 lowercase letters, numbers, or hyphens, and must start and end with a letter or number.';
+  }
+
+  if ([
+    'active',
+    'current',
+    'default',
+    'false',
+    'handoff',
+    'index',
+    'new',
+    'no',
+    'null',
+    'off',
+    'on',
+    'sessions',
+    'state',
+    'true',
+    'wip',
+    'yes',
+  ].includes(value)) {
+    return `Lane id "${value}" is reserved.`;
+  }
+
+  return null;
+}
+
 function getRepoDirectoryHints(repo) {
   const hints = new Set();