@bonesofspring/ai-rules 0.2.31 → 0.2.32

package/presets/claude/next/rules/ui-and-accessibility/forms-validation.md

@@ -0,0 +1,35 @@
+---
+description: Forms and validation — use the repo's form library + design-system fields + shared validators, not ad-hoc state
+impact: MEDIUM
+paths:
+  - app/src/**/*Form*.tsx
+  - app/src/**/*Form*.ts
+  - app/src/**/*Modal*.tsx
+---
+
+# Forms and validation
+
+Use the form solution already in the repo (`package.json` + the nearest form component). Do not hand-roll form state with `useState` when a form library is present.
+
+## Rules
+
+- One form-hook instance per form; register design-system fields through the library's controller/wrapper (controlled) — not a raw `<input>` when a DS field exists.
+- Validate with the repo's resolver/schema library and reuse the shared validators under the repo's validation utils — never re-implement email / phone / date / length rules inline.
+- Masked inputs (phone, date, card) go through the repo's mask library, not ad-hoc regex on change.
+- Disable submit while `!isValid` / `isSubmitting`; surface field errors from the form library's error state.
+- Keep side effects out of field components: the form owns `onSubmit`; data flows to store/API through the repo's layers (`architecture/architecture-boundaries-ui.md`).
+
+## Accessibility
+
+- Every field has a visible label and an associated error message; do not rely on placeholder-only labels.
+- Field errors are announced and tied to the input; keep the DS field's wiring instead of a bespoke error node.
+
+## Stack notes
+
+- Library: `react-hook-form` + `yup` resolver; `mode: 'onTouched'`.
+- DS fields: `app/src/ui/components/_form/**`; shared validators: `app/src/lib/utils/validations/**`; masks: `imask` / `react-imask`.
+
+## Related
+
+- `ui-and-accessibility/react-ui.md` — component structure and decomposition.
+- `architecture/architecture-boundaries-ui.md` — no API/DTO in UI.

package/presets/claude/next/rules/ui-and-accessibility/react-ui.md

@@ -24,6 +24,24 @@ impact: HIGH
 - No nested ternaries in JSX. For not-ready / empty / error, use an early return or a dedicated `EmptyState` / `ErrorState` component.
 - A `variant` / `mode` flag that renders two unrelated layouts is **two** components, not one.
 
+# One component / one styled element — one purpose
+
+- Each component **and** each styled element serves exactly **one** purpose. Do not drive two distinct shapes (different padding, slot set, alignment, visual identity) from a `variant` / `is…` flag or branchy styles.
+- Two call sites that need visibly different markup → two named components (or two named styled exports). Share the base via a small primitive (`BaseCard` styled block + two thin extensions), not a universal branchy `Card`.
+- A flag that flips a single non-layout property (`compact`, `disabled`) is fine; a flag that flips layout, slots, or visual identity is not — split it.
+
+# CSS-in-JS interpolation functions
+
+- Inside `${…}` interpolations of a styled template (`styled.*`), do **not** write an inline arrow (`${({ tone }) => …}` or `${({ gap }) => gap}`). Reference a **module-level function** that takes the styled props: `${getPromoStatusColor}`.
+- Name it `get` + the value (`getColor`, `getGap`, `getPromoStatusColor`); keep the prop type shared between the styled generic and the function parameter.
+- A module-level function is debuggable, type-checkable in isolation, and reusable across sibling styled blocks; an inline arrow compiles to an untestable one-shot.
+
+# Async UI states
+
+- Loading, empty, error, and load-failed are **distinct** states — render each explicitly; do not collapse them into one spinner/blank branch.
+- Prefer a **per-block skeleton** over a page-level spinner, and reuse the repo's existing primitives (`Skeleton`, `EmptyState`, `ErrorState`, load-failed stub, global `ErrorBoundary`) instead of inventing new ones.
+- Error boundaries are usually mounted once at the app root; add a local boundary only when the repo already does so for that region.
+
 ## Incorrect
 
 ```tsx
@@ -99,7 +117,7 @@ For a reusable component:
 - **Forbidden** to import another component's `styles` (`../Other/styles`, `../../styles`). Allowed: `./styles`, shared primitives from `@/ui/components/...` or design-system packages.
 - CSS / `styled` order — Stylelint idiomatic-order: `ui-and-accessibility/css-property-order.md` (loads on `styles.ts` / `.css`).
 - For visuals use **the style stack and tokens already in the project** (variables, theme, shared classes, design package).
-- **Token binding (Figma → repo):** typography, color, spacing, radius, shadow, and imagery must bind to the project token module and the design system (`@sds/tokens-*` / `@sds/brand-colors` / DS components like `Text variant="…"`, `@sds/icon`, `next/image`). Raw `#…` / `rgb(…)` / `px` where a token exists is a finding. The full discipline — including the per-element parity checklist and the developer self-check vs Figma — is in **`ui-and-accessibility/design-tokens-binding.md`**. When a Figma reference exists, the `mockup-review.md` `## Design contract` section is the binding table; use it.
+- **Token binding (Figma → repo):** typography, color, spacing, radius, shadow, and imagery must bind to the project token module and the design system (`@sds/tokens-*` / `@sds/brand-colors` / DS components like `Text variant="…"`, `@sds/icon`, the project image primitive). Raw `#…` / `rgb(…)` / `px` where a token exists is a finding. The full discipline — including the per-element parity checklist and the developer self-check vs Figma — is in **`ui-and-accessibility/design-tokens-binding.md`**. When a Figma reference exists, the `mockup-review.md` `## Design contract` section is the binding table; use it.
 - Avoid:
   - inline styles except simple cases;
   - duplicating styling already covered by shared primitives;

