@vibecompass/vibecompass 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## Unreleased
+
+## 0.12.0 - 2026-07-10
+
+- New `vibecompass bootstrap --bundle <file>` materializes a complete local
+  root from a hosted bootstrap-export bundle (fail-closed hash validation,
+  verbatim writes, sync-cursor seeding for local-primary bundles).
+- New `vibecompass sync-adopt [--accept-divergence]` re-baselines a root's
+  sync cursor onto the hosted head after a divergence preview (D-215) — the
+  recovery path for fresh clones and second devices.
+- New `vibecompass promote-hosted [--resume|--abort]` and
+  `vibecompass demote-hosted [--accept-divergence]` run the D-288 two-phase
+  hosting-mode cutover: fresh verified baseline, server-side transition
+  intent with a completeness report, local flip + promoted-root marker, and
+  confirm — resumable after any crash and fully reversible.
+- Promoted roots hard-refuse canonical write commands (override with
+  VIBECOMPASS_ALLOW_PROMOTED_ROOT_WRITES=1); `vibecompass status` now checks
+  the hosted mode and warns on local/hosted mode mismatches.
+- `apply-export` pre-validates every operation before writing and treats
+  already-applied operations as converged, so retries after partial failure
+  succeed. `docs-review --apply-decision-artifact` is idempotent and
+  crash-safe (provenance Source line, marker repair, post-write verification,
+  code-enforced append-only) and warns on hosted-only roots.
+
+- The missing-sync-token error now explains how to recover: re-export the bound
+  env var, persist it in a shell profile, or rotate the token from the hosted
+  dashboard (previously a bare "requires VIBECOMPASS_SYNC_TOKEN" with no
+  guidance). README documents the persistence recipe.
+- AGENTS.md gains a release checklist, including verifying that
+  `vibecompass-mcp`'s dependency range still spans the new version so core
+  releases stop stranding the MCP package (its `^0.1.0` pin had drifted 27
+  releases behind).
+
+## 0.11.2 - 2026-07-06
+
+- Complete the remaining Phase 8 start-session overlap warnings: lanes can now
+  declare expected architecture doc paths with `--architecture-doc` and
+  decision domain files with `--decision-domain-file` / `--decision-domain`;
+  active-lane overlap warnings compare normalized path spellings for those
+  fields, and same-repo ownership ambiguity now covers one-sided or
+  unparseable path claims while treating single-repo unprefixed claims and
+  disjoint feature slugs as real non-overlapping ownership.
+- Harden S2 lane-marker follow-ups: mutating session commands revalidate a
+  pre-lock marker snapshot after acquiring the memory-root lock, close-session
+  reports unrecorded cwd markers that name the closing lane, and marker parsing
+  round-trips Windows absolute `memory_root` values with backslashes.
+
 ## 0.11.1 - 2026-07-06
 
 - Harden the per-root serialization lock for symlink-aliased memory roots: root keys now canonicalize through existing parent directories when the memory root itself does not yet exist, and nested lock holders compare held/requested roots by `realpath` before reacquiring the disk lock. This preserves reentrancy when an outer lock creates the root and an inner call reaches it through another spelling.

package/README.md

@@ -145,7 +145,15 @@ npx -y @vibecompass/vibecompass@latest close-session --root .compass --session a
 # close-session and docs-update also print a pre-close staleness set: new
 # decisions since lane start, stale base revisions, newer finalized notes
 # that mention the lane's scope, and claim overlap with other active lanes.
-npx -y @vibecompass/vibecompass@latest start-session --id auth-flow --working-on "Auth flow" --repo app --branch feature/auth --worktree
+npx -y @vibecompass/vibecompass@latest start-session \
+  --id auth-flow \
+  --working-on "Auth flow" \
+  --repo app \
+  --claim src/app/auth \
+  --architecture-doc architecture/product/auth/login.md \
+  --decision-domain-file cross-cutting.md \
+  --branch feature/auth \
+  --worktree
 
 # Per-lane runtime isolation (D-282): every lane gets its own port and temp
 # dir at start (recorded in the lane's session.yaml; defaults configurable
@@ -242,6 +250,17 @@ changed canonical project-memory files and the hosted dashboard should catch
 up. Hosted-only projects do not use a local authoritative push; update or
 refresh them through the hosted dashboard/proposal flow.
 
