@vibecompass/vibecompass 0.3.4 → 0.5.0

package/src/compatibility.js

@@ -0,0 +1,308 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { STATE_VERSION } from './manifest.js';
+import { parseSimpleYaml } from './simple-yaml.js';
+import { PACKAGE_VERSION } from './version.js';
+
+/**
+ * Inspect root compatibility without writing files.
+ * `packageVersion` is a test override; production callers should omit it.
+ */
+export async function inspectProjectCompatibility(options = {}) {
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  const cliPackageVersion = normalizePackageVersion(options.packageVersion ?? PACKAGE_VERSION);
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const manifestPath = path.join(rootDir, 'state', 'manifest.json');
+  const warnings = [];
+
+  const project = await readProjectStamp(projectFilePath);
+  const manifest = await readManifestState(manifestPath);
+  const packageStatus = project.status === 'unreadable'
+    ? {
+        status: 'unknown',
+        rootVersion: null,
+        cliVersion: cliPackageVersion,
+        errorMessage: project.errorMessage,
+      }
+    : buildPackageStatus(project.packageVersion, cliPackageVersion);
+  const stateStatus = buildStateStatus(manifest);
+  // Package and state statuses intentionally use different vocabularies:
+  // canonical package-stamp drift is distinct from derived-state drift.
+
+  if (packageStatus.status === 'unknown') {
+    warnings.push(warning({
+      code: 'project-yaml-unreadable',
+      message: `project.yaml is unreadable. ${packageStatus.errorMessage}`,
+      errorMessage: packageStatus.errorMessage,
+    }));
+  } else if (packageStatus.status === 'legacy') {
+    warnings.push(warning({
+      code: 'package-version-legacy-root',
+      message: 'project.yaml has no metadata.package_version stamp; treating the root as legacy/unknown.',
+      cliVersion: cliPackageVersion,
+    }));
+  } else if (packageStatus.status === 'behind') {
+    warnings.push(warning({
+      code: 'package-version-behind',
+      message: `project.yaml metadata.package_version ${packageStatus.rootVersion} is older than CLI package ${cliPackageVersion}.`,
+      rootVersion: packageStatus.rootVersion,
+      cliVersion: cliPackageVersion,
+    }));
+  } else if (packageStatus.status === 'ahead') {
+    warnings.push(warning({
+      code: 'package-version-ahead',
+      message: `project.yaml metadata.package_version ${packageStatus.rootVersion} is newer than CLI package ${cliPackageVersion}.`,
+      rootVersion: packageStatus.rootVersion,
+      cliVersion: cliPackageVersion,
+    }));
+  } else if (packageStatus.status === 'invalid') {
+    warnings.push(warning({
+      code: 'package-version-invalid',
+      message: 'project.yaml metadata.package_version is present but is not a non-empty semver string.',
+      rootVersion: packageStatus.rootVersion,
+      cliVersion: cliPackageVersion,
+    }));
+  }
+
+  if (stateStatus.status === 'missing') {
+    warnings.push(warning({
+      code: 'state-manifest-missing',
+      message: 'state/manifest.json is missing; commands that need derived state can regenerate it.',
+    }));
+  } else if (stateStatus.status === 'unreadable') {
+    warnings.push(warning({
+      code: 'state-manifest-unreadable',
+      message: `state/manifest.json is unreadable; commands that need derived state can discard and regenerate it. ${stateStatus.errorMessage}`,
+      errorMessage: stateStatus.errorMessage,
+    }));
+  } else if (stateStatus.status === 'unsupported') {
+    warnings.push(warning({
+      code: 'state-version-unsupported',
+      message: `state/manifest.json state_version ${stateStatus.observedVersion} is unsupported by this CLI (expected ${STATE_VERSION}); commands that need derived state can regenerate it.`,
+      observedVersion: stateStatus.observedVersion,
+      expectedVersion: STATE_VERSION,
+      packageObservedVersion: stateStatus.packageObservedVersion,
+    }));
+  }
+
+  return {
+    rootDir,
+    projectFilePath,
+    manifestPath,
+    cliPackageVersion,
+    package: packageStatus,
+    state: stateStatus,
+    warnings,
+  };
+}
+
+export function formatCompatibilityWarnings(result) {
+  return (result?.warnings ?? []).map((warning) => warning.message);
+}
+
+async function readProjectStamp(projectFilePath) {
+  try {
+    const config = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+      sourceName: projectFilePath,
+    });
+    const metadata = isPlainObject(config.metadata) ? config.metadata : {};
+    return {
+      status: 'ok',
+      packageVersion: Object.hasOwn(metadata, 'package_version')
+        ? metadata.package_version
+        : undefined,
+    };
+  } catch (error) {
+    return {
+      status: 'unreadable',
+      packageVersion: undefined,
+      errorMessage: error instanceof Error ? error.message : 'Unable to read project.yaml.',
+    };
+  }
+}
+
+async function readManifestState(manifestPath) {
+  try {
+    return {
+      status: 'ok',
+      manifest: JSON.parse(await readFile(manifestPath, 'utf8')),
+    };
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return { status: 'missing' };
+    }
+
+    return {
+      status: 'unreadable',
+      errorMessage: error instanceof Error ? error.message : 'Unable to read state/manifest.json.',
+    };
+  }
+}
+
+function buildPackageStatus(rootVersion, cliPackageVersion) {
+  if (rootVersion === undefined) {
+    return {
+      status: 'legacy',
+      rootVersion: null,
+      cliVersion: cliPackageVersion,
+    };
+  }
+
+  if (typeof rootVersion !== 'string' || rootVersion.trim() === '') {
+    return {
+      status: 'invalid',
+      rootVersion,
+      cliVersion: cliPackageVersion,
+    };
+  }
+
+  const normalizedRootVersion = normalizePackageVersion(rootVersion);
+  if (!parseSemver(normalizedRootVersion)) {
+    return {
+      status: 'invalid',
+      rootVersion,
+      cliVersion: cliPackageVersion,
+    };
+  }
+
+  const comparison = comparePackageVersions(normalizedRootVersion, cliPackageVersion);
+
+  return {
+    status: comparison === 0 ? 'current' : comparison < 0 ? 'behind' : 'ahead',
+    rootVersion: normalizedRootVersion,
+    cliVersion: cliPackageVersion,
+  };
+}
+
+function buildStateStatus(manifestResult) {
+  if (manifestResult.status === 'missing') {
+    return { status: 'missing' };
+  }
+
+  if (manifestResult.status === 'unreadable') {
+    return {
+      status: 'unreadable',
+      errorMessage: manifestResult.errorMessage,
+    };
+  }
+
+  const manifest = manifestResult.manifest;
+  if (manifest?.state_version !== STATE_VERSION) {
+    return {
+      status: 'unsupported',
+      observedVersion: manifest?.state_version ?? null,
+      expectedVersion: STATE_VERSION,
+      packageObservedVersion:
+        typeof manifest?.package?.observed_version === 'string'
+          ? manifest.package.observed_version
+          : null,
+    };
+  }
+
+  return {
+    status: 'current',
+    observedVersion: manifest.state_version,
+    expectedVersion: STATE_VERSION,
+    packageObservedVersion:
+      typeof manifest?.package?.observed_version === 'string'
+        ? manifest.package.observed_version
+        : null,
+  };
+}
+
+function comparePackageVersions(left, right) {
+  const leftSemver = parseSemver(left);
+  const rightSemver = parseSemver(right);
+  if (!leftSemver || !rightSemver) {
+    return 0;
+  }
+
+  const leftParts = [leftSemver.major, leftSemver.minor, leftSemver.patch];
+  const rightParts = [rightSemver.major, rightSemver.minor, rightSemver.patch];
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] < rightParts[index]) {
+      return -1;
+    }
+    if (leftParts[index] > rightParts[index]) {
+      return 1;
+    }
+  }
+
+  return comparePrerelease(leftSemver.prerelease, rightSemver.prerelease);
+}
+
+function parseSemver(version) {
+  const match = String(version).match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split('.') : [],
+  };
+}
+
+function comparePrerelease(left, right) {
+  if (left.length === 0 && right.length === 0) {
+    return 0;
+  }
+
+  if (left.length === 0) {
+    return 1;
+  }
+
+  if (right.length === 0) {
+    return -1;
+  }
+
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = left[index];
+    const rightPart = right[index];
+    if (leftPart === undefined) {
+      return -1;
+    }
+    if (rightPart === undefined) {
+      return 1;
+    }
+
+    const leftNumeric = /^\d+$/.test(leftPart);
+    const rightNumeric = /^\d+$/.test(rightPart);
+    if (leftNumeric && rightNumeric) {
+      const difference = Number(leftPart) - Number(rightPart);
+      if (difference !== 0) {
+        return difference < 0 ? -1 : 1;
+      }
+      continue;
+    }
+
+    if (leftNumeric !== rightNumeric) {
+      return leftNumeric ? -1 : 1;
+    }
+
+    const comparison = leftPart.localeCompare(rightPart);
+    if (comparison !== 0) {
+      return comparison < 0 ? -1 : 1;
+    }
+  }
+
+  return 0;
+}
+
+function normalizePackageVersion(version) {
+  return String(version).trim();
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function warning(fields) {
+  return Object.fromEntries(
+    Object.entries(fields).filter(([, value]) => value !== undefined),
+  );
+}

package/src/docs-review.js

@@ -59,8 +59,10 @@ export async function preflightDocsReview(options = {}, environment = {}) {
   const localProvider = resolveLocalProvider(options);
   const runtime = resolveDocsReviewRuntime(project, {
     env,
+    guided: Boolean(options.guided),
     localProvider,
     runLocal: shouldRunLocal(options),
+    anthropicEnvVar: options.anthropicEnvVar ?? 'ANTHROPIC_API_KEY',
   });
   const reviewPrompt = renderReviewPrompt({
     project,
@@ -180,14 +182,19 @@ async function applyDocsReviewOutput(options) {
   const blocks = parseArchitectureDocBlocks(source);
 
   if (blocks.length === 0) {
+    const malformedFenceCount = countMalformedArchitectureDocFences(source);
+    if (malformedFenceCount > 0) {
+      throw new Error(
+        `Malformed architecture doc fence found in ${outputPath}. Expected fence openings like \`\`\`vibecompass-architecture-doc path=architecture/domain/feature/component.md\` with exactly one path attribute and no extra attributes.`,
+      );
+    }
+
     throw new Error(
       `No accepted architecture doc blocks found in ${outputPath}. Expected fenced blocks like \`\`\`vibecompass-architecture-doc path=architecture/domain/feature/component.md\`.`,
     );
   }
 
-  for (const block of blocks) {
-    validateArchitectureDocBlock(block);
-  }
+  validateArchitectureDocBlocks(blocks);
 
   const applied = [];
   for (const block of blocks) {
@@ -357,6 +364,13 @@ function validateDocsReviewMode(options) {
 }
 
 async function promptForReviewConfig(options, environment) {
+  if (options.llm && options.model) {
+    return normalizeReviewConfig({
+      llm: options.llm,
+      model: options.model,
+    });
+  }
+
   const prompter = createPrompter(environment.io, environment.runtime);
   try {
     if (!options.llm) {
@@ -485,6 +499,10 @@ function resolveDocsReviewRuntime(project, options) {
       };
     }
 
+    if (options.guided) {
+      return { provider: 'external' };
+    }
+
     throw new Error(
       `docs-review for local-primary projects requires a hosted sync binding or ${options.anthropicEnvVar}.`,
     );
@@ -601,6 +619,32 @@ function parseArchitectureDocBlocks(source) {
   return blocks;
 }
 
+function countMalformedArchitectureDocFences(source) {
+  const fencePattern = /^```vibecompass-architecture-doc\b.*$/gm;
+  const acceptedOpeningPattern = /^```vibecompass-architecture-doc\s+path=[^\s`]+\s*$/;
+  let count = 0;
+  let match;
+
+  while ((match = fencePattern.exec(source)) !== null) {
+    if (!acceptedOpeningPattern.test(match[0])) {
+      count += 1;
+    }
+  }
+
+  return count;
+}
+
+function validateArchitectureDocBlocks(blocks) {
+  const seenPaths = new Set();
+  for (const block of blocks) {
+    if (seenPaths.has(block.path)) {
+      throw new Error(`Accepted docs-review output contains duplicate architecture doc path: ${block.path}`);
+    }
+    seenPaths.add(block.path);
+    validateArchitectureDocBlock(block);
+  }
+}
+
 function normalizeBlockPath(value) {
   return String(value ?? '').trim().replaceAll('\\', '/');
 }
@@ -625,7 +669,10 @@ function validateArchitectureDocBlock(block) {
     throw new Error(`Accepted architecture doc ${block.path} must include frontmatter.`);
   }
 
-  for (const field of ['domain', 'feature', 'component', 'status']) {
+  const requiredFields = block.path === 'architecture/overview/project-shape.md'
+    ? ['status']
+    : ['domain', 'feature', 'component', 'status'];
+  for (const field of requiredFields) {
     if (typeof frontmatter.data[field] !== 'string' || frontmatter.data[field].trim() === '') {
       throw new Error(`Accepted architecture doc ${block.path} requires non-empty frontmatter field "${field}".`);
     }

package/src/generators/agent-files/index.js

@@ -8,6 +8,7 @@ import { claudeMdFormat } from './claude-md.js';
 import { agentsMdFormat } from './agents-md.js';
 import { cursorRulesFormat } from './cursor-rules.js';
 import { copilotInstructionsFormat } from './copilot-instructions.js';
+import { getWorkflowConflictScanPatterns } from '../../workflows/registry.js';
 
 const FORMATS = [
   claudeMdFormat,
@@ -17,17 +18,7 @@ const FORMATS = [
 ];
 
 const FORMAT_MAP = new Map(FORMATS.map((format) => [format.name, format]));
-const CONFLICT_SCAN_PATTERNS = [
-  'session',
-  'handoff',
-  'decisions',
-  'wip.md',
-  'review handoff',
-  'close-session',
-  'address review',
-  'builder',
-  'reviewer',
-];
+const CONFLICT_SCAN_PATTERNS = getWorkflowConflictScanPatterns();
 
 export async function syncAgentInstructionFiles(options = {}) {
   const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();

package/src/generators/agent-files/template.js

@@ -1,3 +1,5 @@
+import { renderPromptCommandLines } from '../../workflows/registry.js';
+
 export function buildAgentContext(readModel) {
   return {
     projectName: readModel.project.name ?? 'Unnamed project',
@@ -16,47 +18,40 @@ export function renderSharedInstructionBody(context, options = {}) {
   const intro =
     options.intro ??
     'Use VibeCompass project memory as the source of truth before making code changes.';
+  const contextPath = `${context.rootDir}/context.md`;
 
   return [
     `# ${heading}`,
     '',
     intro,
     '',
-    `Read \`${context.rootDir}/context.md\` for the full VibeCompass workflow protocol when it exists.`,
+    `This managed block is a compact bootloader. Read \`${contextPath}\` for the full VibeCompass workflow protocol; workflow-specific details live under \`${context.rootDir}/workflows/\`.`,
     '',
     'Existing project-specific coding, style, framework, and safety instructions outside this managed block remain authoritative. This block owns only VibeCompass project-memory workflow: sessions, handoffs, decisions, docs-review, and close-out.',
     '',
-    '## Read First',
+    '## Project Snapshot',
     `- Project memory root: \`${context.rootDir}\``,
-    '- Read `project.yaml` for project identity, repos, mode, and workflow defaults.',
-    '- Read the latest finalized session note under `sessions/` before resuming work.',
-    '- Read `sessions/active/index.yaml` when it exists, then read the selected lane under `sessions/active/<lane-id>/`.',
-    '- Read the selected lane `wip.md` and `handoff.md` when they exist; they are the active builder/reviewer scratch files.',
-    '- Read relevant `architecture/` and `decisions/` files before changing implementation.',
+    ...renderProjectSnapshot(context),
     '',
-    '## Project Shape',
-    ...renderProjectShape(context),
+    '## Read Order',
+    `1. Read \`${contextPath}\`.`,
+    `2. Read the latest finalized session note under \`${context.rootDir}/sessions/\`.`,
+    `3. If present, read \`${context.rootDir}/sessions/active/index.yaml\`, then the selected lane's \`wip.md\` and \`handoff.md\`.`,
+    `4. Read relevant \`${context.rootDir}/architecture/\` and \`${context.rootDir}/decisions/\` docs before editing implementation.`,
     '',
-    '## Workflow Rules',
-    '- VibeCompass active builder sessions are named lanes. Use one lane per active feature or workstream; finalized session notes are append-only history under `sessions/YYYY-MM-DD-N-title.md`.',
-    '- Use `start session` for builder work, `join as reviewer` for review work, and `close session` / `end session` when the builder is ready to close the selected lane.',
-    '- Use `vibecompass start-session --id <lane-id>` to open a named lane for every active feature or workstream.',
-    '- Use `vibecompass list-sessions` and `vibecompass switch-session <lane-id>` to inspect or change the current lane.',
-    '- Treat `sessions/active/index.yaml` as the current lane source of truth; tool-specific Current session blocks are continuity summaries.',
-    '- Use optional planning mode for risky or ambiguous work: read the same context, propose scope, and record the agreed plan in the selected lane `wip.md` before implementation.',
-    '- Use `review handoff` to ask a reviewer to inspect the active handoff.',
-    '- Use `address review` to process reviewer feedback from the selected lane `wip.md` and `handoff.md`.',
-    '- End the active builder session with the `close session` prompt, which runs close-out and ends with `vibecompass close-session --session <lane-id>`; `end session` and `vibecompass end-session` are accepted aliases.',
-    '- If stale scratch files block `start-session`, read them first, then close, recover, move, or delete them intentionally before retrying.',
-    '- Keep decisions append-only in `decisions/`. Session notes may reference decisions, but decisions are the durable source of truth.',
-    '- Treat generated agent files as views. Update canonical VibeCompass project memory instead of editing managed regions.',
+    '## Prompt Commands',
+    ...renderPromptCommandLines({ rootRelativePath: context.rootDir }),
+    '- The prompt commands above are agent behaviors. The `vibecompass` CLI commands remain the filesystem mechanics behind them.',
     '',
-    '## Recent Decisions',
-    ...renderDecisionLines(context.recentDecisions),
+    '## Hard Rules',
+    '- Treat `sessions/active/index.yaml` as the current lane source of truth; tool-specific Current session blocks are continuity summaries.',
+    '- Keep the selected lane `wip.md` and `handoff.md` current during active builder/reviewer work.',
+    '- Keep decisions append-only in `decisions/`; append accepted architectural decisions before implementing them.',
+    '- Do not edit this managed block directly. Update canonical VibeCompass memory, then rerun package commands such as `vibecompass sync-agents`.',
   ].join('\n');
 }
 
-function renderProjectShape(context) {
+function renderProjectSnapshot(context) {
   const lines = [];
 
   if (context.description) {
@@ -71,18 +66,22 @@ function renderProjectShape(context) {
     lines.push(`- Repo \`${repo.id}\`: ${repo.remote}`);
   }
 
-  for (const domain of context.domains.slice(0, 8)) {
-    const features = domain.features.map((feature) => feature.feature).join(', ');
-    lines.push(`- ${domain.domain}: ${features || 'No features recorded yet.'}`);
+  const domainCount = context.domains.length;
+  if (domainCount > 0) {
+    lines.push(`- Architecture domains recorded: ${domainCount}`);
   }
 
-  return lines.length > 0 ? lines : ['- No architecture domains recorded yet.'];
-}
+  if (context.recentDecisions.length > 0) {
+    lines.push(`- Latest decision: ${renderDecisionLine(context.recentDecisions[0])}`);
+  }
 
-function renderDecisionLines(decisions) {
-  if (!decisions || decisions.length === 0) {
-    return ['- No decisions recorded yet.'];
+  if (context.recentSessions.length > 0) {
+    lines.push(`- Latest session: ${context.recentSessions[0].title ?? context.recentSessions[0].path}`);
   }
 
-  return decisions.map((decision) => `- D-${String(decision.decision_id).padStart(3, '0')} — ${decision.title}`);
+  return lines.length > 0 ? lines : ['- No project details recorded yet.'];
+}
+
+function renderDecisionLine(decision) {
+  return `D-${String(decision.decision_id).padStart(3, '0')} — ${decision.title}`;
 }

package/src/index.js

@@ -1,4 +1,8 @@
-export { STATE_VERSION, generateStateManifest, writeStateManifest } from './manifest.js';
+export { STATE_VERSION, generateStateManifest, prepareStateManifest, writeStateManifest } from './manifest.js';
+export { inspectProjectCompatibility, formatCompatibilityWarnings } from './compatibility.js';
+export { PACKAGE_VERSION } from './version.js';
+export { refreshWorkflow } from './refresh-workflow.js';
+export { getProjectStatus, renderStatusText, toStatusJson } from './status.js';
 export { initializeProjectMemory } from './init.js';
 export { preflightDocsReview } from './docs-review.js';
 export {

package/src/init.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { serializeProjectConfig } from './project-yaml.js';
 import { writeStateManifest } from './manifest.js';
@@ -6,12 +6,17 @@ import { scaffoldInitFiles } from './scaffold.js';
 import { applyPlacementDefaults } from './setup.js';
 import { buildWorkflowMetadata } from './workflow.js';
 import { parseSimpleYaml } from './simple-yaml.js';
+import { PACKAGE_VERSION } from './version.js';
 
 const VALID_MODES = new Set(['local-only', 'local-primary', 'hosted-only']);
 
 export async function initializeProjectMemory(options) {
   const normalized = normalizeInitOptions(options);
 
+  if (normalized.force && !normalized.replaceActiveLanes) {
+    await assertNoActiveSessionLanes(normalized.rootDir);
+  }
+
   await mkdir(normalized.rootDir, { recursive: true });
   await mkdir(path.join(normalized.rootDir, 'architecture'), { recursive: true });
   await mkdir(path.join(normalized.rootDir, 'decisions'), { recursive: true });
@@ -137,7 +142,10 @@ function normalizeInitOptions(options) {
     mode: preparedOptions.mode,
     repos,
     ...(sync ? { sync } : {}),
-    metadata: buildAgentFilesMetadata(buildWorkflowMetadata(preparedOptions.metadata, {
+    metadata: buildAgentFilesMetadata(buildWorkflowMetadata({
+      ...(preparedOptions.metadata && typeof preparedOptions.metadata === 'object' ? preparedOptions.metadata : {}),
+      package_version: PACKAGE_VERSION,
+    }, {
       gitPublish:
         typeof preparedOptions.closeSessionGitPublish === 'boolean'
           ? preparedOptions.closeSessionGitPublish
@@ -156,12 +164,44 @@ function normalizeInitOptions(options) {
   return {
     rootDir,
     force: Boolean(preparedOptions.force),
+    replaceActiveLanes: Boolean(preparedOptions.replaceActiveLanes),
     generatedAt: preparedOptions.generatedAt,
     projectConfig,
     bootstrap: bootstrapOptions,
   };
 }
 
+async function assertNoActiveSessionLanes(rootDir) {
+  const activeDir = path.join(rootDir, 'sessions', 'active');
+  let entries = [];
+  try {
+    entries = await readdir(activeDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  const activeLaneIds = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const laneDir = path.join(activeDir, entry.name);
+    if (
+      (await fileExists(path.join(laneDir, 'session.yaml'))) ||
+      (await fileExists(path.join(laneDir, 'wip.md')))
+    ) {
+      activeLaneIds.push(entry.name);
+    }
+  }
+
+  if (activeLaneIds.length > 0) {
+    throw new Error(
+      `Cannot overwrite project memory while active session lanes exist: ${activeLaneIds.join(', ')}. Close the lanes first or pass --replace-active-lanes.`,
+    );
+  }
+}
+
 function normalizeSyncOptions(syncOptions, mode) {
   if (!syncOptions || typeof syncOptions !== 'object') {
     throw new Error('sync configuration must be an object.');

package/src/manifest.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { localRevisionFromManifestHash, stableHash } from './hash.js';
 import { scanProjectMemory } from './project-memory.js';
 import { listProjectSessions } from './session.js';
+import { PACKAGE_VERSION } from './version.js';
 
 export const STATE_VERSION = 1;
 
@@ -50,13 +51,17 @@ export function generateStateManifest(scanResult, options = {}) {
       document_count: manifestInventory.length,
       warning_count: warningCount,
     },
+    package: {
+      observed_version: options.packageVersion ?? PACKAGE_VERSION,
+      observed_at: generatedAt,
+    },
     documents: manifestDocuments,
     ...(options.activeSessions ? { active_sessions: options.activeSessions } : {}),
     ...(options.sync ? { sync: options.sync } : {}),
   };
 }
 
-export async function writeStateManifest(rootDir, options = {}) {
+export async function prepareStateManifest(rootDir, options = {}) {
   const scanResult = await scanProjectMemory(rootDir);
   const activeSessions = await readActiveSessionsForManifest(rootDir);
   const existingSync = Object.hasOwn(options, 'sync')
@@ -70,9 +75,6 @@ export async function writeStateManifest(rootDir, options = {}) {
   const stateDir = path.join(rootDir, 'state');
   const manifestPath = path.join(stateDir, 'manifest.json');
 
-  await mkdir(stateDir, { recursive: true });
-  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
-
   return {
     manifest,
     manifestPath,
@@ -80,6 +82,16 @@ export async function writeStateManifest(rootDir, options = {}) {
   };
 }
 
+export async function writeStateManifest(rootDir, options = {}) {
+  const prepared = await prepareStateManifest(rootDir, options);
+  const stateDir = path.dirname(prepared.manifestPath);
+
+  await mkdir(stateDir, { recursive: true });
+  await writeFile(prepared.manifestPath, `${JSON.stringify(prepared.manifest, null, 2)}\n`, 'utf8');
+
+  return prepared;
+}
+
 async function readExistingSyncState(rootDir) {
   try {
     const existing = JSON.parse(