@vibecompass/vibecompass 0.17.1 → 0.17.3

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 0.17.3 - 2026-10-12
+
+A small sync release: `push` tells you what the hosted dashboard could not
+show. The lane brief stays opt-in (D-368).
+
+- `push` prints the server's projection warnings. The server builds the
+  dashboard in the same step as the push and reports anything it could not
+  build, such as a file whose decision links could not be read
+  (`lineage_extraction_failed`, D-371). `push` now prints each one as a
+  `Note: <code> (<path>): <message>` line after the run, so you learn about it
+  in the terminal instead of only from a dashboard notice. The push itself
+  still succeeded. A push with nothing to report prints no extra lines.
+
+## 0.17.2 - 2026-10-12
+
+Lockstep release with the app's lineage port: section headings open a fence
+only where masking does, commands leave nothing behind on an uninitialized root,
+agent files show a repo's remote beside its local path, `init` ignores lane
+scratch, and the scanner's section warnings read headings fence-aware. The
+lane brief stays opt-in (D-368).
+
+- Lineage: section headings in architecture docs and session notes now open a
+  fence only where masking does. A backtick fence's info string holds no
+  backtick, so a prose line that starts with backticks, such as
+  ```` ```a`b ````, no longer hides every later heading of the file. Before,
+  the decisions listed under a later `## Decisions made` heading were missed as
+  `made` relations, and later citations were filed under the wrong section.
+  Tilde fences may still hold backticks in their info string. A shared golden
+  fixture pair (`note-fence-opener`, `doc-fence-opener`) pins the rule for the
+  app port.
+- Commands no longer leave directories behind on an uninitialized root. A
+  write command run against a missing root (or a folder holding no project
+  memory) left an empty `state/` directory, and the root folder itself, behind
+  before it failed. The cross-process lock still serializes every command
+  there, since `bootstrap` and `apply-export` from an external bundle can
+  create a root, but at release it removes the directories it made while they
+  are still empty. Session commands report the missing root instead of a
+  missing `project.yaml`.
+- Agent files and `context.md` show a Git repo's remote when `project.yaml` also
+  records its local `path:`, as `<remote> (local path <path>)`. Before, any repo
+  with a path read as a local folder. Local-folder sources and repos without a
+  path read as before; run `vibecompass sync-agents` to refresh managed blocks.
+- `init` adds `sessions/active/` to the root's `.gitignore` beside `state/`, so
+  a versioned memory root never commits local-only lane scratch (D-278). It
+  appends only the entries a `.gitignore` lacks. An existing root's
+  `.gitignore` is not changed; add the line yourself.
+- Scanner: the recommended-section warnings for architecture docs and session
+  notes ignore headings inside fenced code, with the read model's fence-aware
+  reader. A fenced example `## Description` no longer hides a missing real
+  section.
+
 ## 0.17.1 - 2026-10-07
 
 Hardening release: decision lineage fails soft, the read model reads sections

package/README.md

@@ -230,6 +230,9 @@ npx -y @vibecompass/vibecompass@latest docs-review --root .compass --rebuild --a
 
 Docs review writes derived state under `state/`, including scanned source
 inventory, accepted coverage, and the accepted documentation-plan projection.
+`init` adds `state/` and `sessions/active/` (local-only lane scratch) to the
+root's `.gitignore`. A command that fails in a folder that is not a project
+memory root yet leaves nothing behind there.
 
 Generated agent files can also include managed VibeCompass blocks:
 
@@ -336,6 +339,11 @@ 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.
 
+`push` prints a `Note: <code> (<path>): <message>` line for anything the
+hosted dashboard could not build from your files, such as a file whose decision
+links could not be read. The push itself succeeded; the note names the file so
+you can check it.
+
 ### Where the token lives (D-355)
 
 Hosted commands look for the token in this order:

package/package.json

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

package/src/cli.js

