solid2-agent-kit 0.4.5 → 0.8.0

package/README.md

@@ -16,7 +16,12 @@ Supported agents: **Cursor** and **Claude Code**.
 | Always-applied hard rules | `.cursor/rules/solid-2.mdc` (glob-attached to `*.tsx`/`*.jsx`) | managed block in `CLAUDE.md` | 23 hard rules + banned Solid 1.x API table + eslint-plugin-solid lint-heritage table. Injected without the agent having to decide to read anything |
 | Agent skill | `.cursor/skills/solid-2/` | `.claude/skills/solid-2/` | Execution-model primer, decision tables, canonical patterns, a “still runs / write the other form” table, review checklist, official-doc URL index |
 | Shared agent context | managed block in `AGENTS.md` | same (Claude Code users can reference it from `CLAUDE.md`) | Core principles and pointers, always in context |
-| Mechanical gate | `solid2-kit check` | same | Whole-file regex guard over `src/**/*.{ts,tsx}`: fails on props destructuring (including multi-line signatures), `{ ...props }` rest copies, `{list().map(...)}` in JSX, React imports/hooks/JSX props/`React.lazy`/`useOptimistic`/`onDoubleClick`, Solid 1.x imports/APIs/components/JSX namespaces, `vite-plugin-solid`, old-router `<Route>`/`<A>`/`<HashRouter>`/`<FileRoutes>`, `MetaProvider`, `Context.Provider`, camelCase style keys, `key` props, `value()!` hand-narrowing, hand-rolled loading signals, `=== undefined` readiness branches, SolidStart leftovers (`@solidjs/start`, `h3`, `createAsync`, `useSubmission`, `"use client"`), Next.js imports/`useRouter`/`typeof window`, `history.pushState`, `render(<App />)` (pass a function), `isPending(user())` / `latest(user())` (pass the accessor), and `<Dynamic>` (use `dynamic()`) |
+| Mechanical gate | `solid2-kit check` | same | Comment-stripped regex guard over `src/**/*.{ts,tsx,jsx}` (or explicit `[files...]`): fails on props destructuring (including multi-line signatures), `{ ...props }` rest copies, `{list().map(...)}` in JSX, React imports/hooks/JSX props/`React.lazy`/`useOptimistic`/`onDoubleClick`, Solid 1.x imports/APIs/components/JSX namespaces, `vite-plugin-solid`, old-router `<Route>`/`<A>`/`<HashRouter>`/`<FileRoutes>`, `MetaProvider`, `Context.Provider`, camelCase style keys, `key` props, `value()!` hand-narrowing, hand-rolled loading signals, `=== undefined` readiness branches, SolidStart leftovers (`@solidjs/start`, `h3`, `createAsync`, `useSubmission`, `"use client"`), Next.js imports/`useRouter`/`typeof window`, `history.pushState`, `render(<App />)` (pass a function), `isPending(user())` / `latest(user())` (pass the accessor), `<Dynamic>` (use `dynamic()`), `import type { JSX } from "solid-js"` (no `JSX` namespace there — `Element` from `solid-js`, DOM `JSX` types from `@solidjs/web`), and two-phase effects whose apply only writes a local signal (use a writable derivation) |
+| Edit-time hook | `postToolUse` entry in `.cursor/hooks.json` | `PostToolUse` entry in `.claude/settings.json` (matcher includes `Bash`) | Runs the mechanical gate automatically on **every agent file edit — including edits made through shell commands** (sed, heredocs, codemods; source paths mentioned in the command are checked after it ran) — and feeds findings straight back into the conversation (Cursor: `additional_context`; Claude Code: stderr + exit 2), so enforcement does not depend on the agent remembering to run `check`. Wired only when the kit is a local devDependency; opt out with `--no-hooks` |
+| Turn-end gate | — | `Stop` entry in `.claude/settings.json` | Whole-project `check` + `doctor` when the agent tries to end its turn: with findings in place the stop is blocked (exit 2) and the findings are fed back, so a turn cannot finish with React/Solid 1.x patterns left behind. Loop-safe via `stop_hook_active` (one forced continuation, never an infinite loop) |
+| Pre-execution guard | `preToolUse` + `beforeShellExecution` entries in `.cursor/hooks.json` | `PreToolUse` entry in `.claude/settings.json` | Denies actions **before they run**: edits/deletes of kit-owned guardrail files (an agent blocked by a gate will try to remove the gate), edits that would strip the kit's hook entries or managed blocks, uninspectable shell rewrites of those files, and `npm/pnpm/yarn/bun install` of banned dependencies (`react`, `vite-plugin-solid`, `eslint-plugin-solid`, SolidStart, ...) — caught proactively instead of post-hoc by `doctor` |
+| Project-wiring gate | `solid2-kit doctor` | same | Config drift the source gate cannot see: React / `vite-plugin-solid` / `eslint-plugin-solid` / SolidStart deps in `package.json`, a 1.x `solid-js` range, `jsx` ≠ `preserve` or `jsxImportSource` ≠ `@solidjs/web` in tsconfig, Solid 1.x wiring in root config files, and stale installed guidance (kit updated but `sync` not re-run) |
+| Review command | `.cursor/commands/solid2-review.md` | `.claude/commands/solid2-review.md` | `/solid2-review` — on-demand deep review: runs both gates, then walks the diff against the skill checklist targeting the semantic failure classes regexes cannot see (post-`await` reads, effect misuse, unkeyed server rows, boundary placement, context snapshots) |
 
 Managed blocks are delimited with `<!-- solid2-agent-kit:*:start/end -->` markers; everything
 outside them is yours. Kit-owned files (`solid-2.mdc`, the skill directories) are overwritten
@@ -35,11 +40,16 @@ npx github:lightsound/solid2-agent-kit init
 npx github:lightsound/solid2-agent-kit init --cursor
 npx github:lightsound/solid2-agent-kit init --claude
 
-# run the mechanical pattern gate (default source dir: src)
+# run the mechanical pattern gate (default source dir: src; or name files)
 npx github:lightsound/solid2-agent-kit check
 npx github:lightsound/solid2-agent-kit check --dir app
+npx github:lightsound/solid2-agent-kit check src/App.tsx
 
-# pull in kit updates later (idempotent; replaces managed blocks and kit-owned files)
+# check the project wiring (deps, tsconfig, root configs)
+npx github:lightsound/solid2-agent-kit doctor
+
+# pull in kit updates later (idempotent; replaces managed blocks, kit-owned
+# files, and hook entries)
 npx github:lightsound/solid2-agent-kit sync
 ```
 
@@ -58,6 +68,71 @@ Update later with `bun update solid2-agent-kit` (or the npm/pnpm equivalent) fol
 `npx solid2-agent-kit sync`. Outside a project that has the kit installed, prefer the
 `npx github:...` form — it always tracks this repo directly.
 
+## Edit-time hooks (automatic enforcement)
+
+The rules and skill teach; `check` verifies — but only if someone runs it. The hook layer
+closes that gap: `init`/`sync` wire `solid2-kit hook` into both agents' hook systems, so the
+mechanical gate runs on **every file the agent edits** and violations come back as feedback
+the agent must act on, in the same turn it introduced them:
+
+- **Cursor** — a `postToolUse` entry in `.cursor/hooks.json`; findings are injected into the
+  conversation as `additional_context` right after the tool result.
+- **Claude Code** — a `PostToolUse` entry in `.claude/settings.json` (matcher
+  `Edit|MultiEdit|Write|Bash`); findings go to stderr with exit 2, which Claude Code feeds
+  back to the model as a correction prompt.
+
+Agents also edit files *through the shell* (sed, heredocs, `mv`, codemod scripts), which
+never hits the Edit/Write tools — so shell-shaped tool payloads are scanned for source
+paths mentioned in the command, and those files are checked after the command ran.
+
+Claude Code additionally gets a **turn-end gate**: a `Stop` hook re-runs the whole
+mechanical check (over `src`/`app`/`lib`) plus `doctor` when the agent tries to finish its
+turn, and blocks the stop while findings remain. `stop_hook_active` is honored, so an agent
+that cannot satisfy the gate is forced to continue exactly once, never looped forever.
+(Cursor's `stop` hook cannot feed back to the agent, so there the last line of defense is
+the always-attached rules plus CI.)
+
+Both agents also get a **pre-execution guard** (Claude: `PreToolUse`; Cursor: `preToolUse`
+and `beforeShellExecution`). A blocked agent's classic next move is to decide the gate
+itself is wrong — edit the rules file, delete the skill, or strip the hook entries. The
+guard denies, before the tool call runs: writes to kit-owned files (rules `.mdc`, skill
+directories, review commands, the kit under `node_modules`); edits to `.cursor/hooks.json`
+/ `.claude/settings.json` / `AGENTS.md` / `CLAUDE.md` that would remove the kit's entries
+or managed blocks (marker-preserving edits pass — agents can still add the user's own
+hooks and sections); shell rewrites of those files (`sed`/`rm`/redirects — uninspectable,
+so the deny message redirects to the Edit tool); and package-manager installs of
+dependencies `doctor` bans (exact token match, so `react` is denied but `react-aria` is
+not). The deny message always tells the agent what to do instead — fix the flagged code,
+run `solid2-kit sync`, or stop and ask the user. Pre-execution events never run the
+content check itself: fixing a currently-bad file is always allowed.
+
+When the kit is installed as a devDependency, `init` also wires a `lint:solid` script
+(`solid2-kit check && solid2-kit doctor`) into the project's `package.json` (only if the
+script does not already exist), so agents and CI can run both gates by name.
+
+The hook command is `node node_modules/solid2-agent-kit/bin/solid2-kit.mjs hook <agent>`,
+so it only works when the kit is installed as a devDependency (see above); `init` skips the
+wiring and prints a note otherwise. Merging is idempotent — kit entries are refreshed in
+place on `sync`, user entries are preserved. Opt out with `init --no-hooks`. Hooks never
+break the agent loop: clean edits, read tools, and malformed payloads exit silently, and
+reports are capped at 40 findings.
+
+Note on gate precision: `check` (and therefore the hooks) matches against
+**comment-stripped** source, so prose like `// migrated off createResource` never trips
+the gate, while string checks (`"use client"`) still work.
+
+## CI for consuming projects
+
+Run both gates on every PR so nothing an agent (or human) merges can reintroduce React or
+Solid 1.x patterns:
+
+```yaml
+- uses: actions/setup-node@v4
+  with: { node-version: 22 }
+- run: npm ci
+- run: npx solid2-agent-kit check && npx solid2-agent-kit doctor
+```
+
 ## Why not eslint-plugin-solid?
 
 `eslint-plugin-solid` was built for Solid 1.x. Its analyzer predates the Solid 2 model and
