docs(harness): document workflow gates

.atl/AGENTS.md

@@ -62,6 +62,7 @@ Components live in `src/components/{atoms|molecules|organisms}/{kebab-name}/` wi
 - For package-facing changes (package output, exports, generated declarations, peer ranges, React major upgrades, or CI/package distribution policy), require `pnpm run build`; require `pnpm run verify:package` when published output or consumer compatibility can change. Tests/Storybook alone are not enough for React major upgrades.
 - Generated declarations must not leak internal path aliases or CSS side-effect imports into the published `.d.ts` output
 - English only — code, comments, stories
+- Paired repository docs are bilingual: base `*.md` files are Spanish and matching `*.en.md` files are English. When editing docs under `docs/` or root README files, preserve that split, update both language variants when the content changes, and never replace the Spanish base file with English prose.
 - Commit messages must follow the commitlint-enforced Conventional Commit format: `<type>(<optional scope>): <description>`. PR titles should follow the same format for review consistency. Allowed types: `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test`. Use scopes for domains such as `a11y`, `tokens`, or `infra` instead of inventing custom types.
 
 ---

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

@@ -34,27 +34,29 @@ Load by intent:
 | Radix primitive | `.atl/skills/component-contributor/references/radix-patterns.md` |
 | `className` merging | `.atl/skills/component-contributor/references/tailwind-merge.md` |
 | Contributor PR workflow | `.atl/skills/component-contributor/references/git-workflow.md` |
-| Starting from a GitHub issue or board task | `.atl/skills/github-project-tasks/SKILL.md` — verify issue label `status:approved`, then run START WORK before implementation |
+| Starting from a GitHub issue or board task | `.atl/skills/github-project-tasks/SKILL.md` — verify issue label `status:approved` and assignee ownership, then run START WORK before implementation |
 
 ## Workflow
 
 Follow these phases in order. Do not skip gates because a component looks simple.
 
 **Non-negotiable approval gate:** implementation must not start under any circumstance unless the linked GitHub issue has the exact label `status:approved`. Chat approval, assumptions, offline mode, or a local copy of the spec do not satisfy this gate.
 
+**Non-negotiable assignee gate:** before reading the implementation spec in detail, planning, creating a branch/worktree, mutating GitHub, or writing code from a linked issue, verify current assignees. If the issue is assigned to someone other than the contributor/user, stop and tell the user they must get explicit permission before reassigning it.
+
 ### 0 — Contributor onboarding
 
 Only when working directly with a contributor: confirm they understand React + strict TypeScript, Tailwind v4 tokens, CVA, the 6-file pattern, Storybook as docs, and tests in `.test.tsx`. If not, teach briefly before proceeding.
 
 ### 1 — Approval gate, START WORK, then spec intake
 
-If implementation will proceed from a GitHub issue or Project board card, first verify that the linked issue has the exact label `status:approved`. If it is missing, stop and ask for maintainer/project lead approval; do not read the implementation spec in detail, plan, or code.
+If implementation will proceed from a GitHub issue or Project board card, first verify that the linked issue has the exact label `status:approved` and is not assigned to someone else. If the label is missing, stop and ask for maintainer/project lead approval; do not read the implementation spec in detail, plan, or code. If another assignee is present, stop before any action and tell the user they need explicit permission before reassigning the issue.
 
-After the label is present, load `.atl/skills/github-project-tasks/SKILL.md` and run **START WORK** before spec intake, planning, or coding: assign the issue to the contributor/user, move Project status to `In progress`, and record the planned branch/worktree. Offline/no-network mode may only skip GitHub mutations after evidence confirms the issue already has `status:approved`; it never bypasses the approval gate.
+After the label and assignee gates pass, load `.atl/skills/github-project-tasks/SKILL.md` and run **START WORK** before spec intake, planning, or coding: verify assignees, assign the issue to the contributor/user, move Project status to `In progress`, and record the planned branch/worktree. Offline/no-network mode may only skip GitHub mutations after evidence confirms the issue already has `status:approved` and is unassigned or assigned to the contributor/user; it never bypasses the approval or assignee gates.
 
 Then extract component name, tier, props, variants, states, accessibility behavior, reference URL, and design notes. If the spec lives in a GitHub issue, read issue comments too; validated specs may live there.
 
-Stop and ask when the issue label `status:approved` is missing or cannot be verified, START WORK cannot be completed, or required behavior, accessibility, states, or variants are missing. Do not invent public API and do not begin implementation.
+Stop and ask when the issue label `status:approved` is missing or cannot be verified, the issue is assigned to someone else without explicit reassignment permission, START WORK cannot be completed, or required behavior, accessibility, states, or variants are missing. Do not invent public API and do not begin implementation.
 
 ### 1.5 — Spec critique
 

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

