[codex] Make prepare the UI edit contract

Resolve the agent-design prepare north-star contract work into main after rebasing the PR branch through main and clearing GitHub checks.

Validation:
- gh pr checks 159 --repo jscraik/Design-System --watch --interval 10 -> pass
- pnpm -C packages/agent-design-engine test -> pass
- pnpm -C packages/cli test -> pass
- AGENT_DESIGN_PREPARE_BASE=origin/main pnpm --silent agent-design:prepare:changed -> pass
- pnpm docs:lint -> pass
- pnpm --silent agent-design:lint -> pass
- git diff --check -> pass

Co-authored-by: Codex <noreply@openai.com>

Author: jscraik

.github/PULL_REQUEST_TEMPLATE.md

@@ -11,6 +11,7 @@
 - [ ] I did not push directly to `main`; this PR is from a dedicated branch.
 - [ ] Branch name follows policy (`codex/*` for agent-created branches).
 - [ ] Required local gates run: `bash scripts/validate-codestyle.sh`, `pnpm check`, `test -f memory.json && jq -e '.meta.version == "1.0" and (.preamble.bootstrap | type == "boolean") and (.preamble.search | type == "boolean") and (.entries | type == "array")' memory.json >/dev/null`.
+- [ ] Agent-first UI gate run when UI surfaces changed: `pnpm agent-design:prepare:changed` locally and/or via CI.
 - [ ] CodeRabbit review completed and findings handled (or explicitly waived).
 - [ ] CodeRabbit review was performed by an independent reviewer (not the coding agent).
 - [ ] Codex review completed and findings handled (or explicitly waived).
@@ -26,6 +27,7 @@
 - Command: `bash scripts/validate-codestyle.sh` -> pass/fail
 - Command: `pnpm check` -> pass/fail
 - Command: `test -f memory.json && jq -e '.meta.version == "1.0" and (.preamble.bootstrap | type == "boolean") and (.preamble.search | type == "boolean") and (.entries | type == "array")' memory.json >/dev/null` -> pass/fail
+- Command: `pnpm agent-design:prepare:changed` -> pass/fail/n.a. (required locally or via CI when UI surfaces changed)
 - Any other command(s):
 
 ## Review artifacts

.github/workflows/ci.yml

@@ -76,6 +76,12 @@ jobs:
         id: apps-sdk-change
         run: node scripts/check-apps-sdk-ui-version.mjs
 
+      - name: Agent design prepare evidence (web platform PR only)
+        if: github.event_name == 'pull_request' && matrix.platform == 'web'
+        env:
+          AGENT_DESIGN_PREPARE_BASE: origin/${{ github.base_ref }}
+        run: pnpm agent-design:prepare:changed
+
       - name: Run Apps SDK UI drift tests
         if: steps.apps-sdk-change.outputs.changed == 'true'
         run: pnpm test:drift

FORJAMIE.md

@@ -24,9 +24,9 @@
 | --- | --- | --- |
 | 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 | Review green; merge-blocked pending required checks | Reviewer loop is green after wrapper/read-only classification, JSON-safe wrapper, matrix evidence, machine locators, and resolved-vs-deferred spec decisions were tightened; PR #160 remains under heartbeat monitoring until required checks pass |
+| Agent Design Prepare plan | Review green; merge-blocked pending required checks | Reviewer loop is green after wrapper/read-only classification, JSON-safe wrapper, matrix evidence, machine locators, and resolved-vs-deferred spec decisions were tightened; PR #159 now carries the prepare contract plus changed-surface evidence gate |
 | Security | Clean | 13 CVEs patched; GitHub Actions SHA-pinned |
-| Open PRs | 1 | PR #160 carries the agent-design prepare contract hardening slice |
+| Open PRs | 1 | PR #159 carries the agent-design prepare north-star and changed-surface gate slice |
 | Blockers | None | |
 <!-- STATUS_END -->
 