package/presets/claude/next/team/fixtures/feature-with-ux-no-figma.json

@@ -2,16 +2,15 @@
   "slug": "example-feature-with-ux-no-figma",
   "intent": "feature",
   "profile": "standard",
-  "summary": "Feature with required-signal UX and no Figma URL — task-analyst loads skill ux-design; no mockup-reviewer step",
+  "summary": "UI-scope feature with required-signal UX and no Figma URL — task-analyst loads skill ux-design; UI scope forces mockup-reviewer (reviewed against AC / ux-design.md)",
   "steps": [
     { "agent": "task-analyst", "label": "Clarify, UX design, decompose" },
+    { "agent": "mockup-reviewer", "label": "UI review vs AC / ux-design" },
     { "agent": "feature-developer", "label": "Implement" },
     { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
     { "agent": "code-reviewer", "label": "Code review", "model": "cheap" }
   ],
   "humanGates": ["after:task-analyst"],
   "autoChain": true,
-  "skipped": [
-    { "agent": "mockup-reviewer", "reason": "No figma.com URL; analyst skill ux-design covers behavioral UX" }
-  ]
+  "skipped": []
 }

package/presets/claude/nuxt/rules/tooling-and-review/agent-team-orchestrator.md

@@ -96,8 +96,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- 
-                  Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/claude/php-hexagonal/rules/tooling-and-review/agent-team-orchestrator.md

@@ -78,8 +78,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- 
-                  Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/claude/php-laravel/rules/tooling-and-review/agent-team-orchestrator.md

@@ -74,8 +74,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- 
-                  Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/claude/svelte/rules/tooling-and-review/agent-team-orchestrator.md

@@ -97,8 +97,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- 
-                  Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/cursor/android-kotlin/rules/agent-team-orchestrator.mdc

@@ -74,7 +74,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/cursor/go/rules/agent-team-orchestrator.mdc

@@ -72,7 +72,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/cursor/ios-swift/rules/agent-team-orchestrator.mdc

@@ -74,7 +74,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/cursor/java/rules/agent-team-orchestrator.mdc

@@ -72,7 +72,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/cursor/mcp-ts/rules/agent-team-orchestrator.mdc

@@ -72,7 +72,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/cursor/next/REPO_AGENTS.md

@@ -43,6 +43,8 @@ Working directory for app scripts: **`app/`**. Detect the package manager from l
 
 After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent `build-verifier`.
 
+Repositories with more than one package (e.g. `app/` + `storybook/`) run each package's own scripts from its own directory; do not conflate runners.
+
 ## Security basics
 
 - Do not commit secrets (`.env`, tokens, credentials).