@@ -88,12 +163,13 @@ markdown with an `.md` suffix).
 ## Layout
 
 ```
-bin/solid2-kit.mjs                 CLI: init / sync / check
+bin/solid2-kit.mjs                 CLI: init / sync / check / doctor / hook
 files/shared/rules-body.md         hard rules (rendered into .mdc and CLAUDE.md)
 files/shared/agents-section.md     AGENTS.md managed-block content
 files/skills/solid-2/              SKILL.md + references/official-docs.md
+files/commands/solid2-review.md    /solid2-review command (Cursor + Claude Code)
 scripts/check-docs-drift.mjs       weekly docs cross-check
-tests/                             mechanical-gate fixtures (`npm test`)
+tests/                             check/doctor fixtures + hook and init-merge tests (`npm test`)
 ```
 
 ## Publishing (npm)

package/bin/solid2-kit.mjs

@@ -2,12 +2,15 @@
 // solid2-agent-kit CLI — installs and maintains Solid 2.0 guidance for AI
 // coding agents (Cursor and Claude Code), and runs a mechanical pattern gate.
 //
-//   solid2-kit init  [--cursor] [--claude] [--target <dir>]
-//   solid2-kit sync  [--cursor] [--claude] [--target <dir>]   (alias of init)
-//   solid2-kit check [--dir <srcdir>] [--target <dir>]
+//   solid2-kit init  [--cursor] [--claude] [--no-hooks] [--target <dir>]
+//   solid2-kit sync  [--cursor] [--claude] [--no-hooks] [--target <dir>]   (alias of init)
+//   solid2-kit check [--dir <srcdir>] [--target <dir>] [files...]
+//   solid2-kit doctor [--target <dir>]
+//   solid2-kit hook (claude|cursor)          (stdin: agent hook JSON payload)
 //
