[vasujain00]

Summary

• Technical spec for epic Origin cache-header audit: per-content-type cacheability diagnostics for publisher origins #834: ts origin audit-headers, a CLI command that audits publisher-origin cache headers and returns per-URL and per-content-type pass/warn/fail verdicts naming the responsible header and the value to set.
• Revision 3 rebases the design on current main (Implement configurable cache header policies #860 cache-header policies, Split origin shareability from template eligibility, and add the readthrough evidence gate #1169 ts origin probe-shareability and origin readthrough, the ESI template cache) and addresses the review rounds from 2026-08-14, 2026-09-24, and 2026-10-01.
• HTML shareability stays with ts origin probe-shareability; this command covers what the probe doesn't: subresources, effective browser and shared-cache policy, TS overrides, redirects, and error responses.

Changes

File	Change
docs/superpowers/specs/2026-07-14-cache-header-audit-design.md	Design spec: command surface and exit codes, per-URL response model, effective browser and shared-cache policy with TS overrides, discovery and origin routing, rules, output contract, CLI integration, tasks

Closes

Closes #835

Test plan

• Docs format: cd docs && npm run format (prettier 3.8.1, the lockfile version, on the spec)
• Other: compiled the §9.1 OriginCommand shape against the workspace's clap 4.6.1
• Other: checked each cited API (asset_route_for_path, origin_host_header, asset_cache_policy_for_path, enforce_set_cookie_cache_privacy, match_slots, tls::install_crypto_provider, the template-cache gate) against main

Checklist

• Changes follow CLAUDE.md conventions
• No secrets or credentials committed

[aram356]

Summary

The spec is a solid starting shape for ts dev audit headers (clear taxonomy, verdict rollup, task breakdown), but several load-bearing claims about the codebase are stale or incorrect — ts dev is already a subcommand tree, there is no CliError enum, reqwest is not a CLI dependency, and the discovery section probes edge-only /_ts/ routes against the publisher origin. Two cacheability rules also fail the strictest correct configuration, and the doc itself is what's breaking the format-docs CI check.

Details are in the inline comments (8 blocking 🔧, 5 🤔, 1 ♻️, 2 🌱, 2 ⛏). Cross-cutting items below.

Blocking

🔧 wrench

• format-docs CI failure: prettier rejects this file's tables — cd docs && npm run format:write (line 30)
• Dependency graph must be mermaid: docs use vitepress-plugin-mermaid; ASCII art won't render (line 391)
• Stale ts dev premise: DevCommand subcommand tree already exists on main; no Serve to default to (lines 254, 289)
• CliError doesn't exist: CLI errors are CliResult<T> = Result<T, String> (line 271)
• reqwest is not a CLI dep + target scoping unaddressed: workspace default target is wasm32-wasip1; spec must say where deps are scoped and that audit is cross-platform, unlike the macOS-only proxy (line 323)
• Discovery probes edge routes against origin: /_ts/* paths 404 on publisher.origin_url (line 131)
• Wrong issue link: #293 text links to /issues/834 (line 7)
• HTML/RTB rules fail no-store alone: RFC 9111's strongest posture would FAIL the audit (lines 75, 106)

Non-blocking

📌 out of scope

• Plan document and epic breakdown still pending: issue #835 asks for a spec and a plan under docs/superpowers/plans/ plus a task breakdown in epic #834; this PR delivers the spec only (Section 10 is a partial plan). Also, the PR body retains the unfilled template (empty Summary/Changes tables, dangling Closes #).

CI Status

• format-docs: FAIL (caused by this file)
• All other checks (fmt, clippy targets, Rust/JS tests, integration, parity, CodeQL): PASS

[aram356]

@vasujain00 Thank you for addressing Please implement it per spec. You can use this pr for the implementation as well.

[aram356]

Summary

The round-1 blockers on the mermaid graph, the DevCommand premise, CliResult, bare no-store, and the #293 link are resolved. Since that round, main has changed under the spec: TS now sets HTML cache privacy itself, has an opt-in template cache and operator asset rules, and documents the CLI's exit codes and --json conventions. Several rules now contradict shipped behavior, and three design gaps (redirects, edge-vs-browser policy, per-URL results) would have the tool grade responses TS never serves. Most of the fixes land in §4, §5 and §7.2.

9 of the inline comments below carry a one-click GitHub suggestion. Use Commit suggestion (or Add suggestion to batch for several at once) to apply them as commits on the PR branch. The remaining comments describe the fix in prose because it spans several sections of the spec.

Blocking

🔧 wrench

• HTML rule fails correct configs and disables the template cache: see inline at 2026-07-14-cache-header-audit-design.md:77-80
• Rules grade Cache-Control as the edge policy (Surrogate-Control, CDN-Cache-Control, Age, Expires ignored): see inline at 2026-07-14-cache-header-audit-design.md:71
• immutable recommended for unfingerprinted JS/CSS/fonts: see inline at 2026-07-14-cache-header-audit-design.md:86
• Exit code 2 collides with the CLI's tool-failure code: see inline at 2026-07-14-cache-header-audit-design.md:40-48
• Audit requests don't match what TS sends to origin: see inline at 2026-07-14-cache-header-audit-design.md:142-143
• Following redirects grades a different response than TS receives: see inline at 2026-07-14-cache-header-audit-design.md:457
• No per-URL record: verdicts can't name the URL; errors and status codes unmodeled: see inline at 2026-07-14-cache-header-audit-design.md:228-243
• Set-Cookie isn't audited, and it overrides every other cache header: see inline at 2026-07-14-cache-header-audit-design.md:67
• RTB bullet still routes discovery to an edge-only route: see inline at 2026-07-14-cache-header-audit-design.md:141-145
• §4.6 still conflates request-side If-None-Match (#428); Last-Modified missing: see inline at 2026-07-14-cache-header-audit-design.md:117-122
• §8.3's reqwest = { workspace = true } makes ts dev proxy panic: see inline at 2026-07-14-cache-header-audit-design.md:296

Non-blocking

• 🤔 All application/json graded as RTB: see inline at 2026-07-14-cache-header-audit-design.md:62
• 🤔 Placement: ts audit is now the audit group: see inline at 2026-07-14-cache-header-audit-design.md:314
• ♻️ Reuse AppConfigArgs instead of a new --config: see inline at 2026-07-14-cache-header-audit-design.md:38
• 🤔 Bare no-store: citation doesn't say "sufficient"; advise adding private: see inline at 2026-07-14-cache-header-audit-design.md:115
• 🤔 Missing Surrogate-Key WARNs every non-Fastly deployment; message is inaccurate: see inline at 2026-07-14-cache-header-audit-design.md:88
• 🤔 Discovery can't reach parts of the taxonomy: see inline at 2026-07-14-cache-header-audit-design.md:138-140
• 🤔 Fetcher has no host allowlist, limits, or output escaping: see inline at 2026-07-14-cache-header-audit-design.md:363
• ⛏ §8.1 snippet needs #[command(subcommand)]: see inline at 2026-07-14-cache-header-audit-design.md:277-278
• ⛏ Cross-platform rationale misstates the dependency facts: see inline at 2026-07-14-cache-header-audit-design.md:288
• ⛏ s-maxage is a directive, not a header: see inline at 2026-07-14-cache-header-audit-design.md:69
• ⛏ Real domain in examples (human output): see inline at 2026-07-14-cache-header-audit-design.md:156
• ⛏ Real domain in examples (JSON): see inline at 2026-07-14-cache-header-audit-design.md:175-179
• ⛏ Task wiring details (args location, cfg cleanup, output writer): see inline at 2026-07-14-cache-header-audit-design.md:215
• 🌱 Test fixture reuse, acceptance cases, docs sidebar: see inline at 2026-07-14-cache-header-audit-design.md:412

Cross-cutting / body-level findings

• 📝 PR description is still the unfilled template: the Summary and Changes table are empty, and there's a dangling Closes # below the real Closes #835. Worth filling in, especially if this PR will also carry the implementation.

CI Status

• Analyze (actions): PASS
• Analyze (javascript-typescript): PASS
• Analyze (rust): PASS
• browser integration tests: PASS
• cargo check (cloudflare native + wasm32-unknown-unknown): PASS
• cargo check/build/test (spin native + wasm32-wasip1): PASS
• cargo fmt: PASS (required)
• cargo test: PASS (required)
• cargo test (axum native): PASS
• cargo test (cross-adapter parity): PASS
• cargo test (ts CLI, native): PASS
• CLAUDE.md symlink guard: PASS
• CodeQL: PASS
• format-docs: PASS (required)
• format-typescript: PASS (required)
• integration tests: PASS
• integration tests (Fastly EC lifecycle): PASS
• prepare integration artifacts: PASS
• vitest: PASS

[prk-Jr]

Summary

The design document is unchanged since the September 24 review. Material specification issues remain in asset caching recommendations, HTML policy, effective cacheability, origin routing, dependency features, exit statuses, and result attribution. These need correction before this specification guides implementation.

This review contains seven blocking findings and one non-blocking documentation correction, all expressed as prose comments.

Blocking

• Avoid enabling a second rustls crypto provider — see inline at docs/superpowers/specs/2026-07-14-cache-header-audit-design.md:301
• Gate immutable caching on verified versioned URLs — see inline at docs/superpowers/specs/2026-07-14-cache-header-audit-design.md:86
• Separate HTML privacy from origin-template eligibility — see inline at docs/superpowers/specs/2026-07-14-cache-header-audit-design.md:77
• Evaluate effective browser and shared-cache policies — see inline at docs/superpowers/specs/2026-07-14-cache-header-audit-design.md:71
• Preserve configured origin routing and Host overrides — see inline at docs/superpowers/specs/2026-07-14-cache-header-audit-design.md:142
• Reserve a distinct exit status for incomplete audits — see inline at docs/superpowers/specs/2026-07-14-cache-header-audit-design.md:48
• Keep verdicts associated with individual sampled URLs — see inline at docs/superpowers/specs/2026-07-14-cache-header-audit-design.md:228

Non-blocking

• Mark the nested clap subcommand — see inline at docs/superpowers/specs/2026-07-14-cache-header-audit-design.md:278

Validation

• All 19 reported GitHub checks pass.
• The changed document passes local Prettier checking.
• Isolated dependency-feature and rustls builder reproductions confirm the crypto-provider conflict; the single-provider reproduction succeeds.
• The corrected nested clap derive compiles.
• The full runtime suite was not rerun locally for this documentation-only PR.

CI Status

• Analyze (actions): PASS
• Analyze (javascript-typescript): PASS
• Analyze (rust): PASS
• browser integration tests: PASS
• cargo check (cloudflare native + wasm32-unknown-unknown): PASS
• cargo check/build/test (spin native + wasm32-wasip1): PASS
• cargo fmt: PASS (required)
• cargo test: PASS (required)
• cargo test (axum native): PASS
• cargo test (cross-adapter parity): PASS
• cargo test (ts CLI, native): PASS
• CLAUDE.md symlink guard: PASS
• CodeQL: PASS
• format-docs: PASS (required)
• format-typescript: PASS (required)
• integration tests: PASS
• integration tests (Fastly EC lifecycle): PASS
• prepare integration artifacts: PASS
• vitest: PASS

Merging since implementation started

[aram356]

Merge