jscraik · jscraik · May 7, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026
diff --git a/.codex/environments/environment.toml b/.codex/environments/environment.toml
diff --git a/FORJAMIE.md b/FORJAMIE.md
@@ -16,15 +16,15 @@
 ## Status
 
 <!-- STATUS_START -->
-**Last updated:** 2026-05-05
+**Last updated:** 2026-05-07
 **Production status:** IN_PROGRESS overall; Agent Design Prepare north-star plan is REVIEW_GREEN
 **Overall health:** Yellow overall; Green for the Agent Design Prepare plan lane
 
 | Area | Status | Notes |
 | --- | --- | --- |
 | Build / CI | Yellow | Focused policy, token, matrix, docs, guidance, whitespace, browser, widget a11y, and aggregate build gates pass for the Agent Design Engine slice |
 | Tests | Yellow | Agent-design and release-readiness gates pass (`agent-design-engine`, `cli`, `design-system-guidance`, web E2E, widget a11y, and root build), including fixture-backed CLI JSON/recovery/migration coverage |
-| Agent Design Prepare plan | Merged into the current simplification lane | The prepare contract and changed-surface evidence gate are now the foundation for PR #161's agent-first simplification and review-thread fixes |
+| Agent Design Prepare plan | Merged into the current simplification lane | The prepare contract and changed-surface evidence gate now include P6 route parity plus P7 stop classification and recovery hints for blocked surfaces |
 | Security | Clean | 13 CVEs patched; GitHub Actions SHA-pinned |
 | Open PRs | 1 | PR #161 carries the agent-first simplification slice and current review-thread fixes |
 | Blockers | None | |
@@ -77,10 +77,10 @@ flowchart LR
 - `docs/` holds architecture, adoption, rollout, and governance guidance.
 - `docs/specs/2026-04-28-agent-native-design-system-spec.md` is the deepened HE spec for turning the current agent-readable design-system contract into an agent-native preparation, routing, context-pack, remediation, example, and abstraction-proposal workflow.
 - `docs/specs/2026-04-30-agent-design-prepare-north-star-spec.md` is the focused north-star spec that makes `astudio design prepare --surface <path> --json` the required pre-edit UI contract for agents, including semantic token guidance, deterministic error codes, schema hardening, safe validation commands, source evidence, proposal-required stops, interface alternatives, token source priority, and first-plan sequencing.
-- `docs/specs/2026-05-02-agent-first-design-system-simplification-spec.md` provides the HE simplification spec for keeping the agent-design spine intact while reducing repo bulk, clarifying active authority, adding agent-ergonomic prepare affordances, resolving prototype/package taxonomy, and splitting large implementation files by responsibility.
+- `docs/specs/2026-05-02-agent-first-design-system-simplification-spec.md` provides the HE simplification spec for keeping the agent-design spine intact while reducing repo bulk, clarifying active authority, adding agent-ergonomic prepare affordances, resolving prototype/package taxonomy, splitting large implementation files by responsibility, closing route-coverage parity gaps, promoting gold-example guidance, classifying productive stop/recovery behavior for agents, and recording session-evidence metadata when telemetry shapes spec requirements.
 - `docs/plans/2026-04-28-agent-native-design-system-plan.md` is the execution plan for that spec, split into contract wiring, routing-table, prepare-payload, CLI, remediation, gold-example, and proposal-gate slices.
 - `docs/plans/2026-04-30-agent-design-prepare-north-star-plan.md` is the focused execution plan for making `prepare` the real north-star command: first prove the build-backed wrapper dependency chain and read-only distinction, then harden the prepare schema and fixture harness, add semantic token-contract loading, complete the payload, map deterministic errors, flip the docs front door, and keep human inspector/gold-example expansion deferred until they have evidence.
