contextdevkit 1.8.0

package/templates/contextkit/tools/scripts/release.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * Releases path claims for the current session (Level >= 3).
+ *
+ * With a path arg: removes just that claim. With no arg: removes ALL claims
+ * for this session (deletes the workspace file). Then regenerates WORKSPACE.md.
+ *
+ * Usage:  node contextkit/tools/scripts/release.mjs [path]
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile, rm } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { sanitizeSid } from '../../runtime/hooks/ledger.mjs';
+import { writeFileAtomic } from '../../runtime/hooks/safe-io.mjs';
+
+const ROOT = process.cwd();
+const WS_DIR = resolve(ROOT, '.claude/.workspace');
+const LAST_TOUCHED = resolve(ROOT, '.claude/.sessions/.last-touched');
+
+async function sessionId() {
+  try {
+    return JSON.parse(await readFile(LAST_TOUCHED, 'utf-8')).sessionId;
+  } catch {
+    return `local_${process.pid}`;
+  }
+}
+
+async function main() {
+  const target = process.argv[2]?.replaceAll('\\', '/');
+  const sid = sanitizeSid(await sessionId());
+  const file = resolve(WS_DIR, `${sid}.json`);
+
+  if (!existsSync(file)) {
+    console.log('ℹ️  No active claims for this session.');
+    return;
+  }
+
+  if (!target) {
+    await rm(file, { force: true });
+    console.log(`✅ Released ALL claims for session ${sid.slice(0, 8)}.`);
+  } else {
+    const claimRecord = JSON.parse(await readFile(file, 'utf-8'));
+    const before = (claimRecord.claims || []).length;
+    claimRecord.claims = (claimRecord.claims || []).filter((c) => c.path !== target);
+    await writeFileAtomic(file, JSON.stringify(claimRecord, null, 2));
+    console.log(before === claimRecord.claims.length ? `ℹ️  No claim matched "${target}".` : `✅ Released claim "${target}".`);
+  }
+
+  try {
+    execFileSync('node', ['contextkit/tools/scripts/workspace-sync.mjs'], { cwd: ROOT, stdio: 'ignore' });
+  } catch {
+    /* best effort */
+  }
+}
+
+main().catch((err) => {
+  console.error('❌ release failed:', err);
+  process.exit(1);
+});