@@ -20,7 +20,10 @@ Use this reference BEFORE writing or reviewing stories. Do not improvise Storybo
   - `## Description` — required for every component; describe what it does and when to use it.
   - `## Dependencies` — include only when the story/component uses other design-system components or external primitives; list each dependency and why it is used.
   - `## Usage Guide` — include only when usage is complex; explain composition, constraints, or non-obvious behavior.
-- Story-level docs must be written as a JSDoc block immediately above each `export const StoryName`; do **not** render documentation cards, panels, helper text blocks, or usage notes inside the story canvas.
+- Story-level docs must be written as a useful JSDoc block immediately above each `export const StoryName`; do **not** render documentation cards, panels, helper text blocks, or usage notes inside the story canvas.
+- Each story must earn its place: demonstrate a distinct state, variant axis, composition constraint, accessibility behavior, or integration context. Do not add stories that duplicate coverage already provided by controls, args, or another story.
+- Do **not** add a generic `DarkMode` story just to show the component in dark theme. Storybook already provides global dark/light switching via the toolbar.
+- A dedicated dark-mode story is allowed only when it demonstrates behavior the global theme toggle cannot express, such as local dark-scope rendering, portal theme inheritance, or a theme-specific bug/regression case. State that reason in the story JSDoc.
 - Story render functions and decorators are examples only: they may provide layout needed to demonstrate the component, but not narrative documentation UI.
 - `Default` story args must not override the component `defaultVariants`.
 - Interactive components must include `Disabled` and interaction-focused stories as appropriate.
