feat(harness): enforce prop default docs

.atl/skills/_shared/component-contract.md

@@ -22,7 +22,9 @@ No extra component files unless a spec explicitly approves a composition split.
 - Use named component exports; avoid default component exports.
 - Reusable/systemic prop types live in `src/types`; component-local types stay component-specific.
 - `types.ts` imports `cva` and `VariantProps` from `class-variance-authority`; all CVA variants and `defaultVariants` live there.
-- Public props exposed in stories include Storybook JSDoc annotations: `@control type` and `@default value` when a default exists. Prose descriptions are optional unless the public API needs clarification.
+- Every public component prop declared through `types.ts` must have Storybook-facing JSDoc when it is story-exposed, including `@control type` where applicable.
+- Every public prop with a runtime default must document the same default with `@default value` in `types.ts`. Runtime defaults include CVA `defaultVariants`, hook/component destructuring defaults, alias/coalesced fallbacks, and boolean fallback chains such as `disabled ?? isDisabled ?? false`.
+- Run `node scripts/verify-prop-default-docs.mjs` before handoff; missing `@default` docs are a component contract violation. Prose descriptions are optional unless the public API needs clarification.
 - Hooks return explicit typed objects; never `any`.
 - No `Array<T>` when `T[]` is equivalent.
 - No non-null assertions, `@ts-ignore`, or `@ts-expect-error` without a documented reason.

.atl/skills/component-contributor/SKILL.md

@@ -118,6 +118,8 @@ Present a concise plan and wait for confirmation unless SDD delegation already a
 
 Implement files in this order: `types.ts` → hook → component → tests → stories → `index.ts`.
 
+After hook/component defaults are known, return to `types.ts` and verify every public prop with a runtime default has matching JSDoc `@default` metadata. Run `node scripts/verify-prop-default-docs.mjs` before handoff.
+
 Use `.atl/skills/_shared/component-contract.md` as the contract for each file. If a local mature component contradicts the shared contract, stop and ask whether to follow current code or update the contract.
 
 ### 4 — Explain decisions

.atl/skills/component-contributor/references/git-workflow.md

@@ -133,6 +133,7 @@ The pre-PR review must check:
 - 6-file architecture and file responsibilities
 - CVA placement and TypeScript conventions
 - Storybook docs/controls/actions conventions
+- Public prop JSDoc `@default` coverage matching runtime defaults (`node scripts/verify-prop-default-docs.mjs`)
 - Token usage and visual states
 - Accessibility, focus visibility, disabled behavior, and keyboard support
 - Tests and build evidence
@@ -166,6 +167,7 @@ A PR will be rejected WITHOUT detailed feedback if:
 | Hardcoded colors/spacing       | Must use design tokens from `theme.css` |
 | Missing tests                  | Unit tests AND story required           |
 | Missing story                  | Storybook is the source of truth        |
+| Missing prop default docs      | `types.ts` must match runtime defaults  |
 | Container/Presentational mixed | Logic in `.tsx` file                    |
 
 ---
@@ -179,6 +181,7 @@ A PR is ready to merge when:
 - [ ] No `any`, no `interface`
 - [ ] Tests in `.test.tsx` cover hook logic + component behavior
 - [ ] Story has args, controls, and description (NO play functions)
+- [ ] Public prop defaults are documented in `types.ts` and `node scripts/verify-prop-default-docs.mjs` passes
 - [ ] No hardcoded values — only design tokens
 - [ ] ARIA attributes present and correct
 - [ ] PR template fully filled

.atl/skills/component-contributor/references/stories.md

@@ -83,6 +83,7 @@ export const Default: Story = {
 - Does `meta.parameters.docs` avoid `description.component`?
 - Are examples aligned with the canonical component API and public docs style?
 - Does each story demonstrate one axis clearly?
+- Do public props in `types.ts` document runtime defaults with `@default`, matching hook/component defaults and CVA `defaultVariants`?
 
 ## Notes
 

.atl/skills/components-auditor/SKILL.md

@@ -40,6 +40,7 @@ Audit against `.atl/skills/_shared/component-contract.md`:
 
 - required 6-file pattern and no unapproved extra files;
 - TypeScript rules and public prop typing;
+- Public prop JSDoc/default parity: compare `types.ts` props against CVA `defaultVariants`, hook/component destructuring defaults, alias/coalesced fallbacks, and boolean fallback chains; fail missing or stale `@default` docs.
 - CVA placement and hook/component responsibilities;
 - token usage and Tailwind v4 custom fractional naming;
 - named export and type export pattern;
@@ -101,6 +102,7 @@ Verdict:
 - [SEVERITY] `file:line` — Problem: ... Expected: ... Found: ... Rule: ...
 
 ### Validation evidence
+- `node scripts/verify-prop-default-docs.mjs`: pass/fail/not run — reason
 - `{command}`: pass/fail/not run — reason
 ```
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -39,6 +39,7 @@ Closes #<!-- issue number -->
 - [ ] Accessibility contract from the spec was implemented or deviations are explained below.
 - [ ] Follows the 6-file pattern: `types.ts`, `use*.ts`, `Component.tsx`, `Component.test.tsx`, `Component.stories.tsx`, `index.ts`.
 - [ ] CVA variants live in `types.ts`; JSX component has no state, CVA calls, or business logic.
+- [ ] Public props with runtime defaults have matching `@default` JSDoc in `types.ts` (`node scripts/verify-prop-default-docs.mjs`).
 - [ ] Uses design tokens from `theme.css`; no hardcoded colors or arbitrary color utilities.
 - [ ] Storybook covers default, variants, documented states, edge cases, and dark mode when visually different.
 - [ ] Component audit result is PASS or accepted PASS WITH WARNINGS.

.github/workflows/storybook-build.yml

@@ -28,6 +28,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Verify prop default docs
+        run: node scripts/verify-prop-default-docs.mjs
+
       - name: Build Storybook
         run: pnpm storybook-build
 

.github/workflows/test.yml

@@ -32,5 +32,8 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Verify prop default docs
+        run: node scripts/verify-prop-default-docs.mjs
+
       - name: Run tests
         run: pnpm test

lefthook.yml

@@ -5,6 +5,8 @@ pre-commit:
       glob: "*.{ts,tsx,js,jsx,json,css}"
       run: pnpm exec biome check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}
       stage_fixed: true
+    prop-docs:
+      run: "node scripts/verify-prop-default-docs.mjs"
     typecheck:
       run: "pnpm exec tsc --noEmit"
 commit-msg:
@@ -15,4 +17,4 @@ pre-push:
   parallel: false
   commands:
     test:
-      run: "pnpm exec vitest run --run"
+      run: "pnpm exec vitest run --run"