@vibecompass/vibecompass 0.10.7 → 0.10.8

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.10.8 - 2026-07-02
+
+- Clarify generated docs-review workflow guidance so first passes establish breadth-first baseline coverage before optional scoped deepening.
+- Add build-session guidance that tells builders to inspect relevant docs, decisions, coverage state, and source before feature work, then record, deepen, or explicitly defer documentation gaps before close-out.
+- Print mode-aware hosted projection guidance during `close-session` / `end-session`: connected `local-primary` roots get an explicit `vibecompass push` reminder, `hosted-only` roots are directed through hosted/dashboard refresh, and `local-only` roots have no hosted push expectation.
+- Expand close-session hosted guidance tests across local-primary with binding, local-primary without binding, hosted-only, and local-only modes.
+
 ## 0.10.7 - 2026-06-25
 
 - Let `connect-hosted` attach hosted sync to existing `local-only` project-memory roots by promoting them to `local-primary`, so local-only users can run the hosted setup command copied from the app without first editing `project.yaml`.

package/README.md

@@ -180,11 +180,15 @@ After setup, use these phrases inside your AI coding tool:
 - `planning mode`
 - `review handoff`
 - `address review`
+- `docs update`
 - `close session` / `end session`
 - `docs review`
 
 The npm package owns the file mechanics. Your AI session owns reading the
-workflow files, updating handoffs, and applying reviewed changes.
+workflow files, updating handoffs, and applying reviewed changes. Use
+`docs review` for the broad baseline and scoped deepening work; use
+`docs update` / `vibecompass docs-update` for ordinary session-delta
+maintenance tied to the current lane.
 
 ## Hosted Sync
 
