sparkle-design-cli 2.0.7 → 2.1.0

package/README.md

@@ -167,6 +167,72 @@ sparkle-design-cli check --help
 
 AI エージェントや CI からこの `lint:sparkle` を呼ぶ運用にすると、ガイドラインの注意書きだけに頼らず機械的に検査できます。
 
+#### アンチパターン検知の拡張（プラグイン）
+
+他のコンポーネントライブラリ（社内拡張など）に固有のアンチパターン検知を、`sparkle-design-cli` 本体に変更を加えず追加できる拡張機構があります。
+
+##### 仕組み
+
+プラグインを提供するパッケージは、自身の `package.json` に検知ルールのエントリを宣言します:
+
+```json
+{
+  "name": "@your-org/your-design-extensions",
+  "sparkleCli": {
+    "antiPatterns": "./anti-patterns/index.js"
+  }
+}
+```
+
+エントリファイルは `defineAntiPatternPlugin` を使ってプラグインを default export します:
+
+```js
+import { defineAntiPatternPlugin } from 'sparkle-design-cli/plugin';
+
+export default defineAntiPatternPlugin({
+  groups: [
+    {
+      id: 'your-org-foocard-nesting',
+      check: {
+        description: 'FooCard を別の FooCard でラップしないでください。',
+        recommendation: '入れ子表示が必要なら FooStack を使ってください。',
+        pattern: /<FooCard[^>]*>[\s\S]*?<FooCard/g,
+      },
+    },
+  ],
+  manualReviewReminders: [
+    {
+      id: 'your-org-foocard-color',
+      message: 'FooCard の color token が brand に揃っているか確認してください。',
+    },
+  ],
+});
+```
+
+##### 自動 discovery
+
+`sparkle-design-cli check` 実行時、CLI は consumer プロジェクトの `package.json` の `dependencies` / `devDependencies` / `peerDependencies` / `optionalDependencies` を走査し、`sparkleCli.antiPatterns` を宣言しているパッケージを発見次第ロードしてビルトインのルールにマージします。
+
+- プラグインパッケージが install されていなければ何も起きません
+- ロードや評価で失敗したプラグインは warn を出してスキップし、残りのルールで check は継続されます
+- ルール ID はビルトイン・他プラグインと名前空間を共有するため、`your-org-` のようなプレフィックスを付けて衝突を避けてください
+
+> ⚠️ **信頼境界**: プラグインのエントリファイルは `import()` で **任意の JavaScript を実行** します。これは Node.js の通常のパッケージ依存と同じ性質ですが、`sparkle-design-cli check` 実行時に走るコードが増えるという点で意識しておく必要があります。プラグインは信頼できる org / 著者のパッケージのみインストールしてください。
+
+##### 契約仕様の確認
+
+最新の契約仕様は CLI から直接出力できます:
+
+```bash
+# 契約 shape のドキュメントを出力
+npx --yes sparkle-design-cli plugin-spec
+
+# 現在のプロジェクトで discover されたプラグインを一覧
+npx --yes sparkle-design-cli plugin-spec --list
+```
+
+完全な型定義は `node_modules/sparkle-design-cli/lib/plugin-api.js` の JSDoc を参照してください。
+
 ### setup: プロジェクトのフルセットアップ
 
 `sparkle-design-cli setup` は、Sparkle Design の導入に必要な作業をまとめて行います：

package/bin/sparkle-design.js

@@ -3,8 +3,11 @@
 import { generateCSS } from '../lib/generate-css.js';
 import { checkProject } from '../lib/check.js';
 import { setupAssistant } from '../lib/setup.js';
+import { runStopHook } from '../lib/stop-hook.js';
+import { PLUGIN_SPEC_MARKDOWN } from '../lib/plugin-api.js';
+import { loadAntiPatternPlugins } from '../lib/load-plugins.js';
 
