@vibecompass/vibecompass 0.11.1 → 0.11.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## Unreleased
+
+## 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

package/package.json

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

package/src/cli.js

@@ -949,6 +949,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;
@@ -2248,6 +2255,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/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);

package/src/scaffold.js

@@ -276,7 +276,7 @@ ${renderWorkflowDefaults(workflow)}
 6. Read the relevant docs under \`${rootRelativePath}/architecture/\` and \`${rootRelativePath}/decisions/\`.
 
 ## Builder workflow
-At session start, prefer running \`vibecompass start-session --id <lane-id> --working-on "..." \`; add \`--branch <name> --repo <id> [--worktree]\` when the lane should work on its own branch or in isolated worktrees (D-281).
+At session start, prefer running \`vibecompass start-session --id <lane-id> --working-on "..." \`; add \`--feature\`, \`--repo\`, \`--claim\`, \`--architecture-doc\`, and \`--decision-domain-file\` values when the lane's scope is known so overlap warnings can be precise. Add \`--branch <name> --repo <id> [--worktree]\` when the lane should work on its own branch or in isolated worktrees (D-281).
 If you manage files manually, create \`${rootRelativePath}/sessions/active/<lane-id>/session.yaml\` and \`${rootRelativePath}/sessions/active/index.yaml\`, then create \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\` if it does not exist:
 
 \`\`\`md

package/src/session.js

@@ -26,6 +26,7 @@ import {
 } from './lane-runtime.js';
 import {
   LANE_MARKER_FILENAME,
+  assertLaneMarkerSnapshotCurrent,
   assertMarkerTargetDisjoint,
   findEnclosingGitDir,
   readLaneMarker,
@@ -141,6 +142,7 @@ export async function inferToolingRootForMemoryRoot(rootDir) {
 }
 
 async function startProjectSessionLocked(normalized, options, markerContext) {
+  await assertLaneMarkerSnapshotCurrent(markerContext);
   const workingOn = requireNonEmptyString(options?.workingOn, 'start-session requires a non-empty workingOn value.');
   const sessionDate = normalizeSessionDate(options?.date);
 
@@ -151,12 +153,17 @@ async function startProjectSessionLocked(normalized, options, markerContext) {
   const features = normalizeStringArray(options?.features);
   const repos = normalizeStringArray(options?.repos);
   const claims = normalizeStringArray(options?.claims);
+  const architectureDocs = normalizeStringArray(options?.architectureDocs).map(normalizeArchitectureDocPath);
+  const decisionDomainFiles = normalizeStringArray(options?.decisionDomainFiles ?? options?.decisionDomains)
+    .map(normalizeDecisionDomainFile);
   const existingLanes = await listActiveSessionLanes(normalized);
   const overlapWarnings = buildOverlapWarnings({
     sessionId,
     features,
     repos,
     claims,
+    architectureDocs,
+    decisionDomainFiles,
     existingLanes,
     hasWorktree: options?.worktree === true,
   });
@@ -276,6 +283,8 @@ async function startProjectSessionLocked(normalized, options, markerContext) {
       features,
       repos,
       claims,
+      architectureDocs,
+      decisionDomainFiles,
       baseRevisions: baseRevisionCapture.baseRevisions,
       runtime: laneRuntime,
       // Record-before-create (D-281): the full binding plan — including the
@@ -426,6 +435,7 @@ export async function closeProjectSession(options) {
 }
 
 async function closeProjectSessionLocked(normalized, options, markerContext) {
+  await assertLaneMarkerSnapshotCurrent(markerContext);
   const title = requireNonEmptyString(options?.title, 'session close requires a non-empty title.');
   const completed = normalizeStringArray(options?.completed);
   const models = normalizeStringArray(options?.models);
@@ -584,6 +594,17 @@ async function closeProjectSessionLocked(normalized, options, markerContext) {
         markerCleanupWarnings.push(...containerCleanup.warnings);
       }
     }
+    if (markerContext.marker?.laneId === sessionId) {
+      const contextMarkerPath = path.resolve(markerContext.marker.markerPath);
+      const recordedMarkerPath = closingLaneMetadata?.laneMarker?.path
+        ? path.resolve(closingLaneMetadata.laneMarker.path)
+        : null;
+      if (contextMarkerPath !== recordedMarkerPath && (await fileExists(contextMarkerPath))) {
+        markerCleanupWarnings.push(
+          `Lane marker at ${contextMarkerPath} names the closed lane "${sessionId}" but was not recorded in session.yaml; close-session left it in place. Remove it manually or recreate it with \`vibecompass write-lane-marker\` before reusing that directory.`,
+        );
+      }
+    }
     if (removal.attempted) {
       worktreeCleanup = {
         branch: closingLaneMetadata?.branch ?? null,
@@ -900,6 +921,7 @@ export async function switchProjectSession(options = {}) {
 }
 
 async function switchProjectSessionLocked(normalized, options, markerContext) {
+  await assertLaneMarkerSnapshotCurrent(markerContext);
   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);
@@ -1020,6 +1042,7 @@ export async function writeLaneMarkerForSession(options) {
 }
 
 async function writeLaneMarkerForSessionLocked(normalized, options, markerContext) {
+  await assertLaneMarkerSnapshotCurrent(markerContext);
   const sessionId = validateLaneId(
     requireNonEmptyString(options?.sessionId, 'write-lane-marker requires --session <lane-id> so the marker binds to an explicit lane.'),
   );
@@ -1506,6 +1529,8 @@ async function listActiveSessionLanes(normalized) {
         features: metadata.features,
         repos: metadata.repos,
         claims: metadata.claims,
+        architectureDocs: metadata.architectureDocs,
+        decisionDomainFiles: metadata.decisionDomainFiles,
         startedAt: metadata.startedAt,
         decisionSnapshot: metadata.decisionSnapshot,
         branch: metadata.branch ?? null,
@@ -1548,6 +1573,8 @@ async function readLaneMetadata(sessionFilePath) {
       features: normalizeStringArray(data.feature_slugs),
       repos: normalizeStringArray(data.repos),
       claims: normalizeStringArray(data.claimed_paths),
+      architectureDocs: normalizeStringArray(data.architecture_docs).map(normalizeArchitectureDocPath),
+      decisionDomainFiles: normalizeStringArray(data.decision_domain_files).map(normalizeDecisionDomainFile),
       startedAt: normalizeOptionalString(data.started_at),
       decisionSnapshot: {
         highestDecisionId: parseNullableNumber(data.decision_snapshot?.highest_decision_id),
@@ -1581,6 +1608,8 @@ async function readLaneMetadata(sessionFilePath) {
       features: [],
       repos: [],
       claims: [],
+      architectureDocs: [],
+      decisionDomainFiles: [],
       startedAt: null,
       decisionSnapshot: {
         highestDecisionId: null,
@@ -1839,6 +1868,8 @@ function renderLaneMetadata(options) {
     renderYamlArray('feature_slugs', options.features),
     renderYamlArray('repos', options.repos),
     renderYamlArray('claimed_paths', options.claims),
+    renderYamlArray('architecture_docs', options.architectureDocs),
+    renderYamlArray('decision_domain_files', options.decisionDomainFiles),
     `started_at: ${formatLocalDateTime(new Date())}`,
     // D-282: the runtime assignment travels with the lane record (local-only
     // per D-278) so lane-env and close-time cleanup read it back.
@@ -2021,13 +2052,32 @@ function buildOverlapWarnings(options) {
       );
     }
 
-    const claimOverlaps = findClaimOverlaps(options.claims, lane.claims ?? []);
+    const claimOverlaps = findClaimOverlaps(
+      options.claims,
+      options.repos,
+      lane.claims ?? [],
+      lane.repos ?? [],
+    );
     for (const overlap of claimOverlaps) {
       warnings.push(
         `Active session lane "${options.sessionId}" overlaps "${lane.id}" on claimed path ${overlap.repo}:${overlap.path}.`,
       );
     }
 
+    const sharedArchitectureDocs = intersect(options.architectureDocs ?? [], lane.architectureDocs ?? []);
+    if (sharedArchitectureDocs.length > 0) {
+      warnings.push(
+        `Active session lane "${options.sessionId}" overlaps "${lane.id}" on architecture doc(s): ${sharedArchitectureDocs.join(', ')}.`,
+      );
+    }
+
+    const sharedDecisionDomainFiles = intersect(options.decisionDomainFiles ?? [], lane.decisionDomainFiles ?? []);
+    if (sharedDecisionDomainFiles.length > 0) {
+      warnings.push(
+        `Active session lane "${options.sessionId}" overlaps "${lane.id}" on decision domain file(s): ${sharedDecisionDomainFiles.join(', ')}.`,
+      );
+    }
+
     const sharedRepos = intersect(options.repos, lane.repos ?? []);
     warnings.push(...buildSharedCheckoutWarnings({
       sessionId: options.sessionId,
@@ -2038,15 +2088,38 @@ function buildOverlapWarnings(options) {
       context: 'start-session',
     }));
 
+    const bothLackClaims = options.claims.length === 0 && (lane.claims ?? []).length === 0;
     if (
       sharedRepos.length > 0 &&
       (options.hasWorktree || lane.worktreeContainer) &&
-      options.claims.length === 0 &&
-      (lane.claims ?? []).length === 0
+      bothLackClaims
     ) {
       warnings.push(
         `Active session lane "${options.sessionId}" shares repo(s) ${sharedRepos.join(', ')} with "${lane.id}" without path claims; add --claim values to clarify ownership.`,
       );
+      continue;
+    }
+
+    const disambiguatedByFeatures =
+      options.features.length > 0 &&
+      (lane.features ?? []).length > 0 &&
+      sharedFeatures.length === 0;
+    const disambiguatedByClaims = hasNarrowNonOverlappingClaims({
+      sharedRepos,
+      leftClaims: options.claims,
+      leftRepos: options.repos,
+      rightClaims: lane.claims ?? [],
+      rightRepos: lane.repos ?? [],
+    });
+    if (
+      sharedRepos.length > 0 &&
+      claimOverlaps.length === 0 &&
+      !disambiguatedByFeatures &&
+      !disambiguatedByClaims
+    ) {
+      warnings.push(
+        `Active session lane "${options.sessionId}" shares repo(s) ${sharedRepos.join(', ')} with "${lane.id}" without narrower non-overlapping ownership; ownership is ambiguous. Add --claim paths or --feature slugs to both lanes to clarify ownership.`,
+      );
     }
   }
 
@@ -2093,10 +2166,10 @@ function intersect(left, right) {
   return left.filter((item) => rightSet.has(item));
 }
 
-function findClaimOverlaps(leftClaims, rightClaims) {
+function findClaimOverlaps(leftClaims, leftRepos, rightClaims, rightRepos) {
   const overlaps = [];
-  for (const left of leftClaims.map(parseClaim).filter(Boolean)) {
-    for (const right of rightClaims.map(parseClaim).filter(Boolean)) {
+  for (const left of expandClaims(leftClaims, leftRepos)) {
+    for (const right of expandClaims(rightClaims, rightRepos)) {
       if (left.repo !== right.repo) {
         continue;
       }
@@ -2113,20 +2186,94 @@ function findClaimOverlaps(leftClaims, rightClaims) {
   return overlaps;
 }
 
-function parseClaim(value) {
-  const separatorIndex = value.indexOf(':');
-  if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
-    return null;
+function hasNarrowNonOverlappingClaims(options) {
+  if (options.sharedRepos.length === 0) {
+    return false;
   }
 
-  return {
-    repo: value.slice(0, separatorIndex),
-    path: normalizeClaimPath(value.slice(separatorIndex + 1)),
-  };
+  const leftClaims = expandClaims(options.leftClaims, options.leftRepos);
+  const rightClaims = expandClaims(options.rightClaims, options.rightRepos);
+  return options.sharedRepos.every((repo) => {
+    const leftForRepo = leftClaims.filter((claim) => claim.repo === repo);
+    const rightForRepo = rightClaims.filter((claim) => claim.repo === repo);
+    if (leftForRepo.length === 0 || rightForRepo.length === 0) {
+      return false;
+    }
+
+    return leftForRepo.every((left) =>
+      rightForRepo.every((right) => !pathPrefixesOverlap(left.path, right.path)));
+  });
+}
+
+function expandClaims(claims, repos) {
+  const normalizedRepos = normalizeStringArray(repos);
+  return normalizeStringArray(claims)
+    .flatMap((claim) => parseClaim(claim, normalizedRepos))
+    .filter(Boolean);
+}
+
+function parseClaim(value, repos = []) {
+  const source = String(value ?? '').trim();
+  if (!source) {
+    return [];
+  }
+
+  const normalizedRepos = normalizeStringArray(repos);
+  const separatorIndex = source.indexOf(':');
+  const repoId = separatorIndex > 0 ? source.slice(0, separatorIndex) : '';
+  const rawClaimPath = separatorIndex > 0 ? source.slice(separatorIndex + 1) : '';
+  if (separatorIndex > 0 && !rawClaimPath) {
+    return [];
+  }
+
+  if (
+    separatorIndex > 0 &&
+    rawClaimPath &&
+    (!isWindowsDrivePath(source) || (normalizedRepos.includes(repoId) && rawClaimPath.startsWith('/')))
+  ) {
+    const normalizedPath = normalizeClaimPath(rawClaimPath);
+    if (!normalizedPath) {
+      return [];
+    }
+
+    return [{
+      repo: repoId,
+      path: normalizedPath,
+    }];
+  }
+
+  const normalized = normalizeClaimPath(source);
+  if (!normalized) {
+    return [];
+  }
+
+  return normalizedRepos.map((repo) => ({
+    repo,
+    path: normalized,
+  }));
 }
 
 function normalizeClaimPath(value) {
-  return value.replace(/^\/+/, '').replace(/\/+$/, '');
+  return String(value ?? '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/\/+/g, '/')
+    .split('/')
+    .filter((segment) => segment !== '' && segment !== '.')
+    .join('/');
+}
+
+function normalizeArchitectureDocPath(value) {
+  return normalizeClaimPath(value);
+}
+
+function normalizeDecisionDomainFile(value) {
+  const normalized = normalizeClaimPath(value);
+  return normalized.startsWith('decisions/') ? normalized : `decisions/${normalized}`;
+}
+
+function isWindowsDrivePath(value) {
+  return /^[A-Za-z]:[\\/]/.test(String(value ?? ''));
 }
 
 function pathPrefixesOverlap(left, right) {