contextdevkit 1.8.0

package/templates/contextkit/runtime/git-hooks/commit-msg.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * commit-msg git hook (Level >= 3) — validates Conventional Commits.
+ *
+ * Pattern: <type>(<scope>)?: <subject>
+ *   - type: feat | fix | chore | docs | refactor | test | ci | build | perf | style | revert
+ *   - scope: optional, lowercase a-z0-9-
+ *   - subject: 1..100 chars, no trailing period
+ *
+ * Bypass: include `[skip-cc]` anywhere in the subject.
+ *
+ * Invoked by `.git/hooks/commit-msg` (the installer drops a thin wrapper that
+ * calls this file). Exit 0 = allowed, 1 = blocked.
+ */
+import { readFileSync } from 'node:fs';
+
+const messageFile = process.argv[2];
+if (!messageFile) {
+  console.error('commit-msg hook: missing message file argument');
+  process.exit(1);
+}
+
+const subject = readFileSync(messageFile, 'utf-8').split('\n')[0].trim();
+
+if (/^(Merge|Revert|fixup!|squash!|amend!|wip:)/i.test(subject) || subject.includes('[skip-cc]')) {
+  process.exit(0);
+}
+
+const PATTERN = /^(feat|fix|chore|docs|refactor|test|ci|build|perf|style|revert)(\([a-z0-9-]+\))?: .{1,100}$/;
+
+if (!PATTERN.test(subject)) {
+  console.error('');
+  console.error('✗ Commit message does not follow Conventional Commits format.');
+  console.error('');
+  console.error(`Got:    ${subject}`);
+  console.error('');
+  console.error('Expected: <type>(<scope>)?: <subject>');
+  console.error('  type:    feat | fix | chore | docs | refactor | test | ci | build | perf | style | revert');
+  console.error('  subject: 1..100 chars, no trailing period');
+  console.error('');
+  console.error('Examples:');
+  console.error('   feat(api): add schedule endpoint');
+  console.error('   fix(ui): correct safe-area inset on notch');
+  console.error('   chore: bump dependencies');
+  console.error('');
+  console.error('Bypass intentionally with `[skip-cc]` in the subject.');
+  process.exit(1);
+}
+
+if (subject.endsWith('.')) {
+  console.error('✗ Commit subject must not end with a period.');
+  process.exit(1);
+}
+
+process.exit(0);

package/templates/contextkit/runtime/git-hooks/pre-commit.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * pre-commit git hook (Level >= 3).
+ *
+ * Goal: keep the derived indices (`contextkit/memory/SESSIONS.md` and
+ * `WORKSPACE.md`) in sync with their source-of-truth files, FAST (< 1s).
+ * Heavy validation (type-check, lint, tests) belongs in CI, not here.
+ *
+ * Invoked by `.git/hooks/pre-commit` (a thin wrapper the installer drops).
+ * Bypass: `git commit --no-verify`.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathsFor } from '../config/paths.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+
+function safeRun(cmd) {
+  try {
+    execSync(cmd, { cwd: ROOT, stdio: ['ignore', 'pipe', 'pipe'], timeout: 10_000 });
+  } catch {
+    /* never block the commit on a derived-doc regen failure */
+  }
+}
+
+function main() {
+  console.log('› pre-commit: regenerating derived docs...');
+
+  if (existsSync(P.sessions)) {
+    safeRun('node contextkit/tools/scripts/session-reindex.mjs');
+    safeRun('git add contextkit/memory/SESSIONS.md');
+  }
+  if (existsSync(resolve(ROOT, '.claude/.workspace'))) {
+    safeRun('node contextkit/tools/scripts/workspace-sync.mjs');
+    safeRun('git add contextkit/memory/WORKSPACE.md');
+  }
+  if (existsSync(P.pipeline)) {
+    safeRun('node contextkit/tools/scripts/pipeline.mjs sync');
+    safeRun('git add contextkit/pipeline/devpipeline.md contextkit/pipeline/known-bugs.md');
+  }
+
+  console.log('✓ pre-commit done.');
+}
+
+main();

