Epic: comprehension family, prerequisites contract and shared-code amendment

[kyle-sexton]

Brief

Source: PLAN, topic karpathy-comprehension

Program: comprehension family, prerequisites contract, shared-code amendment. Sources: Karpathy (X, 2026-10-02: STE writing, diagrams, HTML, narrated explainer videos), Thariq Shihipar's HTML-effectiveness corpus, Matt Pocock (wait-what; STE fails as CLAUDE.md or output style). Every decision below is settled; the sub-issues implement them and do not re-decide them.

Settled decisions

• Markdown is the record; HTML, MP4 and audio are views. Views never sit beside the record (rendered-views README, "markdown is the record").
• HTML views are interactive by default, tailored per use case; static only for reports (which may still filter, collapse or animate). Tiers: static, client-interactive, animated, Claude-interactive.
• Content classes: K0 session-authored and K1 this repo's files may use model-written script; K2 attacker-controllable (PR diffs, fetched web text, other repos' files) is builder-only: a checked-in template plus escaped JSON data, never model-written script.
• Thin intent-named skills; no generic HTML skill.
• Publish destination via the existing cascade key medium (auto|terminal|file|artifact); the PR digest ships artifact as its default (amend the rendered-views README); the owner's personal layer sets medium: file (multi-account).
• Mermaid in local pages: pre-render to SVG with a pinned mmdc when present, else source. Artifacts render Mermaid natively.
• No versioning of formats anywhere in this program: one format, migrate every consumer in the same change, document the convention. Breaking plugin owners is accepted; they update.
• No upstream filings to Anthropic; work around platform gaps.

Names (naming run + validator audit)

• PR digest skill: review:explain-change (replaces review:pr-explainer; leave a one-release stub pointing to it).
• Explainer: grow education:eli5 into the single explainer skill under a new verb-phrase name (short naming round inside its own item); education:explain stays the in-chat one-shot.
• TTS plugin speech, skill narrate (description says text-to-speech; ElevenLabs discloses third-party egress).
• Video plugin explainer-video, skill produce (leaf-name registry entry beside animation:produce).
• Libraries: session-bridge, view-builder.mjs + view-runtime.js (runtime inlined per page).
• Folder convention: record-bundle (record + diagrams + media; views written outside it).

Waves (dependency order)

Wave A: foundations, independent

