phasegate 0.15.0

package/docs/ADR/ADR-011-archgate-pattern.md

@@ -0,0 +1,62 @@
+# ADR-011: archgate パターン — L1 ルールによるアーキテクチャ強制
+
+## Status
+
+Accepted
+
+## Context
+
+「ドメイン層は外部フレームワークに依存しない」「全ソースファイルに Unit/Layer 帰属を明示する」といったアーキテクチャルールは、ドキュメントに書いただけでは破られる。特に AI エージェントは利便性を優先してルールを無視する傾向がある。
+
+## Decision
+
+アーキテクチャルールを **実行可能なコード（Biome AST ルール）** として表現する。このパターンを **archgate** と呼ぶ。
+
+### archgate の実装例
+
+```typescript
+// L1-003: no-layer-violation
+// domain/ 配下のファイルが infrastructure/ や presentation/ から import していないか検証
+//
+// 例: 以下のコードは L1-003 違反として検出される
+// scripts/harness/validator-system/domain/services/drift-detection-service.ts
+import { FileSystemAdapter } from '../../infrastructure/adapters/fs-adapter.js';
+//       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+//       L1-003: domain 層から infrastructure 層への import は禁止です
+//
+// 正しいパターン: Port（インターフェース）を経由する
+import type { FileSystemPort } from '../ports/file-system-port.js';
+```
+
+```typescript
+// L1-001: require-unit-comment
+// 全ソースファイルに @unit コメントが必要
+//
+// 違反例:
+export class MyService { }  // L1-001: @unit コメントがありません
+//
+// 正しいパターン:
+/**
+ * @unit validator-system
+ * @layer domain
+ */
+export class MyService { }
+```
+
+### Executable Governance 原則
+
+| ルール | ドキュメント表現 | archgate 表現 |
+|--------|----------------|--------------|
+| レイヤー境界 | 「domain は infrastructure に依存しない」 | `no-layer-violation` が import グラフを解析 |
+| メタデータ | 「全ファイルに @unit を書く」 | `require-unit-comment` が AST で検出 |
+| フォルダ構造 | 「規約に従う」 | `enforce-folder-structure` がパス検証 |
+
+## Consequences
+
+- プロンプトで「願う」のではなくコードで「強制する」
+- 違反はコミット前に検出され、レビューコストが削減される
+- AI エージェントのプロンプト遵守度に品質が依存しない
+
+## 関連要件
+
+K1（4層防御）、K3（Biome AST解析）

package/docs/ADR/ADR-012-two-phase-execution.md

@@ -0,0 +1,38 @@
+# ADR-012: 2-Phase Execution（人間承認ゲート）
+
+## Status
+
+Accepted
+
+## Context
+
+AI エージェントは設計段階で誤った判断を行う可能性がある。設計文書が誤っていれば、その後の実装・テストも全て誤った方向に進む。設計のミスは実装のミスより修正コストが桁違いに高い。
+
+## Decision
+
+全ての設計スキル（domain-designer, logical-designer 等）の出力に **人間の承認を必須** とする 2-Phase Execution パターンを採用する。
+
+### Phase 構成
+
+| Phase | 実行者 | 出力 | 人間承認 |
+|-------|--------|------|---------|
+| Phase 1（計画） | AI | `inception/` 配下の `*_plan.md` | **必須** |
+| Phase 2（実行） | AI | `product/construction/` 配下の設計文書 | Phase 1 承認後に自動実行 |
+
+### Plan 文書の必須生成（K15）
+
+Planning Mode が interactive であれ embedded-qa であれ、全フェーズの Phase 1 は `inception/` 配下に `*_plan.md` を生成して完了する。plan 文書なしの Phase 2 移行は不可。
+
+### QA セクション
+
+設計判断の根拠を `*_plan.md` 内の QA セクションに構造化して保持する。セッションが失われても設計意図が残る。
+
+## Consequences
+
+- AI の設計判断に人間の承認ゲートが挿入される
+- Phase Gate バリデータ（L2-001）が plan 文書の存在を機械的に検証
+- 設計判断の根拠が QA セクションとしてトレーサブルに保持される
+
+## 関連要件
+
+K6（2-Phase Execution）、K15（Plan文書の必須生成）

package/docs/guide/cli-reference.md