+The sync token is read from the environment variable you bind (for example
+`VIBECOMPASS_SYNC_TOKEN`). One-off `export`s do not survive new terminals —
+persist the token in your shell profile (`~/.zshenv` or `~/.bashrc`):
+
+```bash
+echo 'export VIBECOMPASS_SYNC_TOKEN="<your sync token>"' >> ~/.zshenv
+```
+
+If the token is lost, rotate it on the hosted dashboard under Setup -> Hosted
+sync and export the new value.
+
 ### Multiple environments
 
 One project can have named sync targets (for example a local dev server and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecompass/vibecompass",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -17,8 +17,11 @@ import { getProjectStatus, renderStatusText, toStatusJson } from './status.js';
 import { refreshWorkflow } from './refresh-workflow.js';
 import { inspectProjectCompatibility, formatCompatibilityWarnings } from './compatibility.js';
 import { PACKAGE_VERSION } from './version.js';
+import { demoteHosted, promoteHosted } from './mode-transition.js';
 import {
+  adoptRemoteHead,
   applyPullExport,
+  bootstrapFromBundle,
   pullExportProjectMemory,
   pullPreviewProjectMemory,
   pushProjectMemory,
@@ -437,6 +440,71 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'promote-hosted' || parsed.command === 'demote-hosted') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const run = parsed.command === 'promote-hosted' ? promoteHosted : demoteHosted;
+    const result = await run(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Mode transition: ${result.status}\n`);
+    if (result.completeness) {
+      io.stdout.write(`Carries over: ${result.completeness.carries_over}\n`);
+      for (const [kind, total] of Object.entries(result.completeness.documents_by_kind ?? {})) {
+        io.stdout.write(`  ${kind}: ${total}\n`);
+      }
+      io.stdout.write('Does not carry over:\n');
+      for (const item of result.completeness.does_not_carry_over ?? []) {
+        io.stdout.write(`  - ${item}\n`);
+      }
+    }
+    for (const warning of result.warnings) {
+      io.stdout.write(`Note: ${warning}\n`);
+    }
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'sync-adopt') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const result = await adoptRemoteHead(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Sync adopt: ${result.status}\n`);
+    io.stdout.write(`Adopted head: ${result.remoteRevisionId}\n`);
+    io.stdout.write(`Recorded ${result.manifestPath}\n`);
+    for (const warning of result.warnings) {
+      io.stdout.write(`Warning: ${warning}\n`);
+    }
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'bootstrap') {
+    const result = await bootstrapFromBundle(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Bootstrap: ${result.status}\n`);
+    io.stdout.write(`Root: ${result.rootDir}\n`);
+    io.stdout.write(`Documents: ${result.documentCount}\n`);
+    if (result.mode) {
+      io.stdout.write(`Mode: ${result.mode}\n`);
+    }
+    if (result.manifestPath) {
+      io.stdout.write(`Recorded ${result.manifestPath}\n`);
+    }
+    for (const warning of result.warnings) {
+      io.stdout.write(`Warning: ${warning}\n`);
+    }
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
   if (parsed.command === 'pull-preview') {
     await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await pullPreviewProjectMemory(parsed.options, {
@@ -708,6 +776,18 @@ export function parseCliArgs(argv) {
       return parsePushArgs(rest);
     }
 
+    if (command === 'promote-hosted' || command === 'demote-hosted') {
+      return parseModeTransitionArgs(command, rest);
+    }
+
+    if (command === 'sync-adopt') {
+      return parseSyncAdoptArgs(rest);
+    }
+
+    if (command === 'bootstrap') {
+      return parseBootstrapArgs(rest);
+    }
+
     if (command === 'pull-preview') {
       return parsePullPreviewArgs(rest);
     }
@@ -949,6 +1029,13 @@ function parseStartSessionArgs(argv) {
       case '--claim':
         parsed.claims = [...(parsed.claims ?? []), value];
         break;
+      case '--architecture-doc':
+        parsed.architectureDocs = [...(parsed.architectureDocs ?? []), value];
+        break;
+      case '--decision-domain':
+      case '--decision-domain-file':
+        parsed.decisionDomainFiles = [...(parsed.decisionDomainFiles ?? []), value];
+        break;
       case '--branch':
         parsed.branch = value;
         break;
@@ -1769,6 +1856,122 @@ function parseDocsReviewArgs(argv) {
   };
 }
 
+function parseModeTransitionArgs(command, 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 === '--resume') {
+      parsed.resume = true;
+      continue;
+    }
+    if (token === '--abort') {
+      parsed.abort = true;
+      continue;
+    }
+    if (token === '--accept-divergence') {
+      parsed.acceptDivergence = 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 '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for ${command}.`);
+    }
+  }
+
+  return { command, options: parsed };
+}
+
+function parseSyncAdoptArgs(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 === '--accept-divergence') {
+      parsed.acceptDivergence = 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 '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for sync-adopt.`);
+    }
+  }
+
+  return {
+    command: 'sync-adopt',
+    options: parsed,
+  };
+}
+
+function parseBootstrapArgs(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 '--bundle':
+        parsed.bundlePath = value;
+        break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for bootstrap.`);
+    }
+  }
+
+  return {
+    command: 'bootstrap',
+    options: parsed,
+  };
+}
+
 function parsePushArgs(argv) {
   return {
     command: 'push',
@@ -2176,6 +2379,10 @@ function usageText() {
     '  vibecompass next-decision-id [options]',
     '  vibecompass sync-agents [options]',
     '  vibecompass push [options]',
+    '  vibecompass bootstrap --bundle <file> [--root <dir>]',
+    '  vibecompass sync-adopt [--accept-divergence] [options]',
+    '  vibecompass promote-hosted [--resume|--abort] [options]',
+    '  vibecompass demote-hosted [--accept-divergence] [options]',
     '  vibecompass pull-preview [options]',
     '  vibecompass pull-export [options]',
     '  vibecompass apply-export [options]',
@@ -2248,6 +2455,8 @@ function usageText() {
     '  --feature <slug>                     Repeatable feature slug for the lane',
     '  --repo <id>                          Repeatable repo ID for the lane',
     '  --claim <path>                       Repeatable path claim for overlap warnings',
+    '  --architecture-doc <path>            Repeatable architecture doc path the lane expects to edit',
+    '  --decision-domain-file <domain.md>   Repeatable decision domain file the lane expects to edit (alias: --decision-domain)',
     '  --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',

package/src/docs-review.js

@@ -434,6 +434,15 @@ async function applyDecisionArtifactLocked(options) {
     throw new Error(`Decision artifact ${artifactId} must include a non-empty rationale before it can be appended locally.`);
   }
 
+  // Idempotency guard: never append the same artifact twice. The marker is
+  // the fast path; the file-content check covers a crash between the file
+  // write and the marker update.
+  if (artifact.local_status === 'applied') {
+    throw new Error(
+      `Decision artifact ${artifactId} is already applied locally as ${artifact.local_decision_id ? `decision ${artifact.local_decision_id}` : 'a decision entry'}. Re-applying would append a duplicate entry.`,
+    );
+  }
+
   const nextDecisionId = await readNextDecisionId(options.rootDir);
   const targetFilePath = path.join(options.rootDir, targetPath);
   await mkdir(path.dirname(targetFilePath), { recursive: true });
@@ -446,27 +455,99 @@ async function applyDecisionArtifactLocked(options) {
     existingContent = `# ${path.basename(targetPath, '.md')} decisions\n`;
   }
 