@@ -65,10 +67,18 @@ Skills: `.cursor/skills/`, `.claude/skills/`, `.mavis/skills/`, or `.opencode/sk
 
 Gotchas, local patterns, and team decisions: **`.ai.local/conventions.md`** (fill after init; `init` does not overwrite it).
 
+## Seed library (`.ai.local/rules-library/`)
+
+`init` seeds **staged-inactive** rule templates here (Cursor `.mdc` sources analog: `presets/cursor/next/ai-local/rules-library/**`). They are **not** active until moved into `.ai.local/rules/`. When a seed matches the task scope, apply it and tell the owner to move it. Typical seeds: `router-pages` (Pages Router override), `no-react-fc`, `component-child-decomposition`, `single-source-copy-constants`, `commit-hygiene`, `pre-pr-checklist`, `api-contract-source`, `agent-pipeline-gates`, `task-levels`, `analytics-events`, `feature-flags-experiments`, `pwa-service-worker`, `qa-test-cases`, `forms-validation`, and the `storybook-*` set.
+
+## Managed vs preserved
+
+`init` owns `.cursor/**`, `.claude/**`, `.mavis/**`, `.opencode/**`, root `AGENTS.md`, and the tool MCP config; it **overwrites/merges** them. Durable project config and authoritative specs belong **outside** those trees: `.ai.local/**`, `.ai/context/**`, `docs/specs/**`, `openspec/**`, repo-root `.mcp.json`. After a re-init, re-check any consumer-owned block added to a managed file.
+
 ## Local overlay (`.ai.local/`) — MANDATORY
 
 A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in monorepos. **All agents MUST read and apply it on every turn.** Rules there override preset rules; in conflicts, the local rule wins. `override: kill <preset-rule-name>` drops the named preset rule from the agent's context entirely.
 
-Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`.
+Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`. Staged seeds live in `.ai.local/rules-library/**`; a matching seed must be moved into `.ai.local/rules/` to activate.
 
 On every turn, probe `ls -la .ai.local`, apply `.ai.local/rules/*.md` and `.ai.local/conventions.md`, and acknowledge `Using .ai.local: <rule-name>`. Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule is always-on on Cursor and session-start on Claude (no `paths:`). Mavis and OpenCode have no native `alwaysApply`; this section plus the platform entry's essential-rules list is the reinforcement.

package/presets/cursor/next/agents/build-verifier.md

@@ -23,6 +23,7 @@ Use **`package-manager.mdc`** for the repo package manager.
 2. **`lint:css`** — full Stylelint.
 3. **`type-check`** — when TypeScript changed.
 4. **Unit tests** — run specs for changed modules (paths from diff); if unclear, run the narrowest parent suite that covers changed mappers/services/store.
+5. **Component catalog** — when the repo ships a catalog (e.g. `storybook/`) and `app/src/ui/**` or catalog files changed, run the catalog's own test/visual-baseline suite from the catalog package and require green **without** `--update` (`component-catalog-gate`). A green app unit run does not cover catalog stories.
 
 Prefer **`lint`** (= js + css + type-check) before handoff on large changes.
 

package/presets/cursor/next/agents/code-reviewer.md

@@ -99,5 +99,6 @@ Do not mix this output with retrospective facilitation — keep review and retro
 
 - **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition, implementation, validation evidence, and the scoped git diff.
 - **Owned outputs:** `review.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `review`) and preserve all foreign items in `manifest.artifacts[]`.
+- **Commit hygiene:** never run `git commit` / `git push`. Reviewer turns end with findings only; when asked for commit guidance, propose an area-split commit plan (source / artifacts / docs) with the owning slug.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/cursor/next/agents/feature-developer.md

@@ -126,5 +126,6 @@ Shipped browser split: Playwright MCP for e2e specs/selectors; Chrome DevTools M
 
 - **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.
 - **Owned outputs:** `implementation.md` plus changed implementation/test paths; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `implementation`) and preserve all foreign items in `manifest.artifacts[]`.
+- **Commit hygiene:** never run `git commit` / `git push`. At the end of the turn return a `## Human commits` block: files touched + a proposed commit message, split by area (source / artifacts / docs) with the owning slug/ticket in the subject. See the consumer `commit-hygiene` local rule.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/cursor/next/agents/openspec-author.md

@@ -61,6 +61,8 @@ Hard constraints (read `config.yaml rules.proposal` first — they win):
 
 - `proposal.md` ≤ 500 words.
 - `## Non-goals` section mandatory (omit → `blocked`).
+- `## Compliance impact` block mandatory in `proposal.md` and `design.md` (None | Affected — list PD / medical / analytics / SSR-cookie / third-party surfaces); when unclear, default to `Affected` and block.
+- `## Hard rules applied` block at the top of `proposal.md` / `design.md` / `tasks.md` (applicable rules + how applied; `N/A — reason` for the rest), when the consumer repo maintains hard rules.
 - `## What Changes` lists capability deltas **only**; no implementation steps.
 - `## Capabilities` table groups deltas by capability slug; cite spec paths.
 - Spec deltas use `## MODIFIED Requirements` heading (or `## REMOVED Requirements`); Each `### Requirement:` block carries `SHALL` statements and `#### Scenario:` Given/When/Then. Mirror existing capability voice.

package/presets/cursor/next/agents/task-analyst.md

@@ -50,6 +50,13 @@ Create or update files under `.ai.local/team/tasks/<slug>/`:
 ## Slug
 <slug>
 
+## Hard rules applied
+- <applicable preset/local rule> — <how applied>
+- N/A — <reason>   (list non-applicable hard rules explicitly)
+
+## Compliance impact
+None | Affected — <surfaces: PD / medical data / analytics / SSR cookies / error reporting / third-party scripts>
+
 ## Goal
 ...
 

package/presets/cursor/next/agents/task-router.md

@@ -101,6 +101,7 @@ Keep top-level `profile` and emit this top-level object in every new `pipeline.j
 - If prompt or `brief.md` contains `figma.com` on `feature` / `refactor` / `spike` / `spec-gen`, insert **mockup-reviewer** after **task-analyst** (when present) and before **solution-architect** and **feature-developer**. Set `model: "strong"` on that step. Do not add static `humanGates: ["after:mockup-reviewer"]` (FAIL-only hook exception). Never put `mockup-reviewer` in a `parallel: true` step (FAIL-only gate is serial).
 - Classify intent `mockup-review` **before** `ux-design` **before** `review-only`. A `figma.com` URL with review-not-implement language is `mockup-review` even without the word «макет», including when the user said «ревью UX». <!-- i18n-keep: E4 -->
 - If UI stack and (required-signal or advisory UI AC), instruct **task-analyst** to load skill `ux-design` (no new pipeline step; analyst default model, not `strong`). Required-signal: user asked UX, or AC require flows/states, or spec-gen page/feature.
+- If the resolved scope touches UI paths (`app/src/ui/**`, or the repo's component-catalog root) on `feature` / `refactor`, insert **mockup-reviewer** even **without** a `figma.com` URL — it reviews against the AC / `ux-design.md` instead of Figma. Pair it with a **`mockup-review.md`** terminal artifact requirement (the UI change is not complete without it) and, where the repo ships a component catalog, a catalog-test note on `build-verifier` (`component-catalog-gate`).
 - Skip **task-analyst** if AC/scope fully specified → document in `skipped`.
 - Add **solution-architect** for cross-layer / new public APIs — after analyst, before developer.
 - Add **api-contract-reviewer** for new/changed backend contracts — before developer.

package/presets/cursor/next/ai-local/rules-library/agent-artifacts-no-local-paths.md

@@ -6,7 +6,18 @@ glob: always
 
 When this rule applies, acknowledge: `Using .ai.local: agent-artifacts-no-local-paths(, …)*`.
 
-Committed agent artifacts leak into git history. Absolute host paths expose the developer machine layout even if the file is deleted in a later MR.
+Committed agent artifacts leak into git history. Absolute host paths (`/Users/<username>/…`) expose the developer machine layout even if the file is deleted in a later MR.
+
+## Scope (mandatory)
+
+Every agent-written file that may be committed, especially:
+
+- `.ai.local/team/tasks/<slug>/pipeline.json`
+- `.ai.local/team/tasks/<slug>/artifact-manifest.json` (`authoritativePaths`, `evidencePaths`, any path array)
+- `.ai.local/team/**` markdown (`brief.md`, `decomposition.md`, `implementation.md`, `review.md`, `validation-report.md`, …)
+- `.ai.local/team/active-task.json` and other team JSON
+
+Same ban for any other agent-authored committed path (`openspec/**`, `docs/**`).
 
 ## Forbidden
 
@@ -14,20 +25,42 @@ Do **not** write host-absolute paths, including:
 
 - `/Users/<username>/…` (macOS)
 - `/home/<username>/…` (Linux)
-- `C:\Users\<username>\…` and `C:/Users/<username>/…` (Windows)
-- Any other absolute checkout root.
+- `C:\Users\<username>\…` and `C:/Users/<username>\…` (Windows)
+- Any other absolute checkout root (`/Users/…/<workspace>/<repo>`, `~/…` expanded)
 
-Do **not** put those strings in `productionTarget.root`, `instructions[]`, summaries, or evidence lists.
+Do **not** put those strings in `instructions[]`, config values, summaries, or `authoritativePaths` / `evidencePaths`.
 
 ## Required instead
 
-- This repo: path from workspace root (`src/…`, `.ai.local/team/tasks/<slug>/pipeline.json`).
-- Task-local artifacts: basename is enough (`pipeline.json`, `brief.md`) when the file lives in the same task directory.
+- This repo: repo-relative path from the repo root (`app/src/…`, `.ai.local/team/tasks/<slug>/pipeline.json`).
+- Task-local artifacts: basename is enough (`pipeline.json`, `brief.md`) when the file lives in the same task directory — match `.ai.local/team/fixtures/artifact-manifest.example.json`.
 - Sibling / other repo: **repo name** + repo-relative path. Never the filesystem location of that checkout.
 
+```jsonc
+// ❌ BAD — a receipt in artifact-manifest.json leaking the host path
+{
+  "receipt": {
+    "evidencePaths": [
+      "/Users/<username>/<workspace>/other-repo/app/src/modules/health-tracking/"
+    ]
+  }
+}
+
+// ✅ GOOD — repo-relative; another repo is prefixed by its name
+{
+  "receipt": {
+    "evidencePaths": [
+      "other-repo:app/src/modules/health-tracking/"
+    ]
+  }
+}
+```
+
+Prose: `other-repo` `app/src/modules/health-tracking/` — not a `/Users/…` prefix.
+
 ## Gate before finishing a write
 
-After writing or editing a team artifact, scan the file (and any JSON you are about to write) for `/Users/`, `/home/`, `C:\Users`, `C:/Users`. If any match, rewrite to repo-relative **before** considering the step done.
+After writing or editing a team artifact, scan the file (and the JSON you are about to write) for `/Users/`, `/home/`, `C:\Users`, `C:/Users`. If any match, rewrite to repo-relative **before** considering the step done. Do not `git add` until clean.
 
 Deleting a leaked file later does **not** remove it from git history — prevention is the only fix.
 
@@ -35,4 +68,4 @@ Deleting a leaked file later does **not** remove it from git history — prevent
 
 - Repo-relative paths, `@/` aliases, URL paths (`/api/…`).
 - Public URLs (`https://…`, `figma.com/…`).
-- Ephemeral local logs that are **not** committed.
+- Ephemeral local logs that are **not** committed (e.g. `/tmp/….log`). Do not copy those absolute paths into committed artifacts; cite the command or a repo-relative copy instead.

package/presets/cursor/next/ai-local/rules-library/agent-pipeline-gates.md

@@ -0,0 +1,19 @@
+glob: always
+
+## Body
+
+# Agent pipeline gates (local overlay)
+
+These gates are **agent-enforced** (local rules; the preset hook/router is not edited). Treat them as MUST, not advisory. Acknowledge: `Using .ai.local: agent-pipeline-gates(, …)*`.
+
+## Gates
+
+- **UI scope** (`app/src/ui/**`): the pipeline MUST include `mockup-reviewer` — not only when a `figma.com` URL is present. A terminal `mockup-review.md` with verdict `PASS`/`PASS_WITH_NOTES` is required before the task is complete. Missing artifact = **blocked**, not a warning. (See `ui-change-review-gate`.)
+- **DTO/type scope**: `api-contract-reviewer` is blocking per `api-contract-source`.
+- **build-verifier**: when `storybook/**` or `app/src/ui/**` changed, run targeted storybook tests and require green **without** `--update`.
+- **code-reviewer**: (a) a behaviour change under `app/src/**` without a matching `docs/qa/**` or `*.cases.md` update → WARN (REQUEST_CHANGES when AC names the case); (b) a production behaviour change made to satisfy a test → **blocker**; (c) every review artifact states the reviewed revision (sha or `working tree @ <date>`).
+- **single writer**: do not rewrite a block shipped the same day without a new review artifact and an owner.
+
+## Why local, not preset
+
+The mechanical hook/router gate would live in the preset-managed hook + router, which `init` overwrites. Per project decision, all gate changes stay in `.ai.local` (agent-enforced).

package/presets/cursor/next/ai-local/rules-library/analytics-events.md

@@ -0,0 +1,18 @@
+globs: app/src/analytics/**/*.{ts,tsx},app/src/ui/**/*.{ts,tsx}
+
+## Body
+
+# Analytics / telemetry events (team conventions template)
+
+When emitting or changing an analytics/telemetry event, acknowledge: `Using .ai.local: analytics-events(, …)*`.
+
+Events go through one owned module per domain — not scattered `pushEvent` / `track` calls in components.
+
+## Rules
+
+- Event modules live under `app/src/analytics/events/<domain>/` and expose `logX(...)` functions wrapping the analytics client (`pushEvent` or repo equivalent); payload types live in a sibling `*.types.ts`.
+- Components emit events via a hook or store slice (`_complexSlices/Analytics` analog), not by importing the analytics client directly.
+- Respect the repo's gating flag (e.g. `NEXT_PUBLIC_*_ANALYTICS_DISABLED`) and the init in the app root; do not initialize adapters twice.
+- Deduplicate repeated events with the repo's cache idiom when it exists.
+- **Never** put PD, medical/record text, raw auth tokens, or full URL search params into a payload. See the security rule's compliance section.
+- Analytics is a side effect: cross-slice event emission belongs in listener middleware, not in a reducer (see `store-rtk`).

