@vibecompass/vibecompass 0.10.4 → 0.10.6

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## Unreleased
+
+## 0.10.6 - 2026-06-22
+
+- Add `docs-update` as a session-delta documentation maintenance planner that maps changed files, lane claims, session repos/features, new decisions, and package-owned generated/state surfaces to targeted architecture/decision/session follow-up.
+- Print the same docs-update plan during `close-session` / `end-session` before the required document-maintenance checkpoint, while keeping semantic document authorship with the closing agent or human.
+- Breaking: `close-session` / `end-session` and the `closeProjectSession` API now require document-maintenance checkpoint statuses for architecture docs, the decision log, and session handoff/scratch maintenance before a lane can be finalized.
+- Surface shared docs-review architecture quality warnings for missing review metadata, evidence, blindspots, retrieval guidance, and repo scope in scanner/status output.
+- Refresh `state/manifest.json.active_sessions` after session start, switch, and close commands so package-managed roots do not keep stale active-lane summaries.
+
+## 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.

package/README.md

@@ -113,6 +113,9 @@ npx -y @vibecompass/vibecompass@latest close-session \
   --session feature-lane \
   --title "Feature Lane" \
   --completed "Shipped the slice" \
+  --architecture-docs updated \
+  --decision-log not-needed \
+  --session-maintenance updated \
   --next-step "Review and publish"
 ```
 
@@ -127,12 +130,14 @@ npx -y @vibecompass/vibecompass@latest status --root .compass
 npx -y @vibecompass/vibecompass@latest start-session --root .compass --id auth-flow --working-on "Auth flow"
 npx -y @vibecompass/vibecompass@latest list-sessions --root .compass
 npx -y @vibecompass/vibecompass@latest switch-session auth-flow --root .compass
-npx -y @vibecompass/vibecompass@latest close-session --root .compass --session auth-flow --title "Auth Flow" --completed "Built auth" --next-step "Review"
+npx -y @vibecompass/vibecompass@latest docs-update --root .compass --session auth-flow
+npx -y @vibecompass/vibecompass@latest close-session --root .compass --session auth-flow --title "Auth Flow" --completed "Built auth" --architecture-docs updated --decision-log not-needed --session-maintenance updated --next-step "Review"
 
 # Agent instruction files
 npx -y @vibecompass/vibecompass@latest sync-agents --root .compass
 
-# Architecture docs review
+# Targeted and comprehensive architecture docs maintenance
+npx -y @vibecompass/vibecompass@latest docs-update --root .compass --session auth-flow --changed app:src/auth/login.ts
 npx -y @vibecompass/vibecompass@latest docs-review --root .compass --guided
 npx -y @vibecompass/vibecompass@latest docs-review --root .compass --guided --source-root app=../app
 npx -y @vibecompass/vibecompass@latest docs-review --root .compass --apply-output

package/package.json

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

package/src/cli.js

@@ -4,6 +4,7 @@ import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { connectHostedProjectMemory, initializeProjectMemory, setDefaultSyncTarget } from './init.js';
 import { preflightDocsReview } from './docs-review.js';
+import { planDocsUpdate, renderDocsUpdatePlan } from './docs-update.js';
 import { resolveConnectHostedCliOptions, resolveInitCliOptions } from './setup.js';
 import { closeProjectSession, listProjectSessions, startProjectSession, switchProjectSession } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
@@ -205,6 +206,20 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'docs-update') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const result = await planDocsUpdate({
+      ...parsed.options,
+      ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
+    });
+    if (parsed.options.json) {
+      io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    } else {
+      io.stdout.write(renderDocsUpdatePlan(result));
+    }
+    return 0;
+  }
+
   if (parsed.command === 'close-session' || parsed.command === 'end-session') {
     await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await closeProjectSession({
@@ -214,12 +229,17 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     io.stdout.write(`Closed session ${result.sessionDate}-${result.sessionNumber}\n`);
     io.stdout.write(`Wrote ${result.sessionFilePath}\n`);
     io.stdout.write(`Updated ${result.claudePath}\n`);
+    if (result.docsUpdatePlan) {
+      io.stdout.write(renderDocsUpdatePlan(result.docsUpdatePlan));
+    }
+    writeDocumentMaintenanceCheckpoint(io, result.documentMaintenance);
     if (result.workflowGuidance.length > 0) {
       io.stdout.write('Workflow guidance:\n');
       for (const item of result.workflowGuidance) {
         io.stdout.write(`- ${item}\n`);
       }
     }
+    writeWarnings(io, result.warnings);
     writeAgentFileSyncResult(io, result.agentFileSync);
     return 0;
   }
@@ -250,6 +270,7 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     });
     io.stdout.write(`Current session lane: ${result.current}\n`);
     io.stdout.write(`Updated ${result.claudePath}\n`);
+    writeWarnings(io, result.warnings);
     writeAgentFileSyncResult(io, result.agentFileSync);
     return 0;
   }
@@ -457,6 +478,10 @@ export function parseCliArgs(argv) {
       return parseRefreshWorkflowArgs(rest);
     }
 
+    if (command === 'docs-update') {
+      return parseDocsUpdateArgs(rest);
+    }
+
     if (command === 'close-session' || command === 'end-session') {
       return parseCloseSessionArgs(rest);
     }
@@ -896,6 +921,7 @@ function parseCloseSessionArgs(argv) {
     models: [],
     blockers: [],
     nextSteps: [],
+    documentMaintenance: {},
   };
   // Repeatable CLI flags stay singular for readability, but map to plural arrays in the JS API.
 
@@ -949,6 +975,15 @@ function parseCloseSessionArgs(argv) {
       case '--next-session-should':
         parsed.nextSessionShould = value;
         break;
+      case '--architecture-docs':
+        parsed.documentMaintenance.architectureDocs = value;
+        break;
+      case '--decision-log':
+        parsed.documentMaintenance.decisionLog = value;
+        break;
+      case '--session-maintenance':
+        parsed.documentMaintenance.sessionMaintenance = value;
+        break;
       default:
         throw new Error(`Unknown flag "${token}".`);
     }
@@ -960,6 +995,49 @@ function parseCloseSessionArgs(argv) {
   };
 }
 
+function parseDocsUpdateArgs(argv) {
+  const parsed = {
+    changedFiles: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--json') {
+      parsed.json = true;
+      continue;
+    }
+
+    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 '--session':
+        parsed.sessionId = value;
+        break;
+      case '--changed':
+        parsed.changedFiles.push(value);
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}".`);
+    }
+  }
+
+  return {
+    command: 'docs-update',
+    options: parsed,
+  };
+}
+
 function parseListSessionsArgs(argv) {
   const parsed = {};
 
@@ -1464,6 +1542,17 @@ function writeRefreshWorkflowResult(io, result) {
   writeAgentFileSyncResult(io, result.agentFileSync);
 }
 
+function writeDocumentMaintenanceCheckpoint(io, documentMaintenance) {
+  if (!documentMaintenance) {
+    return;
+  }
+
+  io.stdout.write('Document maintenance checkpoint:\n');
+  io.stdout.write(`- Architecture docs: ${documentMaintenance.architectureDocs}\n`);
+  io.stdout.write(`- Decision log: ${documentMaintenance.decisionLog}\n`);
+  io.stdout.write(`- Session handoff/scratch: ${documentMaintenance.sessionMaintenance}\n`);
+}
+
 async function writeCompatibilityPreflightWarnings(io, options = {}, runtime = {}) {
   const result = await inspectProjectCompatibility({
     ...options,
@@ -1513,9 +1602,10 @@ function usageText() {
     '  vibecompass sync-target [<name>] [options]',
     '  vibecompass status [options]',
     '  vibecompass refresh-workflow [--dry-run|--apply] [options]',
+    '  vibecompass docs-update [--session <lane-id>] [options]',
     '  vibecompass start-session --id <lane-id> --working-on <text> [options]',
-    '  vibecompass close-session --title <text> --completed <text> --next-step <text> [options]',
-    '  vibecompass end-session --title <text> --completed <text> --next-step <text> [options]  # alias',
+    '  vibecompass close-session --title <text> --completed <text> --architecture-docs <status> --decision-log <status> --session-maintenance <status> [options]',
+    '  vibecompass end-session --title <text> --completed <text> --architecture-docs <status> --decision-log <status> --session-maintenance <status> [options]  # alias',
     '  vibecompass list-sessions [options]',
     '  vibecompass switch-session <id> [options]',
     '  vibecompass sync-agents [options]',
@@ -1578,6 +1668,12 @@ function usageText() {
     '  --update-package-stamp               Update an existing project.yaml package_version stamp',
     '  --allow-downgrade-templates          Allow applying templates with a CLI older than the root stamp',
     '',
+    'Docs-update options:',
+    '  --root <path>                        Project-memory root. Defaults to .compass',
+    '  --session <lane-id>                  Active session lane to inspect; defaults to current lane',
+    '  --changed <repo:path|path>           Repeatable explicit changed path; defaults to git status when omitted',
+    '  --json                               Print the typed docs-update plan as JSON',
+    '',
     'Start-session options:',
     '  --root <path>                        Project-memory root. Defaults to .compass',
     '  --tooling-root <path>                Tooling root that contains CLAUDE.md. Defaults to cwd',
@@ -1602,6 +1698,9 @@ function usageText() {
     '  --model <text>                       Optional repeatable model contribution entry',
     '  --blocker <text>                     Repeatable blocker or open question',
     '  --next-step <text>                   Repeatable next-session step',
+    '  --architecture-docs <status>         Required checkpoint: updated|not-needed|deferred',
+    '  --decision-log <status>              Required checkpoint: updated|not-needed|deferred',
+    '  --session-maintenance <status>       Required checkpoint: updated|not-needed|deferred',
     '  --last-thing-completed <text>        Optional override for the CLAUDE.md completed summary',
     '  --next-session-should <text>         Optional override for the CLAUDE.md next-session summary',
     '',

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.',