phasegate 0.116.0 → 0.117.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.117.0] - 2026-05-07
+
+### 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)）。
+  - **`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 プレースホルダを実値に展開。
+  - **phase-nodes リテラル置換**: `STANDARD_PHASE_NODES` / `FULL_PHASE_NODES` / `MINIMAL_PHASE_NODES` の path リテラル `'docs/inception/...'` / `'docs/product/construction/...'` を `'{inceptionDocsRoot}/...'` / `'{designDocsRoot}/...'` に置換。
+  - **後方互換**: `paths` 未指定または既定値の場合、要求パスは v0.116.0 以前と完全同一。
+  - **スコープ外（Q1 (α) 採用）**: `docs/product/product_overview.md` / `docs/product/user_stories.md` / `docs/product/units/{unit}_unit.md` 等、`docs/product/` 直下の Level 1 product-wide 成果物はリテラル維持。`paths.designDocs`（= `docs/product/construction`）は construction subtree のみを管理する。
+  - **テスト追加**: ユニット 9 ケース（UT-PD-169〜177）と既存 5 ケースの意味反転 / シグネチャ拡張、IT 8 ケース（IT-PD-123〜130）を追加。`unit_test_design.md` / `it_test_design.md` / `coverage_report.md` 同期更新。
+  - **ドキュメント整合**: `docs/guide/configuration.md` §「Paths and the AIDLC Document Structure」に新プレースホルダ仕様と非 construction パスの取り扱いを明記。
+
 ## [0.116.0] - 2026-05-07
 
 ### Security

package/docs/ADR/ADR-016-paths-config-placeholder.md

@@ -0,0 +1,155 @@
+# ADR-016: phase-gate validator のパス解決を `paths` config プレースホルダ化する
+
+## Status
+
+Accepted — 2026-05-07
+
+## Context
+
+`phasegate.config.json` には `paths.designDocs` / `paths.inceptionDocs` という設定が存在し、`docs/guide/configuration.md:471` には次の記述がある:
+
+> If you move your design documents to a non-default location, update `paths` accordingly so that all validators and hooks resolve files correctly.
+
+しかし実装では、L2-001（phase-gate validator）の経路で `paths.*` 設定が反映されず、利用者が `paths.designDocs: "mydocs/product/construction"` 等を設定しても **要求される成果物パスは `docs/inception/...` / `docs/product/...` のまま** となる。外部レポーター（GitHub Issue [#1](https://github.com/junpei-9898/phasegate/issues/1), nakataj-mti, 2026-05-07）が報告し、phasegate チームによる再検証で報告内容が正確であることを確認した（WI-085）。
+
+### バグの実体（grep ベース、2026-05-07）
+
+#### 1. ハードコードされたパスリテラル
+
+`scripts/harness/phase-dependency-model/domain/definitions/standard-phase-nodes.ts` 全 18 か所の `path:` フィールドが `'docs/inception/...'` / `'docs/product/...'` 文字列リテラル。`full-phase-nodes.ts` / `minimal-phase-nodes.ts` も同様の構造。
+
+#### 2. プレースホルダ展開の制約
+
+`scripts/harness/phase-dependency-model/domain/values/artifact.ts:6`:
+
+```ts
+const ALLOWED_PLACEHOLDERS = new Set(['unit', 'storyId']);
+```
+
+`{designDocsRoot}` / `{inceptionDocsRoot}` のような **トップレベルパス展開は未実装**。
+
+#### 3. `docs/` 接頭辞の強制バリデーション
+
+`scripts/harness/phase-dependency-model/domain/values/artifact.ts:48`:
+
+```ts
+if (normalizedPath.length === 0 || !normalizedPath.startsWith('docs/')) {
+  throw new InvalidArtifactPathError(args.path);
+}
+```
+
+仮にユーザーが `phaseDependencies.preset: "custom"` + `gates[]` で迂回しようとしても、`mydocs/...` のような非 `docs/` 接頭辞は **Artifact 生成時点で拒否される**。
+
+#### 4. `paths` config が `Artifact.resolve()` に到達していない
+
+`scripts/harness/phase-dependency-model/application/services/evidence-bundle-assembler.ts:42-49` で `phaseConfigProvider` から `planningMode` のみ取得。`paths.designDocs` / `paths.inceptionDocs` は `Artifact.resolve(scope)` 呼び出しに渡されていない。`scope` 型も `{ unitId?: string; storyId?: string }` のみで、ルートパスを通す経路がない。
+
+#### 5. 部分対応箇所との不整合
+
+`paths.designDocs` を実際に参照している箇所は存在するが、いずれも phase-gate validator（L2-001）の経路ではない:
+
+- `scripts/harness/harness-api/infrastructure/adapters/file-system-artifact-scanner-adapter.ts:118`（harness-api の scanner）
+- `scripts/harness/agent-integration/infrastructure/adapters/phase-gate-query-adapter.ts:60`（agent runtime hook の `unitDir` 解決）
+
+phase-gate validator 本体（`PhaseStructure` / `EvidenceBundleAssembler` / `Artifact`）には `paths.*` が一切流入していない。同一 config に対して validator 経路ごとに挙動が乖離している状態。
+
+### 検討した代替案
+
+#### (A) `paths.designDocs` / `paths.inceptionDocs` でトップレベルパスを実際に置換する（**採用**）
+
+phase-gate validator のパスリテラルを `{designDocsRoot}` / `{inceptionDocsRoot}` プレースホルダ化し、`paths` config の値で展開する。`Artifact` の `docs/` 接頭辞バリデーションはプレースホルダ展開後に実施するか撤廃する。
+
+#### (B) ドキュメントを修正し「`paths.*` は storyReflection 専用」と明記する
+
+`paths.designDocs` / `paths.inceptionDocs` は phase-gate ノードのパスには影響しないと documentation を改訂し、「ノードのパスを変えたい場合は `phaseDependencies.preset: "custom"` + `gates[]` で個別に上書きする」ことを推奨する。
+
+## Decision
+
+**(A) を採用する。** phase-gate validator のパス解決にプレースホルダ展開機構を導入し、`paths.designDocs` / `paths.inceptionDocs` 設定を反映させる。
+
+### 採用理由
+
+1. **ドキュメントが利用者の合理的期待を形成済み** — `docs/guide/configuration.md:471` の記述により「`paths` を変えれば全 validator / hook が解決する」ことが約束されている。実装をドキュメントに合わせる方が修正の方向性として正しい
+2. **(B) は現状コードでは動作しない** — `Artifact.create()` に `docs/` 接頭辞バリデーション (artifact.ts:48) が存在するため、`gates[]` で `mydocs/...` を指定しても `InvalidArtifactPathError` で拒否される。(B) を採るには結局接頭辞バリデーションの緩和が必要で、(A) と実装コストの大半が重複する
+3. **UX 上の持続可能性** — 28 スキル × 多数の path フィールドを利用者が `gates[]` で個別に書き直す UX は持続不可能。デフォルトを変えるという軽量な操作で済む (A) の方が retrofit-adoption（既存 PJ への phasegate 導入）ユースケースに適合する
+4. **既存の部分対応箇所との整合** — `harness-api` / `agent-integration` 配下の adapter 群は既に `paths.designDocs` を読んでいる。phase-gate validator だけが取り残されている形であり、(A) は不整合を解消する
+
+### 新プレースホルダ仕様
+
+| プレースホルダ | 解決元 | デフォルト | 既存挙動との関係 |
+|----------------|--------|------------|---|
+| `{designDocsRoot}` | `paths.designDocs` | `docs/product/construction` | 新設 |
+| `{inceptionDocsRoot}` | `paths.inceptionDocs` | `docs/inception` | 新設 |
+| `{unit}` | `scope.unitId` | （変更なし） | 既存 |
+| `{storyId}` | `scope.storyId` | （変更なし） | 既存 |
+
+### `Artifact` バリデーションの取り扱い
+
+`docs/` 接頭辞バリデーション (artifact.ts:48) は **撤廃する**。理由:
+
+- `{designDocsRoot}` / `{inceptionDocsRoot}` のデフォルト値が `docs/...` なので、デフォルト挙動では引き続き `docs/` 配下に展開される
+- 利用者が意図的に `mydocs/...` を選択した場合、それを拒否する正当性がない（`paths` 設定の存在意義そのもの）
+- プレースホルダ展開後の文字列を再度 `docs/` 接頭辞で検査すると、`paths.*` の独自値が `Artifact` 生成時に未展開のまま検査される時系列問題が発生するため、**展開後の検査も行わない**
+- 代替の防御として、`paths.designDocs` / `paths.inceptionDocs` 自体の妥当性は config-foundation の schema validation（既存）で担保する
+
+### `EvidenceBundleAssembler` の paths 流入経路
+
+`PhaseConfigProviderPort` に新メソッド `getPathRoots()` を追加し、`paths.designDocs` / `paths.inceptionDocs` を取得する。`EvidenceBundleAssembler.assembleForLevel()` 内で paths を取得し、`scope` に追加するか別引数で `Artifact.resolve()` に渡す（具体形は logical-designer フェーズで確定）。
+
+### 後方互換戦略
+
+- `paths` 未指定または既定値（`docs/product/construction` / `docs/inception`）の場合、要求パスは v0.115.0 以前と完全に同一
+- 既存の `gates[]` でパスを上書きしているユーザーは、上書き値がそのまま使われる挙動を維持する（プレースホルダを含まないリテラルパスはそのまま resolve される）
+- `Artifact` の `docs/` 接頭辞バリデーション撤廃は **緩和方向の変更**であり、既存の正常な config を破壊しない
+
+## Consequences
+
+### ポジティブ
+
+- ドキュメント `configuration.md:471` の記述と実装が一致し、利用者の合理的期待が満たされる
+- `paths.designDocs` / `paths.inceptionDocs` が validator 経路（L2-001 phase-gate, harness-api scanner, agent-integration hook）で一貫して解釈される
+- retrofit-adoption（ISSUE-007）で既存 PJ がドキュメント配置規約を保ったまま phasegate を被せられるようになり、適用範囲が拡大
+- 28 スキル × 多数の path フィールドに `gates[]` で介入させる UX 負担が解消される
+
+### ネガティブ / トレードオフ
+
+- **ドメイン契約変更**: `Artifact.resolve()` のシグネチャが拡張されるため、phase-dependency-model の domain 層に破壊的変更が入る
+  - **緩和策**: 内部 API のみであり、phasegate-cli 利用者には影響しない。テストで後方互換を assert する
+- **`docs/` 接頭辞バリデーション撤廃の緩み**: 任意の文字列パスを許容することで、typo 等の誤設定を `Artifact.create()` 段階で検出できなくなる
+  - **緩和策**: `paths.designDocs` / `paths.inceptionDocs` の妥当性は config-foundation の schema validation で検査済み。プレースホルダを含まないリテラル path（`gates[]` 経由）の typo は実行時の `artifactExistenceChecker` で「ファイルが存在しない」として検出される
+- **新プレースホルダの命名選定**: `{designDocsRoot}` / `{inceptionDocsRoot}` は `paths` config キー名と微妙に異なる（`designDocs` vs `designDocsRoot`）
+  - **判断**: 既存プレースホルダ `{unit}` / `{storyId}` も config キー名そのままではないため整合的。`Root` suffix で「ルートディレクトリ」であることを明示する方が利用者にとって意味が明確
+
+### スコープ外（本 ADR で扱わない）
+
+- L2 以外の validator（L1 / L3 / L4）への paths 設定の網羅的反映 — 既に各 validator が個別に `paths.*` を読んでいる箇所があるため、本 ADR は L2-001 phase-gate に閉じる
+- `paths.designDocs` 直下の Unit ディレクトリ命名規約変更
+- skill ファイル（`.claude/skills/`）内の path 参照の動的化
+- `Artifact.path` のユーザー任意プレースホルダ拡張（`{customRoot}` 等）— 本 ADR で導入する 2 個のプレースホルダで現状のニーズは満たされる
+
+## Migration
+
+1. **ドメイン層**: `Artifact` の `ALLOWED_PLACEHOLDERS` に `designDocsRoot` / `inceptionDocsRoot` を追加し、`docs/` 接頭辞バリデーションを撤廃。`Artifact.resolve()` シグネチャに path roots を渡す経路を追加
+2. **ドメイン定義**: `STANDARD_PHASE_NODES` / `FULL_PHASE_NODES` / `MINIMAL_PHASE_NODES` の path リテラルを `{inceptionDocsRoot}/...` / `{designDocsRoot}/...` に書き換え
+3. **アプリケーション層**: `PhaseConfigProviderPort` に `getPathRoots()` を追加。`EvidenceBundleAssembler` 等で paths を取得して `Artifact.resolve()` に渡す
+4. **インフラ層**: `PhaseConfigProviderPort` 実装で `paths.designDocs` / `paths.inceptionDocs` を `getPathRoots()` から返すように接続
+5. **テスト**:
+   - default paths で従来通り `docs/inception/...` を要求すること
+   - `paths.inceptionDocs: "mydocs/inception"` で `mydocs/inception/...` を要求すること
+   - `Artifact` が `docs/` 以外で始まるパス（プレースホルダ展開後）を許容すること
+6. **ドキュメント**: `docs/guide/configuration.md` に新プレースホルダの動作を明記
+7. **CHANGELOG**: bug fix として記載（GitHub Issue [#1](https://github.com/junpei-9898/phasegate/issues/1) への参照付き）
+
+詳細な設計は WI-085 Phase 2（`logical-designer`）で `docs/product/construction/phase-dependency-model/logical_design.md` 等に記録する。
+
+## 関連
+
+- **WI-085** — 本 ADR を駆動する Work Item。GitHub Issue [#1](https://github.com/junpei-9898/phasegate/issues/1) に対応
+- **`scripts/harness/phase-dependency-model/domain/values/artifact.ts:6-80`** — プレースホルダ仕様 + `docs/` 接頭辞バリデーション、本 ADR の改修対象
+- **`scripts/harness/phase-dependency-model/domain/definitions/standard-phase-nodes.ts:29-`** — ハードコード path（`full-phase-nodes.ts` / `minimal-phase-nodes.ts` も同様）
+- **`scripts/harness/phase-dependency-model/application/services/evidence-bundle-assembler.ts:42-49`** — paths 流入欠落点、本 ADR の改修対象
+- **`scripts/harness/phase-dependency-model/domain/ports/phase-config-provider-port.ts`** — `getPathRoots()` 追加対象
+- **`scripts/harness/harness-api/infrastructure/adapters/file-system-artifact-scanner-adapter.ts:118`** — 既に paths を読んでいる先行箇所、整合確認用
+- **`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 に拡張するもの

