@vibecompass/vibecompass 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.10.1 - 2026-06-14
+
+- Add completeness-inventory guidance to docs-review so coverage plans account for accepted, deferred, and missing subsystems instead of silently omitting large areas.
+- Score accepted coverage against the optional completeness inventory denominator when present, with a backwards-compatible fallback for older coverage plans.
+- Add soft parser warnings for modern coverage plans that omit completeness inventory or under-explain accepted/deferred/missing inventory items.
+- Add prose-only surface matrix guidance for feature docs while keeping `systems[]` as derived overview metadata rather than a second projected graph.
+
 ## 0.10.0 - 2026-06-14
 
 - Make docs-review prompts mode-aware: interactive AI sessions stop at the coverage-plan approval gate, while `--run-local` and hosted single-turn runs emit fenced proposal material for later apply/proposal review.

package/package.json

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

package/src/docs-review.js

@@ -9,7 +9,7 @@ import { parseSimpleYaml } from './simple-yaml.js';
 import { readSyncCursor, resolveSyncBinding } from './sync-binding.js';
 import { PACKAGE_VERSION } from './version.js';
 
-const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v5';
+const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v6';
 const ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES = 12000;
 const COVERAGE_PLAN_OUTPUT_VERSION = 1;
 const COVERAGE_PLAN_STATUSES = new Set(['accepted', 'deferred', 'missing']);
@@ -921,10 +921,12 @@ function buildCoverageProjection(blocks, options) {
 
   const ids = new Set();
   const areas = plan.areas.map((area, index) => normalizeCoverageArea(area, index, ids));
+  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);
   const statuses = countBy(areas, 'status');
   const coverage_levels = countBy(areas, 'coverage');
-  const denominator = areas.length;
-  const acceptedCount = statuses.accepted ?? 0;
+  const inventory_statuses = countBy(completenessInventory, 'status');
 
   return {
     version: COVERAGE_PLAN_OUTPUT_VERSION,
@@ -937,13 +939,30 @@ function buildCoverageProjection(blocks, options) {
     ...(normalizeOptionalString(plan.topology) ? { topology: normalizeOptionalString(plan.topology) } : {}),
     ...(normalizeCoverageTaxonomy(plan.taxonomy) ? { taxonomy: normalizeCoverageTaxonomy(plan.taxonomy) } : {}),
     area_count: areas.length,
-    coverage_score: denominator === 0 ? null : Number((acceptedCount / denominator).toFixed(4)),
+    ...(hasCompletenessInventory ? {
+      completeness_inventory: completenessInventory,
+      inventory_count: completenessInventory.length,
+      inventory_statuses,
+    } : {}),
+    coverage_score: calculateCoverageScore({ areas, statuses, completenessInventory, hasCompletenessInventory }),
     statuses,
     coverage_levels,
     areas,
   };
 }
 
+function calculateCoverageScore({ areas, statuses, completenessInventory, hasCompletenessInventory }) {
+  if (hasCompletenessInventory) {
+    const denominator = completenessInventory.length;
+    const acceptedCount = completenessInventory.filter((item) => item.status === 'accepted').length;
+    return denominator === 0 ? null : Number((acceptedCount / denominator).toFixed(4));
+  }
+
+  const denominator = areas.length;
+  const acceptedCount = statuses.accepted ?? 0;
+  return denominator === 0 ? null : Number((acceptedCount / denominator).toFixed(4));
+}
+
 function normalizeCoverageTaxonomy(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     return null;
@@ -961,6 +980,55 @@ function normalizeCoverageTaxonomy(value) {
   };
 }
 