package/presets/cursor/next/ai-local/rules-library/api-contract-source.md

@@ -0,0 +1,14 @@
+globs: app/src/api/**/*.{ts,tsx},app/src/types/**/*.{ts,tsx},app/src/mocks/**/*.{ts,tsx}
+
+## Body
+
+# API contract source is mandatory (no invented DTOs)
+
+When changing DTOs, response types, mappers, or mocks, acknowledge: `Using .ai.local: api-contract-source(, …)*`.
+
+## Rules
+
+- Any new/changed DTO, response type, response mapper, or shared type **names its contract source** in the task brief: an OpenAPI path + schema (or the project's equivalent contract), or an explicit `no in-repo contract — capture is provisional` risk.
+- The API-contract reviewer is **blocking** when the contract source is a capture and the DTO is new/changed → emit `changes_requested`, not advisory notes.
+- Map only fields present in the contract source. Do not add a field that exists only in mockup copy or a guessed payload.
+- Watch nullability / object-vs-scalar: verify against the contract schema, not a single capture (a capture cannot show absent/empty cases).

package/presets/cursor/next/ai-local/rules-library/artifact-lifecycle.md

@@ -0,0 +1,17 @@
+glob: always
+
+## Body
+
+# Agent artifact lifecycle
+
+When writing team artifacts, acknowledge: `Using .ai.local: artifact-lifecycle(, …)*`.
+
+Task-folder artifacts (`.ai.local/team/tasks/<slug>/**`) are an **audit trail**, not a second source of truth. Durable knowledge (decisions, contracts, product behaviour) belongs in `docs/specs/**` or `openspec/**`.
+
+## Rules
+
+- `.ai.local/team/tasks/**` stays **tracked in git** by default; do not add a gitignore entry. Committing task artifacts is the human's choice at the commit step.
+- Keep artifacts **small**: no host paths (see `agent-artifacts-no-local-paths`), no raw diff dumps, no duplicate copies (`* (1).*`), no screenshots beyond intentional baselines.
+- **Never bulk-purge** committed artifacts to "clean up". Deleting does not remove git history. Prevention only.
+- Durable output (approved spec, ADR, contract, QA cases) is copied into `docs/specs/**` / `openspec/**`; the task folder is not the SoT.
+- Follow `commit-hygiene`: artifact/doc churn does not share a commit with `app/src/**`.

package/presets/cursor/next/ai-local/rules-library/code-style.md

@@ -0,0 +1,68 @@
+globs: app/src/**/*.{ts,tsx},app/__tests__/**/*.{ts,tsx}
+
+## Body
+
+# Code style (team conventions template)
+
+When editing TS/TSX, acknowledge: `Using .ai.local: code-style(, …)*`.
+
+The preset is generic. This repo has its own naming and file shapes — **open the nearest analog in the same layer and mirror it**. Where a preset example differs, this rule wins.
+
+## Reference analogs (mirror these)
+
+| Layer | Analog |
+|-------|--------|
+| UI page | `app/src/ui/pages/<Domain>/` |
+| UI component | `app/src/ui/components/<Name>/` |
+| Store slice | `app/src/store/slices/<Domain>/` |
+| API service | `app/src/api/services/<Service>/<Domain>/` |
+| Types | `app/src/types/<Entity>.types.ts` |
+| Unit tests | `app/__tests__/unit/<mirrored path>/` |
+
+## Naming
+
+- Domain types — `T` prefix: `TAnalysis`, `TUserProfile`. Transport/response types — `T…Response` (`TAnalysisResponse`).
+- Interfaces / props — `I` prefix: `interface IProps`, `IRootState`.
+- DTO → domain mappers — verb `format`: `formatAnalysis`, `formatBiomarkers`. Not `map…`.
+- Endpoint constants — `SCREAMING_SNAKE` + `_ENDPOINT` (`DOMAIN_ANALYSIS_ENDPOINT`); dynamic — `prepare…Endpoint`.
+- No `FC` / `React.FC` (see `no-react-fc`).
+
+## Components
+
+- `export const X = ({ ... }: IProps) => (...)`; no `FC`.
+- Styles: a sibling styles module; root export `Root`.
+- Local children in `./components/<Name>/`: `Name.tsx` + `styles.ts` (or `Name.styles.ts` when the parent already has a `styles.ts`) + optional `Name.data.ts` / `Name.utils.ts` / `Name.hooks.ts` + `index.ts`. **Strictly forbidden:** declaring a subcomponent in the same file as the parent — see `component-child-decomposition`.
+- Layout sizes of one component (skeleton `height` / `width` / `maxWidth`, one-off `px`) stay as literals in the JSX prop or in `styles.ts`. Do not hoist them into `SCREAMING_SNAKE` constants or a `*.data.ts`.
+- `*.data.ts` is for copy, labels, lookup maps, and values imported by another module. A file that only names pixels is overhead — delete it and inline.
+
+## API layer (`app/src/api/services/<Service>/<Domain>/`)
+
+- `<Domain>.apiMethods.ts` — `export const XxxApiMethods = { fetchX, createX, saveX, deleteX: async (...) => { … } }`.
+- `<Domain>.endpoints.ts` — path constants.
+- `<Domain>.responseTypes.ts` — `T…Response` (DTO).
+- `<Domain>.responseMappers.ts` — `formatXxx(data: T…Response): T…`.
+- `index.ts` — re-export the four above.
+- Cross-entity mappers — `_shared/<Entity>/<Entity>.responseMappers.ts`.
+- Outside the layer, import only from the `@/api` barrel.
+
+## Store (`app/src/store/slices/<Domain>/`)
+
+- Folder: `<Domain>.ts` (slice + thunks + selectors), `types.ts`, `utils.ts`, `index.ts` barrel.
+- Slice named `xxxSlice`, re-exported via the barrel; not a default export.
+- Thunks: `fetchX` / `createX` / `saveX` / `deleteX`; error typing via `rejectWithValue`.
+- Selectors: curried `xxxSelector = (args) => (state: IRootState) => …`; memoize derived values with `createSelector`.
+- Local `interface IRootState { <sliceName>: TState }` in the slice file; state shape typed in `types.ts`.
+- Errors: follow the existing slice pattern; do not rewrite the error model in a point task.
+- Domain comments — in the project language.
+
+## Types (`app/src/types`)
+
+- Project-language JSDoc; `[computed]` prefix on frontend-derived fields; `Xxx.types.ts` or a folder + barrel `index.ts`.
+
+## Tests
+
+- Mirrored path `app/__tests__/unit/<rel>`, `*.spec.ts(x)`; project-language `describe` / `it`.
+
+## Format
+
+- Prettier: no semicolons, single quotes, trailing commas, width 100. The linter enforces it — run the post-change gate.

package/presets/cursor/next/ai-local/rules-library/component-child-decomposition.md

@@ -0,0 +1,81 @@
+globs: app/src/**/*.{ts,tsx},storybook/stories/**/*.stories.tsx
+
+## Body
+
+# Component child decomposition (strict)
+
+When this rule applies, acknowledge: `Using .ai.local: component-child-decomposition(, …)*`.
+
+A subcomponent of a parent UI component **must** live in a dedicated `components/<Name>/` subfolder of the parent. Defining a subcomponent in the same file as the parent is a **forbidden** shortcut — it breaks the convention used by every other modal/card in the repo, makes the parent file mix orchestration with detail rendering, and prevents re-use of the child from sibling features.
+
+This is enforced by the file structure visible in the working tree. A reviewer or `code-reviewer` agent who finds a subcomponent declared alongside the parent's main export must request changes with reference to this rule.
+
+## File structure
+
+```
+Parent/
+├── Parent.tsx                 ← public export, thin composition only
+├── Parent.styles.ts           ← only styles used directly by Parent (Root, Title, layout shell, list)
+├── index.ts                   ← re-export of Parent
+└── components/
+    └── Child/
+        ├── Child.tsx          ← public export of the subcomponent
+        ├── Child.styles.ts    ← styles specific to the child (its own Card, Icon, Title, etc.)
+        ├── Child.utils.ts     ← OPTIONAL: pure helpers
+        ├── Child.data.ts      ← OPTIONAL: lookup maps / constants
+        └── index.ts           ← re-export of Child
+```
+
+- Child file name: `Child.tsx` (PascalCase, same as folder name). Styles: `Child.styles.ts` (prefixed with child name) to avoid collision when the parent also has a `styles.ts`.
+- Parent uses `import { Child } from './components/Child'` (or `./components/Child/index`); never imports from `../Child.tsx` or `../../Child`.
+- The child does not import from the parent's `styles.ts`. If both share a token, they each import it from the design-token source directly.
+- `Child.utils.ts` / `Child.data.ts` are optional and only added when there are real helpers/maps. Do not create empty files.
+
+## Subcomponents
+
+A **subcomponent** is any JSX `<X .../>` (a) the parent repeats, (b) the parent passes resolved props to (instead of letting the child compute them), or (c) that owns its own layout/typography/visual contract. Inline JSX like `<s.Icon><img/></s.Icon>` is a styled element, not a subcomponent.
+
+When the parent has more than one or two branches, several repeated JSX subtrees, or any non-trivial rendering block, that block **must** be extracted to a subcomponent in `./components/<Name>/`. The parent then becomes a thin switch — it owns the wiring, the wrapper, and the iteration that maps data into `<Child>` instances.
+
+## Forbidden
+
+```tsx
+// ❌ Parent file with a co-located subcomponent
+export const ItemsModal = () => (
+  <Modal>
+    {items.map((item) => (
+      <s.Card key={item.id}>
+        <s.Icon><s.IconImage src={...} /></s.Icon>
+        <s.Body><s.Title>{item.title}</s.Title>...</s.Body>
+      </s.Card>
+    ))}
+  </Modal>
+)
+
+// Declared in the same file — file structure is wrong
+const CardItem = ({ item }) => <s.Card>...</s.Card>
+```
+
+## Correct
+
+```tsx
+// ItemsModal/ItemsModal.tsx
+import { CardItem } from './components/CardItem'
+
+export const ItemsModal = () => (
+  <Modal>{items.map((i) => <CardItem key={i.id} item={i} />)}</Modal>
+)
+
+// ItemsModal/components/CardItem/CardItem.tsx
+import * as s from './CardItem.styles'
+
+export const CardItem = ({ item }: { item: TItem }) => <s.Card>...</s.Card>
+```
+
+## Why the rule is strict, not a preference
+
+- **Diffability:** a change to the child shows up in `components/Child/Child.tsx`, not as noise in the parent file.
+- **Reviewability:** the parent file stays short (~50 lines) and the reviewer reads orchestration without scrolling past detail rendering.
+- **Re-use:** the child can be imported by other stories, modals, or pages without copy-paste.
+- **Tests:** a child-only story (visual regression of the card alone) is possible without re-rendering the whole modal.
+- **Lint / IDE:** per-folder patterns scale better than 200-line parent files mixing styles + helpers + subcomponents + data.

package/presets/cursor/next/ai-local/rules-library/feature-flags-experiments.md

@@ -0,0 +1,15 @@
+globs: app/src/constants/**/*.{ts,tsx},app/src/ui/**/*.{ts,tsx}
+
+## Body
+
+# Feature flags & experiments (team conventions template)
+
+When gating UI/behaviour by a flag or A/B experiment, acknowledge: `Using .ai.local: feature-flags-experiments(, …)*`.
+
+## Rules
+
+- Local flags live in one module (e.g. `app/src/constants/localFeatureFlags.ts`) as `isFeature…Enabled`; remote experiments come from the experiments client (`@sh/experiments` analog).
+- Read a flag through the repo's access path — a store slice / provider / singleton mounted at the app root — not by scattering `process.env` checks or ad-hoc constants.
+- Experiment-gated routes are registered in the repo's allowlist (e.g. `EXPERIMENT_PAGES`); do not invent a parallel mechanism.
+- Experimental / legacy page variants are **non-canonical** — do not copy them as the reference for new work, and do not delete a flag without the paired spec / story / e2e sync (flag removal is a cross-cutting change).
+- A flag that flips layout or visual identity is still one purpose per component after the flag is removed — do not bake the flag into a universal branchy component (`react-ui`).