phasegate 0.172.0 → 0.177.0

package/CHANGELOG.md

@@ -701,7 +701,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - **WI-085: phase-gate validator (L2-001) が `paths.designDocs` / `paths.inceptionDocs` 設定を尊重しない問題を修正** — 外部レポーター nakataj-mti が GitHub Issue [#1](https://github.com/junpei-9898/phasegate/issues/1) で報告。`paths.designDocs` を `mydocs/...` などのデフォルト外パスに変更しても、L2-001 が要求する成果物パスは `docs/inception/...` / `docs/product/...` のままになる挙動を修正した。`docs/guide/configuration.md` の「`paths` を変えれば全 validator / hook が解決する」記述と実装の齟齬を解消。
-  - **新プレースホルダ**: `Artifact.path` で `{designDocsRoot}` / `{inceptionDocsRoot}` を許可。`Artifact.resolve(scope, pathRoots?)` が `paths.designDocs` / `paths.inceptionDocs` の値（未指定時はデフォルト `docs/product/construction` / `docs/inception`）でこれらを展開するよう拡張（[ADR-016](docs/ADR/ADR-016-paths-config-placeholder.md)）。
+  - **新プレースホルダ**: `Artifact.path` で `{designDocsRoot}` / `{inceptionDocsRoot}` を許可。`Artifact.resolve(scope, pathRoots?)` が `paths.designDocs` / `paths.inceptionDocs` の値（未指定時はデフォルト `docs/product/construction` / `docs/inception`）でこれらを展開するよう拡張（[ADR-016](docs/ADR/016-paths-config-placeholder.md)）。
   - **`docs/` 接頭辞バリデーション撤廃**: `Artifact.create()` の `path` が `docs/` 始まりでなければ `InvalidArtifactPathError` を投げる挙動を削除。プレースホルダ展開後の任意 root（`mydocs/...` 等）を許容するため。許可外プレースホルダの拒否は維持。
   - **新ポートメソッド**: `PhaseConfigProviderPort.getPathRoots(): Promise<{ designDocsRoot, inceptionDocsRoot }>` を追加。`HarnessConfigPhaseConfigProvider` が `paths.designDocs` / `paths.inceptionDocs` 設定を読み（末尾スラッシュは trim）、未指定時はデフォルト値を返す。
   - **流入経路**: `EvidenceBundleAssembler.assembleForLevel` 内で `getPathRoots()` を 1 回呼び、結果を `Artifact.resolve(scope, pathRoots)` および `ArtifactExistenceCheckerPort.checkAll(artifacts, scope, pathRoots)` に渡す。`PhaseInfoResolver.resolve(..., pathRoots?)` でブロッカー表示時にも root プレースホルダを実値に展開。

package/README.md

@@ -386,7 +386,7 @@ For selection guidance and config examples see [Preset Selection Guide](docs/gui
 | `minimal` | None | Disabled -- no inception -> product enforcement | Prototyping / exploration |
 | `custom` | User-defined via `gates[]` array | User-defined via `storyReflection.mappings` | Full control (requires `override: true`) |
 
-`storyReflection` blocks writes to `src/{unit}/*` when an inception US/issue design exists but has not been cascaded into `docs/product/construction/{unit}/`. See [ADR-013](docs/ADR/ADR-013-story-reflection-gate.md) and the [Configuration guide](docs/guide/configuration.md#storyreflection-inception--product-gate).
+`storyReflection` blocks writes to `src/{unit}/*` when an inception US/issue design exists but has not been cascaded into `docs/product/construction/{unit}/`. See [ADR-013](docs/ADR/013-story-reflection-gate.md) and the [Configuration guide](docs/guide/configuration.md#storyreflection-inception--product-gate).
 
 ### Key Configuration Sections
 

package/docs/ADR/{ADR-001-four-layer-defense-model.md → 001-four-layer-defense-model.md}

@@ -1,8 +1,11 @@
-# ADR-001: L1 — Biome AST による Editor-Time 品質強制
+---
+adr_id: "001"
+title: "L1 — Biome AST による Editor-Time 品質強制"
+status: Accepted
+date: 2026-03-24
+---
 
-## Status
-
-Accepted
+# L1 — Biome AST による Editor-Time 品質強制
 
 ## Context
 
@@ -32,3 +35,7 @@ Rust製 Biome の AST 解析を用いて、L1（Editor-Time）で以下の8ル
 ## 関連要件
 
 K1（4層防御モデル）、K3（Biome AST解析）、K3.5（@unit/@layerメタデータ）
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-002-pre-commit-validators.md → 002-pre-commit-validators.md}

@@ -1,8 +1,11 @@
-# ADR-002: L2 — Pre-commit バリデータによる設計-実装順序の強制
+---
+adr_id: "002"
+title: "L2 — Pre-commit バリデータによる設計-実装順序の強制"
+status: Accepted
+date: 2026-03-24
+---
 
-## Status
-
-Accepted
+# L2 — Pre-commit バリデータによる設計-実装順序の強制
 
 ## Context
 
@@ -36,3 +39,7 @@ L2（Pre-commit）で以下のバリデータにより設計-実装の順序、
 ## 関連要件
 
 K2（Phase Gate）、K3.5（メタデータ）、K4（テスト品質ルール）、K14（Phase Dependency Model）
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-003-ci-validators.md → 003-ci-validators.md}

@@ -1,8 +1,11 @@
-# ADR-003: L3 — CI バリデータによるセキュリティ・パフォーマンス・カバレッジ検証
+---
+adr_id: "003"
+title: "L3 — CI バリデータによるセキュリティ・パフォーマンス・カバレッジ検証"
+status: Accepted
+date: 2026-03-24
+---
 
-## Status
-
-Accepted
+# L3 — CI バリデータによるセキュリティ・パフォーマンス・カバレッジ検証
 
 ## Context
 
@@ -34,3 +37,7 @@ L3（CI/CD）で以下の4バリデータを実行する。
 ## 関連要件
 
 K1（4層防御）、K10（Security/Performance検出）
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-004-scheduled-validators.md → 004-scheduled-validators.md}

@@ -1,8 +1,11 @@
-# ADR-004: L4 — Scheduled バリデータによる設計-実装乖離の定期検出
+---
+adr_id: "004"
+title: "L4 — Scheduled バリデータによる設計-実装乖離の定期検出"
+status: Accepted
+date: 2026-03-24
+---
 
-## Status
-
-Accepted
+# L4 — Scheduled バリデータによる設計-実装乖離の定期検出
 
 ## Context
 
@@ -36,3 +39,7 @@ L4（Scheduled）で以下のバリデータを週次または明示実行で扱
 ## 関連要件
 
 K1（4層防御）、K11（Drift Detection）、K12（Consistency Checker）
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-005-hexagonal-architecture.md → 005-hexagonal-architecture.md}

