@vibecompass/vibecompass 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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).

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

package/package.json

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

package/src/cli.js

@@ -568,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);
@@ -1461,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.`);
   }
 
@@ -1495,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',

package/src/docs-review.js

@@ -7,7 +7,7 @@ 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']);
@@ -785,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$/, ''),
     });
   }
 
@@ -829,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;
 
@@ -1705,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.',
@@ -1746,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',
@@ -1791,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',

package/src/init.js

@@ -257,13 +257,42 @@ function normalizeInitOptions(options) {
     }
     seenRepoIds.add(repo.id);
 
-    if (typeof repo.remote !== 'string' || repo.remote.trim() === '') {
-      throw new Error(`repo "${repo.id}" requires a non-empty remote.`);
+    const source = typeof repo.source === 'string' && repo.source.trim() !== ''
+      ? repo.source.trim()
+      : null;
+    const pathValue = typeof repo.path === 'string' && repo.path.trim() !== ''
+      ? repo.path.trim()
+      : null;
+    const remote = typeof repo.remote === 'string' ? repo.remote.trim() : '';
+
+    if (source && !['git', 'local'].includes(source)) {
+      throw new Error(`repo "${repo.id}" source must be git or local.`);
+    }
+
+    if (source === 'local' || (!source && !remote && pathValue)) {
+      if (!['local-only', 'local-primary'].includes(preparedOptions.mode)) {
+        throw new Error(`repo "${repo.id}" local sources are supported only in local-only or local-primary mode.`);
+      }
+
+      if (!pathValue) {
+        throw new Error(`repo "${repo.id}" source local requires a non-empty path.`);
+      }
+
+      return {
+        id: repo.id,
+        source: 'local',
+        path: pathValue,
+      };
+    }
+
+    if (!remote) {
+      throw new Error(`repo "${repo.id}" requires a non-empty remote, or use a local repo source with source: local and path.`);
     }
 
     return {
       id: repo.id,
-      remote: repo.remote,
+      ...(source === 'git' ? { source: 'git' } : {}),
+      remote,
       ...(repo.defaultBranch ? { default_branch: repo.defaultBranch } : {}),
     };
   });

package/src/project-memory.js

@@ -34,7 +34,7 @@ const KNOWN_PROJECT_FIELDS = new Set([
   'sync',
   'metadata',
 ]);
-const KNOWN_REPO_FIELDS = new Set(['id', 'remote', 'default_branch']);
+const KNOWN_REPO_FIELDS = new Set(['id', 'source', 'remote', 'path', 'default_branch']);
 const KNOWN_SYNC_FIELDS = new Set([
   'provider',
   'api_url',
@@ -278,8 +278,25 @@ function validateProjectData(data, relativePath) {
         repoIds.push(repo.id);
       }
 
-      if (typeof repo.remote !== 'string' || repo.remote.trim() === '') {
-        errors.push(createError(relativePath, 'project-invalid-repo-remote', `${prefix}.remote must be a non-empty string.`));
+      const source = typeof repo.source === 'string' && repo.source.trim() !== ''
+        ? repo.source.trim()
+        : null;
+      const remote = typeof repo.remote === 'string' ? repo.remote.trim() : '';
+      const sourcePath = typeof repo.path === 'string' ? repo.path.trim() : '';
+
+      if (source && !['git', 'local'].includes(source)) {
+        errors.push(createError(relativePath, 'project-invalid-repo-source', `${prefix}.source must be git or local.`));
+      }
+
+      if (source === 'local' || (!source && !remote && sourcePath)) {
+        if (!['local-only', 'local-primary'].includes(data.mode)) {
+          errors.push(createError(relativePath, 'project-invalid-repo-source', `${prefix}.source local is supported only when mode is local-only or local-primary.`));
+        }
+        if (!sourcePath) {
+          errors.push(createError(relativePath, 'project-invalid-repo-path', `${prefix}.path must be a non-empty string for local sources.`));
+        }
+      } else if (!remote) {
+        errors.push(createError(relativePath, 'project-invalid-repo-remote', `${prefix}.remote must be a non-empty string for Git-backed sources.`));
       }
     }
   }
@@ -336,10 +353,12 @@ function validateProjectData(data, relativePath) {
       repo_ids: repoIds,
       repos: Array.isArray(data.repos)
         ? data.repos
-            .filter((repo) => isPlainObject(repo) && typeof repo.id === 'string' && typeof repo.remote === 'string')
+            .filter((repo) => isPlainObject(repo) && typeof repo.id === 'string')
             .map((repo) => ({
               id: repo.id,
-              remote: repo.remote,
+              source: typeof repo.source === 'string' ? repo.source : (typeof repo.remote === 'string' ? 'git' : 'local'),
+              remote: typeof repo.remote === 'string' ? repo.remote : null,
+              path: typeof repo.path === 'string' ? repo.path : null,
               default_branch: typeof repo.default_branch === 'string' ? repo.default_branch : null,
             }))
         : [],

package/src/read-model.js

@@ -105,7 +105,9 @@ function buildProjectSummary(scanResult, currentManifest, freshness, existingMan
   const extracted = scanResult.project.extracted ?? {};
   const repos = (extracted.repos ?? []).map((repo) => ({
     id: repo.id,
+    source: repo.source,
     remote: repo.remote,
+    path: repo.path,
     default_branch: repo.default_branch,
   }));
 
@@ -451,10 +453,12 @@ function buildRepoAliasMap(repos) {
     aliases.set(repo.id, repo.id);
     aliases.set(repo.id.toLowerCase(), repo.id);
 
-    const remoteName = repo.remote
-      .replace(/\.git$/, '')
-      .split('/')
-      .pop();
+    const remoteName = typeof repo.remote === 'string'
+      ? repo.remote
+          .replace(/\.git$/, '')
+          .split('/')
+          .pop()
+      : null;
 
     if (remoteName) {
       aliases.set(remoteName, repo.id);

package/src/scaffold.js

@@ -206,7 +206,7 @@ function generateContextMarkdown(options) {
   const workflow = resolveWorkflowSettings(options.projectConfig);
   const promptCommands = renderPromptCommandLines({ rootRelativePath }).join('\n');
   const repos = options.projectConfig.repos
-    .map((repo) => `- \`${repo.id}\` → ${repo.remote}`)
+    .map((repo) => `- \`${repo.id}\` → ${formatRepoDescriptor(repo)}`)
     .join('\n');
 
   return `# Project Context — ${projectName}
@@ -348,7 +348,7 @@ automatically by package commands.
 function generateStarterArchitectureDoc(projectConfig) {
   const repos = projectConfig.repos.map((repo) => repo.id);
   const repoLines = projectConfig.repos
-    .map((repo) => `- \`${repo.id}\` — ${repo.remote}${repo.default_branch ? ` (${repo.default_branch})` : ''}`)
+    .map((repo) => `- \`${repo.id}\` — ${formatRepoDescriptor(repo)}${repo.default_branch ? ` (${repo.default_branch})` : ''}`)
     .join('\n');
   const repoEvidence = projectConfig.repos
     .map((repo) => `- \`${repo.id}:/\` — declared repository root`)
