[codex] ratchet quality debt cleanup

.design-system-guidance.json

@@ -7,11 +7,15 @@
   ],
   "include": [
     "packages/ui/src/app",
+    "platforms/web/apps/web/src",
     "platforms/web/apps/web/src/pages",
     "packages/ui/src/components/ui",
     "packages/ui/src/design-system/showcase",
+    "packages/ui/src/icons",
     "packages/ui/src/storybook",
-    "packages/ui/src/styles"
+    "packages/ui/src/styles",
+    "packages/ui/src/templates",
+    "packages/widgets/src"
   ],
   "ignore": [
     "node_modules",
@@ -124,7 +128,11 @@
       "platforms/web/apps/web/src/pages/**/*.{ts,tsx,js,jsx,css}",
       "packages/ui/src/components/ui/**/*.{ts,tsx,js,jsx,css}",
       "packages/ui/src/design-system/showcase/**/*.{ts,tsx,js,jsx,css}",
+      "packages/ui/src/icons/**/*.tsx",
       "packages/ui/src/storybook/**/*.{ts,tsx,js,jsx,css}",
+      "packages/ui/src/templates/**/*.tsx",
+      "packages/widgets/src/**/*.tsx",
+      "platforms/web/apps/web/src/**/*.{ts,tsx,js,jsx,css}",
       "**/*.stories.tsx"
     ],
     "exempt": [

FORJAMIE.md

@@ -16,7 +16,7 @@
 ## Status
 
 <!-- STATUS_START -->
-**Last updated:** 2026-05-02
+**Last updated:** 2026-05-03
 **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
 
@@ -207,14 +207,20 @@ 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 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 app/widget/UI catalog trees, runs the read-only CLI prepare operation for each surface, and fails closed for protected surfaces when a payload is unsafe, incomplete, unparseable, or points outside the repository. Warn-scope surfaces can report missing route coverage without blocking a non-design cleanup, while `-- --surface <path>` remains a fail-closed targeted 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.
 - `docs/guides/AGENT_DESIGN_WORKFLOW.md` is the detailed workflow authority for protected UI edits. `README.md` is the short repo front door, and this file is the durable project map; avoid restating the whole workflow in all three places.
 - `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-03
+
+- **Unslopify quality evidence refresh**: ran the `unslopify` cleanup audit path across the current repo-owned cleanup gates, refreshed the Apps SDK upstream alignment stamp from a passing `pnpm test:drift` run, and generated the current weekly quality-debt report. The report remains warn-first: it is release-owner evidence, not a new hard-fail gate.
+- **Disabled Biome rule ratchet**: renamed the quality-debt radar category from ambiguous “lint suppressions” language to `Disabled Biome rules`, promoted 15 previously disabled Biome rules back into active lint coverage, and fixed the resulting lint errors/warnings in chart styles, sidebar cookie persistence, story exports, generated icon locals, widget entrypoints, widget state fallbacks, icon catalog filtering, map refs, migration/drift scripts, token watcher logging, and remote skill ingestion. The generated weekly report now shows 18 disabled linter rules remaining, down from 34.
+- **Agent-design changed-surface CLI cleanup**: aligned `pnpm agent-design:prepare:changed` with the PR evidence contract by keeping protected surfaces fail-closed, treating warn-scope unrouted catalog/widget/story surfaces as visible warnings, and adding a provisional `navigation_sidebar` route for the protected Sidebar fallback. `.design-system-guidance.json` now classifies icon, template, widget, and web-app entrypoint surfaces as warn-scope instead of leaving them as unknown CLI drift.
+
 ### 2026-05-02
 
 - **PR #161 review-thread fixes**: tightened the derived `astudio design prepare` formats so CI refuses `--format brief` and `--format pr-evidence` instead of emitting non-JSON contract output, made route confidence/example maturity depend on registered gold-example evidence, and added `nextAction.reasonCode`, route confidence, forbidden-patterns, and stricter validation-command typing to the brief, PR-evidence, schema, and payload surfaces. The same fix pass hardened `packages/effects` scroll and tilt components by clamping fallback progress/tilt values, resetting invalid selector progress, preserving TOC marker style override precedence, sanitizing `hoverScale`, and removing inline style assertions. It also added `pnpm validation-prototype:ban-check` and wired it into `pnpm test:policy` so product code cannot import the validation fixture; the guard now checks real import/export/require/dynamic-import specifiers and package dependency fields instead of raw text mentions. Gold-example parsing now trims and rejects blank `sourcePath`, `purpose`, and state values, and validation-command `ifFails` guidance now trims blanks back to the deterministic default remediation text. Validation evidence for the focused fixes includes `pnpm -C packages/agent-design-engine test`, `pnpm -C packages/cli test`, `pnpm -C packages/effects test`, and `pnpm validation-prototype:ban-check`.
@@ -237,7 +243,7 @@ project: design-system
 repo: ~/dev/design-system
 status: IN_PROGRESS
 health: yellow
-last_updated: 2026-05-02
+last_updated: 2026-05-03
 open_prs: 1
 blockers: none
 next_milestone: Agent Design Prepare PR review and merge

biome.json

@@ -21,7 +21,7 @@
       "!docs/examples",
       "!docs/validation",
       "!**/generated",
-      "!worker-configuration.d.ts",
+      "!**/worker-configuration.d.ts",
       "!packages/astudio-icons/src/react/**/*.tsx",
       "!pnpm-lock.yaml",
       "!scripts/policy",
@@ -41,17 +41,14 @@
         "noExplicitAny": "off",
         "noAssignInExpressions": "off",
         "noArrayIndexKey": "off",
-        "noShadowRestrictedNames": "off",
-        "noSuspiciousSemicolonInJsx": "off",
-        "noGlobalAssign": "off",
-        "noRedeclare": "off",
-        "noDuplicateObjectKeys": "off",
-        "noDocumentCookie": "off",
-        "useIterableCallbackReturn": "off",
-        "noCommentText": "off"
-      },
-      "style": {
-        "noNonNullAssertion": "off"
+        "noShadowRestrictedNames": "error",
+        "noSuspiciousSemicolonInJsx": "error",
+        "useIterableCallbackReturn": "error",
+        "noGlobalAssign": "error",
+        "noRedeclare": "error",
+        "noDuplicateObjectKeys": "error",
+        "noDocumentCookie": "warn",
+        "noCommentText": "warn"
       },
       "a11y": {
         "noSvgWithoutTitle": "off",
@@ -64,25 +61,24 @@
         "useValidAnchor": "off",
         "useFocusableInteractive": "off",
         "useAriaPropsForRole": "off",
-        "noRedundantAlt": "off"
+        "noRedundantAlt": "error"
       },
       "correctness": {
         "useHookAtTopLevel": "off",
         "noUnusedFunctionParameters": "off",
         "noUnusedVariables": "off",
-        "noInvalidPositionAtImportRule": "off",
         "useExhaustiveDependencies": "off",
         "noUnusedImports": "off"
       },
       "complexity": {
-        "noBannedTypes": "off",
-        "noStaticOnlyClass": "off"
+        "noBannedTypes": "error",
+        "noStaticOnlyClass": "warn"
       },
       "performance": {
-        "noDynamicNamespaceImportAccess": "off"
+        "noDynamicNamespaceImportAccess": "warn"
       },
       "security": {
-        "noDangerouslySetInnerHtml": "off"
+        "noDangerouslySetInnerHtml": "error"
       }
     }
   },

docs/design-system/AGENT_UI_ROUTING.json

@@ -143,6 +143,51 @@
         "docs/design-system/COMPONENT_LIFECYCLE.json"
       ]
     },
+    {
+      "need": "navigation_sidebar",
+      "canonicalNeed": "navigation_sidebar",
+      "aliases": ["sidebar navigation", "app sidebar", "collapsible sidebar"],
+      "preferredComponent": {
+        "name": "Sidebar",
+        "importPath": "packages/ui/src/components/ui/navigation/sidebar/fallback/Sidebar.tsx",
+        "packageName": "@design-studio/ui",
+        "coverageName": "Sidebar"
+      },
+      "lifecycleStatus": "transitional",
+      "routeMaturity": "provisional",
+      "surfacePatterns": ["packages/ui/src/components/ui/navigation/sidebar/fallback/Sidebar.tsx"],
+      "useWhen": [
+        "A page shell needs collapsible sidebar navigation while Apps SDK UI lacks matching API parity.",
+        "The surface is maintaining the existing fallback sidebar primitive rather than creating a new navigation abstraction."
+      ],
+      "requiredStates": ["ready", "collapsed", "expanded", "mobile"],
+      "examples": [
+        "packages/ui/src/app/chat/ChatSidebar/ChatSidebar.stories.tsx",
+        "packages/ui/src/app/chat/ChatSidebar/ChatSidebar.test.tsx"
+      ],
+      "avoid": [
+        "A second sidebar primitive parallel to the existing fallback.",
+        "New product page shells that hand-roll sidebar state instead of using ProductPageShell slots."
+      ],
+      "fallbacks": [
+        {
+          "component": "ProductPageShell",
+          "reason": "Use for page-level shell composition and only reach for Sidebar when shell slots need the existing fallback behavior."
+        }
+      ],
+      "validationCommands": [
+        {
+          "command": "pnpm agent-design:lint",
+          "safetyClass": "read_only",
+          "reason": "Checks the current design contract without mutating files."
+        }
+      ],
+      "sourceRefs": [
+        "docs/design-system/AGENT_UI_ROUTING.md#agent-composition-primitives",
+        "docs/design-system/COMPONENT_LIFECYCLE.json",
+        "docs/KEYBOARD_NAVIGATION_TESTS.md"
+      ]
+    },
     {
       "need": "product_panel",
       "canonicalNeed": "product_panel",

docs/design-system/AGENT_UI_ROUTING.md

@@ -60,6 +60,7 @@ For new product surfaces, start with the smallest local composition primitive th
 | Repeated content group             | `ProductSection`      | Owns section heading and vertical rhythm.                                               |
 | Async collection or results region | `ProductDataView`     | Combines section hierarchy with ready/loading/empty/error/busy state routing.           |
 | Local async state inside a panel   | `ProductStateWrapper` | Swaps between ready content and accessible loading, empty, error, or busy presentation. |
+| Collapsible sidebar navigation     | `Sidebar`             | Transitional fallback for shell sidebar navigation until Apps SDK UI has API parity.    |
 
 Use `Stack`, `Flex`, and `Grid` inside these primitives for local rhythm and alignment. Do not rebuild page shells from loose `div` chains when one of these primitives fits.
 

docs/design-system/COMPONENT_LIFECYCLE.json

@@ -100,6 +100,13 @@
       "routing_tier": 2,
       "notes": "Preferred destructive confirmation primitive while Apps SDK UI lacks matching API parity."
     },
+    {
+      "name": "Sidebar",
+      "path": "packages/ui/src/components/ui/navigation/sidebar/fallback/Sidebar.tsx",
+      "lifecycle": "transitional",
+      "routing_tier": 2,
+      "notes": "Fallback navigation sidebar primitive for page shells until Apps SDK UI exposes matching API parity."
+    },
     {
       "name": "DataTable",
       "path": "packages/ui/src/components/ui/data-display/DataTable/DataTable.tsx",

docs/design-system/UPSTREAM_ALIGNMENT.md

@@ -1,6 +1,14 @@
 # Apps SDK UI Upstream Alignment Log
 
-Last updated: 2026-01-08
+Last updated: 2026-05-03
+
+## Table of Contents
+
+- [Pinned Version](#pinned-version)
+- [Last Verified](#last-verified)
+- [Drift Test Suite](#drift-test-suite)
+- [Delta Register Template](#delta-register-template)
+- [Alignment Stamp (CI-Managed)](#alignment-stamp-ci-managed)
 
 ## Pinned Version
 
@@ -9,7 +17,7 @@ Last updated: 2026-01-08
 
 ## Last Verified
 
-- Last verified: 2026-01-24T01:28:42Z (drift suite run locally; warnings logged for non-reexported upstream components).
+- Last verified: 2026-05-03T11:35:12Z (drift suite run locally; warnings logged for non-reexported upstream components).
 
 ## Drift Test Suite
 
@@ -33,6 +41,6 @@ Use this template for any deviation from upstream:
 
 This section is updated by CI when drift tests pass:
 
-- Verified at: 2026-01-24T01:28:42Z (local run; CI stamp pending)
+- Verified at: 2026-05-03T11:35:12Z (local run; CI stamp pending)
 - apps-sdk-ui version: ^0.2.1
-- Drift suite commit: b85fe78bd5caa86a7bb89a5962c218832316c2ab (working tree)
+- Drift suite commit: 2e5423f184964e1a2b39f9da1714870bfeb8343a (working tree)

docs/operations/quality-debt-radar.categories.json

@@ -9,9 +9,9 @@
   "categories": [
     {
       "id": "lint-suppressions",
-      "label": "Lint suppressions",
+      "label": "Disabled Biome rules",
       "owner": "@platform",
-      "description": "Biome rules intentionally disabled or broadly suppressed that can hide real issues.",
+      "description": "Biome lint rules intentionally disabled in the repository configuration that can hide real issues.",
       "source_anchors": ["biome.json", "FORJAMIE.md"],
       "probe": "biome_disabled_rules",
       "source_commands": ["pnpm lint"],

docs/operations/quality-debt-radar.md

@@ -41,7 +41,7 @@ Debt is tracked by category. Do not collapse to a single score.
 
 | Category              | Description                                                                                | Source Anchors                                                                    |
 | --------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
-| Lint suppressions     | Lint rules intentionally disabled or broadly suppressed that hide real issues              | `/biome.json`, `/FORJAMIE.md`                                                     |
+| Disabled Biome rules  | Biome lint rules intentionally disabled in repo config that hide real issues               | `/biome.json`, `/FORJAMIE.md`                                                     |
 | A11y debt             | Accessibility-lint suppressions and uncovered contract gaps for local primitives           | `/docs/design-system/A11Y_CONTRACTS.md`, `/docs/design-system/COVERAGE_MATRIX.md` |
 | CSS lint coverage gap | CSS excluded from current lint surface due parser/tooling constraints                      | `/biome.json`                                                                     |
 | Integration drift     | Drift between upstream/contracts and local integration seams (Apps SDK, exports, wrappers) | `/scripts/test-drift.mjs`, `/docs/design-system/UPSTREAM_ALIGNMENT.md`            |

packages/astudio-icons/src/registry.ts

@@ -183,7 +183,7 @@ import Category from "./react/platform/Category";
 import Checkbox from "./react/platform/Checkbox";
 import CheckboxChecked from "./react/platform/CheckboxChecked";
 import CheckboxIndeterminate from "./react/platform/CheckboxIndeterminate";
-import Function from "./react/platform/Function";
+import FunctionIcon from "./react/platform/Function";
 import GptPlaceholder from "./react/platform/GptPlaceholder";
 import KeyAmpersand from "./react/platform/KeyAmpersand";
 import KeyArrowDown from "./react/platform/KeyArrowDown";
@@ -274,7 +274,7 @@ import ToggleOn from "./react/platform/ToggleOn";
 import Wifi from "./react/platform/Wifi";
 import CheckCircle from "./react/settings/CheckCircle";
 import Checkmark from "./react/settings/Checkmark";
-import Error from "./react/settings/Error";
+import ErrorIcon from "./react/settings/Error";
 import Info from "./react/settings/Info";
 import LightBulb from "./react/settings/LightBulb";
 import Moon from "./react/settings/Moon";
@@ -372,7 +372,7 @@ export const iconRegistry = {
   "dropbox-icon": DropboxIcon,
   edit: Edit,
   email: Email,
-  error: Error,
+  error: ErrorIcon,
   "expand-lg": ExpandLg,
   "expand-md": ExpandMd,
   "expand-sm": ExpandSm,
@@ -383,7 +383,7 @@ export const iconRegistry = {
   flask: Flask,
   folder: Folder,
   "folder-open": FolderOpen,
-  function: Function,
+  function: FunctionIcon,
   "git-hub-icon": GitHubIcon,
   globe: Globe,
   go: Go,