phasegate 0.142.0 → 0.144.0

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.144.0] - 2026-05-10
+
+### Added
+
+- **WI-129 / WI-130 — semantic L2 test-quality validation** — `L2-003 test-quality` を test case 単位の semantic AAA / assertion strength モデルへ更新した。
+  - TypeScript adapter は AST から `TestCaseStructure` / `SemanticAssertion` を構築し、複数 Act、Act 観測不足、Act 以外への Assert、domain/internal mock、weak truthiness / snapshot only / length only / interaction only、error contract 不足を warning として検出する。
+  - lifecycle/E2E と parameterized test の例外を追加し、weak assertion policy は constructor option で差し替え可能にした。
+
 ## [0.142.0] - 2026-05-10
 
 ### Added

package/README.ja.md

@@ -86,7 +86,7 @@ claude
 - `.codex/hooks.json` — Codex CLI hooks 設定（`--agent codex|both` 時）
 - `docs/principles/*.md` — アーキテクチャ哲学・テスト規約（immutable）
 - `docs/folder_management_rules.md` — ドキュメント配置ルール（**正本**）
-- `--with-husky` を付けると `.husky/pre-commit` ・ `.husky/commit-msg` も配置
+- `--with-husky` を付けると `.husky/pre-commit` ・ `.husky/commit-msg` ・ `.husky/pre-push` も配置
 - `--with-ci` を付けると `.github/workflows/aidlc-gate.yml` ・ `.github/workflows/consistency-check.yml` ・ `.github/workflows/agent-context-refresh.yml` も配置
 
 **`init` が生成しないもの**（後で skill が作る）:
@@ -142,7 +142,7 @@ npx phasegate update-skills   # スキルを最新版に再デプロイ
 |     @unit / @layer メタデータ, レイヤー違反, AI アンチパターン   |
 +------------------------------------------------------------------+
 | L2  pre-commit                                                   |
-|     phase-gate, story-reflection, テスト品質 (AAA/日本語名)       |
+|     phase-gate, story-reflection, テスト品質 (semantic AAA)       |
 +------------------------------------------------------------------+
 | L3  CI/CD                                                        |
 |     security, performance, coverage 90%/95%, 要件カバレッジ        |
@@ -293,7 +293,7 @@ npx phasegate <command> [options]
 | `baseline` | retrofit grandfather snapshot 生成（`--dry-run`, `--force`, `--paths <glob>`, `--json`） |
 | `scaffold-design --unit <id> --phase <logical\|domain\|uiux\|unit-test\|it-test>` | 最小構成の設計文書を `templates/` から生成 |
 | `phasegate:status` | 全体の健全性サマリ |