-const SUBCOMMANDS = new Set(['generate', 'check', 'setup']);
+const SUBCOMMANDS = new Set(['generate', 'check', 'setup', 'stop-hook', 'plugin-spec']);
 
 function requireOptionValue(args, index, flags) {
   const value = args[index + 1];
@@ -135,9 +138,11 @@ Sparkle Design CLI
   sparkle-design-cli <command> [options]
 
 Commands:
-  generate   sparkle.config.json から CSS を生成
-  check      Sparkle Design のアンチパターンを検査
-  setup      Sparkle Design プロジェクトをセットアップ（パッケージ導入 + 初期ファイル + AI ガード + generate）
+  generate     sparkle.config.json から CSS を生成
+  check        Sparkle Design のアンチパターンを検査
+  setup        Sparkle Design プロジェクトをセットアップ（パッケージ導入 + 初期ファイル + AI ガード + generate）
+  stop-hook    AI assistant の Stop hook 用 internal subcommand（findings 検出時に exit 2 で 1 度だけ停止をブロック / 再発火は自動回避）
+  plugin-spec  アンチパターン拡張プラグインの契約仕様を出力（--list で導入済みプラグインを表示）
 
 Generate:
   sparkle-design-cli generate
@@ -151,6 +156,10 @@ Check:
   sparkle-design-cli check src --format json
   sparkle-design-cli check src/components src/features
 
+Plugin spec:
+  sparkle-design-cli plugin-spec           # アンチパターン拡張プラグインの契約仕様を出力
+  sparkle-design-cli plugin-spec --list    # 現在のプロジェクトで発見されたプラグインを表示
+
 Setup:
   sparkle-design-cli setup                                        # フルセットアップ（推奨・新規導入時）
   sparkle-design-cli setup --assistant claude                     # Claude 向けガードも同時にセットアップ
@@ -248,7 +257,31 @@ generate で生成されるファイル:
 `);
 }
 
-function main() {
+async function runPluginSpec(args) {
+  // `--list` prints the discovered plugins; default prints the contract markdown so authors
+  // can `npx sparkle-design-cli plugin-spec > PLUGIN.md` to seed their docs.
+  // en: With --list, summarize what was discovered in the cwd; otherwise print the spec.
+  if (args.includes('--list')) {
+    const { discovered } = await loadAntiPatternPlugins();
+    if (discovered.length === 0) {
+      console.log('No anti-pattern plugins discovered in the current project.');
+      return;
+    }
+    for (const record of discovered) {
+      const status = record.status === 'loaded' ? 'ok' : `error: ${record.error}`;
+      console.log(`- ${record.packageName} (${status})`);
+      console.log(`    entry: ${record.entry}`);
+      console.log(`    resolved: ${record.resolvedFile}`);
+      if (record.groupIds && record.groupIds.length > 0) {
+        console.log(`    rules: ${record.groupIds.join(', ')}`);
+      }
+    }
+    return;
+  }
+  console.log(PLUGIN_SPEC_MARKDOWN);
+}
+
+async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
 
@@ -280,7 +313,7 @@ function main() {
         process.exit(0);
       }
 
-      const hasFindings = checkProject(options.targets, {
+      const hasFindings = await checkProject(options.targets, {
         strict: options.strict,
         format: options.format,
       });
@@ -302,6 +335,21 @@ function main() {
       return;
     }
 
+    if (command === 'stop-hook') {
+      // setup で各 agent の hook 設定ファイルから呼ばれる internal subcommand。
+      // 第 2 引数は lint 対象 path（setup 時に決まったもの）。option flag は未対応。
+      // en: Internal subcommand invoked by agent stop hooks. The single positional
+      // arg is the lint target path determined at setup time.
+      const target = args[1];
+      const exitCode = await runStopHook(target);
+      process.exit(exitCode);
+    }
+
+    if (command === 'plugin-spec') {
+      await runPluginSpec(args.slice(1));
+      return;
+    }
+
     // 未知のコマンド: エラー終了ではなく note + help 表示にする（typo 時の迷子を防ぐ）
     // en: Unknown command: show a short note + help instead of throwing
     console.warn(

package/lib/anti-pattern-rules.js

@@ -23,7 +23,7 @@ function renderJSDocSection(section) {
   return output.map((line) => (line ? ` * ${line}` : ' *')).join('\n');
 }
 
-const MANUAL_REVIEW_REMINDERS = [
+const BUILTIN_MANUAL_REVIEW_REMINDERS = [
   {
     id: 'badge-tag-semantics',
     message:
@@ -46,7 +46,7 @@ const MANUAL_REVIEW_REMINDERS = [
   },
 ];
 
-const ANTI_PATTERN_GROUPS = [
+const BUILTIN_ANTI_PATTERN_GROUPS = [
   {
     id: 'card-description',
     featureSection: lines([
@@ -1200,51 +1200,62 @@ const ANTI_PATTERN_GROUPS = [
   },
 ];
 
-function getCheckRules() {
-  const order = [
-    'dialog-form',
-    'dialog-button-wrap',
-    'button-icon-only',
-    'material-symbols-direct',
-    'shadcn-token',
-    'tailwind-typography',
-    'card-title-typography',
-    'card-control-non-button',
-    'card-padding-override',
-    'aschild-with-icon-props',
-    'disabled-vs-is-disabled',
-    'button-prefixicon-jsx',
-    'icon-children-text',
-  ];
+// Built-in groups always come before plugin-supplied groups in this priority order.
+// Plugin-supplied IDs that aren't in this list fall to the end (stable insertion order).
+// en: Determines `check` finding emission order so the most-important built-in rules surface first.
+const BUILTIN_CHECK_ORDER = [
+  'dialog-form',
+  'dialog-button-wrap',
+  'button-icon-only',
+  'material-symbols-direct',
+  'shadcn-token',
+  'tailwind-typography',
+  'card-title-typography',
+  'card-control-non-button',
+  'card-padding-override',
+  'aschild-with-icon-props',
+  'disabled-vs-is-disabled',
+  'button-prefixicon-jsx',
+  'icon-children-text',
+];
 
-  return ANTI_PATTERN_GROUPS.filter((group) => group.check)
+function getCheckRules(groups = BUILTIN_ANTI_PATTERN_GROUPS) {
+  return groups
+    .filter((group) => group.check)
     .map((group) => ({
       id: group.id,
       ...group.check,
     }))
     .sort((left, right) => {
-      const leftIndex = order.indexOf(left.id);
-      const rightIndex = order.indexOf(right.id);
+      const leftIndex = BUILTIN_CHECK_ORDER.indexOf(left.id);
+      const rightIndex = BUILTIN_CHECK_ORDER.indexOf(right.id);
       const normalizedLeftIndex = leftIndex === -1 ? Number.MAX_SAFE_INTEGER : leftIndex;
       const normalizedRightIndex = rightIndex === -1 ? Number.MAX_SAFE_INTEGER : rightIndex;
       return normalizedLeftIndex - normalizedRightIndex;
     });
 }
 
-function getAllJSDocTargets() {
-  return ANTI_PATTERN_GROUPS.flatMap((group) => group.jsdocTargets);
+function getAllJSDocTargets(groups = BUILTIN_ANTI_PATTERN_GROUPS) {
+  return groups.flatMap((group) => group.jsdocTargets ?? []);
 }
 
-function renderFeatureSections() {
-  return ANTI_PATTERN_GROUPS.map((group) => group.featureSection).join('\n\n');
+function renderFeatureSections(groups = BUILTIN_ANTI_PATTERN_GROUPS) {
+  return groups
+    .map((group) => group.featureSection)
+    .filter(Boolean)
+    .join('\n\n');
 }
 
-function getManualReviewReminders() {
-  return MANUAL_REVIEW_REMINDERS;
+function getManualReviewReminders(reminders = BUILTIN_MANUAL_REVIEW_REMINDERS) {
+  return reminders;
 }
 
 export {
-  ANTI_PATTERN_GROUPS,
+  BUILTIN_ANTI_PATTERN_GROUPS,
+  BUILTIN_MANUAL_REVIEW_REMINDERS,
+  // Backward-compatible aliases — keep until external callers (sync-anti-pattern-docs, tests) migrate.
+  BUILTIN_ANTI_PATTERN_GROUPS as ANTI_PATTERN_GROUPS,
+  BUILTIN_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
   COMMON_INTRO,
   getAllJSDocTargets,
   getCheckRules,

package/lib/check.js

@@ -1,14 +1,22 @@
 import fs from 'fs';
 import path from 'path';
 
-import { getCheckRules, getManualReviewReminders } from './anti-pattern-rules.js';
+import {
+  BUILTIN_ANTI_PATTERN_GROUPS,
+  BUILTIN_MANUAL_REVIEW_REMINDERS,
+  getCheckRules,
+  getManualReviewReminders,
+} from './anti-pattern-rules.js';
+import { loadAntiPatternPlugins } from './load-plugins.js';
 import { REGEX, FONT_DOMAINS } from './constants.js';
 
 const DEFAULT_TARGET = 'src';
 const TEXT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']);
 const CSS_EXTENSIONS = new Set(['.css']);
-const RULES = getCheckRules();
-const BASE_MANUAL_REVIEW_REMINDERS = getManualReviewReminders();
+
+// Built-ins resolved at module load so test code that imports { RULES } directly still works.
+// en: Synchronous built-in snapshot for backward-compatible export below.
+const BUILTIN_RULES = getCheckRules(BUILTIN_ANTI_PATTERN_GROUPS);
 
 const SPARKLE_HEAD_JSX_PATTERN = /<SparkleHead\s*\/?\s*>/;
 // CSP key が「実際の設定 key として記述されている」コンテキストに絞る。
@@ -102,7 +110,8 @@ function formatSnippet(text) {
  * out when character-* / Sparkle tokens don't map cleanly (e.g. sub-token
  * font sizes). Same-line or previous-line comment is honored.
  */
-const SUPPRESS_LINE = /(?:\/\/|\/\*|\{\/\*)\s*sparkle-disable-line\s+([A-Za-z0-9,\s_-]+?)\s*(?:\*\/\}?|$)/;
+const SUPPRESS_LINE =
+  /(?:\/\/|\/\*|\{\/\*)\s*sparkle-disable-line\s+([A-Za-z0-9,\s_-]+?)\s*(?:\*\/\}?|$)/;
 const SUPPRESS_NEXT_LINE =
   /(?:\/\/|\/\*|\{\/\*)\s*sparkle-disable-next-line\s+([A-Za-z0-9,\s_-]+?)\s*(?:\*\/\}?|$)/;
 
@@ -130,7 +139,7 @@ function isSuppressed(ruleId, contentLines, lineNumber) {
   return false;
 }
 
-function collectFindings(filePath, content) {
+function collectFindings(filePath, content, rules = BUILTIN_RULES) {
   const findings = [];
   const contentLines = content.split(/\r?\n/);
   const pushFinding = (rule, index, snippet) => {
@@ -146,18 +155,40 @@ function collectFindings(filePath, content) {
     });
   };
 
-  for (const rule of RULES) {
-    if (typeof rule.match === 'function') {
-      // rule.match(content) -> Array<{ index: number, text: string }>
-      // 複雑な照合が必要なルール向けの opt-in API。2-pass 方式などで regex 単体の
-      // backtracking リスクを回避したいときに使う。index は content 内の絶対オフセット。
-      for (const hit of rule.match(content)) {
-        pushFinding(rule, hit.index ?? 0, formatSnippet(hit.text ?? ''));
+  for (const rule of rules) {
+    // rule ごとに try/catch で隔離する。1 つのプラグイン rule の throw / malformed
+    // RegExp で sparkle-design-cli check 全体が落ちるのを防ぐ。loadAntiPatternPlugins の
+    // 「warn して skip」と同じ failure mode に揃える。
+    // en: Isolate each rule. A broken plugin rule (throw / non-global regex / wrong
+    // type) must not crash the whole check pipeline.
+    try {
+      if (typeof rule.match === 'function') {
+        // rule.match(content) -> Array<{ index: number, text: string }>
+        // 複雑な照合が必要なルール向けの opt-in API。2-pass 方式などで regex 単体の
+        // backtracking リスクを回避したいときに使う。index は content 内の絶対オフセット。
+        const hits = rule.match(content);
+        if (!Array.isArray(hits)) {
+          throw new TypeError(`rule.match must return an array, got ${typeof hits}`);
+        }
+        for (const hit of hits) {
+          pushFinding(rule, hit?.index ?? 0, formatSnippet(hit?.text ?? ''));
+        }
+        continue;
       }
-      continue;
-    }
-    for (const match of content.matchAll(rule.pattern)) {
-      pushFinding(rule, match.index ?? 0, formatMatch(match));
+      if (!(rule.pattern instanceof RegExp)) {
+        throw new TypeError('rule.pattern must be a RegExp (or define rule.match instead)');
+      }
+      if (!rule.pattern.global) {
+        throw new TypeError('rule.pattern must include the global flag (e.g. /foo/g)');
+      }
+      for (const match of content.matchAll(rule.pattern)) {
+        pushFinding(rule, match.index ?? 0, formatMatch(match));
+      }
+    } catch (error) {
+      const message = error?.message ?? String(error);
+      console.warn(
+        `⚠️  sparkle-design-cli: rule "${rule.id ?? '(unknown)'}" failed on ${toRelativeReportPath(filePath)} — skipping (${message})`
+      );
     }
   }
 
@@ -267,7 +298,9 @@ function collectNextjsCspFindings(cwd) {
   return findings;
 }
 
-function createCheckReport(targets = []) {
+function createCheckReport(targets = [], options = {}) {
+  const rules = options.rules ?? BUILTIN_RULES;
+  const baseReminders = options.baseReminders ?? BUILTIN_MANUAL_REVIEW_REMINDERS;
   const resolvedTargets = targets.length > 0 ? targets : [DEFAULT_TARGET];
   const textFiles = new Set();
   const cssFiles = new Set();
@@ -289,7 +322,7 @@ function createCheckReport(targets = []) {
   }
 
   const findings = [...fileContents.entries()]
-    .flatMap(([filePath, content]) => collectFindings(filePath, content))
+    .flatMap(([filePath, content]) => collectFindings(filePath, content, rules))
     .map((finding) => ({
       ...finding,
       filePath: toRelativeReportPath(finding.filePath),
@@ -308,7 +341,7 @@ function createCheckReport(targets = []) {
     return left.id.localeCompare(right.id);
   });
 
-  const manualReviewReminders = [...BASE_MANUAL_REVIEW_REMINDERS];
+  const manualReviewReminders = [...baseReminders];
   if (!hasSparkleHeadUsage(fileContents)) {
     manualReviewReminders.push({
       id: 'sparkle-head-missing',
@@ -352,15 +385,9 @@ function printTextReport(report, options = {}) {
     // exit code — reminders are judgment calls, not hard failures.
     console.log('');
     console.log('=== Manual review reminders (must acknowledge each ID in your response) ===');
-    console.log(
-      'These are judgment calls the linter cannot detect. For every item below,'
-    );
-    console.log(
-      'explicitly state the reminder ID in your reply together with whether the'
-    );
-    console.log(
-      'current code already satisfies it, or what change is needed. Silence = skipped.'
-    );
+    console.log('These are judgment calls the linter cannot detect. For every item below,');
+    console.log('explicitly state the reminder ID in your reply together with whether the');
+    console.log('current code already satisfies it, or what change is needed. Silence = skipped.');
     console.log('');
     for (const reminder of reminders) {
       console.log(`- [${reminder.id}] ${reminder.message}`);
@@ -413,8 +440,19 @@ function printJsonReport(report, options = {}) {
   );
 }
 
-export function checkProject(targets = [], options = {}) {
-  const report = createCheckReport(targets);
+export async function checkProject(targets = [], options = {}) {
+  // Plugins are discovered from the consumer project's package.json deps. Errors are
+  // already warn-and-skip inside loadAntiPatternPlugins, so we just consume the result.
+  // en: Auto-discover plugins from cwd; loader handles its own failure reporting.
+  const { groups: pluginGroups, reminders: pluginReminders } = await loadAntiPatternPlugins();
+  const mergedGroups = [...BUILTIN_ANTI_PATTERN_GROUPS, ...pluginGroups];
+  const rules = getCheckRules(mergedGroups);
+  const baseReminders = getManualReviewReminders([
+    ...BUILTIN_MANUAL_REVIEW_REMINDERS,
+    ...pluginReminders,
+  ]);
+
+  const report = createCheckReport(targets, { rules, baseReminders });
 
   if (options.format === 'json') {
     printJsonReport(report, options);
@@ -426,8 +464,8 @@ export function checkProject(targets = [], options = {}) {
 }
 
 export {
-  RULES,
+  BUILTIN_RULES as RULES,
   collectFindings,
   createCheckReport,
-  BASE_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
+  BUILTIN_MANUAL_REVIEW_REMINDERS as MANUAL_REVIEW_REMINDERS,
 };

package/lib/load-plugins.js

@@ -0,0 +1,136 @@
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+import { pathToFileURL } from 'url';
+
+import {
+  PLUGIN_PACKAGE_FIELD,
+  PLUGIN_ANTI_PATTERNS_KEY,
+  validatePluginShape,
+} from './plugin-api.js';
+
+const DEP_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function collectDependencyNames(consumerPkg) {
+  const names = new Set();
+  for (const field of DEP_FIELDS) {
+    const block = consumerPkg[field];
+    if (block && typeof block === 'object') {
+      for (const name of Object.keys(block)) {
+        names.add(name);
+      }
+    }
+  }
+  return [...names];
+}
+
+function resolvePluginPackageJson(depName, cwd) {
+  // cwd を基点に dep の package.json を解決する。tsup / pkg-roll で生成される strict な
+  // `exports` フィールドのみのパッケージは subpath `./package.json` が export されておらず
+  // require.resolve が `ERR_PACKAGE_PATH_NOT_EXPORTED` を投げる。その場合は node_modules
+  // 配下の `package.json` を fs で直接読みに行く fallback を取る（pnpm の symlink は OS 透過）。
+  // en: Primary resolve via Node's resolver; if the plugin package's `exports` does not list
+  // `./package.json`, fall back to a direct fs read so plugins are not silently skipped.
+  const requireFromCwd = createRequire(path.join(cwd, 'package.json'));
+  try {
+    return requireFromCwd.resolve(`${depName}/package.json`);
+  } catch (error) {
+    if (error?.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+      const fallback = path.join(cwd, 'node_modules', ...depName.split('/'), 'package.json');
+      if (fs.existsSync(fallback)) {
+        return fallback;
+      }
+    }
+    return null;
+  }
+}
+
+function extractPluginEntry(pkg) {
+  const block = pkg?.[PLUGIN_PACKAGE_FIELD];
+  if (!block || typeof block !== 'object') return null;
+  const entry = block[PLUGIN_ANTI_PATTERNS_KEY];
+  return typeof entry === 'string' && entry.length > 0 ? entry : null;
+}
+
+/**
+ * Discover and load anti-pattern plugins from the consumer's package.json deps.
+ *
+ * Returns an object of the shape:
+ *   {
+ *     groups: AntiPatternGroup[],
+ *     reminders: ManualReviewReminder[],
+ *     discovered: Array<{
+ *       packageName: string,
+ *       entry: string,              // path declared in package.json (relative)
+ *       resolvedFile: string,       // absolute resolved file path
+ *       status: 'loaded' | 'error',
+ *       groupIds?: string[],        // populated when status === 'loaded'
+ *       error?: string,
+ *     }>,
+ *   }
+ *
+ * The function never throws — broken or missing plugins are reported in `discovered`
+ * and surfaced to stderr as warnings so the rest of the check can proceed.
+ */
+export async function loadAntiPatternPlugins({ cwd = process.cwd() } = {}) {
+  const consumerPkgPath = path.join(cwd, 'package.json');
+  const consumerPkg = readJsonSafe(consumerPkgPath);
+  if (!consumerPkg) {
+    return { groups: [], reminders: [], discovered: [] };
+  }
+
+  const depNames = collectDependencyNames(consumerPkg);
+  const discovered = [];
+  const groups = [];
+  const reminders = [];
+
+  for (const depName of depNames) {
+    const depPkgPath = resolvePluginPackageJson(depName, cwd);
+    if (!depPkgPath) continue;
+
+    const depPkg = readJsonSafe(depPkgPath);
+    if (!depPkg) continue;
+
+    const entry = extractPluginEntry(depPkg);
+    if (!entry) continue;
+
+    const resolvedFile = path.resolve(path.dirname(depPkgPath), entry);
+    const record = { packageName: depName, entry, resolvedFile, status: 'loaded' };
+
+    try {
+      if (!fs.existsSync(resolvedFile)) {
+        throw new Error(`plugin entry file not found at ${resolvedFile}`);
+      }
+      const mod = await import(pathToFileURL(resolvedFile).href);
+      const candidate = mod?.default ?? mod;
+      // shape の検証は plugin-api.js と共有する。`defineAntiPatternPlugin` を呼ばずに
+      // plain object を export する plugin にも同じ厳しさを適用したい。
+      // en: Share shape validation with `defineAntiPatternPlugin` so plugins that skip
+      // the helper are still rejected at load time.
+      validatePluginShape(candidate, `${depName} (${entry})`);
+      groups.push(...candidate.groups);
+      record.groupIds = candidate.groups.map((group) => group.id);
+      if (Array.isArray(candidate.manualReviewReminders)) {
+        reminders.push(...candidate.manualReviewReminders);
+      }
+    } catch (error) {
+      record.status = 'error';
+      record.error = error?.message ?? String(error);
+      console.warn(
+        `⚠️  sparkle-design-cli: failed to load anti-pattern plugin from ${depName} (entry: ${entry}, error: ${record.error})`
+      );
+    }
+
+    discovered.push(record);
+  }
+
+  return { groups, reminders, discovered };
+}

package/lib/plugin-api.js

@@ -0,0 +1,253 @@
+/**
+ * sparkle-design-cli anti-pattern plugin contract.
+ *
+ * Plugin packages declare themselves in their own package.json:
+ *
+ *   {
+ *     "name": "@your-org/your-design-extensions",
+ *     "sparkleCli": {
+ *       "antiPatterns": "./anti-patterns/index.js"
+ *     }
+ *   }
+ *
+ * The referenced file must export a plugin object as the default export,
+ * typically produced by `defineAntiPatternPlugin({ ... })`.
+ *
+ * ## Plugin shape
+ *
+ *   defineAntiPatternPlugin({
+ *     groups: AntiPatternGroup[],
+ *     manualReviewReminders?: ManualReviewReminder[],
+ *   })
+ *
+ * ## AntiPatternGroup
+ *
+ *   {
+ *     id: string,                         // unique stable identifier (also used in --disable-line comments)
+ *     featureSection?: string,            // markdown emitted into the published anti-pattern doc (esa)
+ *     jsdocTargets?: JSDocTarget[],       // optional — JSDoc injection targets in the plugin's own source
+ *     check?: {
+ *       description: string,              // shown in `check` findings
+ *       recommendation: string,           // shown in `check` findings
+ *       pattern?: RegExp,                 // simple regex check. MUST have the global (`g`) flag.
+ *                                         // mutually exclusive with `match`.
+ *       match?: (content: string) => Array<{ index: number, text: string }>,
+ *                                         // opt-in API for complex matching (2-pass, AST, etc.)
+ *     },
+ *   }
+ *
+ * ## JSDocTarget
+ *
+ *   {
+ *     file: string,                       // path relative to the plugin package root
+ *     targetName: string,                 // symbol whose JSDoc block receives the anti-pattern section
+ *     section: {
+ *       bullets: Array<{ ja: string, en: string }>,
+ *       example?: string,                 // tsx snippet
+ *     },
+ *   }
+ *
+ * ## ManualReviewReminder
+ *
+ *   {
+ *     id: string,                         // unique stable identifier echoed by the AI in acknowledgments
+ *     message: string,                    // human-readable instruction
+ *   }
+ *
+ * ## Notes
+ *
+ * - Built-in rules for the public `@goodpatch/sparkle-design` library are bundled with the CLI
+ *   and not exposed as a plugin. Plugins are merged on top of the built-ins.
+ * - Plugins are auto-discovered from the consumer's `package.json` dependencies, so a plugin
+ *   is active only when the consuming project actually installs the plugin package.
+ * - Plugin IDs share a namespace with built-ins. Pick a prefix (e.g. `internal-`) to avoid clashes.
+ */
+
+const PLUGIN_PACKAGE_FIELD = 'sparkleCli';
+const PLUGIN_ANTI_PATTERNS_KEY = 'antiPatterns';
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function validateGroup(group, context) {
+  if (!group || typeof group !== 'object' || Array.isArray(group)) {
+    throw new TypeError(`${context}: group entry must be a non-null object`);
+  }
+  if (!isNonEmptyString(group.id)) {
+    throw new TypeError(`${context}: group.id must be a non-empty string`);
+  }
+
+  if (group.check !== undefined) {
+    const { check } = group;
+    if (!check || typeof check !== 'object') {
+      throw new TypeError(`${context} (group "${group.id}"): check must be an object`);
+    }
+    if (!isNonEmptyString(check.description)) {
+      throw new TypeError(
+        `${context} (group "${group.id}"): check.description must be a non-empty string`
+      );
+    }
+    if (!isNonEmptyString(check.recommendation)) {
+      throw new TypeError(
+        `${context} (group "${group.id}"): check.recommendation must be a non-empty string`
+      );
+    }
+    const hasPattern = check.pattern !== undefined;
+    const hasMatch = check.match !== undefined;
+    if (hasPattern === hasMatch) {
+      throw new TypeError(
+        `${context} (group "${group.id}"): check must define exactly one of \`pattern\` (RegExp) or \`match\` (function)`
+      );
+    }
+    if (hasPattern) {
+      if (!(check.pattern instanceof RegExp)) {
+        throw new TypeError(`${context} (group "${group.id}"): check.pattern must be a RegExp`);
+      }
+      // matchAll は global flag が無い RegExp で TypeError を投げるので、ここで明示的に弾く。
+      // en: Bail early so the check pipeline never reaches `content.matchAll(nonGlobal)`.
+      if (!check.pattern.global) {
+        throw new TypeError(
+          `${context} (group "${group.id}"): check.pattern must include the global flag (e.g. /foo/g)`
+        );
+      }
+    } else if (typeof check.match !== 'function') {
+      throw new TypeError(`${context} (group "${group.id}"): check.match must be a function`);
+    }
+  }
+}
+
+function validateReminders(reminders, context) {
+  if (reminders === undefined) return;
+  if (!Array.isArray(reminders)) {
+    throw new TypeError(`${context}: manualReviewReminders must be an array if present`);
+  }
+  for (const [index, reminder] of reminders.entries()) {
+    if (!reminder || typeof reminder !== 'object') {
+      throw new TypeError(`${context}: manualReviewReminders[${index}] must be a non-null object`);
+    }
+    if (!isNonEmptyString(reminder.id)) {
+      throw new TypeError(
+        `${context}: manualReviewReminders[${index}].id must be a non-empty string`
+      );
+    }
+    if (!isNonEmptyString(reminder.message)) {
+      throw new TypeError(
+        `${context}: manualReviewReminders[${index}].message must be a non-empty string`
+      );
+    }
+  }
+}
+
+/**
+ * Validate that the given object matches the documented plugin shape. Throws TypeError
+ * with an actionable message on the first violation. Exported so the loader can apply
+ * the same checks to plugins that don't go through `defineAntiPatternPlugin`.
+ *
+ * @param {unknown} plugin
+ * @param {string} [context] source identifier shown in error messages (e.g. `@org/pkg (./file.js)`)
+ */
+function validatePluginShape(plugin, context = 'plugin') {
+  if (!plugin || typeof plugin !== 'object' || Array.isArray(plugin)) {
+    throw new TypeError(`${context}: plugin must be a non-null object`);
+  }
+  if (!Array.isArray(plugin.groups)) {
+    throw new TypeError(`${context}: plugin.groups must be an array`);
+  }
+  for (const [index, group] of plugin.groups.entries()) {
+    validateGroup(group, `${context} groups[${index}]`);
+  }
+  validateReminders(plugin.manualReviewReminders, context);
+}
+
+function defineAntiPatternPlugin(plugin) {
+  validatePluginShape(plugin, 'defineAntiPatternPlugin');
+  return plugin;
+}
+
+const PLUGIN_SPEC_MARKDOWN = `# sparkle-design-cli anti-pattern plugin spec
+
+Plugin packages extend \`sparkle-design-cli check\` with additional anti-pattern rules.
+Built-in rules cover the public \`@goodpatch/sparkle-design\` library; plugins are auto-discovered
+from the consuming project's dependencies, so private or org-specific component libraries can ship
+their own detection rules without bundling them into the public CLI.
+
+## Declaring a plugin
+
+In the plugin package's own \`package.json\`:
+
+\`\`\`json
+{
+  "name": "@your-org/your-design-extensions",
+  "sparkleCli": {
+    "antiPatterns": "./anti-patterns/index.js"
+  }
+}
+\`\`\`
+
+The referenced file must default-export a plugin object:
+
+\`\`\`js
+import { defineAntiPatternPlugin } from 'sparkle-design-cli/plugin';
+
+export default defineAntiPatternPlugin({
+  groups: [
+    {
+      id: 'internal-foo-misuse',
+      featureSection: '### FooCard はネスト禁止\\n...',
+      check: {
+        description: 'FooCard を別の FooCard でラップしないでください。',
+        recommendation: '入れ子表示が必要なら FooStack を使ってください。',
+        pattern: /<FooCard[^>]*>[\\s\\S]*?<FooCard/g,
+      },
+    },
+  ],
+  manualReviewReminders: [
+    {
+      id: 'internal-foo-color',
+      message: 'FooCard の color token が brand に揃っているか確認してください。',
+    },
+  ],
+});
+\`\`\`
+
+## Discovery
+
+When \`sparkle-design-cli\` runs in a project, it reads that project's \`package.json\`,
+walks \`dependencies\` / \`devDependencies\` / \`peerDependencies\` / \`optionalDependencies\`,
+and resolves each entry's own \`package.json\`. Packages whose \`package.json\` declares
+\`sparkleCli.antiPatterns\` are loaded and merged into the check rules.
+
+End users do not have to configure anything — installing a plugin package is enough to activate it.
+
+## Shape reference
+
+See the JSDoc in \`lib/plugin-api.js\` for the full type contract:
+
+- \`AntiPatternGroup\`: \`{ id, featureSection?, jsdocTargets?, check? }\`
+- \`AntiPatternGroup.check\`: \`{ description, recommendation, pattern | match }\`
+  - \`pattern\` is a RegExp and **must include the global flag** (\`/foo/g\`); otherwise
+    the rule is rejected at load time.
+  - \`pattern\` and \`match\` are mutually exclusive — provide exactly one.
+- \`JSDocTarget\`: \`{ file, targetName, section: { bullets, example? } }\`
+- \`ManualReviewReminder\`: \`{ id, message }\`
+
+## ID namespace
+
+Plugin rule IDs share a namespace with built-in rules and with each other. Choose a stable prefix
+(e.g. \`internal-\`, \`acme-\`) so suppression comments like \`// sparkle-disable-next-line internal-foo-misuse\`
+remain unambiguous.
+
+## Failure mode
+
+Errors loading or evaluating a plugin are logged as warnings; the rest of the check continues with
+the rules that did load. The CLI never fails because a plugin is missing or broken.
+`;
+
+export {
+  PLUGIN_PACKAGE_FIELD,
+  PLUGIN_ANTI_PATTERNS_KEY,
+  PLUGIN_SPEC_MARKDOWN,
+  defineAntiPatternPlugin,
+  validatePluginShape,
+};

