chore(design-system): harness context docs. SCORE-1998

AGENTS.md

@@ -0,0 +1,113 @@
+# Agents
+
+This repo is a **PV1 platform submodule** served by the **SSC Claude Code Harness** — a
+multi-agent system wired into Claude Code. It is aggregated by `pv1-monorepo` (the agent
+entrypoint that pulls all PV1 services in as git submodules). Every engineer working on
+this repo has these agents available. Invoke any agent by running `/plan`, `/review`,
+`/security-review`, etc. in Claude Code, or by dispatching them directly by name.
+
+---
+
+## Roster
+
+### Margaret — Planner / Architect
+**Model:** claude-opus-4-8 | **Role:** planner
+**Persona:** Methodical, thorough, risk-aware. Thinks before anyone builds. Surfaces
+assumptions, identifies dependencies, flags scope creep.
+**Invoke when:** Starting any feature or significant refactor; before changes that cross
+service boundaries or touch data schemas.
+**Invocation:** `/plan <task description>`
+**Adversarial pair:** Devlin challenges Margaret's plans for gaps and hidden assumptions.
+
+### Devlin — Adversarial Planner
+**Model:** claude-sonnet-4-6 (external provider) | **Role:** adversarial-planner
+**Persona:** Red-teams plans. Hunts unstated assumptions, missing edge cases, failure modes.
+**Invoke when:** Automatically paired with Margaret during `/plan`.
+
+### Fletcher — Implementer
+**Model:** claude-sonnet-4-6 | **Role:** implementer
+**Persona:** Surgical. Touches only what the plan specifies. Never refactors adjacent code.
+Matches existing style without being asked.
+**Invoke when:** Executing a planned sprint. Implementation only — not design.
+
+### Ruth — Reviewer
+**Model:** claude-opus-4-8 | **Role:** reviewer
+**Persona:** Independent. Never reviews code she wrote. Checks correctness, security,
+performance, and naming. Reports findings; does not fix them.
+**Invoke when:** After every sprint. Before merging any non-trivial change.
+**Invocation:** `/review`
+
+### Conrad — Security
+**Model:** claude-opus-4-8 | **Role:** security-reviewer
+**Persona:** Adversarial by design. Assumes every surface is attacker-reachable. Auth,
+secrets, injection, trust boundaries, OWASP top 10.
+**Invoke when:** Any change touching auth, tokens, external APIs, user input, or data egress.
+**Invocation:** `/security-review` (solo) or `/adversarial-security-review` (Conrad + Argus)
+
+### Argus — Adversarial Security Reviewer
+**Model:** claude-sonnet-4-6 | **Role:** adversarial-security-reviewer
+**Persona:** Treats every reviewed input as adversary-controlled. Refutes or confirms
+Conrad's findings from a different angle.
+**Invoke when:** `/adversarial-security-review`, paired with Conrad.
+
+### Sentinel — Researcher
+**Model:** claude-sonnet-4-6 | **Role:** researcher
+**Persona:** Deep, methodical, cites everything. Structured research with confidence ratings.
+**Invoke when:** Before building something unfamiliar — a third-party API, library, or domain.
+
+### Grant — Test Writer
+**Model:** claude-sonnet-4-6 | **Role:** tester
+**Persona:** Writes tests that prove correctness, not tests that pass. Adversarial coverage.
+**Invoke when:** After implementation to add coverage; when auditing a test suite.
+
+### Vera — Wiki Maintainer
+**Model:** claude-sonnet-4-6 | **Role:** wiki-maintainer
+**Persona:** Keeps the encyclopedia current. Documents only what exists.
+**Invoke when:** After indexing or major refactors. **Invocation:** `/index-project`, `/ingest`
+
+### Doris — Document Renderer
+**Model:** claude-haiku-4-5 | **Role:** docs
+**Persona:** Render-only. Writes structured output from other agents to disk. Auto-dispatched.
+
+### Wallace — Scaffolder
+**Model:** claude-haiku-4-5 | **Role:** scaffolder
+**Persona:** Fast project bootstrapper — directories, boilerplate, CI, harness wiring.
+**Invoke when:** Starting a new service. **Invocation:** `/bootstrap`
+
+---
+
+## How They Work Together
+
+```
+Margaret (plan) → Devlin (challenge) → Margaret (arbitrate)
+      ↓
+Fletcher (implement)
+      ↓
+Ruth (review) → Fletcher (fix) → Ruth (re-review, max 3×)
+      ↓
+Conrad + Argus (security, parallel) — for security-sensitive changes
+```
+
+Sentinel and Vera run asynchronously — research before planning, wiki updates after merging.
+
+---
+
+## Working in This Repo
+
+This repo is a submodule of `pv1-monorepo`. Context precedence — **deepest CLAUDE.md wins**:
+this repo's own `CLAUDE.md` overrides the domain's, which overrides the aggregator's root.
+Commits, branches, and PRs for this service happen **here, in this repo** — not at the
+aggregator root (the aggregator only bumps submodule pointers).
+
+## Context Files Agents Read
+
+| File | Purpose |
+|---|---|
+| `AGENTS.md` | This file — agent roster and invocation guide |
+| `CLAUDE.md` | This service's agent context (if present — authoritative) |
+| `docs/ai/architecture.md` | This service's architecture |
+| `docs/ai/conventions.md` | Coding / PR / submodule conventions |
+
+---
+
+_Last indexed: 2026-06-17 by `/index-project` — re-run to update after major changes._

