@vibecompass/vibecompass 0.15.0 → 0.16.0

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

@@ -47,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/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;

package/src/scaffold.js

@@ -226,6 +226,7 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 - \`${rootRelativePath}/sessions/active/<lane-id>/session.yaml\` — lane metadata (including the recorded \`lane_marker\` when one exists)
 - \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\` — lane-local builder scratchpad
 - \`${rootRelativePath}/sessions/active/<lane-id>/handoff.md\` — lane-local builder/reviewer relay
+- \`${rootRelativePath}/sessions/active/<lane-id>/brief.md\` — generated session brief (D-359, D-364): the memory this lane should read first, written by \`start-session\` and \`continue-session\` when \`brief.enabled: true\` (opt-in, D-368) or on request with \`vibecompass brief --write\`; never hand-edit
 - \`.vibecompass-lane.yaml\` — worktree-local lane marker (D-280); lives outside the memory root, written only by \`vibecompass write-lane-marker\` or worktree provisioning, never synced
 - \`${rootRelativePath}/decisions/INDEX.md\` — derived grouped decision index; refresh with \`vibecompass refresh-decision-index\` (D-283, structure-preserving) instead of hand-editing rows
 
@@ -233,6 +234,7 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 - VibeCompass active builder sessions are named lanes. Use one lane per active feature or workstream.
 - \`vibecompass start-session\` requires \`--id <lane-id>\` so each active lane has a meaningful feature or workstream name.
 - The active lane scratch files live under \`${rootRelativePath}/sessions/active/<lane-id>/\`.
+- When \`${rootRelativePath}/project.yaml\` sets \`brief.enabled: true\` (opt-in, D-368), \`start-session\` and \`continue-session\` write the lane's generated \`brief.md\` (D-359, D-364): the task is the lane's working-on, the files its claims, and the features its feature slugs. A brief failure is reported as a warning or an incomplete brief and never fails the lifecycle command. \`--no-brief\` skips it for one command, \`vibecompass brief --session <lane-id> --write\` writes one on request whatever the setting, and \`brief.exclude\` lists root-relative globs the brief must never read.
 - Lane selection follows D-277: an explicit \`--session\` wins, then the nearest worktree lane marker (\`.vibecompass-lane.yaml\`, walking up from cwd), then the single active lane. With two or more active lanes there is no implicit current-lane fallback.
 - \`${rootRelativePath}/sessions/active/index.yaml\` is the lane inventory; its \`current\` pointer and the tool-specific Current session block are human-readable continuity summaries, not the lane-selection source of truth.
 - An active lane directory is an open session, not an unclosed crash (D-353). Resume it with \`vibecompass continue-session [<lane-id>]\`: the lane keeps its opening date and session number; the command records \`resumed_at\`/\`resume_count\` in \`session.yaml\`, appends a dated \`Resumed\` line to \`wip.md\`, moves the index \`current\` hint and the Current session block to the lane, and re-emits runtime, git-binding, and staleness warnings. \`start-session --id <existing-lane>\` fails closed and names \`continue-session\`.
@@ -276,7 +278,8 @@ ${renderWorkflowDefaults(workflow)}
 3. Inventory active lanes with \`vibecompass list-sessions\` (or read \`${rootRelativePath}/sessions/active/index.yaml\`), then follow the "Open, resume, or choose" protocol below to decide between opening a new lane and resuming one; select a lane from an explicit \`--session\`, the nearest worktree lane marker, or the single active lane (D-277).
 4. If present, read \`${rootRelativePath}/sessions/active/<lane-id>/wip.md\`.
 5. If present, read \`${rootRelativePath}/sessions/active/<lane-id>/handoff.md\`.
-6. Read the relevant docs under \`${rootRelativePath}/architecture/\` and \`${rootRelativePath}/decisions/\`.
+6. If present, read \`${rootRelativePath}/sessions/active/<lane-id>/brief.md\` before planning: the generated session brief selects the architecture docs, decisions (with their declared successors), and notes for the lane's task. Its status line says whether it is complete, partial, incomplete (read the listed required reads first), or no-match; \`vibecompass brief --check\` reports whether it is stale.
+7. Read the relevant docs under \`${rootRelativePath}/architecture/\` and \`${rootRelativePath}/decisions/\`, starting from the brief's units and follow-up reads.
 
 ## Open, resume, or choose (D-353)
 Both \`start session\` and \`continue session\` begin with the active-lane inventory. Then:
@@ -284,7 +287,7 @@ Both \`start session\` and \`continue session\` begin with the active-lane inven
 - **Exactly one active lane, or a cwd bound to a lane by a worktree marker:** resume it with \`vibecompass continue-session\` without asking. Open a second lane only when the user is clearly asking for separate new work; never re-open a lane that already exists.
 - **Two or more active lanes, no marker, no lane named by the user:** do not guess. Present the inventory (lane id, working-on, opened date, resume count, branch/worktree, last log line) and ask which lane to continue or whether to open a new one. The index \`current\` pointer and the Current session block are continuity hints to mention, never defaults to adopt silently. Resume with \`vibecompass continue-session <lane-id>\` once the user answers (\`continue session <lane-id>\`).
 - **Lane named by the user:** \`continue session <lane-id>\` resumes that lane; an unknown id fails closed with the inventory.
-- After resuming, read the lane's \`wip.md\` (latest \`## Log\` entries and \`## Reviewer input needed\`), \`handoff.md\`, and the latest finalized note; treat resume-staleness warnings (new decisions past the lane snapshot, stale base revisions, newer finalized notes touching the lane scope, claim overlap) as required reading before editing.
+- After resuming, read the lane's \`wip.md\` (latest \`## Log\` entries and \`## Reviewer input needed\`), \`handoff.md\`, \`brief.md\` if present (with \`brief.enabled: true\`, continue-session keeps a current brief and regenerates a missing or stale one), and the latest finalized note; treat resume-staleness warnings (new decisions past the lane snapshot, stale base revisions, newer finalized notes touching the lane scope, claim overlap) as required reading before editing.
 - Run recovery (reconstruct a missing finalized note from git history) only when the Current session block date is in the past *and* no active lane exists *and* no finalized note covers that date. An active lane with a past date is simply resumable.
 
 ## Builder workflow
@@ -302,6 +305,8 @@ Session lane: <lane-id>
 
 ## Reviewer input needed
 
+## Context used
+
 ## Review log
 \`\`\`
 
@@ -330,6 +335,8 @@ Session lane: <lane-id>
 During the session:
 - append short summaries to \`wip.md\` after meaningful exchanges
 - keep \`handoff.md\` current after substantive work blocks
+- optionally list under \`wip.md\` \`## Context used\` the docs and decisions the lane actually relied on (path or D-number, and what for), so the brief's usefulness can be audited
+- refresh the lane brief with \`vibecompass brief --write\` after the lane's scope changes; \`vibecompass brief --check\` reports whether it is stale
 - run \`eval "$(vibecompass lane-env)"\` in a lane shell before starting dev servers or build tools so the lane's assigned port and temp dir are used (D-282); do not hardcode ports in lane work
 - run \`vibecompass docs-update --session <lane-id>\` whenever you need an ad hoc targeted documentation-maintenance plan for the current session delta
 - after substantive feature work, confirm affected architecture docs and decisions still match the implementation; if not, update them while the context is fresh — fold the changes into the doc's current-state sections (rewrite in place; no dated "update" sections, lane names in headings, or completed-task chronology; D-292)
@@ -588,6 +595,7 @@ Finalized session notes for ${projectConfig.name} live here.
 - \`active/<lane-id>/session.yaml\` — lane metadata, including the recorded \`lane_marker\` when one exists
 - \`active/<lane-id>/wip.md\` — builder scratchpad during an active lane
 - \`active/<lane-id>/handoff.md\` — reviewer/builder baton-pass during an active lane
+- \`active/<lane-id>/brief.md\` — generated session brief for the lane (D-359, D-364); regenerated, never hand-edited
 
 Those scratch files are session-scoped working artifacts, not finalized history.
 `;