+function normalizeCompletenessInventory(value, areaById) {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error('Coverage plan completeness_inventory must be an array when present.');
+  }
+
+  const ids = new Set();
+  return value.map((item, index) => normalizeCompletenessInventoryItem(item, index, ids, areaById));
+}
+
+function normalizeCompletenessInventoryItem(item, index, ids, areaById) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) {
+    throw new Error(`Coverage plan completeness_inventory item at index ${index} must be an object.`);
+  }
+
+  const id = normalizeOptionalString(item.id);
+  if (!id) {
+    throw new Error(`Coverage plan completeness_inventory item at index ${index} requires non-empty "id".`);
+  }
+  if (ids.has(id)) {
+    throw new Error(`Coverage plan completeness_inventory contains duplicate item id: ${id}`);
+  }
+  ids.add(id);
+
+  const status = normalizeOptionalString(item.status);
+  if (!COVERAGE_PLAN_STATUSES.has(status)) {
+    throw new Error(`Coverage plan completeness_inventory item "${id}" requires status to be accepted, deferred, or missing.`);
+  }
+
+  const coverageAreaIds = normalizeStringArray(item.coverage_area_ids);
+  for (const areaId of coverageAreaIds) {
+    if (!areaById.has(areaId)) {
+      throw new Error(`Coverage plan completeness_inventory item "${id}" references unknown coverage area id: ${areaId}`);
+    }
+  }
+
+  return {
+    id,
+    ...(normalizeOptionalString(item.kind) ? { kind: normalizeOptionalString(item.kind) } : {}),
+    ...(normalizeOptionalString(item.label) ? { label: normalizeOptionalString(item.label) } : {}),
+    status,
+    ...(coverageAreaIds.length > 0 ? { coverage_area_ids: coverageAreaIds } : {}),
+    evidence: normalizeStringArray(item.evidence),
+    blindspots: normalizeStringArray(item.blindspots),
+  };
+}
+
 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.`);
@@ -1134,15 +1202,30 @@ function createCoveragePlanQualityWarnings(coverageProjection, anchors) {
     return [];
   }
 
+  const warnings = [];
+  const hasModernCoverageMetadata = Boolean(coverageProjection.topology || coverageProjection.taxonomy);
+  const hasCompletenessInventory = Array.isArray(coverageProjection.completeness_inventory);
+  if (hasModernCoverageMetadata && !hasCompletenessInventory) {
+    warnings.push('missing_completeness_inventory: coverage plan should enumerate discovered subsystems so deferred or missing areas cannot be silently omitted.');
+  } else if (hasCompletenessInventory) {
+    for (const item of coverageProjection.completeness_inventory) {
+      if (item.status === 'accepted' && (!Array.isArray(item.coverage_area_ids) || item.coverage_area_ids.length === 0)) {
+        warnings.push(`accepted_inventory_without_area: completeness_inventory item "${item.id}" is accepted but does not reference coverage_area_ids.`);
+      }
+      if (item.status !== 'accepted' && (!Array.isArray(item.blindspots) || item.blindspots.length === 0)) {
+        warnings.push(`incomplete_inventory_blindspot: completeness_inventory item "${item.id}" is ${item.status} but does not explain the gap in blindspots.`);
+      }
+    }
+  }
+
   const hasPriorAnchors =
     (anchors?.architectureDocs?.length ?? 0) > 0 ||
     (anchors?.projectMapFeatures?.length ?? 0) > 0 ||
     Boolean(anchors?.coverage);
   if (!hasPriorAnchors) {
-    return [];
+    return warnings;
   }
 
-  const warnings = [];
   for (const area of coverageProjection.areas) {
     if (!area.anchor_action) {
       warnings.push(`missing_anchor_action: coverage area "${area.id}" should classify prior docs or project-map identities when re-review anchors exist.`);
@@ -2025,14 +2108,17 @@ 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.',
     '- Identify the project topology before choosing docs: single-repo/monolith, multi-repo, multi-surface, package/CLI, workers/services, mobile app, or mixed. State the topology in the coverage plan.',
+    '- Build a completeness inventory of discovered apps/repos, routes/screens, API endpoints, tables/storage, jobs/cron/tasks, auth/session flows, external integrations, platform surfaces, and product features. Keep it subsystem-level, not a raw file dump.',
     '- 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, ownership boundaries, user journey entry points, feature-to-feature relationships, and system-layer connections with concrete `repo:path` evidence.',
+    '- Separate product features from runtime surfaces. Web, mobile, backend/API, database/storage, jobs, external integrations, and deployment/runtime are surfaces or systems that participate in features; do not treat them as competing feature categories unless the project itself is a platform/tooling project.',
     '- 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.',
     '- 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.',
+    '- 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.',
     '- 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.',
@@ -2058,6 +2144,8 @@ function renderReviewPrompt(options) {
     '- frontmatter fields: `domain`, `feature`, `component`, `status`, plus `repo` or `repos` when implementation-scoped',
     '- body sections: `## Description`, `## Review metadata`, `## Details`, `## Retrieval guidance`, `## Next steps`, `## Involved files`',
     '- overview docs may add compact peer sections for Stage 1 backbone outputs when useful: `## Topology`, `## Core feature inventory`, `## User journey map`, `## Project systems map`, and `## Coverage and quality summary`',
+    '- feature docs may add a compact `## Surface matrix` prose table when multiple surfaces participate. Keep it evidence-sized: include participating surfaces with concrete `repo:path` evidence and explicit N/A rows only when an absence is important to retrieval. Do not emit a new machine-readable surface block.',
+    '- surface/platform ownership docs should stay inside the existing contract, typically as `architecture/platform/<surface>/<component>.md`; do not introduce a top-level `systems/` tree.',
     '',
     'Use this exact Review metadata sub-header in every generated architecture doc:',
     '',