@@ -212,12 +212,17 @@ See also: `~/.codex/instructions/Learnings.md`
 - `pnpm agent-design:proposals` now blocks silent enforced-route and uncovered lifecycle promotion, but the first waiver registry intentionally grandfathered existing ProductComposition and ChatShell gaps. Those waivers should be replaced by accepted proposal records or per-export coverage before expiry.
 - `@brainwav/design-system-guidance` imports the public `@brainwav/agent-design-engine` package export, whose package types resolve through `dist`. Its build and type-check scripts must build the sibling engine package first, or clean CI installs can fail before the guidance checks run.
 - `pnpm --silent agent-design:prepare --surface <path>` depends on built `packages/agent-design-engine`, `packages/design-system-guidance`, and `packages/skill-ingestion` artifacts because the CLI imports those workspace packages through package exports. Keep it aligned with `pnpm agent-design:lint` by building those packages before building the CLI. The wrapper appends `--json` itself and does not include a default surface; callers provide `--surface` explicitly. The wrapper is build-backed convenience; the read-only contract belongs to the underlying `astudio design prepare` operation once the CLI is available. Use `--silent` whenever an agent or script captures JSON, because plain `pnpm` writes lifecycle banners to stdout.
+- `pnpm agent-design:prepare:changed` is the agent-first PR/local evidence gate. It builds the prepare dependencies, discovers changed `.tsx`/`.jsx` UI surfaces under the protected app/widget trees, runs the read-only CLI prepare operation for each surface, and fails closed when a payload is unsafe, incomplete, unparseable, or points outside the repository. Use `-- --surface <path>` to force a single-surface check. GitHub Actions also runs this gate on pull requests in the web platform lane with `AGENT_DESIGN_PREPARE_BASE` pointed at the PR base ref.
 - `pnpm quality-debt:report` is warn-first by design. Amber/red radar posture is release-owner evidence, not a new hard-fail gate, until explicit thresholds are approved.
 - Quality-debt radar CLI output now includes `service:"quality-debt-radar"` on status/error lines, and flag parsing fails fast when `--output`, `--date`, or `--week` are missing values.
 - The next agent-native design-system hardening lane is specified broadly in `docs/specs/2026-04-28-agent-native-design-system-spec.md` and narrowed by `docs/specs/2026-04-30-agent-design-prepare-north-star-spec.md`. The north-star rule is that no protected UI change is ready until `astudio design prepare --surface <path> --json` returns `safeForAutomaticImplementation: true`, or the PR explains the proposal/manual decision required. The focused execution source for this lane is now `docs/plans/2026-04-30-agent-design-prepare-north-star-plan.md`; use the older `docs/plans/2026-04-28-agent-native-design-system-plan.md` only for broader historical context and adjacent non-prepare slices.
 
 ## Recent changes
 
+### 2026-05-02
+
+- **PR #159 merge conflict resolution**: rebased the changed-surface evidence gate onto the merged Agent Design Prepare hardening from `main`. The branch now keeps the newer prepare parser/schema/token-contract behavior from `main`, while preserving `pnpm agent-design:cli:prebuild`, `pnpm agent-design:prepare:changed`, the web CI evidence step, PR template checklist, README/workflow docs, and CLI tests that prove the gate builds the prepare stack before checking changed protected UI surfaces.
+
 ### 2026-04-30
 
 - **Agent Design Prepare north-star spec**: added `docs/specs/2026-04-30-agent-design-prepare-north-star-spec.md` as the focused HE standard spec for making `astudio design prepare --surface <path> --json` the project front door before AI agents edit UI. The spec keeps the current engine/CLI/guidance package boundaries, requires `designTokenContract` in the prepare payload, adds deterministic design error codes, tightens `astudio.design.prepare.v1` schema expectations, keeps returned validation commands read-only by default, and defers the human Design Prepare Inspector to a companion UI spec before implementation. The spec was then deepened with interface alternatives, selected Shape A (`prepare` in place), token source priority from runtime theme slots and token aliases, additional failure classes, observability fields, and a first-plan sequence. Follow-ups clarified that `pnpm --silent agent-design:prepare --surface <path> --json` is the JSON-safe build-backed wrapper, while `astudio design prepare` is the read-only contract; updated the wrapper to build engine, guidance, and skill-ingestion workspace dependencies before the CLI without baking in a colliding default surface; and moved wrapper reliability/classification to the first recommended planning step so future planning does not defer that gate.

