@vibecompass/vibecompass 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # 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
+opt-in (D-368). The re-evaluation meant to decide default-on stopped at a protocol
+deviation before any run was graded, so it gives no evidence either way. These
+fixes target misses from the earlier evaluation and were checked on its tuning
+tasks with briefs alone, not in an agent evaluation.
+
+**Breaking for `vibecompass brief --json` consumers:** contract version 2 removes
+`selection.narrowed` (see below). Other commands and the read model are unchanged.
+
+- Selection: a decision is also matched on the sentences in architecture docs
+  that cite it (the overview included; Review metadata and Involved files
+  excluded), so a doc's own words reach a decision whose entry uses different
+  ones. A doc shares the keyword relevance of the decisions it cites, so a doc
+  whose Description misses the task's words is still reached through the
+  decisions it describes. Common abbreviations meet their long forms
+  (organization/org, repository/repo, configuration/config, database/db,
+  environment/env, documentation/doc, authentication/auth).
+- No-match: evaluative words ("clearer", "flaky", "noticeably") and
+  kind-of-work words ("investigate", "failure", "bug") never count as a task's
+  distinctive topic words. When the distinctive topic words are mostly unknown
+  to memory and only keywords matched, the status is `no-match` with up to four
+  nearby reads (paths that share other task words, never presented as
+  relevant). This replaces the narrow `partial` match.
+- Framing: a brief with units says it is a starting point of cut excerpts that
+  can miss the doc a task depends on, and names up to six of the task's words
+  to search for beyond it (`selection.search_terms` in `--json`).
+- Lane `brief.md` format 2: `exclude` and `repo_aliases` show at most four
+  entries, bound by `exclude_digest` and `repo_aliases_digest`, so staleness
+  checks stay complete as settings and repos grow; a header comment says the
+  token budget covers the body only. Format 1 briefs read as stale and are
+  regenerated on resume.
+- `--json` contract version 2: `selection.narrowed` is replaced by
+  `selection.topic_absent` and `selection.search_terms`; follow-ups gain the
+  `nearby` priority.
+
 ## 0.16.0 - 2026-09-30
 
 The session brief ships as an opt-in experiment (D-368). In a baseline-versus-brief

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.
@@ -266,7 +268,11 @@ follow-up reads. It runs locally and deterministically: no network, no model,
 no account. A decision always appears together with any later decision whose
 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.
+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. 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):
 
@@ -286,8 +292,10 @@ The brief is opt-in because of the project's own evaluation, which did not
 fully follow its protocol. Agents with a brief found about as much of the
 relevant memory as agents without one, and made none of the specific false
 authority claims the evaluation checked for. But they missed nine facts the
-others found, in one case after the brief left out the key document. Treat a
-brief as a starting point, not the whole answer.
+others found, in one case after the brief left out the key document. A second
+evaluation, after retrieval fixes, stopped at a protocol deviation before any
+grading, so turning the brief on by default still waits for a conforming one.
+Treat a brief as a starting point, not the whole answer.
 
 ## Hosted Sync
 
@@ -412,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.16.0",
+  "version": "0.17.1",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

package/src/brief-keywords.js

@@ -66,7 +66,24 @@ const SUFFIX_RULES = [
   ['s', '', 3],
 ];
 
