@vibecompass/vibecompass 0.10.5 → 0.10.7

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## Unreleased
+
+## 0.10.7 - 2026-06-25
+
+- Let `connect-hosted` attach hosted sync to existing `local-only` project-memory roots by promoting them to `local-primary`, so local-only users can run the hosted setup command copied from the app without first editing `project.yaml`.
+- Print the mode promotion in CLI output and preserve existing `local-primary` / `hosted-only` behavior.
+- Cover hosted-only passthrough, local-only promotion, and named-target promotion with CLI regression tests.
+
+## 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.

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.5",
+  "version": "0.10.7",
   "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';
@@ -146,6 +147,9 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
       ...(runtime.cwd ? { cwd: runtime.cwd } : {}),
     });
     io.stdout.write(`Connected hosted VibeCompass for ${result.mode}\n`);
+    if (result.modeChanged) {
+      io.stdout.write(`Project mode: ${result.previousMode} -> ${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`);
@@ -205,6 +209,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 +232,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 +273,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 +481,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 +924,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 +978,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 +998,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 +1545,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 +1605,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 +1671,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 +1701,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',
     '',