Phase 10: "How this works" analysis (T-10.14) + cleanup/retro (T-10.15)

[Mkohler4]

Finishes the last two Phase 10 tasks, in two commits.

Commit 1 — feat(app): "How this works" on-demand analysis (T-10.14)

A single quiet How this works disclosure on the module page opens an
AI-written walkthrough of a module's design — a plain-language summary, the
data flow (input → transform → output), the key functions, what it touches, and
its honest limits. The long form of the T-10.8 input signature.

Decision (the task's "decide and report"): generated app-side and cached on
first request, not at engine extraction. The engine extractor makes no LLM
call and the manual-approve path is pure Swift with no engine, so an
engine-only cache would leave every manually-approved and older module
permanently unanalyzed. Generating in the app — where the user's
provider/model/key already live — is one mechanism that covers every module and
honors the hard constraints:

• instant on open (reads the cache; never a live model call at view time),
• never auto-summoned on page open — unanalyzed/older modules show a quiet
  "Not analyzed yet" with a single on-demand "Analyze" action (the refining-loop
  rule),
• generated once, then cached in a new app-only, additive Schema v7
  (module_analyses, keyed per module, upsert-in-place).

Mono is used only for the code references inside the analysis. A
GUNK_DEBUG_HOW_IT_WORKS=closed|open|missing hook stages the states.
New ModuleAnalysis / ModuleAnalysisComposer (pure prompt + JSON schema +
parse) / LiveModuleAnalysisGenerator, Store read/list/upsert, and a
BrowseModel cache + generateAnalysis seam.

Commit 2 — chore(app): phase-10 cleanup, regression pass, retro (T-10.15)

• Deleted the orphaned legacy RunConsoleView — superseded by
  RunConsoleStageView when the v2 run console landed (T-10.9), yet never
  instantiated anywhere (rg confirmed zero references; the screenshot hooks live
  on the still-used RunConsoleModel). T-10.13 had even updated its deferred
  label copy — editing dead code. File renamed to RunConsoleModel.swift to
  match its sole surviving content. The inline ModuleDetailView was already
  gone (T-10.4).
• ADR-0017 (MCP run tool) → Accepted (implemented in T-10.12); both
  Phase 10 ADRs (0016 sandbox, 0017 run tool) now linked from the roadmap.
• Roadmap Phase 10 items checked off (the "Tested badge" item recorded as
  superseded by the coverage ledger + sign-off per CP-F; UI-module launch left
  open as deferred). docs/retros/phase-10.md written; CHANGELOG updated.

Constraints / verification

• Schema v7 is app-only, with no mcp/src/schema/v7.sql — the gunk-mcp and
  TS-engine migrators pin LATEST_VERSION = 4 and read explicit columns, so v7
  is invisible to them. The schema-parity check still passes (v0–v4 only).
• toolbox-v2 constraints hold: graphite surfaces, mono only for
  paths/code/terminal, accent green only on earned meaning, glass on the
  controls layer; the two-surfaces rule (smoke run ≠ extraction inspector) is
  intact.
• Build + tests green: 257 passing, 1 sandbox-availability skip.

Test plan

• cd app && swift build && swift test (257 passing, 1 skip)
• Open a real module → How this works → "Analyze" → confirm it generates,
  caches, and re-opens instantly; mono only on the code references.
• Older/unanalyzed module shows the quiet "Not analyzed yet" + single
  Analyze action (no model call on page open).
• Regression pass at 960×600 and default width across every run state
  (GUNK_DEBUG_MODULE_PAGE + GUNK_DEBUG_RUN_CONSOLE + GUNK_DEBUG_HOW_IT_WORKS).

Made with Cursor

[netlify]

✅ Deploy Preview for velvety-moxie-c6d22b canceled.

Name	Link
🔨 Latest commit	242af9c
🔍 Latest deploy log	https://app.netlify.com/projects/velvety-moxie-c6d22b/deploys/6a32f04b91ed47000897957b