package/src/session.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { access, mkdir, readFile, readdir, realpath, rm, rmdir, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { refreshLaneBriefForLifecycle } from './brief-lifecycle.js';
 import { scanProjectMemory } from './project-memory.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import { buildCloseSessionGuidance, resolveWorkflowSettings } from './workflow.js';
@@ -398,6 +399,16 @@ async function startProjectSessionLocked(normalized, options, markerContext) {
     rootDir: normalized.rootDir,
     toolingRootDir: normalized.toolingRootDir,
   });
+  // D-359/D-364/D-368: the opt-in lane brief is written only after every
+  // lifecycle write succeeded, still inside the memory-root lock; it never
+  // throws, so a brief failure cannot overturn the start.
+  const brief = await refreshLaneBriefForLifecycle({
+    trigger: 'start',
+    rootDir: normalized.rootDir,
+    laneId: sessionId,
+    disabled: options?.brief === false,
+    buildBrief: options?.briefBuilder,
+  });
 
   return {
     rootDir: normalized.rootDir,
@@ -420,7 +431,9 @@ async function startProjectSessionLocked(normalized, options, markerContext) {
       ...(gitBinding?.warnings ?? []),
       ...manifestRefresh.warnings,
       ...auditWarnings,
+      ...brief.warnings,
     ],
+    brief,
     ...(gitBinding
       ? {
           gitBinding: {
@@ -1145,6 +1158,18 @@ async function continueProjectSessionLocked(normalized, options, markerContext)
     rootDir: normalized.rootDir,
     toolingRootDir: normalized.toolingRootDir,
   });
+  // D-359/D-364: keep a current lane brief, regenerate a missing or stale
+  // one. `--source-root` (D-255 dogfood) is read only when named here; it is
+  // never inferred from the existing brief's header.
+  const brief = await refreshLaneBriefForLifecycle({
+    trigger: 'continue',
+    rootDir: normalized.rootDir,
+    laneId: lane.id,
+    disabled: options?.brief === false,
+    sourceRootDir: options?.sourceRootDir ? path.resolve(normalized.cwd, options.sourceRootDir) : undefined,
+    sourceSessionId: normalizeOptionalString(options?.sourceSessionId) ?? undefined,
+    buildBrief: options?.briefBuilder,
+  });
   const finalizedSessions = await listFinalizedSessions(normalized.sessionsDir);
   const latestFinalized = finalizedSessions.length > 0 ? finalizedSessions[finalizedSessions.length - 1] : null;
   // The returned inventory is the post-resume state (what list-sessions shows
@@ -1181,6 +1206,7 @@ async function continueProjectSessionLocked(normalized, options, markerContext)
     otherLanes: inventoryAfter.lanes.filter((item) => item.id !== lane.id),
     inventory: inventoryAfter,
     docsUpdatePlan: docsUpdate.plan,
+    brief,
     warnings: [
       ...markerContext.warnings,
       ...selection.warnings,
@@ -1196,6 +1222,7 @@ async function continueProjectSessionLocked(normalized, options, markerContext)
       }),
       ...docsUpdate.warnings,
       ...manifestRefresh.warnings,
+      ...brief.warnings,
     ],
     manifest: manifestRefresh.manifest,
     agentFileSync,
@@ -2279,6 +2306,9 @@ ${options.workingOn}
 ## Reviewer input needed
 - None yet.
 
+## Context used
+- Optional: the docs and decisions this lane actually relied on (path or D-number, and what for) — an audit trail for the session brief; list what you used, not everything the brief showed.
+
 ## Review log
 `;
 }