Add cache-header audit design spec for ts dev audit headers

[vasujain00]

Technical spec for epic #834: origin cache-header audit with per-content-type cacheability diagnostics. Covers content-type taxonomy, cacheability rules for all five directives (Cache-Control, Surrogate-Control, Surrogate-Key, Vary, ETag), per-type verdict rollup, CLI integration into the ts dev group, and a 7-task implementation breakdown.

Closes #835

Summary

Changes

File	Change

Closes

Closes #

Test plan

• cargo test-fastly && cargo test-axum
• cargo clippy-fastly && cargo clippy-axum
• cargo fmt --all -- --check
• JS tests: cd crates/trusted-server-js/lib && npx vitest run
• JS format: cd crates/trusted-server-js/lib && npm run format
• Docs format: cd docs && npm run format
• WASM build: cargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1
• Manual testing via fastly compute serve
• Other:

Checklist

• Changes follow CLAUDE.md conventions
• No unwrap() in production code — use expect("should ...")
• Uses tracing macros (not println!)
• New code has tests
• 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.