-  const entry = renderDecisionEntry({
-    decisionId: nextDecisionId,
-    title,
-    decision,
-    rationale,
-    context,
-    artifactId,
-  });
-  await writeFile(targetFilePath, `${existingContent.trimEnd()}\n\n${entry}`, 'utf8');
-  const indexResult = options.refreshIndex
-    ? await refreshDecisionIndex(options.rootDir)
-    : {
+  const applyWarnings = [];
+  const alreadyInFile = existingContent.includes(
+    `hosted docs-review artifact ${artifactId}`,
+  );
+  let appliedDecisionIdForMarker = nextDecisionId;
+
+  if (alreadyInFile) {
+    // A previous apply wrote the file but crashed before recording the
+    // marker. Repair the marker instead of appending a duplicate.
+    applyWarnings.push(
+      `Artifact ${artifactId} was already present in ${targetPath}; repaired the marker without appending a duplicate entry.`,
+    );
+    const existingIdMatch = existingContent.match(
+      new RegExp(
+        `### (D-\\d+)[^\\n]*(?:\\n(?!### ).*)*hosted docs-review artifact ${artifactId.replaceAll(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}`,
+      ),
+    );
+    appliedDecisionIdForMarker = existingIdMatch
+      ? Number.parseInt(existingIdMatch[1].slice(2), 10)
+      : nextDecisionId;
+  } else {
+    const entry = renderDecisionEntry({
+      decisionId: nextDecisionId,
+      title,
+      decision,
+      rationale,
+      context,
+      artifactId,
+    });
+    const nextContent = `${existingContent.trimEnd()}\n\n${entry}`;
+    // Append-only enforced in code, not just convention: the previous file
+    // content must survive verbatim as a prefix of what we write.
+    if (!nextContent.startsWith(existingContent.trimEnd())) {
+      throw new Error(
+        `Refusing to apply artifact ${artifactId}: the write would not preserve the existing content of ${targetPath} (decisions are append-only).`,
+      );
+    }
+    await writeFile(targetFilePath, nextContent, 'utf8');
+
+    // Post-write verification: the canonical write must be durable and
+    // intact before the marker records the artifact as applied.
+    const verification = await readFile(targetFilePath, 'utf8');
+    if (verification !== nextContent) {
+      throw new Error(
+        `Post-write verification failed for ${targetPath}: the file on disk does not match the appended content. The marker was NOT updated; inspect the file and retry.`,
+      );
+    }
+  }
+
+  // Hosted-only roots can apply locally but can never push the result back
+  // until the project is demoted to local-primary — say so instead of letting
+  // the user discover it at push time.
+  try {
+    const projectConfig = parseSimpleYaml(
+      await readFile(path.join(options.rootDir, 'project.yaml'), 'utf8'),
+      { sourceName: 'project.yaml' },
+    );
+    if (projectConfig?.mode === 'hosted-only') {
+      applyWarnings.push(
+        'This is a hosted-only project: the locally applied decision cannot be pushed back to the hosted canonical store. The hosted copy was already recorded when the artifact was accepted; treat this local root as a working copy.',
+      );
+    }
+  } catch {
+    // Unreadable project.yaml is surfaced by other commands; not fatal here.
+  }
+
+  let indexResult;
+  if (options.refreshIndex) {
+    try {
+      indexResult = await refreshDecisionIndex(options.rootDir);
+    } catch (error) {
+      // An index-refresh failure after a verified canonical write must not
+      // strand the marker (a retry would duplicate the entry): degrade to a
+      // warning and keep going.
+      indexResult = {
+        refreshed: false,
+        warnings: [
+          `decisions/INDEX.md refresh failed after the entry was appended: ${error.message}. Run vibecompass refresh-decision-index manually.`,
+        ],
+      };
+    }
+  } else {
+    indexResult = {
       refreshed: false,
       warnings: [
         'decisions/INDEX.md was not refreshed. Run again with --refresh-index if this root uses the package-generated flat index, or update the project-specific index manually.',
       ],
     };
+  }
 
   const appliedDecisionArtifact = {
     artifact_id: artifactId,
-    decision_id: nextDecisionId,
+    decision_id: appliedDecisionIdForMarker,
     target_path: targetPath,
     applied_at: new Date().toISOString(),
     refreshed_index: indexResult.refreshed,
@@ -478,7 +559,7 @@ async function applyDecisionArtifactLocked(options) {
       ...current.hosted,
       artifacts: (current.hosted?.artifacts ?? []).map((item) =>
         item?.artifact_id === artifactId
-          ? { ...item, local_status: 'applied', local_decision_id: nextDecisionId }
+          ? { ...item, local_status: 'applied', local_decision_id: appliedDecisionIdForMarker }
           : item,
       ),
     },
@@ -494,8 +575,10 @@ async function applyDecisionArtifactLocked(options) {
     hosted: current.hosted ?? null,
     appliedDecisionArtifact,
     reviewPrompt: null,
-    warnings: indexResult.warnings,
-    message: `Applied decision artifact ${artifactId} as D-${String(nextDecisionId).padStart(3, '0')} in ${targetPath}.`,
+    warnings: [...applyWarnings, ...indexResult.warnings],
+    message: alreadyInFile
+      ? `Repaired the marker for decision artifact ${artifactId} (already present in ${targetPath} as D-${String(appliedDecisionIdForMarker).padStart(3, '0')}).`
+      : `Applied decision artifact ${artifactId} as D-${String(appliedDecisionIdForMarker).padStart(3, '0')} in ${targetPath}.`,
   };
 }
 
@@ -1972,6 +2055,10 @@ function renderDecisionEntry(options) {
     `**Decision:** ${options.decision}`,
     `**Rationale:** ${options.rationale}`,
     ...(options.context ? [`**Context:** ${options.context}`] : []),
+    // Provenance makes re-application detectable from the file itself, so a
+    // crash between the file write and the marker update can never cause a
+    // silent duplicate append on retry.
+    ...(options.artifactId ? [`**Source:** hosted docs-review artifact ${options.artifactId}`] : []),
     '',
   ].join('\n');
 }

