@hopla/claude-setup 1.17.0 → 1.19.0

package/commands/plan-feature.md

@@ -90,7 +90,23 @@ Based on research, define:
 - **API surface enumeration (security/access control plans):** When the plan modifies access control, authorization, or data visibility, enumerate ALL API surfaces that serve the same data — REST endpoints, WebSocket handlers, Durable Object methods, and any other data paths. Each surface must be updated consistently. Add a task for each surface, not just the primary one.
 - **Role access matrix:** For features involving multiple user roles or multi-tenant access (admin, member, viewer, buyer, external user), define a matrix: what data does each role see? What endpoints does each role call? What filters apply per role?
 - **External integration buffer:** If the feature integrates an external API or third-party service, budget 2x the estimated time. Document: do we have working test credentials? Is the SDK tested in our runtime (Workers, Node, edge, etc.)? Are there known deprecations or version constraints?
-- **UI iteration budget:** For features with significant UI (new pages, complex forms, interactive grids), note that UI specifications are provisional — visual polish typically needs iteration on user feedback. Specify what "good enough for v1" looks like vs. future polish so scope creep is not classified as plan failure.
+- **UI iteration budget (MANDATORY when UI is detected):** If the feature touches a visible UI surface (see "UI detection heuristic" below), the plan's "Out of Scope" OR "Notes for Executing Agent" section MUST include the line `Expected UX iterations: N`, where N is an honest positive integer (default 2-4 for new components, 1-2 for tweaks to existing components). Do NOT write `0` — manual smoke surfaces 2-4 deviations on average for any plan that adds or modifies a label, panel, modal, or interactive flow. Plans that don't budget for this perceive routine UX feedback as scope creep. The original "what 'good enough for v1' looks like" guidance still applies — specify it alongside the iteration count.
+- **UI detection heuristic:** A feature touches UI when ANY of the following matches the user's request OR the files the plan will create/modify:
+  - **Vocabulary triggers:** `component`, `panel`, `modal`, `dialog`, `card`, `badge`, `banner`, `label`, `button`, `flow`, `screen`, `page`, `view`, `render`, `layout`, `status indicator`, `tooltip`, `wizard`, `form`, `grid`, `table` (when interactive), `icon`
+  - **File path triggers:** `src/components/`, `src/pages/`, `src/views/`, `src/modules/*/components/`, `src/screens/`, files ending in `.tsx`, `.jsx`, `.vue`, `.svelte`
+  - **Plan task triggers:** any task with Action `create | modify` whose File path matches the above
+  - When uncertain, err on inclusion: a 2-line UX iteration budget costs nothing; a missing one re-classifies normal feedback as scope creep.
+- **Domain Assumptions (MANDATORY when domain vocabulary is detected):** If the feature uses project-specific domain terms (see "Domain vocabulary detection heuristic" below), the plan MUST include a `## Domain Assumptions` subsection in the plan template — placed BEFORE `## Implementation Tasks` — listing each user-confirmable assumption as a bullet. Each bullet describes ONE inference the planner made about meaning, behavior, or business rule. The user confirms or corrects each bullet before implementation begins. This is distinct from `Verified Assumptions` (Phase 3, technical state) — Domain Assumptions cover semantic meaning that only the user can validate.
+- **Domain vocabulary detection heuristic:** A feature uses domain vocabulary when ANY of the following category-based triggers fires (the categories below are universal — examples vary by project):
+  - **Entity state semantics:** any term describing a state, condition, or status of an entity in the project's domain. Generic examples: `Active` / `Inactive`, `Pending` / `Approved` / `Rejected`, `Open` / `Closed`, `Available` / `Unavailable`. Project-specific examples come from the project's own vocabulary.
+  - **Lifecycle states:** `draft` / `published` / `archived`, `created` / `processed` / `completed`, `submitted` / `reviewed` / `accepted`. Any sequence of states an entity passes through over time.
+  - **Grades / tiers / quality levels:** `A` / `B` / `C` grading, `premium` / `standard` / `basic`, `hot` / `warm` / `cold`, condition tiers, severity levels. Any ordinal classification with semantic boundaries.
+  - **Roles / permissions / multi-tenant access:** `admin` / `member` / `viewer` / `owner`, internal vs external users, buyer vs seller. Anything where access or behavior depends on who the actor is.
+  - **Color-coded UI states with semantic meaning:** green=ok / amber=warning / red=error, or any project-specific color → state mapping. The mapping itself is a domain assumption.
+  - **Business rules:** "when X happens, then Y is forbidden / required / triggered". Any conditional behavior that encodes a policy decision rather than a technical constraint.
+  - **Project-specific vocabulary harvest:** read the project's root `AGENTS.md` (or `CLAUDE.md` as fallback). If a `Domain`, `Glossary`, `Vocabulary`, or similar section exists, harvest its terms. Any of those terms appearing in the user's request triggers the heuristic. **Fallback when no such section exists:** rely on the category-based triggers above.
+  - **Sentinel check:** if the planner wrote sentences in the plan that describe behavior using nouns or adjectives that are NOT in the user's verbatim request, those are inferred meanings — surface them as Domain Assumptions.
+  - When uncertain, err on inclusion: a `Domain Assumptions` subsection with 1-2 bullets is cheaper than a misaligned implementation surfaced during manual smoke.
 
 ## Phase 5: Generate the Plan
 
