@vibecompass/vibecompass 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # 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.
+- Make shared-checkout lane warnings honest about runnable isolation: unbound same-repo lanes now recommend `--branch <name> --worktree` for independent files or dev servers, including at `lane-env` where `PORT` is exported, while keeping `--claim` as the ownership-review fallback.
+- Suppress shared-checkout warnings when either the selected lane or the sibling lane is already worktree-bound, and add regression coverage for the symlink-root reentrancy and worktree-bound warning paths.
+
 ## 0.11.0 - 2026-07-03
 
 Phase 8 concurrent multi-session lanes (stages S1–S4). Highlights: a per-root

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.0",
+  "version": "0.11.2",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -151,7 +151,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     }
     if (result.runtime) {
       io.stdout.write(`Runtime: port ${result.runtime.port}, temp dir ${result.runtime.tmpDir}\n`);
-      io.stdout.write('Export into a shell with: eval "$(vibecompass lane-env)" (D-282; pass --session <lane-id> when multiple lanes are active).\n');
+      io.stdout.write('Export into a shell with: eval "$(vibecompass lane-env)" (D-282; pass --session <lane-id> when multiple lanes are active; use --worktree for independently runnable same-repo lanes).\n');
     }
     writeWarnings(io, result.warnings);
     writeAgentFileSyncResult(io, result.agentFileSync);
@@ -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',
@@ -2290,7 +2299,7 @@ function usageText() {
     '  --session <lane-id>                  Lane to export. Omitted: nearest worktree lane marker, else the single active lane; 2+ active lanes require --session or a marker (D-277)',
     '  --json                               Print the runtime assignment as JSON instead of shell export lines',
     '  --no-conventional                    Omit the conventional PORT/TMPDIR alias exports',
-    '                                        Consume with: eval "$(vibecompass lane-env)"; defaults come from project.yaml runtime.{port_base,port_step,tmp_base}',
+    '                                        Consume with: eval "$(vibecompass lane-env)"; defaults come from project.yaml runtime.{port_base,port_step,tmp_base}; use --worktree for independent same-repo dev servers',
     '',
     'Decision-log options (append-decision / next-decision-id):',
     '  --root <path>                        Project-memory root. Defaults to .compass',

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

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 /**
@@ -47,9 +47,9 @@ export function memoryRootLockPath(rootDir) {
  * a nested call from inside the lock holder runs immediately.
  */
 export async function withMemoryRootLock(rootDir, label, fn, options = {}) {
-  const key = path.resolve(rootDir);
+  const key = await canonicalizeMemoryRootKey(rootDir);
   const held = heldRoots.getStore();
-  if (held?.has(key)) {
+  if (await findHeldMemoryRootKey(held, key)) {
     return fn();
   }
 
@@ -78,6 +78,45 @@ export async function withMemoryRootLock(rootDir, label, fn, options = {}) {
   }
 }
 
+async function canonicalizeMemoryRootKey(rootDir) {
+  const resolved = path.resolve(rootDir);
+  try {
+    return await realpath(resolved);
+  } catch {
+    try {
+      return path.join(await realpath(path.dirname(resolved)), path.basename(resolved));
+    } catch {
+      return resolved;
+    }
+  }
+}
+
+async function findHeldMemoryRootKey(held, key) {
+  if (!held) {
+    return null;
+  }
+
+  if (held.has(key)) {
+    return key;
+  }
+
+  for (const heldKey of held) {
+    if (await memoryRootKeysReferToSamePath(heldKey, key)) {
+      return heldKey;
+    }
+  }
+
+  return null;
+}
+
+async function memoryRootKeysReferToSamePath(left, right) {
+  try {
+    return (await realpath(left)) === (await realpath(right));
+  } catch {
+    return false;
+  }
+}
+
 async function acquireDiskLock(key, label, options) {
   const lockDir = memoryRootLockPath(key);
   const attempts = options.attempts ?? DEFAULT_ATTEMPTS;

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,13 +153,19 @@ 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,
   });
   const highestDecisionId = await readHighestDecisionId(normalized.rootDir);
   const projectConfig = await readProjectConfig(normalized.projectFilePath);
@@ -275,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
@@ -425,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);
@@ -583,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,
@@ -850,7 +872,18 @@ export async function readLaneEnvironment(options = {}) {
     port: lane.runtime.port,
     tmpDir: lane.runtime.tmpDir,
     env,
-    warnings: [...markerContext.warnings, ...selection.warnings],
+    warnings: [
+      ...markerContext.warnings,
+      ...selection.warnings,
+      ...buildSharedCheckoutWarnings({
+        sessionId: selection.sessionId,
+        repos: lane.repos ?? [],
+        claims: lane.claims ?? [],
+        existingLanes: lanes.filter((item) => item.id !== selection.sessionId),
+        hasWorktree: Boolean(lane.worktreeContainer),
+        context: 'lane-env',
+      }),
+    ],
   };
 }
 
@@ -888,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);
@@ -1008,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.'),
   );
@@ -1494,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,
@@ -1536,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),
@@ -1569,6 +1608,8 @@ async function readLaneMetadata(sessionFilePath) {
       features: [],
       repos: [],
       claims: [],
+      architectureDocs: [],
+      decisionDomainFiles: [],
       startedAt: null,
       decisionSnapshot: {
         highestDecisionId: null,
@@ -1827,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.
@@ -2009,24 +2052,111 @@ 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 ?? []);
-    if (sharedRepos.length > 0 && options.claims.length === 0 && (lane.claims ?? []).length === 0) {
+    warnings.push(...buildSharedCheckoutWarnings({
+      sessionId: options.sessionId,
+      repos: options.repos,
+      claims: options.claims,
+      existingLanes: [lane],
+      hasWorktree: options.hasWorktree,
+      context: 'start-session',
+    }));
+
+    const bothLackClaims = options.claims.length === 0 && (lane.claims ?? []).length === 0;
+    if (
+      sharedRepos.length > 0 &&
+      (options.hasWorktree || lane.worktreeContainer) &&
+      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.`,
+      );
     }
   }
 
   return warnings;
 }
 
+function buildSharedCheckoutWarnings(options) {
+  if (options.hasWorktree) {
+    return [];
+  }
+
+  const warnings = [];
+  for (const lane of options.existingLanes) {
+    if (lane.worktreeContainer) {
+      continue;
+    }
+
+    const sharedRepos = intersect(options.repos, lane.repos ?? []);
+    if (sharedRepos.length === 0) {
+      continue;
+    }
+
+    const ownershipHint = options.claims.length === 0 && (lane.claims ?? []).length === 0
+      ? ' Add --claim values when shared-checkout work is intentional so ownership is reviewable.'
+      : '';
+    const runtimeHint = options.context === 'lane-env'
+      ? ' The exported PORT is a runtime assignment, not an independently runnable dev server for a shared checkout.'
+      : '';
+    warnings.push(
+      `Active session lane "${options.sessionId}" shares repo(s) ${sharedRepos.join(', ')} with unbound lane "${lane.id}" in the same checkout. ` +
+        `Use --branch <name> --worktree when lanes need independent files or dev servers; worktrees are the isolation boundary.${runtimeHint}${ownershipHint}`,
+    );
+  }
+
+  return warnings;
+}
+
 function collectLaneMetadataWarnings(lanes) {
   return lanes.flatMap((lane) => lane.warnings ?? []);
 }
@@ -2036,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;
       }
@@ -2056,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) {