@vibecompass/vibecompass 0.10.4 → 0.10.6

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' },
     ],
   },
   {