@@ -74,9 +74,9 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     }
     io.stdout.write(`Wrote ${result.projectFilePath}\n`);
     if (result.gitignoreUpdated) {
-      io.stdout.write(`Updated ${result.gitignorePath} to ignore state/\n`);
+      io.stdout.write(`Updated ${result.gitignorePath} to ignore state/ and sessions/active/\n`);
     } else {
-      io.stdout.write(`${result.gitignorePath} already ignored state/\n`);
+      io.stdout.write(`${result.gitignorePath} already ignored state/ and sessions/active/\n`);
     }
     io.stdout.write(
       `Generated ${result.manifestPath} (${result.manifest.canonical.document_count} canonical docs, ${result.manifest.canonical.warning_count} warnings)\n`,
@@ -619,6 +619,10 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     if (result.staleProposalIds.length > 0) {
       io.stdout.write(`Stale proposals: ${result.staleProposalIds.join(', ')}\n`);
     }
+    for (const warning of result.warnings) {
+      const where = warning.path ? ` (${warning.path})` : '';
+      io.stdout.write(`Note: ${warning.code}${where}: ${warning.message}\n`);
+    }
     io.stdout.write(`Recorded ${result.manifestPath}\n`);
     io.stdout.write(`${result.message}\n`);
     return 0;

package/src/decision-lineage.js

@@ -1577,7 +1577,7 @@ export function findFencedRanges(text) {
       }
       continue;
     }
-    if (marker && !(marker[1][0] === '`' && line.slice(line.indexOf(marker[1]) + marker[1].length).includes('`'))) {
+    if (opensFence(marker, line)) {
       fence = { char: marker[1][0], length: marker[1].length, start: lineStart };
     }
   }
@@ -1585,6 +1585,13 @@ export function findFencedRanges(text) {
   return ranges;
 }
 
+// A fence opens on three or more backticks or tildes indented at most three
+// spaces; a backtick opener's info string holds no backtick, so ```a`b is
+// prose. Shared by masking and the section index.
+function opensFence(marker, line) {
+  return Boolean(marker) && !(marker[1][0] === '`' && line.slice(line.indexOf(marker[1]) + marker[1].length).includes('`'));
+}
+
 // A closing fence holds only the opener's character, at least as many times,
 // so ```~~~ never closes. Shared by masking and the section index.
 function closesFence(fence, marker, line) {
@@ -1686,7 +1693,7 @@ function buildSectionIndex(content, bodyStart) {
       }
       continue;
     }
