cap-pro 1.0.0

package/hooks/dist/cap-learn-review-hook.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// @cap-feature(feature:F-073) Learn-Review Stop-Hook — flags pending pattern reviews after each session.
+//                              Fires AFTER cap-memory's Stop hook (memory pipeline → learn pipeline →
+//                              review board). cap-hook-version: {{CAP_VERSION}}
+//
+// Stop hook: at session end, compute shouldShowBoard(projectRoot). If the gate is met, write
+// .cap/learning/board-pending.flag so /cap:status (and the next /cap:learn review run) can surface
+// the pending review. We DO NOT spawn the skill from the hook — Claude Code hook subprocesses can't
+// drive an interactive review flow.
+//
+// Skip via CAP_SKIP_LEARN_REVIEW_HOOK=1.
+// Never exits non-zero: a failure here must not block the user's session end.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// @cap-todo(ac:F-073/AC-3) Skip switch — keep parity with cap-learning-hook.js / cap-memory.js so
+//                          ops can disable a single learning hook without touching the others.
+if (process.env.CAP_SKIP_LEARN_REVIEW_HOOK === '1') {
+  process.exit(0);
+}
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  run(input);
+});
+
+function tryRequire(modulePath) {
+  try { return require(modulePath); } catch { return null; }
+}
+
+// @cap-decision(F-073/D1) Lib resolution mirrors cap-learning-hook.js exactly: env override →
+//                  colocated in-tree → installed under ~/.claude. Keeps every CAP hook on the same
+//                  resolution path so an ops change to one hook applies to the others for free.
+function resolveReviewModule() {
+  const candidates = [];
+  if (process.env.CAP_LEARN_REVIEW_LIB) candidates.push(process.env.CAP_LEARN_REVIEW_LIB);
+  candidates.push(path.join(__dirname, '..', 'cap', 'bin', 'lib', 'cap-learn-review.cjs'));
+  candidates.push(path.join(os.homedir(), '.claude', 'cap', 'bin', 'lib', 'cap-learn-review.cjs'));
+  for (const p of candidates) {
+    const mod = tryRequire(p);
+    if (mod) return mod;
+  }
+  return null;
+}
+
+function run(raw) {
+  // @cap-todo(ac:F-073/AC-3) Whole hook body wrapped in try/catch; failures never escape.
+  try {
+    const data = raw ? JSON.parse(raw) : {};
+    const cwd = data.cwd || process.cwd();
+
+    const review = resolveReviewModule();
+    if (!review) process.exit(0); // library not installed — silent no-op (mirrors cap-memory.js).
+
+    // Compute the gate. shouldShowBoard reads SESSION.json internally for the per-session skip/reject
+    // sets — no need to pass anything explicit here.
+    let shouldShow = false;
+    try {
+      shouldShow = review.shouldShowBoard(cwd) === true;
+    } catch (_e) {
+      shouldShow = false;
+    }
+
+    if (!shouldShow) {
+      // Below threshold — NO flag. If a stale flag from a prior session is on disk we leave it
+      // alone here; /cap:learn review clears it after the user processes the board, and a fresh
+      // shouldShowBoard==false simply means there's nothing new to add.
+      process.exit(0);
+    }
+
+    // Threshold met — write the flag. Eligible count is recomputed for diagnostic purposes;
+    // the SKILL checks for FILE EXISTENCE, not content, so a half-written flag is harmless.
+    let eligibleCount = 0;
+    try {
+      const board = review.buildReviewBoard(cwd);
+      if (board && Array.isArray(board.eligible)) eligibleCount = board.eligible.length;
+    } catch (_e) {
+      eligibleCount = 0;
+    }
+
+    // @cap-risk(F-073/AC-3) writeBoardPendingFlag sanitises sessionId before persistence so a
+    //                       hostile SESSION.json can't smuggle bytes via the flag content.
+    review.writeBoardPendingFlag(cwd, { eligibleCount });
+    process.exit(0);
+  } catch (_err) {
+    // Best-effort error log to .cap/learning/.errors.log so we can diagnose without leaking
+    // through the tool surface. Mirrors cap-learning-hook.js's error-log strategy.
+    try {
+      const cwd = process.cwd();
+      const errDir = path.join(cwd, '.cap', 'learning');
+      if (!fs.existsSync(errDir)) fs.mkdirSync(errDir, { recursive: true });
+      fs.appendFileSync(
+        path.join(errDir, '.errors.log'),
+        JSON.stringify({
+          ts: new Date().toISOString(),
+          hook: 'cap-learn-review-hook',
+          message: _err && _err.message ? _err.message : String(_err),
+        }) + '\n',
+        'utf8',
+      );
+    } catch {
+      // Even logging failed — stay silent.
+    }
+    process.exit(0);
+  }
+}