@@ -1,8 +1,11 @@
-# ADR-005: Hexagonal Architecture（Ports & Adapters）の採用
+---
+adr_id: "005"
+title: "Hexagonal Architecture（Ports & Adapters）の採用"
+status: Accepted
+date: 2026-03-24
+---
 
-## Status
-
-Accepted
+# Hexagonal Architecture（Ports & Adapters）の採用
 
 ## Context
 
@@ -37,3 +40,7 @@ presentation/    — CLI コマンド、フォーマッター
 ## 関連要件
 
 K1（4層防御、L1-003）、K5（DDD設計スキル群）
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-006-agent-independence.md → 006-agent-independence.md}

@@ -1,8 +1,11 @@
-# ADR-006: エージェント非依存設計原則
+---
+adr_id: "006"
+title: "エージェント非依存設計原則"
+status: Accepted
+date: 2026-03-24
+---
 
-## Status
-
-Accepted
+# エージェント非依存設計原則
 
 ## Context
 
@@ -32,3 +35,7 @@ Quality Harness の全バリデータは **ファイルシステムに書き込
 ## 関連要件
 
 K13（phasegate.config.json）
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-007-harness-config-single-source.md → 007-harness-config-single-source.md}

@@ -1,13 +1,18 @@
-# ADR-007: phasegate.config.json を品質設定の Single Source of Truth とする
+---
+adr_id: "007"
+title: "phasegate.config.json を品質設定の Single Source of Truth とする"
+status: Accepted
+date: 2026-03-24
+---
 
-## Status
-
-Accepted
+# phasegate.config.json を品質設定の Single Source of Truth とする
 
 ## Context
 
 品質設定が複数のファイル（ESLint 設定、テスト設定、CI 設定）に分散すると、設定間の矛盾が発生し、プリセット（minimal/standard/strict）の切り替えが困難になる。
 
+> §12 Key Decision: config-file-separation
+
 ## Decision
 
 `phasegate.config.json` を品質設定の唯一の真実源とする。
@@ -37,3 +42,7 @@ Ownership が完全に分離され、設定の混在を防止する。
 ## 関連要件
 
 K13（phasegate.config.json）
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-008-quick-mode.md → 008-quick-mode.md}

