@vibecompass/vibecompass 0.11.1 → 0.12.0

package/src/mode-transition.js

@@ -0,0 +1,265 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseSimpleYaml } from './simple-yaml.js';
+import { resolveSyncBinding } from './sync-binding.js';
+import { withMemoryRootLock } from './serialization.js';
+import { adoptRemoteHead, pushProjectMemory } from './sync.js';
+
+const PROMOTED_MARKER = ['state', 'promoted-root.json'];
+
+/**
+ * D-288 promote: local-primary -> hosted-only as a crash-safe, resumable
+ * two-phase transition. Fresh verified push baseline -> server records the
+ * intent (with a completeness report) -> local changes (project.yaml mode,
+ * promoted-root marker, agent guidance) -> server confirm. `--resume`
+ * continues an interrupted run from whatever state it reached; `--abort`
+ * backs the whole thing out on both sides.
+ */
+export async function promoteHosted(options = {}, environment = {}) {
+  const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  return withMemoryRootLock(rootDir, 'promote-hosted', () =>
+    promoteHostedLocked(options, environment, rootDir),
+  );
+}
+
+async function promoteHostedLocked(options, environment, rootDir) {
+  const context = await loadModeAgnosticSyncContext(rootDir, options, environment);
+  const server = await getJson(context, 'status');
+  const localMode = context.project.mode;
+  const notes = [];
+
+  if (options.abort === true) {
+    // A confirmed promotion cannot be aborted: the server is already
+    // hosted-only, and rewriting only the local record would create exactly
+    // the split-brain the two-phase flow exists to prevent. Reversing a
+    // finished cutover is demote-hosted's job.
+    if (server.mode === 'hosted-only' && !server.pending_mode_transition) {
+      throw new Error(
+        'This promotion was already confirmed — the hosted project is hosted-only. '
+        + 'Aborting now would only rewrite the local record and split the two mode records. '
+        + 'Use vibecompass demote-hosted to reverse the cutover on both sides.',
+      );
+    }
+    await postJson(context, 'mode-transition', { action: 'abort' });
+    if (localMode === 'hosted-only') {
+      await writeProjectMode(rootDir, 'local-primary');
+      await removePromotedMarker(rootDir);
+      notes.push('Restored local project.yaml to local-primary and removed the promoted-root marker.');
+    }
+    return {
+      status: 'aborted',
+      rootDir,
+      warnings: notes,
+      message: 'Promotion aborted; the project remains local-primary on both sides.',
+    };
+  }
+
+  if (server.mode === 'hosted-only' && localMode === 'hosted-only' && !server.pending_mode_transition) {
+    await ensurePromotedMarker(rootDir, context);
+    return {
+      status: 'already-promoted',
+      rootDir,
+      warnings: [],
+      message: 'This project is already hosted-only on both sides.',
+    };
+  }
+
+  const resuming = options.resume === true || Boolean(server.pending_mode_transition) || localMode === 'hosted-only';
+  let completeness = null;
+
+  if (localMode === 'local-primary') {
+    // Phase 1: fresh verified baseline. Idempotent push makes retries safe.
+    const pushResult = await pushProjectMemory(
+      { rootDir, syncTarget: options.syncTarget ?? null },
+      environment,
+    );
+    notes.push(`Baseline push: ${pushResult.status} (${pushResult.remoteRevisionId}).`);
+
+    const manifest = JSON.parse(await readFile(path.join(rootDir, 'state', 'manifest.json'), 'utf8'));
+    const begin = await postJson(context, 'mode-transition', {
+      action: 'begin',
+      target_mode: 'hosted-only',
+      expected_manifest_hash: manifest.canonical.manifest_hash,
+    });
+    completeness = begin.completeness ?? null;
+
+    // Phase 2: local changes.
+    await writeProjectMode(rootDir, 'hosted-only');
+    await ensurePromotedMarker(rootDir, context);
+  } else if (resuming) {
+    // Crash-window repair: the mode flipped locally but the marker (or the
+    // confirm) may be missing.
+    await ensurePromotedMarker(rootDir, context);
+  } else {
+    throw new Error(`promote-hosted requires a local-primary root (found mode: ${localMode ?? 'unknown'}).`);
+  }
+
+  // Phase 3: confirm (safe to retry; the server treats a repeated confirm as done).
+  await postJson(context, 'mode-transition', { action: 'confirm', target_mode: 'hosted-only' });
+
+  notes.push(
+    'Agent re-pointing: hosted context is now canonical. In your MCP configuration set VIBECOMPASS_API_KEY '
+    + '(create a key on the hosted Setup page), remove VIBECOMPASS_ROOT, and restart your MCP server. '
+    + 'Agent instruction files keep working for reading; canonical writes belong on the hosted dashboard.',
+  );
+  notes.push(
+    'This root is now a promoted working copy: canonical write commands refuse by default '
+    + '(vibecompass demote-hosted reverses the cutover; VIBECOMPASS_ALLOW_PROMOTED_ROOT_WRITES=1 overrides deliberately).',
+  );
+
+  return {
+    status: resuming && localMode !== 'local-primary' ? 'resumed-and-promoted' : 'promoted',
+    rootDir,
+    completeness,
+    warnings: notes,
+    message: 'Promotion complete: the hosted app is now this project\'s source of truth (both mode records agree).',
+  };
+}
+
+/**
+ * D-289 demote: hosted-only -> local-primary. Run from a local root that
+ * holds the hosted content (freshly bootstrapped from the export bundle, or
+ * the original promoted root). Flips both records via the same two-phase
+ * endpoint, then adopts the hosted head as the sync cursor so the first push
+ * works immediately.
+ */
+export async function demoteHosted(options = {}, environment = {}) {
+  const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  return withMemoryRootLock(rootDir, 'demote-hosted', () =>
+    demoteHostedLocked(options, environment, rootDir),
+  );
+}
+
+async function demoteHostedLocked(options, environment, rootDir) {
+  const context = await loadModeAgnosticSyncContext(rootDir, options, environment);
+  const server = await getJson(context, 'status');
+  const notes = [];
+
+  if (server.mode === 'local-primary' && context.project.mode === 'local-primary') {
+    return {
+      status: 'already-local-primary',
+      rootDir,
+      warnings: [],
+      message: 'This project is already local-primary on both sides.',
+    };
+  }
+
+  if (server.mode === 'hosted-only') {
+    await postJson(context, 'mode-transition', { action: 'begin', target_mode: 'local-primary' });
+  }
+  if (context.project.mode !== 'local-primary') {
+    await writeProjectMode(rootDir, 'local-primary');
+    notes.push('Local project.yaml mode set to local-primary.');
+  }
+  await removePromotedMarker(rootDir);
+  await postJson(context, 'mode-transition', { action: 'confirm', target_mode: 'local-primary' });
+
+  // Adopt the hosted head as this root's baseline so the first push has the
+  // correct parent (bundle-restored roots already carry it; this makes the
+  // flow correct for any root).
+  const adoption = await adoptRemoteHead(
+    {
+      rootDir,
+      syncTarget: options.syncTarget ?? null,
+      acceptDivergence: options.acceptDivergence === true,
+    },
+    environment,
+  );
+  notes.push(adoption.message);
+
+  return {
+    status: 'demoted',
+    rootDir,
+    warnings: notes,
+    message: 'Demotion complete: this local root is canonical again (local-primary on both sides). Local files win; push to publish changes.',
+  };
+}
+
+async function loadModeAgnosticSyncContext(rootDir, options, environment) {
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const project = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+    sourceName: projectFilePath,
+  });
+  const binding = resolveSyncBinding(project, options.syncTarget ?? null);
+  if (!binding) {
+    throw new Error('Mode transitions require a sync binding in project.yaml (run connect-hosted first).');
+  }
+  const credential = ((environment.env ?? process.env)[binding.credentialEnvVar] ?? '').trim();
+  if (!credential) {
+    throw new Error(`Mode transitions require ${binding.credentialEnvVar} to be set.`);
+  }
+  const fetchImpl = environment.runtime?.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('Mode transitions require a fetch implementation.');
+  }
+  return { rootDir, project, binding, credential, fetch: fetchImpl };
+}
+
+function endpointUrl(context, routeName) {
+  const base = context.binding.apiUrl.endsWith('/')
+    ? context.binding.apiUrl
+    : `${context.binding.apiUrl}/`;
+  return new URL(
+    `api/sync/projects/${encodeURIComponent(context.binding.projectId)}/${routeName}`,
+    base,
+  ).href;
+}
+
+async function getJson(context, routeName) {
+  const response = await context.fetch(endpointUrl(context, routeName), {
+    headers: {
+      accept: 'application/json',
+      authorization: `Bearer ${context.credential}`,
+    },
+  });
+  if (!response.ok) {
+    const text = typeof response.text === 'function' ? await response.text() : '';
+    throw new Error(`Hosted ${routeName} failed with ${response.status}${text ? `: ${text}` : ''}`);
+  }
+  return typeof response.json === 'function' ? response.json() : {};
+}
+
+async function postJson(context, routeName, body) {
+  const response = await context.fetch(endpointUrl(context, routeName), {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      authorization: `Bearer ${context.credential}`,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    const text = typeof response.text === 'function' ? await response.text() : '';
+    throw new Error(`Hosted ${routeName} failed with ${response.status}${text ? `: ${text}` : ''}`);
+  }
+  return typeof response.json === 'function' ? response.json() : {};
+}
+
+async function writeProjectMode(rootDir, mode) {
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const raw = await readFile(projectFilePath, 'utf8');
+  const next = raw.replace(/^mode:\s*\S+\s*$/m, `mode: ${mode}`);
+  if (next === raw && !new RegExp(`^mode:\\s*${mode}\\s*$`, 'm').test(raw)) {
+    throw new Error(`Could not update the mode line in ${projectFilePath}; edit it to "mode: ${mode}" and re-run with --resume.`);
+  }
+  await writeFile(projectFilePath, next, 'utf8');
+}
+
+async function ensurePromotedMarker(rootDir, context) {
+  const markerPath = path.join(rootDir, ...PROMOTED_MARKER);
+  await mkdir(path.dirname(markerPath), { recursive: true });
+  const marker = {
+    promoted_at: new Date().toISOString(),
+    api_url: context.binding.apiUrl,
+    project_id: context.binding.projectId,
+    note: 'This root was promoted to hosted-only (D-288). The hosted app is canonical; local canonical writes refuse by default.',
+  };
+  await writeFile(markerPath, `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
+}
+
+async function removePromotedMarker(rootDir) {
+  await rm(path.join(rootDir, ...PROMOTED_MARKER), { force: true });
+}

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/serialization.js

@@ -46,7 +46,33 @@ export function memoryRootLockPath(rootDir) {
  * Runs `fn` while holding the serialization lock for `rootDir`. Reentrant:
  * a nested call from inside the lock holder runs immediately.
  */
+// Commands that stay allowed on a promoted root: the transition flows
+// themselves, plus recovery tooling that must be able to repair state.
+const PROMOTED_ROOT_ALLOWED_COMMANDS = new Set([
+  'promote-hosted',
+  'demote-hosted',
+  'bootstrap',
+]);
+
+async function assertNotPromotedRoot(rootDir, label) {
+  if (PROMOTED_ROOT_ALLOWED_COMMANDS.has(label)) return;
+  if (process.env.VIBECOMPASS_ALLOW_PROMOTED_ROOT_WRITES === '1') return;
+  const markerPath = path.join(rootDir, 'state', 'promoted-root.json');
+  let marker;
+  try {
+    marker = JSON.parse(await readFile(markerPath, 'utf8'));
+  } catch {
+    return;
+  }
+  throw new Error(
+    `This root was promoted to hosted-only${marker?.promoted_at ? ` on ${marker.promoted_at}` : ''}: the hosted app is canonical and local writes here can never sync back (D-288). `
+    + 'Make changes on the hosted dashboard, run vibecompass demote-hosted to make this root canonical again, '
+    + 'or set VIBECOMPASS_ALLOW_PROMOTED_ROOT_WRITES=1 to override deliberately.',
+  );
+}
+
 export async function withMemoryRootLock(rootDir, label, fn, options = {}) {
+  await assertNotPromotedRoot(rootDir, label);
   const key = await canonicalizeMemoryRootKey(rootDir);
   const held = heldRoots.getStore();
   if (await findHeldMemoryRootKey(held, key)) {

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) {