-- `docs/plans/2026-05-02-agent-first-design-system-simplification-plan.md` remains the active HE delivery plan for the simplification spec. It starts with authority mapping and reference audits, then sequences prepare ergonomics, derived brief/PR-evidence formats, responsibility splits, package taxonomy, root script simplification, and `FORJAMIE.md` compression.
+- `docs/plans/2026-05-02-agent-first-design-system-simplification-plan.md` remains the active HE delivery plan for the simplification spec. P0-P9 are recorded in its execution ledger; no newer simplification-specific Linear acceptance map has replaced it yet.
 - `docs/design-system/GOLD_EXAMPLES.json` is the machine-readable gold-example inventory for promoted agent examples, state coverage, validation commands, and explicitly deferred non-promotable categories.
 - `docs/design-system/proposals/` is the proposal-gate surface for new agent UI abstractions. It holds the proposal template, typed waiver registry, and docs for when enforced routes or uncovered canonical lifecycle promotions need accepted design evidence.
 - `docs/architecture/COMMAND_SURFACE.md` is the current command-routing map. It keeps canonical agent-design, repo health, product-surface, specialist, and compatibility commands in one place so README, workflow docs, and this handoff do not grow competing script inventories.
@@ -176,7 +176,7 @@ See also: `~/.codex/instructions/Learnings.md`
 - `DESIGN.md` section line numbers must stay anchored to the original file, including YAML frontmatter. Lint findings use those lines as agent remediation evidence.
 - `astudio design init` validates the starter contract before writing, but it must still enforce the write gate first so a missing `--write` remains a policy error instead of a provenance error.
 - Package-level Biome scripts need to use the same pinned Biome 2.x command as the root scripts. The workspace still contains older Biome 1.x dependencies for other packages, and those cannot parse the current `biome.json` schema.
-- Browser-backed Playwright gates need a provisioned Chromium cache and a macOS launch path that is not blocked by the Codex sandbox. If every browser test fails at launch with `bootstrap_check_in ... Permission denied (1100)`, treat it as an environment permission issue and rerun the browser gate through the approved unsandboxed path before debugging UI code.
+- `make hooks-pre-push` must stay browser-free for sandboxed Codex pushes: it runs docs/environment/Semgrep/codestyle plus `pnpm build -- --skip-tests`. Browser-backed Playwright gates still need a provisioned Chromium cache and a macOS launch path that is not blocked by the Codex sandbox; if every explicit browser test fails at launch with `bootstrap_check_in ... Permission denied (1100)`, treat it as an environment permission issue before debugging UI code.
 - Package manifests can point at `dist` in `main`, `types`, `exports`, `bin`, or `files`, but those generated outputs are no longer committed source. Build before pack, publish, or direct `node packages/*/dist/...` execution.
 - `pnpm generated-source:check` is the canonical freshness gate for tracked generated runtime inputs. It regenerates the web template registry, widget JavaScript manifest, and Cloudflare worker manifest, formats the tracked generated source with Biome 2.3.11, and fails if the committed snapshot is stale.
 - `packages/widgets/src/sdk/generated/widget-manifest.ts` is still an ignored mutable local mirror. The tracked runtime authority is `packages/widgets/src/sdk/generated/widget-manifest.js`, and Cloudflare consumes its own deterministic `src/worker/widget-manifest.generated.ts` mirror after `pnpm -C packages/cloudflare-template run prebuild`.
@@ -215,6 +215,19 @@ See also: `~/.codex/instructions/Learnings.md`
 
 ## Recent changes
 