package/lib/setup.js

@@ -594,16 +594,20 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
  *
  * 各 agent が持つ hook システムの schema は異なるため、agent ごとに以下の
  * ヘルパーを持つ。共通ポイントは:
- *   - 実行コマンドは `npx --yes sparkle-design-cli check <target> --strict || exit 2`
- *   - exit 2 にエスカレーションすることで、ブロック対応する agent では
- *     応答終了を止めて findings 修正に向かわせる
+ *   - 実行コマンドは `npx --yes sparkle-design-cli stop-hook <target>`
+ *     （内部で check --strict を回し、初回 findings 検出時のみ exit 2 で停止を
+ *     ブロックする。Claude Code の `stop_hook_active` を読んで再発火時は
+ *     exit 0 で抜けることでセッション内ループを防ぐ）
  *   - 既存の hook 設定ファイルは非破壊マージし、同一 command が含まれていれば skip
- *     （冪等）
+ *     （冪等）。2.0.7 までの旧コマンド `check ... --strict || exit 2` を見つけたら
+ *     新 subcommand へ自動移行する
  *   - 壊れた JSON は silent 上書きせず、ユーザーに修正を促すエラーを出す
  *
- * en: Install an agent-specific hook that runs `lint:sparkle --strict || exit 2`.
- * Each agent ships its own hook config format; these helpers emit the right
- * shape while preserving existing user content and staying idempotent on rerun.
+ * en: Install an agent-specific hook that runs the `stop-hook` subcommand,
+ * which surfaces findings once and avoids the infinite re-fire loop the
+ * pre-2.0.8 form had. Each agent ships its own hook config format; these
+ * helpers emit the right shape, stay idempotent on rerun, and migrate
+ * legacy 2.0.7 commands when found.
  *
  * References (2026-04 時点):
  *   - Claude Code : https://docs.claude.com/en/docs/claude-code/hooks
