phasegate 0.15.0

package/README.md

@@ -0,0 +1,254 @@
+# Phasegate
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+
+**Phasegate -- AI-agnostic quality defense toolkit.**
+
+Enforces structural integrity between design intent and code, regardless of which AI agent you use.
+
+---
+
+## Why Phasegate?
+
+AI coding agents are fast but unconstrained. They skip design steps, violate layer boundaries, and produce code that drifts from intent. Phasegate solves this with a portable, agent-independent defense layer that makes it **physically impossible** to implement without design, commit without validation, or merge without traceability.
+
+Works with **Claude Code, Codex, Cursor, Copilot**, or any other AI agent.
+
+---
+
+## Features
+
+| Feature | Description |
+|---|---|
+| **5-Layer Defense Model** | L0 through L4 validators from editor time to scheduled audits |
+| **28 AIDLC Skills** | Full coverage from product architecture to story implementation |
+| **Phase Dependency Model** | Blocks implementation when required design documents are missing |
+| **Quick Mode** | Lightweight gate for bugfixes, docs, tests, and config changes |
+| **Claude Code Hooks** | Native PreToolUse / PostToolUse / Stop hook integration |
+| **HarnessError Format** | Every error includes ADR references and fix examples for AI self-correction |
+| **Presets** | minimal, standard, and strict -- choose your quality level |
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install --save-dev phasegate
+```
+
+### 2. Initialize
+
+```bash
+npx harness init --name my-project
+```
+
+This deploys 28 skills to `.claude/skills/` and generates `phasegate.config.json`.
+
+### 3. Copy design principles
+
+```bash
+cp node_modules/phasegate/docs/folder_management_rules.md docs/
+mkdir -p docs/principles
+cp node_modules/phasegate/docs/principles/*.md docs/principles/
+```
+
+### 4. Start the AIDLC
+
+Launch your AI agent and run the `/product-architect` skill to begin.
+
+---
+
+## 5-Layer Defense Model
+
+```
++------------------------------------------------------------------+
+|  L0  HOOKS ENGINE          Agent hook configuration              |
++------------------------------------------------------------------+
+|  L1  EDITOR TIME           Biome AST rules                       |
+|  require-unit-comment, no-layer-violation, no-any-abuse,         |
+|  enforce-folder-structure, no-ghost-file, no-code-duplication    |
++------------------------------------------------------------------+
+|  L2  PRE-COMMIT            Validators                            |
+|  phase-gate, metadata completeness, test-quality (AAA pattern)   |
++------------------------------------------------------------------+
+|  L3  CI/CD                 Validators                            |
+|  security, performance, coverage threshold, nyquist traceability |
++------------------------------------------------------------------+
+|  L4  SCHEDULED             Validators                            |
+|  drift-detection, consistency-check, dead-code analysis          |
++------------------------------------------------------------------+
+```
+
+| Layer | Trigger | Key Checks |
+|---|---|---|
+| L0 | Agent hooks | Hook config validation, gate checks |
+| L1 | Editor save / lint | Import graph, layer violations, AI anti-patterns |
+| L2 | Pre-commit | Phase gate, `@unit`/`@layer` metadata, test quality |
+| L3 | CI/CD pipeline | Security, performance, coverage (90%/95%), requirements traceability |
+| L4 | Scheduled (weekly) | Design-code drift, cross-document consistency, dead code |
+
+---
+
+## 28 Skills
+
+Skills cover the full **AIDLC (AI-Driven Development Life Cycle)**, enforcing phase dependencies so that implementation cannot begin without design.
+
+### Foundation (4)
+
+| Skill | Purpose |
+|---|---|
+| `/product-architect` | Define product vision, domains, architecture, and constraints |
+| `/story-writer` | Create Who/What/Why user stories with acceptance criteria |
+| `/story-mapper` | Prioritize stories and define MVP scope |
+| `/unit-designer` | Group stories into independently buildable Units |
+
+### Design (5)
+
+| Skill | Purpose |
+|---|---|
+| `/domain-designer` | DDD tactical design -- aggregates, entities, value objects, events |
+| `/logical-designer` | Hexagonal architecture design (ports and adapters) |
+| `/mock-designer` | UI mockup design for early validation |
+| `/uiux-designer` | Final UI/UX definition from test cases and logical design |
+| `/environment-designer` | Local dev environment and infrastructure design |
+
+### Test Engineering (7)
+
+| Skill | Purpose |
+|---|---|
+| `/unit-test-designer` | Unit test case design from domain models |
+| `/it-test-designer` | Integration test case design from logical design |
+| `/scenario-test-designer` | E2E scenario test case design |
+| `/unit-test-logic-designer` | Vitest implementation logic with pseudocode |
+| `/it-test-logic-designer` | Integration test Vitest implementation logic |
+| `/scenario-test-logic-designer` | Playwright E2E implementation logic |
+| `/test-coverage-checker` | Coverage verification and Nyquist validation |
+
+### Implementation (4)
+
+| Skill | Purpose |
+|---|---|
+| `/story-implementor` | TDD implementation (Red-Green-Refactor) with atomic commits |
+| `/quick-implementor` | Lightweight implementation for bugfixes, docs, tests, config |
+| `/implementation-planner` | Implementation plan from Unit specs and domain models |
+| `/implementation-readiness-checker` | Pre-implementation readiness verification |
+
+### Verification (8)
+
+| Skill | Purpose |
+|---|---|
+| `/consistency-checker` | Cross-layer consistency check across design documents |
+| `/cascade-updater` | Propagate lower-phase discoveries to upstream design docs |
+| `/codex-delegator` | Delegate tasks to Codex CLI with quality oversight |
+| `/codebase-mapper` | Generate structure map from `@unit`/`@layer` annotations |
+| `/doc-freshness-checker` | Design document staleness detection (L4 extension) |
+| `/pointer-validator` | Validate file path references in design documents |
+| `/engineering-perspective` | Multi-perspective design review (Beck, Fowler, Martin, Evans) |
+| `/skill-creator` | Create or update agent skills |
+
+---
+
+## Configuration
+
+`phasegate.config.json` is the **Single Source of Truth** for quality settings.
+
+### Presets
+
+| Preset | Layers | Coverage | Use Case |
+|---|---|---|---|
+| `minimal` | L1 + L2 | -- | Prototyping, early exploration |
+| `standard` | L1 - L3 | 90% | Production development (default) |
+| `strict` | L1 - L4 | 95% | Mission-critical systems |
+
+### Key Configuration Sections
+
+```jsonc
+{
+  "preset": "standard",
+  "project": { "name": "my-project", "architecture": "clean-architecture" },
+  "layers": {
+    "L1_editor":    { "enabled": true },
+    "L2_precommit": { "enabled": true },
+    "L3_ci":        { "enabled": true },
+    "L4_scheduled": { "enabled": false }
+  },
+  "quickMode": {
+    "allowedCategories": ["bugfix", "docs", "test", "config"],
+    "maintainedLayers": ["L1", "L2"]
+  },
+  "phaseDependencies": { "preset": "default" }
+}
+```
+
+---
+
+## Claude Code Hooks Integration
+
+Phasegate integrates natively with Claude Code via hooks in `.claude/settings.json`:
+
+| Hook | Trigger | Behavior |
+|---|---|---|
+| `PreToolUse` | `Write` or `Edit` | Blocks writes to source files without design docs; runs Biome lint |
+| `PostToolUse` | `Write` or `Edit` | Auto-formats and validates metadata |
+| `Stop` | Session end | Runs full test suite to ensure all tests pass |
+
+All hook errors use the `HarnessError` format with ADR references and fix examples, enabling AI agents to self-correct without human intervention.
+
+---
+
+## CLI Reference
+
+```bash
+npx harness <command> [options]
+```
+
+| Command | Description |
+|---|---|
+| `init --name <name>` | Initialize project, deploy skills, generate config |
+| `lint` | Run L1 Biome AST checks |
+| `validate --layer <L1-L4\|all>` | Run validators for specified layer |
+| `ci-check` | Full CI check (L2-L4) |
+| `update-skills` | Update skills to latest version |
+| `harness:status` | Display overall harness health summary |
+| `harness:check-phase --unit <id>` | Check current phase for a Unit |
+| `list-errors --layer <L0-L4>` | List error definitions with fix examples |
+
+See the [Japanese README](README.ja.md) for the complete CLI reference.
+
+---
+
+## Documentation
+
+Detailed guides are available under `docs/guide/`:
+
+- [Installation](docs/guide/installation.md) -- Detailed install and setup instructions
+- [Configuration](docs/guide/configuration.md) -- `phasegate.config.json` full reference
+- [CLI Reference](docs/guide/cli-reference.md) -- All CLI commands and options
+- [Skills Overview](docs/guide/skills-overview.md) -- 28 skills with AIDLC execution order
+- [5-Layer Defense Model](docs/guide/layer-model.md) -- L0-L4 layer details and HarnessError format
+- [Hooks Integration](docs/guide/hooks-integration.md) -- Claude Code Hooks setup and behavior
+
+Additional resources:
+
+- `docs/principles/architecture-philosophy.md` -- Architecture philosophy
+- `docs/principles/testing-rules.md` -- Testing conventions
+- `docs/ADR/` -- Architecture Decision Records
+
+---
+
+## Contributing
+
+Contributions are welcome. Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before submitting a pull request.
+
+---
+
+## License
+
+[Apache License 2.0](LICENSE)
+
+---
+
+[Japanese version / 日本語版](README.ja.md)

package/bin/harness

@@ -0,0 +1,18 @@
+#!/bin/sh
+# GSDLC Harness CLI entry point
+# tsx を使って scripts/harness/main.ts を実行するラッパー
+
+# このスクリプトの実体ファイルの場所を解決する（シンボリックリンク対応）
+SCRIPT_PATH="$(realpath "$0" 2>/dev/null || readlink -f "$0" 2>/dev/null || echo "$0")"
+PACKAGE_DIR="$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd)"
+MAIN_TS="$PACKAGE_DIR/scripts/harness/main.ts"
+
+# tsx を探す: npx経由の場合はnode_modules/.binがPATHに入っているので command -v で見つかる
+if command -v tsx >/dev/null 2>&1; then
+  exec tsx "$MAIN_TS" "$@"
+elif [ -f "$PACKAGE_DIR/node_modules/.bin/tsx" ]; then
+  exec "$PACKAGE_DIR/node_modules/.bin/tsx" "$MAIN_TS" "$@"
+else
+  echo "Error: tsx not found. Run: npm install" >&2
+  exit 1
+fi

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

@@ -0,0 +1,34 @@
+# ADR-001: L1 — Biome AST による Editor-Time 品質強制
+
+## Status
+
+Accepted
+
+## Context
+
+AIエージェントが生成するコードのアーキテクチャ違反（レイヤー境界越え、メタデータ欠落、不適切なファイル配置）をプロンプトベースの指示だけで防ぐことは不可能である。プロンプト遵守率はエージェントやモデルに依存し、品質が確率的になる。
+
+## Decision
+
+Rust製 Biome の AST 解析を用いて、L1（Editor-Time）で以下の8ルールを機械的に強制する。
+
+| ルール | コード | 検出対象 |
+|--------|--------|---------|
+| require-unit-comment | L1-001 | `@unit` コメント欠落 |
+| require-layer-comment | L1-002 | `@layer` コメント欠落 |
+| no-layer-violation | L1-003 | レイヤー境界を越える import |
+| enforce-folder-structure | L1-004 | アーキテクチャ規約違反のファイル配置 |
+| no-any-abuse | L1-005 | `any` 型の乱用 |
+| no-ghost-file | L1-006 | import されないファイル |
+| no-comment-flood | L1-007 | 過剰なコメント |
+| no-code-duplication | L1-008 | 構造的に重複するコードブロック |
+
+## Consequences
+
+- エージェントのプロンプト遵守度に品質が依存しない
+- Rust 製 Biome により 50-100 倍の高速 AST 解析が可能
+- import グラフ解析によりレイヤー違反を物理的に検出
+
+## 関連要件
+
+K1（4層防御モデル）、K3（Biome AST解析）、K3.5（@unit/@layerメタデータ）

package/docs/ADR/ADR-002-pre-commit-validators.md

@@ -0,0 +1,35 @@
+# ADR-002: L2 — Pre-commit バリデータによる設計-実装順序の強制
+
+## Status
+
+Accepted
+
+## Context
+
+AIエージェントは設計文書を無視して直接コードを書くことがある。設計→実装の順序を守らないと、設計意図とコードが乖離し、トレーサビリティが崩壊する。
+
+## Decision
+
+L2（Pre-commit）で以下の3バリデータにより設計-実装の順序を機械的に強制する。
+
+| バリデータ | コード | 検出対象 |
+|-----------|--------|---------|
+| phase-gate | L2-001 | 設計文書なしの実装コード変更を拒否 |
+| metadata | L2-002 | @unit/@layer/@US-XXX メタデータの完全性検証 |
+| test-quality | L2-003 | AAA パターン、actual 命名、日本語テスト名の検証 |
+
+### Phase Gate の3層検証
+
+1. Level 間の依存違反（Level 2 の前提なしに Level 3 開始）
+2. Level 内の上流設計なしの下流設計生成
+3. 設計文書・plan 文書なしの実装コード変更
+
+## Consequences
+
+- 設計文書なしのコード変更が物理的に不可能になる
+- `@US-XXX` によるトレーサビリティが機械的に保証される
+- テスト品質ルール（AAA, actual 命名）が全テストに強制される
+
+## 関連要件
+
+K2（Phase Gate）、K3.5（メタデータ）、K4（テスト品質ルール）、K14（Phase Dependency Model）

package/docs/ADR/ADR-003-ci-validators.md

@@ -0,0 +1,36 @@
+# ADR-003: L3 — CI バリデータによるセキュリティ・パフォーマンス・カバレッジ検証
+
+## Status
+
+Accepted
+
+## Context
+
+セキュリティ脆弱性（ハードコードされた秘密情報）、パフォーマンス問題（ループ内 await）、テストカバレッジ不足は、Editor-Time や Pre-commit では検出コストが高く、CI パイプラインでの検証が適切である。
+
+## Decision
+
+L3（CI/CD）で以下の4バリデータを実行する。
+
+| バリデータ | コード | 検出対象 |
+|-----------|--------|---------|
+| security | L3-001 | ハードコード秘密情報、SQL インジェクションパターン |
+| performance | L3-002 | ループ内 await（TypeScript AST）、バンドルサイズ超過 |
+| coverage | L3-003 | テストカバレッジ閾値（standard: 90%, strict: 95%） |
+| nyquist | L3-004 | 要件→テスト双方向トレーサビリティ |
+
+### 技術的実装
+
+- **security**: 正規表現パターンマッチング（API key, password, secret token パターン）
+- **performance**: TypeScript Compiler API (`ts.createProgram`) による AST レベルの await-in-loop 検出
+- **nyquist**: `@story` メタデータと受け入れ基準の双方向マッピング検証
+
+## Consequences
+
+- セキュリティ脆弱性が PR マージ前に検出される
+- パフォーマンス問題が AST レベルで正確に検出される（正規表現ではなく構文木解析）
+- 要件→テストのトレーサビリティが Nyquist Validation で体系的に保証される
+
+## 関連要件
+
+K1（4層防御）、K10（Security/Performance検出）

package/docs/ADR/ADR-004-scheduled-validators.md

@@ -0,0 +1,35 @@
+# ADR-004: L4 — Scheduled バリデータによる設計-実装乖離の定期検出
+
+## Status
+
+Accepted
+
+## Context
+
+日常の開発では L1-L3 のゲートで品質が維持されるが、時間の経過とともに設計文書とコードの乖離（ドリフト）、文書間の不整合、未使用コードの蓄積が発生する。これらは即座に検出する必要はないが、放置すると技術的負債として蓄積する。
+
+## Decision
+
+L4（Scheduled）で以下の3バリデータを週次で実行する。
+
+| バリデータ | コード | 検出対象 |
+|-----------|--------|---------|
+| drift-detect | L4-001 | 設計にあるがコードにない / コードにあるが設計にない双方向乖離 |
+| consistency-check | L4-002 | 文書間のレイヤー整合性の破綻 |
+| dead-code | L4-003 | 未使用エクスポート、到達不能コード |
+
+### 技術的実装
+
+- **drift-detect**: `DriftDetectionService` が設計文書のエレメント（Markdown 解析）とコードのエクスポート（TypeScript Compiler API）を比較
+- **consistency-check**: `ConsistencyCheckService` が設計文書間の @layer アノテーション整合性を検証
+- **dead-code**: `DeadCodeDetectionService` が import グラフ解析で未参照エクスポートを検出
+
+## Consequences
+
+- 設計-実装の乖離が週次で自動検出される
+- 未使用コードの蓄積が防止される
+- strict プリセットでのみ L4 が有効（standard/minimal ではスキップ）
+
+## 関連要件
+
+K1（4層防御）、K11（Drift Detection）、K12（Consistency Checker）

package/docs/ADR/ADR-005-hexagonal-architecture.md

@@ -0,0 +1,39 @@
+# ADR-005: Hexagonal Architecture（Ports & Adapters）の採用
+
+## Status
+
+Accepted
+
+## Context
+
+Quality Harness はエージェント非依存であり、外部システム（ファイルシステム、Biome CLI、Git、テストランナー）との結合を疎に保つ必要がある。また、各バリデータのビジネスロジック（ドメイン層）をインフラストラクチャの詳細から独立させることで、テスタビリティと移植性を確保したい。
+
+## Decision
+
+全 Unit に Hexagonal Architecture（Ports & Adapters パターン）を適用する。
+
+```
+domain/          — Entity, VO, Service, Port（インターフェース）
+application/     — UseCase, DTO, Mapper
+infrastructure/  — Port の実装（Adapter）、外部システム接続
+presentation/    — CLI コマンド、フォーマッター
+```
+
+### 依存方向の規則
+
+- `domain` は他のどのレイヤーにも依存しない
+- `application` は `domain` にのみ依存する
+- `infrastructure` は `domain` の Port を実装する
+- `presentation` は `application` の UseCase を呼び出す
+
+この規則は L1-003 `no-layer-violation` ルールにより機械的に強制される。
+
+## Consequences
+
+- ドメインロジックが外部依存から完全に独立する
+- Port を差し替えることでテスト時にモックが容易
+- L1 バリデータが import グラフ解析でレイヤー違反を自動検出
+
+## 関連要件
+
+K1（4層防御、L1-003）、K5（DDD設計スキル群）

package/docs/ADR/ADR-006-agent-independence.md

@@ -0,0 +1,34 @@
+# ADR-006: エージェント非依存設計原則
+
+## Status
+
+Accepted
+
+## Context
+
+AIエージェントのエコシステムは急速に変化する。Claude Code、Codex、Cursor、GSD-2、将来の未知のエージェント — いずれで開発しても品質基準は不変でなければならない。品質保証がエージェント固有の仕組み（プロンプト遵守、特定の Hook API）に依存すれば、エージェント変更のたびに品質基盤が崩壊する。
+
+## Decision
+
+Quality Harness の全バリデータは **ファイルシステムに書き込まれた成果物のみ** を検査対象とし、エージェント固有の API やプロトコルには依存しない。
+
+### 設計原則
+
+1. バリデータはファイルパス・ファイル内容・AST のみを入力とする
+2. エージェントの種類を識別するコードを含まない
+3. `phasegate.config.json` はエージェント非依存の品質設定のみを管理する
+4. CI/CD テンプレートは汎用的な Git Hook + CLI コマンドで構成する
+
+### 検証方法
+
+回帰テスト `run-agent-independence-guard-usecase.test.ts` により、エージェント固有依存の混入を自動検出する。
+
+## Consequences
+
+- エージェントが変わっても品質基準は不変
+- 既存プロジェクトへの導入が容易（エージェント固有のセットアップ不要）
+- 回帰テストによりエージェント依存の混入を継続的に防止
+
+## 関連要件
+
+K13（phasegate.config.json）

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

@@ -0,0 +1,39 @@
+# ADR-007: phasegate.config.json を品質設定の Single Source of Truth とする
+
+## Status
+
+Accepted
+
+## Context
+
+品質設定が複数のファイル（ESLint 設定、テスト設定、CI 設定）に分散すると、設定間の矛盾が発生し、プリセット（minimal/standard/strict）の切り替えが困難になる。
+
+## Decision
+
+`phasegate.config.json` を品質設定の唯一の真実源とする。
+
+### スキーマ構成（v2）
+
+- `project.preset`: `"minimal"` | `"standard"` | `"strict"`
+- `layers.L1-L4`: 各レイヤーの有効/無効とバリデータ設定
+- `quickMode`: Quick Mode の適用条件
+- `phaseDependencies`: Phase Dependency Model のカスタマイズ
+- `harnesses`: 品質ハーネス固有設定（bundleSizeLimit 等）
+- `paths`: 設計文書パス
+
+### パッケージ分離
+
+- `phasegate.config.json`: 品質設定のみ（Quality Harness 管轄）
+- `orchestration.config.json`: オーケストレーション設定（別パッケージ管轄）
+
+Ownership が完全に分離され、設定の混在を防止する。
+
+## Consequences
+
+- プリセット切り替えが1ファイルの変更で完結する
+- JSON Schema によるバリデーション（`ValidateConfigUseCase`）で設定の整合性を保証
+- オーケストレーション設定との混在が物理的に不可能
+
+## 関連要件
+
+K13（phasegate.config.json）

package/docs/ADR/ADR-008-quick-mode.md

@@ -0,0 +1,46 @@
+# ADR-008: Quick Mode の適用条件と範囲
+
+## Status
+
+Accepted
+
+## Context
+
+1行のバグ修正にフルハーネス（設計文書作成 → テスト設計 → Phase Gate）を要求すると、開発速度が不必要に低下する。一方で、品質ゲートの緩和を安易に拡大すると品質基盤が形骸化する。
+
+## Decision
+
+Quick Mode として明確に定義された条件下でのみ、ハーネスの一部を緩和する。
+
+### 適用条件
+
+| 適用（Quick Mode 可） | 除外（フルハーネス必須） |
+|----------------------|----------------------|
+| バグ修正 | 新機能追加 |
+| ドキュメント修正 | API 契約変更 |
+| テスト追加 | 新ドメインモデル追加 |
+| 設定変更 | レイヤー構造の変更 |
+
+### 緩和範囲
+
+| レイヤー | 通常モード | Quick Mode |
+|---------|----------|-----------|
+| L1 | 全8ルール | **全維持** |
+| L2 | 3バリデータ | metadata + test-quality 維持、**phase-gate 緩和** |
+| L3 | 4バリデータ | **security のみ** |
+| L4 | 3バリデータ | **スキップ** |
+| 2-Phase Execution | 必須 | **緩和** |
+
+### 防波堤
+
+`phasegate.config.json` の `quickMode.allowedCategories` で適用条件を明示。条件外の変更には自動拒否する。
+
+## Consequences
+
+- 軽微な変更の開発速度が最大化される
+- 品質ゲート緩和の範囲が厳格に定義され、拡大圧力への防波堤となる
+- Quick Mode でも L1 全ルールと L2 metadata/test-quality は維持される
+
+## 関連要件
+
+K1（4層防御）

package/docs/ADR/ADR-009-ddd-tactical-patterns.md

@@ -0,0 +1,40 @@
+# ADR-009: DDD 戦術パターン（Entity/VO/Aggregate）の採用
+
+## Status
+
+Accepted
+
+## Context
+
+品質ハーネスのドメインモデルは複数の概念（バリデータ、エラー、設定、トレーサビリティ）を含む。これらの概念を適切にモデリングし、不変条件を強制するための構造化手法が必要である。
+
+## Decision
+
+DDD 戦術パターンを全 Unit のドメイン層に適用する。
+
+### 適用パターン
+
+| パターン | 適用例 |
+|---------|-------|
+| **Value Object** | `ErrorCode`, `Severity`, `ValidatorId`, `RuleName`, `FilePath`, `AdrRef` |
+| **Entity** | `ErrorDefinition`, `RuleDefinition`, `HookDefinition` |
+| **Aggregate** | `LintReport`, `ValidationResult`, `HarnessConfig` |
+| **Domain Service** | `DriftDetectionService`, `ConsistencyCheckService`, `LintRunner` |
+| **Port（インターフェース）** | `SecurityPatternScannerPort`, `PerformanceScannerPort` |
+
+### Value Object の設計原則
+
+- 不変（`Object.freeze` または `readonly`）
+- ファクトリメソッド（`create`/`fromString`）でバリデーション
+- 等値比較（`equals`）をサポート
+- 無効な値はコンストラクタで即座に拒否
+
+## Consequences
+
+- ドメインの不変条件がコンパイル時に強制される
+- 型安全な値オブジェクトにより、文字列の誤用が防止される
+- domain-designer スキルにより一貫したパターンで設計可能
+
+## 関連要件
+
+K5（DDD設計スキル群）

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

@@ -0,0 +1,42 @@
+# ADR-010: HarnessError に fix_example を必須化（エージェント自己修正設計）
+
+## Status
+
+Accepted
+
+## Context
+
+AIエージェントがエラーメッセージを受け取った際、「何が悪いか」だけでなく「どう直すか」が明示されていれば、人間の介入なしに自己修正できる。従来の Lint エラーは問題の指摘のみで修正方法を示さないため、「エラー発生→人間が読解→人間が AI に修正指示→AI 修正」という長いループが必要だった。
+
+## Decision
+
+全ての `HarnessError` に以下のフィールドを必須化する。
+
+```typescript
+interface HarnessError {
+  code: string;           // "L1-001", "L2-001" 等
+  severity: 'error' | 'warning';
+  message: string;        // 人間可読な説明
+  suggestion: string;     // 修正方法の提案（テキスト）
+  adr_ref?: string;       // 関連 ADR への参照（"ADR-001" 等）
+  fix_example?: string;   // 修正コード例
+}
+```
+
+### adr_ref の設計
+
+エラーの「なぜそのルールが存在するか」を ADR で説明する。エージェントはエラーの背景を理解した上で修正できる。
+
+### fix_example の設計
+
+具体的な修正コード例を提供し、エージェントが「パターンマッチ」で自己修正できるようにする。
+
+## Consequences
+
+- 「エラー発生→AI 自己修正」の短縮ループが実現する
+- エラーメッセージの品質が ADR + fix_example により体系的に保証される
+- fix_example 自体のテスト資産化により、不正な修正例を CI で検出可能
+
+## 関連要件
+
+K1（4層防御）