@@ -2121,6 +2209,7 @@ function renderReviewPrompt(options) {
     '',
     '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.',
     '`systems[]` is optional derived overview metadata, not a new canonical taxonomy, relationship schema, or projection source. Include it only when evidence identifies runtime/deployable units or external systems; treat `owns_features` as documentation-only grouping, put user-journey links in `relationships[]`, and record uncertain systems or system-to-system connections as blindspots.',
+    'Per-feature surface matrices are derived prose. `systems[].owns_features` remains the only machine-readable system-to-feature hint in this release; do not duplicate that graph in another parsed block.',
     '',
     '## Output Contract',
     'First provide a concise findings summary with:',
@@ -2129,6 +2218,7 @@ function renderReviewPrompt(options) {
     '- user journey and project/system map coverage',
     '- gaps/blindspots',
     '- evidence inventory summary',
+    '- completeness inventory summary with accepted/deferred/missing accounting',
     '- topology and chosen taxonomy axis',
     '- coverage plan and proposed architecture docs',
     '- prior-doc anchor classifications and reasons',
@@ -2146,6 +2236,17 @@ function renderReviewPrompt(options) {
     '    "primary_axis": "domain-first | platform-first | repo-first | other",',
     '    "rationale": "Why this axis matches the evidence and how it avoids mixed tiers"',
     '  },',
+    '  "completeness_inventory": [',
+    '    {',
+    '      "id": "stable-subsystem-id",',
+    '      "kind": "feature | surface | route | screen | api | data | storage | job | integration | auth | deployment | other",',
+    '      "label": "Short discovered subsystem label",',
+    '      "status": "accepted | deferred | missing",',
+    '      "coverage_area_ids": ["stable-area-id"],',
+    '      "evidence": ["repo:path"],',
+    '      "blindspots": ["explicit blindspot for deferred or missing items"]',
+    '    }',
+    '  ],',
     '  "areas": [',
     '    {',
     '      "id": "stable-area-id",',

package/src/workflows/registry.js

@@ -111,11 +111,13 @@ Turn starter project memory into evidence-backed architecture docs under \`archi
 2. Inspect the declared source repos in stages:
    - inventory paths, manifests, configs, route/job/test directories, and existing architecture frontmatter first
    - identify project topology before choosing taxonomy: single-repo/monolith, multi-repo, multi-surface, package/CLI, workers/services, mobile app, or mixed
+   - build a subsystem-level completeness inventory of apps/repos, routes/screens, APIs, tables/storage, jobs/cron/tasks, auth/session flows, external integrations, runtime surfaces, and product features
+   - distinguish product features from participating surfaces such as web, mobile, backend/API, data, jobs, integrations, and deployment/runtime
    - 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, topology, chosen taxonomy axis, prior-doc reuse/update/split/merge/defer/replace classifications, coverage plan, backbone outputs (core feature inventory, user journey map, project systems map, coverage/quality summary), proposed architecture docs, blindspots, token-budget risks, quality report, and any decision candidates before generating accepted output. If you stop here for user approval, state clearly that no architecture docs have been applied yet and do not label proposed areas as accepted.
-5. Draft only output the user accepts. After approval, 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 compact backbone sections and exactly one \`vibecompass-project-map version=1\` JSON block with journey-facing features, entry points, evidence-backed relationships, and minimal optional derived \`systems[]\` metadata. Accepted local decisions may be fenced as \`vibecompass-decision-recommendation target=decisions/domain.md\` blocks without D-numbers.
+4. Present the evidence inventory, completeness inventory with accepted/deferred/missing accounting, topology, chosen taxonomy axis, prior-doc reuse/update/split/merge/defer/replace classifications, coverage plan, backbone outputs (core feature inventory, user journey map, project systems map, coverage/quality summary), proposed architecture docs, blindspots, token-budget risks, quality report, and any decision candidates before generating accepted output. If you stop here for user approval, state clearly that no architecture docs have been applied yet and do not label proposed areas as accepted.
+5. Draft only output the user accepts. After approval, 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\`. Feature docs may include compact prose-only surface matrices; surface/platform ownership docs stay under the existing \`architecture/platform/<surface>/<component>.md\` shape rather than a new top-level systems tree. The accepted \`architecture/overview/project-shape.md\` doc should include compact backbone sections and exactly one \`vibecompass-project-map version=1\` JSON block with journey-facing features, entry points, evidence-backed relationships, and minimal optional derived \`systems[]\` metadata. 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 verbatim to \`${outputPath}\`.
 8. Run \`${applyCommand}\` to validate and apply the accepted blocks. If \`vibecompass\` is not installed on PATH, run \`${npxApplyCommand}\` instead. Only report docs-review as applied after this command succeeds. If accepted docs were written manually outside the output file, run \`vibecompass docs-review --root ${rootRelativePath} --complete\` after confirming the marker should be completed.