@@ -611,7 +615,26 @@ function runAssistantGuard(cwd, packageJsonPath, options, assistantConfig) {
  *   - Codex       : https://developers.openai.com/codex/hooks
  */
 function buildManagedHookCommand(target) {
-  return `npx --yes sparkle-design-cli check ${target} --strict || exit 2`;
+  // Stop / stop hook は専用 subcommand に集約する。subcommand 側で
+  // `stop_hook_active` を見て初回だけ exit 2、再発火時は exit 0 で抜ける
+  // ことでセッション内ループを防ぐ。
+  // en: Route through the dedicated `stop-hook` subcommand so we can detect
+  // re-fires (Claude Code's `stop_hook_active`) and avoid infinite loops.
+  return `npx --yes sparkle-design-cli stop-hook ${target}`;
+}
+
+/**
+ * 2.0.7 までは `npx --yes sparkle-design-cli check <target> --strict || exit 2` を
+ * 直接 hook に書いていたが、findings が残っていると Stop hook が再発火し続けて
+ * セッションが無限ループする問題があった。`stop-hook` subcommand に切り替える
+ * ため、既存 hook 設定にこの旧コマンドが残っている場合は新コマンドへ置換する。
+ *
+ * en: Detect legacy hook commands installed by 2.0.7 and earlier so setup
+ * reruns can heal them by swapping in the loop-safe `stop-hook` subcommand.
+ */
+function isLegacyManagedHookCommand(command) {
+  if (typeof command !== 'string') return false;
+  return /sparkle-design-cli\s+check\s+\S+\s+--strict\s*\|\|\s*exit\s+2/.test(command);
 }
 
 function loadHookJson(filePath, label) {
@@ -685,14 +708,40 @@ function runClaudeHook(cwd, target, dryRun) {
     typeof nextSettings.hooks === 'object' && nextSettings.hooks ? { ...nextSettings.hooks } : {};
   const stopGroups = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
 
-  const alreadyPresent = stopGroups.some(
-    (group) =>
-      Array.isArray(group?.hooks) &&
-      group.hooks.some((entry) => entry?.type === 'command' && entry?.command === managedCommand)
-  );
+  // 1st pass: legacy エントリを発見。alreadyPresent / migrated を判定する。
+  // 2 回目以降の setup や、ユーザーが手動で新コマンドを足した状態でも
+  // 重複が出ないよう、変換は 2nd pass で行う。
+  // en: First pass detects state; second pass mutates without creating dupes.
+  let alreadyPresent = false;
+  let hasLegacy = false;
+  for (const group of stopGroups) {
+    if (!Array.isArray(group?.hooks)) continue;
+    for (const entry of group.hooks) {
+      if (entry?.type !== 'command') continue;
+      if (entry.command === managedCommand) alreadyPresent = true;
+      else if (isLegacyManagedHookCommand(entry.command)) hasLegacy = true;
+    }
+  }
+  const migrated = hasLegacy;
+
+  const updatedGroups = stopGroups.map((group) => {
+    if (!Array.isArray(group?.hooks)) return group;
+    const updatedHooks = group.hooks
+      .map((entry) => {
+        if (entry?.type === 'command' && isLegacyManagedHookCommand(entry.command)) {
+          // legacy + 新コマンドが両方あったら legacy を削除（dedupe）。
+          // legacy のみなら新コマンドへ in-place 置換。
+          // en: Drop legacy when the new command coexists; otherwise rewrite.
+          return alreadyPresent ? null : { ...entry, command: managedCommand };
+        }
+        return entry;
+      })
+      .filter((entry) => entry !== null);
+    return { ...group, hooks: updatedHooks };
+  });
 
   const mismatch = detectClaudeSessionRootMismatch(cwd);
-  if (alreadyPresent) {
+  if (alreadyPresent && !migrated) {
     return {
       assistant: 'claude',
       changed: false,
@@ -704,10 +753,12 @@ function runClaudeHook(cwd, target, dryRun) {
     };
   }
 
-  stopGroups.push({
-    hooks: [{ type: 'command', command: managedCommand }],
-  });
-  hooks.Stop = stopGroups;
+  let nextStopGroups = updatedGroups;
+  if (!migrated && !alreadyPresent) {
+    nextStopGroups = [...updatedGroups, { hooks: [{ type: 'command', command: managedCommand }] }];
+  }
+
+  hooks.Stop = nextStopGroups;
   nextSettings.hooks = hooks;
 
   if (!dryRun) {
@@ -719,7 +770,7 @@ function runClaudeHook(cwd, target, dryRun) {
     changed: true,
     existed,
     path: settingsPath,
-    reason: existed ? 'appended' : 'created',
+    reason: migrated ? 'migrated' : existed ? 'appended' : 'created',
     command: managedCommand,
     sessionRootMismatch: mismatch,
   };
@@ -740,8 +791,24 @@ function runCursorHook(cwd, target, dryRun) {
     typeof nextConfig.hooks === 'object' && nextConfig.hooks ? { ...nextConfig.hooks } : {};
   const stopEntries = Array.isArray(hooks.stop) ? [...hooks.stop] : [];
 
-  const alreadyPresent = stopEntries.some((entry) => entry?.command === managedCommand);
-  if (alreadyPresent) {
+  let alreadyPresent = false;
+  let hasLegacy = false;
+  for (const entry of stopEntries) {
+    if (entry?.command === managedCommand) alreadyPresent = true;
+    else if (isLegacyManagedHookCommand(entry?.command)) hasLegacy = true;
+  }
+  const migrated = hasLegacy;
+
+  const updatedEntries = stopEntries
+    .map((entry) => {
+      if (isLegacyManagedHookCommand(entry?.command)) {
+        return alreadyPresent ? null : { ...entry, command: managedCommand };
+      }
+      return entry;
+    })
+    .filter((entry) => entry !== null);
+
+  if (alreadyPresent && !migrated) {
     return {
       assistant: 'cursor',
       changed: false,
@@ -752,8 +819,12 @@ function runCursorHook(cwd, target, dryRun) {
     };
   }
 
-  stopEntries.push({ command: managedCommand });
-  hooks.stop = stopEntries;
+  let nextStopEntries = updatedEntries;
+  if (!migrated && !alreadyPresent) {
+    nextStopEntries = [...updatedEntries, { command: managedCommand }];
+  }
+
+  hooks.stop = nextStopEntries;
   nextConfig.hooks = hooks;
 
   if (!dryRun) {
@@ -766,7 +837,7 @@ function runCursorHook(cwd, target, dryRun) {
     changed: true,
     existed,
     path: hooksPath,
-    reason: existed ? 'appended' : 'created',
+    reason: migrated ? 'migrated' : existed ? 'appended' : 'created',
     command: managedCommand,
   };
 }
@@ -786,13 +857,37 @@ function runCodexHook(cwd, target, dryRun) {
     typeof nextConfig.hooks === 'object' && nextConfig.hooks ? { ...nextConfig.hooks } : {};
   const stopGroups = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
 
-  const alreadyPresent = stopGroups.some(
-    (group) =>
-      Array.isArray(group?.hooks) &&
-      group.hooks.some((entry) => entry?.type === 'command' && entry?.command === managedCommand)
-  );
+  let alreadyPresent = false;
+  let hasLegacy = false;
+  for (const group of stopGroups) {
+    if (!Array.isArray(group?.hooks)) continue;
+    for (const entry of group.hooks) {
+      if (entry?.type !== 'command') continue;
+      if (entry.command === managedCommand) alreadyPresent = true;
+      else if (isLegacyManagedHookCommand(entry.command)) hasLegacy = true;
+    }
+  }
+  const migrated = hasLegacy;
+
+  const updatedGroups = stopGroups.map((group) => {
+    if (!Array.isArray(group?.hooks)) return group;
+    const updatedHooks = group.hooks
+      .map((entry) => {
+        if (entry?.type === 'command' && isLegacyManagedHookCommand(entry.command)) {
+          return alreadyPresent ? null : { ...entry, command: managedCommand };
+        }
+        return entry;
+      })
+      .filter((entry) => entry !== null);
+    return { ...group, hooks: updatedHooks };
+  });
+
+  // 有効化にはユーザー側の opt-in が必要な旨を summary に載せる。
+  // en: Codex hooks are behind an opt-in feature flag; surface that in summary.
+  const featureFlagNote =
+    'Codex で有効化するには `~/.codex/config.toml` に `[features]` セクションを作り `codex_hooks = true` を設定してください。';
 
-  if (alreadyPresent) {
+  if (alreadyPresent && !migrated) {
     return {
       assistant: 'codex',
       changed: false,
@@ -800,17 +895,16 @@ function runCodexHook(cwd, target, dryRun) {
       path: hooksPath,
       reason: 'already-present',
       command: managedCommand,
-      // 有効化にはユーザー側の opt-in が必要な旨を summary に載せる。
-      // en: Codex hooks are behind an opt-in feature flag; surface that in summary.
-      featureFlagNote:
-        'Codex で有効化するには `~/.codex/config.toml` に `[features]` セクションを作り `codex_hooks = true` を設定してください。',
+      featureFlagNote,
     };
   }
 
-  stopGroups.push({
-    hooks: [{ type: 'command', command: managedCommand }],
-  });
-  hooks.Stop = stopGroups;
+  let nextStopGroups = updatedGroups;
+  if (!migrated && !alreadyPresent) {
+    nextStopGroups = [...updatedGroups, { hooks: [{ type: 'command', command: managedCommand }] }];
+  }
+
+  hooks.Stop = nextStopGroups;
   nextConfig.hooks = hooks;
 
   if (!dryRun) {
@@ -823,10 +917,9 @@ function runCodexHook(cwd, target, dryRun) {
     changed: true,
     existed,
     path: hooksPath,
-    reason: existed ? 'appended' : 'created',
+    reason: migrated ? 'migrated' : existed ? 'appended' : 'created',
     command: managedCommand,
-    featureFlagNote:
-      'Codex で有効化するには `~/.codex/config.toml` に `[features]` セクションを作り `codex_hooks = true` を設定してください。',
+    featureFlagNote,
   };
 }
 
@@ -918,11 +1011,12 @@ export function setupAssistant(options = {}) {
     assistantConfig
   );
   // assistant 別に hook 設定ファイル（`.claude/settings.json` /
-  // `.cursor/hooks.json` / `.codex/hooks.json`）に `lint:sparkle --strict` を
-  // 走らせる stop / Stop hook を自動設定する。instruction 頼みではなく hook
-  // で強制することで lint:sparkle の実行漏れを防ぐ。generic は hook なし。
-  // en: For supported assistants, install a stop hook so `lint:sparkle --strict`
-  // becomes a hard gate. Generic assistant has no hook target.
+  // `.cursor/hooks.json` / `.codex/hooks.json`）に `stop-hook` subcommand を
+  // 設定する。instruction 頼みではなく hook で強制することで lint:sparkle の
+  // 実行漏れを防ぐ。subcommand 側で `stop_hook_active` を見て再発火を抑止し、
+  // findings があるときの 1 回だけ exit 2 でブロックする。generic は hook なし。
+  // en: Install the loop-safe `stop-hook` subcommand so lint:sparkle becomes a
+  // hard gate. Generic assistant has no hook target.
   const hook = runAssistantHook(assistant, cwd, guard.target, dryRun);
   const generate = runGenerate({
     skipGenerate: Boolean(options.skipGenerate),
@@ -1045,10 +1139,12 @@ function printPostSetupReminder(target, packageManager, { hook, legacyCursorGuar
         ? '（既存のまま）'
         : hook.reason === 'created'
           ? '（新規作成）'
-          : '（既存設定に追記）';
+          : hook.reason === 'migrated'
+            ? '（旧 || exit 2 形式から自動移行）'
+            : '（既存設定に追記）';
     lines.push(
-      `  4. ${meta.name} の ${meta.event} hook を ${meta.file} に設定しました ${label}。応答を終える直前に \`lint:sparkle --strict\` が走り、findings があれば exit 2 で停止がブロックされます。`,
-      `     Installed a ${meta.name} ${meta.event} hook in ${meta.file}: it runs \`lint:sparkle --strict\` before the turn ends and exits with code 2 when findings exist.`
+      `  4. ${meta.name} の ${meta.event} hook を ${meta.file} に設定しました ${label}。応答を終える直前に \`sparkle-design-cli stop-hook\` が走り、findings があれば 1 度だけ exit 2 で停止をブロックします（再発火は \`stop_hook_active\` を見て自動回避）。`,
+      `     Installed a ${meta.name} ${meta.event} hook in ${meta.file}: it runs \`sparkle-design-cli stop-hook\` before the turn ends, blocks once with exit 2 when findings exist, and skips re-blocking on stop_hook_active.`
     );
     if (hook.featureFlagNote) {
       lines.push(`     ⚠️  ${hook.featureFlagNote}`);

package/lib/stop-hook.js

@@ -0,0 +1,60 @@
+import fs from 'fs';
+import { checkProject } from './check.js';
+
+/**
+ * AI assistant の Stop / stop hook 用エントリポイント。
+ *
+ * 単に `lint:sparkle --strict || exit 2` を毎回走らせると、Claude Code
+ * のように exit 2 を「もう一度ターンを継続させる」シグナルとして解釈する
+ * agent では、findings が残っている限り Stop hook が再発火し続けて
+ * セッションが無限ループに陥る。
+ *
+ * Claude Code は再発火時に stdin JSON へ `stop_hook_active: true` を
+ * 渡してくるので、そのフラグが立っていたらここで block せず exit 0 で
+ * 抜ける。これで「最初の 1 回だけ exit 2 で停止をブロックして findings
+ * を通知し、以降はユーザーの判断に委ねる」フローになる。
+ *
+ * en: Run `check --strict` once per session to surface findings, but stop
+ * blocking on subsequent invocations within the same Stop hook chain.
+ * Claude Code sets `stop_hook_active: true` on re-fires so the hook can
+ * exit cleanly instead of looping forever (see Claude Code hooks docs).
+ */
+export async function runStopHook(target) {
+  const payload = readStdinJsonSafely();
+
+  if (payload && payload.stop_hook_active === true) {
+    process.stderr.write(
+      'sparkle-design-cli stop-hook: stop_hook_active=true を検知したため再ブロックしません。' +
+        '前回の exit 2 で findings は通知済みです。' +
+        ' / Detected stop_hook_active=true; not re-blocking. Findings were already surfaced on the first call.\n'
+    );
+    return 0;
+  }
+
+  const targets = target ? [target] : [];
+  const hasFindings = await checkProject(targets, { strict: true, format: 'text' });
+
+  if (hasFindings) {
+    process.stderr.write(
+      '\nsparkle-design-cli stop-hook: findings を検出したため応答終了を 1 度だけブロックしました。' +
+        '上記の findings を修正するか、対応しない判断であればユーザーに確認してから再度応答を完了してください。' +
+        ' / Blocked once because findings were detected. Fix them or confirm with the user before completing the response again.\n'
+    );
+    return 2;
+  }
+
+  return 0;
+}
+
+function readStdinJsonSafely() {
+  // stdin が tty / 空 / 非 JSON の場合は「初回呼び出し」として扱う。
+  // en: Treat missing or non-JSON stdin as a first invocation.
+  try {
+    if (process.stdin.isTTY) return null;
+    const raw = fs.readFileSync(0, 'utf8');
+    if (!raw || !raw.trim()) return null;
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "2.0.7",
+  "version": "2.1.0",
   "description": "Sparkle Design CLI — プロジェクトセットアップ、CSS・フォント生成、アンチパターン検査、AI エージェント（Claude Code / Cursor / Codex）向けのガードと hook 設定まで一括で行う sparkle-design 公式 CLI。",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -8,6 +8,11 @@
   },
   "main": "lib/generate-css.js",
   "type": "module",
+  "exports": {
+    ".": "./lib/generate-css.js",
+    "./plugin": "./lib/plugin-api.js",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "sparkle-design-cli": "./bin/sparkle-design.js"
   },