horizontwo/Lenzon-Platform PR #34 — UI Phase 2: Doctrine-first organization — PR #34
horizontwo/Lenzon-Platform · pull request #34 ·
Transcript
PlainEnglish
Let's walk through PR number thirty-four — UI Phase Two. This is a major reorganization of the Lenzon Platform's documentation interface. It touches twenty-three files with nearly three thousand lines added. The goal is to shift from an error-first view to a planning-first view, teaching users how the system is organized rather than just showing them what's broken.
PlainEnglish
Here's what we're pursuing. The two primary objectives are grouping docs by the planning doctrine instead of worst-drift-first, and landing scan rows in the real viewer instead of the mini player. Four supporting goals: adding health visualizations, connecting L2 docs to their delivery scans, extending the snapshot schema with lineage and impact metadata, and generating an MCP tool reference that won't drift. And two constraints — we're trimming the nav to three tabs, and we're only rearranging the facts, not changing them.
PlainEnglish
Phase One shipped the Docs tab as a worst-drift-first list. That taught readers that errors exist, but it never taught them how planning is organized. The surface read as an error report, not a planning system. Phase Two reverses that. Instead of sorting by drift, we group by doctrine level — concept, tactical, canonical, reference — in fixed order, with drift as a badge. The planning method becomes the story, and the health metrics support it.
Architecture
The heart of the first objective lives here. We define four doctrine sections in immutable order: concept, tactical, canonical, and reference. The doctrineSections function takes the flat list of docs and groups them by their level, then sorts within each section by most recent activity rather than by drift. Retired tactical plans — landed, superseded, or archived — get grouped separately so active plans stay above the fold.
Architecture
Here's the second primary objective. RunsClient used to open the mini player at /generate, which had no playback controls and wasn't shareable. Now it links to the real viewer at /viewer/scriptId. That's the same surface you get when you open a scan from anywhere else — full playback, scrubbing, sharing. And because RunsClient is now generic, we reuse it on the repo Scans tab with a repoUrl filter. One component, two surfaces, same behavior.
Architecture
The deliveries module is new. It joins L2 tactical docs to their delivery scans by looking up the delivered-by PR numbers in the analysis ledger. There are three states: watchable when a script exists, analysed when we have the analysis but no script yet, and none when the PR hasn't been scanned. Unjoinable references — a doc that cites a PR number we can't find — are reported as errors rather than silently dropped. And the whole join is batched to one database round-trip per page, so the panel stays fast.
Architecture
The Health tab gains two new visualizations. First is the Doctrine View — a static diagram that shows the three planning levels and how PRs connect them. It teaches the method without motion. Second is the Orbit View, a d3-force simulation where docs orbit the repo at a radius driven by staleness, sized by their blast radius, and connected by lineage edges. It shows the shape of the planning system at a glance. The existing stat tiles stay at the bottom as validation.
Architecture
The snapshot schema gains four new fields. deliveredBy holds PR numbers or strings for L2 docs that cite their delivery scans. derivesFrom and supersedes capture lineage — which docs this one evolved from or replaced. And impacts holds glob patterns showing which parts of the codebase the doc affects. All four are optional and additive. Snapshots from workers predating this PR won't have them, and they'll render as empty arrays rather than inventing coverage. The facts underneath don't change; we're just capturing more of them now.
PlainEnglish
Here's what the codebase looks like after this lands. The Docs tab teaches the planning doctrine first and shows drift as a badge. Scan rows open in the real viewer with full playback. The Health tab shows the system's shape — the doctrine diagram, the orbit, and the validation counts. Navigation is trimmed to three tabs: Health, Docs, and Scans. And the snapshot schema is extended to capture delivery links, lineage, and blast radius. The facts underneath — the docs, the lanes, the ledger — are untouched. Only their arrangement changed.
CodeQuality
One thing to keep an eye on. In the byActivityThenPath sort function, unparseable dates return NaN from Date.parse. The comparison bm minus am on line seven will return NaN if both dates are unparseable, which is falsy in the sort context and could lead to undefined order. The function does handle this with the aHas not-equals bHas path check, so there's no bug. But the only documentation of this anti-pattern is in a comment on lines two-twenty-three and two-twenty-four. It's correct, just subtle.
PlainEnglish
This is a disciplined refactor that shifts the Lenzon Platform's narrative from error-first to planning-first. The objectives are clear, the constraints are respected, and the facts are preserved. I'd approve with a couple of notes. First, gates two and seven are documented as still owed — confirm the docGraph delivery from the clone worker in a real Fargate run, and validate the byte-comparable output from the capture freeze. Second, review the NaN handling comment in byActivityThenPath for clarity. Otherwise, this is ready to merge. Nice work.
How this was made
Lenzon read horizontwo/Lenzon-Platform at pull request #34 and generated this walkthrough automatically. The narration above is the transcript of what it says.
Explain a pull request from your own repo
Point Lenzon at a repo or a pull request and get a narrated walkthrough like this one.
Try it