README.md

@@ -128,6 +128,20 @@ 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. Use `pnpm --silent` when a script or agent needs to capture the JSON payload, because plain `pnpm` adds lifecycle banners to stdout. Supporting commands such as `astudio design lint`, `export`, `components`, `coverage`, and `propose-abstraction` are diagnostics rather than the normal pre-edit happy path.
 
+Before PR handoff for protected UI changes, run the changed-surface evidence gate:
+
+```bash
+pnpm agent-design:prepare:changed
+```
+
+For a targeted local check, pass one or more explicit surfaces through the gate:
+
+```bash
+pnpm agent-design:prepare:changed -- --surface <path>
+```
+
+CI runs the changed-surface gate on pull requests in the web platform lane, using the PR base ref as the comparison point. That makes the prepare evidence rule automatic for UI changes while keeping the direct `astudio design prepare` operation read-only.
+
 ## Verify
 
 - Widget Gallery: open <http://localhost:5173/>

docs/guides/AGENT_DESIGN_WORKFLOW.md

@@ -28,7 +28,7 @@ astudio design prepare --surface <path> --json
 1. In this repo, the clean-checkout convenience wrapper is:
 
 ```bash
-pnpm --silent agent-design:prepare --surface <path> --json
+pnpm --silent agent-design:prepare --surface <path>
 ```
 
 The wrapper is build-backed setup. It may build `packages/agent-design-engine`, `packages/design-system-guidance`, `packages/skill-ingestion`, and `packages/cli` before invoking the CLI. The read-only operation contract belongs to `astudio design prepare` itself once the CLI is available. Use `pnpm --silent` for JSON capture, because plain `pnpm` prints lifecycle banners before script output.
@@ -37,6 +37,8 @@ The wrapper is build-backed setup. It may build `packages/agent-design-engine`,
 1. If implementation is safe, use the returned `recommendedRoutes`, `designTokenContract`, `requiredStates`, `relevantExamples`, `forbiddenPatterns`, and `validationCommands` as the implementation brief.
 1. Edit the UI.
 1. Run the returned read-only validation commands that apply to the changed surface.
+1. Before PR handoff, run `pnpm agent-design:prepare:changed`. It builds the local CLI dependencies, checks changed `.tsx`/`.jsx` UI surfaces with the read-only prepare command, and fails if any surface is unsafe or missing prepare evidence. Use `pnpm agent-design:prepare:changed -- --surface <path>` for a single surface.
+1. CI reruns the changed-surface gate on pull requests in the web platform lane. If it fails, treat that as a missing or unsafe prepare contract, not as a generic CI failure.
 1. If validation fails or a proposal-required stop appears, fix the underlying design-system evidence or open the proposal/manual decision path.
 
 Supporting commands such as `astudio design lint`, `astudio design export`, `astudio design components`, `astudio design coverage`, and `astudio design propose-abstraction` are diagnostics. They are not the normal happy path before UI edits.

package.json

@@ -21,7 +21,7 @@
     "build:astudio-icons": "pnpm -C packages/astudio-icons build",
     "build:astudio-json-render": "pnpm -C packages/json-render build",
     "build:astudio": "pnpm build:astudio-tokens && pnpm build:astudio-ui && pnpm build:astudio-icons && pnpm build:astudio-json-render",
-    "skill-ingestion:build": "pnpm -C packages/skill-ingestion build",
+    "skill-ingestion:build": "pnpm -C packages/skill-ingestion clean && pnpm -C packages/skill-ingestion build",
     "design-system-guidance:build": "pnpm -C packages/design-system-guidance build",
     "design-system-guidance:type-check": "pnpm -C packages/design-system-guidance type-check",
     "design-system-guidance:check": "pnpm -C packages/design-system-guidance run build && node packages/design-system-guidance/dist/cli.js check .",
