@hopla/claude-setup 1.17.1 → 2.1.1

package/hooks/tsc-check.js

@@ -7,6 +7,25 @@ import { execSync } from "child_process";
 import fs from "fs";
 import path from "path";
 
+const TS_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"];
+
+// Pulls every file_path the hook payload references. Covers Write/Edit (single
+// file_path) and MultiEdit (edits[]). Returns null when no payload was available
+// — callers treat null as "can't tell, run tsc to be safe".
+function extractFilePaths(payload) {
+    const input = payload?.tool_input;
+    if (!input) return null;
+    const collected = new Set();
+    if (typeof input.file_path === "string") collected.add(input.file_path);
+    if (typeof input.path === "string") collected.add(input.path);
+    if (Array.isArray(input.edits)) {
+        for (const edit of input.edits) {
+            if (edit && typeof edit.file_path === "string") collected.add(edit.file_path);
+        }
+    }
+    return collected.size > 0 ? [...collected] : null;
+}
+
 function resolveTscCommand(cwd) {
     const localBin = path.join(cwd, "node_modules", ".bin", "tsc");
     if (fs.existsSync(localBin)) return `"${localBin}"`;
@@ -16,10 +35,30 @@ function resolveTscCommand(cwd) {
 }
 
 async function main() {
-    // Drain stdin (hook contract) but we don't need the payload for tsc --noEmit
     const chunks = [];
     for await (const chunk of process.stdin) chunks.push(chunk);
 
+    let payload = null;
+    if (chunks.length > 0) {
+        try {
+            payload = JSON.parse(Buffer.concat(chunks).toString());
+        } catch {
+            // Malformed payload — fall through; treat as "can't tell"
+        }
+    }
+
+    // Filter: if every touched file is non-TS/JS, skip invoking tsc.
+    // When the payload is missing or unparseable we default to running tsc
+    // (safe behavior — matches the pre-filter implementation).
+    const touched = extractFilePaths(payload);
+    if (touched !== null) {
+        const hasCompilable = touched.some((f) => {
+            const ext = path.extname(f).toLowerCase();
+            return TS_EXTENSIONS.includes(ext);
+        });
+        if (!hasCompilable) process.exit(0);
+    }
+
     const cwd = process.cwd();
     const tsconfigPath = path.join(cwd, "tsconfig.json");
     if (!fs.existsSync(tsconfigPath)) {
@@ -31,14 +70,12 @@ async function main() {
 
     try {
         execSync(`${tsc} --noEmit`, { cwd, stdio: "pipe" });
-        // Compile clean — exit silently
         process.exit(0);
     } catch (err) {
         const output = (err.stdout || "").toString() + (err.stderr || "").toString();
         if (output.trim()) {
             process.stdout.write("TypeScript errors detected:\n" + output + "\n");
         }
-        // PostToolUse hooks cannot block; stdout is fed back to Claude
         process.exit(0);
     }
 }

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "@hopla/claude-setup",
-  "version": "1.17.1",
-  "description": "Hopla team agentic coding system for Claude Code",
+  "version": "2.1.1",
+  "description": "Agentic coding system for Claude Code — CLI for global rules + permissions (plugin available via /plugin marketplace add HOPLAtools/claude-setup)",
   "type": "module",
   "bin": {
-    "claude-setup": "cli.js",
     "hopla-claude-setup": "cli.js"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HOPLAtools/claude-setup.git"
+  },
+  "homepage": "https://github.com/HOPLAtools/claude-setup#readme",
+  "bugs": {
+    "url": "https://github.com/HOPLAtools/claude-setup/issues"
+  },
   "files": [
     "cli.js",
     "global-rules.md",
@@ -14,11 +21,14 @@
     "skills/",
     "agents/",
     "hooks/",
-    ".claude-plugin/"
+    ".claude-plugin/",
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
-    "prepublishOnly": "node scripts/check-versions.js",
-    "check-versions": "node scripts/check-versions.js"
+    "prepublishOnly": "node scripts/check-versions.js && npm test",
+    "check-versions": "node scripts/check-versions.js",
+    "test": "node --test tests/*.test.js tests/hooks/*.test.js"
   },
   "engines": {
     "node": ">=18"

package/skills/brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: "Design exploration and brainstorming before planning. Use when the user wants to explore options for a new feature, discuss approaches, design a solution, brainstorm ideas, or evaluate trade-offs. Trigger on: 'new feature', 'brainstorm', 'explore options', 'design', 'how should we', 'what approach', 'trade-offs', 'quiero agregar', 'diseñar', 'explorar opciones'. Do NOT use when the user already has a clear plan or is asking to execute existing work."
+description: "Design exploration and brainstorming before planning. Use when the user wants to explore options for a new feature, discuss approaches, design a solution, brainstorm ideas, or evaluate trade-offs. Trigger on: 'new feature', 'brainstorm', 'explore options', 'design', 'how should we', 'what approach', 'trade-offs'. Do NOT use when the user already has a clear plan or is asking to execute existing work."
 ---
 
 # Brainstorming: Design Exploration Before Planning
@@ -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/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: code-review
 description: "Technical code review on changed files. Use when the user says 'review code', 'code review', 'check my code', 'review changes', 'look for bugs', or 'audit code'. Also use after completing implementation when validation passes. Do NOT use for reviewing plans or documents — only code."
+triggers:
+  - "review (my |the |this )?code"
+  - "code review"
+  - "audit (my |the |this )?code"
+  - "look for bugs"
 allowed-tools: Read, Grep, Glob, Bash
 ---
 

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/debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: "Systematic debugging methodology for finding and fixing bugs. Use when encountering errors, bugs, failures, unexpected behavior, or when the user says 'bug', 'error', 'not working', 'failing', 'debug', 'fix', 'broken', 'falla', 'no funciona', 'error'. Do NOT use for planned feature work or refactoring — only for diagnosing and fixing unexpected problems."
+description: "Systematic debugging methodology for finding and fixing bugs. Use when encountering errors, bugs, failures, unexpected behavior, or when the user says 'bug', 'error', 'not working', 'failing', 'debug', 'fix', 'broken'. Do NOT use for planned feature work or refactoring — only for diagnosing and fixing unexpected problems."
 ---
 
 # Systematic Debugging

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).

package/skills/hook-audit/tests/fixtures/use-bad.ts.example

@@ -0,0 +1,53 @@
+// SYNTHETIC FIXTURE — triggers all 4 hook-audit rules.
+// Filename is *.example so TypeScript ignores it. This file is read as text by the hook-audit skill.
+
+import { useState, useRef } from 'react';
+
+// Rule D-1: module-level cache without companion inFlight map. BUG.
+const cache = new Map<string, FooResult>();
+
+type FooResult = { ok: boolean; value: string };
+
+export function useFooLookup(fooId: string) {
+  const [data, setData] = useState<FooResult | null>(null);
+  const [loading, setLoading] = useState(false);
+  const currentFooRef = useRef<string>(fooId);
+
+  async function load(id: string) {
+    setLoading(true);
+    currentFooRef.current = id;
+    try {
+      const cached = cache.get(id);
+      if (cached) {
+        setData(cached);
+        return;
+      }
+      const result = await fakeFetch(id);
+      cache.set(id, result);
+      if (currentFooRef.current === id) {
+        setData(result);
+      }
+    } catch (error: any) {
+      // Rule E-1: substring match — too permissive. BUG.
+      if (error.message.includes('imei')) {
+        setData({ ok: false, value: 'imei-error' });
+      }
+    } finally {
+      // Rule S-8: setLoading(false) inside stale-id guard. BUG.
+      if (currentFooRef.current === id) {
+        setLoading(false);
+      }
+    }
+  }
+
+  // Rule P-5: object literal return without useMemo. BUG.
+  return {
+    data,
+    loading,
+    load,
+  };
+}
+
+async function fakeFetch(id: string): Promise<FooResult> {
+  return { ok: true, value: id };
+}