From 5416a8af7ad9d9bd4f106f67e245d6ff9088e3b5 Mon Sep 17 00:00:00 2001
From: "k.hiro1818" <k.hiro1818@gmail.com>
Date: Wed, 13 May 2026 21:51:22 +0000
Subject: [PATCH 1/2] docs: add accessibility rules and refine coding-style,
 testing, and AGENTS guidelines

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .claude/rules/accessibility.md | 44 ++++++++++++++++++++++++++++++++++
 .claude/rules/coding-style.md  |  2 +-
 .claude/rules/testing.md       | 11 +++++----
 AGENTS.md                      |  4 ++--
 4 files changed, 53 insertions(+), 8 deletions(-)
 create mode 100644 .claude/rules/accessibility.md

diff --git a/.claude/rules/accessibility.md b/.claude/rules/accessibility.md
new file mode 100644
index 000000000..a19441412
--- /dev/null
+++ b/.claude/rules/accessibility.md
@@ -0,0 +1,44 @@
+---
+description: Accessibility rules for UI components
+paths:
+  - 'src/**/*.svelte'
+  - 'src/lib/components/**'
+  - 'src/features/**/components/**'
+---
+
+# Accessibility
+
+## Tables
+
+Always declare header scope:
+
+```html
+<th scope="col">Grade</th>
+<th scope="row">abc001</th>
+```
+
+## Color
+
+Never use color as the sole indicator of meaning. Grade badges and status icons must
+include a visible text label or `aria-label` — screen readers and users with color
+vision differences depend on it.
+
+## Interactive Elements
+
+Every `<button>` and `<a>` must have an accessible name: visible text, `aria-label`,
+or `aria-labelledby`. Icon-only buttons require `aria-label`.
+
+## Dynamic Content
+
+When `{#if}` reveals a modal, dialog, or focus-trap region, move focus programmatically
+on open and restore it on close.
+
+## Flowbite Svelte
+
+Omitting `color` on `<Button>` applies the filled green default and may strip
+`aria-label` on icon-only variants — always verify in browser DevTools Accessibility panel.
+
+## Form Labels
+
+Every `<input>`, `<select>`, and `<textarea>` must have an associated `<label>` (via
+`for`/`id`) or `aria-label`. Placeholder text does not substitute for a label.
diff --git a/.claude/rules/coding-style.md b/.claude/rules/coding-style.md
index 43cb71b43..a2d240a75 100644
--- a/.claude/rules/coding-style.md
+++ b/.claude/rules/coding-style.md
@@ -32,7 +32,7 @@ Before writing logic, decide which layer it belongs to:
 - **Braces**: always for single-statement `if` blocks
 - **Catch blocks**: never silent; re-throw, log, or comment
 - **Plural aliases**: `type Items = Item[]` in signatures
-- **TSDoc**: every export; `@param`/`@returns` when non-obvious
+- **TSDoc**: add when behavior, constraints, or params are non-obvious; omit when names are self-explanatory (`getTaskById(id: string)` needs no `@param id` comment)
 
 ## Type Guards at API Boundaries
 
diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md
index 8533dcfc1..10b77dea0 100644
--- a/.claude/rules/testing.md
+++ b/.claude/rules/testing.md
@@ -15,6 +15,7 @@ paths:
 - **English only**: describe expected behavior (e.g., `'returns empty array when workbooks is empty'`)
 - **Test integrity**: never weaken assertions to make tests pass; fix implementation instead
 - **Unused imports**: signal missing tests, not dead code—add the test case first
+- **TDD exceptions**: skip test-first for exploratory spikes, type-only changes, and config files with no branching logic; write tests before implementation for all service/util/store code
 
 ## Test Types
 
