@vibecompass/vibecompass 0.17.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.17.1 - 2026-10-07
+
+Hardening release: decision lineage fails soft, the read model reads sections
+fence-aware, and close-session no longer leaves half-deleted worktrees. The lane
+brief stays opt-in (D-368).
+
+- Lineage fails soft (D-371): when the lineage parser throws on a file, the read
+  model still loads and `decision_lineage.status` is `unavailable`, listing the
+  file in `unavailable_sources` with a `lineage-extraction-failed` diagnostic
+  (the error's class and first line, at most 200 characters). Relations, counts,
+  and `getDecisionLineage`'s lists are null, never empty. `getProjectContext`
+  gains a `decision_lineage` status, so Local MCP's project context shows it.
+  Before, one parser exception failed the whole read model: the brief, every
+  Local MCP read, and agent-file sync. Available lineage is unchanged, with the
+  same relation records and contract version 1.
+- Brief: with lineage unavailable, the brief abstains. It is `incomplete`, shows
+  the lane only, and lists the file lineage could not be read from, the
+  overview, and `decisions/INDEX.md` as required reads. A lane `brief.md`
+  written then records a failed generation, so `continue-session` regenerates
+  it.
+- Read model (D-372): architecture component sections (Description, Details,
+  Next steps, Retrieval guidance, Review metadata, Involved files) are read
+  fence-aware, and the first section of a title wins. A heading inside a fenced
+  example no longer replaces the real section (for example a sample
+  `## Description` in a schema doc). It is the brief's reader, now shared.
+- Lineage: section headings in architecture docs and session notes now follow
+  the closing-fence rule that 0.17.0 gave masking. A fence closes only on a
+  line of its opener's own character, so a mixed line such as ```` ```~~~ ````
+  no longer ends an example early. In 0.17.0 a sample `## Decisions made`
+  heading after such a line could be taken as the note's listing, making a
+  false `made` relation and missing the real ones, and later real headings
+  could be read as fenced. A shared golden fixture pair
+  (`decisions-fence-closing`, `note-fence-closing`) pins the rule for the app
+  port.
+- close-session: git removes a lane's worktrees with no time limit. A removal
+  killed by the 120-second limit while deleting a full `node_modules` left a
+  half-deleted checkout that the next close counted as modified. Git still
+  refuses locked worktrees, worktrees with submodules, and modified ones before
+  it deletes anything.
+- Tests: the lane-runtime settings test passes inside a `lane-env` shell.
+
+Not listed in 0.17.0's notes, though it shipped there: masking and decision
+entry structure closed a fence only on a line of its opener's own character,
+so a sample `**Supersedes:**` line after a mixed ```` ```~~~ ```` line no longer
+declared false lineage.
+
 ## 0.17.0 - 2026-10-03
 
 Session brief retrieval and framing fixes (recall plan A7). The lane brief stays

package/README.md

@@ -162,7 +162,9 @@ npx -y @vibecompass/vibecompass@latest brief --root .compass --session auth-flow
 # (guarded, never forced; branches are never deleted); dirty or in-use
 # worktrees survive with guidance and the lane marker stays as a breadcrumb.
 # Gitignored files (e.g. .env) do not count as dirty and are deleted with a
-# clean worktree — copy ignored local files out before closing.
+# clean worktree — copy ignored local files out before closing. Git does the
+# removal with no time limit, so a large node_modules can take a while; it
+# keeps locked worktrees and worktrees with submodules.
 # close-session and docs-update also print a pre-close staleness set: new
 # decisions since lane start, stale base revisions, newer finalized notes
 # that mention the lane's scope, and claim overlap with other active lanes.
@@ -268,7 +270,9 @@ own text explicitly declares that it replaces or amends it, and the brief never
 claims that a decision governs your task. It cannot spot a replacement that is
 only implied, so read the follow-up list too. When the task's distinctive words
 match nothing in memory, the status is `no-match`, with at most four nearby
-reads that share the task's other words.
+reads that share the task's other words. If decision lineage cannot be read
+from a file, the brief shows no decisions or docs: it is `incomplete` and lists
+that file, the overview, and the decision index to read first.
 
 The brief in a session lane is an experiment you turn on (D-368):
 
@@ -416,8 +420,13 @@ the parser cannot certify is `unknown`. Every relation carries its source
 path, section, line, and content hashes. `getDecisionLineage(readModel, id)`
 returns one decision's incoming and outgoing lineage and its declared
 successors, followed transitively. Nothing is ever reported as "governs" or
-"currently valid". Architecture components also carry `retrieval_guidance`
-and `retrieval_scope` when their docs define them.
+"currently valid". If the parser throws on any file, `decision_lineage.status`
+is `unavailable`, with the file in `unavailable_sources` and null relations
+and counts, never empty ones; the rest of the read model still loads, and
+`getProjectContext` reports the lineage status. Architecture components also
+carry `retrieval_guidance` and `retrieval_scope` when their docs define them;
+their sections are read fence-aware, so a heading inside a code example never
+replaces a real section.
 
 `buildSessionBrief({ rootDir, task, files, featureSlugs, claims, laneId, budget })`
 is the read-only engine behind `vibecompass brief`: it returns the selection

package/package.json

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

package/src/brief.js

@@ -6,6 +6,7 @@ import { compileBriefExclusions, readBriefSettingsForRoot, validateExcludePatter
 import { collectDeclaredSuccessors, parseDecisionEntries, scanDecisionReferences } from './decision-lineage.js';
 import { sha256Text, stableStringify } from './hash.js';
 import { resolveLaneMarkerContext, resolveLaneSelection, validateLaneId } from './lane-marker.js';
+import { extractSection, splitSections, stepFence } from './markdown-sections.js';
 import { loadProjectReadModelWithDocuments } from './read-model.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 
@@ -119,6 +120,15 @@ export async function buildSessionBrief(options = {}) {
     }
   }
 
+  // D-371: with lineage unavailable no decision can be shown with its
+  // declared successors (D-359), so the brief abstains: the lane unit only,
+  // and the sources lineage could not be read from as required reads.
+  let lineageUnavailable = [];
+  if (!retrievalError && loaded.readModel.decision_lineage.status === 'unavailable') {
+    lineageUnavailable = loaded.readModel.decision_lineage.unavailable_sources;
+    retrievalError = `decision lineage is unavailable (D-371): it could not be extracted from ${describePaths(lineageUnavailable.map((source) => source.path))}, so no decision can be shown with its declared successors`;
+  }
+
   const overviewExcluded = exclusions?.matches(BRIEF_OVERVIEW_PATH) ?? false;
   const overviewExists = !overviewExcluded && (await pathExists(path.join(input.rootDir, BRIEF_OVERVIEW_PATH)));
   if (!overviewExists) {
@@ -149,7 +159,7 @@ export async function buildSessionBrief(options = {}) {
   };
 
   if (retrievalError) {
-    return finalizeRetrievalFailure(context, retrievalError);
+    return finalizeRetrievalFailure(context, retrievalError, lineageUnavailable);
   }
 
   const selection = selectCandidates(context, loaded, task);
@@ -1241,8 +1251,17 @@ function buildFollowUps(selection, context, included, omitted) {
   }
   entries.push(...requiredDecisions.sort((left, right) => right.decision_id - left.decision_id));
 
-  // A failed retrieval can still point at the fixed entry points.
+  // A failed retrieval can still point at the fixed entry points, after the
+  // sources lineage could not be read from (D-371).
   if (selection.retrievalError) {
+    for (const source of selection.lineageUnavailable ?? []) {
+      entries.push({
+        priority: 'required',
+        path: source.path,
+        heading: null,
+        reason: 'decision lineage could not be extracted from this file (D-371); read it directly',
+      });
+    }
     if (context.overview.exists) {
       entries.push({ priority: 'required', path: BRIEF_OVERVIEW_PATH, heading: null, reason: 'whole-project orientation' });
     }
@@ -1328,8 +1347,14 @@ function lineageReads(unit, priority) {
     }));
 }
 
-function finalizeRetrievalFailure(context, reason) {
-  return packBrief(context, { retrievalError: reason, terms: [], distinctive: [], relations: [], nearby: [] });
+function finalizeRetrievalFailure(context, reason, lineageUnavailable = []) {
+  return packBrief(context, { retrievalError: reason, lineageUnavailable, terms: [], distinctive: [], relations: [], nearby: [] });
+}
+
+/** Up to three paths, then "+N more". */
+function describePaths(paths) {
+  const shown = paths.slice(0, 3).map((value) => `\`${value}\``);
+  return paths.length > 3 ? `${shown.join(', ')} and ${paths.length - 3} more` : shown.join(', ');
 }
 
 /**
@@ -1379,31 +1404,6 @@ function buildDecisionAnchors(documents, decisionIds) {
   return new Map([...anchors].map(([id, sentences]) => [id, [...sentences].join('\n')]));
 }
 
-/**
- * One line of fenced-code tracking, with the rules of `findFencedRanges` in
- * `decision-lineage.js`. A fence opens on three or more backticks or tildes
- * indented at most three spaces; a backtick fence's info string has no
- * backtick. It closes only on a line holding the same character at least as
- * many times and nothing else (no other character, so ```~~~ never closes), so
- * a ``` line inside a ```` example stays code.
- */
-function stepFence(fence, line) {
-  const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
-  if (fence) {
-    const closes = marker && marker[1][0] === fence.char && marker[1].length >= fence.length && closingFence(fence.char).test(line);
-    return { fence: closes ? null : fence, delimiter: Boolean(closes) };
-  }
-  if (marker && !(marker[1][0] === '`' && line.slice(line.indexOf(marker[1]) + marker[1].length).includes('`'))) {
-    return { fence: { char: marker[1][0], length: marker[1].length }, delimiter: true };
-  }
-  return { fence: null, delimiter: false };
-}
-
-/** A closing fence line: only the opener's character (three or more), then whitespace — never mixed delimiters. */
-function closingFence(char) {
-  return char === '`' ? /^ {0,3}`{3,}\s*$/ : /^ {0,3}~{3,}\s*$/;
-}
-
 /** Paragraphs, list items, and table rows of a markdown body with their level-2 section, fence-aware. */
 function markdownBlocks(content) {
   const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/, '');
@@ -1583,39 +1583,6 @@ function docSectionFields(content, component) {
   };
 }
 
-/**
- * Level-2 sections of a markdown body, fence-aware: headings inside fenced
- * code are content, and the first section with a given title wins (docs such
- * as `file-schema.md` show example `## Description` blocks in fences).
- */
-function splitSections(content, level = 2) {
-  const sections = new Map();
-  if (!content) return sections;
-  const lines = content.split(/\r?\n/);
-  const heading = new RegExp(`^#{1,${level}}\\s`);
-  const exact = new RegExp(`^#{${level}}\\s+(.+?)\\s*$`);
-  let fence = null;
-  let current = null;
-  for (const line of lines) {
-    const step = stepFence(fence, line);
-    const fenced = fence !== null || step.delimiter;
-    fence = step.fence;
-    if (!fenced && heading.test(line)) {
-      const match = line.match(exact);
-      current = match && !sections.has(match[1]) ? { title: match[1], lines: [] } : null;
-      if (current) sections.set(current.title, current);
-      continue;
-    }
-    if (current) current.lines.push(line);
-  }
-  return new Map([...sections].map(([title, section]) => [title, section.lines.join('\n').trim() || null]));
-}
-
-/** Body of a level-2 section (`## Title`), trimmed; null when absent. */
-export function extractSection(content, title) {
-  return splitSections(content, 2).get(title) ?? null;
-}
-
 /** Body of `### sub` inside `## section`; null when absent. */
 function extractSubsection(content, section, sub) {
   return splitSections(extractSection(content, section), 3).get(sub) ?? null;

package/src/decision-lineage.js

@@ -309,30 +309,37 @@ export function extractDecisionFileRelations({ path, content }) {
 /**
  * Builds the corpus-wide lineage view over scanned canonical documents
  * (`{ path, kind, content }`): every relation plus `target_exists`, the
- * diagnostics, and per-relation counts.
+ * diagnostics, and per-relation counts, with `status: 'available'`.
+ *
+ * D-371: each lineage source is extracted inside its own guard, which holds
+ * only that source's pure extraction (entry parse and relation extraction;
+ * no I/O). When any source throws, lineage is unavailable as a whole — a
+ * missing decision file can hide a declared successor of any decision — so
+ * the model carries `status: 'unavailable'`, the failed sources, and their
+ * `lineage-extraction-failed` diagnostics, with null relations and counts.
+ * Unavailable lineage is never returned as empty lineage.
  */
 export function buildDecisionLineageModel(documents) {
   const knownIds = new Set();
-  for (const document of documents) {
-    if (document.kind !== 'decision') continue;
-    for (const entry of parseDecisionEntries(document.content)) knownIds.add(entry.decision_id);
-  }
-
   const relations = [];
   const diagnostics = [];
+  const failures = [];
   for (const document of documents) {
-    const extractor =
-      document.kind === 'architecture'
-        ? extractArchitectureDocCitations
-        : document.kind === 'session'
-          ? extractSessionNoteRelations
-          : document.kind === 'decision'
-            ? extractDecisionFileRelations
-            : null;
-    if (!extractor) continue;
-    const result = extractor({ path: document.path, content: document.content });
-    relations.push(...result.relations);
-    diagnostics.push(...result.diagnostics);
+    if (!LINEAGE_SOURCE_KINDS.has(document.kind)) continue;
+    let extracted;
+    try {
+      extracted = extractLineageSource(document);
+    } catch (error) {
+      failures.push({ path: document.path, kind: document.kind, error: describeExtractionError(error) });
+      continue;
+    }
+    for (const id of extracted.decisionIds) knownIds.add(id);
+    relations.push(...extracted.relations);
+    diagnostics.push(...extracted.diagnostics);
+  }
+
+  if (failures.length > 0) {
+    return buildUnavailableLineageModel(failures);
   }
 
   const unresolved = new Set();
@@ -356,13 +363,101 @@ export function buildDecisionLineageModel(documents) {
 
   return {
     contract_version: DECISION_LINEAGE_CONTRACT_VERSION,
+    status: 'available',
     decision_count: knownIds.size,
     relation_counts: relationCounts,
     relations: sortRelations(withExistence),
+    unavailable_sources: [],
     diagnostics: sortDiagnostics(diagnostics),
   };
 }
 
+function buildUnavailableLineageModel(failures) {
+  const sources = [...failures].sort((left, right) => left.path.localeCompare(right.path));
+  return {
+    contract_version: DECISION_LINEAGE_CONTRACT_VERSION,
+    status: 'unavailable',
+    decision_count: null,
+    relation_counts: null,
+    relations: null,
+    unavailable_sources: sources.map(({ path, kind, error }) => ({ path, kind, error })),
+    diagnostics: sources.map(({ path, error }) => ({
+      code: 'lineage-extraction-failed',
+      path,
+      line: null,
+      message: `Decision lineage could not be extracted from this file (${error}), so lineage is unavailable for the whole root until the file changes or the extractor is fixed.`,
+    })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Per-source extraction (D-371)
+// ---------------------------------------------------------------------------
+
+const LINEAGE_SOURCE_KINDS = new Set(['architecture', 'session', 'decision']);
+const EXTRACTION_ERROR_LIMIT = 200;
+
+/** The relations of one canonical document, by kind. */
+function extractDocumentRelations({ path, kind, content }) {
+  if (kind === 'architecture') return extractArchitectureDocCitations({ path, content });
+  if (kind === 'session') return extractSessionNoteRelations({ path, content });
+  return extractDecisionFileRelations({ path, content });
+}
+
+const DEFAULT_LINEAGE_PHASES = Object.freeze({
+  parseEntries: parseDecisionEntries,
+  extractRelations: extractDocumentRelations,
+});
+let lineagePhases = DEFAULT_LINEAGE_PHASES;
+
+/**
+ * Internal fault-injection seam for degraded-lineage tests (D-371): replaces
+ * the entry-parse and/or relation-extraction phase of per-source extraction
+ * and returns a function that restores the previous phases. It is not
+ * exported from `index.js`, so the package's `exports` map keeps it out of
+ * reach of consumers. Tests restore it in `finally`.
+ */
+export function setLineagePhasesForTesting(overrides = {}) {
+  const previous = lineagePhases;
+  lineagePhases = Object.freeze({ ...DEFAULT_LINEAGE_PHASES, ...overrides });
+  return () => {
+    lineagePhases = previous;
+  };
+}
+
+// One source's extraction: pure, synchronous, and the only code inside the
+// D-371 guard. A decision file contributes its entry IDs (known targets) and
+// its relations; a doc or note contributes relations.
+function extractLineageSource(document) {
+  const decisionIds =
+    document.kind === 'decision' ? lineagePhases.parseEntries(document.content).map((entry) => entry.decision_id) : [];
+  const result = lineagePhases.extractRelations({ path: document.path, kind: document.kind, content: document.content });
+  return { decisionIds, relations: result.relations, diagnostics: result.diagnostics };
+}
+
+/**
+ * The error class (or a thrown non-Error value's type) and the first line of
+ * its message, at most 200 code points; never a stack trace. The source path
+ * is recorded separately, so cutting this text never hides which source failed.
+ */
+function describeExtractionError(error) {
+  let text;
+  try {
+    if (error instanceof Error) {
+      const name = typeof error.name === 'string' && error.name ? error.name : 'Error';
+      const message = typeof error.message === 'string' ? error.message.split(/\r?\n/, 1)[0].trim() : '';
+      text = message ? `${name}: ${message}` : name;
+    } else {
+      const type = error === null ? 'null' : typeof error;
+      const value = typeof error === 'string' ? error.split(/\r?\n/, 1)[0].trim() : '';
+      text = value ? `thrown ${type}: ${value}` : `thrown ${type}`;
+    }
+  } catch {
+    text = 'unreadable thrown value';
+  }
+  return boundText(collapse(text), EXTRACTION_ERROR_LIMIT);
+}
+
 /**
  * Declared successors of a decision, transitively: later decisions whose own
  * text (or structured fields) declares `supersedes` or `amends` for it, and
@@ -1476,8 +1571,7 @@ export function findFencedRanges(text) {
     offset += line.length + 1;
     const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
     if (fence) {
-      // A closing fence holds only the opener's character, so ```~~~ never closes.
-      if (marker && marker[1][0] === fence.char && marker[1].length >= fence.length && (fence.char === '`' ? /^ {0,3}`+\s*$/ : /^ {0,3}~+\s*$/).test(line)) {
+      if (closesFence(fence, marker, line)) {
         ranges.push([fence.start, Math.min(offset - 1, text.length)]);
         fence = null;
       }
@@ -1491,6 +1585,13 @@ export function findFencedRanges(text) {
   return ranges;
 }
 
+// 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) {
+  return Boolean(marker) && marker[1][0] === fence.char && marker[1].length >= fence.length &&
+    (fence.char === '`' ? /^ {0,3}`+\s*$/ : /^ {0,3}~+\s*$/).test(line);
+}
+
 function insideRanges(offset, ranges) {
   return ranges.some(([start, end]) => offset >= start && offset < end);
 }
@@ -1580,7 +1681,7 @@ function buildSectionIndex(content, bodyStart) {
 
     const fenceMatch = line.match(/^ {0,3}(`{3,}|~{3,})/);
     if (fence) {
-      if (fenceMatch && fenceMatch[1][0] === fence.char && fenceMatch[1].length >= fence.length && /^ {0,3}[`~]+\s*$/.test(line)) {
+      if (closesFence(fence, fenceMatch, line)) {
         fence = null;
       }
       continue;

package/src/git-binding.js

@@ -15,6 +15,14 @@ const QUICK_GIT_TIMEOUT_MS = 5000;
 const WORKTREE_GIT_TIMEOUT_MS = 120000;
 const GIT_OUTPUT_MAX_BUFFER = 1024 * 1024;
 
+// H3: close-time removal has no kill timeout. Git is the only deleter, and it
+// makes every refusal (locked, submodules, modified or untracked files, not a
+// worktree of this repo) before it deletes anything; killing it while it
+// deletes a large tree (a full node_modules) left a half-deleted checkout that
+// the next close saw as modified. A filesystem that stalls makes close wait
+// until git finishes or the user interrupts it.
+export const WORKTREE_REMOVE_AT_CLOSE_EXEC_OPTIONS = Object.freeze({ maxBuffer: GIT_OUTPUT_MAX_BUFFER });
+
 /**
  * Repo working copies live as siblings of the memory root: the workspace is
  * `dirname(rootDir)` and a declared `repo.path` (else the repo id) resolves
@@ -396,6 +404,9 @@ export async function rollbackGitBinding(progress, branch) {
  *   container AND covered by a token-matched container marker are removable
  *   (D-279/D-280 guards — arbitrary path removal is refused)
  * - removal is never forced; a status failure counts as unknown, not clean
+ * - git is the only deleter and runs without a kill timeout (H3), so its own
+ *   refusals (lock, submodules, registration) come before any deletion and a
+ *   large ignored tree is never left half-deleted by a timer
  * - removal is skipped with guidance when the process cwd sits inside the
  *   target
  * - branches are never deleted at close
@@ -487,10 +498,16 @@ export async function removeLaneWorktreesAtClose(options) {
       await execFileAsync(
         'git',
         ['-C', sourceDir, 'worktree', 'remove', entry.worktreePath],
-        { timeout: WORKTREE_GIT_TIMEOUT_MS, maxBuffer: GIT_OUTPUT_MAX_BUFFER },
+        WORKTREE_REMOVE_AT_CLOSE_EXEC_OPTIONS,
       );
       removed.push({ repoId: entry.repoId, worktreePath: entry.worktreePath, sourceDir });
     } catch (error) {
+      if (error && typeof error === 'object' && error.signal) {
+        // No timer kills this call (H3), so a signal is an outside
+        // interruption, possibly mid-delete.
+        keep(entry, 'git-interrupted', `git was interrupted (${error.signal}) while removing it, so the checkout may be partly deleted. Inspect it before removing it.`);
+        continue;
+      }
       keep(entry, 'git-refused', `git refused the removal: ${describeGitError(error)}. Resolve that first.`);
     }
   }

package/src/markdown-sections.js

@@ -0,0 +1,65 @@
+/**
+ * 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`).
+ */
+
+/**
+ * One line of fenced-code tracking, with the rules of `findFencedRanges` in
+ * `decision-lineage.js`. A fence opens on three or more backticks or tildes
+ * indented at most three spaces; a backtick fence's info string has no
+ * backtick. It closes only on a line holding the same character at least as
+ * many times and nothing else (no other character, so ```~~~ never closes), so
+ * a ``` line inside a ```` example stays code.
+ */
+export function stepFence(fence, line) {
+  const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
+  if (fence) {
+    const closes = marker && marker[1][0] === fence.char && marker[1].length >= fence.length && closingFence(fence.char).test(line);
+    return { fence: closes ? null : fence, delimiter: Boolean(closes) };
+  }
+  if (marker && !(marker[1][0] === '`' && line.slice(line.indexOf(marker[1]) + marker[1].length).includes('`'))) {
+    return { fence: { char: marker[1][0], length: marker[1].length }, delimiter: true };
+  }
+  return { fence: null, delimiter: false };
+}
+
+/** A closing fence line: only the opener's character (three or more), then whitespace — never mixed delimiters. */
+function closingFence(char) {
+  return char === '`' ? /^ {0,3}`{3,}\s*$/ : /^ {0,3}~{3,}\s*$/;
+}
+
+/**
+ * Sections of a markdown body at `level` (default 2), fence-aware: headings
+ * inside fenced code are content, the first section with a given title wins
+ * (docs such as `file-schema.md` show example `## Description` blocks in
+ * fences), and a heading at that level or above ends the current section.
+ */
+export function splitSections(content, level = 2) {
+  const sections = new Map();
+  if (!content) return sections;
+  const lines = content.split(/\r?\n/);
+  const heading = new RegExp(`^#{1,${level}}\\s`);
+  const exact = new RegExp(`^#{${level}}\\s+(.+?)\\s*$`);
+  let fence = null;
+  let current = null;
+  for (const line of lines) {
+    const step = stepFence(fence, line);
+    const fenced = fence !== null || step.delimiter;
+    fence = step.fence;
+    if (!fenced && heading.test(line)) {
+      const match = line.match(exact);
+      current = match && !sections.has(match[1]) ? { title: match[1], lines: [] } : null;
+      if (current) sections.set(current.title, current);
+      continue;
+    }
+    if (current) current.lines.push(line);
+  }
+  return new Map([...sections].map(([title, section]) => [title, section.lines.join('\n').trim() || null]));
+}
+
+/** Body of a level-2 section (`## Title`), trimmed; null when absent. */
+export function extractSection(content, title) {
+  return splitSections(content, 2).get(title) ?? null;
+}

package/src/read-model.js

@@ -3,9 +3,9 @@ import path from 'node:path';
 import { buildDecisionLineageModel, collectDeclaredSuccessors } from './decision-lineage.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { generateStateManifest } from './manifest.js';
+import { splitSections } from './markdown-sections.js';
 import { scanProjectMemory } from './project-memory.js';
 
-const SECTION_PATTERN = /^##\s+(.+)$/gm;
 const DECISION_HEADING_PATTERN = /^###\s+D-(\d{3,})\s+—\s+(.+)$/gm;
 
 export async function loadProjectReadModel(rootDir) {
@@ -83,6 +83,12 @@ export function getProjectContext(readModel, options = {}) {
     domains: readModel.domains,
     recent_decisions: readModel.decisions.slice(0, decisionLimit),
     recent_sessions: readModel.sessions.slice(0, sessionLimit),
+    // D-371: whether decision lineage could be read, in every response, so a
+    // reader (Local MCP's project context) can tell unavailable from empty.
+    decision_lineage: {
+      status: readModel.decision_lineage.status,
+      unavailable_sources: readModel.decision_lineage.unavailable_sources,
+    },
   };
 }
 
@@ -113,7 +119,8 @@ export function getDecisionLog(readModel, options = {}) {
  * what later decisions declare about it, and `declared_successors` follows
  * declared `supersedes`/`amends` transitively. Mentions stay mentions: no
  * relation here certifies that a decision governs anything or is currently
- * valid.
+ * valid. When lineage is unavailable (D-371), `lineage_status` says so and
+ * every relation-derived value is null, never an empty list.
  */
 export function getDecisionLineage(readModel, decisionId, options = {}) {
   const id = typeof decisionId === 'number' ? decisionId : Number(String(decisionId ?? '').replace(/^D-/i, ''));
@@ -122,8 +129,27 @@ export function getDecisionLineage(readModel, decisionId, options = {}) {
   }
 
   const citationLimit = Math.max(1, Math.min(options.citationLimit ?? 50, 500));
-  const relations = readModel.decision_lineage.relations;
+  const lineage = readModel.decision_lineage;
   const decision = readModel.decisions.find((entry) => entry.decision_id === id) ?? null;
+  if (lineage.status === 'unavailable') {
+    return {
+      freshness: readModel.freshness,
+      decision_id: id,
+      exists: Boolean(decision),
+      title: decision?.title ?? null,
+      path: decision?.path ?? null,
+      lineage_status: 'unavailable',
+      unavailable_sources: lineage.unavailable_sources,
+      outgoing: null,
+      incoming: null,
+      declared_successors: null,
+      made_in: null,
+      cited_by: null,
+      cited_by_total: null,
+    };
+  }
+
+  const relations = lineage.relations;
   const lineageRelations = new Set(['supersedes', 'amends', 'preserves', 'unknown']);
   const outgoing = relations.filter(
     (relation) => relation.source_decision_id === id && lineageRelations.has(relation.relation),
@@ -142,6 +168,8 @@ export function getDecisionLineage(readModel, decisionId, options = {}) {
     exists: Boolean(decision),
     title: decision?.title ?? null,
     path: decision?.path ?? null,
+    lineage_status: 'available',
+    unavailable_sources: [],
     outgoing,
     incoming,
     declared_successors: collectDeclaredSuccessors(relations, id),
@@ -237,7 +265,9 @@ function buildFeatureMap(scanResult, repoAliases, projectRepos) {
 
 function buildComponentRecord(document, repoAliases, projectRepos) {
   const frontmatter = parseFrontmatter(document.content, { sourceName: document.path });
-  const sections = splitMarkdownSections(frontmatter.body);
+  // D-372: the brief's fence-aware reader, so a fenced example heading or a
+  // repeated title never replaces a real section.
+  const sections = splitSections(frontmatter.body, 2);
   const repoIds = uniqueSorted(document.extracted.repo_ids ?? []);
   const involvedFiles = parseInvolvedFiles({
     rawSection: sections.get('Involved files') ?? '',
@@ -418,19 +448,6 @@ function extractDecisionEntries(content, sourcePath) {
   });
 }
 
-function splitMarkdownSections(body) {
-  const sections = new Map();
-  const matches = [...body.matchAll(SECTION_PATTERN)];
-
-  for (const [index, match] of matches.entries()) {
-    const start = (match.index ?? 0) + match[0].length;
-    const end = matches[index + 1]?.index ?? body.length;
-    sections.set(match[1].trim(), body.slice(start, end).trim());
-  }
-
-  return sections;
-}
-
 function parseInvolvedFiles({ rawSection, defaultRepoIds, repoAliases, projectRepos }) {
   if (!rawSection) {
     return [];