@@ -1,13 +1,18 @@
-# ADR-008: Quick Mode の適用条件と範囲
+---
+adr_id: "008"
+title: "Quick Mode の適用条件と範囲"
+status: Accepted
+date: 2026-03-24
+---
 
-## Status
-
-Accepted
+# Quick Mode の適用条件と範囲
 
 ## Context
 
 1行のバグ修正にフルハーネス（設計文書作成 → テスト設計 → Phase Gate）を要求すると、開発速度が不必要に低下する。一方で、品質ゲートの緩和を安易に拡大すると品質基盤が形骸化する。
 
+> §12 Key Decision: quick-mode-eligibility
+
 ## Decision
 
 Quick Mode として明確に定義された条件下でのみ、ハーネスの一部を緩和する。
@@ -44,3 +49,7 @@ Quick Mode として明確に定義された条件下でのみ、ハーネスの
 ## 関連要件
 
 K1（4層防御）
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-009-ddd-tactical-patterns.md → 009-ddd-tactical-patterns.md}

@@ -1,8 +1,11 @@
-# ADR-009: DDD 戦術パターン（Entity/VO/Aggregate）の採用
+---
+adr_id: "009"
+title: "DDD 戦術パターン（Entity/VO/Aggregate）の採用"
+status: Accepted
+date: 2026-03-24
+---
 
-## Status
-
-Accepted
+# DDD 戦術パターン（Entity/VO/Aggregate）の採用
 
 ## Context
 
@@ -38,3 +41,7 @@ DDD 戦術パターンを全 Unit のドメイン層に適用する。
 ## 関連要件
 
 K5（DDD設計スキル群）
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-010-harness-error-fix-example.md → 010-harness-error-fix-example.md}

@@ -1,13 +1,18 @@
-# ADR-010: HarnessError に fix_example を必須化（エージェント自己修正設計）
+---
+adr_id: "010"
+title: "HarnessError に fix_example を必須化（エージェント自己修正設計）"
+status: Accepted
+date: 2026-03-24
+---
 
-## Status
-
-Accepted
+# HarnessError に fix_example を必須化（エージェント自己修正設計）
 
 ## Context
 
 AIエージェントがエラーメッセージを受け取った際、「何が悪いか」だけでなく「どう直すか」が明示されていれば、人間の介入なしに自己修正できる。従来の Lint エラーは問題の指摘のみで修正方法を示さないため、「エラー発生→人間が読解→人間が AI に修正指示→AI 修正」という長いループが必要だった。
 
+> §12 Key Decision: harness-error-fix-example
+
 ## Decision
 
 全ての `HarnessError` に以下のフィールドを必須化する。
@@ -40,3 +45,7 @@ interface HarnessError {
 ## 関連要件
 
 K1（4層防御）
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-011-archgate-pattern.md → 011-archgate-pattern.md}

@@ -1,8 +1,11 @@
-# ADR-011: archgate パターン — L1 ルールによるアーキテクチャ強制
+---
+adr_id: "011"
+title: "archgate パターン — L1 ルールによるアーキテクチャ強制"
+status: Accepted
+date: 2026-03-24
+---
 
-## Status
-
-Accepted
+# archgate パターン — L1 ルールによるアーキテクチャ強制
 
 ## Context
 
@@ -60,3 +63,7 @@ export class MyService { }
 ## 関連要件
 
 K1（4層防御）、K3（Biome AST解析）
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-012-two-phase-execution.md → 012-two-phase-execution.md}

@@ -1,8 +1,11 @@
-# ADR-012: 2-Phase Execution（人間承認ゲート）
+---
+adr_id: "012"
+title: "2-Phase Execution（人間承認ゲート）"
+status: Accepted
+date: 2026-03-24
+---
 
-## Status
-
-Accepted
+# 2-Phase Execution（人間承認ゲート）
 
 ## Context
 
@@ -36,3 +39,7 @@ Planning Mode が interactive であれ embedded-qa であれ、全フェーズ
 ## 関連要件
 
 K6（2-Phase Execution）、K15（Plan文書の必須生成）
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-013-story-reflection-gate.md → 013-story-reflection-gate.md}

@@ -1,8 +1,11 @@
-# ADR-013: storyReflection ゲート（inception → product 反映の機械強制）
+---
+adr_id: "013"
+title: "storyReflection ゲート（inception → product 反映の機械強制）"
+status: Accepted
+date: 2026-04-05
+---
 
-## Status
-
-Accepted
+# storyReflection ゲート（inception → product 反映の機械強制）
 
 ## Context
 
