@vibecompass/vibecompass 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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.2",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

package/src/docs-review.js

@@ -1722,7 +1722,7 @@ function renderReviewPrompt(options) {
     '- 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.',
+    '- Ask for user acceptance before emitting fenced architecture-doc blocks. When you stop for acceptance, state plainly that no architecture docs have been applied yet.',
     '',
     'Stage 3 — Bounded doc generation:',
     '- Generate only accepted docs, one complete fenced block per architecture path.',
@@ -1735,7 +1735,7 @@ function renderReviewPrompt(options) {
     `- After the user accepts Stage 2, write the complete accepted fenced output verbatim to \`${outputPath}\`.`,
     `- 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:',

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.
+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.
 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.
 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