@@ -201,6 +205,11 @@ npx -y @vibecompass/vibecompass@latest connect-hosted \
 npx -y @vibecompass/vibecompass@latest push --root .compass
 ```
 
+After `close-session`, run `push` again when a connected local-primary root
+changed canonical project-memory files and the hosted dashboard should catch
+up. Hosted-only projects do not use a local authoritative push; update or
+refresh them through the hosted dashboard/proposal flow.
+
 ### Multiple environments
 
 One project can have named sync targets (for example a local dev server and

package/package.json

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

package/src/scaffold.js

@@ -256,7 +256,8 @@ ${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.
+- Comprehensive \`docs review\` establishes a breadth-first baseline first: inventory the project, propose a coverage plan, create compact accepted docs, and leave deferred/missing areas visible before focused deepening.
+- Before implementation work on a specific feature, inspect the relevant architecture docs, decisions, coverage/documentation-plan state if present, and source files. If the area is missing, partial, or has never been deepened enough for the build, record that gap in the lane scratch and use \`docs update\`, a focused docs-review/deepening pass, or an explicit deferral before close-out.
 - 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.
 
@@ -312,6 +313,7 @@ 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
+- after substantive feature work, confirm affected architecture docs and decisions still match the implementation; if not, update them while the context is fresh
 - 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
@@ -335,6 +337,8 @@ At session close:
 - 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
+- for local-primary roots with hosted sync configured, run \`vibecompass push --root ${rootRelativePath}\` after canonical docs/session files are finalized when the hosted dashboard should reflect the session; pass \`--sync-target <name>\` when using a non-default or named target
+- for hosted-only projects, there is no local authoritative push; confirm hosted dashboard/proposal/Understanding state was updated or record the refresh/apply work as deferred
 
 ## Reviewer workflow
 - use \`review handoff\` when you want the reviewer to run the next review pass

package/src/session.js

@@ -185,7 +185,8 @@ export async function closeProjectSession(options) {
 
   await ensureInitializedProjectMemory(normalized.rootDir, { allowMissingProjectFile: true });
   const claude = await readClaudeFile(normalized.claudePath);
-  const workflowSettings = await readWorkflowSettings(normalized.projectFilePath);
+  const projectConfig = await readProjectConfig(normalized.projectFilePath);
+  const workflowSettings = resolveWorkflowSettings(projectConfig);
   const sessionId = await resolveExistingSessionId(normalized, options);
   const lanePaths = sessionId ? getLanePaths(normalized, sessionId) : normalized;
   const documentMaintenance = normalizeDocumentMaintenanceCheckpoint(options?.documentMaintenance);
@@ -294,7 +295,10 @@ export async function closeProjectSession(options) {
     sessionNumber: activeSession.sessionNumber,
     documentMaintenance,
     docsUpdatePlan: docsUpdate.plan,
-    workflowGuidance: buildCloseSessionGuidance(workflowSettings),
+    workflowGuidance: buildCloseSessionGuidance(workflowSettings, {
+      projectConfig,
+      rootFlag: buildRootFlagForGuidance(normalized),
+    }),
     warnings: [
       ...docsUpdate.warnings,
       ...manifestRefresh.warnings,
@@ -527,16 +531,19 @@ async function ensureInitializedProjectMemory(rootDir, options = {}) {
   }
 }
 
-async function readWorkflowSettings(projectFilePath) {
+async function readProjectConfig(projectFilePath) {
   try {
     const source = await readFile(projectFilePath, 'utf8');
-    const data = parseSimpleYaml(source, { sourceName: projectFilePath });
-    return resolveWorkflowSettings(data);
+    return parseSimpleYaml(source, { sourceName: projectFilePath });
   } catch {
-    return resolveWorkflowSettings(null);
+    return null;
   }
 }
 
+function buildRootFlagForGuidance(normalized) {
+  return `--root ${toPosix(path.relative(normalized.cwd, normalized.rootDir) || '.')}`;
+}
+
 async function readClaudeFile(claudePath) {
   if (!(await fileExists(claudePath))) {
     throw new Error(

package/src/workflow.js

@@ -1,3 +1,5 @@
+import { resolveSyncBinding } from './sync-binding.js';
+
 export const DEFAULT_REVIEWER_HANDBACK = 'handoff-file';
 export const DEFAULT_GIT_REMOTE = 'origin';
 export const DEFAULT_COMMIT_TEMPLATE = 'docs(session): YYYY-MM-DD-N — <summary>';
@@ -74,8 +76,10 @@ export function buildWorkflowMetadata(existingMetadata, overrides = {}) {
   };
 }
 
-export function buildCloseSessionGuidance(workflowSettings) {
+export function buildCloseSessionGuidance(workflowSettings, options = {}) {
   const guidance = [];
+  const projectConfig = isPlainObject(options.projectConfig) ? options.projectConfig : null;
+  const rootFlag = normalizeOptionalString(options.rootFlag) ?? '--root .compass';
 
   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.');
@@ -95,9 +99,43 @@ export function buildCloseSessionGuidance(workflowSettings) {
     guidance.push(`Use commit message format: ${workflowSettings.closeSession.commitTemplate}`);
   }
 
+  guidance.push(...buildHostedProjectionGuidance(projectConfig, rootFlag));
+
   return guidance;
 }
 
+function buildHostedProjectionGuidance(projectConfig, rootFlag) {
+  if (!projectConfig) {
+    return [
+      'Hosted projection freshness could not be determined because project.yaml was unavailable; if this root is connected to hosted, push or refresh hosted state explicitly after close-session.',
+    ];
+  }
+
+  if (projectConfig.mode === 'local-primary') {
+    const binding = resolveSyncBinding(projectConfig, null);
+    if (!binding) {
+      return [
+        'Hosted projection freshness: no hosted sync binding is configured for this local-primary root, so no hosted push command is available.',
+      ];
+    }
+
+    const targetFlag = binding.target ? ` --sync-target ${binding.target}` : '';
+    return [
+      `Hosted projection freshness: after local canonical files are finalized, run \`vibecompass push ${rootFlag}${targetFlag}\` when the hosted dashboard should reflect this session.`,
+    ];
+  }
+
+  if (projectConfig.mode === 'hosted-only') {
+    return [
+      'Hosted projection freshness: this root is hosted-only, so there is no authoritative local push; confirm hosted dashboard/proposal/Understanding state was updated or record it as deferred.',
+    ];
+  }
+
+  return [
+    'Hosted projection freshness: local-only mode has no hosted push expectation unless the project is later connected with connect-hosted.',
+  ];
+}
+
 function normalizeReviewerHandback(value) {
   const normalized = normalizeOptionalString(value);
   if (!normalized) {

package/src/workflows/registry.js

@@ -106,6 +106,8 @@ When the user says \`docs review\`, run this workflow inside the current Claude
 
 Turn starter project memory into evidence-backed architecture docs under \`architecture/<domain>/<feature>/<component>.md\`, a projected coverage plan, a journey-aware project map, and optional accepted decision recommendations.
 
+The first pass is breadth-first: establish an honest project denominator, compact baseline docs, and explicit deferred or missing areas before spending tokens on deep dives. Focused deepening happens after that baseline, either because the user chooses a feature/system or because an implementation session needs better docs for a specific area.
+
 ## Steps
 
 1. Read \`${projectYamlPath}\`, \`${contextPath}\`, existing \`${architecturePath}\`, \`${decisionsPath}\`, and finalized \`${sessionsPath}\` notes.
@@ -115,14 +117,15 @@ Turn starter project memory into evidence-backed architecture docs under \`archi
    - build a subsystem-level completeness inventory of apps/repos, routes/screens, APIs, tables/storage, jobs/cron/tasks, auth/session flows, external integrations, runtime surfaces, and product features
    - distinguish product features from participating surfaces such as web, mobile, backend/API, data, jobs, integrations, and deployment/runtime
    - produce a coverage plan before reading broad source bodies
+   - classify each planned area as \`baseline\` breadth or \`deepening\` follow-up scope
    - 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, completeness inventory with accepted/deferred/missing accounting, topology, chosen taxonomy axis, prior-doc reuse/update/split/merge/defer/replace classifications, coverage plan, backbone outputs (core feature inventory, user journey map, project systems map, coverage/quality summary), proposed architecture docs, blindspots, token-budget risks, quality report, 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\`. Feature docs may include compact prose-only surface matrices; surface/platform ownership docs stay under the existing \`architecture/platform/<surface>/<component>.md\` shape rather than a new top-level systems tree. The accepted \`architecture/overview/project-shape.md\` doc should include compact backbone sections and exactly one \`vibecompass-project-map version=1\` JSON block with journey-facing features, entry points, evidence-backed relationships, and minimal optional derived \`systems[]\` metadata. Accepted local decisions may be fenced as \`vibecompass-decision-recommendation target=decisions/domain.md\` blocks without D-numbers.
+4. Present the evidence inventory, completeness inventory with accepted/deferred/missing accounting, topology, chosen taxonomy axis, prior-doc reuse/update/split/merge/defer/replace classifications, coverage plan, backbone outputs (core feature inventory, user journey map, project systems map, coverage/quality summary), proposed architecture docs, blindspots, token-budget risks, quality report, and any decision candidates before generating accepted output. At this gate, ask whether to apply the compact baseline now, adjust the plan, or spend a follow-up pass deepening specific high-risk areas. 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\` and should preserve each area's \`run_scope\` as \`baseline\` or \`deepening\`. 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\`. Feature docs may include compact prose-only surface matrices; surface/platform ownership docs stay under the existing \`architecture/platform/<surface>/<component>.md\` shape rather than a new top-level systems tree. The accepted \`architecture/overview/project-shape.md\` doc should include compact backbone sections and exactly one \`vibecompass-project-map version=1\` JSON block with journey-facing features, entry points, evidence-backed relationships, and minimal optional derived \`systems[]\` metadata. 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. 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.
+9. Run \`vibecompass status\` to confirm the docs-review marker is complete and not drifted. Report the applied architecture paths, coverage projection, baseline/deepening split, decision recommendations, parser warnings such as oversized docs or missing review metadata, and any blindspots or deepening candidates documented in the accepted docs-review output.
 
 ## Rebuild option