@@ -39,7 +39,9 @@
     "agent-design:boundaries": "node scripts/check-agent-design-boundaries.mjs",
     "agent-design:boundaries:self-test": "node scripts/check-agent-design-boundaries.mjs --self-test",
     "agent-design:proposals": "pnpm agent-design:build && node scripts/check-agent-design-proposals.mjs",
-    "agent-design:prepare": "pnpm agent-design:build && pnpm design-system-guidance:build && pnpm skill-ingestion:build && pnpm -C packages/cli build && node packages/cli/dist/index.js design prepare --json",
+    "agent-design:cli:prebuild": "pnpm agent-design:build && pnpm design-system-guidance:build && pnpm skill-ingestion:build && pnpm -C packages/cli build",
+    "agent-design:prepare": "pnpm agent-design:cli:prebuild && node packages/cli/dist/index.js design prepare --json",
+    "agent-design:prepare:changed": "pnpm agent-design:cli:prebuild && node scripts/check-agent-design-prepare-evidence.mjs",
     "agent-design:prepare:smoke": "pnpm --silent agent-design:prepare --surface packages/ui/src/app/settings/AppsPanel/AppsPanel.tsx",
     "tracked-ignored:check": "node scripts/check-tracked-ignored-artifacts.mjs",
     "tracked-ignored:check:self-test": "node scripts/check-tracked-ignored-artifacts.mjs --self-test",
@@ -128,7 +130,7 @@
     "agent-design:build": "pnpm -C packages/agent-design-engine build",
     "agent-design:type-check": "pnpm -C packages/agent-design-engine type-check",
     "agent-design:test": "pnpm -C packages/agent-design-engine test",
