@vibecompass/vibecompass 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.9.3 - 2026-06-14
+
+- Make docs-review prompts mode-aware: interactive AI sessions stop at the coverage-plan approval gate, while `--run-local` and hosted single-turn runs emit fenced proposal material for later apply/proposal review.
+- Clarify that pre-approval coverage plans are proposed scope, not accepted output, so agents should not label proposed areas `accepted` before user approval.
+- Update generated docs-review workflow guidance and prompt regression coverage for the interactive vs single-turn split.
+
+## 0.9.2 - 2026-06-14
+
+- Clarify docs-review acceptance gates so agents state when no architecture docs have been applied yet and only report completion after apply succeeds.
+- Render local folder repo sources correctly in generated agent files instead of showing `null`.
+- Fix false agent-file drift in `status` after `sync-agents` when managed files are already current.
+
 ## 0.9.1 - 2026-06-14
 
 - Make local docs-review prompts self-contained by printing the accepted output file, root-scoped apply command, and same-version `npx` fallback the agent should run after user acceptance.

package/README.md

@@ -46,7 +46,11 @@ Please set it up in this project:
 2. Initialize project memory with guided setup.
 3. If this folder is not a Git repo, use a local folder source.
 4. Start a named session lane for this setup work.
-5. Tell me which files changed and what I should review.
+5. If you run docs review, continue until either architecture docs are applied
+   or you are waiting for my explicit coverage-plan approval. Do not call docs
+   review done just because the marker was created.
+6. Tell me which files changed, whether docs were actually applied, and what I
+   should review next.
 
 Do not ask me to paste secret tokens into chat.
 ```
@@ -58,8 +62,9 @@ docs review
 ```
 
 That asks the AI to inspect your code and create the first real architecture
-docs. The package prints the output file and the exact apply command when the
-docs are ready for you to accept.
+docs. If it asks you to approve a coverage plan, approve it or ask for changes;
+the package prints the output file and exact apply command after the accepted
+docs are ready.
 
 ### Terminal path
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecompass/vibecompass",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

package/src/docs-review.js