-| `work-items:status --dry-run` / `--apply` | 成果物から WI status を導出し、必要に応じて `description.md` frontmatter を更新 |
+| `work-items:status --dry-run` / `--apply` | 成果物から WI status を導出し、必要に応じて `description.md` frontmatter を更新。`--apply` は既定で downgrade を拒否し、必要時のみ `--allow-downgrade` を指定 |
 | `phasegate:check-phase --unit <id>` | 指定 Unit の現在フェーズ |
 | `phasegate:detect-drift` | 設計-コード乖離レポート |
 | `migrate work-items --dry-run` / `--apply` | 既存リポジトリの旧 `ISSUE-XXX` / `H{NN}-{NN}` directory を WI 統一レイアウト（`_cross/{WI-XXX}/` / `{unit}/{WI-XXX}/`）へ移行。frontmatter（`type` / `severity` / `legacy_id` / `affects`）を自動注入。冪等。`--json` で CI/スクリプト連携可。詳細: [Work Item Migration](docs/guide/cli-reference.md#work-item-migration) |
@@ -305,6 +305,7 @@ npx phasegate <command> [options]
 | `list-errors --layer <L0-L4>` | エラー定義一覧 |
 | `hook <pre-tool-use\|post-tool-use\|stop>` | agent hook を起動（stdin から JSON） |
 | `pre-commit` | L2 pre-commit バリデータをステージファイルに適用 |
+| `bypass:audit --base <ref> [--head <ref>]` | push/CI range に pre-commit validation を再適用し、gate failure に structured bypass evidence を要求 |
 
 完全な CLI Reference: [CLI Reference](docs/guide/cli-reference.md)
 
@@ -407,7 +408,7 @@ TESTED (@work-item-id 付きテストあり / green)
 
 `type: chore` は DRAFTED で完結。`type: fix` は DRAFTED → REFLECTED → IMPLEMENTED の簡略パス。`status` は PhaseGate が自動更新します。
 
-`phasegate work-items:status --dry-run` で current status / derived status / reason / next action を確認できます。単一 WI に絞る場合は `--id WI-XXX`、CI 風に stale status を検出する場合は `--fail-on-stale`、`description.md` frontmatter の `status:` 行だけを書き戻す場合は `--apply` を指定します。
+`phasegate work-items:status --dry-run` で current status / derived status / reason / next action / structured missing evidence を確認できます。単一 WI に絞る場合は `--id WI-XXX`、CI 風に stale status を検出する場合は `--fail-on-stale`、`description.md` frontmatter の `status:` 行だけを書き戻す場合は `--apply` を指定します。標準 L2 validation は `L2-014 work-item-status-staleness` も実行し、stale WI status を pre-commit / CI の fail signal として扱います。
 
 詳細仕様: [`docs/folder_management_rules.md`](docs/folder_management_rules.md)
 

package/README.md

@@ -85,7 +85,7 @@ claude
 - `.claude/skills` and/or `.codex/skills` links for agent use
 - `.claude/settings.json` and/or `.codex/hooks.json` hook configuration
 - `docs/principles/*.md` and `docs/folder_management_rules.md`
-- `.husky/pre-commit` and `.husky/commit-msg` when `--with-husky` is passed
+- `.husky/pre-commit`, `.husky/commit-msg`, and `.husky/pre-push` when `--with-husky` is passed
 - `.github/workflows/aidlc-gate.yml`, `.github/workflows/consistency-check.yml`, and `.github/workflows/agent-context-refresh.yml` when `--with-ci` is passed
 
 `init` intentionally does **not** create `docs/inception/` work item directories or `docs/product/` design documents. Those are produced later by skills such as `/product-architect`, `/domain-designer`, and `/logical-designer`. That is the core contract: no design, no code.
@@ -139,7 +139,7 @@ npx phasegate update-skills
 +------------------------------------------------------------------+
 |  L2  PRE-COMMIT            Validators                            |
 |  phase-gate, metadata completeness, story-reflection,            |
-|  test-quality (AAA pattern)                                      |
+|  test-quality (semantic AAA + assertion strength)                |
 +------------------------------------------------------------------+
 |  L3  CI/CD                 Validators                            |
 |  security, performance, coverage threshold, nyquist traceability |
@@ -152,7 +152,7 @@ npx phasegate update-skills
 
 | Layer | Trigger | Key Checks |
 |---|---|---|
-| L0 | AI agent runtime (`.claude/settings.json` / `.codex/hooks.json`) + Husky git hooks | PreToolUse blocks Write/Edit/Bash that violate gates; PostToolUse runs lint/format; Stop enforces ReentryGuard + `complete-check`; `.husky/pre-commit` runs `phasegate pre-commit`; `.husky/commit-msg` enforces `Work-Item: WI-XXX` trailer |
+| L0 | AI agent runtime (`.claude/settings.json` / `.codex/hooks.json`) + Husky git hooks | PreToolUse blocks Write/Edit/Bash that violate gates; PostToolUse runs lint/format; Stop enforces ReentryGuard + `complete-check`; `.husky/pre-commit` runs `phasegate pre-commit`; `.husky/commit-msg` enforces `Work-Item: WI-XXX` and bypass trailers; `.husky/pre-push` runs `phasegate bypass:audit` |
 | L1 | Editor save / `phasegate lint` | `@unit` / `@layer` metadata, layer violations, AI anti-patterns, dead code |
 | L2 | Pre-commit (also evaluated inside PreToolUse at L0) | Phase gate, metadata completeness, `@work-item-id` reflection (`L2-STORY-REFLECTION`), test quality |
 | L3 | CI/CD pipeline | Security, performance, coverage (90%/95%), requirements traceability |
@@ -247,7 +247,7 @@ TESTED  (test files annotated with @work-item-id, all green)
 
 `type: chore` ends at DRAFTED. `type: fix` shortcuts via DRAFTED → REFLECTED → IMPLEMENTED. PhaseGate auto-updates `status`.
 
-Use `phasegate work-items:status --dry-run` to inspect current status, derived status, reason, and next action. Add `--id WI-XXX` to scope the report, `--fail-on-stale` for CI-style stale status detection, or `--apply` to update only the `status:` line in each stale `description.md` frontmatter.
+Use `phasegate work-items:status --dry-run` to inspect current status, derived status, reason, next action, and structured missing evidence. Add `--id WI-XXX` to scope the report, `--fail-on-stale` for CI-style stale status detection, or `--apply` to update only the `status:` line in each stale `description.md` frontmatter. Standard L2 validation also runs `L2-014 work-item-status-staleness`; stale WI status fails `validate --layer L2` for pre-commit/CI use.
 
 Full spec: [`docs/folder_management_rules.md`](docs/folder_management_rules.md)
 
@@ -476,7 +476,7 @@ npx phasegate <command> [options]
 | `p2:check-agent-context` | Check AGENTS.md / CLAUDE.md freshness |
 | `update-skills` | Update skills to latest version |
 | `phasegate:status` | Display overall harness health summary |
-| `work-items:status --dry-run` / `--apply` | Derive WI status from artifacts and optionally update stale `description.md` frontmatter |
+| `work-items:status --dry-run` / `--apply` | Derive WI status from artifacts and optionally update stale `description.md` frontmatter. Apply refuses downgrades unless `--allow-downgrade` is supplied. |
 | `phasegate:check-phase --unit <id>` | Check current phase for a Unit |
 | `check-change-category --paths <csv>` | Classify changed files into Quick Mode categories and report whether Full Mode is required (`--format json`, `--fail-on-full-required`) |
 | `baseline` | Create `.phasegate/baseline.json` snapshot for Phase A-2 retrofit grandfather (`--dry-run`, `--force`, `--paths <glob,glob,...>`, `--json`). `baseline.enabled` defaults to `true` since v0.71.0. |
@@ -484,6 +484,7 @@ npx phasegate <command> [options]
 | `list-errors --layer <L0-L4>` | List error definitions with fix examples |
 | `hook <pre-tool-use\|post-tool-use\|stop>` | Run a Claude Code hook (reads JSON from stdin) |
 | `pre-commit` | Run L2 pre-commit validators on staged files |
+| `bypass:audit --base <ref> [--head <ref>]` | Replay pre-commit validation over a push/CI range and require structured bypass evidence for gate failures |
 | `delegate-sonnet [...args]` | Delegate task to Sonnet 4.6 (transparent wrapper) |
 | `migrate work-items --dry-run` / `--apply` | Migrate legacy `ISSUE-XXX` / `H{NN}-{NN}` directories under `docs/inception/` to the unified `WI-XXX` layout (frontmatter `type` / `legacy_id` / `affects` injected). Sequential allocator skips numbers already used by existing WIs. See [CLI Reference -- Work Item Migration](docs/guide/cli-reference.md#work-item-migration). |
 | `migrate --schema v3` | Upgrade `phasegate.config.json` to v3 schema by adding the `architecture` key (idempotent). |

package/docs/guide/layer-model.md

@@ -50,7 +50,8 @@ Deployed by `phasegate init --with-husky` into `.husky/`.
 | Hook file | Invokes | Responsibility |
 |-----------|---------|----------------|
 | **.husky/pre-commit** | `npx phasegate pre-commit` | Runs L2 validators (phase-gate / metadata / story-reflection / test-quality) on staged files. Fails the commit on violation. |
-| **.husky/commit-msg** | `npx phasegate commit-msg $1` | Enforces the `Work-Item: WI-XXX` trailer when WI directories or their contents are staged. Ensures every commit is traceable to a work item. |
+| **.husky/commit-msg** | `npx phasegate commit-msg $1` | Enforces the `Work-Item: WI-XXX` trailer when WI directories or their contents are staged, and validates structured bypass trailers when present. |
+| **.husky/pre-push** | `npx phasegate bypass:audit --base origin/main --head HEAD` | Replays pre-commit validation for the push range so commits created with `git commit --no-verify` still need complete bypass evidence before leaving the workstation. |
 
 ### About `validate --layer L0`
 
@@ -107,7 +108,7 @@ L2 validators run before every commit. They enforce process discipline and test
 |-----------|-------------|
 | **phase-gate** | Enforces design-before-implementation order. Code changes to `scripts/harness/` are blocked unless the corresponding design documents exist in `docs/product/construction/`. |
 | **metadata** | Verifies completeness of source file annotations: `@unit`, `@layer`, `@US-XXX`, and `@story` |
-| **test-quality** | Enforces test authoring standards: AAA pattern (Arrange/Act/Assert), `actual` variable naming, single-act-per-test, and no mocking in domain layer tests |
+| **test-quality** | Enforces test authoring standards through a runner-independent semantic model: AAA pattern (Arrange/Act/Assert), named Act observation, single-act-per-test, assertion strength, lifecycle/E2E exceptions, and no domain/internal mocking in domain layer tests |
 
 **Command:**
 

package/docs/guide/quick-vs-full-mode.md

@@ -46,7 +46,7 @@ flowchart TD
 | L4 Scheduled | drift + consistency + dead-code | skipped |
 | Commit prefix | conventional (`feat:`, `fix:`, ...) | `[quick] ...` |
 
-Both modes keep **L1 in full strength** and **L2 metadata / test-quality** — `@unit` / `@layer` comments and AAA test structure are non-negotiable regardless of flow.
+Both modes keep **L1 in full strength** and **L2 metadata / test-quality** — `@unit` / `@layer` comments, semantic AAA structure, and assertion-strength checks are non-negotiable regardless of flow.
 
 ---
 

package/docs/principles/testing-rules.md

@@ -12,6 +12,24 @@
 - 実行結果は `actual` に代入する。
 - テストの関心外の共通準備はヘルパーやファクトリに寄せる。ただし、各テストの前提が読めなくなるほど隠蔽しない。
 
+## Semantic AAA と Assertion Quality
+
+<!-- @work-item-id WI-129, WI-130 -->
+
+AAA は特定の runner やコメント表記ではなく、テストケースが以下の意味構造を持つこととして扱う。
+
+| 構造 | 意味 |
+|------|------|
+| Arrange | 前提条件、入力、fixture、制御可能な依存を組み立てる |
+| Act | 観測したいふるまいを実行する。Unit / Integration では原則 1 つ |
+| Assert | Act の観測結果、状態変化、発行イベント、永続化結果、error contract、interaction を検証する |
+
+Assertion Quality は matcher 名だけで判断しない。観測対象は `observed output` / `state` / `emitted event` / `persisted effect` / `error contract` / `interaction` に分類し、観測強度は `exact value` / `shape` / `invariant` / `range` / `weak truthiness` / `snapshot only` / `interaction only` / `length only` に分類する。
+
+- `toBeTruthy()` 相当の truthiness のみ、snapshot のみ、length のみ、mock call count のみは弱い観測として扱う。
+- error case は error type / code / message / recovery hint などの contract を検証する。
+- E2E の一連のライフサイクルは複数 Act を許可してよいが、各 Act の直後に観測可能な Assert を置く。
+
 ## テスト構造
 
 `target` / `describe` / `context` / `it` は以下の役割で使う。

package/docs/templates/ci/aidlc-gate.yml

@@ -5,9 +5,10 @@
 #
 # 実行タイミング: Pull Request（open / synchronize / reopen）
 # 実行内容:
-#   1. harness:lint  — L1 Biome AST ルール検証
-#   2. harness:ci-check — L3 CI バリデータ（security / performance / coverage / nyquist）
-#   3. 失敗時: PR にエラーサマリーをコメント
+#   1. bypass:audit — bypass trailer / evidence 監査
+#   2. harness:lint  — L1 Biome AST ルール検証
+#   3. harness:ci-check — L3 CI バリデータ（security / performance / coverage / nyquist）
+#   4. 失敗時: PR にエラーサマリーをコメント
 
 name: AIDLC Quality Gate
 
@@ -25,6 +26,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
@@ -40,6 +43,21 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      # Bypass audit: local `git commit --no-verify` can skip hooks, but CI
+      # replays the gate over the PR range and requires structured evidence.
+      - name: Bypass Audit
+        id: bypass_audit
+        run: |
+          set +e
+          git fetch origin "${{ github.base_ref }}" --depth=1
+          RESULT=$(npx phasegate bypass:audit --base "origin/${{ github.base_ref }}" --head HEAD 2>&1)
+          EXIT_CODE=$?
+          echo "result<<EOF" >> $GITHUB_OUTPUT
+          echo "$RESULT" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
+          exit $EXIT_CODE
+
       # L1: Biome AST ルール
       - name: L1 Lint (Biome AST)
         id: lint
@@ -75,11 +93,16 @@ jobs:
           script: |
             const lintResult   = `${{ steps.lint.outputs.result }}`;
             const ciResult     = `${{ steps.ci_check.outputs.result }}`;
+            const bypassResult = `${{ steps.bypass_audit.outputs.result }}`;
             const lintFailed   = '${{ steps.lint.outputs.exit_code }}' !== '0';
             const ciFailed     = '${{ steps.ci_check.outputs.exit_code }}' !== '0';
+            const bypassFailed = '${{ steps.bypass_audit.outputs.exit_code }}' !== '0';
 
             let body = '## ❌ AIDLC Quality Gate — 失敗\n\n';
 
+            if (bypassFailed) {
+              body += '### Bypass Audit エラー\n```text\n' + bypassResult + '\n```\n\n';
+            }
             if (lintFailed) {
               body += '### L1 Lint エラー\n```json\n' + lintResult + '\n```\n\n';
             }

package/docs/templates/hooks/pre-push

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+# PhaseGate pre-push hook template.
+#
+# Audits commits that may have bypassed local hooks with `git commit --no-verify`.
+
+npx phasegate bypass:audit --base origin/main --head HEAD

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.142.0",
+  "version": "0.144.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/config-foundation/application/mappers/validator-system-config-mapper.ts

@@ -1,7 +1,7 @@
 /**
  * @layer application
  * @unit config-foundation
- * @work-item-id WI-092 / WI-094 / WI-033
+ * @work-item-id WI-092 / WI-094 / WI-033 / WI-140
  */
 import type { HarnessConfigV2 } from '../../domain/harness-config.js';
 
@@ -11,7 +11,7 @@ export function toValidatorSystemConfig(resolvedConfig: HarnessConfigV2 | undefi
   return {
     project: { preset: resolvedConfig.project.preset },
     layers: {
-      L2: { enabled: resolvedConfig.layers.L2.enabled, validators: ['L2-001', 'L2-002', 'L2-003', 'L2-013'] },
+      L2: { enabled: resolvedConfig.layers.L2.enabled, validators: ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014'] },
       L3: { enabled: resolvedConfig.layers.L3.enabled },
       L4: { enabled: resolvedConfig.layers.L4.enabled, validators: resolvedConfig.layers.L4.validators },
     },

package/scripts/harness/integrations/pre-commit.ts

@@ -1,7 +1,7 @@
 /**
  * @unit harness-api
  * @layer presentation
- * @work-item-id WI-092
+ * @work-item-id WI-141
  *
  * Pre-commit CLI entry.
  * Runs L2 validators against staged TypeScript files AND design-document
@@ -14,8 +14,8 @@
  *   2 = runtime error
  */
 
-import { execSync } from "node:child_process";
-import { readFile } from "node:fs/promises";
+import { execFileSync, execSync } from "node:child_process";
+import { access, readFile } from "node:fs/promises";
 import { createConfigFoundationModule } from "../config-foundation/composition-root.js";
 import { toValidatorSystemConfig } from "../config-foundation/application/mappers/validator-system-config-mapper.js";
 import { createTraceabilityModelModule } from "../traceability-model/composition-root.js";
@@ -36,6 +36,9 @@ const MD_EXTENSION = ".md";
 const WORK_ITEM_PATH_PATTERN = /(?:^|\/)WI-\d+(?:\/|$)/;
 const WORK_ITEM_TRAILER_PATTERN = /^Work-Item:\s*WI-\d+\s*$/m;
 const TEST_FILE_SUFFIXES = Object.freeze([".test.ts", ".test.tsx", ".spec.ts", ".spec.tsx"]);
+const BYPASS_TRAILER_NAMES = Object.freeze(["Bypass-Reason", "Bypass-Evidence", "Bypass-Owner"]);
+const OPTIONAL_BYPASS_TRAILER_NAMES = Object.freeze(["Bypass-Report"]);
+const NON_BYPASSABLE_VALIDATOR_IDS = Object.freeze(["L2-002", "L2-003", "L2-014"]);
 
 function isConfigNotFoundError(err: unknown): boolean {
   return err instanceof Error && err.name === "ConfigNotFoundError";
@@ -184,6 +187,7 @@ export interface PreCommitDeps {
 export interface PreCommitResult {
   readonly exitCode: 0 | 1 | 2;
   readonly stdout: string;
+  readonly blockerClasses: readonly BypassBlockerClass[];
 }
 
 export interface PreCommitOptions {
@@ -194,6 +198,28 @@ export interface PreCommitOptions {
    */
   readonly commitMessage?: string;
   readonly implementationExtensions?: readonly string[];
+  readonly allowConditionalBypass?: boolean;
+  readonly evidenceRoot?: string;
+}
+
+export interface BypassBlockerClass {
+  readonly code: string;
+  readonly label: string;
+  readonly bypassable: boolean;
+}
+
+export interface BypassTrailerValidationResult {
+  readonly hasAnyBypassTrailer: boolean;
+  readonly complete: boolean;
+  readonly errors: readonly string[];
+}
+
+export interface BypassAuditOptions {
+  readonly baseRef?: string;
+  readonly headRef?: string;
+  readonly commitMessages?: readonly string[];
+  readonly changedFiles?: readonly string[];
+  readonly evidenceRoot?: string;
 }
 
 function getStagedFiles(): string[] {
@@ -248,6 +274,95 @@ function hasWorkItemTrailer(commitMessage: string): boolean {
   return WORK_ITEM_TRAILER_PATTERN.test(commitMessage);
 }
 
+function extractTrailer(commitMessage: string, trailerName: string): string | undefined {
+  const pattern = new RegExp(`^${trailerName}:\\s*(.+?)\\s*$`, "m");
+  return pattern.exec(commitMessage)?.[1]?.trim();
+}
+
+function hasTrailer(commitMessage: string, trailerName: string): boolean {
+  return extractTrailer(commitMessage, trailerName) !== undefined;
+}
+
+function isPathLikeEvidence(value: string): boolean {
+  return value.startsWith("report:");
+}
+
+function evidencePath(value: string): string {
+  return value.slice("report:".length).trim();
+}
+
+async function pathExists(path: string, root = process.cwd()): Promise<boolean> {
+  try {
+    const { resolve } = await import("node:path");
+    await access(resolve(root, path));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function validateBypassTrailers(
+  commitMessage: string,
+  evidenceRoot = process.cwd(),
+): Promise<BypassTrailerValidationResult> {
+  const allTrailerNames = [...BYPASS_TRAILER_NAMES, ...OPTIONAL_BYPASS_TRAILER_NAMES];
+  const hasAnyBypassTrailer = allTrailerNames.some((name) => hasTrailer(commitMessage, name));
+  if (!hasAnyBypassTrailer) {
+    return { hasAnyBypassTrailer: false, complete: false, errors: [] };
+  }
+
+  const errors: string[] = [];
+  for (const name of BYPASS_TRAILER_NAMES) {
+    if (!hasTrailer(commitMessage, name)) {
+      errors.push(`Missing required bypass trailer: ${name}`);
+    }
+  }
+
+  const evidence = extractTrailer(commitMessage, "Bypass-Evidence");
+  if (evidence !== undefined) {
+    if (evidence.startsWith("command:")) {
+      const command = evidence.slice("command:".length).trim();
+      if (command.length === 0) {
+        errors.push("Bypass-Evidence command must not be empty.");
+      }
+    } else if (isPathLikeEvidence(evidence)) {
+      const reportPath = evidencePath(evidence);
+      if (reportPath.length === 0) {
+        errors.push("Bypass-Evidence report path must not be empty.");
+      } else if (!(await pathExists(reportPath, evidenceRoot))) {
+        errors.push(`Bypass-Evidence report does not exist: ${reportPath}`);
+      }
+    } else {
+      errors.push("Bypass-Evidence must start with command: or report:.");
+    }
+  }
+
+  const report = extractTrailer(commitMessage, "Bypass-Report");
+  if (report !== undefined && !(await pathExists(report, evidenceRoot))) {
+    errors.push(`Bypass-Report does not exist: ${report}`);
+  }
+
+  return { hasAnyBypassTrailer: true, complete: errors.length === 0, errors };
+}
+
+function classifyValidatorFailure(result: ValidationResultContract): BypassBlockerClass | undefined {
+  if (result.passed || result.skipped) return undefined;
+  const nonBypassable = NON_BYPASSABLE_VALIDATOR_IDS.includes(result.validatorId);
+  return {
+    code: result.validatorId,
+    label: result.validatorId === "L2-003" ? "test-quality" : result.validatorId,
+    bypassable: !nonBypassable,
+  };
+}
+
+function metadataBlocker(): BypassBlockerClass {
+  return { code: "metadata", label: "metadata", bypassable: false };
+}
+
+function hasNonBypassableBlocker(blockers: readonly BypassBlockerClass[]): boolean {
+  return blockers.some((blocker) => !blocker.bypassable);
+}
+
 function normalizeImplementationExtensions(extensions: readonly string[] | undefined): readonly string[] {
   const rawExtensions = extensions === undefined || extensions.length === 0
     ? DEFAULT_IMPLEMENTATION_EXTENSIONS
@@ -274,6 +389,7 @@ export async function runPreCommit(
     return {
       exitCode: 0,
       stdout: `${DIM}[phasegate] No staged files to check. Skipping.${RESET}`,
+      blockerClasses: [],
     };
   }
 
@@ -284,6 +400,7 @@ export async function runPreCommit(
   );
 
   let exitCode: 0 | 1 | 2 = 0;
+  const blockerClasses: BypassBlockerClass[] = [];
 
   if (implementationFiles.length > 0) {
     // staged TS file を Unit ごとにグルーピングし、Unit 単位で L2 phase gate
@@ -311,6 +428,10 @@ export async function runPreCommit(
     }
 
     const merged = mergePerUnitResults(runs);
+    blockerClasses.push(...merged.flatMap((result) => {
+      const blocker = classifyValidatorFailure(result);
+      return blocker === undefined ? [] : [blocker];
+    }));
     const report = buildReport(merged);
     sections.push("");
     sections.push(`${BOLD}== 実装ファイル (${implementationFiles.length} file(s)) ==${RESET}`);
@@ -328,6 +449,9 @@ export async function runPreCommit(
     sections.push(`${BOLD}== 設計 / テスト メタデータ注釈 (${metadataFiles.length} file(s)) ==${RESET}`);
     sections.push(metadataResult.text);
     exitCode = maxExitCode(exitCode, metadataResult.exitCode);
+    if (metadataResult.exitCode !== 0) {
+      blockerClasses.push(metadataBlocker());
+    }
   }
 
   if (options.commitMessage !== undefined && requiresWorkItemTrailer(stagedFiles)) {
@@ -343,6 +467,29 @@ export async function runPreCommit(
     }
   }
 
+  if (options.commitMessage !== undefined) {
+    const bypassValidation = await validateBypassTrailers(options.commitMessage, options.evidenceRoot);
+    if (bypassValidation.hasAnyBypassTrailer) {
+      sections.push("");
+      sections.push(`${BOLD}== Bypass audit ==${RESET}`);
+      if (!bypassValidation.complete) {
+        for (const error of bypassValidation.errors) {
+          sections.push(`${RED}FAIL${RESET} ${error}`);
+        }
+        exitCode = maxExitCode(exitCode, 1);
+      } else if (hasNonBypassableBlocker(blockerClasses)) {
+        const labels = blockerClasses.filter((blocker) => !blocker.bypassable).map((blocker) => blocker.label);
+        sections.push(`${RED}FAIL${RESET} Bypass rejected for non-bypassable blocker(s): ${labels.join(", ")}`);
+        exitCode = maxExitCode(exitCode, 1);
+      } else if (exitCode !== 0 && options.allowConditionalBypass === true) {
+        sections.push(`${GREEN}PASS${RESET} Conditional bypass evidence is complete.`);
+        exitCode = 0;
+      } else {
+        sections.push(`${GREEN}PASS${RESET} Bypass trailers are complete.`);
+      }
+    }
+  }
+
   sections.push("");
   if (exitCode === 0) {
     sections.push(`${GREEN}[phasegate]${RESET} All checks passed.`);
@@ -353,6 +500,72 @@ export async function runPreCommit(
   return {
     exitCode,
     stdout: sections.join("\n"),
+    blockerClasses,
+  };
+}
+
+function getChangedFilesInRange(baseRef: string, headRef: string): string[] {
+  try {
+    const output = execFileSync("git", ["diff", "--name-only", "--diff-filter=ACM", `${baseRef}..${headRef}`], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return output.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+function getCommitMessagesInRange(baseRef: string, headRef: string): string[] {
+  try {
+    const output = execFileSync("git", ["log", "--format=%B%x1e", `${baseRef}..${headRef}`], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return output.split("\x1e").map((message) => message.trim()).filter((message) => message.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+function hasCompleteBypassTrailerSet(results: readonly BypassTrailerValidationResult[]): boolean {
+  return results.some((result) => result.hasAnyBypassTrailer && result.complete);
+}
+
+export async function runBypassAudit(
+  deps: PreCommitDeps,
+  options: BypassAuditOptions = {},
+): Promise<PreCommitResult> {
+  const baseRef = options.baseRef ?? "origin/main";
+  const headRef = options.headRef ?? "HEAD";
+  const changedFiles = options.changedFiles ?? getChangedFilesInRange(baseRef, headRef);
+  const commitMessages = options.commitMessages ?? getCommitMessagesInRange(baseRef, headRef);
+  const syntheticCommitMessage = commitMessages.join("\n\n");
+
+  const result = await runPreCommit(changedFiles, deps, {
+    commitMessage: syntheticCommitMessage,
+    allowConditionalBypass: true,
+    evidenceRoot: options.evidenceRoot,
+  });
+  const bypassResults = await Promise.all(
+    commitMessages.map((message) => validateBypassTrailers(message, options.evidenceRoot)),
+  );
+
+  const sections = [
+    `${BOLD}[phasegate]${RESET} Bypass audit (${baseRef}..${headRef})`,
+    result.stdout,
+  ];
+  let exitCode = result.exitCode;
+  if (result.exitCode !== 0 && !hasCompleteBypassTrailerSet(bypassResults)) {
+    sections.push("");
+    sections.push(`${RED}FAIL${RESET} Gate failure requires complete bypass trailers.`);
+    exitCode = 1;
+  }
+
+  return {
+    exitCode,
+    stdout: sections.join("\n"),
+    blockerClasses: result.blockerClasses,
   };
 }
 
@@ -410,6 +623,41 @@ export async function runCommitMsgCli(commitMessagePath: string | undefined): Pr
       {
         commitMessage,
         implementationExtensions: await loadPreCommitImplementationExtensions(),
+        evidenceRoot: process.cwd(),
+      },
+    );
+
+    process.stdout.write(`${result.stdout}\n`);
+    process.exit(result.exitCode);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${RED}[phasegate] Unexpected error:${RESET} ${msg}\n`);
+    process.exit(2);
+  }
+}
+
+function parseCliFlag(args: readonly string[], flag: string): string | undefined {
+  const index = args.indexOf(flag);
+  if (index === -1 || index + 1 >= args.length) return undefined;
+  return args[index + 1];
+}
+
+export async function runBypassAuditCli(args: readonly string[] = []): Promise<void> {
+  try {
+    const validatorMod = createValidatorSystemModule(await loadValidatorSystemConfig());
+    const traceabilityMod = createTraceabilityModelModule(
+      process.cwd(),
+      await loadTraceabilityModelOptions(),
+    );
+    const result = await runBypassAudit(
+      {
+        runL2ValidatorsUseCase: validatorMod.runL2ValidatorsUseCase,
+        validateMetadataCommandHandler: traceabilityMod.validateMetadataCommandHandler,
+      },
+      {
+        baseRef: parseCliFlag(args, "--base"),
+        headRef: parseCliFlag(args, "--head"),
+        evidenceRoot: process.cwd(),
       },
     );