@vibecompass/vibecompass 0.10.5 → 0.10.6

package/CHANGELOG.md

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

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.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-update.js

@@ -0,0 +1,538 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { parseFrontmatter } from './frontmatter.js';
+import { scanProjectMemory } from './project-memory.js';
+import { parseSimpleYaml } from './simple-yaml.js';
+
+const execFileAsync = promisify(execFile);
+const PACKAGE_OWNED_PATH_PATTERNS = [
+  /^state\//,
+  /^context\.md$/,
+  /^workflows\//,
+  /^CLAUDE\.md$/,
+  /^AGENTS\.md$/,
+  /^\.cursorrules$/,
+  /^\.github\/copilot-instructions\.md$/,
+];
+
+export async function planDocsUpdate(options = {}) {
+  const normalized = normalizeDocsUpdateOptions(options);
+  const scan = await scanProjectMemory(normalized.rootDir);
+  const project = scan.project?.extracted ?? {};
+  const activeSession = await readActiveSession(normalized.rootDir, normalized.sessionId);
+  const changedFiles = await resolveChangedFiles({
+    cwd: normalized.cwd,
+    explicitChangedFiles: normalized.changedFiles,
+    repos: project.repos ?? [],
+  });
+  const architectureDocs = scan.documents
+    .filter((document) => document.kind === 'architecture')
+    .map((document) => summarizeArchitectureDocument(document));
+  const delta = {
+    changedFiles,
+    claimedPaths: activeSession?.claimedPaths ?? [],
+    sessionRepos: activeSession?.repos ?? [],
+    featureSlugs: activeSession?.featureSlugs ?? [],
+  };
+  const affectedArchitectureDocs = findAffectedArchitectureDocs(architectureDocs, delta);
+  const packageOwnedChanges = changedFiles
+    .filter((file) => isPackageOwnedPath(file.normalizedPath))
+    .map((file) => file.raw);
+  const decisionStatus = summarizeDecisionStatus(scan, activeSession);
+  const recommendations = buildRecommendations({
+    changedFiles,
+    affectedArchitectureDocs,
+    packageOwnedChanges,
+    decisionStatus,
+    activeSession,
+  });
+
+  return {
+    rootDir: normalized.rootDir,
+    cwd: normalized.cwd,
+    session: activeSession
+      ? {
+          id: activeSession.id,
+          workingOn: activeSession.workingOn,
+          decisionSnapshotHighestId: activeSession.decisionSnapshotHighestId,
+        }
+      : null,
+    delta: {
+      changedFiles: changedFiles.map((file) => file.raw),
+      claimedPaths: delta.claimedPaths,
+      sessionRepos: delta.sessionRepos,
+      featureSlugs: delta.featureSlugs,
+    },
+    architecture: {
+      affected: affectedArchitectureDocs,
+      needsNewDoc: changedFiles.some((file) => isImplementationLikePath(file.normalizedPath)) && affectedArchitectureDocs.length === 0,
+    },
+    decisions: decisionStatus,
+    packageOwnedChanges,
+    recommendations,
+  };
+}
+
+export function renderDocsUpdatePlan(plan) {
+  const lines = [
+    'Docs update plan:',
+    `- Session: ${plan.session?.id ?? '(none selected)'}`,
+    `- Changed files: ${plan.delta.changedFiles.length > 0 ? plan.delta.changedFiles.join(', ') : 'none detected'}`,
+    `- Claimed paths: ${plan.delta.claimedPaths.length > 0 ? plan.delta.claimedPaths.join(', ') : 'none recorded'}`,
+  ];
+
+  lines.push('Affected architecture docs:');
+  if (plan.architecture.affected.length === 0) {
+    lines.push(plan.architecture.needsNewDoc
+      ? '- No matching architecture doc found for implementation-like changes; create a focused component doc or defer explicitly.'
+      : '- None detected from the current session delta.');
+  } else {
+    for (const doc of plan.architecture.affected) {
+      lines.push(`- ${doc.path}`);
+      for (const reason of doc.reasons) {
+        lines.push(`  - ${reason}`);
+      }
+      if (doc.qualityWarnings.length > 0) {
+        lines.push(`  - quality warnings: ${doc.qualityWarnings.map((warning) => warning.code).join(', ')}`);
+      }
+    }
+  }
+
+  lines.push('Decision log:');
+  if (plan.decisions.newDecisionIds.length > 0) {
+    lines.push(`- New decisions since lane start: ${plan.decisions.newDecisionIds.map((id) => `D-${id}`).join(', ')}`);
+  } else if (plan.decisions.decisionSnapshotHighestId === null) {
+    lines.push('- No lane decision snapshot available.');
+  } else {
+    lines.push('- No new decisions detected since lane start.');
+  }
+
+  if (plan.packageOwnedChanges.length > 0) {
+    lines.push('Package-owned generated/state surfaces:');
+    for (const filePath of plan.packageOwnedChanges) {
+      lines.push(`- ${filePath}`);
+    }
+  }
+
+  lines.push('Recommended next actions:');
+  for (const recommendation of plan.recommendations) {
+    lines.push(`- ${recommendation}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function normalizeDocsUpdateOptions(options) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  return {
+    cwd,
+    rootDir: path.resolve(cwd, options.rootDir ?? '.compass'),
+    sessionId: normalizeOptionalString(options.sessionId),
+    changedFiles: Array.isArray(options.changedFiles) ? options.changedFiles : [],
+  };
+}
+
+async function readActiveSession(rootDir, requestedSessionId) {
+  const activeRoot = path.join(rootDir, 'sessions', 'active');
+  const indexPath = path.join(activeRoot, 'index.yaml');
+  let sessionId = normalizeOptionalString(requestedSessionId);
+
+  if (!sessionId) {
+    try {
+      const indexData = parseSimpleYaml(await readFile(indexPath, 'utf8'), { sourceName: indexPath });
+      sessionId = normalizeOptionalString(indexData.current);
+    } catch {
+      sessionId = null;
+    }
+  }
+
+  if (!sessionId) {
+    return null;
+  }
+
+  const sessionPath = path.join(activeRoot, sessionId, 'session.yaml');
+  try {
+    const data = parseSimpleYaml(await readFile(sessionPath, 'utf8'), { sourceName: sessionPath });
+    return {
+      id: sessionId,
+      workingOn: normalizeOptionalString(data.working_on),
+      repos: normalizeStringArray(data.repos),
+      claimedPaths: normalizeStringArray(data.claimed_paths),
+      featureSlugs: normalizeStringArray(data.feature_slugs),
+      decisionSnapshotHighestId: Number.isInteger(data.decision_snapshot?.highest_decision_id)
+        ? data.decision_snapshot.highest_decision_id
+        : null,
+    };
+  } catch {
+    return {
+      id: sessionId,
+      workingOn: null,
+      repos: [],
+      claimedPaths: [],
+      featureSlugs: [],
+      decisionSnapshotHighestId: null,
+    };
+  }
+}
+
+async function resolveChangedFiles(options) {
+  if (options.explicitChangedFiles.length > 0) {
+    return normalizeChangedFiles(options.explicitChangedFiles, options.repos);
+  }
+
+  const changedPaths = new Set();
+  for (const filePath of await readGitStatusPaths(options.cwd)) {
+    changedPaths.add(filePath);
+  }
+
+  const repoStatusResults = await Promise.all(
+    options.repos.map(async (repo) => {
+      const repoDir = resolveRepoWorkingDirectory(options.cwd, repo);
+      if (!repo?.id || !repoDir || repoDir === options.cwd) {
+        return [];
+      }
+
+      return (await readGitStatusPaths(repoDir)).map((filePath) => `${repo.id}:${filePath}`);
+    }),
+  );
+
+  for (const filePath of repoStatusResults.flat()) {
+    changedPaths.add(filePath);
+  }
+
+  return normalizeChangedFiles(Array.from(changedPaths).sort((left, right) => left.localeCompare(right)), options.repos);
+}
+
+async function readGitStatusPaths(cwd) {
+  try {
+    const { stdout } = await execFileAsync('git', ['-C', cwd, 'status', '--porcelain=v1', '--untracked-files=all'], {
+      timeout: 5000,
+      maxBuffer: 1024 * 1024,
+    });
+    return parseGitStatusPaths(stdout);
+  } catch {
+    return [];
+  }
+}
+
+function resolveRepoWorkingDirectory(cwd, repo) {
+  if (!repo?.id) {
+    return null;
+  }
+
+  if (repo.path) {
+    return path.resolve(cwd, repo.path);
+  }
+
+  return path.resolve(cwd, repo.id);
+}
+
+function parseGitStatusPaths(stdout) {
+  return stdout
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter(Boolean)
+    .map((line) => {
+      const rawPath = line.slice(3).trim();
+      const renameIndex = findUnquotedRenameSeparator(rawPath);
+      const pathPart = renameIndex >= 0 ? rawPath.slice(renameIndex + 4).trim() : rawPath;
+      return unquoteGitPorcelainPath(pathPart);
+    });
+}
+
+function findUnquotedRenameSeparator(value) {
+  let inQuotes = false;
+  let escaped = false;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+
+    if (inQuotes && char === '\\') {
+      escaped = true;
+      continue;
+    }
+
+    if (char === '"') {
+      inQuotes = !inQuotes;
+      continue;
+    }
+
+    if (!inQuotes && value.startsWith(' -> ', index)) {
+      return index;
+    }
+  }
+
+  return -1;
+}
+
+function unquoteGitPorcelainPath(value) {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('"') || !trimmed.endsWith('"')) {
+    return trimmed;
+  }
+
+  let decoded = '';
+  let octalBytes = [];
+  const flushOctalBytes = () => {
+    if (octalBytes.length === 0) {
+      return;
+    }
+
+    decoded += Buffer.from(octalBytes).toString('utf8');
+    octalBytes = [];
+  };
+
+  for (let index = 1; index < trimmed.length - 1; index += 1) {
+    const char = trimmed[index];
+    if (char !== '\\') {
+      flushOctalBytes();
+      decoded += char;
+      continue;
+    }
+
+    const next = trimmed[index + 1];
+    if (next === undefined) {
+      flushOctalBytes();
+      decoded += '\\';
+      continue;
+    }
+
+    const octalMatch = trimmed.slice(index + 1).match(/^[0-7]{1,3}/);
+    if (octalMatch) {
+      octalBytes.push(Number.parseInt(octalMatch[0], 8));
+      index += octalMatch[0].length;
+      continue;
+    }
+
+    flushOctalBytes();
+    const escapes = {
+      a: '\u0007',
+      b: '\b',
+      f: '\f',
+      n: '\n',
+      r: '\r',
+      t: '\t',
+      v: '\v',
+      '\\': '\\',
+      '"': '"',
+    };
+    decoded += escapes[next] ?? next;
+    index += 1;
+  }
+
+  flushOctalBytes();
+  return decoded;
+}
+
+function normalizeChangedFiles(paths, repos) {
+  return paths
+    .map((raw) => normalizeOptionalString(raw))
+    .filter(Boolean)
+    .map((raw) => {
+      const normalizedPath = normalizePath(raw);
+      return {
+        raw,
+        normalizedPath,
+        repoPathCandidates: buildRepoPathCandidates(normalizedPath, repos),
+      };
+    });
+}
+
+function buildRepoPathCandidates(filePath, repos) {
+  const candidates = new Set([filePath]);
+  const explicitRepoMatch = filePath.match(/^([^:/]+):(.+)$/);
+  if (explicitRepoMatch) {
+    const repoRelativePath = normalizePath(explicitRepoMatch[2]);
+    candidates.add(`${explicitRepoMatch[1]}:${repoRelativePath}`);
+    candidates.add(repoRelativePath);
+  }
+
+  if (!explicitRepoMatch && repos.length === 1 && repos[0]?.id) {
+    candidates.add(`${repos[0].id}:${filePath}`);
+  }
+
+  for (const repo of repos) {
+    if (!repo?.id) {
+      continue;
+    }
+    if (filePath.startsWith(`${repo.id}/`)) {
+      candidates.add(`${repo.id}:${filePath.slice(repo.id.length + 1)}`);
+    }
+    if (repo.path) {
+      const repoPath = normalizePath(repo.path).replace(/^\.\//, '');
+      if (repoPath && filePath.startsWith(`${repoPath}/`)) {
+        candidates.add(`${repo.id}:${filePath.slice(repoPath.length + 1)}`);
+      }
+    }
+  }
+
+  return Array.from(candidates);
+}
+
+function summarizeArchitectureDocument(document) {
+  const frontmatter = parseFrontmatter(document.content, { sourceName: document.path });
+  const data = frontmatter.data ?? {};
+  return {
+    path: document.path,
+    repoIds: [
+      ...(typeof data.repo === 'string' ? [data.repo] : []),
+      ...(Array.isArray(data.repos) ? data.repos.filter((repo) => typeof repo === 'string') : []),
+    ],
+    domain: normalizeOptionalString(data.domain),
+    feature: normalizeOptionalString(data.feature),
+    component: normalizeOptionalString(data.component),
+    involvedFiles: extractInvolvedFiles(frontmatter.body),
+    warnings: document.warnings,
+  };
+}
+
+function extractInvolvedFiles(body) {
+  return Array.from(body.matchAll(/`([^`\n]+:[^`\n]+)`/g))
+    .map((match) => normalizePath(match[1]))
+    .filter(Boolean);
+}
+
+function findAffectedArchitectureDocs(docs, delta) {
+  return docs
+    .map((doc) => {
+      const reasons = [];
+
+      for (const changedFile of delta.changedFiles) {
+        if (pathMatchesDocument(changedFile, doc)) {
+          reasons.push(`matches changed file ${changedFile.raw}`);
+        }
+      }
+
+      for (const claimedPath of delta.claimedPaths) {
+        const normalizedClaim = normalizePath(claimedPath);
+        if (doc.involvedFiles.some((involvedFile) => pathsOverlap(involvedFile, normalizedClaim))) {
+          reasons.push(`matches lane claim ${claimedPath}`);
+        }
+      }
+
+      if (delta.featureSlugs.some((feature) => slugify(doc.feature ?? '') === feature)) {
+        reasons.push(`matches lane feature ${delta.featureSlugs.filter((feature) => slugify(doc.feature ?? '') === feature).join(', ')}`);
+      }
+
+      return {
+        path: doc.path,
+        reasons: Array.from(new Set(reasons)),
+        qualityWarnings: doc.warnings,
+      };
+    })
+    .filter((doc) => doc.reasons.length > 0)
+    .sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function pathMatchesDocument(changedFile, doc) {
+  if (changedFile.normalizedPath === doc.path) {
+    return true;
+  }
+
+  return changedFile.repoPathCandidates.some((candidate) =>
+    doc.involvedFiles.some((involvedFile) => pathsOverlap(involvedFile, candidate)),
+  );
+}
+
+function pathsOverlap(left, right) {
+  const normalizedLeft = normalizePath(left);
+  const normalizedRight = normalizePath(right);
+  return (
+    normalizedLeft === normalizedRight ||
+    normalizedLeft.startsWith(`${normalizedRight}/`) ||
+    normalizedRight.startsWith(`${normalizedLeft}/`) ||
+    normalizedLeft.endsWith(`/${normalizedRight}`) ||
+    normalizedRight.endsWith(`/${normalizedLeft}`)
+  );
+}
+
+function summarizeDecisionStatus(scan, activeSession) {
+  const decisionIds = scan.documents
+    .filter((document) => document.kind === 'decision')
+    .flatMap((document) => document.extracted?.decision_ids ?? [])
+    .sort((left, right) => left - right);
+  const highestDecisionId = decisionIds.length > 0 ? decisionIds[decisionIds.length - 1] : null;
+  const snapshot = activeSession?.decisionSnapshotHighestId ?? null;
+
+  return {
+    highestDecisionId,
+    decisionSnapshotHighestId: snapshot,
+    newDecisionIds: snapshot === null ? [] : decisionIds.filter((id) => id > snapshot),
+  };
+}
+
+function buildRecommendations(options) {
+  const recommendations = [];
+
+  if (options.affectedArchitectureDocs.length > 0) {
+    recommendations.push('Review and update the affected architecture docs listed above, then close with --architecture-docs updated.');
+  } else if (options.changedFiles.length > 0 && options.affectedArchitectureDocs.length === 0) {
+    recommendations.push('No matching architecture doc was found for the session delta; create a focused doc, mark docs not-needed with evidence, or defer explicitly.');
+  } else {
+    recommendations.push('No architecture doc update is indicated by the current delta; close with --architecture-docs not-needed if that remains true.');
+  }
+
+  if (options.decisionStatus.newDecisionIds.length > 0) {
+    recommendations.push('Ensure affected architecture docs reference the new decisions where they change contracts or ownership.');
+  } else {
+    recommendations.push('Append a decision only if this session accepted a real architectural/product/process choice.');
+  }
+
+  if (options.packageOwnedChanges.length > 0) {
+    recommendations.push('Do not hand-edit package-owned state/generated surfaces; use refresh-workflow --dry-run/--apply or sync-agents as appropriate.');
+  }
+
+  if (options.activeSession) {
+    recommendations.push('Keep the active lane wip.md/handoff.md current; close-session will distill them into the finalized note.');
+  }
+
+  return recommendations;
+}
+
+function isPackageOwnedPath(filePath) {
+  const normalized = normalizePath(filePath).replace(/^\.compass\//, '');
+  return PACKAGE_OWNED_PATH_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
+function isImplementationLikePath(filePath) {
+  const normalized = stripRepoPrefix(filePath);
+  return !(
+    normalized.startsWith('architecture/') ||
+    normalized.startsWith('decisions/') ||
+    normalized.startsWith('sessions/') ||
+    isPackageOwnedPath(normalized)
+  );
+}
+
+function stripRepoPrefix(filePath) {
+  const normalized = normalizePath(filePath);
+  const repoMatch = normalized.match(/^[^:/]+:(.+)$/);
+  return repoMatch ? normalizePath(repoMatch[1]) : normalized;
+}
+
+function normalizeStringArray(value) {
+  return Array.isArray(value)
+    ? value.map((item) => normalizeOptionalString(item)).filter(Boolean)
+    : [];
+}
+
+function normalizeOptionalString(value) {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+}
+
+function normalizePath(value) {
+  return String(value).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function slugify(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}

package/src/index.js

@@ -5,6 +5,7 @@ export { refreshWorkflow } from './refresh-workflow.js';
 export { getProjectStatus, renderStatusText, toStatusJson } from './status.js';
 export { initializeProjectMemory } from './init.js';
 export { preflightDocsReview } from './docs-review.js';
+export { planDocsUpdate, renderDocsUpdatePlan } from './docs-update.js';
 export {
   applyPullExport,
   pullExportProjectMemory,

package/src/project-memory.js

@@ -11,7 +11,9 @@ const NON_CANONICAL_ARCHITECTURE_FILES = new Set(['README.md']);
 const VALID_MODES = new Set(['local-only', 'local-primary', 'hosted-only']);
 const RECOMMENDED_ARCHITECTURE_SECTIONS = [
   'Description',
+  'Review metadata',
   'Details',
+  'Retrieval guidance',
   'Next steps',
   'Involved files',
 ];
@@ -446,6 +448,31 @@ function parseArchitectureDocument(options) {
       }
     }
 
+    if (!/^\s*-\s*Evidence:\s+\S/im.test(frontmatter.body)) {
+      warnings.push(
+        createWarning(
+          'architecture-missing-evidence-metadata',
+          'Architecture doc is missing review metadata "Evidence" with concrete repo:path references.',
+        ),
+      );
+    } else if (/^\s*-\s*Evidence:\s*repo:path references inspected before making implementation claims\s*$/im.test(frontmatter.body)) {
+      warnings.push(
+        createWarning(
+          'architecture-generic-evidence-metadata',
+          'Architecture doc uses generic evidence metadata; list concrete repo:path references instead.',
+        ),
+      );
+    }
+
+    if (!/^\s*-\s*Blindspots:\s+\S/im.test(frontmatter.body)) {
+      warnings.push(
+        createWarning(
+          'architecture-missing-blindspots-metadata',
+          'Architecture doc is missing review metadata "Blindspots".',
+        ),
+      );
+    }
+
     if (repoIds.length === 0 && /##\s+Involved files/i.test(frontmatter.body) && /`[^`]+\/[^`]+`/.test(frontmatter.body)) {
       warnings.push(
         createWarning(

package/src/scaffold.js

@@ -216,7 +216,7 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 ## Canonical files
 - \`${rootRelativePath}/project.yaml\` — machine-oriented project metadata
 - \`${rootRelativePath}/architecture/\` — canonical architecture docs
-- \`${rootRelativePath}/decisions/\` — canonical decision log
+- \`${rootRelativePath}/decisions/\` — append-only decision log for this project-memory root
 - \`${rootRelativePath}/sessions/\` — finalized session notes
 
 ## Derived and scratch files
@@ -233,7 +233,7 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 - The active lane scratch files live under \`${rootRelativePath}/sessions/active/<lane-id>/\`.
 - \`${rootRelativePath}/sessions/active/index.yaml\` is the authoritative current lane pointer; the tool-specific Current session block is a human-readable continuity summary, not the lane-selection source of truth.
 - Finalized sessions are append-only notes named \`${rootRelativePath}/sessions/YYYY-MM-DD-N-title.md\`; multiple sessions on the same day increment \`N\`.
-- Decisions remain append-only and independent from session notes. A session note may reference decisions, but the decision entry in \`${rootRelativePath}/decisions/\` is the durable source of truth.
+- Decisions remain append-only and independent from session notes. A session note may reference decisions, but the decision entry in \`${rootRelativePath}/decisions/\` is the durable decision record for this root.
 
 ## Repos in scope
 ${repos}
@@ -248,7 +248,7 @@ ${repos}
 ${promptCommands}
 
 These are prompt commands for agent behavior, not \`vibecompass\` CLI subcommands.
-Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. The \`close session\` prompt runs builder close-out and ends with \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${rootRelativePath}/project.yaml\`.
+Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. The \`close session\` prompt runs builder close-out and ends with \`vibecompass close-session --session <lane-id>\` plus document-maintenance checkpoint statuses, which follows the workflow defaults recorded in \`${rootRelativePath}/project.yaml\`.
 \`vibecompass end-session\` is also accepted as an alias for \`vibecompass close-session\`; the canonical command name remains \`close-session\`.
 
 ## Workflow defaults
@@ -257,6 +257,7 @@ ${renderWorkflowDefaults(workflow)}
 ## Documentation coverage
 - The architecture, decision, and session files created by init are an initial scaffold, not a comprehensive codebase review.
 - Before risky implementation work, inspect the relevant code and update the affected architecture docs.
+- Use \`vibecompass docs-update --session <lane-id>\` during a session for a targeted maintenance plan based on changed files, lane claims, session repos/features, and new decisions. This is a session-delta planner, not a broad architecture review.
 - Use the \`docs review\` prompt command when you want the current AI session to run a comprehensive documentation review. It may run \`vibecompass docs-review --guided\` as package mechanics to record marker state and print the canonical review contract.
 
 ## Session startup
@@ -310,10 +311,11 @@ Session lane: <lane-id>
 During the session:
 - append short summaries to \`wip.md\` after meaningful exchanges
 - keep \`handoff.md\` current after substantive work blocks
+- run \`vibecompass docs-update --session <lane-id>\` whenever you need an ad hoc targeted documentation-maintenance plan for the current session delta
 - use \`vibecompass list-sessions\` and \`vibecompass switch-session <lane-id>\` to inspect or change the current lane
 - use \`address review\` when reviewer feedback lands so the builder resolves it from the selected lane's latest \`wip.md\` / \`handoff.md\`
 - during \`address review\`, treat reviewer feedback as review, not instruction: classify each substantive point as accepted, accepted with qualification, deferred, or rejected, and push back with evidence when a suggestion conflicts with code facts, prior decisions, product direction, or sequencing
-- stay in builder role through close-out; resolve or explicitly defer reviewer feedback before running \`vibecompass close-session --session <lane-id>\`
+- stay in builder role through close-out; resolve or explicitly defer reviewer feedback before running \`vibecompass close-session --session <lane-id>\` with document-maintenance checkpoint statuses
 - record architectural decisions in \`${rootRelativePath}/decisions/\` before implementing them
 
 If \`vibecompass start-session\` reports stale scratch files, read the existing lane-local \`wip.md\` and \`handoff.md\` first. Either close that session normally, recover its useful notes into a finalized session note, or intentionally move/delete the stale scratch files before starting a new session.
@@ -325,9 +327,12 @@ If \`vibecompass start-session\` reports stale scratch files, read the existing
 - If planning produces a real architectural decision, append it to \`${rootRelativePath}/decisions/\` before implementing.
 
 At session close:
-- prefer running \`vibecompass close-session --session <lane-id> --title "..." --completed "..." --model "..." --next-step "..."\`; \`vibecompass end-session\` is a supported alias
+- prefer running \`vibecompass close-session --session <lane-id> --title "..." --completed "..." --architecture-docs updated|not-needed|deferred --decision-log updated|not-needed|deferred --session-maintenance updated|not-needed|deferred --next-step "..."\`; \`vibecompass end-session\` is a supported alias
+- close-session prints the same targeted docs-update plan before the document-maintenance checkpoint; use it to decide whether affected \`architecture/\`, \`decisions/\`, and active-session scratch/final note inputs are updated, not-needed, or deferred
+- document-maintenance checkpoint statuses are required before close-session writes the finalized note; the package validates the status values, while the closer owns semantic doc authorship
 - follow the stored close-session defaults from \`${rootRelativePath}/project.yaml\`
-- finalize the lane-local \`wip.md\` into \`${rootRelativePath}/sessions/YYYY-MM-DD-N-title.md\`
+- finalize the lane-local \`wip.md\` into \`${rootRelativePath}/sessions/YYYY-MM-DD-N-title.md\`; the permanent note distills decisions, completions, blockers, and next steps rather than preserving the full \`## Review log\`
+- if a granular reviewer trail must remain durable, summarize it explicitly in the session note inputs or create a separate finalized session note before close-session deletes lane scratch files
 - delete the closed lane directory under \`${rootRelativePath}/sessions/active/<lane-id>/\`
 - refresh any affected architecture/decision docs
 
@@ -371,6 +376,10 @@ Initial project-memory scaffold for ${projectConfig.name}.
 
 ${projectConfig.description ? `${projectConfig.description}\n` : ''}This document is a starting map, not a comprehensive architecture review.
 
+## Review metadata
+- Evidence: \`project.yaml\`, declared repo descriptors, and the files created by \`vibecompass init\`
+- Blindspots: Runtime architecture, feature flows, persistence, integrations, deployment, observability, and test strategy are not reviewed by the init scaffold.
+
 ## Details
 - Mode: \`${projectConfig.mode}\`
 - Documentation coverage: initial scaffold
@@ -394,6 +403,11 @@ Not yet documented:
 
 Before changing any undocumented area, inspect the relevant code and update or add architecture docs.
 
+## Retrieval guidance
+- Use this doc to understand the project-memory root shape, declared repositories, and the fact that the initial coverage is scaffold-only.
+- Do not use this doc as evidence for runtime behavior, feature ownership, data flow, external integrations, or deployment behavior.
+- Prefer more specific domain/feature/component docs once they exist, and run \`vibecompass docs-update --session <lane-id>\` during active work to find targeted maintenance needs.
+
 ## Next steps
 - Use the \`docs review\` prompt command for a comprehensive documentation review.
 - Replace this placeholder with domain/feature/component docs as the project map becomes evidence-backed.
@@ -487,10 +501,18 @@ architecture/<domain-slug>/<feature-slug>/<component>.md
 
 ## Recommended sections
 - \`## Description\`
+- \`## Review metadata\`
 - \`## Details\`
+- \`## Retrieval guidance\`
 - \`## Next steps\`
 - \`## Involved files\`
 
+## Shared quality bar
+- Review metadata should record concrete evidence sources and blindspots.
+- Retrieval guidance should say when to consult the doc, what it does not cover, and which related docs or decisions matter.
+- Details should distinguish confirmed behavior from known gaps or open follow-up.
+- Involved files should use concrete \`repo:path\` references that match the affected implementation surface.
+
 Each component doc is canonical. This README is only a convenience guide.
 `;
 }
@@ -600,6 +622,7 @@ function buildScaffoldAgentContext(options) {
 function renderWorkflowDefaults(workflow) {
   const lines = [
     `- reviewer handback: ${describeReviewerHandback(workflow)}`,
+    '- close-session: require document-maintenance checkpoint statuses for architecture docs, decision log, and session handoff/scratch',
     '- close-session: refresh any relevant architecture docs before finalizing the session',
     '- close-session: refresh any relevant decision files before finalizing the session',
   ];

package/src/session.js

@@ -5,11 +5,34 @@ import { parseSimpleYaml } from './simple-yaml.js';
 import { buildCloseSessionGuidance, resolveWorkflowSettings } from './workflow.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
 import { START_MARKER } from './generators/agent-files/markers.js';
+import { planDocsUpdate } from './docs-update.js';
+// This lazy-only cycle is intentional: manifest.js reads lane state from this
+// module, and session command handlers rewrite the derived manifest after
+// lane mutations. Keep both sides free of top-level calls into the other.
+import { writeStateManifest } from './manifest.js';
 
 const CURRENT_SESSION_REQUIRED_FIELDS = ['Date:', 'Working on:', 'Last thing completed:', 'Blockers:', 'Next session should:'];
 const WIP_HEADER_PATTERN = /^# WIP — (\d{4}-\d{2}-\d{2}) \(session (\d+)\)$/m;
 const SESSION_FILENAME_PATTERN = /^(\d{4}-\d{2}-\d{2})-(\d+)-([a-z0-9-]+)\.md$/i;
 const LANE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/;
+const DOCUMENT_MAINTENANCE_STATUSES = new Set(['updated', 'not-needed', 'deferred']);
+const DOCUMENT_MAINTENANCE_FIELDS = [
+  {
+    key: 'architectureDocs',
+    label: 'Architecture docs',
+    flag: '--architecture-docs',
+  },
+  {
+    key: 'decisionLog',
+    label: 'Decision log',
+    flag: '--decision-log',
+  },
+  {
+    key: 'sessionMaintenance',
+    label: 'Session handoff/scratch',
+    flag: '--session-maintenance',
+  },
+];
 const RESERVED_LANE_IDS = new Set([
   'active',
   'current',
@@ -114,6 +137,7 @@ export async function startProjectSession(options) {
     status: 'active',
     workingOn,
   }, { current: sessionId });
+  const manifestRefresh = await refreshStateManifestSafely(normalized.rootDir);
   const auditWarnings = await buildDocsReviewWarnings(normalized);
   const metadataWarnings = collectLaneMetadataWarnings(existingLanes);
   const agentFileSync = await syncAgentInstructionFilesSafely({
@@ -134,8 +158,10 @@ export async function startProjectSession(options) {
     warnings: [
       ...metadataWarnings,
       ...overlapWarnings,
+      ...manifestRefresh.warnings,
       ...auditWarnings,
     ],
+    manifest: manifestRefresh.manifest,
     agentFileSync,
   };
 }
@@ -162,6 +188,14 @@ export async function closeProjectSession(options) {
   const workflowSettings = await readWorkflowSettings(normalized.projectFilePath);
   const sessionId = await resolveExistingSessionId(normalized, options);
   const lanePaths = sessionId ? getLanePaths(normalized, sessionId) : normalized;
+  const documentMaintenance = normalizeDocumentMaintenanceCheckpoint(options?.documentMaintenance);
+  const docsUpdate = await planDocsUpdateSafely({
+    rootDir: normalized.rootDir,
+    cwd: normalized.cwd,
+    sessionId,
+    // Test injection seam; production callers should let close-session use the default planner.
+    planner: options?.docsUpdatePlanner,
+  });
 
   if (!(await fileExists(lanePaths.wipFilePath))) {
     throw new Error(
@@ -205,6 +239,7 @@ export async function closeProjectSession(options) {
       completed,
       decisions,
       models: models.length > 0 ? models : ['Not recorded.'],
+      documentMaintenance,
       blockers,
       nextSteps,
     }),
@@ -241,6 +276,7 @@ export async function closeProjectSession(options) {
   );
 
   await writeFile(normalized.claudePath, updatedClaude, 'utf8');
+  const manifestRefresh = await refreshStateManifestSafely(normalized.rootDir);
   const agentFileSync = await syncAgentInstructionFilesSafely({
     rootDir: normalized.rootDir,
     toolingRootDir: normalized.toolingRootDir,
@@ -256,7 +292,14 @@ export async function closeProjectSession(options) {
     sessionRelativePath,
     sessionDate: activeSession.sessionDate,
     sessionNumber: activeSession.sessionNumber,
+    documentMaintenance,
+    docsUpdatePlan: docsUpdate.plan,
     workflowGuidance: buildCloseSessionGuidance(workflowSettings),
+    warnings: [
+      ...docsUpdate.warnings,
+      ...manifestRefresh.warnings,
+    ],
+    manifest: manifestRefresh.manifest,
     agentFileSync,
     removedScratchFiles: [
       lanePaths.wipFilePath,
@@ -265,6 +308,46 @@ export async function closeProjectSession(options) {
   };
 }
 
+function normalizeDocumentMaintenanceCheckpoint(value) {
+  const source = value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+  const missing = [];
+  const invalid = [];
+  const checkpoint = {};
+
+  for (const field of DOCUMENT_MAINTENANCE_FIELDS) {
+    const normalized = normalizeOptionalString(source[field.key]);
+    if (!normalized) {
+      missing.push(`${field.flag} <updated|not-needed|deferred>`);
+      continue;
+    }
+
+    if (!DOCUMENT_MAINTENANCE_STATUSES.has(normalized)) {
+      invalid.push(`${field.flag}=${normalized}`);
+      continue;
+    }
+
+    checkpoint[field.key] = normalized;
+  }
+
+  if (missing.length > 0 || invalid.length > 0) {
+    const details = [
+      missing.length > 0
+        ? `Missing document-maintenance checkpoint status: ${missing.join(', ')}.`
+        : null,
+      invalid.length > 0
+        ? `Invalid document-maintenance checkpoint status: ${invalid.join(', ')}. Allowed values: updated, not-needed, deferred.`
+        : null,
+      'The package validates the close-session checkpoint, but the closer remains responsible for semantic doc updates.',
+    ].filter(Boolean);
+
+    throw new Error(details.join(' '));
+  }
+
+  return checkpoint;
+}
+
 export async function listProjectSessions(options = {}) {
   const normalized = normalizeSessionPaths(options);
   await ensureInitializedProjectMemory(normalized.rootDir, { allowMissingProjectFile: true });
@@ -300,6 +383,7 @@ export async function switchProjectSession(options = {}) {
     ),
     'utf8',
   );
+  const manifestRefresh = await refreshStateManifestSafely(normalized.rootDir);
   const agentFileSync = await syncAgentInstructionFilesSafely({
     rootDir: normalized.rootDir,
     toolingRootDir: normalized.toolingRootDir,
@@ -310,10 +394,50 @@ export async function switchProjectSession(options = {}) {
     claudePath: normalized.claudePath,
     current: sessionId,
     lanes,
+    warnings: manifestRefresh.warnings,
+    manifest: manifestRefresh.manifest,
     agentFileSync,
   };
 }
 
+async function refreshStateManifestSafely(rootDir) {
+  try {
+    const manifest = await writeStateManifest(rootDir);
+    return {
+      manifest,
+      warnings: [],
+    };
+  } catch (error) {
+    return {
+      manifest: null,
+      warnings: [
+        `State manifest refresh skipped: ${error instanceof Error ? error.message : String(error)}`,
+      ],
+    };
+  }
+}
+
+async function planDocsUpdateSafely(options) {
+  try {
+    const planner = typeof options.planner === 'function' ? options.planner : planDocsUpdate;
+    return {
+      plan: await planner({
+        rootDir: options.rootDir,
+        cwd: options.cwd,
+        sessionId: options.sessionId,
+      }),
+      warnings: [],
+    };
+  } catch (error) {
+    return {
+      plan: null,
+      warnings: [
+        `Docs-update plan skipped: ${error instanceof Error ? error.message : String(error)}`,
+      ],
+    };
+  }
+}
+
 async function syncAgentInstructionFilesSafely(options) {
   try {
     return await syncAgentInstructionFiles(options);
@@ -364,6 +488,7 @@ function normalizeSessionPaths(options) {
     : cwd;
 
   return {
+    cwd,
     rootDir,
     toolingRootDir,
     projectFilePath: path.resolve(rootDir, 'project.yaml'),
@@ -918,6 +1043,9 @@ ${renderBulletList(options.decisions, 'No new decisions were logged in this sess
 ## Models used
 ${renderBulletList(options.models)}
 
+## Document maintenance checkpoint
+${renderDocumentMaintenanceCheckpoint(options.documentMaintenance)}
+
 ## Blockers / open questions
 ${renderBulletList(options.blockers, 'No blocker remains.')}
 
@@ -926,6 +1054,12 @@ ${renderOrderedList(options.nextSteps)}
 `;
 }
 
+function renderDocumentMaintenanceCheckpoint(documentMaintenance) {
+  return DOCUMENT_MAINTENANCE_FIELDS
+    .map((field) => `- ${field.label}: ${documentMaintenance[field.key]}`)
+    .join('\n');
+}
+
 function renderBulletList(items, fallback) {
   if (items.length === 0) {
     return `- ${fallback}`;

package/src/status.js

@@ -5,6 +5,7 @@ import { sha256Text } from './hash.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { listProjectSessions } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
+import { scanProjectMemory } from './project-memory.js';
 
 export async function getProjectStatus(options = {}) {
   const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
@@ -18,11 +19,12 @@ export async function getProjectStatus(options = {}) {
     cwd,
     ...(options.packageVersion ? { packageVersion: options.packageVersion } : {}),
   });
-  const [project, sessions, docsReview, agentFiles] = await Promise.all([
+  const [project, sessions, docsReview, agentFiles, projectMemory] = await Promise.all([
     readProjectSummary(compatibility.projectFilePath),
     readSessionsStatus(rootDir),
     readDocsReviewStatus(rootDir),
     readAgentFileStatus(rootDir, toolingRootDir),
+    readProjectMemoryStatus(rootDir),
   ]);
 
   return {
@@ -39,12 +41,14 @@ export async function getProjectStatus(options = {}) {
     sessions,
     docsReview,
     agentFiles,
+    projectMemory,
     recommendations: buildRecommendations({
       project,
       compatibility,
       sessions,
       docsReview,
       agentFiles,
+      projectMemory,
     }),
   };
 }
@@ -99,6 +103,9 @@ export function renderStatusText(status) {
       ? [`- Output drift: ${status.docsReview.outputDrift.reasons.join('; ')}`]
       : []),
     '',
+    'Project memory:',
+    ...formatProjectMemoryStatus(status.projectMemory),
+    '',
     'Agent files:',
     ...formatAgentFileStatus(status.agentFiles),
   );
@@ -125,6 +132,7 @@ export function toStatusJson(status) {
     sessions: status.sessions,
     docsReview: status.docsReview,
     agentFiles: status.agentFiles,
+    projectMemory: status.projectMemory,
     recommendations: status.recommendations,
   };
 }
@@ -297,7 +305,48 @@ async function readAgentFileStatus(rootDir, toolingRootDir) {
   }
 }
 
-function buildRecommendations({ project, compatibility, sessions, docsReview, agentFiles }) {
+async function readProjectMemoryStatus(rootDir) {
+  try {
+    const scan = await scanProjectMemory(rootDir);
+    const architectureDocs = scan.documents.filter((document) => document.kind === 'architecture');
+    const architectureWarnings = scan.warnings
+      .filter((warning) => warning.path?.startsWith('architecture/'))
+      .map((warning) => ({
+        path: warning.path,
+        code: warning.code,
+        message: warning.message,
+      }));
+
+    return {
+      status: scan.errors.length > 0 ? 'errors' : 'ok',
+      architectureDocCount: architectureDocs.length,
+      architectureWarningCount: architectureWarnings.length,
+      warningSample: architectureWarnings.slice(0, 10),
+      truncatedWarningCount: Math.max(0, architectureWarnings.length - 10),
+      errorCount: scan.errors.length,
+      errorSample: scan.errors.slice(0, 10).map((error) => ({
+        path: error.path,
+        code: error.code,
+        message: error.message,
+      })),
+      truncatedErrorCount: Math.max(0, scan.errors.length - 10),
+    };
+  } catch (error) {
+    return {
+      status: 'unavailable',
+      architectureDocCount: 0,
+      architectureWarningCount: 0,
+      warningSample: [],
+      truncatedWarningCount: 0,
+      errorCount: 0,
+      errorSample: [],
+      truncatedErrorCount: 0,
+      errorMessage: error instanceof Error ? error.message : 'Unable to scan project memory.',
+    };
+  }
+}
+
+function buildRecommendations({ project, compatibility, sessions, docsReview, agentFiles, projectMemory }) {
   const recommendations = [];
   if (project.status === 'unreadable') {
     recommendations.push('vibecompass init --guided');
@@ -320,6 +369,16 @@ function buildRecommendations({ project, compatibility, sessions, docsReview, ag
     recommendations.push('vibecompass sync-agents --dry-run');
   }
 
+  if (projectMemory.status === 'errors') {
+    recommendations.push('vibecompass status --json');
+  } else if (projectMemory.architectureWarningCount > 0) {
+    recommendations.push(
+      sessions.status === 'ok' && sessions.current
+        ? `vibecompass docs-update --session ${sessions.current}`
+        : 'vibecompass docs-review --guided',
+    );
+  }
+
   if (sessions.status === 'ok' && sessions.lanes.length === 0) {
     recommendations.push('vibecompass start-session --id LANE_ID --working-on "TASK"');
   } else if (sessions.status === 'ok' && sessions.lanes.length >= 2) {
@@ -334,6 +393,8 @@ function hasStatusDrift(status) {
     status.compatibility.warnings.length > 0 ||
     status.docsReview.status !== 'completed' ||
     Boolean(status.docsReview.outputDrift?.hasDrift) ||
+    status.projectMemory.status !== 'ok' ||
+    status.projectMemory.architectureWarningCount > 0 ||
     status.agentFiles.status !== 'ok' ||
     status.agentFiles.results.some((item) => item.changed || item.warning)
   );
@@ -390,6 +451,34 @@ function formatDocsReviewStatus(docsReview) {
   return `${docsReview.status}${docsReview.completedAt ? ` at ${docsReview.completedAt}` : ''}`;
 }
 
+function formatProjectMemoryStatus(projectMemory) {
+  if (projectMemory.status === 'unavailable') {
+    return [`- unavailable (${projectMemory.errorMessage})`];
+  }
+
+  const lines = [
+    `- Architecture docs: ${projectMemory.architectureDocCount}`,
+    `- Architecture warnings: ${projectMemory.architectureWarningCount}`,
+  ];
+
+  for (const warning of projectMemory.warningSample) {
+    lines.push(`- ${warning.path}: ${warning.code} — ${warning.message}`);
+  }
+
+  if (projectMemory.truncatedWarningCount > 0) {
+    lines.push(`- ${projectMemory.truncatedWarningCount} more architecture warning(s) omitted; use --json for the full status sample.`);
+  }
+
+  if (projectMemory.errorCount > 0) {
+    lines.push(`- Scan errors: ${projectMemory.errorCount}`);
+    for (const error of projectMemory.errorSample) {
+      lines.push(`- ${error.path}: ${error.code} — ${error.message}`);
+    }
+  }
+
+  return lines;
+}
+
 function formatAgentFileStatus(agentFiles) {
   if (agentFiles.status !== 'ok') {
     return [`- unavailable (${agentFiles.errorMessage})`];

package/src/workflow.js

@@ -78,6 +78,7 @@ export function buildCloseSessionGuidance(workflowSettings) {
   const guidance = [];
 
   guidance.push('Reviewer handback stays in the selected sessions/active/<lane-id>/wip.md and handoff.md before close-session runs.');
+  guidance.push('Close-session requires document-maintenance checkpoint statuses for architecture docs, decision log, and session handoff/scratch: updated, not-needed, or deferred.');
 
   if (workflowSettings.closeSession.refreshArchitectureDocs) {
     guidance.push('Refresh any relevant architecture docs before finalizing the session.');

package/src/workflows/registry.js

@@ -12,7 +12,8 @@ export const WORKFLOW_REGISTRY = [
       { trigger: 'planning mode', summary: 'optional prompt-level mode for scoping work before implementation' },
       { trigger: 'review handoff', summary: 'reviewer reads the selected lane handoff and appends findings' },
       { trigger: 'address review', summary: 'builder critically resolves reviewer feedback from the selected lane scratch files' },
-      { trigger: 'close session', summary: 'builder runs the close-out checklist and ends with `vibecompass close-session --session <lane-id>`; `end session` and `vibecompass end-session` are accepted aliases' },
+      { trigger: 'docs update', summary: 'builder runs a targeted session-delta documentation maintenance plan with `vibecompass docs-update --session <lane-id>`' },
+      { trigger: 'close session', summary: 'builder runs the close-out checklist and ends with `vibecompass close-session --session <lane-id>` plus required document-maintenance checkpoint statuses; `end session` and `vibecompass end-session` are accepted aliases' },
     ],
   },
   {