@@ -98,3 +101,7 @@ inception/order/US-002/logical_design.md は存在しますが、
 - ADR-008（Quick Mode）— storyReflection も `relaxedGates` で緩和される
 - ADR-012（2-Phase Execution）— storyReflection は Phase 2 完了の事後条件に相当
 - `docs/folder_management_rules.md` — inception / product の累積更新フロー
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-014-presentation-domain-dependency.md → 014-presentation-domain-dependency.md}

@@ -1,8 +1,11 @@
-# ADR-014: presentation → domain 直接依存を許容する（Robert C. Martin 版 Clean Architecture 準拠）
+---
+adr_id: "014"
+title: "presentation → domain 直接依存を許容する（Robert C. Martin 版 Clean Architecture 準拠）"
+status: Accepted
+date: 2026-04-23
+---
 
-## Status
-
-Accepted — 2026-04-23
+# presentation → domain 直接依存を許容する（Robert C. Martin 版 Clean Architecture 準拠）
 
 ## Context
 
@@ -80,3 +83,13 @@ const ALLOWED_DEPENDENCIES = {
 - ADR-009 (DDD Tactical Patterns) — domain immutability 規約で mutation リスクを抑止
 - ISSUE-019 (LayerBoundary 再評価) — 本 ADR で CLOSED
 - ISSUE-014 (architecture style config) — preset 化での opt-in 厳格派提供を予定
+
+## Alternatives
+
+本 ADR は既存本文で 3 つのアーキテクチャ解釈を比較しており（正規化時に canonical `## Alternatives` として再掲）:
+
+1. **Robert C. Martin 版 Clean Architecture（採用）** — `presentation → domain` の read-only 依存を許容する。
+2. **厳格 DDD Layered** — `presentation` は `application` 経由でのみ `domain` に触れる。read-only の VO/type/policy 参照まで false positive として弾くため不採用（ただし将来 `strict-ddd` preset で opt-in 提供予定）。
+3. **phasegate 旧実装（厳格 DDD 派）** — 実装時の暗黙判断。本 ADR で置き換える。
+
+比較の詳細は上記 Context「哲学的立場の整理」および Decision を参照。

package/docs/ADR/{ADR-015-architecture-preset.md → 015-architecture-preset.md}

@@ -1,8 +1,11 @@
-# ADR-015: アーキテクチャスタイルを preset 化し、PhaseGate を複数アーキに対応させる
+---
+adr_id: "015"
+title: "アーキテクチャスタイルを preset 化し、PhaseGate を複数アーキに対応させる"
+status: Accepted
+date: 2026-04-23
+---
 
-## Status
-
-Accepted — 2026-04-23
+# アーキテクチャスタイルを preset 化し、PhaseGate を複数アーキに対応させる
 
 ## Context
 
@@ -181,3 +184,7 @@ schema v3 移行の詳細は Wave 2 で `config-foundation` の migration script
 - **ISSUE-007 retrofit-adoption** — 既存 PJ への phasegate 導入。本 ADR により Clean 以外でも受け入れ可能になり、retrofit の適用範囲が拡大
 - **`scripts/harness/biome-ast-engine/domain/value-objects/layer-name.ts:6,15-20`** — 現状のハードコード実体、Wave 2 の改修対象
 - **`scripts/harness/config-foundation/infrastructure/schemas/harness-config-v2.schema.json`** — schema v3 の拡張対象、Wave 3 で改修
+
+## Alternatives
+
+当時、代替案は明示的に文書化されていない。本節は既存決定を `validate-adr` ゲートで検査可能にするための遡及的正規化（コーパス正規化）に伴い追加された。

package/docs/ADR/{ADR-016-paths-config-placeholder.md → 016-paths-config-placeholder.md}

@@ -1,8 +1,11 @@
-# ADR-016: phase-gate validator のパス解決を `paths` config プレースホルダ化する
+---
+adr_id: "016"
+title: "phase-gate validator のパス解決を `paths` config プレースホルダ化する"
+status: Accepted
+date: 2026-05-07
+---
 
-## Status
-
-Accepted — 2026-05-07
+# phase-gate validator のパス解決を `paths` config プレースホルダ化する
 
 ## Context
 
@@ -153,3 +156,12 @@ phase-gate validator のパスリテラルを `{designDocsRoot}` / `{inceptionDo
 - **`scripts/harness/agent-integration/infrastructure/adapters/phase-gate-query-adapter.ts:60`** — 同上
 - **`docs/guide/configuration.md:445-471`** — 利用者の期待を形成しているドキュメント記述
 - **ADR-007** — harness-config を Single Source of Truth とする決定。本 ADR は ADR-007 の精神（config から validator を駆動する）を phase-gate validator に拡張するもの
+
+## Alternatives
+
+本 ADR は既存本文の「検討した代替案」に代替案を記録済みである（正規化時に canonical `## Alternatives` として再掲）:
+
+1. **(A) `paths.designDocs` / `paths.inceptionDocs` でトップレベルパスを実際に置換する（採用）** — phase-gate validator のパスリテラルをプレースホルダ化し `paths` config で展開する。
+2. **(B) ドキュメントを修正し「`paths.*` は storyReflection 専用」と明記する** — `Artifact` の `docs/` 接頭辞バリデーションが残るため現状コードでは動作せず、(A) と実装コストの大半が重複するため不採用。
+
+採用理由の詳細は上記 Decision「採用理由」を参照。

package/docs/ADR/{ADR-017-warning-severity-aggregation.md → 017-warning-severity-aggregation.md}

@@ -1,8 +1,11 @@
-# ADR-017: warning-severity validator の集計セマンティクス
+---
+adr_id: "017"
+title: "warning-severity validator の集計セマンティクス"
+status: Accepted
+date: 2026-05-08
+---
 
-## Status
-
-Accepted — 2026-05-08
+# warning-severity validator の集計セマンティクス
 
 ## Context
 
@@ -200,3 +203,12 @@ human/agent/ci formatter で `[FAIL]` と `[WARN]` を分離:
 - **`scripts/harness/config-foundation/application/mappers/validator-system-config-mapper.ts`** — `toValidatorSystemConfig` 拡張対象
 - **ADR-007** — harness-config Single Source of Truth。本 ADR は `failOnWarning` を CLI flag のみから config まで持ち上げて ADR-007 の精神を強化
 - **ADR-001** — 4 層防御モデル。L4 validator の advisory 位置付けが本決定の根拠
+
+## Alternatives
+
+本 ADR は既存本文の「検討した代替案」に代替案を記録済みである（正規化時に canonical `## Alternatives` として再掲）:
+
+1. **(A) warning-only fail は overall PASS / exit 0 を default にする（採用）** — 集計ロジックを修正し warning-only fail を fail にカウントせず、`failOnWarning: true` で旧挙動へ opt-in。
+2. **(B) warning も exit 1 を default に保つ（CI 互換性優先）** — default を変えず移行コストはゼロだが、`defaultSeverity: warning` 宣言と「常に fail」実装の semantic 乖離が残るため不採用。
+
+採用理由の詳細は上記 Decision「採用理由」を参照。

package/docs/ADR/{ADR-018-drift-detect-pointers.md → 018-drift-detect-pointers.md}

@@ -1,8 +1,11 @@
-# ADR-018: drift-detect の design pointers 仕様
+---
+adr_id: "018"
+title: "drift-detect の design pointers 仕様"
+status: Accepted
+date: 2026-05-08
+---
 
-## Status
-
-Accepted — 2026-05-08
+# drift-detect の design pointers 仕様
 
 ## Context
 
@@ -45,3 +48,10 @@ GitHub Issue #4 の follow-up として WI-095 を起票した。
 `DesignDocumentPort` は後方互換のため既存 `getElements()` を維持し、optional な `getElementPointers()` を追加する。`SourceCodeAnalyzerPort` も optional な `getElementFilePathMap()` を追加する。両 optional port が未実装の場合、`DriftDetectionService` は従来挙動のまま動作する。
 
 YAML fenced metadata は今回採用しない。Markdown本文の構造と混ざりやすく、既存のコードブロック抽出や設計例との衝突リスクが高いため、必要になった時点で別ADRで拡張する。
+
+## Alternatives
+
+本 ADR は既存本文で採用しなかった代替案を 1 件明記している（正規化時に canonical `## Alternatives` として再掲）:
+
+1. **見出し単位で対応実装ファイル path を明示する `pointers`（採用）** — HTML コメント形式と `<pointers>` タグ形式の 2 形式を受け付ける。
+2. **YAML fenced metadata で pointer を表現する（不採用）** — Markdown 本文の構造と混ざりやすく、既存のコードブロック抽出や設計例との衝突リスクが高いため今回は採用せず、必要になった時点で別 ADR で拡張するとした。

package/docs/ADR/022-package-separation.md

@@ -0,0 +1,29 @@
+---
+adr_id: "022"
+title: "パッケージ分離 — Quality Harness / Orchestration"
+status: Accepted
+date: 2026-03-11
+---
+
+# パッケージ分離 — Quality Harness / Orchestration
+
+## Context
+
+phasegate の品質ハーネスは、特定の AI エージェントやオーケストレーション基盤に依存せず、単独で品質防御を提供できるべきである（ADR-006「エージェント非依存」）。品質ハーネスとオーケストレーション（エージェントの起動・タスク割り当て・ワークフロー制御）を同一パッケージに結合すると、品質の移植性が損なわれ、オーケストレーション基盤を変更・撤去した際に品質防御も道連れになる。
+
+> §12 Key Decision: package-separation
+
+## Decision
+
+品質ハーネスを担う **Quality-Harness パッケージ（本リポジトリ）** と、エージェント制御を担う **Orchestration パッケージ** を分離する。
+
+- 品質設定は `phasegate.config.json` に、オーケストレーション設定は `orchestration.config.json` に置く（ADR-007）。
+- 両パッケージは相互に所有し合わない。Quality-Harness は Orchestration の設定・コードを一切含まない。
+
+## Consequences
+
+- 本リポジトリには orchestration のコード・設定が意図的に不在である。この不在そのものが分離の証跡となる。
+- 品質防御が特定のオーケストレーション基盤から独立して移植可能になる。
+- 非交渉要件 K1-K13 は全て品質ハーネス側に帰属する（ADR-024）。オーケストレーション側へ品質責務が漏れない。
+
+関連: ADR-006（エージェント非依存設計原則）、ADR-007（設定ファイルの Single Source of Truth と設定ファイル分離）、ADR-024（K1-K13 の品質ハーネス帰属）。

package/docs/ADR/023-eslint-to-biome-migration.md

@@ -0,0 +1,28 @@
+---
+adr_id: "023"
+title: "ESLint→Biome 全面移行"
+status: Accepted
+date: 2026-03-11
+---
+
+# ESLint→Biome 全面移行
+
+## Context
+
+v0 の L1 静的検査は ESLint に 4 つのカスタムルールを載せた構成だった。ESLint は JavaScript 実装であり、大規模コーパスに対する実行速度が遅く、フィードバックループの短縮を阻害していた。
+
+> §12 Key Decision: eslint-to-biome
+
+## Decision
+
+L1 の静的検査エンジンを Rust 製の **Biome** へ全面移行する。
+
+- v0 の 4 カスタムルールを Biome の AST ルールとして移植する。
+- ESLint 由来のレガシー成果物（設定・依存）は能動的に拒否し、回帰を防止する。
+
+## Consequences
+
+- L1 エンジンは Biome となり、ADR-001 の 8 ルールを Biome AST 上で実行する。ESLint 比で 50-100 倍高速なフィードバックが得られる。
+- `scripts/harness/biome-ast-engine/application/usecases/verify-eslint-removal-usecase.ts` が ESLint 成果物の残存を検出し、`LegacyEslintArtifactDetectedError` を throw して ESLint への回帰を機械的に防ぐ。
+
+関連: ADR-001（4層防御モデル / L1 の 8 ルール）。

package/docs/ADR/024-k-requirements-quality-ownership.md

@@ -0,0 +1,26 @@
+---
+adr_id: "024"
+title: "K1-K13 の品質ハーネス帰属"
+status: Accepted
+date: 2026-03-11
+---
+
+# K1-K13 の品質ハーネス帰属
+
+## Context
+
+phasegate の非交渉要件 K1-K13 は、いずれも品質に関する要件である。パッケージ分離（ADR-022）により品質ハーネスとオーケストレーションが分離された結果、各 K 要件の所有者を一意に定める必要がある。所有が曖昧だと、要件がオーケストレーション側へ漏れて品質防御の移植性が損なわれる。
+
+> §12 Key Decision: k-requirements-quality-ownership
+
+## Decision
+
+K1-K13 を全て品質ハーネス側に帰属させ、オーケストレーション側へ分散させない。
+
+## Consequences
+
+- 各 K 要件は品質ハーネスのレイヤ／バリデータに対応づけられる（例: K1=4層防御=ADR-001、L3=ADR-003、L4=ADR-004、archgate=ADR-011）。
+- 要件の充足は archgate パターン（ADR-011）を通じて機械的に強制される。
+- オーケストレーション基盤を差し替えても K 要件の充足責務は品質ハーネス側に残り、移植性が保たれる（ADR-006）。
+
+関連: ADR-006（エージェント非依存設計原則）、ADR-011（archgate パターン）、ADR-022（パッケージ分離）。

package/docs/ADR/025-fuse-hooks-engine-out-of-scope.md

@@ -0,0 +1,26 @@
+---
+adr_id: "025"
+title: "FUSE Hooks Engine は v1 スコープ外"
+status: Accepted
+date: 2026-03-11
+---
+
+# FUSE Hooks Engine は v1 スコープ外
+
+## Context
+
+ファイルシステムレベル（FUSE ベース）で横断的にファイル操作を捕捉する Hooks Engine を横断基盤として検討した。しかし、Core Value（設計意図とコードの構造的整合性の機械的保証）は L1-L4 の防御層で維持可能であり、FUSE のような重い横断基盤を v1 に含める必然性はなかった。
+
+> §12 Key Decision: fuse-out-of-scope
+
+## Decision
+
+FUSE Hooks Engine を v1 のスコープ外とし、横断基盤としては別途検討へ defer する。
+
+## Consequences
+
+- その後 L0 は FUSE ではなく **エージェントランタイムのフック + git フックのエンジン**（`agent-integration` ユニット + Husky）として実現された。詳細は `docs/guide/layer-model.md` §L0 を参照。
+- FUSE 自体は依然として defer された選択肢のままであり、採用も棄却もされていない。
+- L0 を後から追加する拡張パス（ADR-029）は、この defer を前提に設計された。
+
+関連: ADR-001（4層防御モデル）、ADR-029（L0 4層→5層復帰パス）。

package/docs/ADR/026-nyquist-truths-artifacts-integration.md

@@ -0,0 +1,25 @@
+---
+adr_id: "026"
+title: "Nyquist 統合 — GSD-2 Truths/Artifacts 検証パターン"
+status: Accepted
+date: 2026-03-11
+---
+
+# Nyquist 統合 — GSD-2 Truths/Artifacts 検証パターン
+
+## Context
+
+要件から成果物へのトレーサビリティ検証は、GSD-2 における Truths/Artifacts パターンとして既に存在していた。概念的に同一の検証（要件→成果物トレーサビリティ）を phasegate 側で二重実装すると、検証ロジックが分岐し、整合性の保証が困難になる。
+
+> §12 Key Decision: nyquist-truths-artifacts
+
+## Decision
+
+GSD-2 の Truths/Artifacts 検証パターンを Nyquist バリデータ（L3-004）へ統合し、再実装しない。
+
+## Consequences
+
+- `scripts/harness/validator-system/domain/value-objects/validator-id.ts` において `L3-004` が `nyquist` に対応づけられている。
+- AC レベルのトレーサビリティアダプタが、fail-closed な L3 ゲートと advisory な L4 層の両方を提供する。同一の検証概念を一箇所へ集約することで検証の分岐を防ぐ。
+
+関連: ADR-003（CI バリデータ / L3）、ADR-018（drift-detect ポインタ）。

package/docs/ADR/027-artifact-driven-state-derivation.md

@@ -0,0 +1,25 @@
+---
+adr_id: "027"
+title: "成果物駆動の状態導出"
+status: Accepted
+date: 2026-03-11
+---
+
+# 成果物駆動の状態導出
+
+## Context
+
+ハーネスの検査状態（各レイヤの健全性・フェーズゲートの状態）は再現可能であるべきである。可変な保存状態（別途書き込む state ファイル）に依存すると、実際のディスク上の成果物と state が乖離し、状態が信頼できなくなる。GSD-2 は成果物から状態を導出する優れたパターンを持っていた。
+
+> §12 Key Decision: artifact-driven-state
+
+## Decision
+
+ハーネスの検査状態を、ディスク上の成果物から導出する（GSD-2 パターンの再利用）。可変な保存状態を真実源としない。
+
+## Consequences
+
+- `scripts/harness/harness-api/domain/services/status-derivation-service.ts` が `ArtifactScanResult` から `LayerHealth` および `HarnessStatusSummary` を導出する。
+- `check-phase` / `check-ready` 系のコマンドは成果物を読んで状態を判定するため、状態が常にディスクの実態と一致し、再現可能になる。
+
+関連: ADR-012（2-Phase Execution）、ADR-018（drift-detect ポインタ）。

package/docs/ADR/028-validator-stack-detection.md

@@ -0,0 +1,26 @@
+---
+adr_id: "028"
+title: "バリデータ無限ループ防止 — スタック検出"
+status: Accepted
+date: 2026-03-11
+---
+
+# バリデータ無限ループ防止 — スタック検出
+
+## Context
+
+同一の `HarnessError` が繰り返し発生する状況では、バリデータとエージェントの間で自己修正ループが無限に回り、エージェントのサイクルを浪費する。GSD-2 のスタック検出パターンは、この種の反復を検出して打ち切る仕組みを持っていた。
+
+> §12 Key Decision: validator-stack-detection
+
+## Decision
+
+同一 `HarnessError` の繰り返しを検出し、閾値を超えた場合に自動エスカレーションする（GSD-2 スタック検出パターンの応用）。
+
+## Consequences
+
+- `ci-governance` ユニット（H13-02）で実装済み。`RepetitionDetector`、`RecordErrorOccurrenceUseCase`、`CheckEscalationUseCase`、エスカレーションログにより、同一エラーの反復を検出しエスカレーションする。
+- 加えて stop-hook の `ReentryGuard`（`agent-integration` ユニット）がフックの再入ループを防止する。
+- **STATUS NOTE**: §12 は当初この決定を "Pending" としていたが、実装が完了しているため本 ADR は Accepted とする。§12 側の Status も本作業（WI-230 Step 3）で "Decided" に訂正した。
+
+関連: ADR-003（CI バリデータ）、ADR-004（scheduled バリデータ）。

package/docs/ADR/029-four-to-five-layer-return-path.md

@@ -0,0 +1,25 @@
+---
+adr_id: "029"
+title: "L0 4層→5層復帰パス"
+status: Accepted
+date: 2026-03-11
+---
+
+# L0 4層→5層復帰パス
+
+## Context
+
+FUSE ベースの L0 を v1 スコープ外へ defer した（ADR-025）ため、非交渉要件 K1 を一時的に 4 層（L1-L4）で定義した。将来 L0 を追加した際に既存の 4 層定義が障害とならないよう、4層から 5層への拡張パスをあらかじめ明示しておく必要があった。
+
+> §12 Key Decision: four-to-five-layer-path
+
+## Decision
+
+4層→5層の拡張パスを明示的に定義する。将来の L0 追加を阻害しない形で K1 の層構造を段階的に拡張できるようにする。
+
+## Consequences
+
+- 5層への復帰は既に達成されている。`docs/guide/layer-model.md` は現在 "5-Layer Defense Model (L0-L4)" を記述し、L0 は FUSE ではなく hooks engine（`agent-integration` + Husky）として実現されている（ADR-025）。
+- 一方で ADR-001（"four-layer-defense-model"、K1=4層）は 5層の現実に遅れている。ADR-001 の見直しは本作業のスコープ外であり、follow-up として別途行う必要がある。
+
+関連: ADR-001（4層防御モデル）、ADR-025（FUSE Hooks Engine は v1 スコープ外）。

package/docs/guide/configuration.md

@@ -461,7 +461,7 @@ Override the preset defaults only when your project needs a different policy:
 2. `WriteTargetScope` resolves the `@unit` annotation (comma-separated and multi-line `@unit` are both supported; **all** listed units are checked).
 3. For each unit, every `storyId` directory under `docs/inception/{unit}/` is enumerated.
 4. For each required mapping, the pre-tool-use hook checks that the target product document contains `@story-id {storyId}`.
-5. Any missing reflection produces a `STORY_REFLECTION` block reason with a fix hint that points to the `cascade-updater` skill and [ADR-013](../ADR/ADR-013-story-reflection-gate.md).
+5. Any missing reflection produces a `STORY_REFLECTION` block reason with a fix hint that points to the `cascade-updater` skill and [ADR-013](../ADR/013-story-reflection-gate.md).
 
 ##### Passing the gate
 

package/docs/guide/preset-selection.md

@@ -165,6 +165,6 @@ npx phasegate migrate --schema v3
 
 - `docs/inception/issues/ISSUE-014/wave1_schema_proposal.md` — 設計提案とプリセット詳細
 - `docs/inception/issues/ISSUE-014/issue_description.md` — issue 背景
-- `docs/ADR/ADR-015-architecture-preset.md` — アーキ設計決定
+- `docs/ADR/015-architecture-preset.md` — アーキ設計決定
 - `docs/guide/retrofit-adoption.md` — 既存 PJ への後付け導入
 - `docs/guide/configuration.md` — 他の config 項目

package/docs/guide/retrofit-adoption.md

@@ -325,5 +325,5 @@ sha1 一致で判定しているため、**フォーマット変更・インポ
 
 - `docs/guide/cli-reference.md` — `baseline` / `scaffold-design` のフラグ一覧
 - `docs/guide/layer-model.md` — L0-L4 防御モデルと phase-gate の位置付け
-- `docs/ADR/ADR-013-story-reflection-gate.md` — phase-gate の思想的背景
+- `docs/ADR/013-story-reflection-gate.md` — phase-gate の思想的背景
 - ISSUE-007 — 本ガイドが対応する起票 issue（`docs/inception/issues/ISSUE-007/`）

package/package.json

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