feat(architecture): interactive views for the map-* records

[kyle-sexton]

Closes #5863

Summary

Each architecture:map-* skill can now offer an interactive view of its JSON record, built only with lib/view-builder.mjs and lib/view-runtime.js (#5937). The markdown and the record stay the record. Part of #5835 (comprehension family); relates to #3606.

Fix

• plugins/architecture/scripts/build-view.mjs <kind> --record <file> fills one checked-in template, templates/map-view.html, through the builder's interactive profile. Scalars in the record become header facts, each array is counted and its items become rows (an edge row is named from -> to), and the page is written under the OS temp directory. No page holds model-written markup or script, so repository text stays data.
• The page offers a filter that traces an id through every row that names it, and rows that open to their fields and citations. It draws no diagram; the markdown holds that.
• --from <node-id> keeps the closure reachable from a deployable, which is how map-components charts one deployable from dependency-graph.json.
• reference/rendered-view.md holds the lane procedure: offer after the record, resolve medium from the rendered-views cascade (file when unset; artifact publishes through the Artifact tool and degrades to the path with a reason; terminal builds nothing), and the kind-to-record table. All nine map skills (landscape, containers, components, dependencies, data, events, flow, context, deployment) carry a short ## Interactive view section and one eval.
• The plugin carries generated copies of view-builder.mjs, view-runtime.js and html-escape.mjs, registered in scripts/shared-copies.txt. architecture bumped 0.19.0 to 0.20.0 with a CHANGELOG entry; the rendered-views README and CHANGELOG list the new emitters.
• The mermaid gate (feat(visualization): mermaid gate with parse and optional pinned-mmdc svg pre-render #5974) is not depended on.

Verification

• bash plugins/architecture/scripts/build-view.test.sh: 42 checks pass. All nine kinds build and pass the interactive profile (view-builder.mjs --check), hostile text stays inside the JSON block and as text in headless Chromium opened from file://, --from keeps the right closure, and bad input exits 1 or 2. The private output directory and the symlinked-output case are covered.
• Built a page from a real dependency-graph.json that dependency-graph.sh wrote for a three-project fixture; it passes the profile.
• bash scripts/affected-tests.sh --run --jobs 4: 64 shell suites pass; node scripts/check-declared-prerequisites.test.mjs passes.
• sync-shared-copies.sh --check and --check-bump origin/main, check-changelog-parity.sh (--check, --check-bump, --check-order, --check-preserved), check-html-assets.sh, check-changed-skills.sh origin/main (all nine map skills pass), markdownlint-cli2 and htmlhint on changed files: clean.
• Not exercised: rendering inside the live Artifact host, and the page was not built from records of the other eight collectors (the row flattening is generic over top-level arrays and objects; the tests use a hand-built record of that shape).

Related

• Epic: comprehension family, prerequisites contract and shared-code amendment #5835 (spec container), feat(lib): view-builder.mjs and view-runtime.js with report and interactive profiles #5852 (builder, merged as feat(lib): add view-builder.mjs and view-runtime.js with report and interactive profiles #5937), rendered-views: reports and research genre lanes (visualization/education/knowledge) #3606 (reports and research genre lanes), planning: plan and brainstorm views #5866 (plan and brainstorm views, the same pattern).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-03T07:29:38.555495Z	3d3552c	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Claude finished @kyle-sexton's task in 4m 47s —— View job

---

Claude code review complete

• Gather context (PR body, diff, CLAUDE.md/REVIEW.md)
• Review new lib code (view-builder.mjs, view-runtime.js, html-escape.mjs)
• Review build-view.mjs script and its test suite
• Review template and skill doc changes
• Verify candidate findings adversarially
• Post inline comments and final summary

Summary

This lane owns correctness, design, conventions, error handling, and tests — REVIEW.md scopes
security findings (XSS/injection/trust-boundary concerns in view-builder.mjs, view-runtime.js,
and the CSP/escaping logic) exclusively to the claude-security-review lane, which runs on this
repo (.github/workflows/claude-security-review-hosted.yml), so I left those out.

I traced the new code paths closely:

• plugins/architecture/scripts/build-view.mjs's closureFrom, rowOf, and viewData against the
  hand-built fixture in build-view.test.sh (row counts, edge naming, --from closure, scalar/array
  flattening) and against the nine map-* record shapes described in reference/rendered-view.md.
• lib/view-builder.mjs's interactive-profile build/validate round trip (marker placement, CSP
  position, script extraction) against lib/html-escape.mjs's shared escaping helpers.
• All nine SKILL.md "## Interactive view" sections, their evals.json additions, and the
  bookkeeping files (scripts/shared-copies.txt, scripts/cross-plugin-source-registry.txt,
  both CHANGELOGs, plugins/architecture/README.md) for drift against the kind-to-record table.

Everything checked out consistent — each skill's eval references the right record/kind pair, the
generated-copy registrations match the three new shared files, and the doc tables agree with
build-view.mjs's TITLES/kind list. The one logic path worth noting but not rising to a
blocking finding: closureFrom's edge filter
(build-view.mjs#L70)
keeps an edge once seen.has(edge.from) without also requiring seen.has(edge.to), so a
malformed edge whose to isn't a string would stay in the closure's edge list even though its
target was never added to the node set. This only triggers on a record that violates the
documented nodes/edges shape (collectors always emit string to values here), so I'm not
filing it as a review-blocking item — flagging only for awareness.

No inline comments filed; I found no correctness or maintainability issue meeting this lane's
high-signal bar. Author-claimed verification (the 42 build-view.test.sh checks, the
dependency-graph.sh-derived page, sync-shared-copies/check-changelog-parity/lint runs) is
unverified by me — I did not execute those commands myself.

[claude]

Claude finished @kyle-sexton's task in 3m 7s —— View job

---

Security review — /review:security-review

• Gather context (diff, changed files)
• Check instruction-exception-register (no instruction-surface deletions in this PR's actual file set — an apparent AGENTS.md diff was an artifact of a stale local origin/main ref in this checkout, not part of PR feat(architecture): interactive views for the map-* records #6062's 32 changed files)
• Review lib/view-builder.mjs, lib/view-runtime.js, lib/html-escape.mjs for XSS/escaping correctness
• Review scripts/build-view.mjs for path/command injection, temp-file handling
• Review templates/map-view.html for unsafe sinks
• Review test script and skill docs
• Post findings

No security issues found.

This PR wires the architecture plugin's nine map-* skills onto the existing, previously-reviewed shared builder (lib/view-builder.mjs / lib/view-runtime.js / lib/html-escape.mjs, canonical copies under root lib/, byte-identical to the plugin copies modulo the generated-file header — verified directly). What's new here is plugins/architecture/scripts/build-view.mjs, plugins/architecture/templates/map-view.html, and the skill docs. I checked each against the threat model stated in the PR itself: the JSON record is attacker-influenceable repository text (paths, hostnames, citations), so it must never become markup or script.

• Data flow stays data. build-view.mjs flattens the record into facts/rows as plain strings, handed to buildView({ profile: "interactive", ... }). The builder serializes that via JSON.stringify into a <script type="application/json"> block with < escaped to < (view-builder.mjs#L262-L267), which blocks any </script/<!-- breakout. The runtime (view-runtime.js) only ever reads that block via JSON.parse and writes it back via .textContent — no innerHTML, insertAdjacentHTML, document.write, eval, or Function anywhere in the diff (grepped the whole plugin). IDs assigned to rows are built from a template-defined key + list position, never from data, so even a "copy row" payload can't carry record text into a selector or attribute.
• CSP + structural validator as defense in depth. The page's CSP pins script-src to the SHA-256 of the exact inlined runtime and sets default-src 'none', style-src '<hash>', base-uri 'none', form-action 'none' (view-builder.mjs#L102-L111). validateInteractivePage then re-parses the built page and fails closed on any unexpected tag, attribute, unescaped text, extra <script>, or CSP mismatch (view-builder.mjs#L411-L471), and build-view.mjs ties that check into the write path. templates/map-view.html itself carries no <script> and only data-rv-* bindings — confirmed by reading the file.
• Test coverage matches the threat model. build-view.test.sh's hostile payload (</script><img src=x onerror=alert(1)><svg onload=alert(1)>"'\${1}`) exercises script-breakout, event-handler, quote-breakout and template-literal-injection vectors together, and the suite asserts the payload stays inside the JSON block and renders as literal text in headless Chromium (build-view.test.sh#L56, #L123-L137).
• Temp-file handling. The output directory is created 0o700, chmodSync'd regardless, and rejected if lstatSync shows it's not a real directory (catches a pre-planted symlink); the output file itself is removed with rmSync({force:true}) before writeFileSync(..., {mode:0o600}), so a pre-planted symlink at the file path is replaced rather than followed (build-view.mjs#L113-L121) — and the test suite exercises exactly that symlink-replacement case. This is a shared temp directory (tmpdir()/architecture-views) but the pattern is the standard secure-tempfile idiom and multi-user races fail closed (an EPERM from chmodSync against a dir owned by another uid surfaces as exit 2, not a silent write into attacker-controlled storage).
• --from <node-id> and kind are both constrained: kind must be one of nine hardcoded enum keys (so the output filename ${kind}.html is never attacker-influenced), and --from is only ever used for string comparison against node ids, never interpolated into markup, a path, or a shell command.
• No eval/Function/shell-injection surface: build-view.mjs and view-builder.mjs take file paths from CLI args and read them with readFileSync/JSON.parse; nothing shells out with record-derived strings.

Per this lane's scope, GitHub Actions hardening (triggers, permissions, pinning) is deferred to zizmor and not re-reviewed here — no workflow files are touched by this PR anyway.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3d3552c723

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

claude-security-review has reviewed this pull request through 798c3eb; a later push is reviewed from there.

[github-actions]

claude-review has reviewed this pull request through 798c3eb; a later push is reviewed from there.

[claude]

Claude finished @kyle-sexton's task in 54s —— View job

---

Security review — /review:security-review (incremental)

• Gather context (PR body, diff, incremental.diff, CLAUDE.md/REVIEW.md)
• Read .claude-lane/incremental.diff for the actual scope
• Review plugins/architecture/scripts/build-view.mjs changes
• Review plugins/architecture/scripts/build-view.test.sh changes
• Review plugins/architecture/reference/rendered-view.md changes
• Post findings

No security issues found.

This lane last reviewed 8c5871d5db4caea57b0621a89c4faf529157f231. The diff to the current head
(f923391) touching the three files in scope is entirely non-functional:

• plugins/architecture/scripts/build-view.mjs: file mode 100644 → 100755 (executable bit
  only), no content change.
• plugins/architecture/scripts/build-view.test.sh: same, file mode 100644 → 100755 only.
• plugins/architecture/reference/rendered-view.md: one-word spelling fix, labelled →
  labeled, in prose describing how rows are named.

Confirmed via git diff 8c5871d5db4caea57b0621a89c4faf529157f231..f923391203e2c723bf2ed60b648856fec3f6b5b3 -- plugins/architecture/scripts/build-view.mjs plugins/architecture/scripts/build-view.test.sh,
which shows only the mode-bit changes — no data flow, escaping, CSP, temp-file, or input-handling
logic changed since the last review. That prior review already covered the full
build-view.mjs/view-builder.mjs/view-runtime.js data flow for this PR and its conclusions
remain valid at this head.

[claude]

Claude finished @kyle-sexton's task in 39s —— View job

---

Claude incremental code review complete

• Gather context (PR body, incremental diff, CLAUDE.md/REVIEW.md)
• Read .claude-lane/incremental.diff (changes since 8c5871d)
• Review plugins/architecture/reference/rendered-view.md
• Review plugins/architecture/scripts/build-view.mjs
• Review plugins/architecture/scripts/build-view.test.sh
• Verify candidate findings adversarially
• Post inline comments and final summary

Summary

This lane's incremental scope is the diff since this lane's last review at 8c5871d, covering
plugins/architecture/reference/rendered-view.md, plugins/architecture/scripts/build-view.mjs,
and plugins/architecture/scripts/build-view.test.sh. The actual change in that window
(git diff 8c5871d f923391 -- <those three files>) is:

• reference/rendered-view.md: one spelling fix, labelled → labeled
  (permalink).
• build-view.mjs and build-view.test.sh: file-mode change only (100644 → 100755, making
  the scripts executable); no content changed.

This matches the commit in that window, fix(architecture): mark the view scripts executable and fix a spelling. Per this lane's skip gate, a change this trivial/automated has no meaningful
review surface — no inline comments to post.

The prior pass on this PR already reviewed build-view.mjs's logic (including the closureFrom
edge-filter note) and the rest of this PR's files through 8c5871d; that review stands unchanged
since nothing in its reviewed content moved.

[claude]

Claude finished @kyle-sexton's task in 43s —— View job

---

Security review — /review:security-review (incremental)

• Gather context (PR body, .claude-lane/incremental.diff, CLAUDE.md/REVIEW.md)
• Read the incremental diff for the actual scope (change since f923391)
• Review plugins/architecture/scripts/build-view.mjs changes (closureFrom)
• Review plugins/architecture/scripts/build-view.test.sh changes
• Review plugins/architecture/reference/rendered-view.md changes
• Post findings

No security issues found.

This lane last reviewed f923391203e2c723bf2ed60b648856fec3f6b5b3. The diff to the current head
(da355fe357b930c5a0d22304b617fd4d2168d0d8) is commit da355fe, fix(architecture): follow only resolved project edges in the component closure — this is exactly the fix for the P2 correctness
finding Codex raised on the prior commit (closureFrom adding an edge's to to the closure
without checking edge kind/resolution/target kind).

• build-view.mjs#L50-L80:
  closureFrom now only follows an edge into the closure when edge.kind === "project",
  edge.status !== "unresolved", and the target is itself a project-kind node id (projects.has(edge.to)),
  matching the reachability rule render-components.sh already applies. The final edge filter
  also now requires seen.has(edge.to) in addition to seen.has(edge.from)
  (build-view.mjs#L79),
  so a malformed or out-of-scope edge can no longer survive into the emitted closure's edge list.
• This tightens what data reaches the page (fewer, more correctly-scoped nodes/edges) rather than
  loosening it — no new data-flow, escaping, CSP, or temp-file-handling surface is touched, and all
  values still reach the page only as JSON data through the unchanged view-builder.mjs path.
• build-view.test.sh adds one fixture (mixed) with a package edge and an unresolved project
  edge alongside a resolved one, and asserts --from follows only the resolved project edge
  (build-view.test.sh#L123-L137) —
  this is test coverage for the fix above, no security-relevant content itself.
• reference/rendered-view.md's one-line wording change documents the new, narrower --from
  semantics; it states no security property and introduces none.

Per this lane's scope, GitHub Actions hardening is deferred to zizmor and not re-reviewed here —
no workflow files are touched by this change. The prior full-scope review on this PR (through
8c5871d) and the mode-bit/spelling-only incremental review (through f923391) both remain valid;
nothing in their reviewed content moved in this diff.

[claude]

Claude finished @kyle-sexton's task in 2m 32s —— View job

---

Claude incremental code review complete

• Gather context (PR body, incremental diff, CLAUDE.md/REVIEW.md)
• Read .claude-lane/incremental.diff (changes since f923391)
• Review plugins/architecture/scripts/build-view.mjs's closureFrom rewrite
• Review plugins/architecture/scripts/build-view.test.sh's new mixed case
• Review plugins/architecture/reference/rendered-view.md's doc update
• Compare against render-components.sh's eclass/bfs semantics for parity
• Verify candidate findings adversarially
• Post summary

Summary

This lane's incremental scope is the diff since this lane's last review at f923391, covering
plugins/architecture/reference/rendered-view.md, plugins/architecture/scripts/build-view.mjs,
and plugins/architecture/scripts/build-view.test.sh. This window is the direct fix for the one
non-blocking item Codex flagged
on the prior commit ("Restrict component closure to internal project edges").

closureFrom now builds a projects set (node kind === "project"), grows seen only across
edges with kind === "project", status !== "unresolved", and a target already in projects
(build-view.mjs#L56-L73),
and the final edge filter now requires both seen.has(edge.from) and seen.has(edge.to)
(build-view.mjs#L79),
closing exactly the gap Codex named: a malformed or unresolved edge no longer rides along just
because its from end was reached.

I checked this against the sibling implementation it says it mirrors,
plugins/architecture/skills/map-components/scripts/render-components.sh's eclass/bfs
(lines 562-568, 598-610ish): that script classifies an edge as "project" only when
kind == "project" && status != "unresolved" && efrom in is_project && edge_to in is_project, and
bfs() only grows reached across edges of that class. build-view.mjs's growth condition is the
same rule, modulo one deliberate difference: render-components.sh's bfs refuses to start at all
unless the start node itself is is_project, while build-view.mjs seeds seen with --from's
node unconditionally. That matches this plugin's own doc, which calls the --from argument "that
deployable" rather than "that project" — a deployable root need not carry kind: "project" for its
own node entry, only the components beneath it need to. Not a bug.

One nuance worth naming but not blocking: the final edge filter admits any edge (regardless of
kind/status) once both endpoints land in seen, not just the resolved-project edges used to
grow the closure. So an unresolved project edge between two nodes that both became reachable via
other resolved edges would still appear in the closure's row list. That reads as intentional given
the updated doc's own wording — "keeps the project nodes reachable... over resolved project edges,
and the edges between them" (rendered-view.md#L49)
reads as "nodes first, then all edges among them," not "only resolved-project edges." The new
mixed test in build-view.test.sh doesn't exercise that specific case (its unresolved edge's
target, D, isn't reached by any other path), but the behavior matches the doc as written, so I'm
not filing it.

No inline comments: nothing in this incremental window meets this lane's high-signal bar. The new
mixed fixture (build-view.test.sh#L123-L138)
correctly isolates the three edge shapes (resolved project, package, unresolved project) and asserts
exactly the surviving closure (A|B|A -> B), which lines up with the new closureFrom logic by
hand-tracing it. Author-claimed verification (that this test and the other 42 checks pass) is
unverified by me — I did not execute build-view.test.sh myself.
· branch feat/5863-map-interactive-views

[claude]

Claude finished @kyle-sexton's task in 1m 9s —— View job

---

Claude code review complete

• Gather context (PR body, CLAUDE.md/REVIEW.md, prior lane comments)
• Check skip gate / what changed since this lane's last review
• Review new/changed code since last review
• Verify candidate findings adversarially
• Post inline comments and final summary

Summary

This lane last fully reviewed this PR through da355fe357b930c5a0d22304b617fd4d2168d0d8 (the
closureFrom fix for Codex's P2 finding). The current head, 798c3eb73ea97ed2f691830551fb9af471e491ab,
adds only one commit on top: 9671ece, a merge of origin/main into this branch.

I diffed da355fe..798c3eb scoped to this PR's own files
(git diff da355fe..798c3eb -- plugins/architecture docs/conventions/rendered-views scripts/cross-plugin-source-registry.txt scripts/shared-copies.txt)
to find the actual delta:

• docs/conventions/rendered-views/CHANGELOG.md / README.md: new entries for unrelated PRs
  (debugging:debug, discovery:blindspot views, debugging/discovery: views for the debug post-mortem and the blindspot report #5864) landed from main; this PR's own
  "map-* skills offer views on the builder" entry is untouched.
• plugins/architecture/CHANGELOG.md: one new [0.20.1] entry from main for a shared
  prerequisites.sh/prerequisites.ps1 sync, unrelated to this PR's content.
• scripts/cross-plugin-source-registry.txt / shared-copies.txt: new registrations from main
  for other plugins (debugging, discovery, work-items, toolchain, harness-ops) adopting
  the shared view builder — none of this PR's own entries changed.
• No file under plugins/architecture/lib/, plugins/architecture/scripts/,
  plugins/architecture/templates/, or any map-* skill changed at all in this window.

So the merge brought in unrelated upstream work and bookkeeping for other PRs, but introduced no
new content in this PR's own review surface. Per the skip gate ("this head already has a
successful review from this lane that still applies"), the prior review stands unchanged — no new
findings, no inline comments.
· branch feat/5863-map-interactive-views

[claude]

Claude finished @kyle-sexton's task in 1m 32s —— View job

---

Security review — /review:security-review (incremental)

• Gather context (PR body, .claude-lane diff context, CLAUDE.md/REVIEW.md, prior review comments)
• Determine incremental scope since this lane's last review (da355fe357b930c5a0d22304b617fd4d2168d0d8)
• Confirm whether any security-relevant content changed
• Post findings

No security issues found.

This lane last reviewed da355fe357b930c5a0d22304b617fd4d2168d0d8. The current head,
798c3eb73ea97ed2f691830551fb9af471e491ab, is a merge of origin/main into this branch
(9671ece + merge commit) with no new commit of this PR's own.

I compared this PR's actual content — git diff origin/main...HEAD, which matches the 32-file,
+1599/-4 change set in the PR description exactly — against what was already reviewed at da355fe:

• git diff da355fe HEAD -- plugins/architecture/scripts/build-view.mjs plugins/architecture/lib/view-builder.mjs plugins/architecture/lib/view-runtime.js plugins/architecture/lib/html-escape.mjs plugins/architecture/scripts/build-view.test.sh plugins/architecture/templates/map-view.html plugins/architecture/reference/rendered-view.md
  is empty — byte-identical to the already-reviewed state, including the closureFrom fix for the
  Codex-flagged P2 finding.
• The files that do show a diff against origin/main...HEAD are all non-functional and all
  caused by main having moved under this branch, not by new work in this PR:
  • docs/conventions/rendered-views/CHANGELOG.md, README.md, plugins/architecture/CHANGELOG.md:
    this PR's own entries, now interleaved with unrelated entries main picked up in between
    (debugging:debug/discovery:blindspot views, an unrelated 0.20.1 architecture release).
  • plugins/architecture/.claude-plugin/plugin.json: version 0.20.1 → 0.21.0 — a mechanical
    cascade because main's own unrelated bump moved the base version out from under this PR's
    +1 bump; the PR's own version delta is unchanged.
  • scripts/cross-plugin-source-registry.txt, scripts/shared-copies.txt: registry-line
    insertions only (adding architecture to the list of plugins carrying the shared copies),
    same content as already reviewed, just context-shifted by other plugins' unrelated entries
    landing nearby.
  • plugins/architecture/README.md: the same "## Interactive views" doc section already
    reviewed, unmoved.

No data-flow, escaping, CSP, temp-file-handling, or input-validation code changed in this window.
The full-scope review (through 8c5871d) and the two incremental reviews since (mode-bits/spelling
through f923391, and the closureFrom project-edge fix through da355fe) all remain valid at
this head — nothing in their reviewed content moved.

Per this lane's scope, GitHub Actions hardening is deferred to zizmor and not re-reviewed here —
no workflow files are touched by this PR.
· branch feat/5863-map-interactive-views