@vibecompass/vibecompass 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 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

@@ -266,7 +266,9 @@ 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.
 
 The brief in a session lane is an experiment you turn on (D-368):
 
@@ -286,8 +288,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecompass/vibecompass",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "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,6 +1,6 @@
 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';
@@ -28,7 +28,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 +41,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 +65,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;
 
 /**
@@ -454,6 +459,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 +467,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 +482,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 +553,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 +589,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 +614,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 +683,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 +722,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 +822,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 +1098,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 +1186,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 +1205,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 +1221,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' };
 }
@@ -1199,14 +1255,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 +1313,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 +1323,13 @@ 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: [] });
+  return packBrief(context, { retrievalError: reason, terms: [], distinctive: [], relations: [], nearby: [] });
 }
 
 /**
@@ -1290,6 +1355,100 @@ 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')]));
+}
+
+/**
+ * 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|$)/, '');
+  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) {
@@ -1438,12 +1597,10 @@ function splitSections(content, level = 2) {
   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 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);

package/src/decision-lineage.js

@@ -1476,7 +1476,8 @@ 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)) {
+      // 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)) {
         ranges.push([fence.start, Math.min(offset - 1, text.length)]);
         fence = null;
       }