@vibecompass/vibecompass 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.9.0 - 2026-06-14
+
+- Add explicit local folder sources for non-Git projects: `project.yaml.repos[]` may use `source: local` plus `path`, and `init` accepts `--repo-local <id=path>`.
+- Keep blank Git remotes invalid, but report an actionable `--repo-local` hint when `--repo <id=remote>` resolves to an empty value.
+- Update guided init, starter docs, status, scanning, and read-model output so local-source roots validate and render cleanly.
+- Bump docs-review to `VibeCompass Docs Review Prompt v3`, requiring first-pass docs to include a user journey, project/system map, and core journey-facing feature summaries.
+- Add `vibecompass-project-map version=1` support inside `architecture/overview/project-shape.md`, including nested-fence parsing so generated overview docs can round-trip the machine-readable journey map block.
+
+## 0.8.0 - 2026-06-12
+
+- Add named sync targets (D-236): `connect-hosted --target <name>` binds one project root to multiple hosted environments (for example `dev` on localhost and `prod` on vibecompass.dev).
+- Add a `sync-target` command to list named targets and switch the default; flat `sync` fields in project.yaml always mirror the default target so older CLIs keep working.
+- Add `--sync-target <name>` to `push`, `pull-preview`, `pull-export`, and `docs-review` for per-command environment selection; unknown target names error instead of falling back.
+- Partition local sync cursor state per target (D-237): each target keeps its own last-pushed revision and pull previews, identity-checked against its URL and project id, so one environment's history can never become another environment's baseline.
+- Carry the existing sync history over when a flat binding is converted into its first named target with the same URL and project id.
+- Record the submitted sync target in the docs-review marker so `--poll-hosted` stays pinned to the environment the run was submitted to.
+
 ## 0.7.0 - 2026-05-30
 
 - Add `docs-review --rebuild` with dry-run preview, scoped architecture paths, and archive-based stale-doc preparation.

package/README.md

@@ -38,6 +38,15 @@ Create project memory:
 npx -y @vibecompass/vibecompass init --guided
 ```
 
+For a folder that is not a Git repo, use an explicit local source:
+
+```bash
+npx -y @vibecompass/vibecompass init \
+  --name "My Project" \
+  --mode local-primary \
+  --repo-local app=.
+```
+
 Check what to do next:
 
 ```bash
@@ -125,7 +134,7 @@ After setup, use these phrases inside your AI coding tool:
 - `planning mode`
 - `review handoff`
 - `address review`
-- `close session`
+- `close session` / `end session`
 - `docs review`
 
 The npm package owns the file mechanics. Your AI session owns reading the