@@ -379,7 +379,7 @@ ${repoLines}
 ## Coverage
 Confirmed:
 - Project identity and mode from \`project.yaml\`
-- Declared repository IDs and remotes from \`project.yaml\`
+- Declared repository IDs and source descriptors from \`project.yaml\`
 - Project-memory root layout created by \`vibecompass init\`
 
 Not yet documented:
@@ -425,7 +425,7 @@ Do not copy this example as-is. Allocate real decision IDs from the current cano
 function generateStarterSessionNote(options) {
   const sessionDate = sessionDateFromGeneratedAt(options.generatedAt);
   const projectConfig = options.projectConfig;
-  const repoLines = projectConfig.repos.map((repo) => `- \`${repo.id}\` — ${repo.remote}`).join('\n');
+  const repoLines = projectConfig.repos.map((repo) => `- \`${repo.id}\` — ${formatRepoDescriptor(repo)}`).join('\n');
 
   return `# Session — ${sessionDate}-1 — Project Memory Initialized
 
@@ -458,6 +458,14 @@ ${repoLines}
 `;
 }
 
+function formatRepoDescriptor(repo) {
+  if (repo.source === 'local') {
+    return `local folder ${repo.path}`;
+  }
+
+  return repo.remote;
+}
+
 function generateArchitectureGuide(projectConfig) {
   return `# Architecture
 

package/src/setup.js

@@ -882,12 +882,13 @@ async function promptForRepos(prompter, cwd) {
 
   for (let index = 0; index < repoCount; index += 1) {
     const ordinal = index + 1;
-    const repo = {
-      id: await askInput(prompter, `Repo ${ordinal} id`, {
-        defaultValue: repoCount === 1 ? repoIdDefault : `repo-${ordinal}`,
-      }),
-      remote: await askInput(prompter, `Repo ${ordinal} remote`),
-    };
+    const repoId = await askInput(prompter, `Repo ${ordinal} id`, {
+      defaultValue: repoCount === 1 ? repoIdDefault : `repo-${ordinal}`,
+    });
+    const remote = await askOptionalInput(prompter, `Repo ${ordinal} remote (blank for local folder)`);
+    const repo = remote
+      ? { id: repoId, remote }
+      : { id: repoId, source: 'local', path: '.' };
 
     const defaultBranch = await askOptionalInput(prompter, `Repo ${ordinal} default branch`);
     if (defaultBranch) {

package/src/status.js

@@ -143,7 +143,9 @@ async function readProjectSummary(projectFilePath) {
             .filter((repo) => repo && typeof repo === 'object')
             .map((repo) => ({
               id: typeof repo.id === 'string' ? repo.id : null,
+              source: typeof repo.source === 'string' ? repo.source : (typeof repo.remote === 'string' ? 'git' : 'local'),
               remote: typeof repo.remote === 'string' ? repo.remote : null,
+              path: typeof repo.path === 'string' ? repo.path : null,
               defaultBranch: typeof repo.default_branch === 'string' ? repo.default_branch : null,
             }))
             .filter((repo) => repo.id)

package/src/workflows/registry.js

@@ -99,7 +99,7 @@ When the user says \`docs review\`, run this workflow inside the current Claude
 
 ## Goal
 
-Turn starter project memory into evidence-backed architecture docs under \`architecture/<domain>/<feature>/<component>.md\`, a projected coverage plan, and optional accepted decision recommendations.
+Turn starter project memory into evidence-backed architecture docs under \`architecture/<domain>/<feature>/<component>.md\`, a projected coverage plan, a journey-aware project map, and optional accepted decision recommendations.
 
 ## Steps
 
@@ -109,8 +109,8 @@ Turn starter project memory into evidence-backed architecture docs under \`archi
    - produce a coverage plan before reading broad source bodies
    - read targeted source files only when the coverage plan needs evidence
 3. Run \`vibecompass docs-review --guided --llm <tool-name> --model <model-name>\` to record the review marker and print the canonical docs-review contract. Use the current AI tool name and model when known.
-4. Present the evidence inventory, coverage plan, proposed architecture docs, blindspots, token-budget risks, and any decision candidates before generating accepted output.
-5. Draft only output the user accepts. The accepted plan must be fenced as \`vibecompass-coverage-plan version=1\`. Accepted architecture docs must be fenced as \`vibecompass-architecture-doc path=architecture/domain/feature/component.md\` blocks and must include required frontmatter: \`domain\`, \`feature\`, \`component\`, and \`status\`. Accepted local decisions may be fenced as \`vibecompass-decision-recommendation target=decisions/domain.md\` blocks without D-numbers.
+4. Present the evidence inventory, coverage plan, user journey, project/system map, proposed architecture docs, blindspots, token-budget risks, and any decision candidates before generating accepted output.
+5. Draft only output the user accepts. The accepted plan must be fenced as \`vibecompass-coverage-plan version=1\`. Accepted architecture docs must be fenced as \`vibecompass-architecture-doc path=architecture/domain/feature/component.md\` blocks and must include required frontmatter: \`domain\`, \`feature\`, \`component\`, and \`status\`. The accepted \`architecture/overview/project-shape.md\` doc should include exactly one \`vibecompass-project-map version=1\` JSON block with journey-facing features, entry points, and evidence-backed relationships. Accepted local decisions may be fenced as \`vibecompass-decision-recommendation target=decisions/domain.md\` blocks without D-numbers.
 6. Keep each generated architecture doc focused and retrieval-oriented. Soft budget: under 12000 bytes per doc unless the extra detail is necessary and called out in review metadata or retrieval guidance.
 7. Write the accepted fenced blocks to \`${outputPath}\`.
 8. Run \`vibecompass docs-review --apply-output\` to validate and apply the accepted blocks. If accepted docs were written manually outside the output file, run \`vibecompass docs-review --complete\` after confirming the marker should be completed.