docs/ai/architecture.md

@@ -0,0 +1,116 @@
+# design-system — Architecture (Agent-Readable)
+
+> Generated by /index-project (2026-06-17). Companion to the harness encyclopedia system page.
+
+## Overview
+
+`@securityscorecard/design-system` is the SecurityScorecard React component library and
+design-token source, published as a versioned npm package (registry: GitHub Packages). It
+provides the reusable UI primitives, compound components, theming, design tokens, hooks, and
+i18n locales consumed by PV1 frontends (notably `ssc-ui-core`). It is a standalone library —
+not a microservice and not an app — built and distributed for installation into consuming
+applications.
+
+## Architecture
+
+Single-package library (not a monorepo workspace). Source lives under `src/` and is built with
+Vite into `build/` as CJS (`index.cjs`), ESM (`index.mjs`), and type declarations
+(`index.d.ts`), plus separately-exported locale bundles and a `tokens.css` artifact.
+
+Components follow a strict per-directory convention: each component dir holds
+`ComponentName.tsx` (forwardRef pattern), `.types.ts`, `.enums.ts`, `.stories.tsx`,
+`.test.tsx`, and an `index.ts` barrel. Complex components split styled markup into a
+`BaseStyledComponent.tsx`, and shared base implementations live in `src/components/_internal/`
+(BaseButton, BaseTable, BaseDropdownMenu, etc.) composed by public components.
+
+Theming is runtime via `createTheme(overrides)` merged into defaults and supplied through
+`DSProvider`; styled-components read theme through the `theme` prop or `var(--sscds-*)` CSS
+custom properties. Storybook serves as both documentation and the visual-regression test
+surface (all stories are visual tests by default).
+
+## Tech Stack
+
+- **Language:** TypeScript (React 18 library)
+- **UI:** React 18, styled-components 5, Radix UI primitives (colors, collapsible,
+  dropdown-menu, tooltip), FontAwesome SVG icons, react-select, react-popper/@popperjs,
+  @dnd-kit (drag/drop), @tanstack/react-table + react-table, react-datepicker, react-dropzone
+- **Utilities:** ramda / ramda-adjunct, classnames, numeral, fast-deep-equal, pullstate
+  (state managers)
+- **i18n:** i18next + react-i18next + i18next-icu; locales en-US, cs-CZ, es-ES, pt-BR, ja-JP
+- **Build/tooling:** Vite 5 + vite-plugin-dts, Yarn 4 (Berry), semantic-release
+  (conventional-commits driven), husky + commitlint, ESLint (airbnb base), Stylelint, knip
+- **Test:** Vitest + React Testing Library (unit), Storybook 8 + storycap + reg-cli (visual
+  regression, Docker), axe-core/storybook test-runner (a11y)
+- **Peer deps (provided by host app):** react, react-dom, react-router-dom ^5, react-select,
+  styled-components
+- **Distribution:** published to GitHub Packages registry; per-PR snapshot builds published
+  with `pr-<PR-number>` npm tag
+
+## Entry Points
+
+- `src/index.ts` — main library barrel export (the package `.` export / `default`)
+- `build/index.mjs` / `build/index.cjs` / `build/index.d.ts` — published build artifacts
+  (ESM / CJS / types)
+- `src/locales/*` → `./locales/<locale>` package subpath exports (en-US, cs-CZ, es-ES, pt-BR,
+  ja-JP)
+- `build/tokens.css` → `./tokens.css` export — design-token CSS custom properties
+- `yarn build` (vite build) — produce the distributable package
+- `yarn storybook` — Storybook dev server on port 8008 (component dev + docs)
+- `yarn test` / `yarn test:storybook:visual` — unit (Vitest) and visual-regression (Docker)
+  test suites
+
+## Components
+
+- `src/components/` — all public components, each in its own directory (Button/ButtonV2,
+  Card, Drawer, Dropdown, DropdownMenu, Tabs, Tooltip, Toast, Wizard, Stepper, TreeView,
+  SortableList, Pagination, ProgressBar, HexGrade, forms/, layout/, etc.)
+- `src/components/_internal/` — shared base implementations (BaseButton, BaseTable,
+  BaseDropdownMenu) composed by public components
+- `src/theme/` — `createTheme()`, default theme values, `DSProvider` (ThemeProvider wrapper)
+- `src/tokens/` — CSS custom properties (`--sscds-*`) for colors, space, radii, fonts,
+  shadows, depth, size
+- `src/hooks/` — utility hooks (useClipboard, useContainerQuery, useDebounce, useFocusTrap,
+  useLogger, etc.)
+- `src/contexts/` — `DSContext` for global config (portalsContainerId, debugMode,
+  experimental flags)
+- `src/managers/` — application state managers (e.g. NotificationsManager) built on pullstate
+- `src/locales/` — i18n translation bundles
+- `src/utils/` — utilities, including `tests/setup.tsx` test harness (wraps in DSProvider +
+  MemoryRouter)
+- `.storybook/` — Storybook config; `visual-regressions/` — Dockerized visual-regression
+  runner; `extension/` — small browser extension (popup) helper
+
+## Data Schemas
+
+None — this is a UI component library, not a data service. Public contracts are the
+TypeScript component prop types (`*.types.ts`) and variant enums (`*.enums.ts`) exported from
+each component, the theme shape from `createTheme`, and the `--sscds-*` CSS custom-property
+token names. No API endpoints, DB models, or event/proto schemas. (API contracts not
+applicable at survey depth.)
+
+## Cross-System Dependencies
+
+- `pv1-monorepo` — parent aggregator
+- `ssc-ui-core` — primary consumer (main PV1 React SPA shell installs this package); other
+  PV1 frontends consume it as well
+- GitHub Packages (`npm.pkg.github.com`) — publish registry for the released package
+- Radix UI, FontAwesome, styled-components, react-router-dom — key external library
+  dependencies (router is a peer dep supplied by the host app)
+
+## Gotchas
+
+- Versioning/release is fully automated via semantic-release driven by conventional commits;
+  `package.json` version is pinned to `0.0.0` (real versions are assigned at publish time,
+  not committed).
+- PRs target the `alpha` branch (not `main`); `main` is only for hotfixes when `alpha`/`next`
+  don't exist. Per-PR snapshot builds are installable via
+  `yarn add @securityscorecard/design-system@pr-<PR-number>` and auto-unpublished on PR close.
+- `react`, `react-dom`, `react-router-dom`, `react-select`, and `styled-components` are peer
+  dependencies — they must be provided by the consuming app; version mismatches surface
+  there, not here.
+- All Storybook stories double as visual-regression tests by default; opt out with
+  `parameters: { screenshot: { skip: true } }`. Visual regression requires Docker.
+- Local pre-release testing in a consuming app uses `yalc` (`yarn build && yalc push`), not a
+  normal npm install.
+- Use transient props (`$propName`) for styling-only styled-components props to avoid leaking
+  them to the DOM.

