feat: Week 8 — capability reporting, renderer introspection, contract locks, and bundle validation (#12)

* docs: add Week 8 plan and sync roadmap

Add a matching Week 8 planning doc after auditing the design set and
repository state.

- add design/20260319_agent-terminal-v1/16-week-8-plan.md
- update the top-level design entrypoint to point to Week 8
- refresh WEEK2-GAPS.md so the recommended next step matches the new plan

---
_Generated with [`mux`](https://github.com/coder/mux) • Model: `openai:gpt-5.4` • Thinking: `xhigh`_

* feat: add week 8 capability scaffold

* feat: report runtime capabilities

* feat: add inspect renderer runtime summary

* feat: validate proof bundles

* test: lock week 8 golden envelopes

* docs: add week 8 capability-inventory proof bundle

* docs: add week 8 contract-locks proof bundle

* docs: add week 8 bundle-validation proof bundle

* docs: add week 8 inspect-runtime proof bundle

* docs: mark week 8 complete in design docs

* style: format week 8 files with prettier

* fix: degrade version json capability discovery failures

* fix: harden inspect renderer runtime derivation

* fix: improve capability discovery diagnostics

* fix: guard validate-bundle JSON reads

* style: format inspect test

Author: ThomasK33

WEEK2-GAPS.md

@@ -54,11 +54,12 @@ Week 1 control-plane work, Week 2 renderer-backed inspection, Week 3 export / re
 
 ## Recommended next step
 
-The next milestone can now treat the contract/doc ratification work as closed and focus on the intentionally deferred roadmap:
+The next planned milestone is Week 8. It should treat the Week 1–7 contract/doc ratification work as closed and first close the remaining runtime-capability/reporting discipline gaps before moving further down the broader deferred roadmap:
 
-1. native renderers and broader platform parity,
-2. mouse input and richer live renderer state,
-3. remote/network sessions and an MCP wrapper,
-4. and larger model/data redesigns such as dynamic renderer-capability discovery, fuller failure taxonomy, event-log redesign, snapshot-schema expansion, and renderer CSP hardening.
+1. runtime renderer capability discovery plus richer live renderer state/reporting,
+2. the remaining lower-priority public-envelope locks and proof-bundle validation,
+3. native renderers and broader platform parity,
+4. mouse input, remote/network sessions, and an MCP wrapper,
+5. and larger model/data redesigns such as fuller failure taxonomy, event-log redesign, snapshot-schema expansion, and renderer CSP hardening.
 
-See `design/20260319_agent-terminal-v1/15-week-7-plan.md` for the current Week 7 proof-bundle status and the design docs under `design/20260319_agent-terminal-v1/` for the broader roadmap context.
+See `design/20260319_agent-terminal-v1/16-week-8-plan.md` for the current next-step plan, `design/20260319_agent-terminal-v1/15-week-7-plan.md` for the completed Week 7 ratification context, and the design docs under `design/20260319_agent-terminal-v1/` for the broader roadmap context.

design/20260319_agent-terminal-v1.md

@@ -38,7 +38,7 @@ The repository now ships the first three milestones of this design plus Weeks 4
 - macOS CI validation,
 - and proof bundles under `dogfood/`.
 
-Week 7 is the current design-synchronization milestone. The high-value CLI examples now match shipped behavior, the `send-keys` / `destroy` result-shape alignment has landed, and the main remaining Week 7 work is proof-bundle completeness/reviewability. The intentionally deferred platform/runtime work is tracked separately in [`../WEEK2-GAPS.md`](../WEEK2-GAPS.md). See [14-week-6-status.md](./20260319_agent-terminal-v1/14-week-6-status.md), [15-week-7-plan.md](./20260319_agent-terminal-v1/15-week-7-plan.md), and [`../WEEK2-GAPS.md`](../WEEK2-GAPS.md) for the current state.
+Week 7 closed the design-synchronization pass for the shipped v1 surface. The next planned milestone is Week 8, which focuses on runtime capability discovery, richer renderer/session introspection, the remaining lower-priority public-envelope locks, and proof-bundle normalization/validation before broader native-renderer/platform expansion. The intentionally deferred platform/runtime work is tracked separately in [`../WEEK2-GAPS.md`](../WEEK2-GAPS.md). See [14-week-6-status.md](./20260319_agent-terminal-v1/14-week-6-status.md), [15-week-7-plan.md](./20260319_agent-terminal-v1/15-week-7-plan.md), [16-week-8-plan.md](./20260319_agent-terminal-v1/16-week-8-plan.md), and [`../WEEK2-GAPS.md`](../WEEK2-GAPS.md) for the current state.
 
 ## Executive summary
 
@@ -210,6 +210,7 @@ This design file is the entry point. Detailed supporting docs live in `design/20
 - [13-week-6-plan.md](./20260319_agent-terminal-v1/13-week-6-plan.md)
 - [14-week-6-status.md](./20260319_agent-terminal-v1/14-week-6-status.md)
 - [15-week-7-plan.md](./20260319_agent-terminal-v1/15-week-7-plan.md)
+- [16-week-8-plan.md](./20260319_agent-terminal-v1/16-week-8-plan.md)
 
 ## High-level architecture
 

design/20260319_agent-terminal-v1/05-dogfooding-and-validation.md

@@ -8,7 +8,7 @@ A follow-up AI coding agent should treat this file as the minimum review protoco
 
 ## Current shipped state (2026-03-25)
 
-This document still describes the broader dogfooding target, but the repository now ships the full core artifact set needed for review bundles plus a local review helper for browsing them.
+This document still describes the broader dogfooding target, but the repository now ships the full core artifact set needed for review bundles plus local review and validation helpers for checking them.
 
 Shipped today:
 
@@ -20,9 +20,10 @@ Shipped today:
 - artifact manifests,
 - notes / proof bundles under `dogfood/`,
 - static bundle review pages generated by `npm run review-bundle -- <bundle-dir>`,
+- local bundle validation available via `npm run validate-bundle -- <bundle-dir>`,
 - and dedicated Week 6 review pages checked in under `dogfood/20260325-week6-*/index.html`.
 
-The remaining validation gap is no longer missing artifact classes or a missing local review page. It is now **bundle completeness and normalization**: some Week 4–6 bundles still rely mainly on JSON/log outputs or omit committed screenshots, recordings, videos, or generated review pages even though this document's preferred proof format expects them.
+The remaining validation gap is no longer missing artifact classes, a local review page, or a repo-supported minimum checker for new bundles. The remaining debt is now mostly consistency across older bundles: some Week 4–6 bundles predate the new validation profiles and still rely mainly on JSON/log outputs or omit committed screenshots, recordings, videos, or generated review pages even though this document's preferred proof format expects them.
 
 Read the remainder of this file as the broader validation target and checklist for keeping future bundles equally concrete, reproducible, and reviewable.
 
@@ -131,6 +132,63 @@ Those bundles are useful, but they also make the remaining validation debt expli
 
 So the remaining dogfood gap is now consistency rather than capability: the repo has the tooling and artifact types, but not every high-value checked-in bundle yet meets the document's strongest preferred review format.
 
+## Week 8 coverage
+
+As of 2026-03-25, Week 8 closes the explicit bundle-completeness enforcement gap for the targeted bundle classes by adding `src/tools/validate-bundle.ts` and standardizing four dedicated Week 8 proof-bundle paths:
+
+- `dogfood/20260325-week8-capability-inventory/`,
+- `dogfood/20260325-week8-contract-locks/`,
+- `dogfood/20260325-week8-bundle-validation/`,
+- and `dogfood/20260325-week8-inspect-runtime/`.
+
+### Validate-bundle tool
+
+Week 8 adds a standalone validation helper at `src/tools/validate-bundle.ts`.
+
+Run it with either the default profile or an explicit interactive profile:
+
+```sh
+npm run validate-bundle -- <bundle-dir>
+npm run validate-bundle -- <bundle-dir> --profile interactive-renderer
+```
+
+The default profile is `contract-reporting`. `interactive-renderer` extends that minimum for bundles that prove rendered terminal output rather than only CLI/reporting contracts.
+
+`validate-bundle` currently enforces these exact checks:
+
+- `contract-reporting` requires a readable bundle directory, at least one JSON output file, a notes markdown file (`notes.md`, `NOTES.md`, `README.md`, or `index.md`), a generated `index.html` review page, and successfully parsed JSON for every detected JSON output file.
+- `interactive-renderer` requires every `contract-reporting` check plus at least one screenshot (`.png`) and at least one recording (`.cast`) artifact.
+
+`validate-bundle` uses the same artifact classification as `review-bundle`: `manifest.json` does not count as a JSON output file, and files under `logs/` are treated as support files rather than contract JSON outputs.
+
+### Minimum bundle contents by profile
+
+| Requirement | `contract-reporting` | `interactive-renderer` |
+| --- | --- | --- |
+| Readable bundle directory | Required | Required |
+| JSON output files | At least 1 | At least 1 |
+| Notes markdown file | Required | Required |
+| Generated review page (`index.html`) | Required | Required |
+| All detected JSON output files parse successfully | Required | Required |
+| Screenshot artifact (`.png`) | Not required | At least 1 |
+| Recording artifact (`.cast`) | Not required | At least 1 |
+| Replay video (`.webm`) | Recommended when helpful, not validator-required | Recommended when helpful, not validator-required |
+
+### Profile selection guidance
+
+Use `contract-reporting` for bundles that only capture CLI JSON output and reviewer notes, such as:
+
+- `dogfood/20260325-week8-capability-inventory/`,
+- `dogfood/20260325-week8-contract-locks/`,
+- and `dogfood/20260325-week8-bundle-validation/`.
+
+Use `interactive-renderer` for bundles that capture rendered terminal output, such as:
+
+- `dogfood/20260325-week8-inspect-runtime/`,
+- and the checked-in cli-parity example `dogfood/20260322-week4-cli-parity/`.
+
+Run `review-bundle` before or alongside `validate-bundle` so the required `index.html` page is present when the validator checks the bundle.
+
 ## 1. Dogfooding goals
 
 Dogfooding must prove that an agent can:
@@ -145,15 +203,15 @@ Dogfooding must prove that an agent can:
 
 ## 2. Required proof artifacts
 
-Every serious dogfood run must produce:
+Every serious dogfood run must satisfy the profile minimum documented in [Week 8 coverage](#week-8-coverage). For interactive renderer scenarios, the stronger default expectation remains:
 
 - at least one semantic snapshot JSON,
 - at least one PNG screenshot,
 - at least one video recording,
 - at least one recording export (`.cast`),
 - and a short human-readable notes file.
 
-If any of these are missing, the run is incomplete.
+If any profile-required artifacts are missing, or if an interactive renderer run omits the stronger artifacts above, the run is incomplete.
 
 ## 3. Recommended artifact bundle layout