@@ -146,6 +155,28 @@ vibecompass connect-hosted \
 vibecompass push --root .compass
 ```
 
+### Multiple environments
+
+One project can have named sync targets (for example a local dev server and
+production) so you never have to rebind:
+
+```bash
+# add targets once — the first one becomes the default
+vibecompass connect-hosted --root .compass --target dev \
+  --sync-api-url http://localhost:3000 --sync-project-id vc_proj_dev \
+  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN
+vibecompass connect-hosted --root .compass --target prod \
+  --sync-api-url https://vibecompass.dev --sync-project-id vc_proj_prod \
+  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN_PROD
+
+# then pick per command, or switch the default
+vibecompass push --root .compass --sync-target prod
+vibecompass sync-target prod --root .compass
+```
+
+Tip: if you already have a single (flat) binding, add it as your first named
+target using the same URL and project id — its sync history carries over.
+
 See https://vibecompass.dev/developers for the full local-primary workflow.
 
 ## JavaScript API

package/package.json

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

package/src/cli.js

@@ -2,7 +2,7 @@
 
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
-import { connectHostedProjectMemory, initializeProjectMemory } from './init.js';
+import { connectHostedProjectMemory, initializeProjectMemory, setDefaultSyncTarget } from './init.js';
 import { preflightDocsReview } from './docs-review.js';
 import { resolveConnectHostedCliOptions, resolveInitCliOptions } from './setup.js';
 import { closeProjectSession, listProjectSessions, startProjectSession, switchProjectSession } from './session.js';
@@ -140,6 +140,10 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     });
     io.stdout.write(`Connected hosted VibeCompass for ${result.mode}\n`);
     io.stdout.write(`Updated ${result.projectFilePath}\n`);
+    if (result.syncTarget) {
+      io.stdout.write(`Sync target: ${result.syncTarget.name} (default: ${result.syncTarget.defaultTarget})\n`);
+      io.stdout.write(`Select per command with --sync-target ${result.syncTarget.name}, or switch the default with: vibecompass sync-target ${result.syncTarget.name}\n`);
+    }
     io.stdout.write(`Next step: set ${result.syncEnvVar} locally before your first hosted command.\n`);
     if (result.mode === 'local-primary') {
       io.stdout.write('Then run: vibecompass push\n');
@@ -150,6 +154,28 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'sync-target') {
+    const result = await setDefaultSyncTarget({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    if (parsed.options.targetName) {
+      io.stdout.write(
+        result.changed
+          ? `Default sync target set to ${result.defaultTarget}\n`
+          : `Default sync target already ${result.defaultTarget}\n`,
+      );
+      io.stdout.write(`Updated ${result.projectFilePath}\n`);
+    } else {
+      io.stdout.write(`Default sync target: ${result.defaultTarget ?? '(none)'}\n`);
+    }
+    for (const [name, target] of Object.entries(result.targets)) {
+      const marker = name === result.defaultTarget ? '*' : ' ';
+      io.stdout.write(`${marker} ${name}: ${target.api_url} (project ${target.project_id}, env ${target.credential_env_var})\n`);
+    }
+    return 0;
+  }
+
   if (parsed.command === 'status') {
     const result = await getProjectStatus({
       ...parsed.options,
@@ -401,6 +427,10 @@ export function parseCliArgs(argv) {
       return parseConnectHostedArgs(rest);
     }
 
+    if (command === 'sync-target') {
+      return parseSyncTargetArgs(rest);
+    }
+
     if (command === 'status') {
       return parseStatusArgs(rest);
     }
@@ -538,6 +568,11 @@ export function parseCliArgs(argv) {
         parsed.repos.push({ id, remote });
         break;
       }
+      case '--repo-local': {
+        const [id, repoPath] = splitAssignment(value, '--repo-local');
+        parsed.repos.push({ id, source: 'local', path: repoPath });
+        break;
+      }
       case '--repo-branch': {
         const [id, defaultBranch] = splitAssignment(value, '--repo-branch');
         parsed.repoBranches.set(id, defaultBranch);
@@ -702,6 +737,9 @@ function parseConnectHostedArgs(argv) {
       case '--root':
         parsed.rootDir = value;
         break;
+      case '--target':
+        parsed.targetName = value;
+        break;
       case '--sync-api-url':
         parsed.syncApiUrl = value;
         break;
@@ -726,6 +764,7 @@ function parseConnectHostedArgs(argv) {
     command: 'connect-hosted',
     options: {
       rootDir: parsed.rootDir,
+      ...(parsed.targetName ? { targetName: parsed.targetName } : {}),
       ...(syncValues.length > 0
         ? {
             sync: {
@@ -1128,6 +1167,9 @@ function parseDocsReviewArgs(argv) {
       case '--artifact':
         parsed.artifactId = value;
         break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
       case '--max-tokens':
         parsed.maxTokens = value;
         break;
@@ -1145,7 +1187,72 @@ function parseDocsReviewArgs(argv) {
 function parsePushArgs(argv) {
   return {
     command: 'push',
-    options: parseRootOnlyArgs(argv, 'push'),
+    options: parseRootAndSyncTargetArgs(argv, 'push'),
+  };
+}
+
+function parseRootAndSyncTargetArgs(argv, commandName) {
+  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 '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for ${commandName}.`);
+    }
+  }
+
+  return parsed;
+}
+
+function parseSyncTargetArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (!token.startsWith('--')) {
+      if (parsed.targetName !== undefined) {
+        throw new Error(`Unexpected argument "${token}".`);
+      }
+      parsed.targetName = token;
+      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;
+      default:
+        throw new Error(`Unknown flag "${token}" for sync-target.`);
+    }
+  }
+
+  return {
+    command: 'sync-target',
+    options: parsed,
   };
 }
 