@@ -0,0 +1,122 @@
+# Phasegate CLI Reference
+
+Entry point:
+
+```
+npx harness <command> [options]
+```
+
+---
+
+## Setup
+
+| Command | Description |
+|---|---|
+| `init --name <name>` | Deploy skills and generate `phasegate.config.json` |
+| `update-skills` | Re-deploy skills to the latest version |
+| `list-features` | List available features |
+| `enable-feature <name>` | Enable a feature |
+| `disable-feature <name>` | Disable a feature |
+
+---
+
+## Quality Checks
+
+| Command | Options | Description |
+|---|---|---|
+| `lint` | `--target <path>` `--json` | L1 Biome AST check |
+| `validate` | `--layer L1\|L2\|L3\|L4\|all` `--unit <name>` `--format human\|agent\|ci` | L2-L4 validators |
+| `ci-check` | `--quick` `--fail-on-reject` `--dry-run` `--files` | Full CI check (L2-L4) |
+| `validate-metadata <files>` | | Validate implementation metadata |
+| `check-phase-gate` | `--level 1\|2\|3` | Phase gate check |
+
+---
+
+## Harness API
+
+Commands exposed as npm scripts (`npm run <command>`).
+
+| Command | Options | Description |
+|---|---|---|
+| `harness:status` | `--json` | Health summary |
+| `harness:check-ready` | `--json` | Phase Gate pass status for all stories |
+| `harness:check-phase` | `--unit <unitId>` `--json` | Current phase for a unit |
+| `harness:ci-check` | `--json` | All L3 validators |
+| `harness:detect-drift` | `--json` | Design-code drift report |
+| `harness:lint` | `--target <path>` `--json` | Lint via harness-api |
+| `harness:complete-check` | `--json` | L2-L4 full check |
+| `harness:impact-analysis` | `<storyId>` `--json` | Story impact analysis |
+
+---
+
+## ADR Management
+
+| Command | Options | Description |
+|---|---|---|
+| `list-adrs` | `--status Proposed\|Accepted\|Deprecated\|Superseded` | List ADRs |
+| `validate-adr` | `--all` or `<adrRef>` | Validate ADR |
+
+---
+
+## HarnessError
+
+| Command | Options | Description |
+|---|---|---|
+| `list-errors` | `--format human\|json` `--layer L0-L4` | List error definitions |
+| `render-errors` | `--format human\|agent\|ci` | Render errors |
+| `validate-fix` | `--code <code>` | Validate fix code example |
+
+---
+
+## Skill Quality
+
+| Command | Options | Description |
+|---|---|---|
+| `skill:execute-tdd-cycle` | `--unit` `--story` `--desc` `--phase RED\|GREEN\|REFACTOR` `--passed` | Run TDD cycle |
+| `skill:check-coverage` | `--story <storyId>` `--json` | Coverage check |
+| `skill:collect-lessons` | `--story <storyId>` `--sources <paths>` `--write-artifact` | Collect agent lessons |
+| `skill:apply-cascade-update` | `--story <storyId>` `--dry-run` | Cascade update to upstream docs |
+| `skill:validate-structure` | `--file <path>` `--json` | Validate skill structure |
+
+---
+
+## CI/CD
+
+| Command | Options | Description |
+|---|---|---|
+| `ci:generate-template` | `--preset <id>` `--type <type>` `--render` `--json` | Generate CI/CD template |
+| `ci:migrate-agents-md` | `--dry-run` `--validate-only` `--json` | Migrate AGENTS.md to pointer format |
+| `ci:check-repetition` | `--code <errorCode>` `--reset` `--json` | Detect repetitive errors |
+
+---
+
+## Regression Tests
+
+| Command | Description |
+|---|---|
+| `regression:run-k-requirements` | K1-K15 non-negotiable requirements |
+| `regression:run-gng-gate` | Go/No-Go Gate 3 quality conditions |
+| `regression:run-agent-guard` | Agent-independence guard |
+| `regression:run-k14-k15` | K14/K15 regression |
+| `regression:configure-ci-gate` | Configure CI gate |
+| `regression:analyze-migration` | Analyze v0 test migration |
+| `regression:migrate-v0-tests` | Execute v0 test migration |
+
+---
+
+## Hooks Engine
+
+| Command | Options | Description |
+|---|---|---|
+| `hooks:config validate` | | Validate `.harness-hooks.yml` |
+| `hooks:gate-check` | `--story <id>` | Completion gate check |
+
+---
+
+## Phase 2 Extensions
+
+| Command | Options | Description |
+|---|---|---|
+| `p2:check-freshness` | `--pattern <glob>` `--dry-run` `--format text\|json` | Design doc freshness check |
+| `p2:validate-pointers` | `--include-urls` `--format text\|json` | Validate file pointers in docs |
+| `p2:generate-e2e-template` | `--phase <phase>` `--output <path>` | Generate E2E test template |