@@ -79,6 +79,9 @@ export async function preflightDocsReview(options = {}, environment = {}) {
     : normalizeReviewConfig(options);
   const env = environment.env ?? process.env;
   const localProvider = resolveLocalProvider(options);
+  const promptExecutionMode = options.submitHosted || shouldRunLocal(options)
+    ? 'single-turn'
+    : 'interactive';
   const runtime = resolveDocsReviewRuntime(project, {
     env,
     guided: Boolean(options.guided),
@@ -92,6 +95,7 @@ export async function preflightDocsReview(options = {}, environment = {}) {
     rootDir,
     llm: reviewConfig.llm,
     model: reviewConfig.model,
+    executionMode: promptExecutionMode,
   });
 
   const status = options.submitHosted
@@ -1687,6 +1691,36 @@ function renderReviewPrompt(options) {
   const outputPath = path.join(options.rootDir, 'state', 'docs-review-output.md');
   const applyCommand = `vibecompass docs-review --root ${shellQuote(options.rootDir)} --apply-output --output ${shellQuote(outputPath)}`;
   const npxApplyCommand = `npx -y @vibecompass/vibecompass@${PACKAGE_VERSION} docs-review --root ${shellQuote(options.rootDir)} --apply-output --output ${shellQuote(outputPath)}`;
+  const isSingleTurn = options.executionMode === 'single-turn';
+  const coveragePlanStageLines = isSingleTurn
+    ? [
+      '- This is a single-turn execution mode: there is no mid-review user approval turn.',
+      '- Treat the coverage plan you emit in this response as accepted proposal material, then emit the planned `vibecompass-coverage-plan`, architecture-doc, and decision-recommendation fences in the same response.',
+      '- Human review happens later at the local apply-output step or hosted proposal surface; generated output is not canonical until accepted and applied.',
+    ]
+    : [
+      '- Before user approval, present the coverage plan as human-readable proposed scope. Do not label proposed areas `accepted` and do not emit the `vibecompass-coverage-plan` fence yet.',
+      '- Ask for user acceptance before emitting fenced coverage-plan or architecture-doc blocks. When you stop for acceptance, state plainly that no architecture docs have been applied yet.',
+      '- After approval, emit the accepted plan as one `vibecompass-coverage-plan version=1` JSON fence before architecture-doc blocks.',
+    ];
+  const outputContractIntroLines = isSingleTurn
+    ? [
+      'Because this is a single-turn execution mode, output the machine-readable coverage-plan block in this response before architecture-doc blocks.',
+    ]
+    : [
+      'If you are stopping for user approval, do not output the machine-readable fence below yet; show the plan as proposed scope and ask the user to approve or revise it.',
+      '',
+      'After the user accepts the plan, output one machine-readable coverage-plan block for the accepted plan:',
+    ];
+  const stage4WriteLine = isSingleTurn
+    ? `- The package will save the model response to \`${outputPath}\`; local users or hosted proposal reviewers decide what becomes canonical later.`
+    : `- After the user accepts Stage 2, write the complete accepted fenced output verbatim to \`${outputPath}\`.`;
+  const finalOutputLine = isSingleTurn
+    ? `Only include accepted proposal-material blocks for coverage, architecture, and decision recommendations. The package or hosted worker saves the response to \`${outputPath}\`; report that generated output still requires local apply or hosted proposal acceptance before it is canonical.`
+    : `Only include accepted coverage, architecture, and decision-recommendation blocks. After user acceptance, save the final accepted output to \`${outputPath}\`, run \`${applyCommand}\` or \`${npxApplyCommand}\`, and report applied paths plus parser warnings.`;
+  const architectureDocBlockIntro = isSingleTurn
+    ? 'Then, for each planned architecture doc in this single-turn response, output one fenced block exactly like this:'
+    : 'Then, for each architecture doc the user accepts, output one fenced block exactly like this:';
 
   return [
     `# ${DOCS_REVIEW_PROMPT_VERSION}`,
@@ -1699,6 +1733,7 @@ function renderReviewPrompt(options) {
     `- Project mode: ${options.project.mode}`,
     `- Review provider to record: ${options.llm}`,
     `- Review model/version to record: ${options.model}`,
+    `- Execution mode: ${isSingleTurn ? 'single-turn (emit accepted proposal output now)' : 'interactive (stop at coverage-plan approval gate)'}`,
     `- Accepted output file: ${outputPath}`,
     `- Apply command after user acceptance: ${applyCommand}`,
     `- Apply command if the CLI is not installed on PATH: ${npxApplyCommand}`,
@@ -1721,8 +1756,7 @@ function renderReviewPrompt(options) {
     '- The minimum useful set must cover: user journey, project/system map (frontend/backend/API/data/integration structure and connections), and summaries of the core journey-facing features.',
     '- Prioritize entry points, user-flow/gating relationships, data ownership, external integrations, jobs/async boundaries, auth/security boundaries, and test surfaces.',
     '- Mark each proposed doc as `comprehensive`, `partial`, or `initial`, with the reason and blindspots.',
-    '- Emit the accepted plan as one `vibecompass-coverage-plan version=1` JSON fence before architecture-doc blocks.',
-    '- Ask for user acceptance before emitting fenced architecture-doc blocks.',
+    ...coveragePlanStageLines,
     '',
     'Stage 3 — Bounded doc generation:',
     '- Generate only accepted docs, one complete fenced block per architecture path.',
@@ -1732,10 +1766,10 @@ function renderReviewPrompt(options) {
     '- Include only the most important involved files; prefer representative entry points and owned contracts over exhaustive file lists.',
     '',
     'Stage 4 — Apply and verify:',
-    `- After the user accepts Stage 2, write the complete accepted fenced output verbatim to \`${outputPath}\`.`,
+    stage4WriteLine,
     `- Then run \`${applyCommand}\` to validate and apply the accepted blocks.`,
     `- If \`vibecompass\` is not installed on PATH, run \`${npxApplyCommand}\` instead.`,
-    '- Surface any parser warnings, especially oversized docs, so the user can decide whether to compact or accept the output.',
+    '- Only report docs-review as applied after the apply command succeeds. Surface any parser warnings, especially oversized docs, so the user can decide whether to compact or accept the output.',
     '',
     '## Architecture Doc Contract',
     'When creating or updating architecture docs, use the existing VibeCompass structure:',
@@ -1804,7 +1838,7 @@ function renderReviewPrompt(options) {
     '- token-budget risks or oversized-doc candidates',
     '- proposed decisions, if any',
     '',
-    'Then output one machine-readable coverage-plan block for the accepted plan:',
+    ...outputContractIntroLines,
     '',
     '```vibecompass-coverage-plan version=1',
     '{',
@@ -1825,7 +1859,7 @@ function renderReviewPrompt(options) {
     '}',
     '```',
     '',
-    'Then, for each architecture doc the user accepts, output one fenced block exactly like this:',
+    architectureDocBlockIntro,
     '',
     '```vibecompass-architecture-doc path=architecture/domain/feature/component.md',
     '<complete markdown file content>',
@@ -1842,7 +1876,7 @@ function renderReviewPrompt(options) {
     '**Context:** Optional supporting context.',
     '```',
     '',
-    `Only include accepted coverage, architecture, and decision-recommendation blocks. After user acceptance, save the final accepted output to \`${outputPath}\`, run \`${applyCommand}\` or \`${npxApplyCommand}\`, and report applied paths plus parser warnings.`,
+    finalOutputLine,
   ].join('\n');
 }
 

package/src/generators/agent-files/markers.js

@@ -46,7 +46,8 @@ export function applyManagedBlock(existingContent, generatedContent, options = {
   }
 
   const before = existingContent.slice(0, startIndex);
-  const after = existingContent.slice(endIndex + END_MARKER.length);
+  const rawAfter = existingContent.slice(endIndex + END_MARKER.length);
+  const after = rawAfter.trim() === '' ? '' : rawAfter;
   const beforeSeparator = before === '' || before.endsWith('\n') ? '' : '\n';
   const afterSeparator = after === '' || after.startsWith('\n') ? '' : '\n';
 

package/src/generators/agent-files/template.js

@@ -63,7 +63,7 @@ function renderProjectSnapshot(context) {
   }
 
   for (const repo of context.repos) {
-    lines.push(`- Repo \`${repo.id}\`: ${repo.remote}`);
+    lines.push(`- Repo \`${repo.id}\`: ${formatRepoDescriptor(repo)}`);
   }
 
   const domainCount = context.domains.length;
@@ -82,6 +82,18 @@ function renderProjectSnapshot(context) {
   return lines.length > 0 ? lines : ['- No project details recorded yet.'];
 }
 
+function formatRepoDescriptor(repo) {
+  if (repo?.source === 'local' || repo?.path) {
+    return `local folder ${repo.path ?? '.'}`;
+  }
+
+  if (repo?.remote) {
+    return repo.remote;
+  }
+
+  return 'source not recorded';
+}
+
 function renderDecisionLine(decision) {
   return `D-${String(decision.decision_id).padStart(3, '0')} — ${decision.title}`;
 }

package/src/scaffold.js

@@ -459,11 +459,11 @@ ${repoLines}
 }
 
 function formatRepoDescriptor(repo) {
-  if (repo.source === 'local') {
+  if (repo.source === 'local' || repo.path) {
     return `local folder ${repo.path}`;
   }
 
-  return repo.remote;
+  return repo.remote ?? 'source not recorded';
 }
 
 function generateArchitectureGuide(projectConfig) {

package/src/status.js

@@ -281,7 +281,7 @@ async function readAgentFileStatus(rootDir, toolingRootDir) {
       results: result.results.map((item) => ({
         format: item.format,
         relativePath: item.relativePath,
-        status: item.status,
+        status: item.changed || item.warning ? item.status : 'current',
         warning: item.warning,
         changed: item.changed,
         conflicts: item.conflicts ?? [],

package/src/workflows/registry.js

@@ -90,8 +90,8 @@ function renderDocsReviewWorkflow(options = {}) {
   const decisionsPath = joinRootRelative(rootRelativePath, 'decisions/');
   const sessionsPath = joinRootRelative(rootRelativePath, 'sessions/');
   const outputPath = joinRootRelative(rootRelativePath, 'state/docs-review-output.md');
-  const applyCommand = `vibecompass docs-review --root ${rootRelativePath} --apply-output`;
-  const npxApplyCommand = `npx -y @vibecompass/vibecompass@${PACKAGE_VERSION} docs-review --root ${rootRelativePath} --apply-output`;
+  const applyCommand = `vibecompass docs-review --root ${rootRelativePath} --apply-output --output ${outputPath}`;
+  const npxApplyCommand = `npx -y @vibecompass/vibecompass@${PACKAGE_VERSION} docs-review --root ${rootRelativePath} --apply-output --output ${outputPath}`;
 
   return `# VibeCompass Workflow — docs review
 
@@ -113,11 +113,11 @@ 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, user journey, project/system map, 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\`. The accepted \`architecture/overview/project-shape.md\` doc should include exactly one \`vibecompass-project-map version=1\` JSON block with journey-facing features, entry points, and evidence-backed relationships. Accepted local decisions may be fenced as \`vibecompass-decision-recommendation target=decisions/domain.md\` blocks without D-numbers.
+4. Present the evidence inventory, coverage plan, user journey, project/system map, proposed architecture docs, blindspots, token-budget risks, and any decision candidates before generating accepted output. If you stop here for user approval, state clearly that no architecture docs have been applied yet and do not label proposed areas as accepted.
+5. Draft only output the user accepts. After approval, 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\`. The accepted \`architecture/overview/project-shape.md\` doc should include exactly one \`vibecompass-project-map version=1\` JSON block with journey-facing features, entry points, and evidence-backed relationships. 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 verbatim to \`${outputPath}\`.
-8. Run \`${applyCommand}\` to validate and apply the accepted blocks. If \`vibecompass\` is not installed on PATH, run \`${npxApplyCommand}\` instead. If accepted docs were written manually outside the output file, run \`vibecompass docs-review --root ${rootRelativePath} --complete\` after confirming the marker should be completed.
+8. Run \`${applyCommand}\` to validate and apply the accepted blocks. If \`vibecompass\` is not installed on PATH, run \`${npxApplyCommand}\` instead. Only report docs-review as applied after this command succeeds. If accepted docs were written manually outside the output file, run \`vibecompass docs-review --root ${rootRelativePath} --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