+// Common abbreviations meet their long forms after stemming, at index and
+// query time alike: "organizations" and "org" both become "org".
+const CANONICAL_STEMS = new Map([
+  ['organiz', 'org'],
+  ['repository', 'repo'],
+  ['configurat', 'config'],
+  ['databas', 'db'],
+  ['environ', 'env'],
+  ['documentat', 'doc'],
+  ['authenticat', 'auth'],
+]);
+
 export function stemWord(word) {
+  const stem = stemRaw(word);
+  return CANONICAL_STEMS.get(stem) ?? stem;
+}
+
+function stemRaw(word) {
   const lower = word.toLowerCase();
   if (IRREGULAR.has(lower)) return IRREGULAR.get(lower);
   if (lower.length <= 3 || lower.endsWith('ss') || lower.endsWith('us') || lower.endsWith('is')) {
@@ -91,6 +108,47 @@ export function stemWord(word) {
   return stem;
 }
 
+// Words that say how a user feels about a topic ("clearer", "flaky",
+// "noticeably", "honestly") or what kind of work they want ("investigate",
+// "failure", "bug") rather than what the topic is. They still count for
+// keyword scoring; they are never a task's distinctive topic words, so they
+// alone cannot make a brief abstain.
+const NON_TOPICAL_WORDS = new Set(
+  (
+    'actual annoying awful awkward bad basic beautiful better best big brittle broken buggy careful clean clear clever clumsy clunky ' +
+    'complete confus confusing constant curious decent difficult dumb easy elegant entire ever extreme fast feel fine flaky fragile frank ' +
+    'frequent friendly frustrating full general glitchy good great happy hard heavy helpful honest hopeful huge ideal important ' +
+    'intermittent intuitive janky laggy large light little lovely main maybe messy minor modern mostly much nice noisy noticeable obvious ' +
+    'occasional odd often overall painful perhaps pleasant polished poor possible pretty probable quick quiet quite random rare real ' +
+    'rather reliable responsive rough seem serious simple skeptical slight slow sluggish small smart smooth snappy solid somehow ' +
+    'sometime sometimes somewhat sporadic strange stupid sturdy subtle super terrible thorough tidy tiny total ugly unclear unfriendly ' +
+    'unhappy unpleasant unreliable unstable usable useful useless usual verbose very weird worried worse worst ' +
+    // Kinds of work and trouble.
+    'behave behavior behaviour bug check crash debug diagnose error explain fail failure figure fix handle help idea improve ' +
+    'improvement incorrect investigate issue missing problem question refactor regression repair tweak understand verify wrong'
+  ).split(' '),
+);
+
+/**
+ * True for a word that only evaluates, hedges, intensifies, or names a kind of
+ * work (comparatives, -ly adverbs, and -s/-ed/-ing forms included).
+ */
+export function isNonTopicalWord(word) {
+  const lower = String(word).toLowerCase();
+  const forms = new Set([lower]);
+  for (const [suffix, replacement] of [
+    ['iest', 'y'], ['ier', 'y'], ['est', ''], ['er', ''], ['ily', 'y'], ['ably', 'able'], ['ibly', 'ible'], ['ly', ''],
+    ['ing', ''], ['ing', 'e'], ['ed', ''], ['ed', 'e'], ['es', ''], ['s', ''],
+  ]) {
+    if (lower.endsWith(suffix) && lower.length - suffix.length >= 3) forms.add(lower.slice(0, lower.length - suffix.length) + replacement);
+  }
+  for (const form of [...forms]) {
+    if (/(.)\1$/.test(form)) forms.add(form.slice(0, -1)); // "bigger" → "bigg" → "big"
+    if (form.endsWith('i')) forms.add(`${form.slice(0, -1)}y`);
+  }
+  return [...forms].some((form) => NON_TOPICAL_WORDS.has(form));
+}
+
 /** Raw lowercase word tokens: letters and digits, split on everything else. */
 export function splitWords(text) {
   return String(text ?? '')

package/src/brief-lifecycle.js

@@ -4,6 +4,7 @@ import {
   BRIEF_CONTRACT_VERSION,
   BRIEF_DEFAULT_BUDGET,
   BRIEF_OVERVIEW_PATH,
+  briefShortHash,
   buildSessionBrief,
   computeBriefCorpusDigest,
   describeBriefInputs,
@@ -30,8 +31,11 @@ import { PACKAGE_VERSION } from './version.js';
  */
 
 export const LANE_BRIEF_FILENAME = 'brief.md';
-export const LANE_BRIEF_FORMAT = 1;
+export const LANE_BRIEF_FORMAT = 2;
 const MAX_HEADER_INPUTS = 24;
+// Lists that grow with settings and repos show at most this many entries; a
+// digest of the whole list is the binding, so staleness checks stay complete.
+const MAX_HEADER_LIST = 4;
 const MAX_REASON_LENGTH = 400;
 
 export function laneBriefPath(rootDir, laneId) {
@@ -210,8 +214,7 @@ async function compareBindings({ header, destinationRoot, laneId, sourceRootDir,
   const reasons = [];
   // The alias map comes from both roots' project.yaml; the destination's is
   // not part of the source corpus, so it is compared directly.
-  const recordedAliases = Array.isArray(header.repo_aliases) ? header.repo_aliases.map(String) : [];
-  if (JSON.stringify(recordedAliases) !== JSON.stringify(source.aliasPairs.map(formatAliasPair))) {
+  if (header.repo_aliases_digest !== headerListDigest(source.aliasPairs.map(formatAliasPair))) {
     reasons.push('the repo alias map changed (a destination or source repo id or remote)');
   }
 
@@ -222,6 +225,9 @@ async function compareBindings({ header, destinationRoot, laneId, sourceRootDir,
     return [...reasons, `brief settings are invalid, so freshness cannot be checked without reading excluded paths: ${problems.join('; ')}`];
   }
   const exclusions = compileBriefExclusions(uniqueStrings([...sourceSettings.exclude, ...destinationSettings.exclude]));
+  if (header.exclude_digest !== headerListDigest(exclusions.patterns)) {
+    reasons.push('the brief exclusions changed (project.yaml brief.exclude)');
+  }
 
   const lane = await readBriefLaneBindings(source.rootDir, source.laneId);
   const identity = lane.sessionDate && Number.isInteger(lane.sessionNumber) ? `${lane.sessionDate}-${lane.sessionNumber}` : null;
@@ -392,12 +398,14 @@ function renderLaneBriefDocument({ destinationRoot, laneId, generatedAt, budget,
     `destination_root: ${quote(destinationRoot)}`,
     `destination_lane: ${quote(laneId)}`,
     `corpus_digest: ${quote(result.source.corpus_digest ?? 'none')}`,
-    ...renderList('exclude', result.source.exclude ?? []),
+    `exclude_digest: ${quote(headerListDigest(result.source.exclude ?? []))}`,
+    ...renderBoundedList('exclude', result.source.exclude ?? [], 'exclude_digest'),
     'lane_bindings:',
     `  session: ${quote(lane?.session ?? 'none')}`,
     `  handoff: ${quote(encodeOptionalHash(lane?.handoff ?? null))}`,
     `  other_lanes: ${quote(lane?.other_lanes ?? 'none')}`,
-    ...renderList('repo_aliases', source.aliasPairs.map(formatAliasPair)),
+    `repo_aliases_digest: ${quote(headerListDigest(source.aliasPairs.map(formatAliasPair)))}`,
+    ...renderBoundedList('repo_aliases', source.aliasPairs.map(formatAliasPair), 'repo_aliases_digest'),
     ...renderList('inputs', [
       ...shown.map((input) => `${input.hash} ${input.key}`),
       ...(folded.length > 0 ? [`+${folded.length} more inputs (covered by corpus_digest)`] : []),
@@ -444,6 +452,7 @@ function assembleBriefDocument(commands, generatedAt, fields, body) {
   const lines = [
     '---',
     '# Generated session brief (D-357, D-359, D-364); do not edit. It is stale once any binding below changes.',
+    '# The token budget covers the brief body below this header; the header is metadata outside it.',
     `# Check: ${commands.check}`,
     `# Refresh: ${commands.write}`,
     `brief_format: ${LANE_BRIEF_FORMAT}`,
@@ -466,6 +475,18 @@ function renderList(key, values) {
   return [`${key}:`, ...values.map((value) => `  - ${quote(value)}`)];
 }
 
+/** At most MAX_HEADER_LIST entries, then "+N more"; the named digest binds the whole list. */
+function renderBoundedList(key, values, digestKey) {
+  if (values.length <= MAX_HEADER_LIST) return renderList(key, values);
+  const shown = values.slice(0, MAX_HEADER_LIST - 1);
+  return renderList(key, [...shown, `+${values.length - shown.length} more (bound by ${digestKey})`]);
+}
+
+/** Order-insensitive short digest of a header list (sorted values). */
+function headerListDigest(values) {
+  return briefShortHash([...values].map(String).sort());
+}
+
 function parseInputLines(values) {
   if (!Array.isArray(values)) return [];
   return values

package/src/brief-render.js

@@ -27,6 +27,13 @@ const EVIDENCE_NOTE =
   '_Evidence: "covers" and "cites" are mechanical (the doc lists the file or mentions the decision); "supersedes" and "amends" come only from the later decision\'s own text. The brief infers no other relation and does not decide which decision applies to this task._';
 const EVIDENCE_NOTE_SHORT = '_Evidence: covers/cites are mechanical; supersedes/amends are declared by the later decision. Nothing else is inferred._';
 
+// Framing (A7): A5 found agents that stopped searching where the brief
+// stopped. The brief says what it is — a keyword- and citation-selected
+// starting point of cut excerpts — and names the task's key terms to search.
+const USE_NOTE =
+  "**Use this brief as a starting point, not the whole context.** It shows cut excerpts chosen by keyword and citation matching, so it can miss the doc this task depends on. Read the full source behind any fact you rely on, and search memory beyond this list";
+const USE_NOTE_SHORT = '**Starting point only:** excerpts are cut and selection can miss key docs; read full sources and search beyond this list';
+
 /**
  * Frame limits (header, status, follow-ups) per compaction level. Level 0 is
  * normal; the engine raises the level only when the frame itself would not
@@ -34,10 +41,10 @@ const EVIDENCE_NOTE_SHORT = '_Evidence: covers/cites are mechanical; supersedes/
  * field is bounded at every level; units render the same at every level.
  */
 const FRAME_LIMITS = [
-  { task: 300, file: 120, files: 4, root: 160, reason: 300, gap: 240, followUpPath: 120, followUpHeading: 60, followUpReason: 170, followUps: Infinity, evidence: EVIDENCE_NOTE },
-  { task: 160, file: 60, files: 2, root: 60, reason: 200, gap: 160, followUpPath: 100, followUpHeading: 40, followUpReason: 80, followUps: Infinity, evidence: EVIDENCE_NOTE_SHORT },
-  { task: 120, file: 50, files: 1, root: 40, reason: 160, gap: 110, followUpPath: 80, followUpHeading: 30, followUpReason: 40, followUps: Infinity, evidence: EVIDENCE_NOTE_SHORT },
-  { task: 100, file: 40, files: 1, root: 30, reason: 120, gap: 90, followUpPath: 70, followUpHeading: 24, followUpReason: 30, followUps: 6, evidence: EVIDENCE_NOTE_SHORT },
+  { task: 300, file: 120, files: 4, root: 160, reason: 300, gap: 240, followUpPath: 120, followUpHeading: 60, followUpReason: 170, followUps: Infinity, evidence: EVIDENCE_NOTE, use: USE_NOTE, searchTerms: 6, searchTerm: 40 },
+  { task: 160, file: 60, files: 2, root: 60, reason: 200, gap: 160, followUpPath: 100, followUpHeading: 40, followUpReason: 80, followUps: Infinity, evidence: EVIDENCE_NOTE_SHORT, use: USE_NOTE_SHORT, searchTerms: 4, searchTerm: 30 },
+  { task: 120, file: 50, files: 1, root: 40, reason: 160, gap: 110, followUpPath: 80, followUpHeading: 30, followUpReason: 40, followUps: Infinity, evidence: EVIDENCE_NOTE_SHORT, use: USE_NOTE_SHORT, searchTerms: 3, searchTerm: 24 },
+  { task: 100, file: 40, files: 1, root: 30, reason: 120, gap: 90, followUpPath: 70, followUpHeading: 24, followUpReason: 30, followUps: 6, evidence: EVIDENCE_NOTE_SHORT, use: USE_NOTE_SHORT, searchTerms: 2, searchTerm: 20 },
 ];
 export const BRIEF_MAX_COMPACTION = FRAME_LIMITS.length - 1;
 
@@ -53,7 +60,7 @@ export function renderBrief(result) {
   lines.push(`**Status: ${result.status}** — ${statusSentence(result, frame)}`, '');
   lines.push(...renderHeader(result, frame), '');
 
-  if (result.status !== 'no-match') lines.push(frame.evidence, '');
+  if (result.status !== 'no-match') lines.push(`${frame.use}${searchSuffix(result, frame)}`, '', frame.evidence, '');
 
   const byKind = (kind) => result.units.filter((unit) => unit.kind === kind);
   const emitted = new Set();
@@ -89,7 +96,7 @@ export function renderBrief(result) {
   }
 
   if (result.status !== 'incomplete' && followUps.length > 0) {
-    lines.push('## Follow-up reads', '', ...followUps, '');
+    lines.push(result.status === 'no-match' ? '## Nearby memory (shares task words only)' : '## Follow-up reads', '', ...followUps, '');
   }
 
   return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`;
@@ -114,27 +121,31 @@ export function renderBriefUnit(unit, options = {}) {
 }
 
 function statusSentence(result, frame) {
-  const withheld = result.omitted.filter((unit) => unit.omitted_reason === 'narrow-match').length;
-  const overflow = result.omitted.length - withheld;
   switch (result.status) {
     case 'complete':
       return 'every selected unit fits the budget.';
     case 'partial': {
-      const parts = [];
-      if (overflow > 0) parts.push(`${overflow} lower-tier unit${overflow === 1 ? '' : 's'} did not fit`);
-      if (withheld > 0) {
-        // Every unit in a narrow match is low-confidence, the packed ones included.
-        parts.push(`most of the task's distinctive words had no keyword match, so every match is low-confidence: the top ${result.units.filter((unit) => unit.tier === 'ranked').length} are shown for orientation and ${withheld} more ${withheld === 1 ? 'is' : 'are'} listed as reads only`);
-      }
-      return `${parts.join('; ')}; see Follow-up reads.`;
+      const overflow = result.omitted.length;
+      return `${overflow} lower-tier unit${overflow === 1 ? '' : 's'} did not fit; see Follow-up reads.`;
     }
     case 'no-match':
-      return 'no architecture doc or decision matched this task. Nothing in memory is presented as relevant; say so in your plan, and read the orientation overview if the task needs broader context.';
+      if (result.follow_ups.length > 0) {
+        // Topic words unknown to the index: nearby reads share other task words.
+        return `no architecture doc or decision matched this task's distinctive words. Nothing in memory is presented as relevant. The nearby reads below share only other task words: check them${searchSuffix(result, frame, ' and search memory')} before concluding that nothing applies, and say in your plan what, if anything, applies.`;
+      }
+      return `no architecture doc or decision matched this task. Nothing in memory is presented as relevant${searchSuffix(result, frame, '; search memory')} before concluding that nothing applies, say so in your plan, and read the orientation overview if the task needs broader context.`;
     default:
       return `${excerpt(result.status_reason, frame.reason)}.`;
   }
 }
 
+/** " for: `a`, `b`" — the task's key terms to search (rarest first), bounded by the frame. */
+function searchSuffix(result, frame, lead = '') {
+  const terms = (result.selection?.search_terms ?? []).slice(0, frame.searchTerms).map((term) => `\`${excerpt(term, frame.searchTerm)}\``);
+  if (terms.length === 0) return lead ? `${lead}` : '.';
+  return `${lead} for ${terms.join(', ')}${lead ? '' : '.'}`;
+}
+
 function renderHeader(result, frame) {
   const files = result.inputs.files;
   const fileText =

package/src/brief.js

@@ -1,11 +1,12 @@
 import { readdir, readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { createKeywordIndex, queryTermOrigins, queryTerms } from './brief-keywords.js';
+import { createKeywordIndex, isNonTopicalWord, queryTermOrigins, queryTerms } from './brief-keywords.js';
 import { BRIEF_MAX_COMPACTION, renderBrief, renderBriefUnit, renderedFollowUpCount } from './brief-render.js';
 import { compileBriefExclusions, readBriefSettingsForRoot, validateExcludePattern } from './brief-settings.js';
 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';
 
@@ -28,7 +29,7 @@ import { parseSimpleYaml } from './simple-yaml.js';
  * doc, file, or task, or that one is currently valid.
  */
 
-export const BRIEF_CONTRACT_VERSION = 1;
+export const BRIEF_CONTRACT_VERSION = 2;
 export const BRIEF_DEFAULT_BUDGET = 6000;
 export const BRIEF_MIN_BUDGET = 800;
 export const BRIEF_RESERVE_TOKENS = 600;
@@ -41,7 +42,12 @@ const DOC_FIELDS = {
   title: { weight: 3, b: 0.3 },
   body: { weight: 1, b: 0.75 },
   guidance: { weight: 1.5, b: 0.75 },
+  // Decisions only: the sentences around each mention of the decision in an
+  // architecture doc (anchor text). Docs describe a decision in their own
+  // words, which are often the words a task uses.
+  anchor: { weight: 1, b: 0.5 },
 };
+const REVERSE_CITATION_WEIGHT = 4;
 const MAX_DOC_CANDIDATES = 10;
 const MAX_DECISION_CANDIDATES = 14;
 // A doc whose mandatory companions would take more than a quarter of the
@@ -60,8 +66,8 @@ const CITATION_WEIGHT = 6;
 // Evidence lists and file inventories cite decisions without saying anything about them.
 const NON_PROPAGATING_SECTIONS = new Set(['Review metadata', 'Involved files']);
 const DISTINCTIVE_TERM_LIMIT = 3;
-const STRONG_TOPIC_TERMS = 3;
-const NARROW_PACKED_UNITS = 4;
+const NEARBY_READS = 4;
+const SEARCH_TERM_LIMIT = 6;
 const DISTINCTIVE_MAX_DOCUMENT_SHARE = 0.02;
 
 /**
@@ -114,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) {
@@ -144,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);
@@ -454,6 +469,7 @@ function selectCandidates(context, loaded, task) {
       entry: decisionEntries.get(decision.decision_id),
     }));
 
+  const anchors = buildDecisionAnchors(documents, new Set(decisions.map((decision) => decision.decisionId)));
   const index = createKeywordIndex(DOC_FIELDS, [
     ...docs.map((doc) => ({
       id: doc.id,
@@ -461,11 +477,12 @@ function selectCandidates(context, loaded, task) {
         title: `${doc.component} ${doc.feature} ${doc.domain} ${path.basename(doc.path, '.md')}`,
         body: doc.description ?? '',
         guidance: [doc.retrievalGuidance, doc.retrievalScope].filter(Boolean).join('\n'),
+        anchor: '',
       },
     })),
     ...decisions.map((decision) => ({
       id: decision.id,
-      fields: { title: decision.title, body: decision.entry.fields.Decision ?? '', guidance: '' },
+      fields: { title: decision.title, body: decision.entry.fields.Decision ?? '', guidance: '', anchor: anchors.get(decision.decisionId) ?? '' },
     })),
   ]);
 
@@ -475,7 +492,18 @@ function selectCandidates(context, loaded, task) {
   const pathWords = [...input.files, ...input.claims, ...(lane?.claims ?? [])].map(pathTopicText).join(' ');
   const terms = uniqueStrings([...queryTerms(task), ...queryTerms(pathWords)]).filter((term) => !projectTerms.has(term));
   const keywordScores = new Map(index.score(terms).map((result) => [result.id, result]));
-  const distinctive = pickDistinctiveTerms(terms, index);
+  const origins = queryTermOrigins(`${task} ${pathWords}`);
+  // Evaluative and kind-of-work words ("clearer", "flaky", "investigate",
+  // "failure") say how the user feels or what they want done, not what the
+  // topic is, so they are never distinctive topic words.
+  const topicTerms = terms.filter((term) => !isNonTopicalWord(origins.get(term) ?? term));
+  const distinctive = pickDistinctiveTerms(topicTerms, index);
+  // The task's key words to search beyond the brief, rarest in the index first.
+  const searchTerms = uniqueStrings(
+    [...topicTerms]
+      .sort((left, right) => index.documentFrequency(left) - index.documentFrequency(right) || left.localeCompare(right))
+      .map((term) => (origins.get(term) ?? term).toLowerCase()),
+  ).slice(0, SEARCH_TERM_LIMIT);
 
   // Mechanical evidence from the inputs: files and claims through the
   // file-owner index, lane-declared architecture docs, feature slugs.
@@ -535,6 +563,34 @@ function selectCandidates(context, loaded, task) {
     doc.score = evidence + doc.keywordScore;
   }
 
+  // Reverse propagation: a doc shares the keyword relevance of the decisions
+  // it cites (outside evidence sections), diluted by how many it cites. A doc
+  // whose Description misses the task's words is still reached through the
+  // decisions it describes.
+  const keywordDecisions = decisions
+    .map((decision) => ({ decision, score: keywordScores.get(decision.id)?.score ?? 0 }))
+    .filter((entry) => entry.score >= MIN_KEYWORD_SCORE);
+  const topDecisionKeyword = Math.max(0, ...keywordDecisions.map((entry) => entry.score));
+  const decisionKeyword = new Map(
+    keywordDecisions
+      .filter((entry) => entry.score >= topDecisionKeyword * RELATIVE_SCORE_FLOOR)
+      .map((entry) => [entry.decision.decisionId, entry.score / topDecisionKeyword]),
+  );
+  const citesByDoc = new Map();
+  for (const relation of relations) {
+    if (relation.relation !== 'cites' || !relation.target_exists) continue;
+    if (NON_PROPAGATING_SECTIONS.has(String(relation.source_section ?? '').split(' > ')[0])) continue;
+    if (!citesByDoc.has(relation.source_path)) citesByDoc.set(relation.source_path, new Set());
+    citesByDoc.get(relation.source_path).add(relation.target_decision_id);
+  }
+  for (const doc of docs) {
+    const cited = [...(citesByDoc.get(doc.path) ?? [])];
+    const matched = cited.filter((id) => decisionKeyword.has(id)).sort((left, right) => decisionKeyword.get(right) - decisionKeyword.get(left) || left - right);
+    doc.reverseBoost = matched.length > 0 ? (REVERSE_CITATION_WEIGHT * matched.reduce((sum, id) => sum + decisionKeyword.get(id), 0)) / Math.sqrt(cited.length) : 0;
+    doc.reverseCited = matched;
+    doc.score += doc.reverseBoost;
+  }
+
   const decisionById = new Map(decisions.map((decision) => [decision.decisionId, decision]));
   const namedDecisionIds = new Set(
     scanDecisionReferences(task)
@@ -543,22 +599,19 @@ function selectCandidates(context, loaded, task) {
   );
 
   const topKeyword = Math.max(0, ...[...keywordScores.values()].map((result) => result.score));
-  // Absent distinctive words alone never abstain: unfamiliar modifiers
-  // ("clearer", "sporadic") are common in real tasks, and a false no-match
-  // hides memory that exists. Abstain on them only when no single unit
-  // shares at least STRONG_TOPIC_TERMS of the task's words.
-  const strongestOverlap = Math.max(0, ...[...keywordScores.values()].map((result) => result.matched.length));
-  const noMatch =
-    docs.every((doc) => doc.evidenceScore === 0) &&
-    namedDecisionIds.size === 0 &&
-    (terms.length === 0 ||
-      topKeyword < MIN_KEYWORD_SCORE ||
-      (distinctiveTermsMostlyAbsent(distinctive, index) && strongestOverlap < STRONG_TOPIC_TERMS));
+  // No-match when only keywords selected memory and either nothing clears the
+  // keyword floor or the task's distinctive topic words are mostly unknown to
+  // the index (evaluative and kind-of-work words never count, so "clearer" or
+  // "investigate" alone cannot abstain). With an unknown topic the best keyword matches become
+  // nearby reads, never units: a misjudged topic still points at the memory
+  // that shares the task's other words, and nothing is presented as relevant.
+  const keywordsOnly = docs.every((doc) => doc.evidenceScore === 0) && namedDecisionIds.size === 0;
+  const topicAbsent = distinctiveTermsMostlyAbsent(distinctive, index);
+  const noMatch = keywordsOnly && (terms.length === 0 || topKeyword < MIN_KEYWORD_SCORE || topicAbsent);
 
   // Task words with no keyword match in the searched fields are disclosed, never guessed at.
   const absent = terms.filter((term) => index.documentFrequency(term) === 0);
   if (absent.length > 0) {
-    const origins = queryTermOrigins(`${task} ${pathWords}`);
     const words = absent.map((term) => origins.get(term) ?? term);
     context.gaps.push({
       code: 'unmatched-terms',
@@ -571,24 +624,17 @@ function selectCandidates(context, loaded, task) {
   }
 
   if (noMatch) {
-    return { noMatch: true, terms, distinctive, docs: [], namedDecisions: [], rankedDecisions: [], notes: [], relations, decisionById, decisionEntries, readModel };
+    const nearby = (topicAbsent && topKeyword >= MIN_KEYWORD_SCORE ? pickNearby(docs, decisions, keywordScores) : []).map((entry) => ({
+      ...entry,
+      matched: entry.matched.map((term) => (origins.get(term) ?? term).toLowerCase()),
+    }));
+    return { noMatch: true, topicAbsent, nearby, terms, distinctive, searchTerms, docs: [], namedDecisions: [], rankedDecisions: [], notes: [], relations, decisionById, decisionEntries, readModel };
   }
 
-  // When the task's distinctive words are mostly unknown and nothing but
-  // keywords selected the memory, confidence is low: the match is kept
-  // narrow. Candidates are chosen and ranked as usual; only the top
-  // NARROW_PACKED_UNITS ranked units are packed and the rest are listed as
-  // follow-up reads, so the top-scoring topic is never dropped for a raw
-  // overlap count and a weak match does not fill the budget.
-  const narrow =
-    distinctiveTermsMostlyAbsent(distinctive, index) &&
-    docs.every((doc) => doc.evidenceScore === 0) &&
-    namedDecisionIds.size === 0;
-
   // Docs with mechanical evidence (they cover an input file or claim, the lane
   // declares them, or they belong to a named feature) skip the relative floor.
   const selectedDocs = pickTop(
-    docs.filter((doc) => doc.evidenceScore > 0 || doc.keywordScore >= MIN_KEYWORD_SCORE),
+    docs.filter((doc) => doc.evidenceScore > 0 || doc.keywordScore + doc.reverseBoost >= MIN_KEYWORD_SCORE),
     MAX_DOC_CANDIDATES,
     (doc) => doc.evidenceScore > 0,
   );
@@ -647,12 +693,15 @@ function selectCandidates(context, loaded, task) {
 
   for (const doc of selectedDocs) {
     if (doc.matchedTerms.length > 0) doc.reasons.push(`keywords: ${doc.matchedTerms.join(', ')}`);
+    if (doc.reverseCited.length > 0) doc.reasons.push(`cites keyword-matched ${doc.reverseCited.slice(0, 4).map(formatId).join(', ')}${doc.reverseCited.length > 4 ? ` (+${doc.reverseCited.length - 4} more)` : ''}`);
   }
 
   return {
     noMatch: false,
-    narrow,
+    topicAbsent: false,
+    nearby: [],
     terms,
+    searchTerms,
     distinctive,
     docs: selectedDocs,
     namedDecisions,
@@ -683,6 +732,29 @@ function pickDistinctiveTerms(terms, index) {
     .slice(0, limit);
 }
 
+/**
+ * Nearby reads for a no-match brief whose topic words are unknown: the best
+ * keyword matches among docs and decisions, interleaved by score relative to
+ * the top of their kind. Paths and matched words only — never units.
+ */
+function pickNearby(docs, decisions, keywordScores) {
+  const docEntries = docs
+    .filter((doc) => doc.keywordScore + doc.reverseBoost >= MIN_KEYWORD_SCORE)
+    .map((doc) => ({ id: doc.id, score: doc.keywordScore + doc.reverseBoost, path: doc.path, heading: null, matched: doc.matchedTerms }));
+  const decisionEntries = decisions
+    .map((decision) => ({ decision, keyword: keywordScores.get(decision.id) }))
+    .filter((entry) => (entry.keyword?.score ?? 0) >= MIN_KEYWORD_SCORE)
+    .map(({ decision, keyword }) => ({ id: decision.id, score: keyword.score, path: decision.path, heading: formatId(decision.decisionId), matched: keyword.matched }));
+  const relative = (entries) => {
+    const top = Math.max(0, ...entries.map((entry) => entry.score));
+    return entries.map((entry) => ({ ...entry, relative: top > 0 ? entry.score / top : 0 }));
+  };
+  return [...relative(docEntries), ...relative(decisionEntries)]
+    .sort((left, right) => right.relative - left.relative || right.score - left.score || left.id.localeCompare(right.id))
+    .slice(0, NEARBY_READS)
+    .map(({ path: entryPath, heading, matched }) => ({ path: entryPath, heading, matched }));
+}
+
 function pickTop(candidates, limit, bypassFloor = () => false) {
   const sorted = [...candidates].sort(compareByScore);
   const top = sorted[0]?.score ?? 0;
@@ -760,8 +832,7 @@ function buildUnits(context, selection) {
     })),
   ].sort((left, right) => right.relative - left.relative || left.unit.id.localeCompare(right.unit.id));
   for (const [index, entry] of ranked.entries()) {
-    const withheld = selection.narrow && index >= NARROW_PACKED_UNITS;
-    units.push({ ...entry.unit, rank: index + 1, ...(withheld ? { withheld: true } : {}) });
+    units.push({ ...entry.unit, rank: index + 1 });
   }
 
   for (const note of selection.notes) units.push(buildNoteUnit(note));
@@ -1037,16 +1108,11 @@ function assemble(context, selection, units, capacity, compaction = 0) {
   const covered = [];
   let used = 0;
 
-  for (const { companions = [], withheld = false, ...unit } of units) {
+  for (const { companions = [], ...unit } of units) {
     if (unit.kind === 'lineage' && unit.members.every((member) => emitted.has(member.decision_id))) {
       covered.push(unit.id);
       continue;
     }
-    if (withheld) {
-      const tokens = estimateBriefTokens(renderBriefUnit(unit, { emittedDecisions: emitted }));
-      omitted.push({ ...unit, estimated_tokens: tokens, omitted_reason: 'narrow-match' });
-      continue;
-    }
 
     // A doc and its mandatory companions pack atomically; companions already
     // shown by an earlier unit cost nothing.
@@ -1130,7 +1196,8 @@ function baseResult(context, selection, { status, units, omitted, covered, follo
     selection: {
       query_terms: selection?.terms ?? [],
       distinctive_terms: selection?.distinctive ?? [],
-      narrowed: Boolean(selection?.narrow),
+      topic_absent: Boolean(selection?.topicAbsent),
+      search_terms: selection?.searchTerms ?? [],
     },
     units,
     omitted,
@@ -1148,8 +1215,11 @@ function decideStatus(selection, omitted) {
     return { status: 'incomplete', reason: `retrieval failed — ${selection.retrievalError}` };
   }
   if (selection.noMatch) {
-    return omitted.some((unit) => unit.kind === 'lane')
-      ? { status: 'incomplete', reason: 'no memory matched the task, and the lane unit did not fit the budget' }
+    if (omitted.some((unit) => unit.kind === 'lane')) {
+      return { status: 'incomplete', reason: 'no memory matched the task, and the lane unit did not fit the budget' };
+    }
+    return selection.topicAbsent
+      ? { status: 'no-match', reason: "no architecture doc or decision matched the task's distinctive words" }
       : { status: 'no-match', reason: 'no architecture doc or decision matched the task' };
   }
 
@@ -1161,11 +1231,7 @@ function decideStatus(selection, omitted) {
     };
   }
   if (omitted.length > 0) {
-    const withheld = omitted.filter((unit) => unit.omitted_reason === 'narrow-match').length;
-    const parts = [];
-    if (omitted.length > withheld) parts.push(`${plural(omitted.length - withheld, 'ranked or optional unit')} did not fit the budget`);
-    if (withheld > 0) parts.push(`${plural(withheld, 'lower-confidence match', 'lower-confidence matches')} listed as reads only (narrow match)`);
-    return { status: 'partial', reason: parts.join('; ') };
+    return { status: 'partial', reason: `${plural(omitted.length, 'ranked or optional unit')} did not fit the budget` };
   }
   return { status: 'complete', reason: 'every selected unit fits the budget' };
 }
@@ -1185,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' });
     }
@@ -1199,14 +1274,23 @@ function buildFollowUps(selection, context, included, omitted) {
   }
 
   for (const unit of omitted.filter((candidate) => candidate.tier === 'ranked')) {
-    const prefix = unit.omitted_reason === 'narrow-match' ? 'narrow match, read only: ' : '';
     if (unit.kind === 'doc') {
-      entries.push({ priority: 'ranked', path: unit.path, heading: null, reason: shortReason(`${prefix}${unit.reasons[0] ?? 'ranked doc'}`) });
+      entries.push({ priority: 'ranked', path: unit.path, heading: null, reason: shortReason(unit.reasons[0] ?? 'ranked doc') });
     } else {
-      entries.push(...lineageReads(unit, 'ranked', prefix));
+      entries.push(...lineageReads(unit, 'ranked'));
     }
   }
 
+  // No-match with an unknown topic: the closest keyword matches, as reads.
+  for (const entry of selection.nearby ?? []) {
+    entries.push({
+      priority: 'nearby',
+      path: entry.path,
+      heading: entry.heading,
+      reason: shortReason(`shares other task words (${entry.matched.join(', ')}); not presented as relevant`),
+    });
+  }
+
   // Uncertified lineage wording aimed at an emitted decision: a read, never
   // a status or a relation. Grouped per source file and target decision.
   const unknownGroups = new Map();
@@ -1248,7 +1332,7 @@ function buildFollowUps(selection, context, included, omitted) {
   });
 }
 
-function lineageReads(unit, priority, prefix = '') {
+function lineageReads(unit, priority) {
   return [...unit.members]
     .sort((left, right) => right.decision_id - left.decision_id)
     .map((member) => ({
@@ -1258,13 +1342,19 @@ function lineageReads(unit, priority, prefix = '') {
       heading: formatId(member.decision_id),
       reason:
         member.role === 'root'
-          ? shortReason(`${prefix}${unit.reasons[0] ? `${unit.tier}: ${unit.reasons[0]}` : `${unit.tier} decision`}`)
+          ? shortReason(unit.reasons[0] ? `${unit.tier}: ${unit.reasons[0]}` : `${unit.tier} decision`)
           : `declared successor of ${formatId(unit.root_decision_id)} (${member.successor_relations.join(', ')})`,
     }));
 }
 
-function finalizeRetrievalFailure(context, reason) {
-  return packBrief(context, { retrievalError: reason, terms: [], distinctive: [], relations: [] });
+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(', ');
 }
 
 /**
@@ -1290,6 +1380,75 @@ function assertLineageSafety(result, relations) {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Anchor text per decision: each sentence of an architecture doc (the
+ * overview included) that mentions the decision, outside fenced code and the
+ * evidence sections (Review metadata, Involved files). Identical sentences
+ * count once per decision.
+ */
+function buildDecisionAnchors(documents, decisionIds) {
+  const anchors = new Map();
+  for (const document of documents) {
+    if (document.kind !== 'architecture' || typeof document.content !== 'string') continue;
+    for (const block of markdownBlocks(document.content)) {
+      if (NON_PROPAGATING_SECTIONS.has(block.section)) continue;
+      const { refs } = scanDecisionReferences(block.text);
+      for (const ref of refs) {
+        if (!decisionIds.has(ref.id)) continue;
+        const sentence = sentenceAround(block.text, ref.start, ref.end);
+        if (!anchors.has(ref.id)) anchors.set(ref.id, new Set());
+        anchors.get(ref.id).add(sentence);
+      }
+    }
+  }
+  return new Map([...anchors].map(([id, sentences]) => [id, [...sentences].join('\n')]));
+}
+
+/** 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|$)/, '');
+  const blocks = [];
+  let section = null;
+  let fence = null;
+  let current = null;
+  const flush = () => {
+    if (current && current.lines.length > 0) blocks.push({ section, text: current.lines.join(' ') });
+    current = null;
+  };
+  for (const line of body.split(/\r?\n/)) {
+    const step = stepFence(fence, line);
+    fence = step.fence;
+    if (step.delimiter) {
+      flush();
+      continue;
+    }
+    if (fence) continue;
+    const heading = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (heading) {
+      flush();
+      if (heading[1].length <= 2) section = heading[2];
+      continue;
+    }
+    if (line.trim() === '') {
+      flush();
+      continue;
+    }
+    if (/^\s*(?:[-*+]|\d+\.)\s+/.test(line) || /^\s*\|/.test(line)) flush();
+    if (!current) current = { lines: [] };
+    current.lines.push(line.trim());
+  }
+  flush();
+  return blocks;
+}
+
+/** The sentence of `text` containing [start, end): bounded by ". ", "? ", "! ", or the block edges. */
+function sentenceAround(text, start, end) {
+  const before = text.slice(0, start);
+  const boundary = Math.max(before.lastIndexOf('. '), before.lastIndexOf('? '), before.lastIndexOf('! '));
+  const after = text.slice(end).search(/[.?!](?:\s|$)/);
+  return text.slice(boundary === -1 ? 0 : boundary + 2, after === -1 ? text.length : end + after + 1).trim();
+}
+
 function buildDecisionEntryMap(documents) {
   const map = new Map();
   for (const document of documents) {
@@ -1424,41 +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 marker = line.match(/^\s{0,3}(`{3,}|~{3,})/);
-    if (marker) {
-      if (!fence) fence = marker[1][0];
-      else if (marker[1][0] === fence) fence = null;
-    }
-    if (!fence && !marker && 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,7 +1571,7 @@ export function findFencedRanges(text) {
     offset += line.length + 1;
     const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
     if (fence) {
-      if (marker && marker[1][0] === fence.char && marker[1].length >= fence.length && /^ {0,3}[`~]+\s*$/.test(line)) {
+      if (closesFence(fence, marker, line)) {
         ranges.push([fence.start, Math.min(offset - 1, text.length)]);
         fence = null;
       }
@@ -1490,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);
 }
@@ -1579,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 [];