package/docs/guide/configuration.md

@@ -469,3 +469,26 @@ docs/
 ```
 
 If you move your design documents to a non-default location, update `paths` accordingly so that all validators and hooks resolve files correctly.
+
+**How paths flow into the L2 phase-gate validator (since v0.117.0 / WI-085):**
+
+`STANDARD_PHASE_NODES` / `FULL_PHASE_NODES` / `MINIMAL_PHASE_NODES` express artifact locations using two placeholders, expanded at validation time from `paths`:
+
+| Placeholder | Resolved from | Default |
+|---|---|---|
+| `{designDocsRoot}` | `paths.designDocs` | `docs/product/construction` |
+| `{inceptionDocsRoot}` | `paths.inceptionDocs` | `docs/inception` |
+
+Setting `paths.designDocs` to `mydocs/product/construction` makes the L2 phase-gate require `mydocs/product/construction/{unit}/domain_model.md` instead of the default. Default values match the v0.115.0 layout for full backward compatibility.
+
+**Out of scope (paths handled by literal references):**
+
+A handful of Level 1 product-wide artifacts live at `docs/product/` directly (not under `construction/`) and remain literal:
+
+- `docs/product/product_overview.md`
+- `docs/product/user_stories.md`
+- `docs/product/user_story_mapping.md`
+- `docs/product/units/{unit}_unit.md`
+- `docs/product/units/integration_contract.md`
+
+These are not controlled by `paths.designDocs` (which targets the *construction* subtree). If your project moves the entire `docs/product/` tree, override these via `phaseDependencies.preset: "custom"` + `gates[]`.

package/package.json

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

package/scripts/harness/config-foundation/application/mappers/phase-config-section-mapper.ts

@@ -40,5 +40,6 @@ export function toPhaseConfigSection(resolvedConfig: HarnessConfigV2) {
       gates: phaseDependencies.gates ?? [],
     },
     reportingOutputDir: resolvedConfig.reporting.outputDir,
+    paths: resolvedConfig.paths,
   };
 }

package/scripts/harness/phase-dependency-model/application/services/evidence-bundle-assembler.ts

@@ -6,6 +6,7 @@
 import type { ArtifactExistenceCheckerPort } from '../../domain/ports/artifact-existence-checker-port.js';
 import type { PhaseConfigProviderPort } from '../../domain/ports/phase-config-provider-port.js';
 import type { PlanDocumentReaderPort } from '../../domain/ports/plan-document-reader-port.js';
+import type { PathRoots } from '../../domain/values/artifact.js';
 import { PhaseLevel } from '../../domain/values/phase-level.js';
 import type { PhaseNode } from '../../domain/values/phase-node.js';
 import type { PlanEvidence } from '../../domain/values/plan-evidence.js';
@@ -21,6 +22,7 @@ export interface EvidenceBundle {
   readonly artifactStatuses: ReadonlyMap<string, boolean>;
   readonly planEvidences: ReadonlyMap<string, PlanEvidence>;
   readonly planningMode: PlanningMode;
+  readonly pathRoots: PathRoots;
 }
 
 export class EvidenceBundleAssembler {
@@ -40,13 +42,21 @@ export class EvidenceBundleAssembler {
     scope: { unitId?: string; storyId?: string },
   ): Promise<EvidenceBundle> {
     const planningMode = await this.phaseConfigProvider.getPlanningMode(scope);
+    const pathRoots = await this.phaseConfigProvider.getPathRoots();
     const artifacts = nodes.flatMap((node) => node.artifacts);
-    const resolvedStatuses = await this.artifactExistenceChecker.checkAll(artifacts, scope);
+    const resolvedStatuses = await this.artifactExistenceChecker.checkAll(
+      artifacts,
+      scope,
+      pathRoots,
+    );
     const artifactStatuses = new Map<string, boolean>();
 
     for (const artifact of artifacts) {
       try {
-        artifactStatuses.set(artifact.path, resolvedStatuses.get(artifact.resolve(scope)) ?? false);
+        artifactStatuses.set(
+          artifact.path,
+          resolvedStatuses.get(artifact.resolve(scope, pathRoots)) ?? false,
+        );
       } catch {
         artifactStatuses.set(artifact.path, false);
       }
@@ -66,6 +76,7 @@ export class EvidenceBundleAssembler {
       artifactStatuses,
       planEvidences,
       planningMode,
+      pathRoots,
     };
   }
 }

package/scripts/harness/phase-dependency-model/application/services/phase-info-resolver.ts

@@ -7,6 +7,7 @@ import type { PhaseInfoDto } from '../dto/phase-info-dto.js';
 import type { PhaseDependency } from '../../domain/values/phase-dependency.js';
 import type { PhaseNode } from '../../domain/values/phase-node.js';
 import type { PlanEvidence } from '../../domain/values/plan-evidence.js';
+import { DEFAULT_PATH_ROOTS, type PathRoots } from '../../domain/values/artifact.js';
 
 export interface ResolvedPhaseInfo
   extends Omit<PhaseInfoDto, 'unitId' | 'storyId'> {}
@@ -41,6 +42,7 @@ export class PhaseInfoResolver {
     },
     artifactStatuses: ReadonlyMap<string, boolean>,
     planEvidences: ReadonlyMap<string, PlanEvidence>,
+    pathRoots: PathRoots = DEFAULT_PATH_ROOTS,
   ): ResolvedPhaseInfo {
     const incomingDependencies = collectIncomingDependencies(graph.dependencies);
     const completedNodeKeys = new Set<string>();
@@ -108,7 +110,7 @@ export class PhaseInfoResolver {
 
       for (const artifact of node.requiredArtifacts()) {
         if (artifactStatuses.get(artifact.path) !== true) {
-          blockers.push(`成果物が不足しています: ${artifact.path}`);
+          blockers.push(`成果物が不足しています: ${artifact.expandRoots(pathRoots)}`);
         }
       }
 

package/scripts/harness/phase-dependency-model/application/usecases/get-phase-info-usecase.ts

@@ -48,6 +48,7 @@ export class GetPhaseInfoUseCase {
       graph,
       evidenceBundle.artifactStatuses,
       evidenceBundle.planEvidences,
+      evidenceBundle.pathRoots,
     );
 
     return Object.freeze({

package/scripts/harness/phase-dependency-model/domain/definitions/full-phase-nodes.ts

@@ -26,7 +26,7 @@ export const FULL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
   createNode(1, 'product-architect', [
     {
       name: 'product-overview-plan',
-      path: 'docs/inception/_shared/product_overview_plan.md',
+      path: '{inceptionDocsRoot}/_shared/product_overview_plan.md',
       required: true,
     },
     {
@@ -38,7 +38,7 @@ export const FULL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
   createNode(1, 'story-writer', [
     {
       name: 'story-writer-plan',
-      path: 'docs/inception/_shared/story_writer_plan.md',
+      path: '{inceptionDocsRoot}/_shared/story_writer_plan.md',
       required: true,
     },
     {
@@ -50,7 +50,7 @@ export const FULL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
   createNode(1, 'story-mapper', [
     {
       name: 'story-mapping-plan',
-      path: 'docs/inception/_shared/story_mapping_plan.md',
+      path: '{inceptionDocsRoot}/_shared/story_mapping_plan.md',
       required: true,
     },
     {
@@ -62,7 +62,7 @@ export const FULL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
   createNode(1, 'unit-designer', [
     {
       name: 'unit-design-plan',
-      path: 'docs/inception/_shared/unit_design_plan.md',
+      path: '{inceptionDocsRoot}/_shared/unit_design_plan.md',
       required: true,
     },
     {
@@ -79,108 +79,108 @@ export const FULL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
   createNode(2, 'domain-designer', [
     {
       name: 'domain-model-plan',
-      path: 'docs/inception/{unit}/domain_model_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/domain_model_plan.md',
       required: true,
     },
     {
       name: 'domain-model',
-      path: 'docs/product/construction/{unit}/domain_model.md',
+      path: '{designDocsRoot}/{unit}/domain_model.md',
       required: true,
     },
   ]),
   createNode(2, 'logical-designer', [
     {
       name: 'logical-design-plan',
-      path: 'docs/inception/{unit}/logical_design_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/logical_design_plan.md',
       required: true,
     },
     {
       name: 'logical-design',
-      path: 'docs/product/construction/{unit}/logical_design.md',
+      path: '{designDocsRoot}/{unit}/logical_design.md',
       required: true,
     },
   ]),
   createNode(2, 'it-test-designer', [
     {
       name: 'it-test-design-plan',
-      path: 'docs/inception/{unit}/it_test_design_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/it_test_design_plan.md',
       required: true,
     },
     {
       name: 'it-test-design',
-      path: 'docs/product/construction/{unit}/it_test_design.md',
+      path: '{designDocsRoot}/{unit}/it_test_design.md',
       required: true,
     },
   ]),
   createNode(2, 'unit-test-designer', [
     {
       name: 'unit-test-design-plan',
-      path: 'docs/inception/{unit}/unit_test_design_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/unit_test_design_plan.md',
       required: true,
     },
     {
       name: 'unit-test-design',
-      path: 'docs/product/construction/{unit}/unit_test_design.md',
+      path: '{designDocsRoot}/{unit}/unit_test_design.md',
       required: true,
     },
   ]),
   createNode(2, 'it-test-logic-designer', [
     {
       name: 'it-test-logic-plan',
-      path: 'docs/inception/{unit}/it_test_logic_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/it_test_logic_plan.md',
       required: true,
     },
     {
       name: 'it-test-logic',
-      path: 'docs/product/construction/{unit}/it_test_logic.md',
+      path: '{designDocsRoot}/{unit}/it_test_logic.md',
       required: true,
     },
   ]),
   createNode(2, 'unit-test-logic-designer', [
     {
       name: 'unit-test-logic-plan',
-      path: 'docs/inception/{unit}/unit_test_logic_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/unit_test_logic_plan.md',
       required: true,
     },
     {
       name: 'unit-test-logic',
-      path: 'docs/product/construction/{unit}/unit_test_logic.md',
+      path: '{designDocsRoot}/{unit}/unit_test_logic.md',
       required: true,
     },
   ]),
   createNode(3, 'logical-designer', [
     {
       name: 'story-logical-design-plan',
-      path: 'docs/inception/{unit}/{storyId}/logical_design_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/logical_design_plan.md',
       required: false,
     },
     {
       name: 'story-logical-design',
-      path: 'docs/inception/{unit}/{storyId}/logical_design.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/logical_design.md',
       required: false,
     },
   ]),
   createNode(3, 'scenario-test-designer', [
     {
       name: 'scenario-test-plan',
-      path: 'docs/inception/{unit}/{storyId}/scenario_test_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/scenario_test_plan.md',
       required: false,
     },
     {
       name: 'scenario-test-design',
-      path: 'docs/inception/{unit}/{storyId}/scenario_test_design.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/scenario_test_design.md',
       required: false,
     },
   ]),
   createNode(3, 'scenario-test-logic-designer', [
     {
       name: 'scenario-test-logic-plan',
-      path: 'docs/inception/{unit}/{storyId}/scenario_test_logic_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/scenario_test_logic_plan.md',
       required: false,
     },
     {
       name: 'scenario-test-logic',
-      path: 'docs/inception/{unit}/{storyId}/scenario_test_logic.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/scenario_test_logic.md',
       required: false,
     },
   ]),
@@ -188,7 +188,7 @@ export const FULL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
   createNode(3, 'story-implementor', [
     {
       name: 'tdd-implementation-plan',
-      path: 'docs/inception/{unit}/{storyId}/tdd_implementation_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/tdd_implementation_plan.md',
       required: false,
     },
   ]),

package/scripts/harness/phase-dependency-model/domain/definitions/minimal-phase-nodes.ts

@@ -26,7 +26,7 @@ export const MINIMAL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
   createNode(1, 'product-architect', [
     {
       name: 'product-overview-plan',
-      path: 'docs/inception/_shared/product_overview_plan.md',
+      path: '{inceptionDocsRoot}/_shared/product_overview_plan.md',
       required: true,
     },
     {
@@ -38,12 +38,12 @@ export const MINIMAL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
   createNode(2, 'logical-designer', [
     {
       name: 'logical-design-plan',
-      path: 'docs/inception/{unit}/logical_design_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/logical_design_plan.md',
       required: true,
     },
     {
       name: 'logical-design',
-      path: 'docs/product/construction/{unit}/logical_design.md',
+      path: '{designDocsRoot}/{unit}/logical_design.md',
       required: true,
     },
   ]),

package/scripts/harness/phase-dependency-model/domain/definitions/standard-phase-nodes.ts

@@ -26,7 +26,7 @@ export const STANDARD_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
   createNode(1, 'product-architect', [
     {
       name: 'product-overview-plan',
-      path: 'docs/inception/_shared/product_overview_plan.md',
+      path: '{inceptionDocsRoot}/_shared/product_overview_plan.md',
       required: true,
     },
     {
@@ -38,7 +38,7 @@ export const STANDARD_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
   createNode(1, 'story-writer', [
     {
       name: 'story-writer-plan',
-      path: 'docs/inception/_shared/story_writer_plan.md',
+      path: '{inceptionDocsRoot}/_shared/story_writer_plan.md',
       required: true,
     },
     {
@@ -50,60 +50,60 @@ export const STANDARD_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
   createNode(2, 'domain-designer', [
     {
       name: 'domain-model-plan',
-      path: 'docs/inception/{unit}/domain_model_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/domain_model_plan.md',
       required: true,
     },
     {
       name: 'domain-model',
-      path: 'docs/product/construction/{unit}/domain_model.md',
+      path: '{designDocsRoot}/{unit}/domain_model.md',
       required: true,
     },
   ]),
   createNode(2, 'logical-designer', [
     {
       name: 'logical-design-plan',
-      path: 'docs/inception/{unit}/logical_design_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/logical_design_plan.md',
       required: true,
     },
     {
       name: 'logical-design',
-      path: 'docs/product/construction/{unit}/logical_design.md',
+      path: '{designDocsRoot}/{unit}/logical_design.md',
       required: true,
     },
   ]),
   createNode(3, 'logical-designer', [
     {
       name: 'story-logical-design-plan',
-      path: 'docs/inception/{unit}/{storyId}/logical_design_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/logical_design_plan.md',
       required: false,
     },
     {
       name: 'story-logical-design',
-      path: 'docs/inception/{unit}/{storyId}/logical_design.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/logical_design.md',
       required: false,
     },
   ]),
   createNode(3, 'scenario-test-designer', [
     {
       name: 'scenario-test-plan',
-      path: 'docs/inception/{unit}/{storyId}/scenario_test_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/scenario_test_plan.md',
       required: false,
     },
     {
       name: 'scenario-test-design',
-      path: 'docs/inception/{unit}/{storyId}/scenario_test_design.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/scenario_test_design.md',
       required: false,
     },
   ]),
   createNode(3, 'scenario-test-logic-designer', [
     {
       name: 'scenario-test-logic-plan',
-      path: 'docs/inception/{unit}/{storyId}/scenario_test_logic_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/scenario_test_logic_plan.md',
       required: false,
     },
     {
       name: 'scenario-test-logic',
-      path: 'docs/inception/{unit}/{storyId}/scenario_test_logic.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/scenario_test_logic.md',
       required: false,
     },
   ]),
@@ -111,7 +111,7 @@ export const STANDARD_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
   createNode(3, 'story-implementor', [
     {
       name: 'tdd-implementation-plan',
-      path: 'docs/inception/{unit}/{storyId}/tdd_implementation_plan.md',
+      path: '{inceptionDocsRoot}/{unit}/{storyId}/tdd_implementation_plan.md',
       required: false,
     },
   ]),

package/scripts/harness/phase-dependency-model/domain/models/phase-structure.ts

@@ -10,7 +10,7 @@ import { MINIMAL_PHASE_NODES } from '../definitions/minimal-phase-nodes.js';
 import { STANDARD_PHASE_DEPENDENCIES } from '../definitions/standard-phase-dependencies.js';
 import { STANDARD_PHASE_NODES } from '../definitions/standard-phase-nodes.js';
 import { GateGraph } from '../services/gate-graph.js';
-import { Artifact } from '../values/artifact.js';
+import { Artifact, DEFAULT_PATH_ROOTS, type PathRoots } from '../values/artifact.js';
 import { CustomRule, InvalidCustomRuleError } from '../values/custom-rule.js';
 import { GateDefinition } from '../values/gate-definition.js';
 import { PhaseCustomizationPolicy } from '../values/phase-customization-policy.js';
@@ -76,13 +76,14 @@ const buildNodeIndex = (nodes: readonly PhaseNode[]): ReadonlyMap<string, PhaseN
 const collectMissingArtifactBlockers = (
   nodes: readonly PhaseNode[],
   artifactStatuses: ReadonlyMap<string, boolean>,
+  pathRoots: PathRoots,
 ): readonly string[] => {
   const blockers: string[] = [];
 
   for (const node of nodes) {
     for (const artifact of node.requiredArtifacts()) {
       if (!artifactStatuses.get(artifact.path)) {
-        blockers.push(`成果物が不足しています: ${artifact.path}`);
+        blockers.push(`成果物が不足しています: ${artifact.expandRoots(pathRoots)}`);
       }
     }
   }
@@ -220,6 +221,7 @@ export class PhaseStructure {
       artifactStatuses: ReadonlyMap<string, boolean>;
       planEvidences: ReadonlyMap<string, PlanEvidence>;
       planningMode: PlanningMode;
+      pathRoots?: PathRoots;
     },
     scope?: {
       unitId?: string;
@@ -237,13 +239,14 @@ export class PhaseStructure {
       });
     }
 
+    const pathRoots = evidence.pathRoots ?? DEFAULT_PATH_ROOTS;
     const prerequisiteNodes = [1, 2, 3]
       .map((value) => PhaseLevel.create(value))
       .filter((level) => level.isPrerequisiteOf(targetLevel))
       .flatMap((level) => this.getPhaseNodes(level));
 
     const blockers = [
-      ...collectMissingArtifactBlockers(prerequisiteNodes, evidence.artifactStatuses),
+      ...collectMissingArtifactBlockers(prerequisiteNodes, evidence.artifactStatuses, pathRoots),
     ];
     const completedNodeKeys = new Set<string>();
     const warnings: string[] = [];
@@ -289,7 +292,7 @@ export class PhaseStructure {
         let nodeComplete = true;
         for (const artifact of node.artifacts) {
           // Evidence map may be keyed by unresolved path (artifact.path) or resolved path
-          const resolvedPath = artifact.resolve(scope);
+          const resolvedPath = artifact.resolve(scope, pathRoots);
           const exists = evidence.artifactStatuses.get(artifact.path)
             ?? evidence.artifactStatuses.get(resolvedPath)
             ?? false;

package/scripts/harness/phase-dependency-model/domain/ports/artifact-existence-checker-port.ts

@@ -3,11 +3,12 @@
  * @unit phase-dependency-model
  */
 
-import type { Artifact } from '../values/artifact.js';
+import type { Artifact, PathRoots } from '../values/artifact.js';
 
 export interface ArtifactExistenceCheckerPort {
   checkAll(
     artifacts: readonly Artifact[],
     scope: { unitId?: string; storyId?: string },
+    pathRoots?: PathRoots,
   ): Promise<ReadonlyMap<string, boolean>>;
 }

package/scripts/harness/phase-dependency-model/domain/ports/phase-config-provider-port.ts

@@ -6,10 +6,12 @@
 import type { PhaseCustomizationPolicy } from '../values/phase-customization-policy.js';
 import type { PlanningMode } from '../values/planning-mode.js';
 import type { StoryReflectionConfig } from '../values/story-reflection-config.js';
+import type { PathRoots } from '../values/artifact.js';
 
 export interface PhaseConfigProviderPort {
   getPlanningMode(scope: { unitId?: string; storyId?: string }): Promise<PlanningMode>;
   getCustomizationPolicy(): Promise<PhaseCustomizationPolicy>;
   getReportingOutputDir(): Promise<string>;
   getStoryReflectionConfig(): Promise<StoryReflectionConfig>;
+  getPathRoots(): Promise<PathRoots>;
 }

package/scripts/harness/phase-dependency-model/domain/values/artifact.ts

@@ -3,10 +3,25 @@
  * @unit phase-dependency-model
  */
 
-const ALLOWED_PLACEHOLDERS = new Set(['unit', 'storyId']);
+const ALLOWED_PLACEHOLDERS = new Set([
+  'unit',
+  'storyId',
+  'designDocsRoot',
+  'inceptionDocsRoot',
+]);
 const PLACEHOLDER_PATTERN = /\{([^}]+)\}/g;
 const UNRESOLVED_PLACEHOLDER_PATTERN = /\{[^}]+\}/;
 
+export interface PathRoots {
+  readonly designDocsRoot: string;
+  readonly inceptionDocsRoot: string;
+}
+
+export const DEFAULT_PATH_ROOTS: PathRoots = Object.freeze({
+  designDocsRoot: 'docs/product/construction',
+  inceptionDocsRoot: 'docs/inception',
+});
+
 export interface ArtifactCreateArgs {
   readonly name: string;
   readonly path: string;
@@ -45,7 +60,7 @@ export class Artifact {
   static create(args: ArtifactCreateArgs): Artifact {
     const normalizedPath = args.path.trim();
 
-    if (normalizedPath.length === 0 || !normalizedPath.startsWith('docs/')) {
+    if (normalizedPath.length === 0) {
       throw new InvalidArtifactPathError(args.path);
     }
 
@@ -66,11 +81,25 @@ export class Artifact {
     return this.path.endsWith('_plan.md');
   }
 
-  resolve(scope: { unitId?: string; storyId?: string }): string {
+  resolve(
+    scope: { unitId?: string; storyId?: string },
+    pathRoots: PathRoots = DEFAULT_PATH_ROOTS,
+  ): string {
     let resolvedPath = this.path;
 
+    resolvedPath = resolvedPath.replaceAll(
+      '{designDocsRoot}',
+      pathRoots.designDocsRoot,
+    );
+    resolvedPath = resolvedPath.replaceAll(
+      '{inceptionDocsRoot}',
+      pathRoots.inceptionDocsRoot,
+    );
     resolvedPath = resolvedPath.replaceAll('{unit}', scope.unitId ?? '{unit}');
-    resolvedPath = resolvedPath.replaceAll('{storyId}', scope.storyId ?? '{storyId}');
+    resolvedPath = resolvedPath.replaceAll(
+      '{storyId}',
+      scope.storyId ?? '{storyId}',
+    );
 
     if (this.required && UNRESOLVED_PLACEHOLDER_PATTERN.test(resolvedPath)) {
       throw new InvalidArtifactPathError(this.path);
@@ -79,6 +108,12 @@ export class Artifact {
     return resolvedPath;
   }
 
+  expandRoots(pathRoots: PathRoots = DEFAULT_PATH_ROOTS): string {
+    return this.path
+      .replaceAll('{designDocsRoot}', pathRoots.designDocsRoot)
+      .replaceAll('{inceptionDocsRoot}', pathRoots.inceptionDocsRoot);
+  }
+
   equals(other: Artifact): boolean {
     return (
       this.name === other.name &&

package/scripts/harness/phase-dependency-model/infrastructure/config/harness-config-phase-config-provider.ts

@@ -12,6 +12,7 @@ import {
 import { CustomRule } from '../../domain/values/custom-rule.js';
 import { StoryReflectionConfig } from '../../domain/values/story-reflection-config.js';
 import { StoryReflectionMapping } from '../../domain/values/story-reflection-mapping.js';
+import { DEFAULT_PATH_ROOTS, type PathRoots } from '../../domain/values/artifact.js';
 import { FULL_STORY_REFLECTION_DEFAULTS } from '../../domain/definitions/full-story-reflection-defaults.js';
 import { STANDARD_STORY_REFLECTION_DEFAULTS } from '../../domain/definitions/standard-story-reflection-defaults.js';
 import { MINIMAL_STORY_REFLECTION_DEFAULTS } from '../../domain/definitions/minimal-story-reflection-defaults.js';
@@ -54,8 +55,14 @@ export interface PhaseConfigSection {
   };
   readonly storyReflection?: StoryReflectionSectionInput;
   readonly reportingOutputDir?: string;
+  readonly paths?: {
+    readonly designDocs?: string;
+    readonly inceptionDocs?: string;
+  };
 }
 
+const trimTrailingSlash = (value: string): string => value.replace(/\/+$/, '');
+
 /**
  * プリセットごとの storyReflection デフォルト定義。
  * `default` は v1.0 で `full` に統合されたため同一値にエイリアスする。
@@ -135,6 +142,17 @@ export class HarnessConfigPhaseConfigProvider
     return this.config.reportingOutputDir ?? this.defaultOutputDir;
   }
 
+  async getPathRoots(): Promise<PathRoots> {
+    const paths = this.config.paths;
+    const designDocsRoot = paths?.designDocs
+      ? trimTrailingSlash(paths.designDocs)
+      : DEFAULT_PATH_ROOTS.designDocsRoot;
+    const inceptionDocsRoot = paths?.inceptionDocs
+      ? trimTrailingSlash(paths.inceptionDocs)
+      : DEFAULT_PATH_ROOTS.inceptionDocsRoot;
+    return { designDocsRoot, inceptionDocsRoot };
+  }
+
   async getStoryReflectionConfig(): Promise<StoryReflectionConfig> {
     const policy = await this.getCustomizationPolicy();
     const presetDefault = PRESET_STORY_REFLECTION_DEFAULTS[policy.preset];

package/scripts/harness/phase-dependency-model/infrastructure/filesystem/file-system-artifact-existence-checker.ts

@@ -6,7 +6,7 @@
 import { access } from 'node:fs/promises';
 import * as path from 'node:path';
 import type { ArtifactExistenceCheckerPort } from '../../domain/ports/artifact-existence-checker-port.js';
-import type { Artifact } from '../../domain/values/artifact.js';
+import type { Artifact, PathRoots } from '../../domain/values/artifact.js';
 
 export interface FileSystemArtifactExistenceCheckerDeps {
   readonly rootDir: string;
@@ -24,13 +24,14 @@ export class FileSystemArtifactExistenceChecker
   async checkAll(
     artifacts: readonly Artifact[],
     scope: { unitId?: string; storyId?: string },
+    pathRoots?: PathRoots,
   ): Promise<ReadonlyMap<string, boolean>> {
     const results = new Map<string, boolean>();
 
     for (const artifact of artifacts) {
       let resolvedPath: string;
       try {
-        resolvedPath = artifact.resolve(scope);
+        resolvedPath = artifact.resolve(scope, pathRoots);
       } catch {
         results.set(artifact.path, false);
         continue;