@vibecompass/vibecompass 0.5.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

@@ -0,0 +1,142 @@
+export const WORKFLOW_REGISTRY = [
+  {
+    id: 'session-lifecycle',
+    title: 'Session lifecycle',
+    detailPath: 'context.md',
+    summary: 'Builder/reviewer lane lifecycle, handoffs, planning mode, and close-out.',
+    promptCommands: [
+      { trigger: 'start session', summary: 'builder role trigger' },
+      { trigger: 'join as reviewer', summary: 'reviewer role trigger' },
+      { 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 processes 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' },
+    ],
+  },
+  {
+    id: 'docs-review',
+    title: 'Docs review',
+    detailPath: 'workflows/docs-review.md',
+    summary: 'Generate evidence-backed architecture docs from the user\'s preferred AI session.',
+    promptCommands: [
+      { trigger: 'docs review', summary: 'agent-led architecture documentation review using the preferred LLM prompt box' },
+    ],
+    generatedFileKind: 'workflow-docs-review',
+    renderFile: renderDocsReviewWorkflow,
+  },
+];
+
+export function getPromptCommands() {
+  return WORKFLOW_REGISTRY.flatMap((workflow) =>
+    workflow.promptCommands.map((command) => ({
+      ...command,
+      workflowId: workflow.id,
+      workflowTitle: workflow.title,
+      detailPath: workflow.detailPath,
+    })),
+  );
+}
+
+export function getWorkflowConflictScanPatterns() {
+  const patterns = new Set([
+    'session',
+    'handoff',
+    'decisions',
+    'wip.md',
+    'builder',
+    'reviewer',
+  ]);
+
+  for (const command of getPromptCommands()) {
+    const normalizedTrigger = command.trigger.toLowerCase();
+    patterns.add(normalizedTrigger);
+    patterns.add(slugifyPromptTrigger(normalizedTrigger));
+  }
+
+  return Array.from(patterns);
+}
+
+export function getGeneratedWorkflowFiles(options = {}) {
+  const rootRelativePath = options.rootRelativePath ?? '.';
+  return WORKFLOW_REGISTRY
+    .filter((workflow) => typeof workflow.renderFile === 'function')
+    .map((workflow) => ({
+      kind: workflow.generatedFileKind,
+      relativePath: workflow.detailPath,
+      content: workflow.renderFile({
+        rootRelativePath,
+        workflow,
+      }),
+    }));
+}
+
+export function renderPromptCommandLines(options = {}) {
+  const rootRelativePath = options.rootRelativePath ?? '.';
+  return getPromptCommands().map((command) => {
+    const detailPath = command.detailPath
+      ? ` Read \`${joinRootRelative(rootRelativePath, command.detailPath)}\` for the full workflow.`
+      : '';
+    return `- \`${command.trigger}\` — ${command.summary}.${detailPath}`;
+  });
+}
+
+function renderDocsReviewWorkflow(options = {}) {
+  const rootRelativePath = options.rootRelativePath ?? '.';
+  const projectYamlPath = joinRootRelative(rootRelativePath, 'project.yaml');
+  const contextPath = joinRootRelative(rootRelativePath, 'context.md');
+  const architecturePath = joinRootRelative(rootRelativePath, 'architecture/');
+  const decisionsPath = joinRootRelative(rootRelativePath, 'decisions/');
+  const sessionsPath = joinRootRelative(rootRelativePath, 'sessions/');
+  const outputPath = joinRootRelative(rootRelativePath, 'state/docs-review-output.md');
+
+  return `# VibeCompass Workflow — docs review
+
+Generated by VibeCompass. This file is a package-owned workflow guide and may be refreshed by \`vibecompass refresh-workflow --apply\`.
+
+## 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 docs-review output.
+
+## Goal
+
+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
+
+1. Read \`${projectYamlPath}\`, \`${contextPath}\`, existing \`${architecturePath}\`, \`${decisionsPath}\`, and finalized \`${sessionsPath}\` notes.
+2. Inspect the declared source repos in stages:
+   - inventory paths, manifests, configs, route/job/test directories, and existing architecture frontmatter first
+   - 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, 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 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
+
+- Do not duplicate the full canonical review prompt in this file. The package command prints that contract from its current implementation.
+- Follow the canonical review prompt for evidence, blindspot, and decision-recommendation constraints.
+- Treat the package-owned prompt as the source of truth. Tool-specific skills may wrap this workflow, but should not define a divergent docs-review protocol.
+- Do not edit generated agent files directly. Update VibeCompass project memory or rerun package commands instead.
+`;
+}
+
+function slugifyPromptTrigger(trigger) {
+  return trigger.trim().replace(/\s+/g, '-');
+}
+
+function joinRootRelative(rootRelativePath, relativePath) {
+  if (!rootRelativePath || rootRelativePath === '.') {
+    return relativePath;
+  }
+
+  return `${rootRelativePath.replace(/\/$/, '')}/${relativePath}`;
+}