@vibecompass/vibecompass 0.10.3 → 0.10.5

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.10.5 - 2026-06-20
+
+- Include compact docs-review evidence summaries in hosted review submissions, covering coverage score basis, source-inventory totals, documentation-plan totals, reconciliation deltas, producer stamps, and warning provenance.
+- Bump docs-review to `VibeCompass Docs Review Prompt v7` and reject accepted coverage plans where `areas[].linked_inventory_ids[]` references inventory IDs missing from the same plan's `completeness_inventory[]`; hosted parsing now enforces the same contract under `hosted-docs-review-parser-v6`.
+- Preserve optional `completeness_inventory[].repo_id` and `confidence` fields in accepted coverage-plan projections for hosted source-inventory filtering.
+
+## 0.10.4 - 2026-06-19
+
+- Add `vibecompass --version`, `vibecompass -v`, and `vibecompass version` CLI support.
+- Make bare `vibecompass init` errors point users to `vibecompass init --guided`.
+- Clarify guided first-session prompts so lane IDs are presented as short kebab-case slugs and reserved yes/no answers explain that pressing Enter accepts the suggested slug.
+- Propagate declared project repo ids into the first lane opened by guided init.
+
 ## 0.10.3 - 2026-06-19
 
 - Let `start-session` create a missing `## Current session` summary block in adopted existing `CLAUDE.md` files instead of failing after guided init.

package/package.json

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

package/src/cli.js

@@ -10,6 +10,7 @@ import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
 import { getProjectStatus, renderStatusText, toStatusJson } from './status.js';
 import { refreshWorkflow } from './refresh-workflow.js';
 import { inspectProjectCompatibility, formatCompatibilityWarnings } from './compatibility.js';