package/docs/guide/configuration.md

@@ -0,0 +1,199 @@
+# Configuration
+
+## phasegate.config.json
+
+Place at project root. Generated by `npx harness init`.
+
+This file is the **Single Source of Truth** for all quality configuration in a Phasegate project. Every layer validator, skill, and harness behavior reads from this file.
+
+### Full Reference
+
+```jsonc
+{
+  "project": {
+    "name": "my-project",
+    "preset": "standard"       // "minimal" | "standard" | "strict"
+  },
+  "layers": {
+    "L0": { "enabled": false },
+    "L1": { "enabled": true },
+    "L2": { "enabled": true },
+    "L3": { "enabled": true },
+    "L4": { "enabled": false }
+  },
+  "quickMode": {
+    "allowedCategories": ["bugfix", "docs", "test", "config"],
+    "maintainedLayers": ["L1", "L2"],
+    "relaxedGates": ["phase-gate", "2-phase-execution"]
+  },
+  "phaseDependencies": {
+    "preset": "default",       // "default" | "custom"
+    "override": false,
+    "customRules": []
+  },
+  "planningMode": {
+    "default": "interactive",  // "interactive" | "embedded-qa"
+    "perPhase": {}
+  },
+  "harnesses": {
+    "agentLessonCollection": false,
+    "cascadeUpdate": false,
+    "bundleSizeLimit": 0,
+    "deadCodeGC": false
+  },
+  "paths": {
+    "designDocs": "docs/product/construction",
+    "inceptionDocs": "docs/inception"
+  },
+  "reporting": {
+    "format": "json",
+    "outputDir": "reports"
+  }
+}
+```
+
+---
+
+### Presets
+
+| Preset     | Use Case                  | Active Layers | Coverage Threshold |
+|------------|---------------------------|---------------|--------------------|
+| `minimal`  | Learning / prototyping    | L1, L2        | --                 |
+| `standard` | Normal development        | L1, L2, L3    | 90%                |
+| `strict`   | Production / enterprise   | L1--L4        | 95%                |
+
+The `strict` preset also enables:
+
+- **L4 scheduled validation** -- weekly drift-detect and dead-code analysis
+- `agentLessonCollection` -- captures agent mistakes for continuous improvement
+- `bundleSizeLimit` -- 500 KB default cap
+- `deadCodeGC` -- automatic dead-code garbage collection
+
+---
+
+### Field Reference
+
+#### `project`
+
+| Sub-field | Type     | Default      | Description                                                    |
+|-----------|----------|--------------|----------------------------------------------------------------|
+| `name`    | `string` | --           | Project identifier. Used in reports and validation output.     |
+| `preset`  | `string` | `"standard"` | One of `"minimal"`, `"standard"`, `"strict"`. Controls which layers and harnesses are active by default. Individual settings override the preset. |
+
+#### `layers`
+
+Each layer key (`L0` through `L4`) accepts an object with:
+
+| Sub-field | Type      | Default | Description                          |
+|-----------|-----------|---------|--------------------------------------|
+| `enabled` | `boolean` | varies  | Whether this validation layer is active. Defaults depend on the selected preset. |
+
+The five layers are:
+
+| Layer | Name                | Purpose                                      |
+|-------|---------------------|----------------------------------------------|
+| L0    | FUSE hooks          | Real-time file-system event validation        |
+| L1    | Biome AST lint      | Static analysis (naming, imports, metadata)   |
+| L2    | Pre-commit          | Phase-gate and structural checks before commit |
+| L3    | CI                  | Continuous integration quality gates          |
+| L4    | Scheduled           | Periodic drift-detect, dead-code, freshness   |
+
+#### `quickMode`
+
+| Sub-field           | Type       | Default                                 | Description                                                                 |
+|---------------------|------------|-----------------------------------------|-----------------------------------------------------------------------------|
+| `allowedCategories` | `string[]` | `["bugfix", "docs", "test", "config"]`  | Change categories permitted under Quick Mode. Any category outside this list requires the full `story-implementor` workflow. |
+| `maintainedLayers`  | `string[]` | `["L1", "L2"]`                          | Layers that remain fully enforced even in Quick Mode.                       |
+| `relaxedGates`      | `string[]` | `["phase-gate", "2-phase-execution"]`   | Gates that are relaxed (not skipped) when Quick Mode is active.             |
+
+#### `phaseDependencies`
+
+| Sub-field     | Type       | Default     | Description                                                        |
+|---------------|------------|-------------|--------------------------------------------------------------------|
+| `preset`      | `string`   | `"default"` | `"default"` uses the built-in AIDLC phase dependency graph. `"custom"` enables `customRules`. |
+| `override`    | `boolean`  | `false`     | When `true`, custom rules fully replace the default graph instead of extending it. |
+| `customRules` | `array`    | `[]`        | Array of custom phase dependency rules. Only used when `preset` is `"custom"`. |
+
+#### `planningMode`
+
+| Sub-field  | Type     | Default         | Description                                                          |
+|------------|----------|-----------------|----------------------------------------------------------------------|
+| `default`  | `string` | `"interactive"` | `"interactive"` prompts the user at each decision point. `"embedded-qa"` embeds QA checks inline without prompting. |
+| `perPhase` | `object` | `{}`            | Override the planning mode for specific phases. Keys are phase names, values are `"interactive"` or `"embedded-qa"`. |
+
+#### `harnesses`
+
+| Sub-field              | Type      | Default | Description                                                          |
+|------------------------|-----------|---------|----------------------------------------------------------------------|
+| `agentLessonCollection`| `boolean` | `false` | Collect agent mistakes and lessons for feedback loops.               |
+| `cascadeUpdate`        | `boolean` | `false` | Automatically propagate lower-phase discoveries to upstream design docs. |
+| `bundleSizeLimit`      | `number`  | `0`     | Maximum bundle size in KB. `0` disables the check.                   |
+| `deadCodeGC`           | `boolean` | `false` | Enable periodic dead-code detection and cleanup suggestions.         |
+
+#### `paths`
+
+| Sub-field       | Type     | Default                        | Description                                           |
+|-----------------|----------|--------------------------------|-------------------------------------------------------|
+| `designDocs`    | `string` | `"docs/product/construction"`  | Root directory for confirmed design documents (logical design, domain model). |
+| `inceptionDocs` | `string` | `"docs/inception"`             | Root directory for inception-phase documents (stories, unit designs).         |
+
+#### `reporting`
+
+| Sub-field   | Type     | Default     | Description                                           |
+|-------------|----------|-------------|-------------------------------------------------------|
+| `format`    | `string` | `"json"`    | Output format for validation reports.                 |
+| `outputDir` | `string` | `"reports"` | Directory where reports are written.                  |
+
+---
+
+### Quick Mode
+
+Quick Mode is a relaxed execution path for low-risk changes such as bug fixes, documentation edits, test additions, and configuration tweaks. It is activated by the `quick-implementor` skill.
+
+**How it works:**
+
+1. The change category is checked against `quickMode.allowedCategories`. If the category is not in the list, Quick Mode is rejected and the full `story-implementor` workflow is required.
+2. Layers listed in `quickMode.maintainedLayers` remain fully enforced -- typically L1 (AST lint) and L2 (pre-commit checks). This ensures naming conventions, metadata, and test quality are never bypassed.
+3. Gates listed in `quickMode.relaxedGates` have their enforcement loosened. For example, `phase-gate` relaxation means you do not need confirmed design documents (`logical_design.md`, `domain_model.md`) before writing code. The `2-phase-execution` relaxation removes the mandatory Phase 1 (plan) then Phase 2 (implement) sequencing.
+
+**Quick Mode is not allowed for:**
+
+- New feature additions
+- API contract changes
+- New domain model introductions
+
+These always require the full `story-implementor` path with `implementation-readiness-checker` as a prerequisite.
+
+---
+
+### Paths and the AIDLC Document Structure
+
+The `paths` configuration tells Phasegate where to find design documents that serve as implementation prerequisites.
+
+**`designDocs`** points to confirmed construction documents. Under this directory, each Unit has its own folder containing:
+
+- `logical_design.md` -- the logical design for the unit
+- `domain_model.md` -- the domain model definition
+
+The pre-tool-use hook enforces that these files exist before any source code under `scripts/harness/` can be created or structurally modified for a given Unit.
+
+**`inceptionDocs`** points to earlier-phase documents produced during inception: user stories, unit designs, and scope definitions. These are inputs to the design skills but are not directly enforced by runtime hooks.
+
+**Example directory layout:**
+
+```
+docs/
+  product/
+    construction/
+      auth-unit/
+        logical_design.md
+        domain_model.md
+      billing-unit/
+        logical_design.md
+        domain_model.md
+  inception/
+    stories/
+    unit-designs/
+```
+
+If you move your design documents to a non-default location, update `paths` accordingly so that all validators and hooks resolve files correctly.