@@ -126,6 +142,33 @@ Key files the executing agent must read before starting:
 - `[path/to/file]` — [why it's relevant]
 - `[path/to/file]` — [why it's relevant]
 
+## Domain Assumptions (if applicable)
+
+> Include this section when the feature uses domain vocabulary (entity states, lifecycle, grades/tiers, roles, color-coded states, business rules, or any project-specific terms in the project's AGENTS.md or CLAUDE.md). **Skip entirely** (do not write "N/A") when no domain semantics are involved.
+
+Each bullet is a user-confirmable assumption the planner made about meaning, behavior, or business rule. The user MUST confirm or correct each bullet BEFORE execution begins.
+
+- [Assumption 1 — entity state: e.g., "An entity with `status='archived'` is excluded from active list queries — confirm."]
+- [Assumption 2 — derived/computed value: e.g., "The `expired` badge shows when `expiresAt < today` AND `status != 'archived'` — confirm formula."]
+- [Assumption 3 — grade / tier / business rule: e.g., "Tier B users have read access to the audit log but cannot export it — confirm boundary."]
+
+## Requirements Delta (if applicable)
+
+> Include this section when the feature **changes documented system behavior** — adds, modifies, or removes a user-visible capability or business rule. Pure refactors, performance fixes, and infrastructure changes can omit this section entirely (do NOT write "N/A"). The delta is consumed by `/hopla:archive` to fold the change into `.agents/specs/canonical/`. If the project does not yet maintain canonical specs, this section is still valuable as a structured summary for the executing agent and reviewers.
+>
+> When a corresponding `.agents/specs/<feature>.md` already includes a `## Requirements Delta` (created by the `brainstorm` skill), reference it here instead of duplicating: `See spec: .agents/specs/<feature>.md`.
+
+### ADDED Requirements
+- REQ-<DOMAIN>-<NNN>: <short title>
+  - Scenario: <name> — Given <state>, When <action>, Then <outcome>
+
+### MODIFIED Requirements
+- REQ-<DOMAIN>-<NNN>: <short title> (replaces previous version)
+  - <description of how the requirement changes>
+
+### REMOVED Requirements
+- REQ-<DOMAIN>-<NNN>: <short title> (deprecated — reason)
+
 ## Implementation Tasks
 
 > All fields are required. Use `N/A` if a field does not apply — never leave a field blank.
@@ -197,6 +240,8 @@ Scoring guide:
 [Any important context, warnings, or decisions made during planning that the executing agent needs to know]
 
 > **UI Styling Note:** UI styling specifications (colors, sizes, variants, labels, spacing) are `[provisional]` proposals — expect them to change once the user sees the implementation. Implement as specified but do not over-invest in pixel-perfect adherence; plan for iteration.
+>
+> **Expected UX iterations: N** — *(include this line when the feature touches a visible UI surface — component, panel, modal, label, card, dialog, button, or interactive flow; **omit entirely otherwise** — do not write "N/A")*. N is the honest number of visual iterations the planner expects on this feature during manual smoke. Forbidden: `0`. Default: `2-4` for new components, `1-2` for tweaks. The user should not classify iterations within this budget as scope creep.
 ```
 
 ---
@@ -217,7 +262,7 @@ Before saving the draft, review the plan against these criteria:
 
 - [ ] Every task has a specific file path (no vague "update the component")
 - [ ] Every task has: Action, File, Pattern, Details, Gotcha, Validate — no field left empty
-- [ ] Validation Checklist has **exact commands** from `CLAUDE.md` or `package.json` (not vague "run lint")
+- [ ] Validation Checklist has **exact commands** from `AGENTS.md` / `CLAUDE.md` or `package.json` (not vague "run lint")
 - [ ] The plan is complete enough that another agent can execute it without this conversation
 - [ ] No ambiguous requirements left unresolved
 - [ ] **Data audit complete:** All data sources audited per `.agents/guides/data-audit.md`, with all findings (null cases, value semantics, derived value propagation) documented in Context References and Gotchas
@@ -233,6 +278,9 @@ Before saving the draft, review the plan against these criteria:
 - [ ] **Likely follow-ups listed:** If the Out of Scope section has items, the Likely Follow-ups section is populated with naturally adjacent work the user may request
 - [ ] **API surface enumeration (if security/access plan):** All parallel API surfaces (REST, WebSocket, DO) that serve the same data are listed with a task for each
 - [ ] **N+1 query check:** For every task that writes database queries or API calls, verify: is any call inside a loop? Could it be batched? Are there duplicate existence checks before mutations?
+- [ ] **UX iteration budget declared:** If the feature touches UI per the Phase 4 heuristic, the plan includes `Expected UX iterations: N` (with N a positive integer ≥ 1) in Out of Scope or Notes for Executing Agent. If UI is NOT involved, the line is correctly absent (no `N/A`, no empty placeholder).
+- [ ] **Domain Assumptions surfaced:** If the feature uses domain vocabulary per the Phase 4 heuristic, the plan includes a `## Domain Assumptions` subsection BEFORE `## Implementation Tasks`, with each bullet phrased as a user-confirmable statement. If no domain vocabulary is involved, the section is correctly absent (no `N/A`, no empty placeholder).
+- [ ] **Requirements Delta declared (when behavior changes):** If the feature adds, modifies, or removes a user-visible capability or business rule, the plan includes a `## Requirements Delta` subsection with one or more of `### ADDED Requirements`, `### MODIFIED Requirements`, `### REMOVED Requirements`. If the change is a pure refactor/perf/infra fix with no behavior change, the section is correctly absent (no `N/A`, no empty placeholder). Requirement IDs follow the project's `REQ-<DOMAIN>-<NNN>` convention.
 
 ## Phase 7: Save Draft and Enter Review Loop
 

package/commands/system-review.md

@@ -22,7 +22,8 @@ ls .agents/system-reviews/
 
 Look for a file that matches the feature name derived from **$1** (the plan filename). If a matching review exists:
 - Skip Steps 1–6
-- Go directly to **Step 7** to archive the plan
+- Notify the user: "✅ A system review already exists at `.agents/system-reviews/[feature]-review.md`. If you haven't closed the lifecycle yet, run `/hopla:archive $1` to fold delta-specs into canonical specs and move the plan to `done/`."
+- Exit.
 
 If no matching review exists, continue with Step 1.
 
@@ -90,7 +91,7 @@ For each bug category in this implementation, check if the same category appeare
 
 ### Unresolved Improvements
 Cross-reference improvement suggestions from previous reviews. If a suggestion was made before and NOT yet applied:
-- Check if the suggested CLAUDE.md update was made
+- Check if the suggested AGENTS.md / CLAUDE.md update was made
 - Check if the suggested command update was made
 - Check if the suggested guide was created
 - List any improvements that were suggested 2+ reviews ago and are still pending
@@ -99,7 +100,7 @@ Cross-reference improvement suggestions from previous reviews. If a suggestion w
 
 Suggest specific actions based on patterns found:
 
-- **CLAUDE.md updates** — universal patterns or anti-patterns to document
+- **AGENTS.md updates** (or `CLAUDE.md` for legacy projects) — universal patterns or anti-patterns to document
 - **Plan command updates** — instructions that need clarification or missing steps
 - **Execute command updates** — steps to add to the execution checklist
 - **New commands** — manual processes repeated 3+ times that should be automated
@@ -136,13 +137,13 @@ root_cause: [unclear plan | missing context | missing validation | other]
 
 ### Pattern Compliance
 - [ ] Followed codebase architecture
-- [ ] Used patterns documented in CLAUDE.md
+- [ ] Used patterns documented in AGENTS.md / CLAUDE.md
 - [ ] Applied testing patterns correctly
 - [ ] Met validation requirements
 
 ### System Improvement Actions
 
-**Update CLAUDE.md:**
+**Update AGENTS.md (or CLAUDE.md for legacy projects):**
 - [ ] [specific addition or change]
 
 **Update Plan Command:**
@@ -175,20 +176,15 @@ After the analysis, use this to prioritize actions:
 
 | Pattern | Action |
 |---|---|
-| Issue happens across ALL features | Update CLAUDE.md |
+| Issue happens across ALL features | Update AGENTS.md (or CLAUDE.md) |
 | Issue happens for a CLASS of features | Update on-demand reference guide or command |
 | Same manual step done 3+ times | Create a new command |
 | Plan was ambiguous in the same spot twice | Update plan-feature command |
 | First time seeing this issue | Note it, don't over-engineer yet |
 
-## Step 7: Archive the Plan
+## Step 7: Suggest Next
 
-Move the completed plan to the archive folder:
+Do **not** move or delete any files. The lifecycle closure (moving the plan to `done/`, folding delta-specs into canonical specs, deleting the ephemeral code review) is the responsibility of `/hopla:archive`.
 
-```bash
-mkdir -p .agents/plans/done
-mv "$1" .agents/plans/done/
-```
-
-Then notify the user:
-> "✅ System review saved to `.agents/system-reviews/[feature]-review.md`. Plan archived to `.agents/plans/done/[plan-name].md` — the active plans folder is now clean."
+Notify the user:
+> "✅ System review saved to `.agents/system-reviews/[feature]-review.md`. To close the lifecycle of this plan, run `/hopla:archive $1` — it will fold any delta-specs into the canonical specs and move the plan to `done/`."

package/commands/validate.md

@@ -16,7 +16,7 @@ If a `.claude/commands/validate.md` exists at the project root, use the commands
 
 Execute levels **1–4** from `commands/guides/validation-pyramid.md` (same repo). Do not skip levels. Do not proceed if a level fails — fix it first.
 
-Use the exact commands from the project's `CLAUDE.md` "Development Commands" section. If a `.claude/commands/validate.md` exists at the project root, use the commands defined there instead.
+Use the exact commands from the project's `AGENTS.md` (or `CLAUDE.md` as fallback) "Development Commands" section. If a `.claude/commands/validate.md` exists at the project root, use the commands defined there instead.
 
 ## Step 3: Summary Report
 

package/hooks/session-prime.js

@@ -97,11 +97,19 @@ async function main() {
         }
     }
 
-    // CLAUDE.md excerpt — cut at a natural boundary, not a fixed line count
+    // Project rules excerpt — prefer canonical AGENTS.md; fall back to CLAUDE.md.
+    // Both paths reuse the same excerpt helper since the format is identical Markdown.
+    const agentsMdPath = path.join(process.cwd(), "AGENTS.md");
     const claudeMdPath = path.join(process.cwd(), "CLAUDE.md");
-    if (fs.existsSync(claudeMdPath)) {
-        const excerpt = excerptClaudeMd(fs.readFileSync(claudeMdPath, "utf8"));
-        lines.push(`Project rules (CLAUDE.md excerpt):\n${excerpt}`);
+    let rulesPath = null;
+    if (fs.existsSync(agentsMdPath)) {
+        rulesPath = { path: agentsMdPath, label: "AGENTS.md" };
+    } else if (fs.existsSync(claudeMdPath)) {
+        rulesPath = { path: claudeMdPath, label: "CLAUDE.md" };
+    }
+    if (rulesPath) {
+        const excerpt = excerptClaudeMd(fs.readFileSync(rulesPath.path, "utf8"));
+        lines.push(`Project rules (${rulesPath.label} excerpt):\n${excerpt}`);
     }
 
     // Auto-discover available skills

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hopla/claude-setup",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "Hopla team agentic coding system for Claude Code",
   "type": "module",
   "bin": {

package/skills/brainstorm/SKILL.md

@@ -14,7 +14,7 @@ Explore the problem space and arrive at a validated design BEFORE creating an im
 ## Process
 
 ### Step 1: Explore Context
-- Read the project's CLAUDE.md, README, and relevant source files
+- Read the project's AGENTS.md (or CLAUDE.md as fallback), README, and relevant source files
 - Understand the existing architecture, patterns, and conventions
 - Identify what already exists that relates to this feature
 - Check `.agents/plans/` for any related previous work
@@ -61,6 +61,20 @@ Which approach and why
 ## Design
 Conceptual design details
 
+## Requirements Delta
+> **Include only when the feature changes documented system behavior** — i.e. it adds, modifies, or removes a user-visible capability or business rule. Pure refactors, perf fixes, and infra changes can omit this section. The delta is consumed by `/hopla:archive` to fold the change into `.agents/specs/canonical/`.
+
+### ADDED Requirements
+- REQ-<DOMAIN>-<NNN>: <short title>
+  - Scenario: <name> — Given <state>, When <action>, Then <outcome>
+
+### MODIFIED Requirements
+- REQ-<DOMAIN>-<NNN>: <short title> (replaces previous version)
+  - <description of how the requirement changes>
+
+### REMOVED Requirements
+- REQ-<DOMAIN>-<NNN>: <short title> (deprecated — reason)
+
 ## Files Affected
 - List of files to create/modify
 
@@ -75,6 +89,8 @@ Conceptual design details
 Run `/hopla:plan-feature` to create the implementation plan from this design
 ```
 
+> **Requirement IDs:** use a stable convention like `REQ-<DOMAIN>-<NNN>` (e.g. `REQ-AUTH-002`). The domain prefix should match the canonical spec filename (`auth.md` → `REQ-AUTH-*`). When in doubt about IDs in a brand-new project, leave them as `REQ-AUTH-TBD` and pick numbers when the first canonical spec is created.
+
 ### Step 6: Review Loop
 Present the design document for user review.
 - Accept feedback using the `<? ... >` comment syntax

package/skills/code-review/checklist.md

@@ -35,7 +35,7 @@ Apply every category to every changed file. Severity guidance is in the parent `
 
 ## 5. Pattern Adherence
 
-- Follows project conventions from `CLAUDE.md`
+- Follows project conventions from `AGENTS.md` (or `CLAUDE.md` as fallback)
 - Consistent with existing codebase style
 
 ## 6. Route & Middleware Ordering

package/skills/execution-report/SKILL.md

@@ -39,7 +39,7 @@ Use the full structure documented in `report-structure.md` (same directory). It
 - Divergences from plan
 - Scope assessment
 - Skipped items
-- Technical patterns discovered (with ready-to-paste CLAUDE.md entry)
+- Technical patterns discovered (with ready-to-paste AGENTS.md / CLAUDE.md entry)
 - Recommendations
 
 Read `report-structure.md` before writing so every section is filled correctly.

package/skills/execution-report/report-structure.md

@@ -75,7 +75,7 @@ New gotchas, patterns, or conventions learned during this implementation that sh
 
 - **Pattern/Gotcha:** [description]
 - **Where it applies:** [what type of feature or context triggers this]
-- **Ready-to-paste CLAUDE.md entry:** [Write the EXACT text that should be added to the project's CLAUDE.md to prevent this gotcha in future features. Format it as a bullet point under the appropriate section. If it belongs in a guide instead, write the exact text for the guide. Do not write vague suggestions like "document this" — write the actual content so the system reviewer can apply it directly.]
+- **Ready-to-paste AGENTS.md / CLAUDE.md entry:** [Write the EXACT text that should be added to the project's AGENTS.md (or CLAUDE.md for legacy projects) to prevent this gotcha in future features. Format it as a bullet point under the appropriate section. If it belongs in a guide instead, write the exact text for the guide. Do not write vague suggestions like "document this" — write the actual content so the system reviewer can apply it directly.]
 
 If nothing new was discovered, write "No new patterns discovered."
 
@@ -85,4 +85,4 @@ Based on this implementation, what should change for next time?
 
 - Plan command improvements: [suggestions]
 - Execute command improvements: [suggestions]
-- CLAUDE.md additions: [suggestions]
+- AGENTS.md / CLAUDE.md additions: [suggestions]

package/skills/git/commit.md

@@ -47,14 +47,14 @@ Wait for explicit approval before running `git commit`.
 
 ## Step 5: Version Bump (if configured)
 
-Before committing, check the project's `CLAUDE.md` for a `## Versioning` section. If it exists:
+Before committing, check the project's `AGENTS.md` (or `CLAUDE.md` as fallback) for a `## Versioning` section. If it exists:
 
 1. Read the versioning configuration (command, trigger, files)
 2. Check if the **trigger condition** matches (e.g., specific branches, always, etc.)
 3. If it matches, run the version bump command
 4. Stage the version files alongside the other changes
 
-If no `## Versioning` section exists in the project's `CLAUDE.md`, skip this step entirely.
+If no `## Versioning` section exists in the project's `AGENTS.md` / `CLAUDE.md`, skip this step entirely.
 
 ## Step 6: Execute Commit
 

package/skills/git/pr.md

@@ -15,7 +15,7 @@ git diff --stat origin/$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>
 
 Read the following if they exist:
 - The plan file in `.agents/plans/` related to this feature
-- `CLAUDE.md` — for project context
+- `AGENTS.md` (or `CLAUDE.md` as fallback) — for project context
 
 ## Step 2: Determine Base Branch
 

package/skills/hook-audit/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: hook-audit
+description: "Static audit of new React hooks against documented bug-class catalog (memoization, stale-id guards, error-match strictness, cache+dedup integrity). Use after creating any file matching `src/hooks/use*.ts` and BEFORE commit. Trigger words: 'audit hook', 'check hook', 'hook review'. Auto-callable from execute skill's Level 1.5 gate."
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+> 🌐 **Language:** All user-facing output must match the user's language. Code, paths, and commands stay in English.
+
+Mechanical static audit of React hook files (`src/hooks/use*.ts`) against the four recurring bug classes catalogued in `checklist.md` (same directory). This skill is FAST (<5s per file) and structural — it does not interpret intent. For semantic / interpretive review, use `code-review` instead.
+
+**When to invoke:**
+- Right after creating or significantly modifying a `src/hooks/use*.ts` file
+- BEFORE committing the hook
+- Auto-callable from `commands/execute.md` Level 1.5 gate (companion plan: `plan-feature-04c-improvements.md`)
+
+## Step 1: Identify Target File(s)
+
+Two modes:
+
+1. **Single-file mode** — argument provided:
+   ```bash
+   /hopla:hook-audit src/hooks/useFoo.ts
+   ```
+   Treat the argument as a single path. If the file does not exist, exit with `File not found: <path>`.
+
+2. **Auto-detect mode** — no argument:
+   ```bash
+   git diff --name-only HEAD | grep -E '^src/hooks/use[A-Z][A-Za-z0-9_]*\.ts$'
+   ```
+   Collect the matching files. If the result is empty:
+   ```bash
+   git ls-files --others --exclude-standard | grep -E '^src/hooks/use[A-Z][A-Za-z0-9_]*\.ts$'
+   ```
+   to pick up new untracked hook files. If both are empty, exit cleanly with `No hook files to audit.`
+
+Scope is strict: only `src/hooks/use*.ts`. Files matching `src/lib/use*` or `electron/use*` are NOT audited (see Out of Scope in the plan).
+
+## Step 2: Load the Checklist
+
+Read `checklist.md` in this skill's directory. It documents each rule with:
+- Rule code (P-5 / S-8 / E-1 / D-1)
+- Severity
+- Detection pattern (regex or grep command)
+- Fix suggestion (with code example)
+- Canonical reference (file from consumer-project history)
+
+## Step 3: Apply Each Rule
+
+For each target file, run the detection command for every rule (see `checklist.md` for the exact commands). Collect findings.
+
+Detection commands must be portable across BSD grep (macOS) and GNU grep (Linux). Use `grep -E` for ERE syntax. Avoid GNU-only flags (`-P`, `-z`).
+
+Each finding records:
+- File path
+- Line number (use `grep -nE` to get line numbers)
+- Rule code
+- One-line description
+- Fix suggestion (from `checklist.md`)
+- Canonical reference
+
+## Step 4: Output Report
+
+Group findings by file. Format per finding:
+
+```
+[severity] [rule-code] file:line — description
+  Fix: suggestion
+  Reference: canonical-file.ts (commit-hash)
+```
+
+End with a one-line summary:
+```
+N issues found across M files. K rules clean.
+```
+
+If no issues found, exit with exactly:
+```
+Hook audit clean — 4 rules checked.
+```
+
+**Gate output budget:** When invoked from `execute.md` Level 1.5 gate, the report must be under 50 lines. If more than 5 issues per file, show a count + the top 3 findings with detail; collapse the rest as `+N more (same rule)`.
+
+## Step 5: Exit Code
+
+This skill is markdown — it does not exit directly. When the calling agent invokes the skill from `execute.md`'s gate (via Bash), the calling Bash invocation should:
+- Exit `0` when the summary line shows `Hook audit clean`
+- Exit `1` when any issues are reported
+
+The gate (defined in `plan-feature-04c-improvements.md`) decides whether to fail the commit or merely warn based on severity. This skill's job is to REPORT — not to enforce.
+
+## Example Output
+
+**Clean run** (0 issues):
+```
+$ /hopla:hook-audit src/hooks/useGradingDefinitions.ts
+Hook audit clean — 4 rules checked.
+```
+
+**3-issue run:**
+```
+$ /hopla:hook-audit src/hooks/useFooLookup.ts
+
+[high]   [P-5] src/hooks/useFooLookup.ts:142 — Hook returns object literal without useMemo
+  Fix: Wrap the return in useMemo({ ... }, [field1, field2, ...])
+  Reference: useGradingDefinitions.ts:123-127
+
+[high]   [S-8] src/hooks/useFooLookup.ts:88 — `setLoading(false)` inside stale-id guard
+  Fix: Move setLoading(false) out of `if (currentFooRef.current === foo)` block in the finally
+  Reference: useSickwLookup.ts (commit 228cd6a)
+
+[medium] [E-1] src/hooks/useFooLookup.ts:101 — Error matching uses substring `.includes('imei')`
+  Fix: Replace with exact match or anchored regex (`/^imei[: ]/`)
+  Reference: useImeiInOtherShipment.ts post-fix
+
+3 issues found across 1 file. 1 rule clean (D-1).
+```
+
+## Source Incidents
+
+This skill exists because the same four bug classes recurred across consumer projects. Each rule in `checklist.md` cites the canonical fixed sibling.
+
+| Occurrence | File | Rule(s) | Fix commit |
+|---|---|---|---|
+| 1 | PhoneTest `useSickwLookup` | S-8 | 228cd6a |
+| 2 | PhoneTest `useIfreeicloudLookup` | S-8 | 06cc692 |
+| 3 | ifreeicloud-library `useIfreeicloudLookup` (second pass) | P-5, S-8 | — |
+| 4 | 04c `useImeiInOtherShipment`, `useActiveShipment` | P-5, S-8, E-1 | 952cab1 |
+
+Recurrence count = motivation for a dedicated mechanical pre-flight skill, separate from the broader `code-review`.
+
+## Next Step
+
+After the audit, the calling agent (execute, or the user via slash command) should:
+- If clean: proceed to commit.
+- If issues found: fix per the suggestions, then re-run this skill until clean. For larger refactors, escalate to `code-review` for full semantic review.

package/skills/hook-audit/checklist.md

@@ -0,0 +1,210 @@
+# Hook Audit Checklist
+
+Four mechanical rules. Each rule has a portable detection command (BSD + GNU grep), a fix suggestion, and a canonical reference from consumer-project history.
+
+> **Maintainer note on canonical references:** The cited commit hashes and file names come from a specific consumer project (PhoneTest-Desktop-App). When this skill is used in other consumer projects, the references may not resolve locally — that's fine, they are documentation of the pattern's origin, not a hard dependency. Update them as patterns evolve (revisit when promoting to v2).
+
+---
+
+## Rule P-5 — Hook return must be memoized
+
+**Severity:** high
+
+**What it catches:** A hook function that ends with `return { ... };` (object literal) NOT wrapped in `useMemo`. Every render returns a new object, which invalidates downstream `useMemo` / `useEffect` deps that consume the hook's return, causing re-render storms and stale-closure bugs.
+
+**Scope filter (apply BEFORE flagging):** The rule applies only to the FINAL return statement of a function whose name starts with `use` and that calls React hooks (`useState`, `useRef`, `useMemo`, `useEffect`, etc.). Plain helper functions inside the same file (e.g. `async function fakeFetch(...)`) are NOT subject to this rule even if they return an object literal.
+
+**Detection (portable grep):**
+
+```bash
+# Step 1 — collect candidate `return { ... }` lines (heuristic; may include helpers)
+grep -nE 'return[[:space:]]*\{' "$FILE"
+```
+
+For each match, read the surrounding 20 lines and apply two filters:
+1. Is the enclosing function a React hook (named `useX`, uses React hooks)? If no → skip.
+2. Is the `return { ... }` block already inside a `useMemo(() => ({ ... }), [...])` wrapper? If yes → skip.
+
+Only flag matches that fail BOTH filters. The wrapper pattern looks like:
+
+```ts
+return useMemo(() => ({
+  field1,
+  field2,
+}), [field1, field2]);
+```
+
+If the `return { ... }` is NOT inside a `useMemo`, flag it.
+
+**Fix:**
+
+```ts
+// Before
+return {
+  foo,
+  bar,
+  doSomething,
+};
+
+// After
+return useMemo(() => ({
+  foo,
+  bar,
+  doSomething,
+}), [foo, bar, doSomething]);
+```
+
+Include every field used in the object literal in the dep array. Missing deps cause stale values.
+
+**Canonical reference:** `useGradingDefinitions.ts:123-127` (consumer projects). Look for the well-formed `return useMemo(() => ({ ... }), [...])` shape there as the model.
+
+---
+
+## Rule S-8 — `setLoading(false)` must not be gated by stale-id guard
+
+**Severity:** high
+
+**What it catches:** Inside a `finally` block, `setLoading(false)` is wrapped in an `if (currentXRef.current === X)` guard. The guard correctly prevents stale results from overwriting newer ones, but ALSO blocks `setLoading(false)` from running when the request is superseded — leaving the UI stuck in "loading" forever when the user rapidly switches inputs.
+
+**Detection (portable grep):**
+
+```bash
+# Find any line with `setLoading(false)` inside the file, then read 5 lines above to check for an `if (current*Ref.current === ...)` guard
+grep -nE 'setLoading\(false\)' "$FILE"
+```
+
+For each match, read 5–10 lines above and confirm whether the call is enclosed by:
+
+```ts
+if (currentSomethingRef.current === somethingId) {
+  // ... result handling ...
+  setLoading(false);  // BUG: blocked when request is superseded
+}
+```
+
+If the `setLoading(false)` is INSIDE the guard, flag it. If it's OUTSIDE the guard (i.e. after the closing brace), the file is clean for this rule.
+
+**Fix:**
+
+```ts
+// Before — bug: setLoading blocked when superseded
+} finally {
+  if (currentImeiRef.current === imei) {
+    setData(result);
+    setLoading(false);
+  }
+}
+
+// After — setLoading runs unconditionally; only data update is guarded
+} finally {
+  if (currentImeiRef.current === imei) {
+    setData(result);
+  }
+  setLoading(false);
+}
+```
+
+**Canonical reference:** `useSickwLookup.ts` after commit `228cd6a` (PhoneTest history). The fix moved `setLoading(false)` out of the guard.
+
+---
+
+## Rule E-1 — Error matching must be anchored, not substring
+
+**Severity:** medium
+
+**What it catches:** Error message detection that uses `.includes('imei')` or similar substring patterns. A substring match can fire on unrelated error messages that happen to contain the token (e.g. `"server error: imei lookup deferred"` would match an `imei`-specific error handler intended only for `"invalid imei format"`).
+
+**Detection (portable grep):**
+
+```bash
+grep -nE "\.message\??\.includes\([\"'][a-z]+[\"']\)" "$FILE"
+```
+
+This regex matches the antipattern `error.message.includes('foo')` (optional chaining tolerated). Each hit is a finding.
+
+**Fix:**
+
+```ts
+// Before — substring match (too permissive)
+if (error.message.includes('imei')) {
+  // ...
+}
+
+// After — anchored regex (precise)
+if (/^(invalid )?imei( format)?\b/i.test(error.message)) {
+  // ...
+}
+
+// Alternative — exact match if the message is a known constant
+if (error.message === 'Invalid IMEI') {
+  // ...
+}
+```
+
+**Canonical reference:** Consumer-project review checklist Section 1, pattern documented after the `useImeiInOtherShipment.ts` error-overshadow incident.
+
+---
+
+## Rule D-1 — Module-level cache must have in-flight dedup
+
+**Severity:** medium
+
+**What it catches:** A hook file declares a module-level `cache` Map for response caching but does NOT also declare an `inFlight` Map. Without dedup, two parallel calls for the same key race and produce duplicate network requests.
+
+**Detection (portable grep):**
+
+```bash
+# Find module-level `const cache = new Map`
+grep -nE '^const cache[[:space:]]*=[[:space:]]*new Map' "$FILE"
+```
+
+If the file matches, check for the companion `inFlight` map:
+
+```bash
+grep -nE '^const inFlight[[:space:]]*=[[:space:]]*new Map' "$FILE"
+```
+
+If `cache` is present but `inFlight` is absent, flag it. Both declarations must be at module scope (no leading whitespace).
+
+**Fix:**
+
+```ts
+// Both maps at module scope
+const cache = new Map<string, ResultShape>();
+const inFlight = new Map<string, Promise<ResultShape>>();
+
+async function fetchOnce(key: string): Promise<ResultShape> {
+  const cached = cache.get(key);
+  if (cached) return cached;
+
+  const inflight = inFlight.get(key);
+  if (inflight) return inflight;
+
+  const promise = doFetch(key).then((result) => {
+    cache.set(key, result);
+    inFlight.delete(key);
+    return result;
+  });
+  inFlight.set(key, promise);
+  return promise;
+}
+```
+
+The companion `inFlight` map ensures parallel calls for the same key share a single in-flight Promise instead of racing.
+
+**Canonical reference:** Consumer-project lookup hooks pattern (e.g. `useSickwLookup.ts` post-`228cd6a`).
+
+---
+
+## Portability Notes
+
+All detection commands use BRE/ERE syntax supported by both:
+- BSD grep (macOS default — `/usr/bin/grep`)
+- GNU grep (most Linux distributions)
+
+Avoid:
+- `-P` (Perl-compatible — GNU only)
+- `-z` (null-separated — GNU only)
+- Lookahead/lookbehind (`(?=...)`, `(?<=...)`)
+
+Use `grep -nE` for line numbers + ERE. Use `grep -E` instead of `egrep` (the latter is deprecated on some systems).