phasegate 0.15.0 → 0.31.0

package/docs/guide/configuration.md

@@ -2,7 +2,7 @@
 
 ## phasegate.config.json
 
-Place at project root. Generated by `npx harness init`.
+Place at project root. Generated by `npx phasegate 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.
 
@@ -27,9 +27,14 @@ This file is the **Single Source of Truth** for all quality configuration in a P
     "relaxedGates": ["phase-gate", "2-phase-execution"]
   },
   "phaseDependencies": {
-    "preset": "default",       // "default" | "custom"
+    "preset": "standard",      // "full" | "standard" | "minimal" | "custom" ("default" -> "full")
     "override": false,
-    "customRules": []
+    "customRules": [],
+    "gates": [],               // Optional. Custom phase gates (preset: "custom"). See gates[] reference below.
+    "storyReflection": {       // Optional. Defaults per preset when omitted.
+      "enabled": true,
+      "mappings": []           // Omit to use the preset's built-in mappings.
+    }
   },
   "planningMode": {
     "default": "interactive",  // "interactive" | "embedded-qa"
@@ -108,11 +113,243 @@ The five layers are:
 
 #### `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"`. |
+| Sub-field          | Type       | Default      | Description                                                        |
+|--------------------|------------|--------------|--------------------------------------------------------------------|
+| `preset`           | `string`   | `"standard"` | One of `"full"`, `"standard"`, `"minimal"`, `"custom"`. `"default"` is accepted for backward compatibility and falls back to `"full"`. |
+| `override`         | `boolean`  | `false`      | When `true`, custom rules fully replace the default graph instead of extending it. Required when `preset` is `"custom"`. |
+| `customRules`      | `array`    | `[]`         | Array of custom phase dependency rules. Only used when `preset` is `"custom"`. |
+| `gates`            | `array`    | `[]`         | Array of custom phase gate definitions. See [gates\[\]](#gates-custom-phase-gates) below. Optional; defaults to empty. |
+| `storyReflection`  | `object`   | preset-based | See [storyReflection](#storyreflection-inception--product-gate) below. Omit entirely for zero-config defaults per preset. |
+
+##### Phase Dependency Presets
+
+| Preset     | Phase 3 Gates | storyReflection default                                                 | Use Case                                           |
+|------------|---------------|-------------------------------------------------------------------------|----------------------------------------------------|
+| `full`     | All gates     | **Enabled** -- `logical_design.md` + `domain_model.md` required, `uiux_design.md` optional | AIDLC full ceremony; mission-critical systems      |
+| `standard` | Core gates    | **Enabled** -- `logical_design.md` required, `domain_model.md` optional | Production development with moderate rigor        |
+| `minimal`  | None          | **Disabled**                                                            | Prototyping / exploration (trade-off: no reflection enforcement) |
+| `custom`   | User-defined  | User-defined (zero or explicit `mappings`)                              | Full control via `customRules` and `storyReflection.mappings` |
+
+> `"default"` is accepted as an alias for `"full"` so existing `phasegate.config.json` files keep working after the upgrade.
+
+#### `gates[]` (custom phase gates)
+
+`gates[]` lets a project declare **additional phase gates** that fire when a write targets specific file globs. Each gate is checked at the pre-tool-use hook (and via `check-phase-gate` CLI) and blocks the write if its preconditions are not met.
+
+`gates[]` is typically combined with `preset: "custom"` and `override: true` when the project wants full control over the phase dependency graph. It is also valid to layer a small number of gates on top of `preset: "custom"` without replacing the full graph.
+
+**Validation is fail-fast**: a malformed `gates[]` entry (e.g. `level: 99`, unknown dependency) causes `loadResolvedConfig()` to exit with code `2` and prints `Invalid phasegate.config.json: ...` to stderr. The same error surfaces as a `blocker` in the hook path.
+
+##### Gate definition schema
+
+Each entry in `gates[]` is an object with:
+
+| Field             | Type       | Required | Description                                                                                                       |
+|-------------------|------------|----------|-------------------------------------------------------------------------------------------------------------------|
+| `name`            | `string`   | yes      | Unique gate identifier. Must match `^[a-z][a-z0-9-]*$`.                                                           |
+| `level`           | `integer`  | yes      | Phase level this gate belongs to. One of `1`, `2`, `3`.                                                           |
+| `requires`        | `object[]` | yes      | Required artifacts. Each entry is `{ "path": "<glob or path>", "required": <boolean> }`.                          |
+| `blocks`          | `string[]` | yes      | Glob patterns of files the gate guards. A write targeting any matching file triggers this gate.                  |
+| `dependsOn`       | `string[]` | yes      | Names of other gates that must pass first. Forms a DAG; cycles are rejected at load time.                         |
+| `storyAnnotation` | `object`   | no       | `{ "required": <boolean>, "tag": "<tag-name>" }`. When `required: true`, matched files must contain the tag (e.g. `@story-id H01-01`). Only valid when `level: 3`. |
+
+**Rules:**
+
+- `name` must be unique across the whole `gates[]` array.
+- `level` is restricted to `1`, `2`, or `3`. `level: 99` or similar is a schema violation.
+- `dependsOn` must reference existing gate names and must not form a cycle.
+- `storyAnnotation` may only appear on `level: 3` gates (schema-enforced).
+- `blocks` uses picomatch glob syntax (e.g. `"src/**/*.ts"`, `"scripts/harness/order/**"`).
+
+##### Example 1 — single level-3 story gate
+
+Enforce that any write under `scripts/harness/order/**` carries an `@story-id` annotation:
+
+```jsonc
+{
+  "phaseDependencies": {
+    "preset": "custom",
+    "override": true,
+    "customRules": [],
+    "gates": [
+      {
+        "name": "order-story-impl",
+        "level": 3,
+        "requires": [
+          { "path": "docs/product/user_stories.md", "required": true }
+        ],
+        "blocks": ["scripts/harness/order/**/*.ts"],
+        "dependsOn": [],
+        "storyAnnotation": { "required": true, "tag": "@story-id" }
+      }
+    ]
+  }
+}
+```
+
+##### Example 2 — diamond DAG with multiple chains
+
+Two level-1 gates feed into a level-2 aggregate, which gates a level-3 implementation:
+
+```jsonc
+{
+  "phaseDependencies": {
+    "preset": "custom",
+    "override": true,
+    "customRules": [],
+    "gates": [
+      {
+        "name": "logical-design",
+        "level": 1,
+        "requires": [
+          { "path": "docs/product/construction/{unit}/logical_design.md", "required": true }
+        ],
+        "blocks": [],
+        "dependsOn": []
+      },
+      {
+        "name": "domain-model",
+        "level": 1,
+        "requires": [
+          { "path": "docs/product/construction/{unit}/domain_model.md", "required": true }
+        ],
+        "blocks": [],
+        "dependsOn": []
+      },
+      {
+        "name": "tdd-plan",
+        "level": 2,
+        "requires": [
+          { "path": "docs/inception/{unit}/{storyId}/tdd_implementation_plan.md", "required": true }
+        ],
+        "blocks": [],
+        "dependsOn": ["logical-design", "domain-model"]
+      },
+      {
+        "name": "story-impl",
+        "level": 3,
+        "requires": [],
+        "blocks": ["scripts/harness/**/*.ts"],
+        "dependsOn": ["tdd-plan"],
+        "storyAnnotation": { "required": true, "tag": "@story-id" }
+      }
+    ]
+  }
+}
+```
+
+##### Example 3 — minimal level-1 gate (no storyAnnotation)
+
+Block commits that touch a protected path unless a design artifact exists — no story-id enforcement:
+
+```jsonc
+{
+  "phaseDependencies": {
+    "preset": "custom",
+    "override": true,
+    "customRules": [],
+    "gates": [
+      {
+        "name": "schema-guard",
+        "level": 1,
+        "requires": [
+          { "path": "docs/schema/migration-notes.md", "required": true }
+        ],
+        "blocks": ["db/migrations/**/*.sql"],
+        "dependsOn": []
+      }
+    ]
+  }
+}
+```
+
+#### `storyReflection` (inception -> product gate)
+
+`storyReflection` enforces that every US / issue under `docs/inception/{unit}/{storyId}/` has been **cascaded into the accumulating product design documents** (`docs/product/construction/{unit}/`) before source code under `src/{unit}/` or `scripts/harness/{unit}/` can be written or edited.
+
+The check fires at the pre-tool-use hook and blocks `Write`/`Edit` (and their Bash equivalents such as `cat > file`, `tee`, heredoc, `sed -i`, `cp`, `mv`, `touch`) whenever an inception design exists but its `@story-id` is not reflected in the corresponding product file.
+
+**Zero-config**: omitting the `storyReflection` block, or specifying it without `mappings`, applies the preset's built-in mappings automatically.
+
+| Sub-field   | Type       | Default                 | Description                                                                  |
+|-------------|------------|-------------------------|------------------------------------------------------------------------------|
+| `enabled`   | `boolean`  | preset-dependent        | Master switch. `full` / `standard` default to `true`; `minimal` defaults to `false`. |
+| `mappings`  | `array`    | preset-dependent        | Array of inception -> product file mappings. Omit to use the preset default. |
+
+Each mapping entry:
+
+| Field       | Type      | Description                                                                 |
+|-------------|-----------|-----------------------------------------------------------------------------|
+| `inception` | `string`  | Template path, e.g. `"docs/inception/{unit}/{storyId}/logical_design.md"`. |
+| `product`   | `string`  | Template path, e.g. `"docs/product/construction/{unit}/logical_design.md"`.|
+| `required`  | `boolean` | When `true`, missing reflection blocks the write. When `false`, it is tolerated (optional mapping). |
+
+##### Preset defaults (hard-coded)
+
+**`full`** -- AIDLC recommended (product-accumulated design documents only; test designs are out of scope because they live per-US inside `inception/`):
+
+```jsonc
+[
+  { "inception": "docs/inception/{unit}/{storyId}/logical_design.md",
+    "product":   "docs/product/construction/{unit}/logical_design.md",
+    "required": true },
+  { "inception": "docs/inception/{unit}/{storyId}/domain_model.md",
+    "product":   "docs/product/construction/{unit}/domain_model.md",
+    "required": true },
+  { "inception": "docs/inception/{unit}/{storyId}/uiux_design.md",
+    "product":   "docs/product/construction/{unit}/uiux_design.md",
+    "required": false }
+]
+```
+
+**`standard`**:
+
+```jsonc
+[
+  { "inception": "docs/inception/{unit}/{storyId}/logical_design.md",
+    "product":   "docs/product/construction/{unit}/logical_design.md",
+    "required": true },
+  { "inception": "docs/inception/{unit}/{storyId}/domain_model.md",
+    "product":   "docs/product/construction/{unit}/domain_model.md",
+    "required": false }
+]
+```
+
+**`minimal`**: `enabled: false`. No storyReflection checking.
+
+##### Custom mappings example
+
+Override the preset defaults only when your project needs a different policy:
+
+```jsonc
+{
+  "phaseDependencies": {
+    "preset": "standard",
+    "storyReflection": {
+      "enabled": true,
+      "mappings": [
+        { "inception": "docs/inception/{unit}/{storyId}/logical_design.md",
+          "product":   "docs/product/construction/{unit}/logical_design.md",
+          "required": true }
+      ]
+    }
+  }
+}
+```
+
+##### How the check fires
+
+1. `Write` / `Edit` (or a Bash write such as `cat > src/order/foo.ts`) targets a source file under a Unit.
+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).
+
+##### Passing the gate
+
+`cascade-updater` is the **standard means of passing the storyReflection gate**: run it to propagate the new US / issue design into the accumulating product documents. Manual editing of the product file with an appended `@story-id` tag is also accepted.
+
+Quick Mode with `relaxedGates: ["phase-gate"]` relaxes `storyReflection` as well (see [Quick Mode](#quick-mode)). L1 and L2 `metadata` / `test-quality` checks remain fully enforced.
 
 #### `planningMode`
 

package/docs/guide/hooks-integration.md

@@ -72,7 +72,7 @@ Use /quick-implementor skill for version changes in package.json.
 - Provides immediate feedback on violations
 
 ### Stop (before session end)
-- Runs `harness:complete-check` (L2-L4 full validation)
+- Runs `phasegate:complete-check` (L2-L4 full validation)
 - Session end is held if checks are not all green
 
 ## Optional Shell Script Hooks

package/docs/guide/installation.md

@@ -33,7 +33,7 @@ npm install
 ### 1. Initialize
 
 ```bash
-npx harness init --name <project-name>
+npx phasegate init --name <project-name>
 ```
 
 This deploys 28 skills to `.claude/skills/` and generates `phasegate.config.json`.
@@ -62,14 +62,14 @@ Run `/product-architect` to begin the AIDLC process.
 
 ```bash
 npm update phasegate
-npx harness update-skills
+npx phasegate update-skills
 ```
 
 ## Recommended .gitignore additions
 
 ```
 node_modules/
-.claude/skills/    # regenerated by npx harness init
+.claude/skills/    # regenerated by npx phasegate init
 dist/
 reports/
 .harness/
@@ -78,7 +78,7 @@ reports/
 ## Verify Installation
 
 ```bash
-npx harness --version
-npx harness lint
-npm run harness:status
+npx phasegate --version
+npx phasegate lint
+npm run phasegate:status
 ```

package/docs/guide/layer-model.md

@@ -31,7 +31,7 @@ The Hooks Engine validates agent hook configuration and enforces completion gate
 **Command:**
 
 ```bash
-npx harness validate --layer L0
+npx phasegate validate --layer L0
 ```
 
 ---
@@ -68,7 +68,7 @@ L1 rules run in real-time as code is written. They are implemented as Biome AST
 **Command:**
 
 ```bash
-npx harness lint
+npx phasegate lint
 ```
 
 ---
@@ -86,7 +86,7 @@ L2 validators run before every commit. They enforce process discipline and test
 **Command:**
 
 ```bash
-npx harness validate --layer L2
+npx phasegate validate --layer L2
 ```
 
 ---
@@ -105,7 +105,7 @@ L3 validators run in the CI/CD pipeline before a merge is permitted. They cover
 **Command:**
 
 ```bash
-npx harness validate --layer L3
+npx phasegate validate --layer L3
 ```
 
 ---
@@ -123,7 +123,7 @@ L4 validators run on a weekly schedule. They detect slow-moving drift that accum
 **Command:**
 
 ```bash
-npx harness validate --layer L4
+npx phasegate validate --layer L4
 ```
 
 ---

package/docs/guide/skills-overview.md

@@ -1,6 +1,6 @@
 # Skills Overview
 
-Phasegate provides 28 skills covering the full AIDLC (AI-Driven Development Life Cycle). Skills are deployed to `.claude/skills/` by `npx harness init` and invoked as slash commands in AI agent sessions.
+Phasegate provides 28 skills covering the full AIDLC (AI-Driven Development Life Cycle). Skills are deployed to `.claude/skills/` by `npx phasegate init` and invoked as slash commands in AI agent sessions.
 
 ## AIDLC Process — Skill Execution Order
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.15.0",
+  "version": "0.31.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "Apache-2.0",
@@ -26,7 +26,7 @@
   },
   "type": "module",
   "files": [
-    "bin/harness",
+    "bin/phasegate",
     "scripts/harness/**/*.ts",
     "!scripts/harness/__tests__/**",
     "scripts/harness/**/*.json",
@@ -40,23 +40,25 @@
     "CHANGELOG.md"
   ],
   "bin": {
-    "harness": "./bin/harness"
+    "phasegate": "./bin/phasegate"
   },
   "scripts": {
-    "harness": "npx tsx scripts/harness/main.ts",
-    "harness:status": "npx tsx scripts/harness/main.ts harness:status",
-    "harness:enable": "npx tsx scripts/harness/main.ts enable-feature",
-    "harness:disable": "npx tsx scripts/harness/main.ts disable-feature",
-    "harness:check-phase": "npx tsx scripts/harness/main.ts harness:check-phase",
-    "harness:check-ready": "npx tsx scripts/harness/main.ts harness:check-ready",
-    "test": "vitest run --config scripts/harness/__tests__/vitest.config.ts"
+    "phasegate": "npx tsx scripts/harness/main.ts",
+    "phasegate:status": "npx tsx scripts/harness/main.ts harness:status",
+    "phasegate:enable": "npx tsx scripts/harness/main.ts enable-feature",
+    "phasegate:disable": "npx tsx scripts/harness/main.ts disable-feature",
+    "phasegate:check-phase": "npx tsx scripts/harness/main.ts harness:check-phase",
+    "phasegate:check-ready": "npx tsx scripts/harness/main.ts harness:check-ready",
+    "test": "vitest run --config scripts/harness/__tests__/vitest.config.forks.ts && vitest run --config scripts/harness/__tests__/vitest.config.ts"
   },
   "dependencies": {
     "ajv": "^8.18.0",
+    "picomatch": "^4.0.4",
     "tsx": "^4.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.7",
+    "@types/picomatch": "^4.0.0",
     "@types/node": "^25.3.5",
     "typescript": "^5.0.0",
     "vitest": "^3.0.0"

package/scripts/harness/adr-foundation/domain/ports/adr-document-parser-port.ts

@@ -1,3 +1,4 @@
+// @layer domain
 import type { ADR } from '../aggregates/adr.js';
 import type { AdrBody } from '../value-objects/adr-body.js';
 import type { AdrFrontmatter } from '../value-objects/adr-frontmatter.js';

package/scripts/harness/adr-foundation/domain/ports/adr-frontmatter-parser-port.ts

@@ -1,3 +1,4 @@
+// @layer domain
 import type { AdrFrontmatter } from '../value-objects/adr-frontmatter.js';
 
 export interface AdrFrontmatterParserPort {

package/scripts/harness/adr-foundation/domain/ports/adr-repository-port.ts

@@ -1,3 +1,4 @@
+// @layer domain
 import type { ADR } from '../aggregates/adr.js';
 import type { AdrId } from '../value-objects/adr-id.js';
 import type { AdrStatus } from '../value-objects/adr-status.js';

package/scripts/harness/adr-foundation/domain/value-objects/adr-status.ts

@@ -5,11 +5,11 @@
 const ALLOWED_STATUSES = ['Proposed', 'Accepted', 'Deprecated', 'Superseded'] as const;
 type AdrStatusValue = (typeof ALLOWED_STATUSES)[number];
 
-const TRANSITIONS: Readonly<Record<AdrStatusValue, readonly AdrStatusValue[]>> = Object.freeze({
-  Proposed: Object.freeze(['Accepted', 'Deprecated']),
-  Accepted: Object.freeze(['Deprecated', 'Superseded']),
-  Deprecated: Object.freeze(['Proposed']),
-  Superseded: Object.freeze([]),
+const TRANSITIONS = Object.freeze({
+  Proposed: Object.freeze(['Accepted', 'Deprecated'] as const),
+  Accepted: Object.freeze(['Deprecated', 'Superseded'] as const),
+  Deprecated: Object.freeze(['Proposed'] as const),
+  Superseded: Object.freeze([] as const),
 });
 
 export class InvalidAdrStatusError extends Error {
@@ -52,7 +52,7 @@ export class AdrStatus {
   }
 
   canTransitionTo(target: AdrStatus): boolean {
-    return TRANSITIONS[this.value].includes(target.value);
+    return (TRANSITIONS[this.value] as readonly string[]).includes(target.value);
   }
 
   equals(other: AdrStatus): boolean {

package/scripts/harness/agent-integration/application/dto/handle-pre-tool-use-dto.ts

@@ -11,8 +11,10 @@ export interface HandlePreToolUseInput {
 export interface HandlePreToolUseOutput {
   shouldBlock: boolean;
   blockedFilePath?: string;
-  blockReason?: 'PROTECTED_FILE' | 'PHASE_GATE';
+  blockReason?: 'PROTECTED_FILE' | 'PHASE_GATE' | 'STORY_REFLECTION';
   error?: { message: string };
   phaseGateBlockers?: string[];
+  storyReflectionBlockers?: string[];
+  storyReflectionWarnings?: string[];
   nextAction?: string;
 }

package/scripts/harness/agent-integration/application/usecases/handle-pre-tool-use-usecase.ts

@@ -9,15 +9,17 @@
 
 import { AsyncHookToCliTranslator } from '../../domain/services/hook-to-cli-translator.js';
 import { HookEvent } from '../../domain/value-objects/hook-event.js';
-import { ProtectedFileList } from '../../domain/value-objects/protected-file-list.js';
 import type { BlockMetadata } from '../../domain/value-objects/hook-translation-result.js';
 import type { ConfigQueryPort } from '../../domain/ports/config-query-port.js';
 import type { PhaseGateQueryPort } from '../../domain/ports/phase-gate-query-port.js';
+import type { StoryReflectionQueryPort } from '../../domain/ports/story-reflection-query-port.js';
+import { WriteTargetScope } from '../../domain/value-objects/write-target-scope.js';
 import type { HandlePreToolUseInput, HandlePreToolUseOutput } from '../dto/handle-pre-tool-use-dto.js';
 
 export interface HandlePreToolUseUseCasePorts {
   configQueryPort: ConfigQueryPort;
   phaseGateQueryPort: PhaseGateQueryPort;
+  storyReflectionQueryPort?: StoryReflectionQueryPort;
 }
 
 export class HandlePreToolUseInputValidationError extends Error {
@@ -29,11 +31,17 @@ export class HandlePreToolUseInputValidationError extends Error {
 }
 
 export class HandlePreToolUseUseCase {
+  private static readonly WRITE_TOOLS: ReadonlySet<string> = new Set([
+    'Write', 'Edit', 'NotebookEdit', 'str_replace_editor',
+  ]);
+
   private readonly translator: AsyncHookToCliTranslator;
   private readonly configQueryPort: ConfigQueryPort;
+  private readonly storyReflectionQueryPort?: StoryReflectionQueryPort;
 
   constructor(ports: HandlePreToolUseUseCasePorts) {
     this.configQueryPort = ports.configQueryPort;
+    this.storyReflectionQueryPort = ports.storyReflectionQueryPort;
     this.translator = new AsyncHookToCliTranslator({
       configQueryPort: ports.configQueryPort,
       reentryGuard: { isActive: () => false } as never,
@@ -71,7 +79,39 @@ export class HandlePreToolUseUseCase {
       };
     }
 
-    return { shouldBlock: false };
+    const scope = this.resolveStoryReflectionScope(input);
+    if (scope === null || this.storyReflectionQueryPort === undefined) {
+      return { shouldBlock: false };
+    }
+
+    const reflectionResult = await this.storyReflectionQueryPort.checkReflection(scope.unitId!);
+
+    if (reflectionResult.skipped || reflectionResult.passed) {
+      return { shouldBlock: false };
+    }
+
+    return HandlePreToolUseUseCase.buildStoryReflectionBlockOutput(
+      input.targetFilePaths[0],
+      reflectionResult.blockers,
+      reflectionResult.warnings,
+    );
+  }
+
+  private resolveStoryReflectionScope(input: HandlePreToolUseInput): WriteTargetScope | null {
+    if (!HandlePreToolUseUseCase.WRITE_TOOLS.has(input.toolName)) {
+      return null;
+    }
+
+    const projectPaths = this.configQueryPort.getProjectPaths();
+
+    for (const targetFilePath of input.targetFilePaths) {
+      const scope = WriteTargetScope.fromPath(targetFilePath, projectPaths);
+      if (scope?.level === 3 && scope.unitId !== undefined) {
+        return scope;
+      }
+    }
+
+    return null;
   }
 
   private static readonly LEVEL_LABELS: Record<number, string> = {
@@ -129,7 +169,7 @@ export class HandlePreToolUseUseCase {
     {
       pattern: /(?:^|\/)harness\.config\.json$/,
       message: (fp) =>
-        `保護ファイルへの書き込みがブロックされました: ${fp}\nハーネス設定は CLI 経由で変更してください: npx harness config ...`,
+        `保護ファイルへの書き込みがブロックされました: ${fp}\nハーネス設定は CLI 経由で変更してください: npx phasegate config ...`,
     },
     {
       pattern: /(?:^|\/)\.claude\/settings\.json$/,
@@ -161,4 +201,70 @@ export class HandlePreToolUseUseCase {
       error: { message },
     };
   }
+
+  private static buildStoryReflectionBlockOutput(
+    blockedFilePath: string | undefined,
+    blockers: readonly string[],
+    warnings: readonly string[],
+  ): HandlePreToolUseOutput {
+    return {
+      shouldBlock: true,
+      blockedFilePath,
+      blockReason: 'STORY_REFLECTION',
+      error: {
+        message: HandlePreToolUseUseCase.buildStoryReflectionErrorMessage(blockers),
+      },
+      storyReflectionBlockers: [...blockers],
+      storyReflectionWarnings: [...warnings],
+    };
+  }
+
+  private static buildStoryReflectionErrorMessage(blockers: readonly string[]): string {
+    const firstBlocker = blockers[0];
+    const details = firstBlocker === undefined
+      ? null
+      : HandlePreToolUseUseCase.extractStoryReflectionDetails(firstBlocker);
+    const lines: string[] = [];
+
+    if (details !== null) {
+      lines.push(`[L2-STORY-REFLECTION] ${details.productPath} に`);
+      lines.push(`@story-id ${details.storyId} が反映されていません。`);
+      lines.push('');
+    } else {
+      lines.push('[L2-STORY-REFLECTION] product 文書に @story-id が反映されていません。');
+      lines.push('');
+    }
+
+    for (const blocker of blockers) {
+      lines.push(`- ${blocker}`);
+    }
+
+    lines.push('');
+    lines.push('修正方法:');
+    lines.push('  1. cascade-updater を実行して product 文書を更新');
+    lines.push(
+      `  2. または手動で該当 product 文書に @story-id ${details?.storyId ?? '<STORY-ID>'} を追加`,
+    );
+    lines.push('');
+    lines.push('参照: ADR-XXX');
+
+    return lines.join('\n');
+  }
+
+  private static extractStoryReflectionDetails(
+    blocker: string,
+  ): { productPath: string; storyId: string } | null {
+    const productPathMatch = blocker.match(/docs\/product\/construction\/[^\s]+\.md/);
+    const storyIdMatch = blocker.match(/@story-id\s+([A-Z][\w-]*-\d+)|\b([A-Z][\w-]*-\d+)\b/);
+    const storyId = storyIdMatch?.[1] ?? storyIdMatch?.[2];
+
+    if (productPathMatch === null || storyId === undefined) {
+      return null;
+    }
+
+    return {
+      productPath: productPathMatch[0],
+      storyId,
+    };
+  }
 }

package/scripts/harness/agent-integration/application/usecases/handle-stop-usecase.ts

@@ -68,7 +68,7 @@ export class HandleStopUseCase {
     await this.reentryGuardStatePort.writeActive();
 
     try {
-      const cliResult = await this.cliExecutorPort.execute('harness:complete-check', []);
+      const cliResult = await this.cliExecutorPort.execute('phasegate:complete-check', []);
       return {
         executed: true,
         cliResult,

package/scripts/harness/agent-integration/domain/ports/config-query-port.ts

@@ -8,5 +8,7 @@ export type HookType = 'pre-tool-use' | 'post-tool-use' | 'stop';
 export interface ConfigQueryPort {
   isHookEnabled(hookType: HookType): Promise<boolean>;
   getProtectedFilePatterns(): Promise<string[]>;
+  getProtectedFileExclusions(): Promise<string[]>;
+  getRelaxedGates(): Promise<readonly string[]>;
   getProjectPaths(): ProjectPaths;
 }