JS Asset Auditor engineering spec

[jevansnyc]

Summary

Engineering spec for the JS Asset Auditor — a Claude Code slash command that sweeps a publisher page via Chrome DevTools MCP, detects third-party JS assets, and generates or diffs js-assets.toml.

Closes#606

Docs added

• docs/superpowers/specs/2026-04-01-js-asset-auditor-design.md — engineering spec covering sweep protocol, Chrome DevTools MCP tooling, heuristic filtering, slug generation, init and diff modes

Test plan

• Review sweep protocol and verify Chrome DevTools MCP tools match what is available
• Verify heuristic filter list covers expected ad tech vs non-ad tech origins
• Confirm slug algorithm matches proxy spec derivation

[prk-Jr]

Summary

Reviewed the engineering spec and left a few implementation-facing questions inline. The main areas are URL normalization, wildcarding, third-party boundary matching, path derivation, and inject_in_head semantics for dynamic scripts.

[aram356]

Summary

Well-structured engineering spec for the JS Asset Auditor. The Auditor/Proxy separation and diff mode design are strong. However, several MCP tool assumptions are incorrect and would cause the skill to fail at implementation time, and the path derivation algorithm contradicts its own examples.

Blocking

🔧 wrench

• MCP tool names are wrong: every mcp__chrome-devtools__* reference uses an incorrect prefix — actual names are mcp__plugin_chrome-devtools-mcp_chrome-devtools__* (line 36+)
• wait_for misuse: tool waits for text on page, not a settle window — need evaluate_script with setTimeout instead (line 37)
• list_network_requests filtering: tool supports resourceTypes filtering, not URL/Content-Type filtering — post-processing needed (line 39)
• Path derivation contradicts examples: algorithm says /{publisher_prefix}/{asset_stem}.js but example shows /sdk/aB3kR7mN.js — these are different structures (line 68 vs 119)

❓ question

• Slug concatenation separator: sha256(publisher.domain + origin_url) doesn't specify a separator — and base62 encoding isn't standardized (character set ordering). Both must be pinned for Auditor/Proxy consistency (line 88)
• Skill location: spec says .claude/skills/audit-js-assets.md but project uses .claude/commands/ for all slash commands — reason for new directory? (line 186)

Non-blocking

🤔 thinking

• Wildcard regex too broad: [A-Za-z0-9]{8,} matches stable path segments like analytics, bootstrap (line 100)
• stale_ttl_sec omitted: Proxy spec defines this field but Auditor doesn't mention it in generated entries (line 70)
• platform.twitter.com: may need updating to platform.x.com post-rebrand (line 58)
• 6s settle window: may miss late-loading ad tech scripts — consider making configurable (line 37)
• MCP permission grants: close_page and wait_for are not pre-approved in .claude/settings.json — will trigger permission prompts
• No error handling specified: DNS failures, ad blockers, browser crashes during sweep — worth documenting expected behavior

🌱 seedling

• docs/superpowers/specs/ is new: existing docs use docs/guide/, docs/internal/, docs/epics/ — convention should be documented
• Wildcard detection asymmetry: only defined in Auditor spec, not cross-referenced in Proxy spec — future tools won't know the patterns

⛏ nitpick

• Relative link to Proxy spec: dead if this PR merges first (line 6, 207)

👍 praise

• Diff mode design: commented-out TOML + never-auto-remove is excellent
• Auditor/Proxy separation: clean architectural boundary with minimal coupling
• Terminal summary: shows filtered-with-reason, slug mapping, wildcard indicators
• inject_in_head DOM detection: sound approach using document.head.querySelectorAll

CI Status

• cargo fmt: PASS
• cargo test: PASS
• vitest: PASS
• format-typescript: PASS
• format-docs: FAIL
• CodeQL: PASS
• integration tests: PASS

[aram356]

Closing in place of #800