+### 2026-05-07
+
+- **Sandbox-safe pre-push hook**: changed `make hooks-pre-push` to run the aggregate build with `pnpm build -- --skip-tests`, and taught `scripts/check-environment.sh` to fail if that browser-free push contract drifts. Push governance still runs docs links, diagram freshness, environment checks, changed-file Semgrep, codestyle, and package builds, while Playwright/Chromium gates remain explicit validation or CI work instead of launching from the git hook inside the Codex sandbox.
+- **Agent-first simplification P9 session evidence traceability**: ran `~/.agents/session-collector` for a 30-day window and kept a compact durable summary at `reports/session-evidence-agent-first-simplification-2026-05-07.json` instead of committing the bulky raw collector bundle. The spec and plan now require future session-derived requirements to cite aggregate collector metadata, classify requirement impact as changed/confirmed/reprioritized, and record confidence, redaction, parse-warning, source-count, blocker-category, and artifact-disposition fields without raw transcript dependence.
+- **Agent-first simplification P8 downstream command contract**: README, the agent workflow guide, command-surface docs, and the simplification spec now present the downstream product story as a small `astudio design` command family: `init`, `prepare --surface <path> --json`, proposed `check --changed --json`, and `propose-abstraction --need "<need>" --surface <path> --json`. The docs keep `prepare` as the dominant machine contract, mark local `pnpm agent-design:*` commands as monorepo wrappers, and describe brief/PR-evidence as derived handoff views rather than replacement contracts.
+- **Agent-first simplification P7 stop classification**: blocked `astudio.design.prepare.v1` payloads now carry schema-backed `nextAction.category`, top-level `stopClassification`, and recovery hints for design, route, proposal, validation, and concrete environment categories. The brief and PR-evidence renderers show the same classification as JSON, and the changed-surface gate preserves per-surface blocked detail so agents can keep branching on `safeForAutomaticImplementation` while also knowing why a stop happened. Focused validation passed with `pnpm agent-design:test` and `pnpm -C packages/cli test`; sandboxed Playwright browser gates still require non-sandbox execution because Chromium cannot register its macOS Mach rendezvous port inside the sandbox.
+- **Agent-first simplification P6 route parity**: added the enforced `icon_action` route for protected `IconButton` surfaces, promoted the IconButton story as a gold example, registered IconButton in lifecycle metadata, and added a typed grandfathering waiver until proposal backfill is complete. `astudio design prepare` now emits actionable missing-route recovery diagnostics with candidate files and closest routes, and `packages/agent-design-engine` exposes a route-parity report so protected guidance scopes can be compared with route coverage. Focused validation passed with `pnpm agent-design:test`, `pnpm -C packages/cli test`, `pnpm -C packages/design-system-guidance check:ci`, `pnpm docs:lint`, JSON `jq` validation, and `git diff --check`.
+- **Agent-first simplification plan follow-on sync**: refreshed `docs/plans/2026-05-02-agent-first-design-system-simplification-plan.md` against the deepened spec so the completed P0-P5 ledger remains intact while new P6-P9 follow-on phases carry route coverage parity, missing-route recovery, gold-example promotion, stop classification, downstream command-contract positioning, and session-evidence traceability. P7 is now complete; the next work packet starts with P8 downstream command-contract wording.
+
+### 2026-05-06
+
+- **Agent-first simplification spec deepening and technical review**: deepened `docs/specs/2026-05-02-agent-first-design-system-simplification-spec.md` from the `he-deepen-spec` targeted-confidence lane and reviewed it with the `he-technical-review` document-review lens. The spec now records the session-collector evidence baseline, route-coverage parity and gold-example maturity requirements, productive missing-route recovery, operational stop taxonomy, correct owner boundaries between `prepare`, changed-surface aggregation, and validation/diagnostic runners, schema-backed payload compatibility guardrails, and new acceptance coverage through SA36. The review corrected over-broad environment-stop ownership before closeout and left the current implementation plan needing a follow-up sync to absorb the new SA23-SA36 acceptance details.
+
 ### 2026-05-05
 
 - **Framer Motion widget manifest refresh**: refreshed the tracked widget runtime manifests on the Dependabot `framer-motion` update branch after installing from the branch lockfile. The dependency update changes the built `pizzaz-shop` and `solar-system` widget bundle hashes, so `packages/widgets/src/sdk/generated/widget-manifest.js` and `packages/cloudflare-template/src/worker/widget-manifest.generated.ts` now match the generated-source freshness gate used by CI.