-// `init`/`sync` are idempotent: kit-owned files are overwritten and managed
-// blocks in AGENTS.md / CLAUDE.md are replaced in place.
+// `init`/`sync` are idempotent: kit-owned files are overwritten, managed
+// blocks in AGENTS.md / CLAUDE.md are replaced in place, and hook entries in
+// .cursor/hooks.json / .claude/settings.json are merged without duplicates.
 
 import {
   cpSync,
@@ -32,6 +35,20 @@ function flagValue(name, fallback) {
   return index === -1 || index + 1 >= args.length ? fallback : args[index + 1];
 }
 
+const VALUE_FLAGS = new Set(['--dir', '--target']);
+
+function positionalArgs() {
+  const out = [];
+  for (let i = 1; i < args.length; i += 1) {
+    if (args[i].startsWith('--')) {
+      if (VALUE_FLAGS.has(args[i])) i += 1;
+      continue;
+    }
+    out.push(args[i]);
+  }
+  return out;
+}
+
 // --- init / sync ------------------------------------------------------------
 
 function countOccurrences(haystack, needle) {
@@ -74,6 +91,104 @@ function writeKitOwnedFile(filePath, body) {
   return filePath;
 }
 
+// Hook commands run from the project root without node_modules/.bin on PATH,
+// so they invoke the locally installed kit through node directly. `init` only
+// wires hooks when that file exists (kit installed as a dependency).
+const KIT_LOCAL_BIN = 'node_modules/solid2-agent-kit/bin/solid2-kit.mjs';
+
+function readJsonConfig(filePath) {
+  if (!existsSync(filePath)) return {};
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    console.warn(
+      `solid2-kit — warning: ${filePath} is not valid JSON. File left untouched; fix it and re-run sync to wire the edit hook.`,
+    );
+    return null;
+  }
+}
+
+function writeJsonConfig(filePath, config) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(config, null, 2)}\n`);
+  return filePath;
+}
+
+// Replace the existing kit-owned entry (identified by the marker in its
+// command) or append a fresh one — sync then updates matchers/commands that
+// changed between kit versions while leaving user entries untouched.
+function upsertHookEntry(entries, marker, entry, matches) {
+  const index = entries.findIndex((existing) => matches(existing, marker));
+  if (index === -1) entries.push(entry);
+  else entries[index] = entry;
+}
+
+const cursorEntryMatches = (entry, marker) =>
+  typeof entry?.command === 'string' && entry.command.includes(marker);
+const claudeEntryMatches = (entry, marker) =>
+  (entry?.hooks ?? []).some((item) => typeof item?.command === 'string' && item.command.includes(marker));
+
+// Cursor hooks: postToolUse (post-edit check injected as additional_context)
+// plus preToolUse / beforeShellExecution (pre-execution guard: guardrail
+// tampering and banned-dependency installs are denied before they run).
+function upsertCursorHook(target) {
+  const filePath = join(target, '.cursor/hooks.json');
+  const config = readJsonConfig(filePath);
+  if (config === null) return null;
+  config.version ??= 1;
+  config.hooks ??= {};
+  const command = `node ${KIT_LOCAL_BIN} hook cursor`;
+  for (const event of ['postToolUse', 'preToolUse', 'beforeShellExecution']) {
+    upsertHookEntry((config.hooks[event] ??= []), 'solid2-kit.mjs hook cursor', { command }, cursorEntryMatches);
+  }
+  return writeJsonConfig(filePath, config);
+}
+
+// Claude Code hooks: PostToolUse (`hook claude` prints findings to stderr and
+// exits 2, which Claude Code feeds back into the model as correction context;
+// Bash is matched so shell edits via sed/heredocs are gated too), PreToolUse
+// (pre-execution guard, may deny) and Stop (whole-project final gate — the
+// agent cannot end its turn with findings).
+function upsertClaudeHook(target) {
+  const filePath = join(target, '.claude/settings.json');
+  const config = readJsonConfig(filePath);
+  if (config === null) return null;
+  config.hooks ??= {};
+  const command = `node ${KIT_LOCAL_BIN} hook claude`;
+  const toolMatcher = 'Edit|MultiEdit|Write|Bash';
+  upsertHookEntry(
+    (config.hooks.PreToolUse ??= []),
+    'solid2-kit.mjs hook claude',
+    { matcher: toolMatcher, hooks: [{ type: 'command', command, timeout: 30 }] },
+    claudeEntryMatches,
+  );
+  upsertHookEntry(
+    (config.hooks.PostToolUse ??= []),
+    'solid2-kit.mjs hook claude',
+    { matcher: toolMatcher, hooks: [{ type: 'command', command, timeout: 30 }] },
+    claudeEntryMatches,
+  );
+  upsertHookEntry(
+    (config.hooks.Stop ??= []),
+    'solid2-kit.mjs hook claude',
+    { hooks: [{ type: 'command', command, timeout: 60 }] },
+    claudeEntryMatches,
+  );
+  return writeJsonConfig(filePath, config);
+}
+
+// Wire a `lint:solid` script (referenced by the AGENTS.md guidance) into the
+// consuming project so agents and CI can run both gates by name.
+function upsertLintScript(target) {
+  const filePath = join(target, 'package.json');
+  if (!existsSync(filePath)) return null;
+  const pkg = readJsonConfig(filePath);
+  if (pkg === null) return null;
+  if (pkg.scripts?.['lint:solid']) return null;
+  (pkg.scripts ??= {})['lint:solid'] = 'solid2-kit check && solid2-kit doctor';
+  return writeJsonConfig(filePath, pkg);
+}
+
 function copySkill(targetSkillDir) {
   // The skill directory is kit-owned: remove it first so files deleted in
   // newer kit versions do not linger after a sync.
@@ -92,6 +207,7 @@ function init() {
 
   const rulesBody = readFileSync(join(KIT_ROOT, 'files/shared/rules-body.md'), 'utf8');
   const agentsSection = readFileSync(join(KIT_ROOT, 'files/shared/agents-section.md'), 'utf8');
+  const reviewCommand = readFileSync(join(KIT_ROOT, 'files/commands/solid2-review.md'), 'utf8');
   const written = [];
 
   if (wantCursor) {
@@ -109,10 +225,12 @@ function init() {
     ].join('\n');
     written.push(writeKitOwnedFile(join(target, '.cursor/rules/solid-2.mdc'), mdc));
     written.push(copySkill(join(target, '.cursor/skills/solid-2')));
+    written.push(writeKitOwnedFile(join(target, '.cursor/commands/solid2-review.md'), reviewCommand));
   }
 
   if (wantClaude) {
     written.push(copySkill(join(target, '.claude/skills/solid-2')));
+    written.push(writeKitOwnedFile(join(target, '.claude/commands/solid2-review.md'), reviewCommand));
     // Claude Code has no glob-attached rules mechanism; CLAUDE.md is always
     // loaded, so the full rules body lives there in a managed block.
     written.push(
@@ -134,12 +252,108 @@ function init() {
     ),
   );
 
+  // Edit-time hooks: run the mechanical gate automatically on every agent
+  // file edit, so enforcement does not depend on the agent remembering to
+  // run `solid2-kit check`.
+  let hooksNote = null;
+  if (!args.includes('--no-hooks')) {
+    if (existsSync(join(target, KIT_LOCAL_BIN))) {
+      if (wantCursor) written.push(upsertCursorHook(target));
+      if (wantClaude) written.push(upsertClaudeHook(target));
+      written.push(upsertLintScript(target));
+    } else {
+      hooksNote =
+        'edit-time hooks not wired: install the kit as a devDependency ("solid2-agent-kit": "github:lightsound/solid2-agent-kit") so `node node_modules/solid2-agent-kit/bin/solid2-kit.mjs` resolves, then re-run sync. Pass --no-hooks to silence this note.';
+    }
+  }
+
   console.log(`solid2-agent-kit v${VERSION} — installed for ${[wantCursor && 'Cursor', wantClaude && 'Claude Code'].filter(Boolean).join(' + ')}:`);
   for (const path of written.filter(Boolean)) console.log(`  ${relative(target, path) || '.'}`);
+  if (hooksNote) console.log(`  note: ${hooksNote}`);
 }
 
 // --- check ------------------------------------------------------------------
 
+// Balanced-scan helpers for the effect-sync check: regexes cannot pair the
+// parentheses of a createEffect(...) call, so scan (string-aware; comments
+// are already stripped) for the matching closer from an opening bracket.
+function scanBalanced(content, openIndex) {
+  let depth = 0;
+  let quote = null;
+  for (let i = openIndex; i < content.length; i += 1) {
+    const ch = content[i];
+    if (quote !== null) {
+      if (ch === '\\') i += 1;
+      else if (ch === quote) quote = null;
+    } else if (ch === "'" || ch === '"' || ch === '`') {
+      quote = ch;
+    } else if (ch === '(' || ch === '{' || ch === '[') {
+      depth += 1;
+    } else if (ch === ')' || ch === '}' || ch === ']') {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function splitTopLevelArgs(argsText) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let start = 0;
+  for (let i = 0; i < argsText.length; i += 1) {
+    const ch = argsText[i];
+    if (quote !== null) {
+      if (ch === '\\') i += 1;
+      else if (ch === quote) quote = null;
+    } else if (ch === "'" || ch === '"' || ch === '`') {
+      quote = ch;
+    } else if (ch === '(' || ch === '{' || ch === '[') {
+      depth += 1;
+    } else if (ch === ')' || ch === '}' || ch === ']') {
+      depth -= 1;
+    } else if (ch === ',' && depth === 0) {
+      parts.push(argsText.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(argsText.slice(start));
+  return parts;
+}
+
+// An apply phase that is nothing but one (optionally if-guarded) call to a
+// local signal setter is "a signal plus an effect that syncs it" — rule 4.
+// Restricting to setters declared via createSignal destructuring in the same
+// file keeps external set* functions (setDefaultOptions, setTimeout) out.
+function soleLocalSetterApply(apply, localSetters) {
+  const head = apply.match(
+    /^(?:async\s*)?(?:\([^()]*\)|[\w$]+)\s*=>\s*\{?\s*(?:if\s*\((?:[^()]|\([^()]*\))*\)\s*\{?\s*)?(set[A-Z][\w$]*)\s*\(/,
+  );
+  if (!head || !localSetters.has(head[1])) return false;
+  const close = scanBalanced(apply, head[0].length - 1);
+  if (close === -1) return false;
+  return /^[\s;}]*$/.test(apply.slice(close + 1));
+}
+
+const LOCAL_SETTER_DECL = /\[\s*[\w$]+\s*,\s*(set[A-Z][\w$]*)\s*\]\s*=\s*createSignal\b/g;
+
+function effectSyncFindings(content) {
+  const localSetters = new Set([...content.matchAll(LOCAL_SETTER_DECL)].map((m) => m[1]));
+  if (localSetters.size === 0) return [];
+  const matches = [];
+  for (const call of content.matchAll(/\bcreateEffect\s*(?:<[^>()]*>)?\s*\(/g)) {
+    const open = call.index + call[0].length - 1;
+    const close = scanBalanced(content, open);
+    if (close === -1) continue;
+    const args = splitTopLevelArgs(content.slice(open + 1, close));
+    if (args.length >= 2 && soleLocalSetterApply(args[1].trim(), localSetters)) {
+      matches.push({ index: call.index });
+    }
+  }
+  return matches;
+}
+
 const CHECKS = [
   {
     id: 'props-destructure-param',
@@ -164,6 +378,20 @@ const CHECKS = [
     message:
       'Solid 1.x import path. Stores/merge/omit come from "solid-js"; render/hydrate/Portal/Dynamic come from "@solidjs/web".',
   },
+  {
+    id: 'jsx-namespace-import',
+    pattern: /import\s+(?:type\s+)?\{[^}]*\bJSX\b[^}]*\}\s*from\s+['"]solid-js['"]/g,
+    message:
+      'Solid 2 does not export a `JSX` namespace from "solid-js" (TS2305). Children/return types are `Element` from "solid-js"; DOM-specific JSX types (JSX.IntrinsicElements, JSX.CSSProperties) come from "@solidjs/web".',
+  },
+  {
+    // A two-phase createEffect whose apply is nothing but one (optionally
+    // if-guarded) call to a setter declared via createSignal in this file.
+    id: 'effect-sync-signal',
+    find: effectSyncFindings,
+    message:
+      'Effect that only syncs a local signal — "state + effect" (rule 4). Derive the value instead; to reset state when another reactive value changes, use a writable derivation: createSignal(() => { source(); return initial; }).',
+  },
   {
     id: 'react-jsx-prop',
     pattern: /\b(?:className|htmlFor)=/g,
@@ -367,8 +595,59 @@ const CHECKS = [
   },
 ];
 
-// .ts / .tsx sources, excluding .d.ts declaration files.
-const SOURCE_FILE = /(?<!\.d)\.tsx?$/;
+// .ts / .tsx / .jsx sources, excluding .d.ts declaration files.
+const SOURCE_FILE = /(?<!\.d)\.(?:tsx?|jsx)$/;
+
+// Blank comment interiors (preserving newlines and offsets) so banned tokens
+// mentioned in comments ("migrated off createResource") do not trip the gate.
+// String and template contents are preserved — some checks match string
+// literals ("use client"). This is a heuristic scanner, not a JS lexer: a
+// regex literal containing escaped slashes or `//` in JSX text can blank the
+// remainder of that one line (false negatives only, never false positives).
+function stripComments(content) {
+  let out = '';
+  let state = 'code';
+  for (let i = 0; i < content.length; i += 1) {
+    const ch = content[i];
+    const next = content[i + 1];
+    if (state === 'code') {
+      if (ch === '/' && (next === '/' || next === '*')) {
+        state = next === '/' ? 'line' : 'block';
+        out += '  ';
+        i += 1;
+      } else {
+        if (ch === "'") state = 'single';
+        else if (ch === '"') state = 'double';
+        else if (ch === '`') state = 'template';
+        out += ch;
+      }
+    } else if (state === 'line') {
+      if (ch === '\n') state = 'code';
+      out += ch === '\n' ? ch : ' ';
+    } else if (state === 'block') {
+      if (ch === '*' && next === '/') {
+        state = 'code';
+        out += '  ';
+        i += 1;
+      } else {
+        out += ch === '\n' ? ch : ' ';
+      }
+    } else {
+      out += ch;
+      if (ch === '\\') {
+        out += next ?? '';
+        i += 1;
+      } else if (
+        (state === 'single' && ch === "'") ||
+        (state === 'double' && ch === '"') ||
+        (state === 'template' && ch === '`')
+      ) {
+        state = 'code';
+      }
+    }
+  }
+  return out;
+}
 
 function* walk(dir) {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -378,36 +657,435 @@ function* walk(dir) {
   }
 }
 
+// One formatted finding per pattern match: "path:line [id] message\n  > source".
+// Patterns run against comment-stripped content (same offsets); the quoted
+// source line comes from the original file.
+function fileFindings(file, relativeTo) {
+  const raw = readFileSync(file, 'utf8');
+  const content = stripComments(raw);
+  const lines = raw.split('\n');
+  const findings = [];
+  for (const rule of CHECKS) {
+    for (const match of rule.find ? rule.find(content) : content.matchAll(rule.pattern)) {
+      const lineNumber = content.slice(0, match.index).split('\n').length;
+      findings.push(
+        `${relative(relativeTo, file) || file}:${lineNumber} [${rule.id}] ${rule.message}\n  > ${lines[lineNumber - 1].trim()}`,
+      );
+    }
+  }
+  return findings;
+}
+
 function check() {
   const target = resolve(flagValue('--target', '.'));
-  const srcDir = resolve(target, flagValue('--dir', 'src'));
-  if (!existsSync(srcDir)) {
-    console.error(`solid2-kit check — source directory not found: ${srcDir} (use --dir)`);
-    process.exit(2);
+  const fileArgs = positionalArgs();
+
+  let files;
+  if (fileArgs.length > 0) {
+    // Explicit file mode (used by agent hooks): check only the named sources.
+    files = fileArgs.map((file) => resolve(target, file)).filter((file) => SOURCE_FILE.test(file));
+  } else {
+    const srcDir = resolve(target, flagValue('--dir', 'src'));
+    if (!existsSync(srcDir)) {
+      console.error(`solid2-kit check — source directory not found: ${srcDir} (use --dir)`);
+      process.exit(2);
+    }
+    files = [...walk(srcDir)];
   }
 
   let findings = 0;
-  let files = 0;
-  for (const file of walk(srcDir)) {
-    files += 1;
-    const content = readFileSync(file, 'utf8');
-    const lines = content.split('\n');
-    for (const rule of CHECKS) {
-      for (const match of content.matchAll(rule.pattern)) {
-        findings += 1;
-        const lineNumber = content.slice(0, match.index).split('\n').length;
-        console.error(
-          `${relative(target, file)}:${lineNumber} [${rule.id}] ${rule.message}\n  > ${lines[lineNumber - 1].trim()}`,
+  for (const file of files) {
+    for (const finding of fileFindings(file, target)) {
+      findings += 1;
+      console.error(finding);
+    }
+  }
+
+  if (findings > 0) {
+    console.error(`\nsolid2-kit check — ${findings} finding(s) in ${files.length} file(s).`);
+    process.exit(1);
+  }
+  console.log(`solid2-kit check — OK (${files.length} files scanned).`);
+}
+
+// --- hook -------------------------------------------------------------------
+// Edit-time gate wired by `init` into the agents' hook systems. Reads the
+// hook JSON payload from stdin, runs the mechanical checks on the edited
+// source files, and feeds findings back through each agent's channel:
+//   claude — Claude Code PostToolUse: findings on stderr + exit 2 (Claude
+//            sees the stderr and fixes; other exit codes are ignored). Also
+//            handles the Stop event as a whole-project final gate: exit 2
+//            blocks the agent from ending its turn with violations in place.
+//   cursor — Cursor postToolUse: findings as {"additional_context"} JSON on
+//            stdout (injected into the conversation after the tool result).
+// Both agents also edit files through shell commands (sed, heredocs, mv,
+// codemods), which never hit the Edit/Write tools — so shell-shaped tool
+// payloads are scanned for source paths mentioned in the command and those
+// files are checked after the command ran.
+// Hooks must never break the agent loop: malformed payloads exit 0 silently.
+
+const WRITE_TOOL = /write|edit|replace|apply|patch/i;
+const SHELL_TOOL = /shell|bash|terminal|command|exec/i;
+const MAX_REPORTED = 40;
+
+function formatReport(header, findings) {
+  const shown = findings.slice(0, MAX_REPORTED);
+  const more = findings.length - shown.length;
+  return `${header}\n\n${shown.join('\n')}${more > 0 ? `\n…and ${more} more finding(s).` : ''}`;
+}
+
+function isCheckableSource(path) {
+  return SOURCE_FILE.test(path) && !path.includes('\n') && !path.includes('node_modules');
+}
+
+function collectSourcePaths(value, found = new Set()) {
+  if (typeof value === 'string') {
+    if (isCheckableSource(value) && existsSync(value)) found.add(value);
+  } else if (Array.isArray(value)) {
+    for (const item of value) collectSourcePaths(item, found);
+  } else if (value && typeof value === 'object') {
+    for (const item of Object.values(value)) collectSourcePaths(item, found);
+  }
+  return found;
+}
+
+// Path-shaped tokens ending in a source extension, resolved against the
+// command's cwd. Existence filtering keeps false positives at zero.
+function collectCommandPaths(command, cwd, found = new Set()) {
+  if (typeof command !== 'string') return found;
+  for (const match of command.matchAll(/[^\s'"`;|&()<>=]+\.(?:tsx?|jsx)\b/g)) {
+    const token = match[0];
+    if (!isCheckableSource(token)) continue;
+    const path = resolve(cwd, token);
+    if (existsSync(path)) found.add(path);
+  }
+  return found;
+}
+
+// --- pre-execution guard (self-defense + proactive denial) -------------------
+// Agents that keep getting blocked by a gate tend to conclude the gate is
+// wrong and edit or delete it. Pre-execution hooks (Claude PreToolUse,
+// Cursor preToolUse / beforeShellExecution) can deny a tool call before it
+// runs, so this guard refuses:
+//   - edits/deletes of kit-owned guardrail files (rules, skill, commands,
+//     the kit itself under node_modules),
+//   - edits that would remove the kit's markers from hook configs or the
+//     AGENTS.md / CLAUDE.md managed blocks,
+//   - shell rewrites of those files (sed/rm/redirects — uninspectable),
+//   - installing dependencies doctor would flag anyway (react,
+//     vite-plugin-solid, eslint-plugin-solid, SolidStart, ...).
+// Everything else is allowed; this gate never inspects file *content* being
+// written (that is the post-edit hook's job).
+
+const GUARDRAIL_PATH =
+  /\.cursor\/rules\/solid-2\.mdc|(?:\.cursor|\.claude)\/skills\/solid-2|(?:\.cursor|\.claude)\/commands\/solid2-review\.md|node_modules\/solid2-agent-kit\//;
+const MARKER_FILE = /(?:\.claude\/settings\.json|\.cursor\/hooks\.json|AGENTS\.md|CLAUDE\.md)$/;
+const KIT_MARKER = 'solid2-agent-kit';
+const SHELL_WRITE = /\b(?:rm|mv|cp|sed|tee|truncate|unlink|chmod|perl|python[\d.]*)\b|>>?/;
+const INSTALL_CMD = /\b(?:npm|pnpm|yarn|bun)\s+(?:-\S+\s+)*(?:install|add|i)\b/;
+
+const TAMPER_MESSAGE =
+  'solid2-agent-kit guardrail: this file is kit-managed Solid 2.0 guidance/enforcement. Do not edit, weaken, or delete it — fix the flagged code instead. Kit files update via `solid2-kit sync`. If you believe the guardrail itself is wrong, or the user explicitly wants it removed, stop and tell the user.';
+
+function bannedInstall(command) {
+  if (!INSTALL_CMD.test(command)) return null;
+  for (const raw of command.split(/\s+/)) {
+    const token = raw.replace(/^['"]|['"]$/g, '');
+    const name = token.replace(/(?!^)@.*$/, '');
+    if (name in BANNED_DEPS) return name;
+  }
+  return null;
+}
+
+function preToolGate(agent, payload) {
+  const deny = (agentMessage) => {
+    if (agent === 'claude') {
+      console.error(agentMessage);
+      process.exit(2);
+    }
+    console.log(
+      JSON.stringify({
+        permission: 'deny',
+        agent_message: agentMessage,
+        user_message: 'solid2-agent-kit guardrail blocked this action.',
+      }),
+    );
+    process.exit(0);
+  };
+
+  let toolInput = payload.tool_input;
+  if (typeof toolInput === 'string') {
+    try {
+      toolInput = JSON.parse(toolInput);
+    } catch {
+      toolInput = undefined;
+    }
+  }
+  const toolName = typeof payload.tool_name === 'string' ? payload.tool_name : '';
+
+  // Shell commands: beforeShellExecution carries `command` at the top level,
+  // PreToolUse(Bash) inside tool_input.
+  const command =
+    typeof payload.command === 'string'
+      ? payload.command
+      : SHELL_TOOL.test(toolName) && typeof toolInput?.command === 'string'
+        ? toolInput.command
+        : null;
+  if (command !== null) {
+    const banned = bannedInstall(command);
+    if (banned) {
+      deny(
+        `solid2-agent-kit guardrail: do not install "${banned}". ${BANNED_DEPS[banned]} (\`solid2-kit doctor\` fails on it.)`,
+      );
+    }
+    if (SHELL_WRITE.test(command)) {
+      if (GUARDRAIL_PATH.test(command)) deny(TAMPER_MESSAGE);
+      if (/(?:\.claude\/settings\.json|\.cursor\/hooks\.json)/.test(command)) {
+        deny(
+          'solid2-agent-kit guardrail: rewriting hook configs through the shell cannot be verified. Use the Edit tool (keeping the solid2-agent-kit hook entries), or ask the user.',
         );
       }
     }
+    process.exit(0);
   }
 
-  if (findings > 0) {
-    console.error(`\nsolid2-kit check — ${findings} finding(s) in ${files} file(s).`);
+  if (!WRITE_TOOL.test(toolName)) process.exit(0);
+  const filePath = typeof toolInput?.file_path === 'string' ? toolInput.file_path : toolInput?.path;
+  if (typeof filePath !== 'string') process.exit(0);
+
+  if (GUARDRAIL_PATH.test(filePath)) deny(TAMPER_MESSAGE);
+
+  if (MARKER_FILE.test(filePath)) {
+    // Editing these files is fine (users add their own hooks/sections through
+    // agents) as long as the kit's entries/managed blocks survive the edit.
+    const removalMessage = `solid2-agent-kit guardrail: this edit removes the ${KIT_MARKER} entries/managed block from ${filePath}. Keep them intact; run \`solid2-kit sync\` to update them. If the user explicitly wants the kit removed, stop and tell the user to do it.`;
+    if (typeof toolInput.content === 'string') {
+      let existing = '';
+      try {
+        existing = readFileSync(resolve(typeof payload.cwd === 'string' ? payload.cwd : process.cwd(), filePath), 'utf8');
+      } catch {
+        // New file — nothing to preserve.
+      }
+      if (existing.includes(KIT_MARKER) && !toolInput.content.includes(KIT_MARKER)) deny(removalMessage);
+    } else if (
+      typeof toolInput.old_string === 'string' &&
+      toolInput.old_string.includes(KIT_MARKER) &&
+      !String(toolInput.new_string ?? '').includes(KIT_MARKER)
+    ) {
+      deny(removalMessage);
+    }
+  }
+
+  process.exit(0);
+}
+
+// Claude Code Stop hook: the per-edit hooks catch violations file by file,
+// but the agent can still end a turn with violations introduced through
+// uncovered paths (git operations, scripts writing files, moved code). The
+// Stop gate re-runs the whole mechanical check plus the wiring doctor and
+// refuses to let the turn end while findings remain. `stop_hook_active`
+// marks a turn that is already continuing because of this gate — allow it
+// through then, so an agent that cannot satisfy the gate never loops forever.
+function stopGate(payload) {
+  if (payload.stop_hook_active) process.exit(0);
+  const target = process.cwd();
+
+  const findings = [];
+  for (const dir of ['src', 'app', 'lib']) {
+    const abs = join(target, dir);
+    if (!existsSync(abs)) continue;
+    for (const file of walk(abs)) findings.push(...fileFindings(file, target));
+  }
+  if (existsSync(join(target, 'package.json'))) {
+    findings.push(...doctorFindings(target).map(({ id, message }) => `[${id}] ${message}`));
+  }
+  if (findings.length === 0) process.exit(0);
+
+  console.error(
+    formatReport(
+      'solid2-kit — React/Solid 1.x patterns are still in the project; fix them before finishing:',
+      findings,
+    ),
+  );
+  process.exit(2);
+}
+
+function hook(agent) {
+  if (agent !== 'claude' && agent !== 'cursor') {
+    console.error('solid2-kit hook — expected agent: claude | cursor');
+    process.exit(2);
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    process.exit(0);
+  }
+  if (!payload || typeof payload !== 'object') process.exit(0);
+
+  const event = typeof payload.hook_event_name === 'string' ? payload.hook_event_name : '';
+  if (agent === 'claude' && event === 'Stop') stopGate(payload);
+  // Pre-execution events (PreToolUse / preToolUse / beforeShellExecution)
+  // only run the guard — never the content check (the file has not been
+  // written yet, so checking would block edits based on pre-edit state).
+  if (/^(?:pre|before)/i.test(event)) preToolGate(agent, payload);
+
+  // afterFileEdit-style payloads carry file_path at the top level; tool-use
+  // payloads carry the edited path(s) inside tool_input. Only write-shaped
+  // and shell-shaped tools are gated, so reads/searches never are.
+  const files = new Set();
+  if (typeof payload.file_path === 'string') collectSourcePaths(payload.file_path, files);
+  if (payload.tool_input !== undefined) {
+    const toolName = typeof payload.tool_name === 'string' ? payload.tool_name : '';
+    let toolInput = payload.tool_input;
+    if (typeof toolInput === 'string') {
+      try {
+        toolInput = JSON.parse(toolInput);
+      } catch {
+        toolInput = undefined;
+      }
+    }
+    if (toolName === '' || WRITE_TOOL.test(toolName)) {
+      collectSourcePaths(toolInput, files);
+    } else if (SHELL_TOOL.test(toolName)) {
+      const cwd = typeof payload.cwd === 'string' ? payload.cwd : process.cwd();
+      collectCommandPaths(toolInput?.command, cwd, files);
+    }
+  }
+  if (files.size === 0) process.exit(0);
+
+  const findings = [];
+  for (const file of files) {
+    try {
+      findings.push(...fileFindings(file, process.cwd()));
+    } catch {
+      // File disappeared between the edit and the hook — nothing to check.
+    }
+  }
+  if (findings.length === 0) process.exit(0);
+
+  const report = formatReport(
+    'solid2-kit check — React/Solid 1.x patterns in this edit; fix them now:',
+    findings,
+  );
+  if (agent === 'claude') {
+    console.error(report);
+    process.exit(2);
+  }
+  console.log(JSON.stringify({ additional_context: report }));
+  process.exit(0);
+}
+
+// --- doctor -----------------------------------------------------------------
+// Project-config gate: `check` covers TSX sources, `doctor` covers the wiring
+// around them — dependencies, tsconfig, and root config files — where agents
+// also reach for React / Solid 1.x tooling (vite-plugin-solid,
+// eslint-plugin-solid, jsxImportSource: "solid-js", ...).
+
+const BANNED_DEPS = {
+  react: 'React does not belong in a Solid 2.0 project.',
+  'react-dom': 'React does not belong in a Solid 2.0 project.',
+  next: 'Next.js does not belong in a Solid 2.0 project.',
+  'vite-plugin-solid': 'Solid 1.x Vite plugin. Use @solidjs/vite-plugin.',
+  'eslint-plugin-solid':
+    'Built for Solid 1.x; its analyzer misreads Solid 2 idioms (two-phase createEffect, writable derivations, draft setters). Remove it — solid2-kit check carries the still-valid intents.',
+  '@solidjs/start': 'SolidStart 1.x. Solid 2 start mode lives in @solidjs/vite-plugin (start: true).',
+  'solid-start': 'SolidStart 0.x. Solid 2 start mode lives in @solidjs/vite-plugin (start: true).',
+  'solid-app-router': 'Pre-1.0 router. Use @solidjs/router 2 (createRouter({ routes })).',
+  vinxi: 'SolidStart 1.x toolchain. Solid 2 uses @solidjs/vite-plugin directly.',
+};
+
+const CONFIG_SOURCE = /\.(?:m|c)?[jt]s$/;
+
+// Files installed by this kit that carry a version marker. When the kit
+// dependency is updated but `sync` is not re-run, the installed guidance
+// keeps teaching agents the older content — silent drift doctor can catch.
+const GUIDANCE_FILES = ['.cursor/rules/solid-2.mdc', 'CLAUDE.md', 'AGENTS.md'];
+
+function doctorFindings(target) {
+  const findings = [];
+  const report = (id, message) => findings.push({ id, message });
+
+  const pkg = JSON.parse(readFileSync(join(target, 'package.json'), 'utf8'));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  for (const [name, message] of Object.entries(BANNED_DEPS)) {
+    if (name in deps) report(`dep-${name.replace(/[@/]/g, '')}`, `package.json depends on "${name}". ${message}`);
+  }
+  const solidRange = deps['solid-js'];
+  if (typeof solidRange === 'string' && /^[\s^~=v]*[01]\./.test(solidRange)) {
+    report('solid-js-version', `package.json pins solid-js "${solidRange}" — this kit teaches Solid 2.x; upgrade to ^2.`);
+  }
+
+  for (const entry of readdirSync(target, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const path = join(target, entry.name);
+
+    if (/^tsconfig.*\.json$/.test(entry.name)) {
+      // tsconfig is JSONC; extract the two relevant keys with regexes.
+      const content = readFileSync(path, 'utf8');
+      const jsx = content.match(/"jsx"\s*:\s*"([^"]+)"/)?.[1];
+      if (jsx && jsx !== 'preserve') {
+        report('tsconfig-jsx', `${entry.name} sets "jsx": "${jsx}". Solid 2 compiles its own JSX: use "preserve".`);
+      }
+      const importSource = content.match(/"jsxImportSource"\s*:\s*"([^"]+)"/)?.[1];
+      if (importSource && importSource !== '@solidjs/web') {
+        report(
+          'tsconfig-jsx-import-source',
+          `${entry.name} sets "jsxImportSource": "${importSource}". Solid 2 JSX types live in "@solidjs/web".`,
+        );
+      }
+      continue;
+    }
+
+    if (CONFIG_SOURCE.test(entry.name)) {
+      const content = readFileSync(path, 'utf8');
+      if (/['"]vite-plugin-solid['"]/.test(content)) {
+        report('config-vite-plugin-solid', `${entry.name} references vite-plugin-solid (Solid 1.x). Import solid from "@solidjs/vite-plugin".`);
+      }
+      if (/jsxImportSource['"]?\s*[:=]\s*['"](?:solid-js|react)['"]/.test(content)) {
+        report('config-jsx-import-source', `${entry.name} sets jsxImportSource to solid-js/react. Solid 2 uses "@solidjs/web".`);
+      }
+    }
+
+    if (/^(?:\.eslintrc|eslint\.config\.)/.test(entry.name)) {
+      const content = readFileSync(path, 'utf8');
+      if (content.includes('eslint-plugin-solid')) {
+        report('eslint-plugin-solid', `${entry.name} wires eslint-plugin-solid (Solid 1.x analyzer; false-positives on Solid 2 idioms). Remove it.`);
+      }
+    }
+  }
+
+  for (const guidance of GUIDANCE_FILES) {
+    const path = join(target, guidance);
+    if (!existsSync(path)) continue;
+    const installed = readFileSync(path, 'utf8').match(/solid2-agent-kit v(\d[\w.-]*)/)?.[1];
+    if (installed && installed !== VERSION) {
+      report(
+        'stale-guidance',
+        `${guidance} was installed by solid2-agent-kit v${installed} but v${VERSION} is running — run \`solid2-kit sync\` so agents read current guidance.`,
+      );
+    }
+  }
+
+  return findings;
+}
+
+function doctor() {
+  const target = resolve(flagValue('--target', '.'));
+  if (!existsSync(join(target, 'package.json'))) {
+    console.error(`solid2-kit doctor — no package.json at ${target} (use --target)`);
+    process.exit(2);
+  }
+
+  const findings = doctorFindings(target);
+  for (const { id, message } of findings) console.error(`[${id}] ${message}`);
+
+  if (findings.length > 0) {
+    console.error(`\nsolid2-kit doctor — ${findings.length} finding(s). Fix the project wiring above.`);
     process.exit(1);
   }
-  console.log(`solid2-kit check — OK (${files} files scanned).`);
+  console.log('solid2-kit doctor — OK (dependencies, tsconfig, root configs, and installed guidance look like Solid 2).');
 }
 
 // --- entry ------------------------------------------------------------------
@@ -420,15 +1098,23 @@ switch (command) {
   case 'check':
     check();
     break;
+  case 'doctor':
+    doctor();
+    break;
+  case 'hook':
+    hook(args[1]);
+    break;
   default:
     console.log(
       [
         `solid2-agent-kit v${VERSION}`,
         '',
         'Usage:',
-        '  solid2-kit init  [--cursor] [--claude] [--target <dir>]  install/update guidance (default: both tools)',
-        '  solid2-kit sync  [--cursor] [--claude] [--target <dir>]  alias of init (idempotent)',
-        '  solid2-kit check [--dir <srcdir>] [--target <dir>]       mechanical React/Solid 1.x pattern gate (default dir: src)',
+        '  solid2-kit init  [--cursor] [--claude] [--no-hooks] [--target <dir>]  install/update guidance + edit hooks (default: both tools)',
+        '  solid2-kit sync  [--cursor] [--claude] [--no-hooks] [--target <dir>]  alias of init (idempotent)',
+        '  solid2-kit check [--dir <srcdir>] [--target <dir>] [files...]         mechanical React/Solid 1.x pattern gate (default dir: src)',
+        '  solid2-kit doctor [--target <dir>]                                    project-wiring gate: deps, tsconfig, root configs',
+        '  solid2-kit hook (claude|cursor)                                       edit-time gate for agent hooks (stdin: hook JSON payload)',
       ].join('\n'),
     );
     process.exit(command ? 2 : 0);

package/files/commands/solid2-review.md

@@ -0,0 +1,30 @@
+Review the current change set for Solid 2.0 correctness. This project bans React patterns
+and Solid 1.x APIs; the mechanical gates catch tokens, but several failure classes are
+semantic and need your judgment.
+
+Steps:
+
+1. Run the gates and fix anything they report first:
+   - `node node_modules/solid2-agent-kit/bin/solid2-kit.mjs check`
+   - `node node_modules/solid2-agent-kit/bin/solid2-kit.mjs doctor`
+2. Read the `solid-2` skill (`.cursor/skills/solid-2/SKILL.md` or
+   `.claude/skills/solid-2/SKILL.md`) and its final review checklist.
+3. Collect the diff under review: staged/uncommitted changes if any, otherwise the branch
+   diff against the default branch.
+4. Review every changed `.tsx`/`.jsx`/`.ts` file against the checklist, prioritizing what
+   regexes cannot see:
+   - reactive reads at component-body top level, or extracted into plain `const`s;
+   - async computations reading reactive inputs **after** the first `await`;
+   - effects that copy state instead of deriving it, or reading stores in the apply phase;
+   - `<For>` over server/refetched rows without a stable-id key function;
+   - `<Loading>`/`<Errored>` wrapping page chrome instead of the data slot, or async memos
+     passed as values (`user={user()}`) instead of accessors;
+   - store updates that rebuild objects/arrays instead of mutating the draft or reconciling;
+   - context values passed as snapshots instead of accessors/setters/stores;
+   - components with conditional/early returns on reactive values.
+5. Verify any API you are not certain about against the official docs mirror
+   (`https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt`); never trust Solid 1.x or
+   React memory.
+
+Report each finding as `file:line — problem — Solid 2 replacement`, then fix them. Finish
+by re-running the gates and the project's typecheck.

package/files/shared/agents-section.md

@@ -2,5 +2,7 @@
 
 - All TSX in this project is Solid 2.0. Components run **once**; reactivity flows through signals/stores to JSX. React patterns (props destructuring, `className`, per-keystroke `onChange`, state-synced-by-effect, `.map()` lists) and Solid 1.x APIs (`createResource`, `onMount`, `solid-js/store`, `Suspense`, path setters) are bugs here.
 - Before writing TSX, read the `solid-2` skill (`.cursor/skills/solid-2/SKILL.md` for Cursor, `.claude/skills/solid-2/SKILL.md` for Claude Code): patterns, decision tables, official doc URLs. Hard rules auto-attach from `.cursor/rules/solid-2.mdc` in Cursor and live in a managed block in `CLAUDE.md` for Claude Code.
-- After editing TSX, run the `solid2-kit check` mechanical gate — it fails on React/Solid 1.x tokens and props destructuring. Use the project's `lint:solid` script if one exists; otherwise `npx solid2-agent-kit check` (with the kit as a devDependency) or `npx github:lightsound/solid2-agent-kit check`. Do not install `eslint-plugin-solid` (built for Solid 1.x; misreads Solid 2 idioms).
-- Solid 2.0 shipped recently and breaks with 1.x — never trust pre-2.0 Solid docs, tutorials, or training knowledge. Verify APIs against https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt (markdown mirror of https://v2.solidjs.com/, which blocks non-browser fetchers). If the project has `@solidjs/router`, server functions, or `@solidjs/meta`, use those official pages (see the skill's official-docs index) — not React Router, Next.js, SolidStart 1.x, or Solid Router 0.x/1.x JSX `<Route>`/`<A>`. Core `action` from `solid-js` is a generator transaction; router `action`/`query` from `@solidjs/router` are POST forms and a read cache. Core `refresh(source)`, router `revalidate(key)`, and server-function `return reload(...)` are three different APIs. Pass the accessor to `isPending(user)`, not `isPending(user())`. Pass a function to `render`/`hydrate`: `render(() => <App />, root)`. Component teardown is `onSettled`, not `onCleanup`. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`.
+- After editing TSX, run the `solid2-kit check` mechanical gate — it fails on React/Solid 1.x tokens and props destructuring. Use the project's `lint:solid` script if one exists; otherwise `npx solid2-agent-kit check` (with the kit as a devDependency) or `npx github:lightsound/solid2-agent-kit check`. An edit-time hook may also run this gate automatically after each file edit — treat its findings as errors to fix immediately, not warnings. Do not install `eslint-plugin-solid` (built for Solid 1.x; misreads Solid 2 idioms).
+- After editing `package.json`, `tsconfig*.json`, or root config files (Vite, ESLint), run `solid2-kit doctor` — it fails on React/Solid 1.x wiring: `react`/`vite-plugin-solid`/`eslint-plugin-solid`/SolidStart dependencies, 1.x `solid-js` ranges, and `jsx`/`jsxImportSource` values other than `preserve`/`@solidjs/web`.
+- The kit's guidance and gate files (`.cursor/rules/solid-2.mdc`, the `solid-2` skill directories, hook entries, managed blocks in this file and `CLAUDE.md`) are guardrails, not obstacles. Never edit, weaken, bypass, or delete them to make a failure go away — fix the flagged code. If a guardrail seems wrong, stop and tell the user.
+- Solid 2.0 shipped recently and breaks with 1.x — never trust pre-2.0 Solid docs, tutorials, or training knowledge. Verify APIs against https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt (markdown mirror of https://v2.solidjs.com/, which blocks non-browser fetchers). If the project has `@solidjs/router`, server functions, or `@solidjs/meta`, use those official pages (see the skill's official-docs index) — not React Router, Next.js, SolidStart 1.x, or Solid Router 0.x/1.x JSX `<Route>`/`<A>`. Core `action` from `solid-js` is a generator transaction; router `action`/`query` from `@solidjs/router` are POST forms and a read cache. Core `refresh(source)`, router `revalidate(key)`, and server-function `return reload(...)` are three different APIs. Pass the accessor to `isPending(user)`, not `isPending(user())`. Pass a function to `render`/`hydrate`: `render(() => <App />, root)`. Component teardown is `onSettled`, not `onCleanup`. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`. Types: `solid-js` exports no `JSX` namespace — children/return types are `Element` from `solid-js`; DOM `JSX` types come from `@solidjs/web`. Reset-a-signal-on-change is a writable derivation (`createSignal(() => { source(); return initial; })`), never an effect calling the setter. Client mode mounts with `render()` into an empty body — no hydration mismatch exists, so never defer initial values to post-mount React-style (that can overwrite persisted state).

package/files/shared/rules-body.md

@@ -25,7 +25,13 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
    (the function itself) into JSX and call it there.
 3. Signals are read by **calling** them: `{count()}` in JSX, not `{count}`.
 4. **Derived state is a function, not state + effect.** `const full = () => a() + b()`.
-   Never write "a signal plus an effect that syncs it". Use `createMemo` only for expensive
+   Never write "a signal plus an effect that syncs it". That includes **reset**: to clear
+   a signal when another reactive value changes, use a writable derivation —
+   `createSignal(() => { source(); return initial; })` (re-runs when `source()` changes;
+   the setter still works) — never a `createEffect` whose apply calls the setter. The
+   derivation also moves the `source()` read to the read site, under its boundaries.
+   Mechanically enforced by `solid2-kit check` (effects whose apply only writes a local
+   signal). Use `createMemo` only for expensive
    computations, multiple consumers, or an equality boundary. When several writes can land
    before a flush, use the setter updater (`setCount((c) => c + 1)`); `setCount(count() + 1)`
    reads the last *committed* value and drops the other staged writes. To store a *function*
@@ -165,7 +171,9 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     cross an async gap default to `action` + `createOptimistic`/`createOptimisticStore` —
     except reactive clients (e.g. Convex) whose subscriptions already push authoritative
     state after mutations. Compiler: `"jsxImportSource": "@solidjs/web"` (not `"solid-js"`);
-    Vite plugin is `@solidjs/vite-plugin` (not `vite-plugin-solid`). Server vs browser:
+    Vite plugin is `@solidjs/vite-plugin` (not `vite-plugin-solid`) — run `solid2-kit doctor`
+    after touching `package.json` / tsconfig / root configs; it fails on React and Solid 1.x
+    wiring. Server vs browser:
     `isServer` / `isDev` from `@solidjs/web`, or `clientOnly(() => import("./Widget"))` for
     browser-only components — never `typeof window` as the SSR boundary. Default
     `clientOnly` starts loading at declaration; `{ lazy: true }` defers until first
@@ -173,7 +181,12 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     visible content — `clientOnly` is for components that must never run on the server.
     Pass a **function** to `render` / `hydrate` / `renderToString` / `renderToStream`
     (`render(() => <App />, root)`), never `render(<App />, root)`. `hydrate` when the
-    container already holds SSR HTML; `render` for an empty mount. `renderToString`
+    container already holds SSR HTML; `render` for an empty mount. Client mode (the
+    `@solidjs/vite-plugin` default) mounts with `render()` into an empty body — there is
+    **no server HTML and no hydration mismatch**, so React's mismatch defenses
+    ("server-safe" initial values adopted after mount, two-pass rendering) are unnecessary
+    and can clobber persisted state; read `localStorage` / `matchMedia` directly when
+    creating the signal. `renderToString`
     emits `<Loading>` fallbacks; async or lazy-route trees need
     `await renderToStream(() => <App />)` (one consumer: `pipe` / `pipeTo` / `readable`).
     When the app owns the document, emit `<HydrationScript />` once before app markup;
@@ -254,6 +267,7 @@ directory (default `src/`).
 | Never write (Solid 1.x) | Write instead (Solid 2) |
 |---|---|
 | `import ... from "solid-js/store"` or `"solid-js/web"` | stores/`merge`/`omit` from `"solid-js"`; `render`/`hydrate`/`Portal`/`Dynamic` from `"@solidjs/web"` |
+| `import type { JSX } from "solid-js"` / `JSX.Element` as the children type | `solid-js` exports no `JSX` namespace: children/returns are `Element` from `"solid-js"`; DOM-specific `JSX` types (`JSX.IntrinsicElements`, `JSX.CSSProperties`) from `"@solidjs/web"` |
 | `createResource` | async `createMemo` + `<Loading>`/`<Errored>`; `refresh()`, `latest()`, `isPending()` |
 | `createEffect(fn)` (one arg), `on(...)` | `createEffect(compute, apply)`; deps belong in `compute` |
 | `onMount` | `onSettled` (return cleanup from its callback) |

package/files/skills/solid-2/SKILL.md

@@ -55,6 +55,7 @@ Most React `useEffect` code should NOT become `createEffect`:
 | Fetch data in an effect, copy into state | `createMemo(async () => ...)` + `<Loading>` |
 | React to a user interaction | do the work in the event handler or an `action` |
 | Sync one state into another | delete the second state; derive it |
+| Reset/clear state when another reactive value changes | writable derivation: `createSignal(() => { source(); return initial; })` — not an effect calling the setter |
 | Push a settled reactive value into a non-Solid system (DOM API, third-party widget, analytics, subscription) | `createEffect(compute, apply)` — this is the only real use |
 | One-time setup after mount (`onMount`) | `onSettled(() => { ...; return cleanup })` |
 | Measure DOM / observe size after paint | ref **directive factory** + `onSettled` (writes a *new* input; not an effect that copies state) |
@@ -222,6 +223,28 @@ Reads inside `apply` do not track. Extract every needed reactive value in `compu
 and reading `user.name` there *runs once* and never retriggers. Compute-phase errors can be
 intercepted with the bundle form `createEffect(compute, { effect, error })`.
 
+A two-phase effect whose apply only calls a local signal setter is "state + effect" in
+disguise — formally legal Solid 2, still rule 4 (`solid2-kit check` flags it). The reset
+form of a writable derivation replaces it, and moves the source read to the read site
+(under that site's boundaries) instead of an effect compute:
+
+```tsx
+// WRONG — signal synced by an effect; organizer() errors bypass the read site's <Errored>
+const [signInError, setSignInError] = createSignal<string | null>(null);
+createEffect(
+  () => organizer(),
+  (id) => {
+    if (id !== null) setSignInError(null);
+  },
+);
+
+// CORRECT — writable derivation: resets when organizer() changes; the setter still works
+const [signInError, setSignInError] = createSignal<string | null>(() => {
+  organizer();
+  return null;
+});
+```
+
 ### Async data
 
 ```tsx
@@ -529,6 +552,24 @@ test('increments on click', () => {
 `jsxImportSource` for tests and app code is `"@solidjs/web"`, not `"solid-js"`.
 Vite plugin is `@solidjs/vite-plugin`, not `vite-plugin-solid`.
 
+To turn those dev diagnostics into a hard gate, patch `console.warn` in the test setup
+file to rethrow unexpected warnings — then any top-level reactive read or unowned write
+an agent sneaks in fails the suite instead of scrolling by.
+
+## Client mode: no server HTML, no hydration reflexes
+
+The `@solidjs/vite-plugin` default (client mode, the `bare` tier) serves an empty-body
+shell and mounts with `render()`. Nothing is server-rendered and nothing hydrates, so
+**React's hydration-mismatch playbook does not transfer**: do not start signals with a
+"server-safe" initial value and adopt `localStorage` / `matchMedia` after mount, do not
+two-pass render, and there is no `suppressHydrationWarning`. Read client sources directly
+when creating state — `createSignal(storedPreference())` is correct in client mode. A
+deferred "safe" initial value is worse than unnecessary: if anything persists the value
+(an effect writing `localStorage`), the placeholder **overwrites the user's stored
+preference** before the real value is adopted. Mismatch only becomes a concept in
+start/SSR mode, where `hydrate()` mounts onto server HTML — and the Solid answer there is
+`isServer` / `clientOnly`, still not React-style deferred adoption.
+
 ## App stack (only if the project has these packages)
 
 This kit's always-applied rules cover `solid-js` + `@solidjs/web` TSX. Official
@@ -543,8 +584,12 @@ Solid Router 0.x/1.x stand-ins.** Patterns below; fetch the matching pages from
 { "compilerOptions": { "jsx": "preserve", "jsxImportSource": "@solidjs/web" } }
 ```
 
-Import DOM `JSX` types from `@solidjs/web`; renderer-neutral `Component` /
-`ParentProps` from `solid-js`. Vite: `import solid from "@solidjs/vite-plugin"`
+`solid-js` does **not** export a `JSX` namespace — `import type { JSX } from "solid-js"`
+is a type error (TS2305), and `JSX.Element` as the children type is a React reflex.
+Children/return types are the renderer-neutral `Element` from `solid-js`
+(`children?: Element`), alongside `Component` / `ParentProps` / `Accessor` / `Setter`.
+DOM-specific `JSX` types (`JSX.IntrinsicElements`, `JSX.CSSProperties`) and
+`ComponentProps` come from `@solidjs/web`. Vite: `import solid from "@solidjs/vite-plugin"`
 with `start: true` / `ssr: true` / `serverFunctions: true` only when the
 project already uses start mode. Tiers are `bare` → `basic` (router) →
 `fullstack` (SSR + server functions); do not jump a tier without cause.
@@ -790,6 +835,8 @@ how to reuse. Prefer the form on the right.
 | `createMemo(() => { void save(); return x(); })` / an effect that calls an action | invoke actions from handlers, not from memos or effects |
 | `createSignal(props.value)` / `createStore(props.items)` | `createSignal(() => props.value)` / `createStore(() => props.items, fallback)` — a bare `props.x` at setup is a snapshot |
 | `createRenderEffect` / `createTrackedEffect` as the default effect | two-phase `createEffect(compute, apply)` |
+| `createEffect(() => source(), () => setError(null))` to reset a signal | `createSignal(() => { source(); return null; })` — the writable derivation resets on change; a sole-setter apply is rule 4 |
+| a "server-safe" initial value adopted after mount (React hydration-mismatch fix) | client mode mounts with `render()` into an empty body — no hydration, no mismatch; read `localStorage` / `matchMedia` directly at signal creation |
 
 ```tsx
 // WRONG — post-await read never subscribes; production can hang pending
@@ -909,7 +956,9 @@ always-applied rules installed alongside this skill.
 - [ ] No props destructuring; no `props.` at component-body top level.
 - [ ] Every reactive read (`signal()`, `props.x`, `store.x`) sits in JSX, a memo, an effect
       compute, or a boundary — not the component body.
-- [ ] No signal-synced-by-effect; derived values are functions or memos.
+- [ ] No signal-synced-by-effect; derived values are functions or memos. Reset-on-change
+      is a writable derivation (`createSignal(() => { source(); return initial; })`), not
+      an effect calling the setter.
 - [ ] Event handlers wrap setters (`onClick={() => setX(...)}`), use `currentTarget`,
       and `onInput` for keystrokes. `innerHTML` is sanitized and not mixed with children.
 - [ ] Async memos are passed as accessors (`user={user}`), not `user={user()}`, so
@@ -929,6 +978,8 @@ always-applied rules installed alongside this skill.
 - [ ] Rest props via `omit`, not `{ ...props }`. Conditional `class` via objects, not string concat.
 - [ ] Input filters write back to the DOM on reject (inputs do not rewind).
 - [ ] No Solid 1.x imports or APIs (`solid-js/store`, `createResource`, `onMount`, `Suspense`, ...).
+      No `JSX` imported from `solid-js` — children/return types are `Element` from
+      `solid-js`; DOM `JSX` types come from `@solidjs/web`.
 - [ ] Inspect children with `children()`; code-split with `lazy` + `<Loading>`; reactive
       component choice with `dynamic()`. No `React.lazy`, no effects inside ref callbacks.
 - [ ] Browser-only code uses `isServer` / `clientOnly`, not `typeof window`.
@@ -944,4 +995,5 @@ always-applied rules installed alongside this skill.
 - [ ] `jsxImportSource` is `@solidjs/web`; Vite plugin is `@solidjs/vite-plugin`.
       No `@solidjs/start`, `vinxi`, `"use client"`, or Next.js imports.
 - [ ] Single return per component; no early returns on reactive conditions.
-- [ ] `solid2-kit check` and the project's typecheck pass.
+- [ ] `solid2-kit check` and the project's typecheck pass; `solid2-kit doctor` too if
+      `package.json`, tsconfig, or root config files changed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid2-agent-kit",
-  "version": "0.4.5",
+  "version": "0.8.0",
   "description": "Teach AI coding agents (Cursor, Claude Code) to write correct Solid 2.0 instead of React or Solid 1.x — always-applied rules, an agent skill, and a mechanical pattern gate.",
   "type": "module",
   "license": "MIT",
@@ -16,7 +16,7 @@
   ],
   "scripts": {
     "check:drift": "node scripts/check-docs-drift.mjs",
-    "test": "node tests/check.test.mjs"
+    "test": "node tests/check.test.mjs && node tests/hook.test.mjs && node tests/doctor.test.mjs && node tests/init.test.mjs"
   },
   "engines": {
     "node": ">=18"