sparkle-design-cli 2.0.7-beta.9 → 2.0.7-rc.3

package/README.md

@@ -4,24 +4,13 @@ Sparkle Design のプロジェクト初期セットアップ、CSS 生成、導
 
 ## クイックスタート
 
-既存の Next.js / Vite プロジェクトに Sparkle Design を導入する場合、以下 1 コマンドで完了します：
+既存の Next.js / Vite プロジェクトで以下を実行するだけで導入完了します。詳細は [`setup` セクション](#setup-プロジェクトのフルセットアップ) を参照してください。
 
 ```bash
 npx --yes sparkle-design-cli setup --assistant claude
 ```
 
-setup は次を自動で行います:
-
-1. パッケージマネージャー（pnpm / npm / yarn / bun）を自動検出
-2. `sparkle-design` を dependencies、`tailwindcss` + `@tailwindcss/postcss` を devDependencies に追加
-3. 未作成の場合のみ初期ファイルを生成:
-   - `sparkle.config.json`（デフォルトは blue / BIZ UDPGothic / BIZ UDGothic / md — sparkle-design 本体のデフォルトに合わせて統一）
-   - `postcss.config.mjs`
-   - Tailwind エントリ CSS — Next.js App Router なら `src/app/globals.css`、Vite なら `src/index.css`、それ以外は `src/globals.css`（プロジェクト構成から自動判定）
-4. AI 指示ファイル（`CLAUDE.md` / `AGENTS.md` / Cursor rules）に Sparkle Design Guard ブロックを追加
-5. `sparkle-design-cli generate` を実行し、`sparkle-design.css` と `SparkleHead.tsx` を生成
-
-既存ファイルは上書きされません。
+`--assistant` は `claude` / `cursor` / `codex` / `generic` から選べます。既存ファイルは上書きされません。
 
 ## インストール
 
@@ -33,22 +22,24 @@ npm install -g sparkle-design-cli
 
 ### リリースチャネル
 
-npm の dist-tag でチャネルを分離しています。通常は latest を使い、品質保証中の変更を試したい場合のみ beta を指定してください。
+npm の dist-tag でチャネルを分けています。通常は `latest` を使い、RC や beta は先行試用時のみ指定してください。
 
-| チャネル | dist-tag | 用途                                                          | 指定方法                            |
-| -------- | -------- | ------------------------------------------------------------- | ----------------------------------- |
-| 安定版   | `latest` | 本番運用向け。`npx --yes sparkle-design-cli` は常にこれを取得 | （デフォルト）                      |
-| Beta     | `beta`   | 品質保証中の検証用                                            | `npx --yes sparkle-design-cli@beta` |
+| チャネル | dist-tag | バージョン形式 | 用途 |
+| --- | --- | --- | --- |
+| 安定版 | `latest` | `X.Y.Z` | 本番運用向け（デフォルト） |
+| Release Candidate | `next` | `X.Y.Z-rc.N` | GA 直前の検証、チーム展開前 |
+| Beta | `beta` | `X.Y.Z-beta.N` | 品質保証中の検証用 |
 
 ```bash
-# beta で setup を試す
-npx --yes sparkle-design-cli@beta setup --assistant claude
+# latest を使う（デフォルト）
+npx --yes sparkle-design-cli setup --assistant claude
 
-# beta で check を試す
-npx --yes sparkle-design-cli@beta check src --strict
-```
+# RC を使う
+npx --yes sparkle-design-cli@next setup --assistant claude
 
-Beta バージョンは `X.Y.Z-beta.N` 形式で publish されます。GA（正式版）へ昇格するときは、beta の -beta.N を外した `X.Y.Z` を改めて publish します。
+# beta を使う
+npx --yes sparkle-design-cli@beta setup --assistant claude
+```
 
 ## 使用方法
 
@@ -231,6 +222,111 @@ npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaf
 
 `setup` は通常実行時も JSON サマリーを stdout に表示します。`--dry-run` を付けると、その JSON を表示したままファイル変更だけを抑止します。
 
+### 手動セットアップ（Next.js / Vite 以外のプロジェクト向け）
+
+`setup` コマンドは **Next.js App Router** と **Vite** を前提に scaffold / entry CSS の配置を自動判定します。Remix / Astro / TanStack Start など他のフレームワークや、独自ディレクトリ構成のプロジェクトでは自動判定が外れるため、以下の手順で手動セットアップすることを推奨します。
+
+#### 手順
+
+**1. パッケージをインストール**
+
+```bash
+# 本体
+pnpm add sparkle-design        # or npm install / yarn add / bun add
+
+# Tailwind v4
+pnpm add -D tailwindcss @tailwindcss/postcss
+```
+
+**2. `sparkle.config.json` をプロジェクトルートに作成**
+
+```json
+{
+  "primary": "blue",
+  "font-pro": "Inter",
+  "font-mono": "JetBrains Mono",
+  "radius": "md"
+}
+```
+
+選択肢の詳細は本 README の「[設定オプション](#設定オプション)」を参照してください。
+
+**3. `postcss.config.mjs` をプロジェクトルートに作成**
+
+```js
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+**4. Tailwind エントリ CSS を自前で用意**
+
+既存プロジェクトに組み込む場合、`@import "tailwindcss";` を含む CSS ファイル（例: `src/styles/app.css`）があればそれを使います。無ければ作成してアプリケーションのエントリから import します。
+
+**5. `generate` を実行**
+
+```bash
+npx --yes sparkle-design-cli generate
+```
+
+これで `sparkle-design.css` が `src/app/sparkle-design.css` に生成され、`SparkleHead.tsx` も同じ場所に出ます。エントリ CSS の検出に失敗する場合は `sparkle.config.json` の `extend.globals-path` に明示指定してください。
+
+```json
+{
+  "primary": "blue",
+  "extend": {
+    "globals-path": "src/styles/app.css"
+  }
+}
+```
+
+**6. フォントの `<link>` タグを手動で配置**
+
+Next.js / Vite 以外ではアプリケーションフレームワークごとに「`<head>` 相当」の配置方法が異なります。自動生成される `SparkleHead.tsx` はそのまま使えるはずですが、使えない場合は中身（`preconnect` + Google Fonts の `<link>` タグ群）を自前のレイアウトにコピーしてください。
+
+たとえば Astro なら `src/layouts/BaseLayout.astro` の `<head>` に直接書きます:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:FILL,wght@0..1,500&display=block" />
+<!-- sparkle.config.json の font-pro / font-mono に合わせた Google Fonts URL -->
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap" />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&display=swap" />
+```
+
+**7. アンチパターン検査を package.json に追加（任意）**
+
+```json
+{
+  "scripts": {
+    "lint:sparkle": "npx --yes sparkle-design-cli check src --strict",
+    "lint:sparkle:json": "npx --yes sparkle-design-cli check src --format json"
+  }
+}
+```
+
+**8. AI エージェントを使うなら Guard ブロックと hook を手動で配置**
+
+AI ガード（`CLAUDE.md` / `AGENTS.md` / `.cursor/rules/*.mdc`）と hook 設定（`.claude/settings.json` / `.cursor/hooks.json` / `.codex/hooks.json`）は `setup` に任せるのが最も楽です。
+
+```bash
+# ガード追加・hook 設定のみ（パッケージインストールや scaffold はスキップ）
+npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaffold --skip-generate
+```
+
+この `--skip-*` 組み合わせは手動セットアップ済みのプロジェクトに対して Guard + hook だけ差し込むのに使えます。
+
+#### 既知の未対応ケース
+
+- **モノレポ（workspaces）**: `generate` は実行した cwd からパッケージマネージャーを遡及検出しないため、サブパッケージで直接実行するのが確実です。
+- **CSS 以外のエントリ（CSS-in-JS / vanilla-extract 等）**: Sparkle Design は Tailwind v4 の `@source` + CSS variable 前提で作られているため、ビルドパイプラインの外で CSS を扱うソリューションは対象外です。
+- **Tailwind v3**: `@source` ディレクティブ依存のため v4 必須です。
+
+Next.js / Vite 以外で導入したい方で困ったときは Issue で教えていただけると助かります。
+
 ## 設定ファイル (sparkle.config.json)
 
 ### 設定ファイルの作成
@@ -305,39 +401,15 @@ Figma プラグインが出力する基本4項目に加えて、プロジェク
 - カスタム出力先: `-o` オプションで指定可能
 - 実行場所を基準として相対パスで処理されます
 
-## 自動フォント管理
-
-**v1.2.0 以降の新機能**
-
-CLI は自動的にフォント管理を行います：
-
-1. **フォント検出**: `sparkle-design.css` から Google Fonts の `@import` 文を検出
-2. **エントリ CSS への移動**: フォントの `@import` を Tailwind エントリ CSS（`globals.css` / `index.css` 等、自動検出）の先頭に移動
-3. **sparkle-design.css から削除**: 元のファイルからフォント `@import` を削除
-
-### なぜこの処理が必要なのか？
-
-CSS の仕様では、`@import` 文は `@charset` と `@layer` 以外のすべてのルールより前に記述する必要があります。Tailwind CSS v4 と組み合わせた場合、この順序が正しくないとビルド時に警告が発生します。
-
-この機能により、以下の警告が自動的に解決されます：
-
-```text
-⚠️ @import rules must precede all rules aside from @charset and @layer statements
-```
-
-### 動作条件
+## フォントと entry CSS の自動管理
 
-- Tailwind エントリ CSS（`@import "tailwindcss"` を含む CSS ファイル）が `sparkle-design.css` と同じディレクトリに存在する場合のみ実行されます（ファイル名に依存しません）
-- エントリ CSS が存在しない場合は、フォント管理処理はスキップされます
+CLI は **Tailwind エントリ CSS（`@import "tailwindcss"` を含む CSS ファイル）** を自動検出し、以下を 1 回で揃えます:
 
-### 出力例
+- `sparkle-design.css` の `@import`
+- `@source "../node_modules/sparkle-design/dist"`（v4 が node_modules のクラスを拾うのに必要）
+- フォント `<link>` タグ（React 向けは `SparkleHead.tsx`、Vite 向けは `index.html` の managed block に自動注入）
 
-```text
-📦 フォント管理処理を開始します...
-📝 3個のフォントimportを検出しました
-✅ エントリ CSS にフォントimportを追加しました
-✅ sparkle-design.css からフォントimportを削除しました
-```
+CSS 仕様上 `@import` は他の at-rule より前に書く必要があるため、順序も適切に整えます。`@import "tailwindcss"` が欠けている場合は先頭に自動追記されます。
 
 ## 開発
 
@@ -354,71 +426,20 @@ npm link
 ### 開発用コマンド
 
 ```bash
-# テスト実行
-npm test
-
-# テスト監視モード
-npm run test:watch
-
-# Lint実行
-npm run lint
-
-# Lintエラーを自動修正
-npm run lint:fix
-
-# コードフォーマット
-npm run format
-
-# フォーマットチェック
-npm run format:check
-```
-
-### CLI実行テスト
-
-```bash
-# CSS生成
-sparkle-design-cli generate
-
-# ヘルプ表示
-sparkle-design-cli --help
-sparkle-design-cli generate --help
-
-# 検査
-sparkle-design-cli check src --strict
+npm test              # Node.js test runner
+npm run lint          # ESLint
+npm run format        # Prettier
 ```
 
 ### リリース手順（メンテナ向け）
 
-npm publish は GitHub Actions (`Publish to npm`) 経由で行います。ローカルから `npm publish` しないでください。
-
-#### 安定版（latest）
-
-1. `main` ブランチに変更をマージ
-2. `package.json` の `version` を SemVer で更新（例: `2.0.6` → `2.1.0`）し、`CHANGELOG.md` に該当セクションを追加
-3. PR をマージ後、Actions の **Publish to npm** を `channel: auto`（または `latest`）で手動実行
-4. workflow は lint / test を流したうえで `npm publish`（dist-tag = latest）を実行
-
-#### Beta（beta）
+publish は GitHub Actions の **Publish to npm** workflow 経由。ローカル `npm publish` は禁止。
 
-品質保証中の変更を先行公開したいときに使います。latest には影響しません。
+1. `package.json` の `version` を更新（安定版: `X.Y.Z` / RC: `X.Y.Z-rc.N` / Beta: `X.Y.Z-beta.N`）
+2. `CHANGELOG.md` に該当セクションを追加
+3. PR をマージ後、**Publish to npm** workflow を `channel: auto` で実行
 
-1. `package.json` の `version` を `X.Y.Z-beta.N` 形式に更新（例: `2.1.0-beta.0`、次の beta は `2.1.0-beta.1`）
-2. `CHANGELOG.md` に `[X.Y.Z-beta.N]` セクションを追加
-3. PR をマージ後、Actions の **Publish to npm** を `channel: auto`（または `beta`）で手動実行
-4. workflow が version を判定して `npm publish --tag beta` を実行
-5. 利用者側は `npx --yes sparkle-design-cli@beta ...` で検証
-
-#### Beta から GA（latest）へ昇格
-
-同じ成果物を latest にする場合は、新しい安定版 `X.Y.Z` を publish するか、既存 beta バージョンに latest タグを付け替えます。
-
-```bash
-# 選択肢 A: 新たに X.Y.Z を publish する（推奨）
-#   version を X.Y.Z に更新 → workflow を latest で実行
-
-# 選択肢 B: 既存の X.Y.Z-beta.N に latest タグを付け替える
-npm dist-tag add sparkle-design-cli@X.Y.Z-beta.N latest
-```
+`channel: auto` は `package.json` の version 形式から dist-tag を自動判定します（`-beta.N` → `beta` / `-rc.N` → `next` / それ以外 → `latest`）。既存 RC / Beta を latest に昇格させる場合は、新しい `X.Y.Z` として改めて publish します（`npm dist-tag add` での手動付け替えも可能ですが、version 管理が明確になる前者を推奨）。
 
 ## ライセンス
 

package/lib/anti-pattern-rules.js

@@ -925,7 +925,7 @@ const ANTI_PATTERN_GROUPS = [
     check: {
       description: 'Tailwind デフォルト typography を Sparkle Design コンポーネント内で使わない',
       recommendation:
-        'text-sm / text-xs / text-base / font-medium / font-semibold / font-bold は character-* utility に置き換えてください。',
+        'text-sm / text-xs / text-base / font-medium / font-semibold / font-bold は character-* utility に置き換えてください。ただし character-* に対応する token が無いサイズ（text-[10px] 等の arbitrary value、あるいは意図的に token 外のサイズを使う場合）は、同一行または直前行に `// sparkle-disable-line tailwind-typography` コメントを付けて例外扱いとして残すこともできます。',
       pattern: /\b(text-(?:xs|sm|base|lg|xl|2xl)|font-(?:medium|semibold|bold|normal|light))\b/g,
     },
     featureSection: lines([
@@ -937,9 +937,15 @@ const ANTI_PATTERN_GROUPS = [
       '',
       '// ❌ Wrong — Tailwind デフォルトの typography を使わない',
       '<span className="text-sm font-medium">テキスト</span>',
+      '',
+      '// 例外 — character-* に対応するサイズが無い場合は arbitrary value を使うか',
+      '// suppress コメントを付けて残す',
+      '<span className="text-[10px] text-text-low">12px 未満の極小メタ情報</span>',
+      '{/* sparkle-disable-next-line tailwind-typography */}',
+      '<span className="text-xs">どうしても text-xs で残したいケース</span>',
       '```',
       '',