+import { PACKAGE_VERSION } from './version.js';
 import {
   applyPullExport,
   pullExportProjectMemory,
@@ -25,6 +26,11 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'version') {
+    io.stdout.write(`${PACKAGE_VERSION}\n`);
+    return 0;
+  }
+
   if (parsed.command === 'init') {
     const initPlan = await resolveInitCliOptions(parsed.options, {
       cwd: runtime.cwd,
@@ -99,6 +105,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
         toolingRootDir: initPlan.initOptions.toolingRootDir,
         sessionId: initPlan.sessionPlan.sessionId,
         workingOn: initPlan.sessionPlan.workingOn,
+        repos: initPlan.sessionPlan.repos,
         ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
       });
       io.stdout.write(`Started session ${sessionResult.sessionDate}-${sessionResult.sessionNumber}\n`);
@@ -425,6 +432,10 @@ export function parseCliArgs(argv) {
     return { command: 'help' };
   }
 
+  if (command === 'version' || command === '--version' || command === '-v') {
+    return { command: 'version' };
+  }
+
   if (command !== 'init') {
     if (command === 'start-session') {
       return parseStartSessionArgs(rest);
@@ -1495,6 +1506,8 @@ function splitAssignment(value, flagName) {
 function usageText() {
   return [
     'Usage:',
+    '  vibecompass --version',
+    '  vibecompass version',
     '  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]',

package/src/docs-review.js

@@ -17,8 +17,9 @@ import {
 import { readSyncCursor, resolveSyncBinding } from './sync-binding.js';
 import { PACKAGE_VERSION } from './version.js';
 
-const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v6';
+const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v7';
 const DOCS_REVIEW_PARSER_VERSION = 'docs-review-parser-v1';
+const DOCS_REVIEW_ACCEPTED_OUTPUT_CONTRACT_VERSION = 'docs-review-accepted-output-v7';
 const DOCS_REVIEW_DOCUMENTATION_PLAN_PROJECTION_VERSION = 'docs-review-documentation-plan-v1';
 const DOCUMENTATION_PLAN_STATE_VERSION = 1;
 const ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES = 12000;
@@ -26,6 +27,7 @@ const COVERAGE_PLAN_OUTPUT_VERSION = 1;
 const COVERAGE_PLAN_STATUSES = new Set(['accepted', 'deferred', 'missing']);
 const COVERAGE_LEVELS = new Set(['comprehensive', 'partial', 'initial', 'missing']);
 const ANCHOR_ACTIONS = new Set(['reuse', 'update', 'split', 'merge', 'defer', 'replace', 'new']);
+const SOURCE_CONFIDENCE_LEVELS = new Set(['high', 'medium', 'low']);
 const DOCUMENTATION_PLAN_RUN_SCOPES = new Set(['baseline', 'deepening']);
 const REBUILD_STALE_POLICIES = new Set(['keep', 'archive']);
 const PROJECT_MAP_PATH = 'architecture/overview/project-shape.md';
@@ -984,6 +986,7 @@ function buildCoverageProjection(blocks, options) {
   const areaById = new Map(areas.map((area) => [area.id, area]));
   const hasCompletenessInventory = Object.prototype.hasOwnProperty.call(plan, 'completeness_inventory');
   const completenessInventory = normalizeCompletenessInventory(plan.completeness_inventory, areaById);
+  validateCoverageAreaInventoryLinks(areas, completenessInventory);
   const statuses = countBy(areas, 'status');
   const coverage_levels = countBy(areas, 'coverage');
   const inventory_statuses = countBy(completenessInventory, 'status');
@@ -994,6 +997,7 @@ function buildCoverageProjection(blocks, options) {
       package_version: PACKAGE_VERSION,
       prompt_version: DOCS_REVIEW_PROMPT_VERSION,
       parser_version: DOCS_REVIEW_PARSER_VERSION,
+      accepted_output_contract: DOCS_REVIEW_ACCEPTED_OUTPUT_CONTRACT_VERSION,
       coverage_projection_version: COVERAGE_PLAN_OUTPUT_VERSION,
       ...(options.sourceInventory?.producer?.scanner_version
         ? { scanner_version: options.sourceInventory.producer.scanner_version }
@@ -1061,6 +1065,7 @@ function buildDocumentationPlanProjection(coverageProjection, sourceInventory, o
       package_version: PACKAGE_VERSION,
       prompt_version: DOCS_REVIEW_PROMPT_VERSION,
       parser_version: DOCS_REVIEW_PARSER_VERSION,
+      accepted_output_contract: DOCS_REVIEW_ACCEPTED_OUTPUT_CONTRACT_VERSION,
       documentation_plan_projection_version: DOCS_REVIEW_DOCUMENTATION_PLAN_PROJECTION_VERSION,
       coverage_projection_version: coverageProjection.version,
       ...(sourceInventory?.producer?.scanner_version
@@ -1177,8 +1182,12 @@ function normalizeCompletenessInventoryItem(item, index, ids, areaById, unknownC
 
   return {
     id,
+    ...(normalizeOptionalString(item.repo_id) ? { repo_id: normalizeOptionalString(item.repo_id) } : {}),
     ...(normalizeOptionalString(item.kind) ? { kind: normalizeOptionalString(item.kind) } : {}),
     ...(normalizeOptionalString(item.label) ? { label: normalizeOptionalString(item.label) } : {}),
+    ...(SOURCE_CONFIDENCE_LEVELS.has(normalizeOptionalString(item.confidence) ?? '')
+      ? { confidence: normalizeOptionalString(item.confidence) }
+      : {}),
     status,
     ...(coverageAreaIds.length > 0 ? { coverage_area_ids: coverageAreaIds } : {}),
     evidence: normalizeStringArray(item.evidence),
@@ -1193,6 +1202,28 @@ function formatUnknownCoverageAreaReferences(references) {
   return `Coverage plan completeness_inventory references unknown coverage area ids: ${formatted}`;
 }
 
+function validateCoverageAreaInventoryLinks(areas, completenessInventory) {
+  const inventoryIds = new Set(completenessInventory.map((item) => item.id));
+  const unknownInventoryReferences = [];
+  for (const area of areas) {
+    for (const inventoryId of area.linked_inventory_ids ?? []) {
+      if (!inventoryIds.has(inventoryId)) {
+        unknownInventoryReferences.push({ areaId: area.id, inventoryId });
+      }
+    }
+  }
+  if (unknownInventoryReferences.length > 0) {
+    throw new Error(formatUnknownLinkedInventoryReferences(unknownInventoryReferences));
+  }
+}
+
+function formatUnknownLinkedInventoryReferences(references) {
+  const formatted = references
+    .map((reference) => `"${reference.areaId}" -> "${reference.inventoryId}"`)
+    .join(', ');
+  return `Coverage plan areas reference unknown linked_inventory_ids: ${formatted}`;
+}
+
 function normalizeCoverageArea(area, index, ids) {
   if (!area || typeof area !== 'object' || Array.isArray(area)) {
     throw new Error(`Coverage plan area at index ${index} must be an object.`);
@@ -1461,6 +1492,7 @@ async function submitHostedDocsReview(options) {
   const baselineRemoteRevisionId = normalizeUuid(
     submitCursor.last_successful_remote_revision,
   );
+  const evidenceScope = await buildHostedDocsReviewEvidenceScope(options);
   const response = await options.fetch(endpoint.href, {
     method: 'POST',
     headers: {
@@ -1481,11 +1513,7 @@ async function submitHostedDocsReview(options) {
         ? { baseline_remote_revision_id: baselineRemoteRevisionId }
         : {}),
       local_root_revision: options.manifest?.manifest?.canonical?.local_root_revision,
-      evidence_scope: {
-        manifest_hash: options.manifest?.manifest?.canonical?.manifest_hash,
-        document_count: options.manifest?.manifest?.canonical?.document_count,
-        warning_count: options.manifest?.manifest?.canonical?.warning_count,
-      },
+      evidence_scope: evidenceScope,
     }),
   });
 
@@ -1517,6 +1545,75 @@ async function submitHostedDocsReview(options) {
   };
 }
 
+async function buildHostedDocsReviewEvidenceScope(options) {
+  const rootDir = options.rootDir;
+  const coverage = rootDir
+    ? await readJsonOptional(path.join(rootDir, 'state', 'docs-review-coverage.json'))
+    : null;
+  const sourceInventory = rootDir
+    ? await readJsonOptional(docsReviewSourceInventoryPath(rootDir))
+    : null;
+  const documentationPlan = rootDir
+    ? await readJsonOptional(path.join(rootDir, 'state', 'docs-review-documentation-plan.json'))
+    : null;
+  const warnings = Array.isArray(coverage?.warnings) ? coverage.warnings : [];
+
+  return {
+    manifest_hash: options.manifest?.manifest?.canonical?.manifest_hash,
+    document_count: options.manifest?.manifest?.canonical?.document_count,
+    warning_count: options.manifest?.manifest?.canonical?.warning_count,
+    ...(coverage?.producer ? { producer: coverage.producer } : {}),
+    ...(coverage ? { coverage_summary: summarizeHostedCoverage(coverage) } : {}),
+    ...(coverage?.source_inventory_summary
+      ? { source_inventory_summary: coverage.source_inventory_summary }
+      : sourceInventory
+        ? { source_inventory_summary: summarizeSourceInventory(sourceInventory) }
+        : {}),
+    ...(coverage?.documentation_plan_summary
+      ? { documentation_plan_summary: coverage.documentation_plan_summary }
+      : documentationPlan
+        ? { documentation_plan_summary: summarizeDocumentationPlan(documentationPlan) }
+        : {}),
+    ...(coverage?.reconciliation_summary ? { reconciliation_summary: coverage.reconciliation_summary } : {}),
+    ...(warnings.length > 0 ? { warning_provenance: summarizeWarningProvenance(warnings) } : {}),
+  };
+}
+
+async function readJsonOptional(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function summarizeHostedCoverage(coverage) {
+  return {
+    path: 'state/docs-review-coverage.json',
+    ...(coverage.score_basis ? { score_basis: coverage.score_basis } : {}),
+    ...(typeof coverage.area_count === 'number' ? { area_count: coverage.area_count } : {}),
+    ...(typeof coverage.coverage_score === 'number' || coverage.coverage_score === null
+      ? { coverage_score: coverage.coverage_score }
+      : {}),
+    ...(coverage.statuses ? { statuses: coverage.statuses } : {}),
+    ...(coverage.coverage_levels ? { coverage_levels: coverage.coverage_levels } : {}),
+    ...(typeof coverage.inventory_count === 'number' ? { inventory_count: coverage.inventory_count } : {}),
+    ...(coverage.inventory_statuses ? { inventory_statuses: coverage.inventory_statuses } : {}),
+    ...(coverage.topology ? { topology: coverage.topology } : {}),
+    ...(coverage.taxonomy?.primary_axis ? { taxonomy_primary_axis: coverage.taxonomy.primary_axis } : {}),
+  };
+}
+
+function summarizeWarningProvenance(warnings) {
+  return {
+    warning_count: warnings.length,
+    codes: countBy(warnings, 'code'),
+  };
+}
+
 function parseJsonObject(value) {
   if (!value) return null;
   try {
@@ -2352,6 +2449,7 @@ function renderReviewPrompt(options) {
     '- Prioritize entry points, user-flow/gating relationships, data ownership, external integrations, jobs/async boundaries, auth/security boundaries, and test surfaces.',
     '- Account for each completeness-inventory item in the coverage plan as accepted, deferred, or missing. Do not inflate coverage by omitting large discovered subsystems; honest deferred/missing entries are expected when the first pass cannot cover everything.',
     '- Before generating prose, self-check that every `completeness_inventory[].coverage_area_ids[]` value points to an `areas[].id` in the same accepted plan. Fix all dangling ids together at the plan gate.',
+    '- Before generating prose, self-check that every `areas[].linked_inventory_ids[]` value points to a `completeness_inventory[].id` in the same accepted plan. Fix all dangling ids together at the plan gate.',
     '- Choose one primary taxonomy axis from topology evidence and keep it stable: single-repo/monolith may default domain-first; multi-repo or multi-surface projects may use platform/repo-first or domain-first with per-surface components. Do not mix taxonomy axes at the same tier unless you explicitly propose and justify a restructuring.',
     '- For every prior architecture doc or project-map feature identity in Re-review Anchors, classify the plan action as `reuse`, `update`, `split`, `merge`, `defer`, or `replace`. Use `new` only for areas not represented by the prior tree.',
     '- Every `split`, `merge`, or `replace` action requires an evidence-backed anchor reason before prose generation. No unexplained slug rename is allowed.',

package/src/init.js

@@ -231,7 +231,9 @@ function normalizeInitOptions(options) {
     : cwd;
 
   if (typeof preparedOptions.name !== 'string' || preparedOptions.name.trim() === '') {
-    throw new Error('init requires a non-empty project name.');
+    throw new Error(
+      'init requires a non-empty project name. Run guided setup with `vibecompass init --guided`, or provide `--name <project-name>`.',
+    );
   }
 
   if (typeof preparedOptions.mode !== 'string' || !VALID_MODES.has(preparedOptions.mode)) {

package/src/setup.js

@@ -104,6 +104,7 @@ export async function resolveInitCliOptions(options, environment = {}) {
       ? {
           sessionId: resolved.sessionId,
           workingOn: resolved.sessionWorkingOn,
+          repos: resolved.repos.map((repo) => repo.id),
         }
       : null,
   };
@@ -608,14 +609,15 @@ async function completeGuidedInitOptions(options, environment) {
     }
 
     if (!resolved.sessionWorkingOn) {
-      resolved.sessionWorkingOn = await askInput(prompter, 'What are you working on?');
+      resolved.sessionWorkingOn = await askInput(prompter, 'Work summary for this first session');
     }
 
     if (!resolved.sessionId) {
-      resolved.sessionId = await askInput(prompter, 'Session lane id', {
-        defaultValue: suggestLaneId(resolved.sessionWorkingOn),
+      const defaultSessionId = suggestLaneId(resolved.sessionWorkingOn);
+      resolved.sessionId = await askInput(prompter, 'Session lane id, short kebab-case slug', {
+        defaultValue: defaultSessionId,
         validate(value) {
-          return validateLaneIdForPrompt(value);
+          return validateLaneIdForPrompt(value, defaultSessionId);
         },
       });
     }
@@ -1245,7 +1247,7 @@ function suggestLaneId(value) {
   return slug.length >= 3 ? slug : 'builder-session';
 }
 
-function validateLaneIdForPrompt(value) {
+function validateLaneIdForPrompt(value, defaultValue) {
   if (!/^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/.test(value)) {
     return 'Lane id must be 3-64 lowercase letters, numbers, or hyphens, and must start and end with a letter or number.';
   }
@@ -1268,7 +1270,7 @@ function validateLaneIdForPrompt(value) {
     'wip',
     'yes',
   ].includes(value)) {
-    return `Lane id "${value}" is reserved.`;
+    return `Lane id "${value}" is reserved. Enter a short kebab-case lane id, or press Enter to use "${defaultValue}".`;
   }
 
   return null;