package/docs/guide/hooks-integration.md

@@ -0,0 +1,105 @@
+# Claude Code Hooks Integration
+
+Phasegate integrates natively with Claude Code through its hooks system. This enables real-time quality enforcement during AI-assisted development.
+
+## Setup
+
+Add the following to `.claude/settings.json`:
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "npx tsx scripts/harness/agent-integration/presentation/pre-tool-use-hook.ts"
+        }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "npx tsx scripts/harness/agent-integration/presentation/post-tool-use-hook.ts"
+        }]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "npx tsx scripts/harness/agent-integration/presentation/stop-hook.ts"
+        }]
+      }
+    ]
+  }
+}
+```
+
+## Hook Behaviors
+
+### PreToolUse (before file write)
+- Enforces Phase Gate: blocks writing to source files if required design documents don't exist
+- Blocks writes to protected files (package.json, biome.json, tsconfig.json)
+- Returns actionable error messages with:
+  - Violation reason
+  - Missing artifacts
+  - Recommended skill to use next
+
+Example error (Phase Gate violation):
+```
+Phase Gate Violation: scripts/harness/config-foundation/domain/test.ts
+Scope: Level 3 (Implementation), Unit: config-foundation
+Blocked because:
+  - Missing artifact: docs/product/construction/config-foundation/domain_model.md
+  - Missing plan: 2:logical-designer
+Next action: Use /story-implementor skill to start from the design phase.
+  Example: /story-implementor --unit config-foundation
+```
+
+Example error (Protected file):
+```
+Write to protected file blocked: package.json
+Use /quick-implementor skill for version changes in package.json.
+```
+
+### PostToolUse (after file write)
+- Runs Biome AST rules automatically
+- Provides immediate feedback on violations
+
+### Stop (before session end)
+- Runs `harness:complete-check` (L2-L4 full validation)
+- Session end is held if checks are not all green
+
+## Optional Shell Script Hooks
+
+Additional hooks can be placed in `.claude/scripts/`:
+
+| Script | Behavior |
+|--------|----------|
+| deny-check.sh | Block dangerous git/bash commands (git reset --hard, rm -rf, etc.) |
+| format-settings-hook.sh | Auto-format settings.json on edit |
+| format-typescript-hook.sh | Auto-format TypeScript files (Biome / ESLint+Prettier) |
+| analyze-errors-hook.sh | Detect tsc/lint errors on TypeScript edit |
+
+### Hook Config
+
+`format-typescript-hook.sh` and `analyze-errors-hook.sh` use `.claude/scripts/hook-config.json`:
+
+```json
+{
+  "targetDirs": ["scripts/harness"],
+  "formatter": "biome",
+  "formatterArgs": ["check", "--write"]
+}
+```
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| targetDirs | Directories where hooks apply (relative to project root) | [] (skip if empty) |
+| formatter | "biome" or "eslint-prettier" | "biome" |
+| formatterArgs | Arguments passed to formatter | ["check", "--write"] |

package/docs/guide/installation.md

@@ -0,0 +1,84 @@
+# Installation
+
+## Prerequisites
+
+- **Node.js** >= 18.0.0
+- **npm** 9+ or **pnpm**
+- **TypeScript** 5.x (included as a devDependency)
+
+## Install from GitHub
+
+```bash
+npm install --save-dev phasegate
+```
+
+Or add it directly to your `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "phasegate": "^0.14.0"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm install
+```
+
+## Project Setup
+
+### 1. Initialize
+
+```bash
+npx harness init --name <project-name>
+```
+
+This deploys 28 skills to `.claude/skills/` and generates `phasegate.config.json`.
+
+### 2. Copy design principle documents
+
+```bash
+cp node_modules/phasegate/docs/folder_management_rules.md docs/
+mkdir -p docs/principles
+cp node_modules/phasegate/docs/principles/*.md docs/principles/
+```
+
+### 3. Create product overview
+
+Create `docs/product/<your_product>_overview.md` as the starting point for AIDLC.
+
+### 4. Start Claude Code
+
+```bash
+claude  # at project root
+```
+
+Run `/product-architect` to begin the AIDLC process.
+
+## Updating
+
+```bash
+npm update phasegate
+npx harness update-skills
+```
+
+## Recommended .gitignore additions
+
+```
+node_modules/
+.claude/skills/    # regenerated by npx harness init
+dist/
+reports/
+.harness/
+```
+
+## Verify Installation
+
+```bash
+npx harness --version
+npx harness lint
+npm run harness:status
+```