-    "agent-design:lint": "pnpm agent-design:build && pnpm design-system-guidance:build && pnpm skill-ingestion:build && pnpm -C packages/cli build && node packages/cli/dist/index.js design lint --file DESIGN.md --json"
+    "agent-design:lint": "pnpm agent-design:cli:prebuild && node packages/cli/dist/index.js design lint --file DESIGN.md --json"
   },
   "devDependencies": {
     "@argos-ci/cli": "^3.0.6",

packages/agent-design-engine/src/token-contract.ts

@@ -158,11 +158,11 @@ function stripCssComments(content: string): string {
  * Preserves newlines from removed comments so original line positions remain aligned and keeps escaped quotes inside string/template literals intact.
  *
  * @param content - Source JavaScript/TypeScript text to strip comments from
- * @returns The input text with `//` and `/* */` comments removed while leaving quoted and template-literal content unchanged
+ * @returns The input text with line and block comments removed while leaving quoted and template-literal content unchanged
  */
 function stripJsTsComments(content: string): string {
   let result = "";
-  let quote: "'" | '"' | "`" | undefined;
+  let quote: string | undefined;
   let escaped = false;
 
   for (let index = 0; index < content.length; index += 1) {
@@ -183,7 +183,7 @@ function stripJsTsComments(content: string): string {
       }
       continue;
     }
-    if (character === "'" || character === '"' || character === "`") {
+    if (character === "'" || character === '"' || character.charCodeAt(0) === 96) {
       quote = character;
       result += character;
       continue;

packages/cli/tests/cli.test.mjs

@@ -561,6 +561,7 @@ test("prepare command schema rejects missing north-star payload fields", async (
   );
 
   const invalidRoute = cloneJson(payload);
+  assert.ok(invalidRoute.data.recommendedRoutes[0], "prepare fixture should include a route");
   invalidRoute.data.recommendedRoutes[0].unexpectedFutureDrift = { bad: true };
   assert.equal(
     validateDesignCommandEnvelope(invalidRoute),
@@ -598,21 +599,33 @@ test("prepare command schema rejects missing north-star payload fields", async (
 test("root prepare wrapper builds CLI dependencies before prepare", () => {
   const packageJson = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
   const prepareScript = packageJson.scripts["agent-design:prepare"];
+  const prebuildScript = packageJson.scripts["agent-design:cli:prebuild"];
   assert.equal(typeof prepareScript, "string");
+  assert.equal(typeof prebuildScript, "string");
   assert.equal(
     prepareScript.includes("--surface"),
     false,
     "root prepare wrapper must not bake in a default surface",
   );
 
-  const expectedSegments = [
+  const expectedPrebuildSegments = [
     "pnpm agent-design:build",
     "pnpm design-system-guidance:build",
     "pnpm skill-ingestion:build",
     "pnpm -C packages/cli build",
-    "node packages/cli/dist/index.js design prepare --json",
   ];
   let previousIndex = -1;
+  for (const segment of expectedPrebuildSegments) {
+    const index = prebuildScript.indexOf(segment);
+    assert.ok(index > previousIndex, `${segment} must appear after the prior prebuild step`);
+    previousIndex = index;
+  }
+
+  const expectedSegments = [
+    "pnpm agent-design:cli:prebuild",
+    "node packages/cli/dist/index.js design prepare --json",
+  ];
+  previousIndex = -1;
   for (const segment of expectedSegments) {
     const index = prepareScript.indexOf(segment);
     assert.ok(index > previousIndex, `${segment} must appear after the prior wrapper step`);
@@ -625,6 +638,55 @@ test("root prepare wrapper builds CLI dependencies before prepare", () => {
   );
 });
 
+test("root changed-surface prepare gate builds dependencies before evidence check", () => {
+  const packageJson = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
+  const prepareChangedScript = packageJson.scripts["agent-design:prepare:changed"];
+  const prebuildScript = packageJson.scripts["agent-design:cli:prebuild"];
+  assert.equal(typeof prepareChangedScript, "string");
+  assert.equal(typeof prebuildScript, "string");
+
+  const expectedPrebuildSegments = [
+    "pnpm agent-design:build",
+    "pnpm design-system-guidance:build",
+    "pnpm skill-ingestion:build",
+    "pnpm -C packages/cli build",
+  ];
+  let previousIndex = -1;
+  for (const segment of expectedPrebuildSegments) {
+    const index = prebuildScript.indexOf(segment);
+    assert.ok(index > previousIndex, `${segment} must appear after the prior prebuild step`);
+    previousIndex = index;
+  }
+
+  const expectedSegments = [
+    "pnpm agent-design:cli:prebuild",
+    "node scripts/check-agent-design-prepare-evidence.mjs",
+  ];
+  previousIndex = -1;
+  for (const segment of expectedSegments) {
+    const index = prepareChangedScript.indexOf(segment);
+    assert.ok(
+      index > previousIndex,
+      `${segment} must appear after the prior prepare evidence step`,
+    );
+    previousIndex = index;
+  }
+
+  const gateSource = fs.readFileSync(
+    path.join(repoRoot, "scripts", "check-agent-design-prepare-evidence.mjs"),
+    "utf8",
+  );
+  assert.match(gateSource, /packages\/ui\/src\//);
+  assert.match(gateSource, /platforms\/web\/apps\/web\/src\//);
+  assert.match(gateSource, /safeForAutomaticImplementation === true/);
+  assert.match(gateSource, /surface is outside the repository/);
+
+  const ciWorkflow = fs.readFileSync(path.join(repoRoot, ".github", "workflows", "ci.yml"), "utf8");
+  assert.match(ciWorkflow, /Agent design prepare evidence \(web platform PR only\)/);
+  assert.match(ciWorkflow, /AGENT_DESIGN_PREPARE_BASE: origin\/\$\{\{ github\.base_ref \}\}/);
+  assert.match(ciWorkflow, /pnpm agent-design:prepare:changed/);
+});
+
 test("design command error fixtures expose stable recovery payloads", async (t) => {
   for (const fixture of designCommandFixtures.errors) {
     await t.test(fixture.name, async () => {

packages/skill-ingestion/package.json

@@ -19,7 +19,7 @@
     "build": "tsc -p tsconfig.build.json",
     "type-check": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist node_modules/.tmp/tsconfig.tsbuildinfo"
   },
   "devDependencies": {
     "@types/node": "^25.2.0",