@vibecompass/vibecompass 0.10.7 → 0.11.0

package/src/simple-yaml.js

@@ -1,4 +1,15 @@
 const KEY_VALUE_PATTERN = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:(?:\s+(.*)|\s*)$/;
+const SAFE_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+/**
+ * Whether a value can appear as a block-map key in this subset. Writers that
+ * derive map keys from user-supplied identifiers (e.g. repo ids in lane
+ * metadata) must check this and fail closed instead of emitting a key the
+ * parser will reject — a parse throw degrades the whole document for readers.
+ */
+export function isSimpleYamlKeySafe(value) {
+  return typeof value === 'string' && SAFE_KEY_PATTERN.test(value);
+}
 
 export function parseSimpleYaml(source, options = {}) {
   // This intentionally supports only the YAML subset used by project.yaml and
@@ -208,10 +219,19 @@ function parseScalar(rawValue) {
     return Number(rawValue);
   }
 
-  if (
-    (rawValue.startsWith('"') && rawValue.endsWith('"')) ||
-    (rawValue.startsWith("'") && rawValue.endsWith("'"))
-  ) {
+  if (rawValue.startsWith('"') && rawValue.endsWith('"')) {
+    // Writers quote free-text values with JSON.stringify; parse the token
+    // back symmetrically so escaped quotes and backslashes (e.g. Windows
+    // paths) round-trip. Hand-authored quoting that is not valid JSON keeps
+    // the historical naive slice so legacy files stay readable.
+    try {
+      return JSON.parse(rawValue);
+    } catch {
+      return rawValue.slice(1, -1);
+    }
+  }
+
+  if (rawValue.startsWith("'") && rawValue.endsWith("'")) {
     return rawValue.slice(1, -1);
   }
 

package/src/status.js

@@ -2,17 +2,21 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { inspectProjectCompatibility } from './compatibility.js';
 import { sha256Text } from './hash.js';
+import { resolveLaneMarkerContext } from './lane-marker.js';
 import { parseSimpleYaml } from './simple-yaml.js';
-import { listProjectSessions } from './session.js';
+import { inferToolingRootForMemoryRoot, listProjectSessions } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
 import { scanProjectMemory } from './project-memory.js';
 
 export async function getProjectStatus(options = {}) {
   const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
-  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  const rootContext = await resolveStatusRootContext(cwd, options.rootDir);
+  const rootDir = rootContext.rootDir;
   const toolingRootDir = options.toolingRootDir
     ? path.resolve(cwd, options.toolingRootDir)
-    : cwd;
+    : rootContext.rootSource === 'marker'
+      ? await inferToolingRootForMemoryRoot(rootDir)
+      : cwd;
 
   const compatibility = await inspectProjectCompatibility({
     rootDir,
@@ -36,7 +40,15 @@ export async function getProjectStatus(options = {}) {
       cliPackageVersion: compatibility.cliPackageVersion,
       package: compatibility.package,
       state: compatibility.state,
-      warnings: compatibility.warnings,
+      warnings: [
+        ...(rootContext.markerError
+          ? [{
+              code: 'lane-marker-unreadable',
+              message: `A lane marker near ${cwd} could not be resolved (${rootContext.markerError}); reporting on ${rootDir} instead. Lane-scoped commands will fail closed on it.`,
+            }]
+          : []),
+        ...compatibility.warnings,
+      ],
     },
     sessions,
     docsReview,
@@ -53,6 +65,30 @@ export async function getProjectStatus(options = {}) {
   };
 }
 
+/**
+ * D-280: status adopts the nearest valid marker's memory root when --root is
+ * omitted, matching lane-scoped commands, so `status` from a worktree cwd
+ * reports the bound root instead of a nonexistent `cwd/.compass`. Status is
+ * read-only and must not fail on a corrupt or foreign marker — resolution
+ * failures fall back to the cwd default.
+ */
+async function resolveStatusRootContext(cwd, explicitRootDir) {
+  if (explicitRootDir) {
+    return { rootDir: path.resolve(cwd, explicitRootDir), rootSource: 'flag', markerError: null };
+  }
+
+  try {
+    const context = await resolveLaneMarkerContext({ cwd });
+    return { rootDir: context.rootDir, rootSource: context.rootSource, markerError: null };
+  } catch (error) {
+    return {
+      rootDir: path.resolve(cwd, '.compass'),
+      rootSource: 'default',
+      markerError: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
 export function renderStatusText(status) {
   if (status.project.status === 'unreadable') {
     return [
@@ -375,7 +411,9 @@ function buildRecommendations({ project, compatibility, sessions, docsReview, ag
     recommendations.push(
       sessions.status === 'ok' && sessions.current
         ? `vibecompass docs-update --session ${sessions.current}`
-        : 'vibecompass docs-review --guided',
+        : sessions.status === 'ok' && sessions.lanes.length >= 2
+          ? 'vibecompass list-sessions'
+          : 'vibecompass docs-review --guided',
     );
   }
 

package/src/sync.js

@@ -2,6 +2,7 @@ import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { sha256Text } from './hash.js';
 import { writeStateManifest } from './manifest.js';
+import { withMemoryRootLock } from './serialization.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import {
   buildSyncStateWithCursor,
@@ -143,6 +144,10 @@ export async function pullExportProjectMemory(options = {}, environment = {}) {
 export async function applyPullExport(options = {}, environment = {}) {
   const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
   const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  return withMemoryRootLock(rootDir, 'apply-export', () => applyPullExportLocked(options, rootDir));
+}
+
+async function applyPullExportLocked(options, rootDir) {
   const outputPath = path.resolve(rootDir, options.outputPath ?? DEFAULT_EXPORT_PATH);
   const bundle = await readJsonRequired(outputPath, 'pull-export bundle');
   const operations = Array.isArray(bundle.operations) ? bundle.operations : [];

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

@@ -10,7 +10,7 @@ export const WORKFLOW_REGISTRY = [
       { 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: 'review handoff', summary: 'reviewer reads the selected lane handoff and appends findings; with multiple active lanes name the lane explicitly: `review handoff <lane-id>`' },
       { trigger: 'address review', summary: 'builder critically resolves reviewer feedback from the selected lane scratch files' },
       { trigger: 'docs update', summary: 'builder runs a targeted session-delta documentation maintenance plan with `vibecompass docs-update --session <lane-id>`' },
       { trigger: 'close session', summary: 'builder runs the close-out checklist and ends with `vibecompass close-session --session <lane-id>` plus required document-maintenance checkpoint statuses; `end session` and `vibecompass end-session` are accepted aliases' },
@@ -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