@vibecompass/vibecompass 0.14.0 → 0.16.0

package/src/docs-review.js

@@ -19,6 +19,7 @@ import {
   writeDocsReviewSourceInventory,
 } from './source-inventory.js';
 import { readSyncCursor, resolveSyncBinding } from './sync-binding.js';
+import { formatMissingCredentialError, resolveSyncCredential } from './credential-store.js';
 import { PACKAGE_VERSION } from './version.js';
 import { withMemoryRootLock } from './serialization.js';
 import { listDecisionFileNames, readNextDecisionId } from './decisions.js';
@@ -89,6 +90,7 @@ export async function preflightDocsReview(options = {}, environment = {}) {
       rootDir,
       statePath,
       env: environment.env ?? process.env,
+      credentialStore: environment.runtime?.credentialStore ?? null,
       fetch: environment.runtime?.fetch ?? globalThis.fetch,
     });
   }
@@ -137,6 +139,7 @@ export async function preflightDocsReview(options = {}, environment = {}) {
   const hosted = options.submitHosted
     ? await submitHostedDocsReview({
       env,
+      credentialStore: environment.runtime?.credentialStore ?? null,
       project,
       reviewConfig,
       reviewPrompt,
@@ -1588,9 +1591,20 @@ async function submitHostedDocsReview(options) {
     throw new Error('docs-review --submit-hosted requires sync.credential_env_var in project.yaml.');
   }
 
-  const credential = normalizeOptionalString(options.env?.[credentialEnvVar]);
+  // D-355: env override, then the local credential store.
+  const submitBinding = {
+    apiUrl: options.runtime.api_url,
+    projectId: options.runtime.project_id,
+    credentialEnvVar,
+    target: options.runtime.sync_target ?? null,
+  };
+  const submitResolution = await resolveSyncCredential(submitBinding, {
+    env: options.env ?? process.env,
+    ...(options.credentialStore ?? {}),
+  });
+  const credential = submitResolution.credential;
   if (!credential) {
-    throw new Error(`docs-review --submit-hosted requires ${credentialEnvVar}.`);
+    throw new Error(formatMissingCredentialError(submitBinding, { action: 'docs-review --submit-hosted', detail: submitResolution.detail }));
   }
 
   const endpoint = new URL(
@@ -1758,9 +1772,19 @@ async function pollHostedDocsReview(options) {
     throw new Error('docs-review --poll-hosted requires runtime.credential_env_var in state/docs-review.json.');
   }
 
-  const credential = normalizeOptionalString(options.env?.[credentialEnvVar]);
+  const pollBinding = {
+    apiUrl: runtime.api_url,
+    projectId: runtime.project_id,
+    credentialEnvVar,
+    target: runtime.sync_target ?? null,
+  };
+  const pollResolution = await resolveSyncCredential(pollBinding, {
+    env: options.env ?? process.env,
+    ...(options.credentialStore ?? {}),
+  });
+  const credential = pollResolution.credential;
   if (!credential) {
-    throw new Error(`docs-review --poll-hosted requires ${credentialEnvVar}.`);
+    throw new Error(formatMissingCredentialError(pollBinding, { action: 'docs-review --poll-hosted', detail: pollResolution.detail }));
   }
 
   const endpoint = new URL(

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

@@ -37,7 +37,8 @@ export function renderSharedInstructionBody(context, options = {}) {
     `1. Read \`${contextPath}\`.`,
     `2. Read the latest finalized session note under \`${context.rootDir}/sessions/\`.`,
     `3. If present, read \`${context.rootDir}/sessions/active/index.yaml\` (the lane inventory), then the selected lane's \`wip.md\` and \`handoff.md\`. The selected lane comes from an explicit \`--session\`, the nearest \`.vibecompass-lane.yaml\` worktree marker (walking up from cwd), or the single active lane.`,
-    `4. Read relevant \`${context.rootDir}/architecture/\` and \`${context.rootDir}/decisions/\` docs before editing implementation.`,
+    '4. If present, read the selected lane\'s `brief.md` before planning: the generated session brief (D-359, D-364) selects the docs and decisions for the lane\'s task and says whether it is complete, partial, incomplete, or no-match.',
+    `5. Read relevant \`${context.rootDir}/architecture/\` and \`${context.rootDir}/decisions/\` docs before editing implementation, starting from the brief's units and follow-up reads.`,
     '',
     '## Prompt Commands',
     ...renderPromptCommandLines({ rootRelativePath: context.rootDir }),

package/src/index.js

@@ -7,6 +7,16 @@ export { initializeProjectMemory } from './init.js';
 export { preflightDocsReview } from './docs-review.js';
 export { planDocsUpdate, renderDocsUpdatePlan } from './docs-update.js';
 export { demoteHosted, promoteHosted } from './mode-transition.js';
+export { loginHosted } from './login.js';
+export {
+  describeCredentialSource,
+  formatMissingCredentialError,
+  listSyncCredentials,
+  removeSyncCredential,
+  resolveCredentialStoreDir,
+  resolveSyncCredential,
+  storeSyncCredential,
+} from './credential-store.js';
 export {
   adoptRemoteHead,
   applyPullExport,
@@ -37,5 +47,39 @@ export {
   getProjectContext,
   getFeatureContext,
   getDecisionLog,
+  getDecisionLineage,
   getFileContext,
 } from './read-model.js';
+export {
+  DECISION_LINEAGE_CONTRACT_VERSION,
+  DECISION_RELATION_TYPES,
+  DECLARED_LINEAGE_RELATIONS,
+  buildDecisionLineageModel,
+  collectDeclaredSuccessors,
+  extractArchitectureDocCitations,
+  extractDecisionFileRelations,
+  extractSessionNoteRelations,
+  parseDecisionEntries,
+  scanDecisionReferences,
+} from './decision-lineage.js';
+export {
+  BRIEF_CONTRACT_VERSION,
+  BRIEF_DEFAULT_BUDGET,
+  BRIEF_FOLLOW_UP_CAP,
+  BRIEF_MIN_BUDGET,
+  BRIEF_OVERVIEW_PATH,
+  BRIEF_RESERVE_TOKENS,
+  BRIEF_STATUSES,
+  buildSessionBrief,
+  estimateBriefTokens,
+  resolveBriefRequest,
+} from './brief.js';
+export { renderBrief } from './brief-render.js';
+export {
+  LANE_BRIEF_FILENAME,
+  LANE_BRIEF_FORMAT,
+  generateLaneBrief,
+  inspectLaneBrief,
+  laneBriefPath,
+} from './brief-lifecycle.js';
+export { validateBriefSettings } from './brief-settings.js';

package/src/login.js

@@ -0,0 +1,257 @@
+import { execFile as nodeExecFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { connectHostedProjectMemory } from './init.js';
+import { parseSimpleYaml } from './simple-yaml.js';
+import { resolveSyncBinding } from './sync-binding.js';
+import {
+  credentialStoreOptionsFrom,
+  normalizeApiUrl,
+  storeSyncCredential,
+} from './credential-store.js';
+import { PACKAGE_VERSION } from './version.js';
+
+/**
+ * Browser device-code sign-in for hosted sync (D-355).
+ *
+ * The CLI asks the hosted app for a device code, shows (and opens) the
+ * verification link plus a short user code, and polls until the signed-in
+ * project owner approves the code in the dashboard. The claim response is the
+ * only place the plaintext token ever exists: the CLI stores it in the local
+ * credential store and, when the root has no sync binding yet, writes the
+ * non-secret binding into project.yaml exactly as `connect-hosted` would.
+ */
+
+export const DEFAULT_HOSTED_API_URL = 'https://vibecompass.dev';
+export const DEFAULT_SYNC_CREDENTIAL_ENV_VAR = 'VIBECOMPASS_SYNC_TOKEN';
+export const DEVICE_AUTH_START_ROUTE = 'api/cli/device-auth';
+export const DEVICE_AUTH_TOKEN_ROUTE = 'api/cli/device-auth/token';
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const DEFAULT_POLL_TIMEOUT_SECONDS = 600;
+const REQUEST_TIMEOUT_MS = 15_000;
+const VALID_MODES = new Set(['local-only', 'local-primary', 'hosted-only']);
+
+export async function loginHosted(options = {}, environment = {}) {
+  const cwd = environment.cwd ? path.resolve(environment.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options.rootDir ?? '.compass');
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  const io = environment.io ?? {};
+  const write = (text) => (io.stdout ?? process.stdout).write(text);
+  const fetchImpl = environment.runtime?.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('login requires a fetch implementation.');
+  }
+  const sleep = environment.runtime?.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = environment.runtime?.now ?? (() => Date.now());
+
+  let project;
+  try {
+    project = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), { sourceName: projectFilePath });
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      throw new Error(`No project.yaml found in ${rootDir}. Run "vibecompass init" first, then "vibecompass login".`);
+    }
+    throw error;
+  }
+  if (!VALID_MODES.has(project.mode)) {
+    throw new Error('login requires project.yaml mode to be local-only, local-primary, or hosted-only.');
+  }
+
+  const binding = resolveLoginBinding(project, options);
+  const apiUrl = binding?.apiUrl ?? options.apiUrl ?? DEFAULT_HOSTED_API_URL;
+  if (binding && options.apiUrl && normalizeApiUrl(options.apiUrl) !== normalizeApiUrl(binding.apiUrl)) {
+    throw new Error(
+      `--api-url ${options.apiUrl} does not match the bound hosted URL ${binding.apiUrl}${binding.target ? ` for target ${binding.target}` : ''}. `
+      + 'Pass --sync-target <name> to sign in to a different environment, or rebind with connect-hosted.',
+    );
+  }
+  const projectHint = binding?.projectId ?? options.projectId ?? null;
+  const credentialEnvVar = binding?.credentialEnvVar ?? options.credentialEnvVar ?? DEFAULT_SYNC_CREDENTIAL_ENV_VAR;
+
+  // Every network wait (start, each poll, and body reads) is bounded by the
+  // overall deadline so a stalled server can never outlive --poll-timeout.
+  const requestedTimeoutSeconds = positiveNumber(options.pollTimeoutSeconds, DEFAULT_POLL_TIMEOUT_SECONDS);
+  let deadline = now() + requestedTimeoutSeconds * 1000;
+  const timing = { now, deadline: () => deadline };
+
+  const start = await postJson(fetchImpl, apiUrl, DEVICE_AUTH_START_ROUTE, {
+    ...(projectHint ? { project_id: projectHint } : {}),
+    label: options.label ?? os.hostname(),
+    package_version: PACKAGE_VERSION,
+  }, timing);
+  if (!start.ok) {
+    throw new Error(`Hosted sign-in could not start (HTTP ${start.status}${start.body?.error ? `: ${start.body.error}` : ''}). Check the hosted URL ${apiUrl} and try again.`);
+  }
+  const deviceCode = requireString(start.body, 'device_code');
+  const userCode = requireString(start.body, 'user_code');
+  const verificationUri = requireString(start.body, 'verification_uri_complete', 'verification_uri');
+  const expiresIn = positiveNumber(start.body.expires_in, DEFAULT_POLL_TIMEOUT_SECONDS);
+  let intervalMs = positiveNumber(start.body.interval, DEFAULT_POLL_INTERVAL_SECONDS) * 1000;
+
+  write('Sign in to VibeCompass\n');
+  write(`Open: ${verificationUri}\n`);
+  write(`Code: ${userCode}\n`);
+  if (!options.noBrowser) {
+    const opened = await openBrowser(verificationUri, environment);
+    write(opened ? 'Opening your browser…\n' : 'Could not open a browser automatically; paste the link into any browser.\n');
+  }
+  write(`Waiting for approval in the dashboard (expires in ${Math.round(expiresIn / 60)} minutes)…\n`);
+
+  deadline = Math.min(deadline, now() + expiresIn * 1000);
+  let claim = null;
+  while (!claim) {
+    const remaining = deadline - now();
+    if (remaining <= 0) {
+      throw new Error('Timed out waiting for the sign-in to be approved. Run "vibecompass login" again.');
+    }
+    await sleep(Math.min(intervalMs, remaining));
+    const poll = await postJson(fetchImpl, apiUrl, DEVICE_AUTH_TOKEN_ROUTE, { device_code: deviceCode }, timing);
+    if (poll.ok && poll.body?.status === 'approved') {
+      claim = poll.body;
+      break;
+    }
+    const code = typeof poll.body?.error === 'string' ? poll.body.error : null;
+    if (code === 'authorization_pending') {
+      continue;
+    }
+    if (code === 'slow_down') {
+      intervalMs += 5000;
+      continue;
+    }
+    if (code === 'expired_token') {
+      throw new Error('The sign-in code expired before it was approved. Run "vibecompass login" again.');
+    }
+    if (code === 'access_denied') {
+      throw new Error('The sign-in request was denied in the dashboard.');
+    }
+    throw new Error(`Hosted sign-in failed (HTTP ${poll.status}${code ? `: ${code}` : ''}).`);
+  }
+
+  const token = requireString(claim, 'token');
+  const approvedProject = claim.project && typeof claim.project === 'object' ? claim.project : {};
+  const projectId = requireString(approvedProject, 'id');
+  const projectName = typeof approvedProject.name === 'string' ? approvedProject.name : projectId;
+
+  const stored = await storeSyncCredential(
+    {
+      apiUrl,
+      projectId,
+      token,
+      label: `VibeCompass sync token (${projectName})`,
+      source: 'login',
+      backend: options.credentialStore,
+    },
+    credentialStoreOptionsFrom(environment),
+  );
+
+  const warnings = [];
+  let bindingWritten = null;
+  if (!binding) {
+    bindingWritten = await connectHostedProjectMemory({
+      cwd,
+      rootDir: options.rootDir ?? '.compass',
+      ...(options.syncTarget ? { targetName: options.syncTarget } : {}),
+      sync: { apiUrl, projectId, credentialEnvVar },
+    });
+  } else if (binding.projectId !== projectId) {
+    warnings.push(
+      `This root is bound to project ${binding.projectId}${binding.target ? ` (target ${binding.target})` : ''}, but you approved ${projectName} (${projectId}). `
+      + `The token is stored for the approved project; rebind with "vibecompass connect-hosted${binding.target ? ` --target ${binding.target}` : ''} --sync-api-url ${apiUrl} --sync-project-id ${projectId} --sync-credential-env-var ${credentialEnvVar}" if that was intended.`,
+    );
+  }
+
+  return {
+    apiUrl,
+    project: { id: projectId, name: projectName },
+    credential: claim.credential && typeof claim.credential === 'object' ? claim.credential : null,
+    stored,
+    binding: bindingWritten,
+    previousBinding: binding,
+    mode: bindingWritten?.mode ?? project.mode,
+    warnings,
+  };
+}
+
+function resolveLoginBinding(project, options) {
+  try {
+    return resolveSyncBinding(project, options.syncTarget ?? null);
+  } catch (error) {
+    // An unknown --sync-target may be created by login only when the caller
+    // is explicit about which hosted environment it points at (D-236: a typo
+    // must never silently land in another environment).
+    if (options.syncTarget && options.apiUrl) {
+      return null;
+    }
+    throw new Error(`${error.message} To create it through login, add --api-url <hosted url>.`);
+  }
+}
+
+async function postJson(fetchImpl, apiUrl, routeName, body, timing) {
+  const endpoint = new URL(routeName, apiUrl.endsWith('/') ? apiUrl : `${apiUrl}/`);
+  const remaining = timing ? timing.deadline() - timing.now() : REQUEST_TIMEOUT_MS;
+  if (remaining <= 0) {
+    throw new Error('Timed out waiting for the sign-in to be approved. Run "vibecompass login" again.');
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.min(REQUEST_TIMEOUT_MS, remaining));
+  try {
+    let response;
+    try {
+      response = await fetchImpl(endpoint.href, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new Error(`Hosted sign-in request to ${endpoint.origin} timed out. Check the connection and run "vibecompass login" again.`);
+      }
+      throw new Error(`Could not reach ${endpoint.origin} (${error?.message ?? 'network error'}).`);
+    }
+    let parsed = null;
+    try {
+      parsed = typeof response.json === 'function' ? await response.json() : null;
+    } catch {
+      if (controller.signal.aborted) {
+        throw new Error(`Hosted sign-in response from ${endpoint.origin} stalled. Check the connection and run "vibecompass login" again.`);
+      }
+      parsed = null;
+    }
+    return { ok: Boolean(response.ok), status: response.status, body: parsed && typeof parsed === 'object' ? parsed : {} };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function openBrowser(url, environment) {
+  const platform = environment.runtime?.platform ?? process.platform;
+  const execFileImpl = environment.runtime?.execFile ?? nodeExecFile;
+  const [file, args] = platform === 'darwin'
+    ? ['open', [url]]
+    : platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+  return new Promise((resolve) => {
+    try {
+      execFileImpl(file, args, { windowsHide: true }, (error) => resolve(!error));
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+function requireString(source, ...keys) {
+  for (const key of keys) {
+    const value = source?.[key];
+    if (typeof value === 'string' && value.trim() !== '') {
+      return value.trim();
+    }
+  }
+  throw new Error(`Hosted sign-in response is missing ${keys[0]}.`);
+}
+
+function positiveNumber(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+}

package/src/mode-transition.js

@@ -2,6 +2,11 @@ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { resolveSyncBinding } from './sync-binding.js';
+import {
+  credentialStoreOptionsFrom,
+  formatMissingCredentialError,
+  resolveSyncCredential,
+} from './credential-store.js';
 import { withMemoryRootLock } from './serialization.js';
 import { adoptRemoteHead, pushProjectMemory } from './sync.js';
 
@@ -186,9 +191,10 @@ async function loadModeAgnosticSyncContext(rootDir, options, environment) {
   if (!binding) {
     throw new Error('Mode transitions require a sync binding in project.yaml (run connect-hosted first).');
   }
-  const credential = ((environment.env ?? process.env)[binding.credentialEnvVar] ?? '').trim();
+  const resolution = await resolveSyncCredential(binding, credentialStoreOptionsFrom(environment));
+  const credential = resolution.credential;
   if (!credential) {
-    throw new Error(`Mode transitions require ${binding.credentialEnvVar} to be set.`);
+    throw new Error(formatMissingCredentialError(binding, { action: 'This mode transition', detail: resolution.detail }));
   }
   const fetchImpl = environment.runtime?.fetch ?? globalThis.fetch;
   if (typeof fetchImpl !== 'function') {

package/src/project-memory.js

@@ -1,5 +1,6 @@
 import { readFile, readdir } from 'node:fs/promises';
 import path from 'node:path';
+import { validateBriefSettings } from './brief-settings.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { sha256Text } from './hash.js';
 import { parseSimpleYaml } from './simple-yaml.js';
@@ -44,6 +45,7 @@ const KNOWN_PROJECT_FIELDS = new Set([
   'default_branch',
   'sync',
   'runtime',
+  'brief',
   'metadata',
 ]);
 // D-282 runtime-isolation settings; deep value validation (ranges, absolute
@@ -73,9 +75,16 @@ const SECRET_BEARING_SYNC_FIELDS = [
   'access_token',
 ];
 
-export async function scanProjectMemory(rootDir) {
+/**
+ * Scans a memory root's canonical documents. `options.exclude` is an optional
+ * predicate over root-relative paths (D-364, session brief exclusions): an
+ * excluded markdown file is dropped from the directory walk before it is
+ * opened, so it is never read. `project.yaml` is always read.
+ */
+export async function scanProjectMemory(rootDir, options = {}) {
   const errors = [];
   const documents = [];
+  const isExcluded = typeof options.exclude === 'function' ? options.exclude : () => false;
 
   const projectPath = path.join(rootDir, PROJECT_FILE);
   const projectDocument = await parseProjectDocument(rootDir, projectPath);
@@ -87,7 +96,8 @@ export async function scanProjectMemory(rootDir) {
   const architectureDocuments = await parseMarkdownTree({
     rootDir,
     directoryName: 'architecture',
-    shouldInclude: (filename) => !NON_CANONICAL_ARCHITECTURE_FILES.has(filename),
+    shouldInclude: (filename, relativePath) =>
+      !NON_CANONICAL_ARCHITECTURE_FILES.has(filename) && !isExcluded(relativePath),
     parseDocument: (documentPath, relativePath, content) =>
       parseArchitectureDocument({
         content,
@@ -99,7 +109,8 @@ export async function scanProjectMemory(rootDir) {
   const decisionDocuments = await parseMarkdownTree({
     rootDir,
     directoryName: 'decisions',
-    shouldInclude: (filename) => !NON_CANONICAL_DECISION_FILES.has(filename),
+    shouldInclude: (filename, relativePath) =>
+      !NON_CANONICAL_DECISION_FILES.has(filename) && !isExcluded(relativePath),
     parseDocument: (documentPath, relativePath, content) =>
       parseDecisionDocument({
         content,
@@ -115,7 +126,9 @@ export async function scanProjectMemory(rootDir) {
     // fail-close the whole scan as a malformed session note. The filename set
     // still covers the legacy root-level wip.md/handoff.md.
     shouldInclude: (filename, relativePath) =>
-      !NON_CANONICAL_SESSION_FILES.has(filename) && !relativePath.startsWith('sessions/active/'),
+      !NON_CANONICAL_SESSION_FILES.has(filename) &&
+      !relativePath.startsWith('sessions/active/') &&
+      !isExcluded(relativePath),
     parseDocument: (documentPath, relativePath, content) =>
       parseSessionDocument({
         content,
@@ -371,6 +384,19 @@ function validateProjectData(data, relativePath) {
     }
   }
 
+  // D-364 session brief settings; the brief fails closed on any problem, so
+  // each one is surfaced here rather than silently ignored.
+  if (data.brief !== undefined) {
+    for (const problem of validateBriefSettings(data.brief).problems) {
+      warnings.push(
+        createWarning(
+          'project-brief-invalid',
+          `project.yaml brief settings: ${problem}. Session briefs read no canonical document until this is fixed (D-364).`,
+        ),
+      );
+    }
+  }
+
   if (data.metadata !== undefined && JSON.stringify(data.metadata).length > 500) {
     warnings.push(
       createWarning(

package/src/read-model.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { buildDecisionLineageModel, collectDeclaredSuccessors } from './decision-lineage.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { generateStateManifest } from './manifest.js';
 import { scanProjectMemory } from './project-memory.js';
@@ -8,7 +9,19 @@ const SECTION_PATTERN = /^##\s+(.+)$/gm;
 const DECISION_HEADING_PATTERN = /^###\s+D-(\d{3,})\s+—\s+(.+)$/gm;
 
 export async function loadProjectReadModel(rootDir) {
-  const scanResult = await scanProjectMemory(rootDir);
+  return (await loadProjectReadModelWithDocuments(rootDir)).readModel;
+}
+
+/**
+ * The read model plus the scanned canonical documents (`{ path, kind,
+ * content, … }`) it was built from, for read-only consumers such as the
+ * session brief that need section text the read model does not keep.
+ * `options.exclude` (a root-relative path predicate) keeps excluded documents
+ * out of the scan before they are read (D-364); `loadProjectReadModel` never
+ * excludes.
+ */
+export async function loadProjectReadModelWithDocuments(rootDir, options = {}) {
+  const scanResult = await scanProjectMemory(rootDir, { exclude: options.exclude });
   if (scanResult.errors.length > 0) {
     const details = scanResult.errors.map((error) => `${error.path}: ${error.message}`).join('\n');
     throw new Error(`Cannot build read model with canonical parse errors.\n${details}`);
@@ -35,8 +48,9 @@ export async function loadProjectReadModel(rootDir) {
   const decisions = buildDecisionList(scanResult);
   const sessions = buildSessionList(scanResult);
   const fileOwners = buildFileOwnershipIndex(features);
+  const decisionLineage = buildDecisionLineageModel(scanResult.documents);
 
-  return {
+  const readModel = {
     freshness,
     repo_aliases: repoAliases,
     manifest_state: {
@@ -51,7 +65,10 @@ export async function loadProjectReadModel(rootDir) {
     decisions,
     sessions,
     file_owners: fileOwners,
+    decision_lineage: decisionLineage,
   };
+
+  return { readModel, documents: scanResult.documents };
 }
 
 export function getProjectContext(readModel, options = {}) {
@@ -90,6 +107,50 @@ export function getDecisionLog(readModel, options = {}) {
   };
 }
 
+/**
+ * Typed lineage for one decision (plan task A2; D-359). `outgoing` is what
+ * this decision's own text declares about earlier decisions, `incoming` is
+ * 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.
+ */
+export function getDecisionLineage(readModel, decisionId, options = {}) {
+  const id = typeof decisionId === 'number' ? decisionId : Number(String(decisionId ?? '').replace(/^D-/i, ''));
+  if (!Number.isInteger(id) || id <= 0) {
+    return null;
+  }
+
+  const citationLimit = Math.max(1, Math.min(options.citationLimit ?? 50, 500));
+  const relations = readModel.decision_lineage.relations;
+  const decision = readModel.decisions.find((entry) => entry.decision_id === id) ?? null;
+  const lineageRelations = new Set(['supersedes', 'amends', 'preserves', 'unknown']);
+  const outgoing = relations.filter(
+    (relation) => relation.source_decision_id === id && lineageRelations.has(relation.relation),
+  );
+  const incoming = relations.filter(
+    (relation) =>
+      relation.target_decision_id === id && relation.source_kind === 'decision' && lineageRelations.has(relation.relation),
+  );
+  const mentions = relations.filter(
+    (relation) => relation.target_decision_id === id && ['cites', 'references', 'made'].includes(relation.relation),
+  );
+
+  return {
+    freshness: readModel.freshness,
+    decision_id: id,
+    exists: Boolean(decision),
+    title: decision?.title ?? null,
+    path: decision?.path ?? null,
+    outgoing,
+    incoming,
+    declared_successors: collectDeclaredSuccessors(relations, id),
+    made_in: mentions.filter((relation) => relation.relation === 'made').map((relation) => relation.source_path),
+    cited_by: mentions.filter((relation) => relation.relation !== 'made').slice(0, citationLimit),
+    cited_by_total: mentions.filter((relation) => relation.relation !== 'made').length,
+  };
+}
+
 export function getFileContext(readModel, filepath) {
   const normalizedPath = normalizeLookupPath(filepath, readModel.repo_aliases, readModel.project.repos);
   const owners = readModel.file_owners.get(normalizedPath) ?? [];
@@ -194,6 +255,8 @@ function buildComponentRecord(document, repoAliases, projectRepos) {
     description: normalizeSectionText(sections.get('Description')),
     details: normalizeSectionText(sections.get('Details')),
     next_steps: normalizeSectionText(sections.get('Next steps')),
+    retrieval_guidance: normalizeSectionText(sections.get('Retrieval guidance')),
+    retrieval_scope: extractReviewMetadataField(sections.get('Review metadata'), 'Retrieval scope'),
     involved_files: involvedFiles,
     warnings: document.warnings,
     warning_count: document.warnings.length,
@@ -529,6 +592,33 @@ function normalizeSectionText(value) {
   return value ? value.trim() : null;
 }
 
+// One bullet from the `## Review metadata` list ("- Retrieval scope: …"),
+// including indented continuation lines; null when the section or bullet is
+// missing or empty.
+function extractReviewMetadataField(section, label) {
+  if (!section) {
+    return null;
+  }
+
+  const lines = section.split(/\r?\n/);
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const start = lines.findIndex((line) => new RegExp(`^\\s*[-*]\\s+${escaped}:`, 'i').test(line));
+  if (start === -1) {
+    return null;
+  }
+
+  const parts = [lines[start].replace(new RegExp(`^\\s*[-*]\\s+${escaped}:\\s*`, 'i'), '')];
+  for (const line of lines.slice(start + 1)) {
+    if (!/^\s+\S/.test(line) || /^\s*[-*]\s+/.test(line)) {
+      break;
+    }
+    parts.push(line.trim());
+  }
+
+  const value = parts.join(' ').trim();
+  return value || null;
+}
+
 function extractLabeledValue(body, label) {
   const pattern = new RegExp(`\\*\\*${label}:\\*\\*\\s+(.+)`);
   return body.match(pattern)?.[1]?.trim() ?? null;