-    if (fenceMatch) {
+    if (opensFence(fenceMatch, line)) {
       fence = { char: fenceMatch[1][0], length: fenceMatch[1].length };
       continue;
     }

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

@@ -88,13 +88,15 @@ function renderProjectSnapshot(context) {
   return lines.length > 0 ? lines : ['- No project details recorded yet.'];
 }
 
+// A local-folder source shows its folder; a Git repo shows its remote, plus
+// the local path where one is recorded beside it (PC2).
 function formatRepoDescriptor(repo) {
-  if (repo?.source === 'local' || repo?.path) {
+  if (repo?.source === 'local' || (repo?.path && !repo?.remote)) {
     return `local folder ${repo.path ?? '.'}`;
   }
 
   if (repo?.remote) {
-    return repo.remote;
+    return repo.path ? `${repo.remote} (local path ${repo.path})` : repo.remote;
   }
 
   return 'source not recorded';

package/src/init.js

@@ -34,7 +34,7 @@ export async function initializeProjectMemory(options) {
   const gitignorePath = path.join(normalized.rootDir, '.gitignore');
 
   await writeProjectFile(projectFilePath, normalized.projectConfig, normalized.force);
-  const gitignoreUpdated = await ensureStateIgnored(gitignorePath);
+  const gitignoreUpdated = await ensureLocalOnlyPathsIgnored(gitignorePath);
   const scaffoldResult = await scaffoldInitFiles(normalized.bootstrap);
   const manifestResult = await writeStateManifest(normalized.rootDir, {
     generatedAt: normalized.generatedAt,
@@ -461,22 +461,25 @@ async function writeProjectFile(projectFilePath, projectConfig, force) {
   await writeFile(projectFilePath, source, 'utf8');
 }
 
-async function ensureStateIgnored(gitignorePath) {
-  const stateEntry = 'state/';
+// Local-only paths a versioned memory root never commits: derived state, and
+// lane scratch under sessions/active/ (D-278; PC5).
+const LOCAL_ONLY_IGNORE_ENTRIES = ['state/', 'sessions/active/'];
 
+async function ensureLocalOnlyPathsIgnored(gitignorePath) {
   if (!(await fileExists(gitignorePath))) {
-    await writeFile(gitignorePath, `${stateEntry}\n`, 'utf8');
+    await writeFile(gitignorePath, `${LOCAL_ONLY_IGNORE_ENTRIES.join('\n')}\n`, 'utf8');
     return true;
   }
 
   const current = await readFile(gitignorePath, 'utf8');
   const entries = current.split(/\r?\n/).map((line) => line.trim());
-  if (entries.includes(stateEntry)) {
+  const missing = LOCAL_ONLY_IGNORE_ENTRIES.filter((entry) => !entries.includes(entry));
+  if (missing.length === 0) {
     return false;
   }
 
   const separator = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
-  await writeFile(gitignorePath, `${current}${separator}${stateEntry}\n`, 'utf8');
+  await writeFile(gitignorePath, `${current}${separator}${missing.join('\n')}\n`, 'utf8');
   return true;
 }
 

package/src/markdown-sections.js

@@ -2,7 +2,7 @@
  * The one markdown section reader shared by the read model's component fields
  * (D-372) and the session brief (D-359): fence-aware, first section of a title
  * wins. The lineage extractor keeps its own section index
- * (`decision-lineage.js`), whose fence opener differs (`decision-lineage.md`).
+ * (`decision-lineage.js`), which follows the same opening and closing rules.
  */
 
 /**

package/src/project-memory.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { validateBriefSettings } from './brief-settings.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { sha256Text } from './hash.js';
+import { splitSections } from './markdown-sections.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 
 const PROJECT_FILE = 'project.yaml';
@@ -886,12 +887,11 @@ function findDuplicateDecisionErrors(documents) {
   return errors;
 }
 
+// Level-2 section titles, lowercased, read fence-aware with the section reader
+// the read model and the brief share (D-372; H10): a heading inside fenced
+// code is an example, so it never satisfies a recommended section.
 function extractLevelTwoSections(content) {
-  const sections = new Set();
-  for (const match of content.matchAll(/^##\s+(.+)$/gm)) {
-    sections.add(match[1].trim().toLowerCase());
-  }
-  return sections;
+  return new Set([...splitSections(content, 2).keys()].map((title) => title.trim().toLowerCase()));
 }
 
 // D-292 changelog-shape detector, shared by the scanner and the docs-review

package/src/scaffold.js

@@ -503,12 +503,18 @@ ${repoLines}
 `;
 }
 
+// A local-folder source shows its folder; a Git repo shows its remote, plus
+// the local path where one is recorded beside it (PC2).
 function formatRepoDescriptor(repo) {
-  if (repo.source === 'local' || repo.path) {
+  if (repo.source === 'local' || (repo.path && !repo.remote)) {
     return `local folder ${repo.path}`;
   }
 
-  return repo.remote ?? 'source not recorded';
+  if (repo.remote) {
+    return repo.path ? `${repo.remote} (local path ${repo.path})` : repo.remote;
+  }
+
+  return 'source not recorded';
 }
 
 function generateArchitectureGuide(projectConfig) {

package/src/serialization.js

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, realpath, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 /**
@@ -16,6 +16,15 @@ import path from 'node:path';
  *   re-enter instead of deadlocking (e.g. close-session refreshing the
  *   manifest, which is itself lock-wrapped)
  *
+ * Every command takes the disk lock, on an uninitialized root too: a locked
+ * command can create a root there (bootstrap, or apply-export from an external
+ * bundle), so skipping the lock would let two of them validate the same
+ * missing files and both write. The lock leaves nothing behind (PC1): at
+ * release it removes the directories it created to hold itself (state/, and
+ * the root when it was missing) while they are still empty, and a root the
+ * lock created still counts as missing to the command
+ * (`memoryRootCreatedByLock`).
+ *
  * This tier is intentionally local-only. Cross-machine serialization belongs
  * to git merge (local-primary teams) or the hosted database (hosted-only);
  * no distributed locking is ever built on top of this file.
@@ -28,6 +37,7 @@ const DEFAULT_ATTEMPTS = 120;
 const RETRY_BASE_DELAY_MS = 25;
 const RETRY_MAX_DELAY_MS = 100;
 
+// Held root key -> { createdRoot }: whether this lock made the root directory.
 const heldRoots = new AsyncLocalStorage();
 const processQueues = new Map();
 
@@ -88,13 +98,14 @@ export async function withMemoryRootLock(rootDir, label, fn, options = {}) {
   await previous;
 
   try {
-    const ownerToken = await acquireDiskLock(key, label, options);
+    const lock = await acquireDiskLock(key, label, options);
     try {
-      const nextHeld = new Set(held ?? []);
-      nextHeld.add(key);
+      const nextHeld = new Map(held ?? []);
+      nextHeld.set(key, { createdRoot: lock.createdRoot });
       return await heldRoots.run(nextHeld, fn);
     } finally {
-      await releaseDiskLock(key, ownerToken);
+      await releaseDiskLock(key, lock.ownerToken);
+      await removeLockCreatedDirectories(key, lock.created);
     }
   } finally {
     releaseQueue();
@@ -104,6 +115,57 @@ export async function withMemoryRootLock(rootDir, label, fn, options = {}) {
   }
 }
 
+/**
+ * Whether `rootDir` exists only because the lock this caller holds made it
+ * (PC1): the root was missing when the command started and still holds
+ * nothing but the lock, so a command that requires an existing root reports
+ * it missing instead of reading the lock's own directory as one. Once the
+ * command writes into it (bootstrap), it is a root in its own right. False
+ * outside a lock holder.
+ */
+export async function memoryRootCreatedByLock(rootDir) {
+  const held = heldRoots.getStore();
+  if (!held) {
+    return false;
+  }
+  const heldKey = await findHeldMemoryRootKey(held, await canonicalizeMemoryRootKey(rootDir));
+  if (!heldKey || !held.get(heldKey).createdRoot) {
+    return false;
+  }
+  try {
+    const rootEntries = await readdir(heldKey);
+    const stateEntries = await readdir(path.dirname(memoryRootLockPath(heldKey)));
+    return rootEntries.every((entry) => entry === 'state') && stateEntries.every((entry) => entry.startsWith(LOCK_DIR_NAME));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Removes the directories acquisition created (state/, then the root and any
+ * missing parents up to `created`) while each is still empty (PC1). A command
+ * that wrote memory there, or another holder's lock, keeps a directory
+ * non-empty, so it stays. Two commands racing on the same missing root can
+ * leave an empty directory when the second found it already made; it never
+ * holds memory.
+ */
+async function removeLockCreatedDirectories(key, created) {
+  if (!created) {
+    return;
+  }
+  const top = path.resolve(created);
+  for (let dir = path.dirname(memoryRootLockPath(key)); ; dir = path.dirname(dir)) {
+    try {
+      await rmdir(dir);
+    } catch {
+      return;
+    }
+    if (dir === top || path.dirname(dir) === dir) {
+      return;
+    }
+  }
+}
+
 async function canonicalizeMemoryRootKey(rootDir) {
   const resolved = path.resolve(rootDir);
   try {
@@ -126,7 +188,7 @@ async function findHeldMemoryRootKey(held, key) {
     return key;
   }
 
-  for (const heldKey of held) {
+  for (const heldKey of held.keys()) {
     if (await memoryRootKeysReferToSamePath(heldKey, key)) {
       return heldKey;
     }
@@ -145,9 +207,11 @@ async function memoryRootKeysReferToSamePath(left, right) {
 
 async function acquireDiskLock(key, label, options) {
   const lockDir = memoryRootLockPath(key);
+  const stateDir = path.dirname(lockDir);
   const attempts = options.attempts ?? DEFAULT_ATTEMPTS;
   const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
-  await mkdir(path.dirname(lockDir), { recursive: true });
+  // The topmost directory this acquisition created, if any (mkdir reports it).
+  let created = await mkdir(stateDir, { recursive: true });
 
   for (let attempt = 1; ; attempt += 1) {
     const ownerToken = randomUUID();
@@ -158,9 +222,17 @@ async function acquireDiskLock(key, label, options) {
         `${JSON.stringify({ pid: process.pid, token: ownerToken, label, acquired_at: new Date().toISOString() })}\n`,
         'utf8',
       );
-      return ownerToken;
+      return {
+        ownerToken,
+        created,
+        createdRoot: Boolean(created) && path.resolve(created) !== path.resolve(stateDir),
+      };
     } catch (error) {
-      if (error?.code !== 'EEXIST') {
+      if (error?.code === 'ENOENT') {
+        // A releasing holder removed the state/ (or root) it had created; make
+        // it again, and remove it at release in turn.
+        created = topmostDirectory(created, await mkdir(stateDir, { recursive: true }));
+      } else if (error?.code !== 'EEXIST') {
         throw error;
       }
     }
@@ -186,6 +258,13 @@ async function acquireDiskLock(key, label, options) {
   }
 }
 
+function topmostDirectory(left, right) {
+  if (!left || !right) {
+    return left ?? right;
+  }
+  return path.resolve(left).length <= path.resolve(right).length ? left : right;
+}
+
 /**
  * A lock is abandoned only when its owner process is provably gone (dead PID),
  * or the owner file never became readable within the grace window (a crash

package/src/session.js

@@ -16,7 +16,7 @@ import {
   removeLaneWorktreesAtClose,
   rollbackGitBinding,
 } from './git-binding.js';
-import { withMemoryRootLock } from './serialization.js';
+import { memoryRootCreatedByLock, withMemoryRootLock } from './serialization.js';
 import { findDuplicateDecisionIds, formatDecisionId } from './decisions.js';
 import {
   assignLanePort,
@@ -1782,7 +1782,9 @@ function getLanePaths(normalized, sessionId) {
 }
 
 async function ensureInitializedProjectMemory(rootDir, options = {}) {
-  if (!(await fileExists(rootDir))) {
+  // The lock makes a missing root to hold its state/ and removes it again at
+  // release (PC1), so a root it created is still missing here.
+  if (!(await fileExists(rootDir)) || (await memoryRootCreatedByLock(rootDir))) {
     throw new Error(
       `No project memory root was found at ${rootDir}. Run "vibecompass init" before using session commands.`,
     );

package/src/sync.js

@@ -56,10 +56,32 @@ export async function pushProjectMemory(options = {}, environment = {}) {
     remoteRevisionId: response.remote_revision_id,
     appliedProposalIds: response.applied_proposal_ids ?? [],
     staleProposalIds: response.stale_proposal_ids ?? [],
+    warnings: readProjectionWarnings(response),
     message: `Pushed ${documents.length} canonical document${documents.length === 1 ? '' : 's'} to hosted project memory.`,
   };
 }
 
+/**
+ * The hosted push projects the dashboard read model in the same transaction
+ * (D-239) and reports what it could not project as `projection.warnings`
+ * (`{ code, message, path? }`), such as `lineage_extraction_failed` (D-371).
+ * The push itself succeeded, so these are notes, not errors. A server that
+ * sends no projection block, or an entry without a message, yields nothing.
+ */
+function readProjectionWarnings(response) {
+  const warnings = response?.projection?.warnings;
+  if (!Array.isArray(warnings)) {
+    return [];
+  }
+  return warnings
+    .filter((warning) => warning && typeof warning === 'object' && typeof warning.message === 'string')
+    .map((warning) => ({
+      code: typeof warning.code === 'string' && warning.code ? warning.code : 'projection_warning',
+      message: warning.message,
+      ...(typeof warning.path === 'string' && warning.path ? { path: warning.path } : {}),
+    }));
+}
+
 export async function pullPreviewProjectMemory(options = {}, environment = {}) {
   const context = await loadSyncContext(options, environment);
   const existingManifest = await readJsonIfPresent(context.manifestPath);