package/templates/contextkit/runtime/git-hooks/pre-push.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * pre-push hook (Level >= 3) — conflict pre-check against the latest remote.
+ *
+ * Before a push lands, this fetches the target branch (config l3.mainBranch,
+ * default "main"), compares what you changed against what changed upstream since
+ * your merge-base, and:
+ *   - BLOCKS (exit 1) if a real textual conflict exists (git merge-tree) — so a
+ *     parallel dev/agent who edited the same lines isn't silently overwritten.
+ *   - WARNS (exit 0) if you both touched the same files but they auto-merge.
+ *   - stays silent when there is no overlap.
+ *
+ * This is the cross-machine guarantee: the per-session ledger can't see other
+ * machines, but git can. Bypass (audited): CONTEXT_ALLOW_CONFLICT_PUSH=1 git push.
+ *
+ * Defensive: no remote / offline / old git → allow (never block on tooling).
+ */
+import { execFileSync } from 'node:child_process';
+import { loadConfigSync } from '../config/load.mjs';
+
+const ROOT = process.cwd();
+const MAIN = loadConfigSync(ROOT).l3?.mainBranch || 'main';
+
+/**
+ * Cap every git subprocess (ms) so the network `fetch` below can't hang a push
+ * against an unreachable/slow remote. On timeout `execFileSync` throws → `git()`
+ * returns `{ ok:false }`, which the conflict check already treats as "couldn't
+ * refresh, allow the push" (defensive: never block on tooling). Env-overridable.
+ */
+const GIT_TIMEOUT_MS = Number.parseInt(process.env.CONTEXT_GIT_TIMEOUT_MS || '', 10) || 15000;
+
+if (process.env.CONTEXT_ALLOW_CONFLICT_PUSH === '1') {
+  console.error('⚠️  pre-push: conflict check bypassed (CONTEXT_ALLOW_CONFLICT_PUSH=1).');
+  process.exit(0);
+}
+
+function git(args, allowFail = true) {
+  try {
+    return { ok: true, out: execFileSync('git', args, { cwd: ROOT, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS }).trim() };
+  } catch (err) {
+    if (!allowFail) throw err;
+    return { ok: false, out: '', status: err?.status };
+  }
+}
+
+function fileList(range) {
+  const r = git(['diff', '--name-only', range]);
+  return r.ok ? r.out.split('\n').filter(Boolean) : [];
+}
+
+function main() {
+  // Refresh the remote ref (best effort, short timeout via git's own).
+  git(['fetch', 'origin', MAIN, '--quiet']);
+
+  const remote = `origin/${MAIN}`;
+  if (!git(['rev-parse', '--verify', '--quiet', remote]).ok) process.exit(0); // no upstream yet
+
+  const base = git(['merge-base', 'HEAD', remote]);
+  if (!base.ok || !base.out) process.exit(0);
+
+  const ours = new Set(fileList(`${base.out}..HEAD`));
+  const theirs = fileList(`${base.out}..${remote}`);
+  const overlap = theirs.filter((f) => ours.has(f));
+  if (overlap.length === 0) process.exit(0); // disjoint — safe
+
+  // Real textual conflict? `git merge-tree --write-tree` exits 1 on conflict.
+  const mt = git(['merge-tree', '--write-tree', 'HEAD', remote]);
+  const hasConflict = mt.status === 1; // status>1 / unsupported → unknown
+
+  if (hasConflict) {
+    console.error('');
+    console.error(`✗ pre-push BLOCKED — your branch conflicts with ${remote} (someone pushed there).`);
+    console.error('');
+    console.error('  Files changed on BOTH sides (likely conflicts):');
+    for (const f of overlap) console.error(`    - ${f}`);
+    console.error('');
+    console.error('  Two sessions/devs changed the same file. Reconcile before pushing so');
+    console.error('  neither change is lost:');
+    console.error(`    git pull --rebase origin ${MAIN}   # replay your work on top, resolve conflicts`);
+    console.error('    # review each file: keep BOTH functions/changes, then continue the rebase');
+    console.error('');
+    console.error('  Emergency bypass (audited): CONTEXT_ALLOW_CONFLICT_PUSH=1 git push ...');
+    console.error('');
+    process.exit(1);
+  }
+
+  // Overlap but auto-mergeable — warn, don't block.
+  console.error('');
+  console.error(`⚠️  pre-push: you and ${remote} both changed these files (git can auto-merge,`);
+  console.error('   but double-check nothing is logically clobbered):');
+  for (const f of overlap) console.error(`    - ${f}`);
+  console.error(`   Tip: git pull --rebase origin ${MAIN} before pushing keeps history clean.`);
+  console.error('');
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (err) {
+  process.stderr.write(`[pre-push] ${err?.message ?? err}\n`);
+  process.exit(0);
+}

package/templates/contextkit/runtime/hooks/boot-context-readers.mjs

@@ -0,0 +1,111 @@
+/**
+ * Boot-context content readers — pure I/O for `session-start.mjs`.
+ *
+ * Each function reads ONE source artifact and returns a Markdown snippet (or
+ * null when missing/empty). All helpers are defensive — they never throw.
+ * Zero third-party deps.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { CHANGELOG, SESSIONS_DIR, SESSIONS_INDEX, WORKSPACE_INDEX } from '../config/paths.mjs';
+import { parseSessionLog, renderDigest } from './session-digest-core.mjs';
+
+const SECTION_LIMIT = 60;
+
+/** Matches `<YYYY-MM-DD>-<NN>-<slug>.md`. Slug allows `a-z0-9._-`. */
+const ENTRY_PATTERN = /^(\d{4}-\d{2}-\d{2})-(\d{2,})-([a-z0-9._-]+)\.md$/;
+
+async function readSafe(root, relPath) {
+  try {
+    return await readFile(resolve(root, relPath), 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+export async function exists(root, relPath) {
+  try {
+    await stat(resolve(root, relPath));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Newest session file (canonical number; later DATE breaks a numbering tie) + its content. */
+async function latestSessionEntry(root) {
+  let files = [];
+  try {
+    files = await readdir(resolve(root, SESSIONS_DIR));
+  } catch {
+    return null;
+  }
+  const entries = files
+    .map((f) => ENTRY_PATTERN.exec(f))
+    .filter(Boolean)
+    .map((m) => ({ filename: m[0], date: m[1], num: Number.parseInt(m[2], 10) }))
+    // Session number is canonical; on a number collision the later DATE wins so
+    // the boot banner never shows a stale entry just because of a numbering clash.
+    .sort((a, b) => b.num - a.num || b.date.localeCompare(a.date));
+  if (entries.length === 0) return null;
+  const content = await readSafe(root, `${SESSIONS_DIR}/${entries[0].filename}`);
+  if (!content) return null;
+  return { filename: entries[0].filename, content, path: resolve(root, SESSIONS_DIR, entries[0].filename) };
+}
+
+/** Most recent registered session as a raw-truncated Markdown snippet + its path. */
+export async function extractLatestSession(root) {
+  const entry = await latestSessionEntry(root);
+  if (!entry) return null;
+  const lines = entry.content.split('\n').slice(0, SECTION_LIMIT);
+  return { path: entry.path, content: lines.join('\n').trim() };
+}
+
+/**
+ * Compact ~6-line digest of the latest session for the boot banner [ADR-0027].
+ * Falls back to the raw-truncated snippet when the log can't be parsed — a digest
+ * miss degrades visibly, it never empties the banner (rules 2 & 8).
+ * @returns {Promise<?{path:string, content:string, mode:'digest'|'raw'}>}
+ */
+export async function digestLatestSession(root) {
+  const entry = await latestSessionEntry(root);
+  if (!entry) return null;
+  const digest = renderDigest(parseSessionLog(entry.content, entry.filename));
+  if (digest) return { path: entry.path, content: digest, mode: 'digest' };
+  const lines = entry.content.split('\n').slice(0, SECTION_LIMIT);
+  return { path: entry.path, content: lines.join('\n').trim(), mode: 'raw' };
+}
+
+/** Extracts the `[Unreleased]` block from a CHANGELOG-shaped string. */
+export function extractUnreleased(text) {
+  if (!text) return null;
+  const lines = text.split('\n');
+  const startIdx = lines.findIndex((l) => /^##\s+\[Unreleased\]/i.test(l));
+  if (startIdx === -1) return null;
+  const slice = lines.slice(startIdx + 1);
+  const endRel = slice.findIndex((l) => l.trim() === '---' || /^##\s+\[/.test(l));
+  const end = endRel === -1 ? slice.length : endRel;
+  const truncated = end > SECTION_LIMIT;
+  const content = slice.slice(0, Math.min(end, SECTION_LIMIT)).join('\n').trim();
+  if (!content || /add your changes|empty|vazio/i.test(content)) return null;
+  // Tell the reader the boot banner is showing a clipped view, not the whole list.
+  return truncated ? `${content}\n… (truncated — full [Unreleased] in docs/CHANGELOG.md)` : content;
+}
+
+/** Active-session table from WORKSPACE.md (first ~12 lines after the header). */
+export async function readWorkspaceSummary(root) {
+  const md = await readSafe(root, WORKSPACE_INDEX);
+  if (!md) return null;
+  const lines = md.split('\n');
+  const startIdx = lines.findIndex((l) => /^##\s+🟢\s+Active/.test(l));
+  if (startIdx === -1) return null;
+  return lines.slice(startIdx).slice(0, 12).join('\n').trim();
+}
+
+export async function readChangelog(root) {
+  return readSafe(root, CHANGELOG);
+}
+
+export async function readSessionsIndex(root) {
+  return readSafe(root, SESSIONS_INDEX);
+}

package/templates/contextkit/runtime/hooks/boot-signals.mjs

@@ -0,0 +1,135 @@
+/**
+ * Boot signals — environment detectors for the SessionStart banner.
+ *
+ * Pure-ish read-only helpers split out of `session-start.mjs` to keep that hook
+ * under the line budget: git divergence/branch, other active branches, project
+ * name, greenfield detection, and the config-driven cadence triggers
+ * (security-mode, predictions-review). All best-effort and silent on error —
+ * a signal never blocks a session. Zero third-party deps.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { loadConfigSync } from '../config/load.mjs';
+import { pathsFor } from '../config/paths.mjs';
+
+export function checkGitDivergence(root) {
+  try {
+    execSync('git fetch origin --quiet', { cwd: root, stdio: 'ignore', timeout: 5000 });
+  } catch {
+    return null;
+  }
+  try {
+    const counts = execSync('git rev-list --left-right --count HEAD...@{u}', { cwd: root, encoding: 'utf-8', timeout: 3000 }).trim();
+    const [a, b] = counts.split(/\s+/);
+    return { ahead: Number.parseInt(a ?? '0', 10), behind: Number.parseInt(b ?? '0', 10) };
+  } catch {
+    return null;
+  }
+}
+
+export function getBranch(root) {
+  try {
+    return execSync('git symbolic-ref --short HEAD', { cwd: root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return 'detached';
+  }
+}
+
+/**
+ * Cross-machine + same-machine awareness (L3): recent OTHER branches — local
+ * worktrees and remote feature branches — with author + age, so parallel work
+ * (other devs/agents) is visible at boot. Read-only, best effort.
+ */
+export function activeBranches(root, currentBranch) {
+  const lines = [];
+  try {
+    const worktrees = execSync('git worktree list --porcelain', { cwd: root, encoding: 'utf-8', timeout: 3000 })
+      .split('\n')
+      .filter((l) => l.startsWith('branch '))
+      .map((l) => l.replace('branch refs/heads/', '').trim())
+      .filter((b) => b && b !== currentBranch);
+    for (const b of [...new Set(worktrees)].slice(0, 5)) lines.push(`- 🌳 local worktree on \`${b}\``);
+  } catch {
+    /* not a worktree setup */
+  }
+  try {
+    const remote = execSync(
+      `git for-each-ref --sort=-committerdate --count=20 --format="%(refname:short)|%(committerdate:relative)|%(authorname)" refs/remotes`,
+      { cwd: root, encoding: 'utf-8', timeout: 3000 },
+    )
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .map((l) => l.split('|'))
+      .filter(([ref]) => ref && !/\/(main|master|HEAD)$/.test(ref) && !ref.endsWith(`/${currentBranch}`))
+      .filter(([, rel]) => !/(month|year)/.test(rel || ''))
+      .slice(0, 5);
+    for (const [ref, rel, author] of remote) lines.push(`- ☁️  \`${ref}\` — ${rel} by ${author}`);
+  } catch {
+    /* no remote */
+  }
+  return lines.length ? lines.join('\n') : null;
+}
+
+/** True when the project has no source code yet (routes first-run to /aidevtool-from0). */
+export function isGreenfield(root) {
+  return !['src', 'app', 'apps', 'packages', 'lib', 'components', 'pages', 'server', 'cmd', 'internal'].some((d) => existsSync(resolve(root, d)));
+}
+
+export async function projectName(root) {
+  try {
+    const pkg = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf-8'));
+    if (typeof pkg?.name === 'string' && pkg.name) return pkg.name;
+  } catch {
+    /* no package.json */
+  }
+  return basename(root);
+}
+
+/** Counts registered session files. Shared by the cadence triggers. */
+function sessionCount(root) {
+  try {
+    return readdirSync(pathsFor(root).sessions).filter((f) => f.endsWith('.md')).length;
+  } catch {
+    return 0;
+  }
+}
+
+/** Security mode (config): returns the cadence N when a /deep-analysis is due, else 0. */
+export function securityModeDue(root) {
+  const cfg = loadConfigSync(root)?.securityMode;
+  if (!cfg || cfg.active !== true) return 0;
+  const everyN = Number(cfg.everyNSessions) > 0 ? Number(cfg.everyNSessions) : 10;
+  const n = sessionCount(root);
+  return n > 0 && n % everyN === 0 ? everyN : 0;
+}
+
+/**
+ * Predictions-review cadence (config): returns N when a review is due — an
+ * every-N-sessions tick AND at least one `/simulate-impact` prediction is still
+ * unreviewed (`fill on review` stub). Zero noise when there's nothing to review.
+ */
+export function predictionsReviewDue(root) {
+  const cfg = loadConfigSync(root)?.predictionsReview;
+  if (!cfg || cfg.active !== true) return 0;
+  const everyN = Number(cfg.everyNSessions) > 0 ? Number(cfg.everyNSessions) : 10;
+  const n = sessionCount(root);
+  if (n === 0 || n % everyN !== 0) return 0;
+  try {
+    const dir = pathsFor(root).predictions;
+    const unreviewed = readdirSync(dir)
+      .filter((f) => f.endsWith('.md'))
+      .some((f) => {
+        try {
+          return readFileSync(resolve(dir, f), 'utf-8').includes('fill on review');
+        } catch {
+          return false;
+        }
+      });
+    return unreviewed ? everyN : 0;
+  } catch {
+    return 0;
+  }
+}

package/templates/contextkit/runtime/hooks/check-registration.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+/**
+ * Stop hook (Level >= 2) — nudges Claude to register the session on drift.
+ *
+ * Session-aware via the per-session ledger keyed by `session_id`. Anti-loop
+ * guard via the `stop_hook_active` flag plus a `stopWarnedAt` timestamp.
+ *
+ * Decision rules:
+ *   - `stop_hook_active === true` → silent (anti-loop).
+ *   - Important paths touched < 2 → silent.
+ *   - Session already registered → silent.
+ *   - Already nudged once → silent.
+ *   - Otherwise: emit `decision: "block"` with the path list + instructions.
+ *
+ * Side jobs (informational, NEVER block): Level 5 archives old registered
+ * ledgers and proposes a distillation cycle when the session count crosses
+ * the configured threshold.
+ *
+ * Zero third-party deps.
+ */
+import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import {
+  ledgerPathFor,
+  listAllLedgers,
+  pendingImportantPaths,
+  readLedger,
+  resolveSessionId,
+  SESSIONS_DIR,
+  wasRegisteredDuringSession,
+  writeLedger,
+} from './ledger.mjs';
+import { getLevel, loadConfig } from '../config/load.mjs';
+import { SESSIONS_DIR as SESSIONS_MD_DIR, SESSIONS_INDEX } from '../config/paths.mjs';
+
+const ROOT = process.cwd();
+const ARCHIVE_DIR = resolve(SESSIONS_DIR, '.archive');
+const DISTILL_NUDGE_PATH = resolve(SESSIONS_DIR, '.distill-nudge');
+const DISTILL_NUDGE_DEBOUNCE_MS = 24 * 60 * 60 * 1000;
+const ADVISOR_NUDGE_PATH = resolve(SESSIONS_DIR, '.advisor-nudge');
+const ADVISOR_NUDGE_DEBOUNCE_MS = 24 * 60 * 60 * 1000;
+
+async function readStdin() {
+  return new Promise((res) => {
+    let buf = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (c) => (buf += c));
+    process.stdin.on('end', () => res(buf));
+    setTimeout(() => res(buf), 500).unref?.();
+  });
+}
+
+function buildReason(paths, sessionId) {
+  const list = paths.slice(0, 12).map((p) => `  - ${p}`).join('\n');
+  const overflow = paths.length > 12 ? `\n  (… and ${paths.length - 12} more)` : '';
+  return [
+    `⚠️  Session drift detected (session id: ${sessionId.slice(0, 8)}…).`,
+    `${paths.length} important file(s) were modified, but ${SESSIONS_INDEX} was not updated.`,
+    '',
+    'Modified paths:',
+    list + overflow,
+    '',
+    'Before finalizing, do ONE of the following and then stop again:',
+    '  1. Run /log-session to register this session and update the CHANGELOG.',
+    '  2. If this session is intentionally discardable (experiment that will be',
+    '     reverted), tell the user and confirm before stopping.',
+    '',
+    'You will not be nudged again for this session — this notice fires once.',
+  ].join('\n');
+}
+
+/** L5 — archives ledgers that are registered AND older than the cutoff. */
+async function archiveOldRegisteredLedgers() {
+  let config;
+  try {
+    config = await loadConfig(ROOT);
+  } catch {
+    return;
+  }
+  const ageDays = Number(config?.l5?.distill?.archiveLedgersOlderThanDays);
+  if (!Number.isFinite(ageDays) || ageDays <= 0) return;
+  const cutoff = Date.now() - ageDays * 24 * 60 * 60 * 1000;
+  let entries;
+  try {
+    entries = await listAllLedgers();
+  } catch {
+    return;
+  }
+  for (const { sessionId, ledger } of entries) {
+    if (!(ledger.registered || wasRegisteredDuringSession(ledger))) continue;
+    const path = ledgerPathFor(sessionId);
+    try {
+      const st = await stat(path);
+      if (st.mtimeMs > cutoff) continue;
+      await mkdir(ARCHIVE_DIR, { recursive: true });
+      await rename(path, resolve(ARCHIVE_DIR, `${sessionId}.json`));
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+/** L5 — proposes `/distill-sessions` once the session count crosses threshold. */
+async function maybeProposeDistillation() {
+  let config;
+  try {
+    config = await loadConfig(ROOT);
+  } catch {
+    return null;
+  }
+  const threshold = Number(config?.l5?.distill?.proposeAfterSessions);
+  if (!Number.isFinite(threshold) || threshold <= 0) return null;
+  let count = 0;
+  try {
+    const entries = await readdir(resolve(ROOT, SESSIONS_MD_DIR));
+    count = entries.filter((f) => /^\d{4}-\d{2}-\d{2}-\d{2,}-.+\.md$/.test(f)).length;
+  } catch {
+    return null;
+  }
+  if (count < threshold) return null;
+  let lastNudgeAt = 0;
+  try {
+    lastNudgeAt = Number.parseInt((await readFile(DISTILL_NUDGE_PATH, 'utf-8')).trim(), 10) || 0;
+  } catch {
+    /* no prior nudge */
+  }
+  if (Date.now() - lastNudgeAt < DISTILL_NUDGE_DEBOUNCE_MS) return null;
+  try {
+    await mkdir(SESSIONS_DIR, { recursive: true });
+    await writeFile(DISTILL_NUDGE_PATH, String(Date.now()), 'utf-8');
+  } catch {
+    return null;
+  }
+  return [
+    `💡 Distillation cycle ready (L5): ${count} sessions registered (threshold ${threshold}).`,
+    '   Consider `/distill-sessions` to propose CLAUDE.md refinements, then `/distill-apply`.',
+    "   Skipping is fine — you'll be reminded again in 24h.",
+  ].join('\n');
+}
+
+/**
+ * ADR-0028 — proactively suggests `/advise` after a PRODUCTIVE session.
+ * Mirrors `maybeProposeDistillation`: config-gated (`advisor.active` &&
+ * `advisor.nudgeOnStop`), fires only when ≥ 2 important paths were touched this
+ * session (real implementation), and debounced 24h. Nudge-only — never blocks,
+ * never runs the network or the AI (that lives in the `/advise` command).
+ *
+ * @param {object} ledger - this session's ledger (for the "real work" signal).
+ * @returns {Promise<string|null>} the nudge text, or null when it should stay silent.
+ */
+async function maybeProposeAdvisor(ledger) {
+  let config;
+  try {
+    config = await loadConfig(ROOT);
+  } catch {
+    return null;
+  }
+  const advisor = config?.advisor;
+  if (advisor?.active !== true || advisor?.nudgeOnStop !== true) return null;
+  const touched = pendingImportantPaths(ledger).length;
+  if (touched < 2) return null;
+  let lastNudgeAt = 0;
+  try {
+    lastNudgeAt = Number.parseInt((await readFile(ADVISOR_NUDGE_PATH, 'utf-8')).trim(), 10) || 0;
+  } catch {
+    /* no prior nudge */
+  }
+  if (Date.now() - lastNudgeAt < ADVISOR_NUDGE_DEBOUNCE_MS) return null;
+  try {
+    await mkdir(SESSIONS_DIR, { recursive: true });
+    await writeFile(ADVISOR_NUDGE_PATH, String(Date.now()), 'utf-8');
+  } catch {
+    return null;
+  }
+  return [
+    `💡 Proactive Advisor (L6): ${touched} important file(s) touched this session.`,
+    '   Run `/advise` for a six-lane improvement scan (architecture · features · deepen ·',
+    '   security · UX · growth) before you wrap up. Skipping is fine — reminded again in 24h.',
+  ].join('\n');
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch {
+    payload = {};
+  }
+  if (payload.stop_hook_active === true) return;
+
+  const sessionId = resolveSessionId(payload);
+  const ledger = await readLedger(sessionId);
+  const level = getLevel(ROOT);
+
+  const sideSuggestions = [];
+  if (level >= 5) {
+    await archiveOldRegisteredLedgers();
+    const distill = await maybeProposeDistillation();
+    if (distill) sideSuggestions.push(distill);
+    const advise = await maybeProposeAdvisor(ledger);
+    if (advise) sideSuggestions.push(advise);
+  }
+  const flushSide = () => {
+    if (sideSuggestions.length > 0) process.stdout.write(sideSuggestions.join('\n\n') + '\n');
+  };
+
+  if (ledger.registered || wasRegisteredDuringSession(ledger)) return flushSide();
+
+  const paths = pendingImportantPaths(ledger);
+  if (paths.length < 2) return flushSide();
+  if (typeof ledger.stopWarnedAt === 'number') return flushSide();
+
+  // Mark BEFORE emitting to avoid races.
+  ledger.stopWarnedAt = Date.now();
+  await writeLedger(sessionId, ledger);
+
+  const reason =
+    sideSuggestions.length > 0
+      ? `${buildReason(paths, sessionId)}\n\n${sideSuggestions.join('\n\n')}`
+      : buildReason(paths, sessionId);
+  process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+}
+
+main().catch((err) => {
+  process.stderr.write(`[check-registration] ${err?.message ?? err}\n`);
+  process.exit(0);
+});