diff --git a/Makefile b/Makefile
@@ -61,7 +61,7 @@ hooks-pre-push: ## Run local pre-push governance gates before pushing
 	@bash ./scripts/check-environment.sh
 	$(MAKE) semgrep-changed
 	$(MAKE) codestyle
-	pnpm build
+	pnpm build -- --skip-tests
 
 secrets-staged: ## Scan staged content for secrets before committing
 	pnpm run secrets:staged
@@ -138,4 +138,4 @@ diagrams: ## Generate architecture diagrams
 # === Environment ===
 
 env-check: ## Check environment policy envelope
-	@bash ./scripts/check-environment.sh
+	@bash ./scripts/check-environment.sh
diff --git a/README.md b/README.md
@@ -115,13 +115,22 @@ Task-first routes:
 
 ## Agent UI Preparation
 
-Before an AI coding agent edits a protected UI surface, run the design prepare command:
+This repo's strongest agent-facing product surface is the pre-edit UI contract. A downstream project should only need a small `astudio design` command family:
 
 ```bash
+astudio design init
 astudio design prepare --surface <path> --json
+astudio design check --changed --json
+astudio design propose-abstraction --need "<need>" --surface <path> --json
 ```
 
-The detailed workflow authority is [`docs/guides/AGENT_DESIGN_WORKFLOW.md`](docs/guides/AGENT_DESIGN_WORKFLOW.md). Keep this README as the short front door: `prepare` is the implementation brief, and a protected UI change is not ready until `safeForAutomaticImplementation` is `true` or the PR explains the manual/proposal decision returned by `openDecisions`.
+`prepare` is the dominant first-run path. Before an AI coding agent edits a protected UI surface, compile the file-specific implementation brief:
+
+```bash
+astudio design prepare --surface <path> --json
+```
+
+The detailed workflow authority is [`docs/guides/AGENT_DESIGN_WORKFLOW.md`](docs/guides/AGENT_DESIGN_WORKFLOW.md). Keep this README as the short front door: `prepare` is the implementation contract compiler, and a protected UI change is not ready until `safeForAutomaticImplementation` is `true` or the PR explains the manual/proposal decision returned by `openDecisions`.
 
 JSON is the canonical machine contract. For human review or PR handoff after the JSON path is understood, the same typed payload can render derived text:
 
@@ -130,13 +139,13 @@ astudio design prepare --surface <path> --format brief
 astudio design prepare --surface <path> --format pr-evidence
 ```
 
-For local repo work, use the build-backed convenience wrapper in silent mode so stdout remains parseable JSON:
+For local monorepo work, use the build-backed convenience wrapper in silent mode so stdout remains parseable JSON:
 
 ```bash
 pnpm --silent agent-design:prepare --surface <path>
 ```
 
-That wrapper may build local workspace packages before invoking the CLI. The read-only operation contract belongs to `astudio design prepare` itself once the CLI is available. Before PR handoff for protected UI changes, run the changed-surface evidence gate:
+That wrapper may build local workspace packages before invoking the CLI. The read-only operation contract belongs to `astudio design prepare` itself once the CLI is available. Before PR handoff for protected UI changes, run the local changed-surface evidence gate:
 
 ```bash
 pnpm agent-design:prepare:changed
@@ -148,7 +157,7 @@ For a targeted local check, pass one or more explicit surfaces through the gate:
 pnpm agent-design:prepare:changed -- --surface <path>
 ```
 
-Supporting commands such as `astudio design lint`, `export`, `components`, `coverage`, and `propose-abstraction` are diagnostics rather than the normal pre-edit path.
+Supporting commands such as `astudio design lint`, `export`, `components`, and `coverage` are diagnostics rather than the normal pre-edit path. `astudio design propose-abstraction` is the explicit escalation path when `prepare` says the requested UI needs a new abstraction instead of improvisation.
 
 For broader command routing, see [`docs/architecture/COMMAND_SURFACE.md`](docs/architecture/COMMAND_SURFACE.md). That page groups the canonical agent-design, repo health, product-surface, and compatibility commands so this README stays a short front door.