@vibecompass/vibecompass 0.6.0 → 0.7.0

package/src/status.js

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { inspectProjectCompatibility } from './compatibility.js';
+import { sha256Text } from './hash.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { listProjectSessions } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
@@ -94,6 +95,9 @@ export function renderStatusText(status) {
     '',
     'Docs review:',
     `- ${formatDocsReviewStatus(status.docsReview)}`,
+    ...(status.docsReview.outputDrift?.hasDrift
+      ? [`- Output drift: ${status.docsReview.outputDrift.reasons.join('; ')}`]
+      : []),
     '',
     'Agent files:',
     ...formatAgentFileStatus(status.agentFiles),
@@ -192,12 +196,15 @@ async function readDocsReviewStatus(rootDir) {
   const markerPath = path.join(rootDir, 'state', 'docs-review.json');
   try {
     const marker = JSON.parse(await readFile(markerPath, 'utf8'));
+    const outputDrift = await readDocsReviewOutputDrift(rootDir, marker);
     return {
       status: typeof marker.status === 'string' ? marker.status : 'unknown',
       markerPath,
       completedAt: typeof marker.completed_at === 'string' ? marker.completed_at : null,
       provider: typeof marker.provider === 'string' ? marker.provider : null,
       model: typeof marker.model === 'string' ? marker.model : null,
+      applied: marker.applied ?? null,
+      outputDrift,
     };
   } catch (error) {
     if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
@@ -215,6 +222,36 @@ async function readDocsReviewStatus(rootDir) {
   }
 }
 
+async function readDocsReviewOutputDrift(rootDir, marker) {
+  const applied = marker?.applied;
+  if (!applied || typeof applied !== 'object') {
+    return { status: 'not-tracked', hasDrift: false, reasons: [] };
+  }
+
+  const reasons = [];
+  if (typeof applied.output_path === 'string' && typeof applied.output_hash === 'string') {
+    try {
+      const outputContent = await readFile(applied.output_path, 'utf8');
+      const currentOutputHash = sha256Text(outputContent);
+      if (currentOutputHash !== applied.output_hash) {
+        reasons.push('state/docs-review-output.md changed since apply');
+      }
+    } catch (error) {
+      if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+        reasons.push('state/docs-review-output.md is missing since apply');
+      } else {
+        reasons.push('state/docs-review-output.md could not be read for drift check');
+      }
+    }
+  }
+
+  return {
+    status: reasons.length > 0 ? 'drift' : 'current',
+    hasDrift: reasons.length > 0,
+    reasons,
+  };
+}
+
 async function readAgentFileStatus(rootDir, toolingRootDir) {
   try {
     const result = await syncAgentInstructionFiles({
@@ -257,8 +294,10 @@ function buildRecommendations({ project, compatibility, sessions, docsReview, ag
     recommendations.push('vibecompass refresh-workflow --dry-run');
   }
 
-  if (docsReview.status === 'missing') {
+  if (docsReview.status === 'missing' || docsReview.status === 'rebuild-ready') {
     recommendations.push('vibecompass docs-review --guided');
+  } else if (docsReview.outputDrift?.hasDrift) {
+    recommendations.push('vibecompass docs-review --apply-output');
   }
 
   if (agentFiles.status === 'ok' && agentFiles.results.some((item) => item.changed || item.warning)) {
@@ -278,6 +317,7 @@ function hasStatusDrift(status) {
   return (
     status.compatibility.warnings.length > 0 ||
     status.docsReview.status !== 'completed' ||
+    Boolean(status.docsReview.outputDrift?.hasDrift) ||
     status.agentFiles.status !== 'ok' ||
     status.agentFiles.results.some((item) => item.changed || item.warning)
   );

package/src/workflows/registry.js

@@ -95,11 +95,11 @@ Generated by VibeCompass. This file is a package-owned workflow guide and may be
 
 ## Prompt trigger
 
-When the user says \`docs review\`, run this workflow inside the current Claude Code, Codex, Cursor, or Copilot session. The npm package owns state markers and apply mechanics; the AI session owns repository inspection and writing accepted architecture docs.
+When the user says \`docs review\`, run this workflow inside the current Claude Code, Codex, Cursor, or Copilot session. The npm package owns state markers and apply mechanics; the AI session owns repository inspection and writing accepted docs-review output.
 
 ## Goal
 
-Turn starter project memory into evidence-backed architecture docs under \`architecture/<domain>/<feature>/<component>.md\`.
+Turn starter project memory into evidence-backed architecture docs under \`architecture/<domain>/<feature>/<component>.md\`, a projected coverage plan, and optional accepted decision recommendations.
 
 ## Steps
 
@@ -109,12 +109,16 @@ Turn starter project memory into evidence-backed architecture docs under \`archi
    - produce a coverage plan before reading broad source bodies
    - read targeted source files only when the coverage plan needs evidence
 3. Run \`vibecompass docs-review --guided --llm <tool-name> --model <model-name>\` to record the review marker and print the canonical docs-review contract. Use the current AI tool name and model when known.
-4. Present the evidence inventory, coverage plan, proposed architecture docs, blindspots, and token-budget risks before generating accepted docs.
-5. Draft only architecture docs the user accepts. Accepted docs must be fenced exactly as \`vibecompass-architecture-doc path=architecture/domain/feature/component.md\` blocks and must include required frontmatter: \`domain\`, \`feature\`, \`component\`, and \`status\`.
+4. Present the evidence inventory, coverage plan, proposed architecture docs, blindspots, token-budget risks, and any decision candidates before generating accepted output.
+5. Draft only output the user accepts. The accepted plan must be fenced as \`vibecompass-coverage-plan version=1\`. Accepted architecture docs must be fenced as \`vibecompass-architecture-doc path=architecture/domain/feature/component.md\` blocks and must include required frontmatter: \`domain\`, \`feature\`, \`component\`, and \`status\`. Accepted local decisions may be fenced as \`vibecompass-decision-recommendation target=decisions/domain.md\` blocks without D-numbers.
 6. Keep each generated architecture doc focused and retrieval-oriented. Soft budget: under 12000 bytes per doc unless the extra detail is necessary and called out in review metadata or retrieval guidance.
 7. Write the accepted fenced blocks to \`${outputPath}\`.
 8. Run \`vibecompass docs-review --apply-output\` to validate and apply the accepted blocks. If accepted docs were written manually outside the output file, run \`vibecompass docs-review --complete\` after confirming the marker should be completed.
-9. Run \`vibecompass status\` to confirm the docs-review marker is complete. Report the applied architecture paths, any parser warnings such as oversized docs, and any blindspots documented in the accepted docs-review output.
+9. Run \`vibecompass status\` to confirm the docs-review marker is complete and not drifted. Report the applied architecture paths, coverage projection, decision recommendations, parser warnings such as oversized docs or missing review metadata, and any blindspots documented in the accepted docs-review output.
+
+## Rebuild option
+
+If the user explicitly wants to rerun docs-review from a clean or narrower architecture-doc slate, preview the scope first with \`vibecompass docs-review --rebuild --path architecture/<scope>\`. Only apply cleanup after the user accepts the preview; use \`vibecompass docs-review --rebuild --apply --stale-policy archive --path architecture/<scope>\` when the user explicitly wants selected stale docs archived before the next review. Rebuild archives selected \`architecture/**/*.md\` docs under \`state/docs-review-archive/\`; it does not mutate decisions, sessions, project.yaml, workflow files, agent instruction files, \`architecture/README.md\`, or \`architecture/overview/project-shape.md\`.
 
 ## Rules