docs/ai/conventions.md

@@ -0,0 +1,43 @@
+# Conventions (Agent-Readable)
+
+> Generated by `/index-project` (2026-06-17). This repo is a **PV1 platform submodule**.
+> Platform-wide conventions from `pv1-monorepo`. If this repo has its own `CLAUDE.md`,
+> that is authoritative and overrides anything here.
+
+## Coding Tenets
+
+1. **Think Before Coding** — State assumptions explicitly. If multiple interpretations
+   exist, present them. If unclear, stop and ask. Do not hide confusion.
+2. **Simplicity First** — Minimum code that solves the problem. No speculative features,
+   no abstractions for single-use code. If 200 lines could be 50, rewrite.
+3. **Surgical Changes** — Touch only what's required. Do not improve adjacent code. Match
+   existing style. Every changed line must trace to the request.
+4. **Goal-Driven Execution** — Define success criteria first. Loop until verified.
+
+## PR Requirements
+
+- **A Jira ticket is required.** Ask for one before opening a PR if not provided.
+- **Title format:** `type(scope): description TICKET-123` — Angular commit convention +
+  Jira ticket. Valid types: `feat`, `fix`, `bug`, `chore`, `hotfix`, `build`, `ci`,
+  `docs`, `perf`, `refactor`, `style`, `test`.
+- **Squash-merge only** — never a merge commit or rebase merge.
+- **Description must explain the implementation approach**, not just reference the ticket.
+- **Pre-PR blocking checks:** no secrets committed, no SQL injection, no silent errors,
+  no broken proto fields.
+
+## Context Hierarchy (Deepest CLAUDE.md Wins)
+
+1. This repo's `CLAUDE.md` (highest authority for this service)
+2. Domain `CLAUDE.md` (in the `pv1-monorepo` aggregator: `domains/<domain>/CLAUDE.md`)
+3. Aggregator platform root `CLAUDE.md`
+
+## Agent Workflow Protocol
+
+`/orient` → `/plan` → implement → `/review` → `/learn`
+
+## Platform Facts
+
+- Deployment: AWS ECS (services), Apache Airflow / MWAA + Databricks (ETL), React SPA (frontend)
+- CI/CD: GitHub Actions (primary), Jenkins (legacy)
+- Secrets: HashiCorp Vault · Feature flags: LaunchDarkly
+- Observability: Datadog (primary), New Relic (some services)