@@ -122,11 +123,7 @@ Parameter types **must match** production signature — use domain types (`TaskG
 
 ## Coverage
 
-Target: 80% lines, 80% branches. Run `pnpm coverage`.
-
-## Test Files Ship with Code
-
-Never defer tests. For non-trivial logic without explicit test requirement, add them anyway.
+Cover meaningful boundaries: happy path, error cases, and edge cases specific to the domain (e.g. empty arrays, null, enum extremes). Run `pnpm coverage` to spot untested branches — treat low coverage as a signal to review, not a target to hit mechanically.
 
 ## Multiple Test Location Patterns
 
@@ -141,6 +138,10 @@ include: [
 ],
 ```
 
+## Test Files Ship with Code
+
+Never defer tests. For non-trivial logic without explicit test requirement, add them anyway.
+
 ## Mocking globalThis Properties
 
 Save and restore `globalThis` state to prevent test leaks:
diff --git a/AGENTS.md b/AGENTS.md
index c944564e2..8f9c26345 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,7 +8,7 @@ Always prefer simplicity over pathological correctness. YAGNI, KISS, DRY. No bac
 
 **When implementing:**
 
-1. Use `/writing-plans` to generate a phased plan (2–5-min tasks, lower risk → higher risk order). Store the plan at `docs/dev-notes/YYYY-MM-DD/{task-name-en}/plan.md`. Split into `phase-N.md` files when the plan exceeds 200 lines or has 5+ phases. Each plan must include: overview, design rationale, rejected alternatives, and a per-phase summary. Write plans in Japanese; source code comments in English. Verify each task before starting:
+1. Use `/writing-plans` to generate a phased plan (lower risk → higher risk order). Store the plan at `docs/dev-notes/YYYY-MM-DD/{task-name-en}/plan.md`. Split into `phase-N.md` files when the plan exceeds 200 lines or has 5+ phases. Each plan must include: overview, design rationale, rejected alternatives, and a per-phase summary. Write plans in Japanese; source code comments in English. Verify each task before starting:
    - Which layer? (prisma / server / zod / types / fixtures / services / utils / stores / routes / components) — split if 2+ layers
    - Single responsibility: one purpose per task
    - Existing util/service/type? Search before creating
@@ -17,7 +17,7 @@ Always prefer simplicity over pathological correctness. YAGNI, KISS, DRY. No bac
 3. Write tests first, then implement production code, then verify with `pnpm test:unit`
 4. Review critically after implementing: flag YAGNI violations, over-abstraction, missing tests
 5. After all phases complete (feature and refactor branches only — not hotfixes or dependency bumps): run a mandatory refactor cycle. Write to `plan.md`: novel lessons (implementation blockers, non-obvious patterns not already in rules) and remaining tasks. Discard `phase-N.md` files. Run `coderabbit review --plain`; write all findings of `critical` / `high` / `potential_issue` (medium) to a `## CodeRabbit Findings` section in `plan.md`. The user decides which to fix before opening a PR; do not fix any finding unilaterally. `nitpick` findings defer to PR CI.
-6. Run `/session-close` at the end of each session: updates plan checklist, proposes rule/skill additions, checks for bloat, and detects repeated instructions
+6. Run `/session-close` at the end of feature and refactor branches (not hotfixes, deps bumps, or single-session fixes): updates plan checklist, proposes rule/skill additions, checks for bloat, and detects repeated instructions
 
 **Plan Approval ≠ Implementation Start:** Generating a plan (`/writing-plans`) does NOT authorize implementation. Always:
 

From 65b23bda4ea37ea4f61e3dfe4e2b3fa0db3cef9f Mon Sep 17 00:00:00 2001
From: "k.hiro1818" <k.hiro1818@gmail.com>
Date: Wed, 13 May 2026 22:02:14 +0000
Subject: [PATCH 2/2] docs: correct Flowbite aria-label note and relax TSDoc
 requirement

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .claude/rules/accessibility.md | 5 +++--
 .claude/rules/coding-style.md  | 2 +-
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/.claude/rules/accessibility.md b/.claude/rules/accessibility.md
index a19441412..8d386c757 100644
--- a/.claude/rules/accessibility.md
+++ b/.claude/rules/accessibility.md
@@ -35,8 +35,9 @@ on open and restore it on close.
 
 ## Flowbite Svelte
 
-Omitting `color` on `<Button>` applies the filled green default and may strip
-`aria-label` on icon-only variants — always verify in browser DevTools Accessibility panel.
+Icon-only `<Button>` variants require an explicit `aria-label`; Flowbite Svelte does
+not generate one automatically. Omitting `color` only applies the `'primary'` default
+style — it has no effect on `aria-label`.
 
 ## Form Labels
 
diff --git a/.claude/rules/coding-style.md b/.claude/rules/coding-style.md
index a2d240a75..5cdd61a9a 100644
--- a/.claude/rules/coding-style.md
+++ b/.claude/rules/coding-style.md
@@ -53,7 +53,7 @@ Delete function only if: (1) zero callers, (2) replacement exists, (3) dependent
 
 - **Plans/dev-notes**: Japanese
 - **Code/commits/tests**: English
-- **TSDoc**: required on all exports
+- **TSDoc**: add when behavior, constraints, or params are non-obvious
 - **Code blocks**: specify language (`typescript`, `sql`, `bash`)
 
 ## Security