@@ -59,7 +62,7 @@ export default meta;
 type Story = StoryObj<typeof Component>;
 
 /**
- * Shows the default component configuration using its default variants.
+ * Demonstrates the component with its built-in default variants so consumers can compare other stories against the baseline API.
  */
 export const Default: Story = {
   args: {
@@ -78,7 +81,9 @@ export const Default: Story = {
 - Is the component-level docs JSDoc block immediately above `const meta`?
 - Does the component-level JSDoc block include required `## Description`?
 - Are `## Dependencies` and `## Usage Guide` included only when applicable?
-- Does each story have a concise JSDoc block immediately above its `export const StoryName`?
+- Does each story JSDoc explain the scenario and why it matters instead of restating the story name or saying only "Shows the component"?
+- Is every story necessary, with no duplicate coverage that controls, args, the global dark-mode toolbar, or another story already provide?
+- Are generic theme-only `DarkMode` stories absent unless they document a local scope, portal inheritance, or regression case that the toolbar cannot express?
 - Are documentation cards, panels, helper text blocks, and usage notes absent from the story canvas?
 - Does `meta.parameters.docs` avoid `description.component`?
 - Are examples aligned with the canonical component API and public docs style?

.atl/skills/component-spec-proposer/SKILL.md

@@ -36,21 +36,23 @@ Do not implement the component. Your job is to turn a vague task into a validate
 | Accessibility contract is vague or missing   | Stop and ask; do not produce a ready-to-approve spec.                          |
 | Composite keyboard/focus behavior unclear    | Ask for the intended pattern before validation.                                |
 | Expected a11y tests are missing              | Add them before asking for approval.                                           |
+| Linked issue assigned to someone else       | Stop before GitHub writes or implementation handoff; tell the user they need explicit permission before reassigning or taking over the issue. |
 | User approves proposal                       | Add the validated spec to the issue, then leave implementation blocked until a maintainer/project lead adds the issue label `status:approved`. |
 | User requests changes                        | Revise the proposal and ask for validation again.                              |
 
 ## Execution Steps
 
-1. Read the GitHub issue, if provided: title, body, comments, assignees, and URL. If the rendered issue page does not expose the comment thread, fetch the issue comments via the GitHub API (`/repos/{owner}/{repo}/issues/{number}/comments`) or `gh api` before continuing.
-2. Fetch and study the reference URL. Extract behavior, states, accessibility, anatomy, and examples.
-3. Identify the semantic pattern: native element, Radix primitive, or WAI-ARIA/APG pattern. For composites, define roles, relationships, keyboard behavior, focus lifecycle, and announced states before proposing API details.
-4. Compare against project rules from `component-contributor`, especially Phase 1 requirements.
-5. Present a proposed spec using `references/spec-template.md` with concrete accessibility acceptance criteria and expected tests.
-6. Include an `Assumptions to validate` section for choices not explicit in the issue/reference, especially screen reader, focus, or keyboard decisions.
-7. Ask the user to approve, reject, or edit the proposal. Do not write to GitHub before approval.
-8. After approval, append or update a GitHub issue comment headed `## Validated component spec` using the approved spec.
-9. Locate the Project item for the issue only to confirm it exists; do not move Project Status to `In progress` from this skill.
-10. Report the issue URL, project item ID, approval state, and next command/action: wait for the `status:approved` issue label, then run START WORK via `github-project-tasks`, then start `component-contributor`.
+1. Read the GitHub issue metadata first, if provided: title, assignees, labels, and URL. Confirm the contributor/user before comparing assignees. If the issue is assigned to someone other than the contributor/user, stop before further workflow action or GitHub writes and tell the user they need explicit permission before reassigning or taking over the issue.
+2. Read the GitHub issue body and comments, if provided. If the rendered issue page does not expose the comment thread, fetch the issue comments via the GitHub API (`/repos/{owner}/{repo}/issues/{number}/comments`) or `gh api` before continuing.
+3. Fetch and study the reference URL. Extract behavior, states, accessibility, anatomy, and examples.
+4. Identify the semantic pattern: native element, Radix primitive, or WAI-ARIA/APG pattern. For composites, define roles, relationships, keyboard behavior, focus lifecycle, and announced states before proposing API details.
+5. Compare against project rules from `component-contributor`, especially Phase 1 requirements.
+6. Present a proposed spec using `references/spec-template.md` with concrete accessibility acceptance criteria and expected tests.
+7. Include an `Assumptions to validate` section for choices not explicit in the issue/reference, especially screen reader, focus, or keyboard decisions.
+8. Ask the user to approve, reject, or edit the proposal. Do not write to GitHub before approval.
+9. After approval, append or update a GitHub issue comment headed `## Validated component spec` using the approved spec.
+10. Locate the Project item for the issue only to confirm it exists; do not move Project Status to `In progress` from this skill.
+11. Report the issue URL, project item ID, approval state, and next command/action: wait for the `status:approved` issue label, then run START WORK via `github-project-tasks`, then start `component-contributor`.
 
 ## Output Contract
 
@@ -79,7 +81,7 @@ After approval and GitHub update, return:
 **Spec**: Added to issue as `Validated component spec`
 **Project setup**: {team/category present or missing setup}
 **Approval gate**: Waiting for issue label `status:approved`
-**Next**: After the issue has label `status:approved`, run START WORK via `github-project-tasks`, then run `component-contributor` for implementation.
+**Next**: After the issue has label `status:approved` and is unassigned or assigned to the contributor/user, run START WORK via `github-project-tasks`, then run `component-contributor` for implementation.
 ```
 
 ## References

.atl/skills/component-spec-proposer/references/github-project-update.md

@@ -20,7 +20,7 @@ item_id=$(gh project item-list 1 \
 ```
 
 Do not move Project Status to `In progress` from `component-spec-proposer`.
-That transition belongs to START WORK in `github-project-tasks`, after spec approval, after the linked issue has label `status:approved`, and immediately before implementation.
+That transition belongs to START WORK in `github-project-tasks`, after spec approval, after the linked issue has label `status:approved`, after assignee ownership is verified, and immediately before implementation. If the issue is assigned to someone else, stop and require explicit permission before reassignment/takeover.
 
 Add the approved spec to the issue:
 
@@ -32,4 +32,4 @@ gh issue comment NUMBER \
 
 If a previous `Validated component spec` comment exists, prefer editing it manually or with the GitHub API instead of adding duplicates.
 
-After writing the validated spec, report that the task is waiting for the issue label `status:approved`. Do not start `component-contributor` or move the Project item to `In progress` until that label is present.
+After writing the validated spec, report that the task is waiting for the issue label `status:approved` and assignee ownership verification. Do not start `component-contributor` or move the Project item to `In progress` until both gates pass.

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

@@ -52,6 +52,8 @@ Audit against `.atl/skills/_shared/component-contract.md`:
 Use the Storybook and testing references as the single source of truth. In particular:
 
 - story docs live in JSDoc above `const meta` and each story export;
+- each story JSDoc explains the scenario and why it matters, not just the story name;
+- story set is necessary and non-duplicative, including no generic theme-only `DarkMode` story when the global Storybook dark-mode toolbar covers the case;
 - `parameters.docs.description.component` is not used;
 - no manual `argTypes` unless a documented exception exists;
 - event args use `action(...)`;