package/templates/contextkit/tools/scripts/resume.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * `/resume` — re-bind the current Claude Code session to a previously
+ * **unregistered** ledger (ticket 046, Compozy follow-through). When a
+ * session ended without `/log-session`, its ledger sits in
+ * `.claude/.sessions/<sid>.json` with `registered: false` and the boot
+ * context flags it as drift. `/resume <sid>` makes that ledger the
+ * active one — subsequent edits continue appending there, `/log-session`
+ * registers it properly, claims (if any) are re-asserted under the same id.
+ *
+ * Usage:
+ *   resume.mjs                    list unregistered candidates
+ *   resume.mjs <session-id>       re-bind to that session
+ *   resume.mjs --json             machine-readable listing
+ *
+ * Refusal modes (rule 8 — refuse, don't assume):
+ *   - target id not present in `.claude/.sessions/` → exit 1
+ *   - target id is already registered (no drift to recover) → exit 1
+ *   - target's path claims overlap an active session's claims → exit 1
+ *
+ * Read-only on the session ledgers themselves; only rewrites the
+ * `.last-touched` pointer atomically.
+ */
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { LAST_TOUCHED_PATH, listAllLedgers, sanitizeSid } from '../../runtime/hooks/ledger.mjs';
+import { writeFileAtomicSync } from '../../runtime/hooks/safe-io.mjs';
+
+const ROOT = process.cwd();
+const WORKSPACE_DIR = resolve(ROOT, '.claude/.workspace');
+const STALE_AFTER_MS = 60 * 60 * 1000;
+
+/**
+ * Returns the set of paths currently claimed by any *active* (non-stale)
+ * session OTHER than `excludeSid`. Used to detect resume-time conflicts.
+ *
+ * @param {string} excludeSid — the session id we're resuming to (its own
+ *   claims shouldn't count as a conflict with itself)
+ * @returns {Set<string>}
+ */
+function activePathClaims(excludeSid) {
+  const out = new Set();
+  if (!existsSync(WORKSPACE_DIR)) return out;
+  for (const name of readdirSync(WORKSPACE_DIR)) {
+    if (!name.endsWith('.json')) continue;
+    try {
+      const rec = JSON.parse(readFileSync(resolve(WORKSPACE_DIR, name), 'utf-8'));
+      if (rec.sessionId === excludeSid) continue;
+      if (typeof rec.lastHeartbeat !== 'number' || Date.now() - rec.lastHeartbeat > STALE_AFTER_MS) continue;
+      for (const c of rec.claims || []) out.add(c.path);
+    } catch { /* skip malformed */ }
+  }
+  return out;
+}
+
+/**
+ * Reads `claims[]` for the given session id, if any. Workspace records are
+ * optional — a session can be in drift without ever calling `/claim`.
+ */
+function claimsFor(sid) {
+  const file = resolve(WORKSPACE_DIR, `${sid}.json`);
+  if (!existsSync(file)) return [];
+  try { return JSON.parse(readFileSync(file, 'utf-8')).claims || []; } catch { return []; }
+}
+
+async function listUnregistered() {
+  const all = await listAllLedgers();
+  return all.filter(({ ledger }) => !ledger.registered && Array.isArray(ledger.modifications) && ledger.modifications.length > 0);
+}
+
+function fmtAgo(ms) {
+  const s = Math.floor((Date.now() - ms) / 1000);
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}
+
+async function listCmd(asJson) {
+  const candidates = await listUnregistered();
+  if (asJson) { console.log(JSON.stringify(candidates.map(({ sessionId, ledger }) => ({ sessionId, modifications: ledger.modifications.length, startedAt: ledger.startedAt, claims: claimsFor(sessionId).length })), null, 2)); return; }
+  if (candidates.length === 0) { console.log('  No unregistered sessions found. The workspace is clean.'); return; }
+  console.log(`\n  ${candidates.length} unregistered session(s) — candidates for /resume:\n`);
+  for (const { sessionId, ledger } of candidates) {
+    const claims = claimsFor(sessionId).length;
+    const claimNote = claims > 0 ? ` · ${claims} claim(s)` : '';
+    console.log(`  ${sessionId.slice(0, 12).padEnd(12)} · ${ledger.modifications.length} edit(s) · started ${fmtAgo(ledger.startedAt)}${claimNote}`);
+  }
+  console.log('\n  Resume with: node contextkit/tools/scripts/resume.mjs <session-id>\n');
+}
+
+async function resumeCmd(targetSid) {
+  const sid = sanitizeSid(targetSid);
+  const candidates = await listUnregistered();
+  const match = candidates.find((c) => c.sessionId === sid || c.sessionId.startsWith(sid));
+  if (!match) { console.error(`✗ session "${targetSid}" not found among unregistered drift candidates.`); process.exit(1); }
+  if (match.ledger.registered) { console.error(`✗ session ${match.sessionId} is already registered — nothing to resume.`); process.exit(1); }
+  const myClaims = new Set(claimsFor(match.sessionId).map((c) => c.path));
+  const otherActiveClaims = activePathClaims(match.sessionId);
+  const conflicts = [...myClaims].filter((p) => otherActiveClaims.has(p));
+  if (conflicts.length > 0) { console.error(`✗ cannot resume: path(s) claimed by another active session: ${conflicts.join(', ')}`); process.exit(1); }
+  writeFileAtomicSync(LAST_TOUCHED_PATH, JSON.stringify({ sessionId: match.sessionId, at: Date.now() }));
+  console.log(`▶  Resumed session ${match.sessionId.slice(0, 12)} (${match.ledger.modifications.length} prior edit(s), ${myClaims.size} claim(s)).`);
+  console.log(`   Run /log-session to register this session properly when you're done.`);
+}
+
+async function main() {
+  const arg = process.argv[2];
+  if (!arg || arg === '--json') { await listCmd(arg === '--json'); return; }
+  if (arg === '--help' || arg === '-h') { console.log('Usage: resume.mjs [<session-id> | --json]'); return; }
+  await resumeCmd(arg);
+}
+
+main().catch((err) => { console.error(`✗ resume failed: ${err?.message || err}`); process.exit(1); });

package/templates/contextkit/tools/scripts/roadmap.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Roadmap helper — find / status / init for the product roadmap.
+ *
+ * The roadmap is prose managed by the `/roadmap` command; this gives that
+ * command deterministic facts:
+ *   - `find`   — scan the repo for an EXISTING roadmap/PRD/spec/vision doc to
+ *                import (so we don't recreate one the project already has).
+ *   - `status` — is `contextkit/memory/roadmap.md` defined (vs the placeholder)?
+ *   - `init`   — create the seed roadmap.md if missing.
+ *
+ * Usage:  node contextkit/tools/scripts/roadmap.mjs <find|status|init> [--json]
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+const CANON = P.roadmap;
+const PLACEHOLDER = 'ROADMAP-NOT-DEFINED';
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'out', '.next', '.turbo', 'vendor', 'target', '__pycache__', '.claude']);
+const NAME_RE = /(road[\s_-]?map|^prd\b|product[\s_-]?spec|product[\s_-]?vision|^vision|^spec)\b/i;
+
+function walk(dir, depth, acc) {
+  if (depth > 3) return acc;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (!SKIP.has(e.name) && !e.name.startsWith('.tmp')) walk(join(dir, e.name), depth + 1, acc);
+    } else if (/\.(md|markdown|txt)$/i.test(e.name)) {
+      const rel = relative(ROOT, join(dir, e.name)).replaceAll('\\', '/');
+      // Don't report our own canonical/seed file as a "found" external roadmap.
+      if (rel === 'contextkit/memory/roadmap.md') continue;
+      if (NAME_RE.test(e.name)) acc.push(rel);
+    }
+  }
+  return acc;
+}
+
+function isDefined() {
+  if (!existsSync(CANON)) return false;
+  try {
+    const t = readFileSync(CANON, 'utf-8');
+    return !t.includes(PLACEHOLDER) && t.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+const cmd = process.argv[2];
+const json = process.argv.includes('--json');
+
+if (cmd === 'find') {
+  const found = walk(ROOT, 0, []);
+  if (json) console.log(JSON.stringify({ canonicalDefined: isDefined(), found }, null, 2));
+  else {
+    console.log(isDefined() ? '✅ contextkit/memory/roadmap.md is defined.' : 'ℹ️  contextkit/memory/roadmap.md not defined yet.');
+    if (found.length) {
+      console.log('\nPossible existing roadmap/PRD/spec files to import:');
+      for (const f of found) console.log(`  - ${f}`);
+    } else {
+      console.log('\nNo existing roadmap/PRD/spec found — propose one from analysis + user objectives.');
+    }
+  }
+} else if (cmd === 'status') {
+  if (json) console.log(JSON.stringify({ defined: isDefined(), path: 'contextkit/memory/roadmap.md' }));
+  else console.log(isDefined() ? 'defined' : 'not-defined');
+  process.exit(isDefined() ? 0 : 1);
+} else if (cmd === 'init') {
+  if (existsSync(CANON)) {
+    console.log('roadmap.md already exists — leaving it untouched.');
+  } else {
+    mkdirSync(P.memory, { recursive: true });
+    writeFileSync(CANON, `# Product Roadmap\n\n<!-- ${PLACEHOLDER} -->\n_No roadmap defined yet._ Run \`/roadmap\`.\n`, 'utf-8');
+    console.log('✅ seeded contextkit/memory/roadmap.md');
+  }
+} else {
+  console.error('Usage: roadmap.mjs <find|status|init> [--json]');
+  process.exit(1);
+}

package/templates/contextkit/tools/scripts/runs.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * `/runs` — lists the last N in-flight items (tasks + pipeline runs) across the
+ * project, reading the canonical state.json substrate ([ADR-0015](../../memory/decisions/0015-pipeline-dsl-working-stage-and-multi-session-work-claims.md) Part C).
+ *
+ * Read-only — never mutates state. Refuses cleanly when no state files exist
+ * ("no runs yet"). Token-light by default — prints the 20 most recent; `--all`
+ * shows everything, `--json` for machine-readable output.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/runs.mjs                # last 20, all kinds
+ *   node contextkit/tools/scripts/runs.mjs --kind task    # tasks only
+ *   node contextkit/tools/scripts/runs.mjs --kind pipeline-run
+ *   node contextkit/tools/scripts/runs.mjs --all          # no limit
+ *   node contextkit/tools/scripts/runs.mjs --json         # JSON for tooling
+ */
+import { listStates } from '../../runtime/state/state-io.mjs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const PIPE = pathsFor(ROOT).pipeline;
+const DEFAULT_LIMIT = 20;
+const STATUS_BADGE = { backlog: '📋', working: '🔵', testing: '🟡', done: '✅', running: '🔄', 'blocked-on-checkpoint': '⏸', failed: '❌' };
+
+/** Returns the value after `--name`, or undefined when absent. */
+function arg(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 && i + 1 < process.argv.length ? process.argv[i + 1] : undefined;
+}
+
+function flag(name) {
+  return process.argv.includes(`--${name}`);
+}
+
+/** Best-effort age formatter mirroring workspace-sync's `relativeTime`. */
+function ago(ms) {
+  if (typeof ms !== 'number' || ms <= 0) return '—';
+  const s = Math.floor((Date.now() - ms) / 1000);
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  return `${Math.floor(h / 24)}d ago`;
+}
+
+/** Duration when both startedAt + endedAt are present, else "—". */
+function duration(state) {
+  if (typeof state.startedAt !== 'number' || typeof state.endedAt !== 'number') return '—';
+  const s = Math.max(0, Math.floor((state.endedAt - state.startedAt) / 1000));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const sec = s % 60;
+  return h > 0 ? `${h}h ${m}m` : m > 0 ? `${m}m ${sec}s` : `${sec}s`;
+}
+
+function renderTasks(tasks) {
+  if (tasks.length === 0) return null;
+  const out = ['📋 tasks', '─'.repeat(60)];
+  for (const t of tasks) {
+    const badge = STATUS_BADGE[t.status] || '·';
+    const owner = t.ownerUser ? ` · ${t.ownerUser}` : '';
+    const branch = t.branch ? ` · ${t.branch}` : '';
+    const when = t.endedAt ? `ended ${ago(t.endedAt)} (${duration(t)})` : `started ${ago(t.startedAt)}`;
+    out.push(`  ${badge} ${t.id.padEnd(5)} [${t.status.padEnd(8)}]${owner}${branch} · ${when}`);
+  }
+  return out.join('\n');
+}
+
+function renderPipelineRuns(runs) {
+  if (runs.length === 0) return null;
+  const out = ['🤖 pipeline runs', '─'.repeat(60)];
+  for (const r of runs) {
+    const badge = STATUS_BADGE[r.status] || '·';
+    const step = r.step ? `${r.step.current ?? '?'}/${r.step.total ?? '?'} steps` : '';
+    const cycles = r.cycles && Object.keys(r.cycles).length > 0 ? `(${Object.entries(r.cycles).map(([k, v]) => `${k}×${v}`).join(', ')})` : '';
+    const when = r.endedAt ? `ended ${ago(r.endedAt)} (${duration(r)})` : `started ${ago(r.startedAt)}`;
+    out.push(`  ${badge} ${r.id.padEnd(20)} [${r.status.padEnd(10)}] ${step} ${cycles} · ${when}`);
+  }
+  return out.join('\n');
+}
+
+function main() {
+  const kindFilter = arg('kind');
+  if (kindFilter && !['task', 'pipeline-run'].includes(kindFilter)) {
+    console.error(`Invalid --kind "${kindFilter}". Use "task" or "pipeline-run".`);
+    process.exit(1);
+  }
+  const limit = flag('all') ? Infinity : Number(arg('limit')) || DEFAULT_LIMIT;
+  const all = listStates(PIPE, kindFilter ? { kind: kindFilter } : {});
+  const truncated = Number.isFinite(limit) ? all.slice(0, limit) : all;
+
+  if (flag('json')) {
+    console.log(JSON.stringify({ total: all.length, shown: truncated.length, states: truncated }, null, 2));
+    return;
+  }
+
+  if (all.length === 0) {
+    console.log('  No runs yet. Start a task with `/pipeline start <id>` or run a squad pipeline.');
+    return;
+  }
+
+  const tasks = truncated.filter((s) => s.kind === 'task');
+  const runs = truncated.filter((s) => s.kind === 'pipeline-run');
+  const sections = [renderTasks(tasks), renderPipelineRuns(runs)].filter(Boolean);
+  if (sections.length === 0) {
+    console.log(`  No ${kindFilter ?? 'state'} entries match. Total in store: ${all.length}.`);
+    return;
+  }
+  console.log('\n' + sections.join('\n\n') + '\n');
+  if (all.length > truncated.length) {
+    console.log(`  (showing ${truncated.length} of ${all.length} — pass --all for the full list)`);
+  }
+}
+
+main();

package/templates/contextkit/tools/scripts/seo-audit.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * SEO audit — static analyser for classical SEO smells (ADR-0025).
+ *
+ * Walks the project for page-shaped files (`.html`, `.astro`, `.jsx`,
+ * `.tsx`, `.vue`, `.svelte`, `.mdx`), checks each against the SEO
+ * checklist in `contextkit/workflows/playbooks/seo-aiso.md`, and emits
+ * findings as either a coloured terminal table (default) or JSON
+ * (`--json`).
+ *
+ * Exit code 1 when any `critical` finding is present (currently only
+ * SPA_ENTRYPOINT) — so CI can gate on it. Exit code 0 otherwise.
+ *
+ * Zero deps. Defensive (rule 2 — never break the dev loop).
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { detectFramework, isSpaFramework, lineOf, renderFindings, exitCodeFor, walkProject } from './audit-shared.mjs';
+
+const PAGE_EXTS = ['.html', '.astro', '.jsx', '.tsx', '.vue', '.svelte', '.mdx'];
+
+const SEVERITY = {
+  SPA_ENTRYPOINT:      'critical',
+  MISSING_TITLE:       'high',
+  MISSING_DESCRIPTION: 'high',
+  MULTIPLE_H1:         'high',
+  MISSING_CANONICAL:   'medium',
+  MISSING_ALT:         'medium',
+  MISSING_SITEMAP:     'high',
+  MISSING_ROBOTS:      'medium',
+};
+
+const finding = (rel) => (code, line, message) =>
+  ({ file: rel, code, line, severity: SEVERITY[code] || 'medium', message });
+
+/** Project-level checks: presence of sitemap.xml, robots.txt, SPA entry-point smell. */
+function checkProject(root, framework) {
+  const out = [];
+  const sitemapPaths = ['sitemap.xml', 'public/sitemap.xml', 'static/sitemap.xml', 'src/pages/sitemap.xml.ts'];
+  const robotsPaths  = ['robots.txt',  'public/robots.txt',  'static/robots.txt'];
+  if (!sitemapPaths.some((p) => existsSync(resolve(root, p)))) {
+    out.push({ file: 'public/sitemap.xml', code: 'MISSING_SITEMAP', line: 0, severity: SEVERITY.MISSING_SITEMAP, message: 'no sitemap.xml found at root, public/, or static/' });
+  }
+  if (!robotsPaths.some((p) => existsSync(resolve(root, p)))) {
+    out.push({ file: 'public/robots.txt', code: 'MISSING_ROBOTS', line: 0, severity: SEVERITY.MISSING_ROBOTS, message: 'no robots.txt found at root, public/, or static/' });
+  }
+  const indexHtml = resolve(root, 'index.html');
+  if (existsSync(indexHtml)) {
+    let html = '';
+    try { html = readFileSync(indexHtml, 'utf8'); } catch { /* defensive */ }
+    const emptyRoot = /<div\s+id=["'](root|app|__next|___gatsby)["']\s*>\s*<\/div>/i.test(html);
+    if (emptyRoot && isSpaFramework(framework)) {
+      out.push({
+        file: 'index.html',
+        code: 'SPA_ENTRYPOINT',
+        line: 1,
+        severity: SEVERITY.SPA_ENTRYPOINT,
+        message: 'empty <div id="root"></div> with no SSG/SSR framework detected — landing pages must be indexable. Pick Astro (recommended) or Next App Router; see ADR-0025.',
+      });
+    }
+  }
+  return out;
+}
+
+/** Per-file checks. The `<title>` / `<meta description>` / canonical checks fire only for HTML-shaped files. */
+function checkFile(file, text, rel) {
+  const f = finding(rel);
+  const out = [];
+  const isHtmlLike = /\.(html|astro)$/i.test(file);
+
+  if (isHtmlLike) {
+    if (!/<title>\s*[^<\s][^<]*<\/title>/i.test(text)) {
+      out.push(f('MISSING_TITLE', 1, 'no <title> in head, or <title> is empty'));
+    }
+    if (!/<meta\s+[^>]*name=["']description["'][^>]*content=["'][^"']{20,}["']/i.test(text)) {
+      out.push(f('MISSING_DESCRIPTION', 1, 'no <meta name="description"> with at least 20 chars of content'));
+    }
+    if (!/<link\s+[^>]*rel=["']canonical["']/i.test(text)) {
+      out.push(f('MISSING_CANONICAL', 1, 'no <link rel="canonical"> — Google may pick a wrong canonical'));
+    }
+  }
+
+  const h1s = [...text.matchAll(/<h1[\s>]/gi)];
+  if (h1s.length > 1) {
+    out.push(f('MULTIPLE_H1', lineOf(text, h1s[1].index), `${h1s.length} <h1> tags found; only one per page is allowed`));
+  }
+
+  for (const m of text.matchAll(/<img\b([^>]*)>/gi)) {
+    const attrs = m[1];
+    if (!/\balt\s*=/i.test(attrs)) {
+      out.push(f('MISSING_ALT', lineOf(text, m.index), '<img> without alt — refuses screen readers and SEO'));
+    }
+  }
+  return out;
+}
+
+/**
+ * Run the SEO audit against a project root.
+ *
+ * @param {string} root  absolute path
+ * @returns {{ framework: string | null, findings: object[] }}
+ */
+export function runSeoAudit(root) {
+  const framework = detectFramework(root);
+  const findings = [...checkProject(root, framework)];
+  for (const file of walkProject(root, PAGE_EXTS)) {
+    let text = '';
+    try { text = readFileSync(file, 'utf8'); } catch { continue; }
+    const rel = relative(root, file).replaceAll('\\', '/');
+    findings.push(...checkFile(file, text, rel));
+  }
+  return { framework, findings };
+}
+
+const argv = process.argv.slice(2);
+const wantJson = argv.includes('--json');
+const wantHelp = argv.includes('--help') || argv.includes('-h');
+
+const isMain = (() => {
+  try {
+    const here = new URL(import.meta.url).pathname.toLowerCase();
+    const entry = process.argv[1]
+      ? new URL('file://' + process.argv[1].replace(/\\/g, '/')).pathname.toLowerCase()
+      : '';
+    return here === entry;
+  } catch { return false; }
+})();
+
+if (isMain) {
+  if (wantHelp) {
+    process.stdout.write(`Usage: seo-audit.mjs [--json]
+
+Scans the project for SEO smells per ADR-0025. Exit code 1 on any
+critical finding (currently only SPA_ENTRYPOINT) so CI can gate.
+
+  --json   emit findings as JSON to stdout (machine-readable)
+  --help   this message
+`);
+    process.exit(0);
+  }
+  const root = process.cwd();
+  const result = runSeoAudit(root);
+  if (wantJson) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    process.stdout.write(`\n   Framework detected: ${result.framework || 'none (plain HTML or unknown)'}`);
+    process.stdout.write(renderFindings(result.findings, { title: 'SEO audit' }));
+  }
+  process.exit(exitCodeFor(result.findings));
+}

package/templates/contextkit/tools/scripts/session-digest.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Session digest — compact, deterministic view of recent session logs. [ADR-0027]
+ *
+ * Replaces "read the last N raw session files" (75–188 lines each) with a ~6-line
+ * structured digest per session, so token-heavy commands (`/distill-sessions`,
+ * `/retro`, `/tune-agents`) reason over digests and open a full log only on demand.
+ * Read-only, zero third-party deps. Parsing is single-sourced in
+ * `runtime/hooks/session-digest-core.mjs` (also used by the boot hook — rule 4).
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/session-digest.mjs            # last 10 (human)
+ *   node contextkit/tools/scripts/session-digest.mjs --last 5
+ *   node contextkit/tools/scripts/session-digest.mjs --id 2026-06-03-36-foo.md
+ *   node contextkit/tools/scripts/session-digest.mjs --json     # machine-readable
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { resolve, basename } from 'node:path';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+import {
+  SESSION_FILENAME_RE,
+  parseSessionLog,
+  renderDigest,
+} from '../../runtime/hooks/session-digest-core.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+const args = process.argv.slice(2);
+const flag = (name) => args.includes(name);
+const opt = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+
+const readSafe = (abs) => readFile(abs, 'utf-8').catch(() => null);
+
+/** Session files under the sessions dir, newest (by number, then date) first. */
+async function listSessions() {
+  let files = [];
+  try {
+    files = await readdir(P.sessions);
+  } catch {
+    return [];
+  }
+  return files
+    .map((f) => ({ f, m: SESSION_FILENAME_RE.exec(f) }))
+    .filter((e) => e.m)
+    .map((e) => ({ filename: e.f, number: Number.parseInt(e.m[2], 10), date: e.m[1] }))
+    .sort((a, b) => b.number - a.number || b.date.localeCompare(a.date));
+}
+
+/** Parse one session file into a record (null when unreadable). */
+async function recordFor(filename) {
+  const text = await readSafe(resolve(P.sessions, filename));
+  if (text === null) return null;
+  return parseSessionLog(text, filename);
+}
+
+async function main() {
+  const id = opt('--id');
+  let records;
+  if (id) {
+    const rec = await recordFor(basename(id));
+    records = rec ? [rec] : [];
+  } else {
+    const last = Math.max(1, Number.parseInt(opt('--last') || '10', 10) || 10);
+    const picked = (await listSessions()).slice(0, last);
+    records = (await Promise.all(picked.map((e) => recordFor(e.filename)))).filter(Boolean);
+  }
+
+  if (flag('--json')) {
+    process.stdout.write(JSON.stringify({ count: records.length, sessions: records }, null, 2) + '\n');
+    return;
+  }
+
+  if (records.length === 0) {
+    console.log('No session logs found (contextkit/memory/sessions/). Register one with /log-session.');
+    return;
+  }
+  console.log(`\n🧬  Session digest — ${records.length} session(s), newest first\n`);
+  const blocks = records.map((r) => renderDigest(r) || '_(unparseable session — open the full log)_');
+  console.log(blocks.join('\n\n'));
+  console.log('\nOpen a full log only if a digest flags something to inspect.');
+}
+
+main().catch((err) => {
+  console.error('❌ session-digest failed:', err?.message ?? err);
+  process.exit(1);
+});