package/src/index.js

@@ -6,8 +6,11 @@ export { getProjectStatus, renderStatusText, toStatusJson } from './status.js';
 export { initializeProjectMemory } from './init.js';
 export { preflightDocsReview } from './docs-review.js';
 export { planDocsUpdate, renderDocsUpdatePlan } from './docs-update.js';
+export { demoteHosted, promoteHosted } from './mode-transition.js';
 export {
+  adoptRemoteHead,
   applyPullExport,
+  bootstrapFromBundle,
   pullExportProjectMemory,
   pullPreviewProjectMemory,
   pushProjectMemory,

package/src/lane-marker.js

@@ -108,7 +108,7 @@ export async function readLaneMarker(markerPath) {
   }
 
   const memoryRoot = typeof data.memory_root === 'string' ? data.memory_root.trim() : '';
-  if (!memoryRoot || !path.isAbsolute(memoryRoot)) {
+  if (!memoryRoot || !isAbsolutePathForAnySupportedPlatform(memoryRoot)) {
     throw new Error(
       `Lane marker at ${markerPath} must record memory_root as an absolute path (found ${JSON.stringify(data.memory_root ?? null)}). ` +
         'Recreate the marker with `vibecompass write-lane-marker`, or pass both --root and --session to bypass it.',
@@ -188,6 +188,40 @@ export async function resolveLaneMarkerContext(options) {
   };
 }
 
+/**
+ * In-lock revalidation for a marker snapshot captured before waiting on the
+ * memory-root lock. If the marker changed while the command waited, fail
+ * closed instead of using stale lane/root context for a mutating operation.
+ */
+export async function assertLaneMarkerSnapshotCurrent(markerContext) {
+  const snapshot = markerContext?.marker;
+  if (!snapshot) {
+    return;
+  }
+
+  let current;
+  try {
+    current = await readLaneMarker(snapshot.markerPath);
+  } catch (error) {
+    throw new Error(
+      `Lane marker at ${snapshot.markerPath} changed while waiting for the project-memory lock. ` +
+        `Could not re-read the original marker (${error instanceof Error ? error.message : String(error)}). ` +
+        'Rerun the command so lane selection and root inference are based on the current marker.',
+    );
+  }
+
+  if (
+    current.laneId !== snapshot.laneId ||
+    current.memoryRoot !== snapshot.memoryRoot ||
+    current.token !== snapshot.token
+  ) {
+    throw new Error(
+      `Lane marker at ${snapshot.markerPath} changed while waiting for the project-memory lock. ` +
+        'Rerun the command so lane selection and root inference are based on the current marker.',
+    );
+  }
+}
+
 /**
  * The D-277 lane selection order, shared by every lane-scoped resolver:
  * explicit --session wins (warning when it contradicts a resolvable marker,
@@ -329,6 +363,10 @@ async function canonicalizePath(value) {
   }
 }
 
+function isAbsolutePathForAnySupportedPlatform(value) {
+  return path.isAbsolute(value) || /^[A-Za-z]:[\\/]/.test(value) || /^\\\\/.test(value);
+}
+
 async function fileExists(filePath) {
   try {
     await access(filePath);