-      'Sparkle Design コンポーネント内では `character-*-pro` / `character-*-mono` を使用する。Tailwind の `text-sm` / `font-medium` 等は使わない。',
+      'Sparkle Design コンポーネント内では `character-*-pro` / `character-*-mono` を使用する。character-1（12px）より小さい指定や、対応 token が無いサイズは Tailwind の arbitrary value (`text-[10px]` 等) で表現するか、`// sparkle-disable-line tailwind-typography` で個別に例外指定する。',
     ]),
     jsdocTargets: [],
   },
@@ -1049,8 +1055,28 @@ const ANTI_PATTERN_GROUPS = [
       description: 'Card 系コンポーネントのデフォルト padding を安易に上書きしない',
       recommendation:
         'CardHeader / CardContent のデフォルト padding（px-6 py-2）をそのまま使ってください。上書きは本当に必要な場合のみ。',
-      pattern:
-        /<Card(?:Header|Content)\b[^>]*\bclassName\s*=\s*(?:"[^"]*\b(?:p-|px-|py-|pt-|pb-|pl-|pr-)[^"]*"|'[^']*\b(?:p-|px-|py-|pt-|pb-|pl-|pr-)[^']*'|\{[^}]*\b(?:p-|px-|py-|pt-|pb-|pl-|pr-)[^}]*\})[^>]*>/g,
+      // 旧 pattern は `[^"]*\b...[^"]*` の 2 つの `[^"]*` が同じ文字列を食い合い
+      // quadratic backtracking になっていた（閉じ quote 無しの壊れた className
+      // で n=80k / 12s の regression）。2-pass 化して linear time を保証する:
+      //   1. `<CardHeader className="..." ...>` / `{...}` 形式の className 値
+      //      を確定マッチで抽出
+      //   2. 抽出した className 値に padding utility が含まれているか
+      //      `\b(?:p-|px-|py-|pt-|pb-|pl-|pr-)` で test する
+      // en: Switch to a 2-pass matcher. The old regex had quadratic
+      // backtracking on malformed input; now we first capture the whole
+      // className value, then test for padding utilities in isolation.
+      match: (content) => {
+        const OPEN_TAG =
+          /<Card(?:Header|Content)\b[^>]*\bclassName\s*=\s*("[^"]*"|'[^']*'|\{[^}]*\})[^>]*>/g;
+        const PADDING_UTIL = /\b(?:p-|px-|py-|pt-|pb-|pl-|pr-)/;
+        const results = [];
+        for (const m of content.matchAll(OPEN_TAG)) {
+          if (PADDING_UTIL.test(m[1])) {
+            results.push({ index: m.index, text: m[0] });
+          }
+        }
+        return results;
+      },
     },
     featureSection: lines([
       '### Card 系コンポーネントの padding を上書きしない',
@@ -1146,7 +1172,18 @@ const ANTI_PATTERN_GROUPS = [
       description: 'Icon の children にテキストを渡さない',
       recommendation:
         'Icon には icon prop でアイコン名を渡してください。children にテキストを渡すのは旧 Material Icons の書き方です。',
-      pattern: /<Icon\b(?:[^>]|\/(?!>))*>[^<]+<\/Icon>/g,
+      // 旧 pattern は `(?:[^>]|\/(?!>))*` が `/ ` を両分岐にマッチさせるため、
+      // 閉じ `>` が無い入力で exponential backtracking する ReDoS の種だった
+      // （n=200 で 48s 消費）。属性部を `[^>]*` の単一分岐に戻して linear に
+      // する。代償として自己閉じ `<Icon ... />` にも `<Icon ... >...</Icon>`
+      // として表面的にはマッチし得るが、自己閉じは `/` が末尾に来るので
+      // `>[^<]+` の後続（children text）に空白以外が必要になり、現実の JSX
+      // では自己閉じと open+close タグが入り乱れる頻度は低い。1-pass で拾い
+      // きれないケースは 2-pass に引き上げることで将来対応する。
+      // en: Old pattern suffered exponential ReDoS because `/ ` fit both
+      // branches of the alternation. Use a linear `[^>]*` and accept a
+      // small risk of self-closing false positives (rare in practice).
+      pattern: /<Icon\b[^>]*>[^<]+<\/Icon>/g,
     },
     featureSection: lines([
       '### Icon の children にテキストを渡さない',

package/lib/check.js

@@ -11,7 +11,18 @@ const RULES = getCheckRules();
 const BASE_MANUAL_REVIEW_REMINDERS = getManualReviewReminders();
 
 const SPARKLE_HEAD_JSX_PATTERN = /<SparkleHead\s*\/?\s*>/;
-const CSP_PATTERN = /content-security-policy|contentSecurityPolicy|Content-Security-Policy/i;
+// CSP key が「実際の設定 key として記述されている」コンテキストに絞る。
+// 以前は単純に `/content-security-policy|.../i` だったため、コメント行
+// （`// TODO: Add Content-Security-Policy later` 等）にだけマッチして
+// false-positive の finding を emit していた。
+// - `'Content-Security-Policy': ...` (object property with quoted string key)
+// - `contentSecurityPolicy: ...` (JS camelCase property)
+// - `"Content-Security-Policy"` を value として持つ header エントリ（`key: 'Content-Security-Policy'`）
+// を許容し、単体コメント文字列には反応しないようにする。
+// en: Restrict CSP detection to contexts that look like actual config entries,
+// avoiding false positives from mere comment mentions.
+const CSP_PATTERN =
+  /(?:['"]Content-Security-Policy['"]\s*[:,]|contentSecurityPolicy\s*[:=]|key\s*:\s*['"]Content-Security-Policy['"])/;
 const NEXT_CONFIG_CANDIDATES = [
   'next.config.js',
   'next.config.ts',
@@ -74,8 +85,66 @@ function formatSnippet(text) {
   return text.replace(/\s+/g, ' ').trim().slice(0, 120);
 }
 
+/**
+ * ESLint 風の suppression コメントをサポートする。以下のいずれかが findings
+ * と同じ行、または直前行にあれば該当 rule の finding は emit しない:
+ *
+ *   // sparkle-disable-line <rule-id>
+ *   // sparkle-disable-next-line <rule-id>
+ *   {/* sparkle-disable-line <rule-id> *\/}   （JSX コメント）
+ *
+ * ユーザーがどうしても character-* に移行できない typography（token に
+ * 存在しないサイズなど）や、特定 file だけ例外扱いしたい場合の escape
+ * hatch として用意する。ルール ID は複数カンマ区切り可（例:
+ * `sparkle-disable-line tailwind-typography, card-padding-override`）。
+ *
+ * en: ESLint-style suppression comments so specific findings can be opted
+ * 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_NEXT_LINE =
+  /(?:\/\/|\/\*|\{\/\*)\s*sparkle-disable-next-line\s+([A-Za-z0-9,\s_-]+?)\s*(?:\*\/\}?|$)/;
+
+function extractSuppressedRules(source, regex) {
+  if (!source) return null;
+  const m = source.match(regex);
+  if (!m) return null;
+  return new Set(
+    m[1]
+      .split(',')
+      .map((id) => id.trim())
+      .filter(Boolean)
+  );
+}
+
+function isSuppressed(ruleId, contentLines, lineNumber) {
+  // lineNumber は 1-origin
+  // en: 1-based line numbers from getLineNumber.
+  const current = contentLines[lineNumber - 1] ?? '';
+  const previous = contentLines[lineNumber - 2] ?? '';
+  const sameLine = extractSuppressedRules(current, SUPPRESS_LINE);
+  if (sameLine && sameLine.has(ruleId)) return true;
+  const prevLine = extractSuppressedRules(previous, SUPPRESS_NEXT_LINE);
+  if (prevLine && prevLine.has(ruleId)) return true;
+  return false;
+}
+
 function collectFindings(filePath, content) {
   const findings = [];
+  const contentLines = content.split(/\r?\n/);
+  const pushFinding = (rule, index, snippet) => {
+    const line = getLineNumber(content, index ?? 0);
+    if (isSuppressed(rule.id, contentLines, line)) return;
+    findings.push({
+      filePath,
+      id: rule.id,
+      description: rule.description,
+      recommendation: rule.recommendation,
+      line,
+      snippet,
+    });
+  };
 
   for (const rule of RULES) {
     if (typeof rule.match === 'function') {
@@ -83,26 +152,12 @@ function collectFindings(filePath, content) {
       // 複雑な照合が必要なルール向けの opt-in API。2-pass 方式などで regex 単体の
       // backtracking リスクを回避したいときに使う。index は content 内の絶対オフセット。
       for (const hit of rule.match(content)) {
-        findings.push({
-          filePath,
-          id: rule.id,
-          description: rule.description,
-          recommendation: rule.recommendation,
-          line: getLineNumber(content, hit.index ?? 0),
-          snippet: formatSnippet(hit.text ?? ''),
-        });
+        pushFinding(rule, hit.index ?? 0, formatSnippet(hit.text ?? ''));
       }
       continue;
     }
     for (const match of content.matchAll(rule.pattern)) {
-      findings.push({
-        filePath,
-        id: rule.id,
-        description: rule.description,
-        recommendation: rule.recommendation,
-        line: getLineNumber(content, match.index ?? 0),
-        snippet: formatMatch(match),
-      });
+      pushFinding(rule, match.index ?? 0, formatMatch(match));
     }
   }
 
@@ -160,22 +215,38 @@ function collectNextjsCspFindings(cwd) {
     let content;
     try {
       content = fs.readFileSync(configPath, 'utf8');
-    } catch {
+    } catch (error) {
+      // ENOENT は候補が存在しないだけなので静かに次へ。EACCES などは
+      // デバッグ価値があるので warn する（silent skip で「check したが
+      // CSP 設定が無かった」と誤解されないように）。
+      // en: ENOENT = config file absent, move on quietly. Other codes
+      // are worth surfacing so the user knows detection was skipped.
+      if (error.code !== 'ENOENT') {
+        console.warn(
+          `⚠️  ${candidate} の読み込みに失敗したため CSP 検査をスキップします (${error.code ?? error.message})`
+        );
+      }
       continue;
     }
 
     if (!CSP_PATTERN.test(content)) continue;
 
+    // host の `.` を regex escape しないと `fontsXgoogleapisXcom` などにも
+    // マッチし、本来足りない allowlist を「足りている」と誤判定する false
+    // negative が起きる。literal `.` として検査する。
+    // en: Escape `.` so we match the literal hostname and don't accept
+    // arbitrary strings as an allowlist match.
+    const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const missingDomains = [
       {
         domain: 'fonts.googleapis.com',
         directive: 'style-src',
-        pattern: new RegExp(FONT_DOMAINS.GOOGLEAPIS.replace('https://', '')),
+        pattern: new RegExp(escapeRegex(FONT_DOMAINS.GOOGLEAPIS.replace('https://', ''))),
       },
       {
         domain: 'fonts.gstatic.com',
         directive: 'font-src',
-        pattern: new RegExp(FONT_DOMAINS.GSTATIC.replace('https://', '')),
+        pattern: new RegExp(escapeRegex(FONT_DOMAINS.GSTATIC.replace('https://', ''))),
       },
     ].filter(({ pattern }) => !pattern.test(content));
 
@@ -268,9 +339,37 @@ function printTextReport(report, options = {}) {
     }
   }
 
-  console.log('Manual review reminders:');
-  for (const reminder of report.manualReviewReminders) {
-    console.log(`- [${reminder.id}] ${reminder.message}`);
+  const reminders = report.manualReviewReminders ?? [];
+  if (reminders.length === 0) {
+    // 0 件のときは従来通り静かに済ます。
+    // en: Nothing to review — keep quiet.
+  } else {
+    // Guard block から参照される acknowledgment フォーマットと合わせるため、
+    // AI 向けに「各 ID を response に echo して確認したことを示してほしい」
+    // と明示的に要求する。hook による exit blocking はしない（判断事項のため）。
+    // en: Ask the AI to echo each reminder ID in its final response, so humans
+    // can see which reminders were considered. This is not enforced by hook
+    // 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('');
+    for (const reminder of reminders) {
+      console.log(`- [${reminder.id}] ${reminder.message}`);
+    }
+    console.log('');
+    console.log(
+      'Example acknowledgment: "[badge-tag-semantics] reviewed — Badge used only for counts (OK). [dialog-modal-ux] reviewed — changed Dialog to Modal for form case."'
+    );
+    console.log('=========================================================================');
   }
 
   if (options.strict && report.findings.length > 0) {
@@ -281,6 +380,7 @@ function printTextReport(report, options = {}) {
 function printJsonReport(report, options = {}) {
   const strictMode = Boolean(options.strict);
   const passed = !(strictMode && report.findings.length > 0);
+  const reminders = report.manualReviewReminders ?? [];
 
   console.log(
     JSON.stringify(
@@ -289,6 +389,18 @@ function printJsonReport(report, options = {}) {
           targetCount: report.targets.length,
           checkedFileCount: report.checkedFiles.length,
           findingCount: report.findings.length,
+          reminderCount: reminders.length,
+          // AI 向けの attention フラグ。reminder が 1 件でもあれば true になり、
+          // AI は最終 response で各 reminder ID を echo する必要がある。
+          // exit code には寄与しない（判断事項を hook で block するのは過剰）。
+          // en: AI attention flag. When reminders exist, the AI MUST echo each
+          // reminder ID in its final reply. Not tied to exit code — reminders
+          // are judgment calls, not hard errors.
+          manualReviewRequired: reminders.length > 0,
+          reminderAcknowledgmentFormat:
+            reminders.length > 0
+              ? 'Respond with each reminder ID followed by your review, e.g. `[badge-tag-semantics] reviewed — Badge is used only for counts (OK)`.'
+              : null,
           strictMode,
           passed,
           exitCode: passed ? 0 : 1,