## 監査が報告する内容

`pnpm tags:audit`はパッケージ所有の監査 CLI を実行します。`src/config/tag-vocabulary.ts`のデフォルト`TagCliConfig`エクスポートで宣言されたコンテンツディレクトリを走査し、各ページのフロントマターから`tags:`配列を収集して、同じモジュールの名前付き`tagVocabulary`エクスポートと照合した3種類の指摘を報告します。

- **Unknown tags** — 正規 id と完全一致しない文字列です。ボキャブラリエントリを追加するか、意図した id に置き換えるか、ページから削除してください。[`tagGovernance: "strict"`](https://zudo-doc.takazudomodular.com/ja/docs/guides/tag-governance)では unknown はビルドを失敗させます。
- **Near-duplicates** — 互いに変種のように見える2つの別個のタグ(文字列類似度が高い、または同じ単数形を持つ)。正規 id を1つ選び、もう一方を使うコンテンツを更新します。
- **Orphan vocabulary entries** — どのページからも参照されていない正規 id。参照をすべて更新または削除してからエントリを削除します。

クリーンな実行では`✓ No tag issues found`と表示されます。

## CLI 設定と package script

scaffold は明示的な設定モジュールを`package.json`で指定します。

```json
{
  "scripts": {
    "tags:audit": "tags-audit --config src/config/tag-vocabulary.ts"
  }
}
```

設定パスはプロジェクトルートから解決されます。`--config`がない、読み込めない、または有効な`TagCliConfig`をデフォルトエクスポートしていない場合、CLI は明確なエラーで終了します。名前付き`tagVocabulary`エクスポートも維持してください。生成された`zfb.config.ts`が同じモジュールを参照するため、ランタイムのガバナンスと CLI 監査が単一の情報源を共有します。

package manager の`--`を使えば、pnpm と npm のどちらでもオプションを一貫して転送できます。

## レポートの読み方

デフォルトの出力はカテゴリ別にグループ化された色付きテキストです。機械処理には`--json`を渡します。

```sh
pnpm tags:audit -- --json > audit.json
```

JSON のペイロードは`AuditReport`で、`unknowns`、`nearDuplicates`、`orphans`、`filesScanned`、そして正確な id をキーとする`frequency`マップを含みます。CI ダッシュボードはこれを利用できます。

## `b4push`経由での CI 連携

プロジェクトのプリプッシュ検証スクリプト([`pnpm b4push`](https://zudo-doc.takazudomodular.com/ja/docs/guides/development-workflow))は`--ci`付きで監査を実行します。

```sh
pnpm tags:audit -- --ci
```

`--ci`は`tagGovernance`の設定値に関わらず、**ハード指摘**(unknown)があれば非ゼロ終了を強制します。つまり:

- `tagGovernance: "warn"`では——unknown があっても`pnpm build`は通過しますが(マイグレーション中に移行を止めないため意図的)、`pnpm b4push`はプッシュを拒否します。
- `tagGovernance: "strict"`では——ビルドはすでに unknown で落ちます。`--ci`は将来的に enforcement を緩めても b4push が厳しさを保つための安全網です。

この「ビルドは寛容、push は厳格」という2層構造は、複数著者のドキュメントベースの最適解です。ドラフトは Zod と戦わずローカルで試行錯誤できつつ、壊れたタグが`main`に入ることはありません。

## 関連

- [タグガバナンス](https://zudo-doc.takazudomodular.com/ja/docs/guides/tag-governance) — ボキャブラリファイル、ガバナンスモード、ファセットパターン。
- [タグサジェスト](https://zudo-doc.takazudomodular.com/ja/docs/guides/tags-suggest) — 新しいページで正規タグを選ぶためのオプトイン LLM ヘルパー。