@@ -1173,6 +1280,9 @@ function parsePullPreviewArgs(argv) {
       case '--root':
         parsed.rootDir = value;
         break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
       default:
         throw new Error(`Unknown flag "${token}".`);
     }
@@ -1206,6 +1316,9 @@ function parsePullExportArgs(argv) {
       case '--root':
         parsed.rootDir = value;
         break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
       case '--preview-token':
         parsed.previewToken = value;
         break;
@@ -1353,6 +1466,11 @@ function writeWarnings(io, warnings = []) {
 function splitAssignment(value, flagName) {
   const separatorIndex = value.indexOf('=');
   if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
+    if (flagName === '--repo' && separatorIndex > 0 && separatorIndex === value.length - 1) {
+      throw new Error(
+        '--repo remote resolved to empty. For a non-Git folder, use --repo-local <id=path> instead of --repo <id=remote>.',
+      );
+    }
     throw new Error(`${flagName} expects id=value.`);
   }
 
@@ -1364,6 +1482,7 @@ function usageText() {
     'Usage:',
     '  vibecompass init --name <project-name> --mode <local-only|local-primary|hosted-only> --repo <id=remote> [options]',
     '  vibecompass connect-hosted [options]',
+    '  vibecompass sync-target [<name>] [options]',
     '  vibecompass status [options]',
     '  vibecompass refresh-workflow [--dry-run|--apply] [options]',
     '  vibecompass start-session --id <lane-id> --working-on <text> [options]',
@@ -1386,7 +1505,8 @@ function usageText() {
     '  --placement <workspace-root|dedicated-memory-repo|primary-repo>',
     '                                        Optional explicit placement pattern',
     '  --guided                             Ask placement and setup questions interactively',
-    '  --repo <id=remote>                   Repeatable repo descriptor',
+    '  --repo <id=remote>                   Repeatable Git-backed repo descriptor',
+    '  --repo-local <id=path>               Repeatable local folder source for non-Git projects',
     '  --repo-branch <id=branch>            Optional per-repo default branch',
     '  --sync-api-url <url>                 Optional hosted sync api_url',
     '  --sync-project-id <id>               Optional hosted sync project_id',
@@ -1405,10 +1525,17 @@ function usageText() {
     '',
     'Connect-hosted options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --target <name>                      Add or update a named sync target (e.g. dev, prod)',
+    '                                        First named target becomes the default; flat sync fields mirror the default target',
     '  --sync-api-url <url>                 Hosted sync api_url',
     '  --sync-project-id <id>               Hosted sync project_id',
     '  --sync-credential-env-var <name>     Hosted sync env var reference',
-    '                                        Replaces any existing project.yaml sync binding',
+    '                                        Without --target, replaces any existing flat project.yaml sync binding',
+    '',
+    'Sync-target options:',
+    '  vibecompass sync-target              List named sync targets and the current default',
+    '  vibecompass sync-target <name>       Switch the default sync target (re-mirrors flat sync fields)',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
     '',
     'Status options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
@@ -1463,6 +1590,7 @@ function usageText() {
     '',
     'Sync transport options:',
     '  push --root <path>                   Push canonical local project memory to hosted',
+    '  --sync-target <name>                 Use a named sync target for this command (push, pull-preview, pull-export, docs-review)',
     '  pull-preview --root <path>           Preview hosted proposals and remote state',
     '  pull-preview --no-pending-proposals  Exclude pending proposals from preview',
     '  pull-export --proposal <id>          Export a selected proposal; repeatable',

package/src/docs-review.js

@@ -5,8 +5,9 @@ import { parseFrontmatter } from './frontmatter.js';
 import { sha256Text } from './hash.js';
 import { writeStateManifest } from './manifest.js';
 import { parseSimpleYaml } from './simple-yaml.js';
+import { readSyncCursor, resolveSyncBinding } from './sync-binding.js';
 
-const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v2';
+const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v3';
 const ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES = 12000;
 const COVERAGE_PLAN_OUTPUT_VERSION = 1;
 const COVERAGE_PLAN_STATUSES = new Set(['accepted', 'deferred', 'missing']);
@@ -83,6 +84,7 @@ export async function preflightDocsReview(options = {}, environment = {}) {
     localProvider,
     runLocal: shouldRunLocal(options),
     anthropicEnvVar: options.anthropicEnvVar ?? 'ANTHROPIC_API_KEY',
+    syncTarget: options.syncTarget ?? null,
   });
   const reviewPrompt = renderReviewPrompt({
     project,
@@ -617,11 +619,10 @@ function resolveDocsReviewRuntime(project, options) {
     localProvider &&
     typeof options.env?.[localProvider.credentialEnvVar] === 'string' &&
     options.env[localProvider.credentialEnvVar].trim() !== '';
-  const hasHostedBinding =
-    project?.sync &&
-    typeof project.sync === 'object' &&
-    typeof project.sync.api_url === 'string' &&
-    typeof project.sync.project_id === 'string';
+  // Throws on an explicitly requested unknown/incomplete --sync-target so a
+  // typo can never fall back to a different environment (D-236).
+  const hostedBinding = resolveSyncBinding(project, options.syncTarget ?? null);
+  const hasHostedBinding = Boolean(hostedBinding);
 
   if (mode === 'local-only') {
     if (options.runLocal && !localProvider) {
@@ -663,11 +664,10 @@ function resolveDocsReviewRuntime(project, options) {
     if (hasHostedBinding) {
       return {
         provider: 'hosted',
-        api_url: project.sync.api_url,
-        project_id: project.sync.project_id,
-        ...(typeof project.sync.credential_env_var === 'string'
-          ? { credential_env_var: project.sync.credential_env_var }
-        : {}),
+        api_url: hostedBinding.apiUrl,
+        project_id: hostedBinding.projectId,
+        credential_env_var: hostedBinding.credentialEnvVar,
+        ...(hostedBinding.target ? { sync_target: hostedBinding.target } : {}),
       };
     }
 
@@ -699,11 +699,10 @@ function resolveDocsReviewRuntime(project, options) {
 
     return {
       provider: 'hosted',
-      api_url: project.sync.api_url,
-      project_id: project.sync.project_id,
-      ...(typeof project.sync.credential_env_var === 'string'
-        ? { credential_env_var: project.sync.credential_env_var }
-        : {}),
+      api_url: hostedBinding.apiUrl,
+      project_id: hostedBinding.projectId,
+      credential_env_var: hostedBinding.credentialEnvVar,
+      ...(hostedBinding.target ? { sync_target: hostedBinding.target } : {}),
     };
   }
 
@@ -786,13 +785,13 @@ function extractAnthropicText(body) {
 
 function parseArchitectureDocBlocks(source) {
   const blocks = [];
-  const pattern = /^```vibecompass-architecture-doc\s+path=([^\s`]+)\s*\n([\s\S]*?)^```[ \t]*$/gm;
+  const pattern = /^(`{3,})vibecompass-architecture-doc\s+path=([^\s`]+)\s*\n([\s\S]*?)^\1[ \t]*$/gm;
   let match;
 
   while ((match = pattern.exec(source)) !== null) {
     blocks.push({
-      path: normalizeBlockPath(match[1]),
-      content: match[2].replace(/\n$/, ''),
+      path: normalizeBlockPath(match[2]),
+      content: match[3].replace(/\n$/, ''),
     });
   }
 
@@ -830,8 +829,8 @@ function parseDecisionRecommendationBlocks(source) {
 }
 
 function countMalformedArchitectureDocFences(source) {
-  const fencePattern = /^```vibecompass-architecture-doc\b.*$/gm;
-  const acceptedOpeningPattern = /^```vibecompass-architecture-doc\s+path=[^\s`]+\s*$/;
+  const fencePattern = /^`{3,}vibecompass-architecture-doc\b.*$/gm;
+  const acceptedOpeningPattern = /^`{3,}vibecompass-architecture-doc\s+path=[^\s`]+\s*$/;
   let count = 0;
   let match;
 
@@ -1107,8 +1106,15 @@ async function submitHostedDocsReview(options) {
     `api/sync/projects/${encodeURIComponent(options.runtime.project_id)}/docs-review`,
     ensureTrailingSlash(options.runtime.api_url),
   );
+  // D-237: the baseline must come from the submitted target's own cursor so a
+  // dev revision can never be sent as another environment's baseline.
+  const submitCursor = readSyncCursor(options.manifest?.manifest?.sync, {
+    target: options.runtime.sync_target ?? null,
+    apiUrl: options.runtime.api_url,
+    projectId: options.runtime.project_id,
+  });
   const baselineRemoteRevisionId = normalizeUuid(
-    options.manifest?.manifest?.sync?.last_successful_remote_revision,
+    submitCursor.last_successful_remote_revision,
   );
   const response = await options.fetch(endpoint.href, {
     method: 'POST',
@@ -1699,18 +1705,20 @@ function renderReviewPrompt(options) {
     'Stage 1 — Evidence inventory:',
     '- Build a compact repo inventory from file paths, manifests/config files, route/job/test directories, and existing architecture frontmatter before reading large file bodies.',
     '- Mine finalized session notes for decision candidates and product constraints, but cap proposed decisions to the five highest-value architecture choices.',
-    '- Identify candidate domains, features, components, and ownership boundaries with concrete `repo:path` evidence.',
+    '- Identify candidate domains, features, components, ownership boundaries, user journey entry points, feature-to-feature relationships, and system-layer connections with concrete `repo:path` evidence.',
     '- Do not fetch or summarize broad source bodies until the coverage plan says a file is needed.',
     '',
     'Stage 2 — Coverage plan:',
     '- Propose the smallest useful architecture-doc set that will let future agents understand the project and retrieve targeted context.',
-    '- Prioritize entry points, data ownership, external integrations, jobs/async boundaries, auth/security boundaries, and test surfaces.',
+    '- The minimum useful set must cover: user journey, project/system map (frontend/backend/API/data/integration structure and connections), and summaries of the core journey-facing features.',
+    '- Prioritize entry points, user-flow/gating relationships, data ownership, external integrations, jobs/async boundaries, auth/security boundaries, and test surfaces.',
     '- Mark each proposed doc as `comprehensive`, `partial`, or `initial`, with the reason and blindspots.',
     '- Emit the accepted plan as one `vibecompass-coverage-plan version=1` JSON fence before architecture-doc blocks.',
     '- Ask for user acceptance before emitting fenced architecture-doc blocks.',
     '',
     'Stage 3 — Bounded doc generation:',
     '- Generate only accepted docs, one complete fenced block per architecture path.',
+    '- Ensure `architecture/overview/project-shape.md` includes a concise system map plus one `vibecompass-project-map version=1` JSON fence that lists journey-facing features and supported relationships.',
     '- Keep docs concise and retrieval-oriented: explain contracts, flows, invariants, and ownership; do not rewrite source code or produce file-by-file walkthroughs.',
     `- Soft size budget: keep each generated architecture doc under ${ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES} bytes unless the extra detail is necessary and called out in Blindspots or Retrieval guidance.`,
     '- Include only the most important involved files; prefer representative entry points and owned contracts over exhaustive file lists.',
@@ -1740,18 +1748,46 @@ function renderReviewPrompt(options) {
     '',
     '## Review Rules',
     '1. Do not delete `architecture/overview/project-shape.md`.',
-    '2. Add evidence-backed component docs alongside the overview.',
-    '3. Update `architecture/overview/project-shape.md` coverage and blindspot sections to summarize what has now been mapped.',
-    '4. Keep all implementation claims source-backed with `repo:path` evidence.',
-    '5. Use only the exact confidence and coverage enum values listed above.',
-    '6. Put uncertainty in `Blindspots`; do not fill gaps with guesses.',
-    '7. Do not append real `D-NNN` decisions without explicit user acceptance. Propose candidate decisions separately.',
-    '8. Do not edit `decisions/INDEX.md` directly unless a canonical decision file was explicitly accepted and appended.',
-    '9. Optimize for future retrieval: project-level docs stay compact; component docs carry focused context for a specific area.',
+    '2. Add or update `architecture/overview/project-shape.md` so it explains the project/system map and includes the accepted `vibecompass-project-map version=1` block.',
+    '3. Add evidence-backed component docs alongside the overview for core journey-facing features and important supporting systems.',
+    '4. Update `architecture/overview/project-shape.md` coverage and blindspot sections to summarize what has now been mapped.',
+    '5. Keep all implementation claims source-backed with `repo:path` evidence.',
+    '6. Use only the exact confidence and coverage enum values listed above.',
+    '7. Put uncertainty in `Blindspots`; do not fill gaps with guesses.',
+    '8. Do not append real `D-NNN` decisions without explicit user acceptance. Propose candidate decisions separately.',
+    '9. Do not edit `decisions/INDEX.md` directly unless a canonical decision file was explicitly accepted and appended.',
+    '10. Optimize for future retrieval: project-level docs stay compact; component docs carry focused context for a specific area.',
+    '',
+    '## Project Map Block',
+    'Include exactly one project-map block inside `architecture/overview/project-shape.md` when the user accepts journey/system mapping output:',
+    '',
+    '```vibecompass-project-map version=1',
+    '{',
+    '  "features": [',
+    '    {',
+    '      "domain": "Domain name matching architecture frontmatter",',
+    '      "feature": "Feature name matching architecture frontmatter",',
+    '      "is_entry_point": true,',
+    '      "summary": "Short user-facing feature summary"',
+    '    }',
+    '  ],',
+    '  "relationships": [',
+    '    {',
+    '      "from": { "domain": "Domain", "feature": "Feature" },',
+    '      "to": { "domain": "Domain", "feature": "Feature" },',
+    '      "kind": "gates | navigates_to | depends_on | writes_to",',
+    '      "label": "Short evidence-backed relationship label"',
+    '    }',
+    '  ]',
+    '}',
+    '```',
+    '',
+    'Only include relationships supported by evidence. Prefer `navigates_to` and `gates` for the main user journey; use `depends_on` and `writes_to` for supporting system relationships. If useful journey links cannot be inferred, state that as a coverage gap rather than inventing links.',
     '',
     '## Output Contract',
     'First provide a concise findings summary with:',
     '- mapped areas',
+    '- user journey and project/system map coverage',
     '- gaps/blindspots',
     '- evidence inventory summary',
     '- coverage plan and proposed architecture docs',
@@ -1785,6 +1821,8 @@ function renderReviewPrompt(options) {
     '<complete markdown file content>',
     '```',
     '',
+    'If the complete markdown file content contains its own fenced block, such as `vibecompass-project-map version=1`, use a longer outer fence for the architecture-doc block (for example four backticks) so the inner fence stays inside the document body.',
+    '',
     'If the review surfaced accepted decision candidates, output each candidate as a separate block without assigning a D-number:',
     '',
     '```vibecompass-decision-recommendation target=decisions/cross-cutting.md',