• A1. Shared-code amendment to ADR 0019. One canonical source per shared library; per-plugin copies are generated output (a header marks them generated), regenerated by one local script or commit hook; CI verifies only and never commits; the version-bump gate stays. Pilot on html-escape, then migrate all 18 sync clusters and retire the hand-run sync scripts. Symlinks were rejected: default Git for Windows checks them out as text stubs. Accept: ADR amended; one regen command; CI drift gate verify-only; all clusters migrated; tests green.
• A2. Prerequisites contract, one format, all plugins. Single prerequisites.json schema at each plugin root (fields: id, kind cli|runtime|system-lib|python-pkg|node-pkg|env|mcp, need required|optional, for, detect incl. version floor, degrade, per-manager install hints never executed, check); plugin-to-plugin deps use native plugin.json dependencies; secrets use native userConfig. Convert all 22 existing files and declare the ~46 undeclared plugins in the same program; shared Node checker lib/prerequisites.mjs distributed per A1 into plugins that declare deps, plus a deterministic sh/pwsh stub that reports node missing; hook::require <id>; session-start notices only for hook dependencies, skills report at use; node-missing notice in every hook plugin, deduplicated to one per session and working without Git Bash; notices name /<plugin>:check (three plugins whose check means something else get check-prerequisites); CI gate fails on undeclared tools in changed files; harness-ops fleet reader moves to the Node checker. Convention documented under docs/conventions.
• A3. Python on-demand dependencies: extend docs/conventions/on-demand-dependencies from npm to Python: hash-locked requirements installed from a hook into ${CLAUDE_PLUGIN_DATA}; no runtime uv run fetching. Accept: convention section, one reference implementation, tests.
• A4. Untrusted-text escaping for the remaining HTML lanes: eli5, knowledge:video-digest, education:teach (codebase mode), harness-ops:observability, event-storming:simulation through the escape helper; register eli5 in the rendered-views emitter list. (quiz-me done in fix(education): escape diff-derived text in quiz-me reports #5821.)
• A5. Small doc and bug fixes: stale "until the escape helper ships" (visualize, architecture:improve); stale cross-account sharing claim in the rendered-views README (email invites now exist); visualization userConfig.medium default "auto" may shadow the cascade file (verify, fix: inherit/omit default); STE rule fixes in write-for-humans (hard 20-word cap, add rules 6.5, 6.6, 3.2, STEMG AI caveat); cross-links eli5/visualize and wait-what/explain/clarify; the "no cream" style rule vs the cream shared chrome; source-control top-level bin/ blocks claude.ai org sync.

Wave B: comprehension conventions and libraries

• B1. Rendered-views convention v2 plus record-bundle convention: tiers, content classes K0-K2, interactive validator profile, rung guidance (when text beats a diagram, page or video), amend the generator-skill ban and the dual-audience rule (keep "offer" for agent-reread reports; person-facing views emit interactive by default), publish default for the digest. Docs only; security gate review required.
• B2. view-builder.mjs + view-runtime.js: report and interactive profiles, SVG allowlist, JSON data block, CSP hashes, hostile-input corpus tests, file:// and Artifact both; distributed per A1. Depends: A1, B1.
• B3. Mermaid gate in visualization: parse plus optional pinned-mmdc SVG pre-render; map-* opt-in. Depends: A2 (declares mmdc).
• B4. session-bridge: extract the transport from planning/surface into the shared lib (planning first, behaviour identical, its suites gate it); transport is a port with the existing loopback watcher adapter and a native channels adapter (research preview; needs claude.ai or Console auth and org enablement). Depends: A1.

Wave C: products

• C1. review:explain-change (reopens review-evidence artifacts: change digest, execution recordings, visual-quality inspector role — plus a shareable artifact-storage seam #1217): per-PR digest (why, before/after, annotated hunks, risk map checked by a fresh-context agent, optional quiz section, run-e2e recording link), interactive view by default, digest_policy off|offer|always (default offer; offer triggers: >5 files, >200 changed LOC, blast radius HIGH/CRITICAL, risk paths, opt-in label; always builds at ready, never posts to the PR, never gates merge), thresholds in a docs/conventions/review-digest.md cascade concern; pr-explainer stub for one release. Depends: B1, B2.
• C2. Explainer skill (grown from eli5): concept or codebase topic, interactive page default, markdown, and video view via explainer-video when installed; STE register option sourcing write-for-humans rules; zero-knowledge preset replaces eli5. Depends: B1, B2; B3 helps.
• C3. speech plugin: narrate skill, backends kokoro (default; GPL espeak-ng installed by the user, not shipped) and elevenlabs (ELEVENLABS_API_KEY env var; estimate of characters, host and cost before every call; org egress floor key), writes narration.wav + words.json (forced alignment when the backend lacks word timings), setup/check, prerequisites per A2, Python deps per A3. Depends: A2, A3.
• C4. explainer-video plugin: produce skill; ManimCE first (Python 3.12/3.13, manim[typst] for math, LaTeX slot later); audio-first timing from speech word timings; low-quality render, ffprobe duration check, frame extraction read back as images, overlap check; final render and ffmpeg mux with captions. Depends: C3, A2, A3.
• C5. Per-producer interactive views for the Thariq use cases (map-* views, flowchart, figure sheet, post-mortem, blindspot, status report, triage board, plan view, brainstorm), slides and design system via Artifact types; follows rendered-views: reports and research genre lanes (visualization/education/knowledge) #3606's order. Depends: B2.
• C6. Claude-interactive adopters on session-bridge: triage board, plan view, explain-change author Q&A, brainstorm. Depends: B4, C5.

Related

• Relates to rendered-views: reports and research genre lanes (visualization/education/knowledge) #3606 (reports and research genre lanes; overlaps the per-producer views).
• Relates to rendered-views: migrate the grandfathered HTML-emitting surfaces to the convention (fleet ladder sweep + evals reconciliation) #3603 (migrate grandfathered HTML surfaces; overlaps the escape-helper routing and view-builder).
• Relates to rendered-views: interactive userConfig smoke test on the current CLI (gates the fleet sweep) #3604 (interactive userConfig smoke test; overlaps the visualization medium default bug).
• review-evidence artifacts: change digest, execution recordings, visual-quality inspector role — plus a shareable artifact-storage seam #1217 is reopened as the explain-change core item under this container.

Execution shape: per-item PRs