package/hooks/dist/cap-learning-hook.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// @cap-feature(feature:F-070) Learning-Signals Hook — PostToolUse entry point for AC-1 (editAfterWrite)
+//                              and AC-2 (memory-ref). cap-hook-version: {{CAP_VERSION}}
+//
+// PostToolUse hook: fires after Edit / Write / MultiEdit / NotebookEdit / Read and emits learning
+// signals into .cap/learning/signals/<type>.jsonl via the cap-learning-signals.cjs collector.
+//
+// Two responsibilities:
+//   1. Cross-event editAfterWrite detection via a per-session persistent ledger
+//      (.cap/learning/signals/../state/written-files.jsonl). Hooks fire as fresh subprocesses, so an
+//      in-memory Set cannot bridge a Write event and a later Edit event — the ledger is the bridge.
+//      Write / MultiEdit / NotebookEdit append to the ledger; Edit checks the ledger and emits
+//      recordOverride({subType:'editAfterWrite'}) when there is a match for the same sessionId.
+//   2. When a Read targets any path under .cap/memory/**/*.md (recursive), emit recordMemoryRef.
+//
+// AC-5 budget: <50ms per hook. The collector is sync JSONL append. The ledger read happens here, but
+// the ledger is per-session (typical <100 lines) and we never read the signal JSONLs.
+//
+// Skip via CAP_SKIP_LEARNING_HOOK=1.
+// Never exits non-zero: a failure here must not block the edit/read tool.
+//
+// Reject-Approval (AC-1 second flavour) is left as an integration gap — Claude Code's PreToolUse
+// rejection signal is not observable from the matchers we have access to in this repo. See the
+// @cap-decision below and the @cap-todo on AC-1.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// @cap-todo(ac:F-070/AC-5) Skip switch for benchmarking and tests that don't want hook side effects.
+if (process.env.CAP_SKIP_LEARNING_HOOK === '1') {
+  process.exit(0);
+}
+
+// Edit handled separately from Write/MultiEdit/NotebookEdit: only the latter three "create new content"
+// in the file from the agent's perspective. An Edit is the user's correction. Both groups append to
+// the ledger so a chain Edit→Edit on a previously-written file still trips editAfterWrite.
+const WRITE_TOOLS = new Set(['Write', 'MultiEdit', 'NotebookEdit']);
+const EDIT_TOOL = 'Edit';
+const OBSERVED_WRITE_TOOLS = new Set([EDIT_TOOL, ...WRITE_TOOLS]);
+const OBSERVED_READ_TOOLS = new Set(['Read']);
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  run(input);
+});
+
+function tryRequire(modulePath) {
+  try { return require(modulePath); } catch { return null; }
+}
+
+// @cap-decision(F-070/D8) Lib resolution mirrors cap-tag-observer.js exactly: env override → colocated
+//                  in-tree → installed under ~/.claude. Keeping the resolution path identical means an
+//                  ops change to one hook applies to the other for free.
+function resolveCollectorModule() {
+  const candidates = [];
+  if (process.env.CAP_LEARNING_LIB) candidates.push(process.env.CAP_LEARNING_LIB);
+  candidates.push(path.join(__dirname, '..', 'cap', 'bin', 'lib', 'cap-learning-signals.cjs'));
+  candidates.push(path.join(os.homedir(), '.claude', 'cap', 'bin', 'lib', 'cap-learning-signals.cjs'));
+  for (const p of candidates) {
+    const mod = tryRequire(p);
+    if (mod) return mod;
+  }
+  return null;
+}
+
+// @cap-decision(F-070/D9) Session id resolution: read .cap/SESSION.json synchronously. The file is small
+//                  (~few hundred bytes) so the read is O(1) and well inside AC-5's 50ms budget.
+function readSessionContext(cwd) {
+  try {
+    const p = path.join(cwd, '.cap', 'SESSION.json');
+    if (!fs.existsSync(p)) return { sessionId: null, featureId: null };
+    const parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return {
+      sessionId: typeof parsed.sessionId === 'string' ? parsed.sessionId : null,
+      featureId: typeof parsed.activeFeature === 'string' ? parsed.activeFeature : null,
+    };
+  } catch { return { sessionId: null, featureId: null }; }
+}
+
+function isUnderMemoryDir(absPath, cwd) {
+  // Match any file under <cwd>/.cap/memory/ regardless of subdirectory or extension.
+  // The collector hashes the path; we just need a routing decision here.
+  const memoryRoot = path.join(cwd, '.cap', 'memory');
+  // Use startsWith with a path separator suffix to avoid matching e.g. .cap/memory-foo.
+  return absPath === memoryRoot
+    || absPath.startsWith(memoryRoot + path.sep)
+    || absPath.startsWith(memoryRoot + '/');
+}
+
+function run(raw) {
+  // @cap-todo(ac:F-070/AC-7) Whole hook body wrapped in try/catch; failures never escape.
+  try {
+    const data = raw ? JSON.parse(raw) : {};
+    const toolName = data.tool_name;
+    const toolInput = data.tool_input || {};
+    const cwd = data.cwd || process.cwd();
+    const filePath = toolInput.file_path || toolInput.notebook_path;
+    if (!toolName || !filePath) process.exit(0);
+
+    const absPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+
+    const collector = resolveCollectorModule();
+    if (!collector) process.exit(0); // library not installed — silent no-op, mirrors cap-memory.js
+
+    // @cap-todo(ac:F-070/AC-1) editAfterWrite detection across subprocess boundaries: the per-session
+    //                          ledger bridges what a single hook process cannot. Edit checks the ledger;
+    //                          all four tools append to the ledger so a subsequent Edit on the same path
+    //                          (this session) emits the override.
+    if (OBSERVED_WRITE_TOOLS.has(toolName)) {
+      const ctx = readSessionContext(cwd);
+      if (toolName === EDIT_TOOL && ctx.sessionId
+          && collector.wasWrittenInSession(cwd, ctx.sessionId, absPath)) {
+        // @cap-risk(F-070/AC-5) recordOverride is sync JSONL append, never reads signal JSONLs.
+        //                       The ledger read above IS in the hot path but stays bounded
+        //                       (per-session file, typical <100 entries). The performance suite
+        //                       brackets the full hook to confirm the 50ms budget holds.
+        collector.recordOverride({
+          projectRoot: cwd,
+          subType: 'editAfterWrite',
+          sessionId: ctx.sessionId,
+          featureId: ctx.featureId,
+          targetFile: absPath, // collector hashes; never persisted raw
+        });
+      }
+      // Append to the persistent ledger so future Edit events in this session can detect the chain.
+      // We append for ALL four tools (Edit included) so Edit→Edit on a previously-written file still
+      // produces an override on the second Edit.
+      if (ctx.sessionId) {
+        collector.recordWriteIntoLedger(cwd, ctx.sessionId, absPath);
+      }
+      process.exit(0);
+    }
+
+    // @cap-todo(ac:F-070/AC-2) memory-ref detection: a Read on .cap/memory/*.md → recordMemoryRef.
+    if (OBSERVED_READ_TOOLS.has(toolName)) {
+      if (!isUnderMemoryDir(absPath, cwd)) process.exit(0);
+      const ctx = readSessionContext(cwd);
+      collector.recordMemoryRef({
+        projectRoot: cwd,
+        sessionId: ctx.sessionId,
+        featureId: ctx.featureId,
+        memoryFile: absPath, // collector hashes
+      });
+      process.exit(0);
+    }
+
+    // Unobserved tool — exit silently.
+    process.exit(0);
+  } catch (_err) {
+    // AC-7: never propagate. Best-effort error log to .cap/learning/signals/.errors.log so we can
+    // diagnose without leaking through the tool surface.
+    try {
+      const cwd = process.cwd();
+      const errDir = path.join(cwd, '.cap', 'learning', 'signals');
+      if (!fs.existsSync(errDir)) fs.mkdirSync(errDir, { recursive: true });
+      fs.appendFileSync(
+        path.join(errDir, '.errors.log'),
+        JSON.stringify({
+          ts: new Date().toISOString(),
+          message: _err && _err.message ? _err.message : String(_err),
+        }) + '\n',
+        'utf8',
+      );
+    } catch {
+      // Even logging failed — stay silent.
+    }
+    process.exit(0);
+  }
+}
+
+// @cap-todo(ac:F-070/AC-1) Reject-Approval flavour of recordOverride is INTENTIONALLY UNWIRED here.
+// @cap-decision(F-070/D10) Reject-Approval is left as a documented integration gap.
+//   Why: PreToolUse rejection events in this repo's hook surface are not observable as a distinct
+//   tool_name / payload — the existing hooks (cap-prompt-guard, cap-workflow-guard) intercept BEFORE a
+//   tool runs but they do not report a "user rejected" signal back into the post-tool stream. Wiring a
+//   speculative shape would invent an interface that downstream Claude Code hook contract changes might
+//   silently drift away from.
+//   What's still good: the COLLECTOR exposes recordOverride({subType:'rejectApproval'}) and the unit
+//   tests cover that shape. Whoever wires the rejection signal later (whether via a distinct hook
+//   matcher or a stdin payload field we haven't seen yet) just needs to call the collector — no schema
+//   work, no module refactor. This keeps the gap honest: tested code path, undefined call site.
+// @cap-risk(F-070/AC-1) The editAfterWrite half of AC-1 is fully wired across subprocess boundaries
+//   via the per-session ledger (cap-learning-signals#recordWriteIntoLedger / wasWrittenInSession) and
+//   covered by an end-to-end spawnSync test that drives Write→Edit through this hook. The rejectApproval
+//   half is collector-tested but has NO hook call site (D10).

package/hooks/dist/cap-memory.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+// @cap-feature(feature:F-030) Memory Automation Hook — post-session hook that triggers memory accumulation pipeline
+// @cap-history(sessions:2, edits:5, since:2026-05-06, learned:2026-05-08) Frequently modified — 2 sessions, 5 edits
+// @cap-history(sessions:3, edits:9, since:2026-04-03, learned:2026-04-04) Frequently modified — 3 sessions, 9 edits
+// cap-hook-version: {{CAP_VERSION}}
+// Memory Hook - runs after session end to accumulate project memory.
+//
+// Pipeline: F-027 (Engine) → F-028 (Annotation Writer) → F-029 (Memory Directory)
+//
+// Two modes:
+//   Incremental (default): Only processes sessions newer than .cap/memory/.last-run
+//   Init (via /cap:memory init): Processes ALL sessions, builds initial memory
+//
+// Skip with CAP_SKIP_MEMORY=1 environment variable.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// @cap-todo(ref:F-030:AC-8) Hook skippable via CAP_SKIP_MEMORY=1
+if (process.env.CAP_SKIP_MEMORY === '1') {
+  process.exit(0);
+}
+
+// Resolve installed module paths
+const homeDir = os.homedir();
+const capLib = path.join(homeDir, '.claude', 'cap', 'bin', 'lib');
+
+function tryRequire(modulePath) {
+  try { return require(modulePath); } catch { return null; }
+}
+
+const LAST_RUN_FILE = '.last-run';
+
+/**
+ * Read the last-run timestamp from .cap/memory/.last-run
+ * @param {string} cwd
+ * @returns {string|null} ISO timestamp or null if never run
+ */
+function readLastRun(cwd) {
+  const fp = path.join(cwd, '.cap', 'memory', LAST_RUN_FILE);
+  try {
+    return fs.readFileSync(fp, 'utf8').trim() || null;
+  } catch { return null; }
+}
+
+/**
+ * Write the current timestamp to .cap/memory/.last-run
+ * @param {string} cwd
+ */
+function writeLastRun(cwd) {
+  const dir = path.join(cwd, '.cap', 'memory');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, LAST_RUN_FILE), new Date().toISOString(), 'utf8');
+}
+
+/**
+ * Filter session files to only those newer than a timestamp.
+ * @param {Array<{path: string, date: string|null}>} files
+ * @param {string|null} since - ISO timestamp
+ * @returns {Array}
+ */
+function filterNewSessions(files, since) {
+  if (!since) return files; // No last-run = process all
+  return files.filter(f => f.date && f.date > since);
+}
+
+// @cap-todo(ref:F-030:AC-1) Post-session hook triggers F-027→F-028→F-029 pipeline
+// @cap-todo(ref:F-030:AC-7) Hook completes within 5 seconds for up to 50 session files
+
+/**
+ * Run the memory pipeline.
+ * @param {Object} [options]
+ * @param {boolean} [options.init] - If true, process ALL sessions (bootstrap mode)
+ */
+function run(options = {}) {
+  const startTime = Date.now();
+  const cwd = process.cwd();
+
+  // Load modules
+  const extract = tryRequire(path.join(capLib, 'cap-session-extract.cjs'));
+  const engine = tryRequire(path.join(capLib, 'cap-memory-engine.cjs'));
+  const writer = tryRequire(path.join(capLib, 'cap-annotation-writer.cjs'));
+  const memDir = tryRequire(path.join(capLib, 'cap-memory-dir.cjs'));
+
+  if (!extract || !engine || !writer || !memDir) {
+    // Modules not installed — skip silently
+    return;
+  }
+
+  // Find project sessions — monorepo-aware for init, single-project for incremental
+  let allSessionFiles;
+  let projectInfo;
+
+  if (options.init && extract.getAllSessionFiles) {
+    // Init mode: scan all sub-project sessions (monorepo-aware)
+    const result = extract.getAllSessionFiles(cwd);
+    allSessionFiles = result.files;
+    projectInfo = result.projects;
+  } else {
+    // Incremental mode: single project only (fast)
+    const projectDir = extract.getProjectDir(cwd);
+    if (!projectDir) return;
+    allSessionFiles = extract.getSessionFiles(projectDir);
+    projectInfo = null;
+  }
+
+  if (allSessionFiles.length === 0) return;
+
+  // Incremental: only process sessions since last run (unless init mode)
+  const lastRun = options.init ? null : readLastRun(cwd);
+  const sessionFiles = filterNewSessions(allSessionFiles, lastRun);
+
+  if (sessionFiles.length === 0) return; // Nothing new
+
+  // Detect debug sessions from SESSION.json
+  let activeDebug = false;
+  try {
+    const sessionPath = path.join(cwd, '.cap', 'SESSION.json');
+    if (fs.existsSync(sessionPath)) {
+      const session = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+      activeDebug = session.step === 'debug' || session.activeDebugSession != null;
+    }
+  } catch { /* ignore */ }
+
+  // --- Primary source: Code tags (single source of truth) ---
+  const scanner = tryRequire(path.join(capLib, 'cap-tag-scanner.cjs'));
+  let codeEntries = [];
+  if (scanner) {
+    const tags = scanner.scanDirectory(cwd, { projectRoot: cwd });
+    codeEntries = engine.accumulateFromCode(tags);
+  }
+
+  // --- Secondary source: Sessions (hotspots only — edit frequency) ---
+  // @cap-decision Hotspots are inherently cumulative (a "hotspot" requires >= minHotspot sessions
+  //                of edits to a single file). In incremental mode the new-session window is too
+  //                narrow — usually 1–2 sessions — so naive filtering produces zero hotspots, and
+  //                writeMemoryDirectory then overwrites hotspots.md with an empty stub. Real-world
+  //                evidence: GoetzeInvest had 61 hotspot nodes in graph.json from a prior init run,
+  //                but hotspots.md was a 202-byte "_No hotspots recorded yet._" header after every
+  //                incremental run. Compute hotspots from ALL sessions every run; the
+  //                filterNewSessions short-circuit above (early-return when sessionFiles is empty)
+  //                still gates whether we run at all, so we don't burn IO on no-op invocations.
+  const filesToProcess = allSessionFiles.map(f => ({
+    path: f.path,
+    isDebugSession: activeDebug,
+  }));
+
+  const sessionResult = engine.accumulateFromFiles(filesToProcess, { projectRoot: cwd });
+
+  // Merge: code-based decisions/pitfalls + session-based hotspots (full-history)
+  const allEntries = [...codeEntries, ...sessionResult.newEntries];
+
+  if (allEntries.length === 0 && sessionResult.staleEntries.length === 0) {
+    writeLastRun(cwd);
+    return;
+  }
+
+  // F-028: Write hotspot annotations into source files (only annotatable source code)
+  // Code-based decisions/pitfalls are ALREADY in the code as @cap-decision/@cap-todo — no need to re-annotate.
+  const NON_ANNOTATABLE_EXT = new Set(['.md', '.markdown', '.json', '.jsonl', '.lock', '.svg', '.xml', '.html', '.css', '.scss']);
+  const fileEntries = {};
+  for (const entry of allEntries) {
+    if (entry.category !== 'hotspot') continue; // Only write hotspot annotations
+    if (entry.file && fs.existsSync(entry.file)) {
+      const ext = path.extname(entry.file).toLowerCase();
+      if (NON_ANNOTATABLE_EXT.has(ext)) continue;
+      if (!fileEntries[entry.file]) fileEntries[entry.file] = [];
+      fileEntries[entry.file].push(entry);
+    }
+  }
+
+  if (Object.keys(fileEntries).length > 0) {
+    writer.writeAnnotations(fileEntries);
+  }
+
+  // F-028: Remove stale annotations
+  if (sessionResult.staleEntries.length > 0) {
+    writer.removeStaleAnnotations(sessionResult.staleEntries);
+  }
+
+  // F-029: Write memory directory (merge mode for multi-developer support)
+  // @cap-feature(feature:F-090, primary:true) Apply confidence-filter at the hook layer:
+  //   only entries with confidence >= 0.6 OR pinned land in the .md output. graph.json is
+  //   built independently and stays full (Cluster/Affinity components need every node).
+  //   Real-world driver: GoetzeInvest hub had 568 KB / 2340 entries in decisions.md, ~95%
+  //   Confidence:0.50/Evidence:1 heuristic noise. Filter brings agent session-start cost
+  //   from ~150k tokens to ~5–15k tokens for typical projects.
+  // @cap-decision(F-090) Threshold lives in the hook (not in writeMemoryDirectory) so direct
+  //   callers (tests, CLI tools, library consumers) keep backwards-compat behavior.
+  memDir.writeMemoryDirectory(cwd, allEntries, { merge: !options.init, minConfidence: 0.6 });
+
+  // @cap-decision(F-079/iter1) Stage-2 #1 fix: processSnapshots wired into memory-pipeline.
+  // Closes AC-4 — "Memory-Pipeline MUSS Snapshots ... referenzieren" — by invoking
+  // processSnapshots() after writeMemoryDirectory so per-feature/platform files get a
+  // populated linked_snapshots block on every pipeline run. Idempotent: byte-identical on
+  // re-run because processSnapshots groups by target and writes ONE upsert per target with
+  // the FULL set. Wrapped in try/catch so a snapshot-linkage failure never blocks memory.
+  // @cap-decision(F-079/followup) F-079-FIX-C: hook surfaces processSnapshots skip-count.
+  //   Previously the hook ignored the `skipped` field from the result. If a snapshot fails
+  //   to be linked (parse-error, malformed frontmatter), it silently disappeared from the
+  //   diagnostic surface. Now we summarize the skipped names + reasons via the project's
+  //   debug logger (CAP_DEBUG=1 surfaces it; default path stays silent to honor the
+  //   "best-effort, never block" contract). Surfaced as a single line for grep-friendliness.
+  const linkage = tryRequire(path.join(capLib, 'cap-snapshot-linkage.cjs'));
+  if (linkage && linkage.processSnapshots) {
+    try {
+      const result = linkage.processSnapshots(cwd, {});
+      if (result && Array.isArray(result.skipped) && result.skipped.length > 0) {
+        const logger = tryRequire(path.join(capLib, 'cap-logger.cjs'));
+        if (logger && typeof logger.debug === 'function') {
+          const summary = result.skipped.map((s) => {
+            const name = (s && typeof s.name === 'string') ? s.name : '<unknown>';
+            const reason = (s && typeof s.reason === 'string') ? s.reason : '<no-reason>';
+            return `${name}=${reason}`;
+          }).join(',');
+          logger.debug({
+            op: 'cap-memory-hook.processSnapshots',
+            errorType: 'snapshot-skipped',
+            errorMessage: `processSnapshots skipped ${result.skipped.length} snapshot(s): ${summary}`,
+            recoveryAction: 'continued pipeline; per-feature/platform writes succeeded for non-skipped snapshots',
+          });
+        } else if (process.env.CAP_DEBUG) {
+          // Fallback when logger isn't available (defense-in-depth — CAP_DEBUG users still see something).
+          try {
+            process.stderr.write(`[cap:debug] processSnapshots skipped ${result.skipped.length} snapshot(s)\n`);
+          } catch (_eDbg) { /* ignore */ }
+        }
+      }
+    } catch (_e) {
+      // Snapshot linkage is best-effort; never block the rest of the pipeline.
+    }
+  }
+
+  // F-034: Update memory graph
+  const memGraph = tryRequire(path.join(capLib, 'cap-memory-graph.cjs'));
+  if (memGraph) {
+    try {
+      if (options.init) {
+        // Full rebuild from all sources
+        const graph = memGraph.buildFromMemory(cwd);
+        memGraph.saveGraph(cwd, graph);
+      } else {
+        // Incremental update with new entries
+        const graph = memGraph.loadGraph(cwd);
+        const staleNodeIds = sessionResult.staleEntries.map(
+          e => memGraph.generateNodeId(e.category, e.content)
+        );
+        memGraph.incrementalUpdate(graph, allEntries, { staleNodeIds });
+        memGraph.saveGraph(cwd, graph);
+      }
+    } catch (_e) {
+      // Graph update is non-critical — don't block session end
+    }
+  }
+
+  // Save last-run timestamp
+  writeLastRun(cwd);
+
+  // Stats for reporting
+  const stats = {
+    decisions: allEntries.filter(e => e.category === 'decision').length,
+    pitfalls: allEntries.filter(e => e.category === 'pitfall').length,
+    patterns: allEntries.filter(e => e.category === 'pattern').length,
+    hotspots: allEntries.filter(e => e.category === 'hotspot').length,
+    fromCode: codeEntries.length,
+    fromSessions: sessionResult.newEntries.length,
+  };
+
+  // Performance check
+  const elapsed = Date.now() - startTime;
+  if (elapsed > 5000 && !options.init) {
+    process.stderr.write(`cap-memory: warning — hook took ${elapsed}ms (target: <5000ms)\n`);
+  }
+
+  // Report in init mode
+  if (options.init) {
+    const elapsed2 = Date.now() - startTime;
+    if (projectInfo && projectInfo.length > 1) {
+      process.stdout.write(`cap-memory init: monorepo mode — ${projectInfo.length} sub-projects found\n`);
+      for (const p of projectInfo) {
+        process.stdout.write(`  ${p}\n`);
+      }
+    }
+    process.stdout.write(`cap-memory init: ${sessionFiles.length} sessions, ${stats.fromCode} code tags processed in ${elapsed2}ms\n`);
+    process.stdout.write(`  decisions: ${stats.decisions} (from code), pitfalls: ${stats.pitfalls} (from code), hotspots: ${stats.hotspots} (from sessions)\n`);
+  }
+}
+
+// CLI mode: support "init" argument for bootstrap
+const args = process.argv.slice(2);
+const isInit = args.includes('init') || args.includes('--init');
+
+try {
+  run({ init: isInit });
+} catch (err) {
+  // Never block session end — fail silently
+  process.stderr.write(`cap-memory: ${err.message}\n`);
+}