phasegate 0.128.0 → 0.130.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.130.0] - 2026-05-08
+
+### Fixed
+
+- **WI-093 — `paths.designDocs` を L2-001 / traceability-model の product 直下文書まで完全 threading (GitHub Issue #4 finding #4)** — WI-085 で残っていた `docs/product/product_overview.md` / `docs/product/user_stories.md` hardcoded 経路を解消。
+  - **phase-dependency-model**: Level 1 product 文書を `{designDocsRoot}/../...` で定義し、`Artifact.resolve()` / `expandRoots()` で POSIX 正規化。`paths.designDocs: "mydocs/product/construction"` の場合、L2 blocker は `mydocs/product/product_overview.md` / `mydocs/product/user_stories.md` を参照する。
+  - **traceability-model**: `MarkdownStoryCatalogGateway` / `MarkdownDesignDocumentGateway` / `MarkdownUnitDefinitionGateway` / `TraceabilityChainBuilder` に custom design docs root を注入し、`mydocs/product/user_stories.md` と `mydocs/product/construction/{unit}` を読むよう修正。
+  - **後方互換**: config 未指定時は従来通り `docs/product/user_stories.md` / `docs/product/construction/{unit}` を利用。
+  - **検証 (publish 前 local/self-host)**: `pnpm exec tsc --noEmit` pass。対象テスト 4 files / 29 tests pass。`pnpm test` は 453 files / 3520 tests pass。`/private/tmp/phasegate-local-wi093` の symlink なし reporter fixture で `validate --layer L2 --format human` を実行し、L2-001 blocker が `mydocs/product/product_overview.md` を参照することを確認。post-publish dogfood は publish 後に実施予定。
+
+## [0.129.0] - 2026-05-08
+
+### Fixed
+
+- **WI-092 — `createValidatorSystemModule()` 残 5 site の config threading 漏れを sweep** — v0.128.0 で `validate --layer L4` 経路のみ修正した DI 配線漏れの follow-up として、harness-api / pre-commit 経路でも user config (`layers.L2/L3/L4.enabled`) が validator-system composition root に渡るよう修正。
+  - **対象**: `ValidatorSystemExecutionAdapter` の `runL3Validators()` / `runAllValidators()` / `runDriftDetection()`、および `runPreCommitCli()` / `runCommitMsgCli()` の計 5 site。
+  - **共通 translator 化**: `toValidatorSystemConfig()` を `config-foundation/application/mappers/validator-system-config-mapper.ts` に移動し、`main.ts` / harness-api adapter / pre-commit CLI から共通利用。渡す値は `project.preset` と `layers.L2/L3/L4.enabled` のみに限定し、`validators` 配列は渡さない。validator catalog は validator-system の default 解決に委ねる。
+  - **fallback**: `phasegate.config.json` 不在時のみ validator-system の default config にフォールバック。不正 config は従来通り runtime error として扱う。
+  - **検証 (publish 前 local/self-host)**: PhaseGate 自身の `phasegate.config.json` (`layers.L4.enabled: false`) で `validate --layer L4` は exit 0 / PASS / validator 0 件。`phasegate:detect-drift --json` は drift detection direct 経路を維持し、既存 drift 2065 件により exit 1。
+  - **テスト**: `pnpm test` は 452 files / 3518 tests pass。対象テスト 3 files / 11 tests pass。変更ファイルの `validate-metadata` pass。
+  - **post-publish dogfood**: `/private/tmp/phasegate-dogfood-wi092` で `npx phasegate@0.129.0` を使い検証済み。`validate --layer L4 --format human` は exit 0 / PASS / validator 0 件、`phasegate:status --json` は L4 `enabled:false`、`phasegate:detect-drift --json` は fixture の drift 1 件を返して exit 1、`pre-commit` は staged markdown 2 件を検査して PASS。
+
 ## [0.128.0] - 2026-05-08
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.128.0",
+  "version": "0.130.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/validator-system-config-mapper.ts

@@ -0,0 +1,19 @@
+/**
+ * @layer application
+ * @unit config-foundation
+ * @work-item-id WI-092
+ */
+import type { HarnessConfigV2 } from '../../domain/harness-config.js';
+
+export function toValidatorSystemConfig(resolvedConfig: HarnessConfigV2 | undefined): object | undefined {
+  if (!resolvedConfig) return undefined;
+
+  return {
+    project: { preset: resolvedConfig.project.preset },
+    layers: {
+      L2: { enabled: resolvedConfig.layers.L2.enabled },
+      L3: { enabled: resolvedConfig.layers.L3.enabled },
+      L4: { enabled: resolvedConfig.layers.L4.enabled },
+    },
+  };
+}

package/scripts/harness/config-foundation/index.ts

@@ -1,9 +1,10 @@
 // @unit config-foundation
-// @layer public-api
+// @layer application
 
 export { createConfigFoundationModule } from './composition-root.js';
 
 export { LoadResolvedConfigUseCase } from './application/usecases/load-resolved-config-use-case.js';
+export { toValidatorSystemConfig } from './application/mappers/validator-system-config-mapper.js';
 
 export type { ResolvedConfigOutput } from './application/dto/resolved-config-output.js';
 export type { FeatureToggleResult } from './application/dto/feature-toggle-result.js';

package/scripts/harness/harness-api/infrastructure/adapters/nyquist-validation-impact-analysis-adapter.ts

@@ -1,3 +1,4 @@
+// @unit harness-api
 // @layer infrastructure
 // nyquist-validation-impact-analysis-adapter.ts — NyquistValidationImpactAnalysisAdapter
 // Wave 2完了後にリアル実装へ差し替え（旧: @stub: wave2-pending）
@@ -24,8 +25,13 @@ export class NyquistValidationImpactAnalysisAdapter implements ImpactAnalysisPor
     return {
       async analyzeImpact(storyId: string): Promise<ImpactAnalysisResult | null> {
         try {
+          const { createConfigFoundationModule } = await import('../../../config-foundation/composition-root.js');
+          const configModule = createConfigFoundationModule();
+          const resolvedConfig = await configModule.usecases.loadResolvedConfigUseCase.execute();
           const { createTraceabilityModelModule } = await import('../../../traceability-model/composition-root.js');
-          const traceModule = createTraceabilityModelModule(rootDir);
+          const traceModule = createTraceabilityModelModule(rootDir, {
+            pathRoots: { designDocsRoot: resolvedConfig.config.paths.designDocs },
+          });
           const storyIds = await traceModule.storyCatalog.getAllStoryIds();
 
           const { createNyquistValidationModule } = await import('../../../nyquist-validation/composition-root.js');

package/scripts/harness/harness-api/infrastructure/adapters/phase-dependency-model-query-adapter.ts

@@ -25,15 +25,17 @@ export class PhaseDependencyModelQueryAdapter implements PhaseGateQueryPort {
     return {
       async queryAllStories(): Promise<PhaseGateStoryResult[]> {
         try {
-          const { createTraceabilityModelModule } = await import('../../../traceability-model/composition-root.js');
-          const traceModule = createTraceabilityModelModule(rootDir);
-          const storyIds = await traceModule.storyCatalog.getAllStoryIds();
-
           // WI-085: paths config を phase-dependency-model に流入させる
           const { createConfigFoundationModule } = await import('../../../config-foundation/composition-root.js');
           const { toPhaseConfigSection } = await import('../../../config-foundation/application/mappers/phase-config-section-mapper.js');
           const configModule = createConfigFoundationModule();
           const resolvedConfig = await configModule.usecases.loadResolvedConfigUseCase.execute();
+          const { createTraceabilityModelModule } = await import('../../../traceability-model/composition-root.js');
+          const traceModule = createTraceabilityModelModule(rootDir, {
+            pathRoots: { designDocsRoot: resolvedConfig.config.paths.designDocs },
+          });
+          const storyIds = await traceModule.storyCatalog.getAllStoryIds();
+
           const { createPhaseDependencyModelModule } = await import('../../../phase-dependency-model/composition-root.js');
           const phaseModule = createPhaseDependencyModelModule({
             rootDir,

package/scripts/harness/harness-api/infrastructure/adapters/validator-system-execution-adapter.ts

@@ -1,10 +1,14 @@
+// @unit harness-api
 // @layer infrastructure
+// @work-item-id WI-092
 // validator-system-execution-adapter.ts — ValidatorSystemExecutionAdapter
 // Wave 2完了後にリアル実装へ差し替え（旧: @stub: wave2-pending）
 
 import type { ValidatorExecutionPort } from '../../domain/ports/validator-execution-port.js';
 import type { ValidatorCheckItem } from '../../domain/value-objects/ci-check-result.js';
 import type { DriftItem } from '../../domain/value-objects/drift-report-summary.js';
+import { toValidatorSystemConfig } from '../../../config-foundation/application/mappers/validator-system-config-mapper.js';
+import { ConfigNotFoundError } from '../../../config-foundation/infrastructure/repositories/file-system-config-repository.js';
 
 // Override interface preserved for testing
 export interface IValidatorSystemStub {
@@ -21,10 +25,22 @@ export class ValidatorSystemExecutionAdapter implements ValidatorExecutionPort {
   }
 
   private static createRealImpl(): IValidatorSystemStub {
+    async function loadValidatorSystemConfig(): Promise<object | undefined> {
+      const { createConfigFoundationModule } = await import('../../../config-foundation/composition-root.js');
+      const configMod = createConfigFoundationModule();
+      try {
+        const resolvedConfig = await configMod.usecases.loadResolvedConfigUseCase.execute();
+        return toValidatorSystemConfig(resolvedConfig.config);
+      } catch (err) {
+        if (err instanceof ConfigNotFoundError) return undefined;
+        throw err;
+      }
+    }
+
     return {
       async runL3Validators(): Promise<ValidatorCheckItem[]> {
         const { createValidatorSystemModule } = await import('../../../validator-system/composition-root.js');
-        const mod = createValidatorSystemModule();
+        const mod = createValidatorSystemModule(await loadValidatorSystemConfig());
         const results = await mod.runL3ValidatorsUseCase.execute({ targetPaths: [] });
         return results.map((r) => ({
           validatorId: r.validatorId,
@@ -35,7 +51,7 @@ export class ValidatorSystemExecutionAdapter implements ValidatorExecutionPort {
 
       async runAllValidators(): Promise<ValidatorCheckItem[]> {
         const { createValidatorSystemModule } = await import('../../../validator-system/composition-root.js');
-        const mod = createValidatorSystemModule();
+        const mod = createValidatorSystemModule(await loadValidatorSystemConfig());
         const report = await mod.runFullValidationUseCase.execute({ targetPaths: [], unitName: '', currentPhase: '' });
         return report.results.map((r) => ({
           validatorId: r.validatorId,
@@ -48,7 +64,7 @@ export class ValidatorSystemExecutionAdapter implements ValidatorExecutionPort {
         // ISSUE-005 P1-5: L4-001 の DriftDetectionService を直接呼び出し、
         // phasegate:detect-drift と validate --layer L4 の結果を一致させる
         const { createValidatorSystemModule } = await import('../../../validator-system/composition-root.js');
-        const mod = createValidatorSystemModule();
+        const mod = createValidatorSystemModule(await loadValidatorSystemConfig());
         const reports = await mod.driftDetectionService.detect();
         return reports.map((r) => ({
           direction: r.direction,

package/scripts/harness/integrations/pre-commit.ts

@@ -1,6 +1,7 @@
 /**
  * @unit harness-api
  * @layer presentation
+ * @work-item-id WI-092
  *
  * Pre-commit CLI entry.
  * Runs L2 validators against staged TypeScript files AND design-document
@@ -15,6 +16,9 @@
 
 import { execSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
+import { createConfigFoundationModule } from "../config-foundation/composition-root.js";
+import { toValidatorSystemConfig } from "../config-foundation/application/mappers/validator-system-config-mapper.js";
+import { ConfigNotFoundError } from "../config-foundation/infrastructure/repositories/file-system-config-repository.js";
 import { createTraceabilityModelModule } from "../traceability-model/composition-root.js";
 import type { ValidateMetadataCommandOutput } from "../traceability-model/presentation/cli/validate-metadata-command-handler.js";
 import type { AggregatedValidationReport } from "../validator-system/application/dto/aggregated-validation-report.js";
@@ -34,6 +38,30 @@ const WORK_ITEM_PATH_PATTERN = /(?:^|\/)WI-\d+(?:\/|$)/;
 const WORK_ITEM_TRAILER_PATTERN = /^Work-Item:\s*WI-\d+\s*$/m;
 const TEST_FILE_SUFFIXES = Object.freeze([".test.ts", ".test.tsx", ".spec.ts", ".spec.tsx"]);
 
+async function loadValidatorSystemConfig(): Promise<object | undefined> {
+  const configMod = createConfigFoundationModule();
+  try {
+    const resolvedConfig = await configMod.usecases.loadResolvedConfigUseCase.execute();
+    return toValidatorSystemConfig(resolvedConfig.config);
+  } catch (err) {
+    if (err instanceof ConfigNotFoundError) return undefined;
+    throw err;
+  }
+}
+
+async function loadTraceabilityModelOptions(): Promise<
+  { readonly pathRoots: { readonly designDocsRoot: string } } | undefined
+> {
+  const configMod = createConfigFoundationModule();
+  try {
+    const resolvedConfig = await configMod.usecases.loadResolvedConfigUseCase.execute();
+    return { pathRoots: { designDocsRoot: resolvedConfig.config.paths.designDocs } };
+  } catch (err) {
+    if (err instanceof ConfigNotFoundError) return undefined;
+    throw err;
+  }
+}
+
 function isTestFile(path: string): boolean {
   return TEST_FILE_SUFFIXES.some((suffix) => path.endsWith(suffix));
 }
@@ -303,8 +331,11 @@ export async function runPreCommit(
 export async function runPreCommitCli(): Promise<void> {
   try {
     const stagedFiles = getStagedFiles();
-    const validatorMod = createValidatorSystemModule();
-    const traceabilityMod = createTraceabilityModelModule(process.cwd());
+    const validatorMod = createValidatorSystemModule(await loadValidatorSystemConfig());
+    const traceabilityMod = createTraceabilityModelModule(
+      process.cwd(),
+      await loadTraceabilityModelOptions(),
+    );
 
     const result = await runPreCommit(
       stagedFiles,
@@ -335,8 +366,11 @@ export async function runCommitMsgCli(commitMessagePath: string | undefined): Pr
 
     const stagedFiles = getStagedFiles();
     const commitMessage = await readFile(commitMessagePath, "utf-8");
-    const validatorMod = createValidatorSystemModule();
-    const traceabilityMod = createTraceabilityModelModule(process.cwd());
+    const validatorMod = createValidatorSystemModule(await loadValidatorSystemConfig());
+    const traceabilityMod = createTraceabilityModelModule(
+      process.cwd(),
+      await loadTraceabilityModelOptions(),
+    );
 
     const result = await runPreCommit(
       stagedFiles,

package/scripts/harness/main.ts

@@ -14,6 +14,7 @@ import { createAdrFoundationModule } from "./adr-foundation/composition-root.js"
 import { createBiomeAstEngineModule } from "./biome-ast-engine/composition-root.js";
 import { buildCiGovernance } from "./ci-governance/composition-root.js";
 import { toPhaseConfigSection } from "./config-foundation/application/mappers/phase-config-section-mapper.js";
+import { toValidatorSystemConfig } from "./config-foundation/application/mappers/validator-system-config-mapper.js";
 import { createConfigFoundationModule } from "./config-foundation/composition-root.js";
 import { ConfigValidationError } from "./config-foundation/domain/errors/config-validation-error.js";
 import type { HarnessConfigV2 } from "./config-foundation/domain/harness-config.js";
@@ -66,6 +67,12 @@ function getProjectRoot(): string {
   return process.cwd();
 }
 
+function toTraceabilityModelOptions(resolvedConfig: HarnessConfigV2 | undefined) {
+  return resolvedConfig
+    ? { pathRoots: { designDocsRoot: resolvedConfig.paths.designDocs } }
+    : undefined;
+}
+
 async function pathExists(path: string): Promise<boolean> {
   try {
     await access(path);
@@ -455,27 +462,6 @@ function toL1Config(resolvedConfig: HarnessConfigV2) {
  * HarnessConfigV2 (resolved) から biome-ast-engine が期待する architecture 情報を抽出する。
  * architecture が未設定の場合は undefined を返し、biome-ast-engine 側の default (clean) に委ねる。
  */
-/**
- * HarnessConfigV2 (resolved) から validator-system の `createValidatorSystemModule` が
- * 期待する shape (`{ project: { preset }, layers: { L2/L3/L4: { enabled } } }`) に変換する。
- *
- * WI-091 finding #1 follow-up: 直接 resolvedConfig を渡すと preset-style の
- * `validators: ["drift-detector"]` が validator-code (L4-001/002/003) を上書きし
- * 全 SKIP になる症状が出るため、`enabled` field のみ thread し validators の
- * 解決は composition root 側の defaultValidators[layer] フォールバックに委ねる。
- */
-function toValidatorSystemConfig(resolvedConfig: HarnessConfigV2 | undefined): object | undefined {
-  if (!resolvedConfig) return undefined;
-  return {
-    project: { preset: resolvedConfig.project.preset },
-    layers: {
-      L2: { enabled: resolvedConfig.layers.L2.enabled },
-      L3: { enabled: resolvedConfig.layers.L3.enabled },
-      L4: { enabled: resolvedConfig.layers.L4.enabled },
-    },
-  };
-}
-
 function toArchitectureInput(resolvedConfig: HarnessConfigV2) {
   if (!resolvedConfig.architecture) {
     return undefined;
@@ -854,7 +840,10 @@ async function main(): Promise<void> {
 
       case "migrate": {
         if (args[1] === "work-items") {
-          const mod = createTraceabilityModelModule(rootDir);
+          const mod = createTraceabilityModelModule(
+            rootDir,
+            toTraceabilityModelOptions(resolvedConfig),
+          );
           const result = await mod.migrateWorkItemsCommandHandler.execute({
             dryRun: hasFlag(args, "--dry-run"),
             apply: hasFlag(args, "--apply"),
@@ -921,7 +910,10 @@ async function main(): Promise<void> {
 
       // ── traceability-model ──
       case "validate-metadata": {
-        const mod = createTraceabilityModelModule(rootDir);
+        const mod = createTraceabilityModelModule(
+          rootDir,
+          toTraceabilityModelOptions(resolvedConfig),
+        );
         const filePaths = parsePositionalArgs(args.slice(1));
         const result = await mod.validateMetadataCommandHandler.execute({
           filePaths,

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

@@ -31,7 +31,7 @@ export const FULL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
     },
     {
       name: 'product-overview',
-      path: 'docs/product/product_overview.md',
+      path: '{designDocsRoot}/../product_overview.md',
       required: true,
     },
   ]),
@@ -43,7 +43,7 @@ export const FULL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
     },
     {
       name: 'user-stories',
-      path: 'docs/product/user_stories.md',
+      path: '{designDocsRoot}/../user_stories.md',
       required: true,
     },
   ]),
@@ -55,7 +55,7 @@ export const FULL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
     },
     {
       name: 'user-story-mapping',
-      path: 'docs/product/user_story_mapping.md',
+      path: '{designDocsRoot}/../user_story_mapping.md',
       required: true,
     },
   ]),
@@ -67,12 +67,12 @@ export const FULL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
     },
     {
       name: 'unit-definition',
-      path: 'docs/product/units/{unit}_unit.md',
+      path: '{designDocsRoot}/../units/{unit}_unit.md',
       required: true,
     },
     {
       name: 'integration-contract',
-      path: 'docs/product/units/integration_contract.md',
+      path: '{designDocsRoot}/../units/integration_contract.md',
       required: true,
     },
   ]),

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

@@ -31,7 +31,7 @@ export const MINIMAL_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
     },
     {
       name: 'product-overview',
-      path: 'docs/product/product_overview.md',
+      path: '{designDocsRoot}/../product_overview.md',
       required: true,
     },
   ]),

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

@@ -31,7 +31,7 @@ export const STANDARD_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
     },
     {
       name: 'product-overview',
-      path: 'docs/product/product_overview.md',
+      path: '{designDocsRoot}/../product_overview.md',
       required: true,
     },
   ]),
@@ -43,7 +43,7 @@ export const STANDARD_PHASE_NODES: readonly PhaseNode[] = Object.freeze([
     },
     {
       name: 'user-stories',
-      path: 'docs/product/user_stories.md',
+      path: '{designDocsRoot}/../user_stories.md',
       required: true,
     },
   ]),

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

@@ -2,6 +2,7 @@
  * @layer domain
  * @unit phase-dependency-model
  */
+import path from 'node:path';
 
 const ALLOWED_PLACEHOLDERS = new Set([
   'unit',
@@ -22,6 +23,8 @@ export const DEFAULT_PATH_ROOTS: PathRoots = Object.freeze({
   inceptionDocsRoot: 'docs/inception',
 });
 
+const normalizeProjectPath = (value: string): string => path.posix.normalize(value);
+
 export interface ArtifactCreateArgs {
   readonly name: string;
   readonly path: string;
@@ -105,13 +108,15 @@ export class Artifact {
       throw new InvalidArtifactPathError(this.path);
     }
 
-    return resolvedPath;
+    return normalizeProjectPath(resolvedPath);
   }
 
   expandRoots(pathRoots: PathRoots = DEFAULT_PATH_ROOTS): string {
-    return this.path
-      .replaceAll('{designDocsRoot}', pathRoots.designDocsRoot)
-      .replaceAll('{inceptionDocsRoot}', pathRoots.inceptionDocsRoot);
+    return normalizeProjectPath(
+      this.path
+        .replaceAll('{designDocsRoot}', pathRoots.designDocsRoot)
+        .replaceAll('{inceptionDocsRoot}', pathRoots.inceptionDocsRoot),
+    );
   }
 
   equals(other: Artifact): boolean {

package/scripts/harness/traceability-model/composition-root.ts

@@ -1,5 +1,5 @@
 /**
- * @layer composition
+ * @layer application
  * @unit traceability-model
  *
  * traceability-model ユニットの Composition Root。
@@ -25,12 +25,39 @@ import { MarkdownUnitDefinitionGateway } from "./infrastructure/gateways/markdow
 import { MigrateWorkItemsCommandHandler } from "./presentation/cli/migrate-work-items-command-handler.js";
 import { ValidateMetadataCommandHandler } from "./presentation/cli/validate-metadata-command-handler.js";
 
-export function createTraceabilityModelModule(rootDir: string) {
+export interface TraceabilityModelPathRoots {
+  readonly designDocsRoot: string;
+}
+
+export interface TraceabilityModelModuleOptions {
+  readonly pathRoots?: TraceabilityModelPathRoots;
+}
+
+const deriveProductDocsRoot = (designDocsRoot: string): string => {
+  const normalized = designDocsRoot.replace(/\/+$/, "");
+  if (normalized.endsWith("/construction")) {
+    return normalized.slice(0, -"/construction".length);
+  }
+  return normalized;
+};
+
+export function createTraceabilityModelModule(
+  rootDir: string,
+  options: TraceabilityModelModuleOptions = {},
+) {
+  const designDocsRoot = options.pathRoots?.designDocsRoot ?? "docs/product/construction";
+  const productDocsRoot = deriveProductDocsRoot(designDocsRoot);
+  const storyCatalogPath = `${productDocsRoot}/user_stories.md`;
+
   // Infrastructure gateways
-  const storyCatalog = new MarkdownStoryCatalogGateway({ rootDir });
-  const unitDefinition = new MarkdownUnitDefinitionGateway({ rootDir });
+  const storyCatalog = new MarkdownStoryCatalogGateway({ rootDir, storyCatalogPath });
+  const unitDefinition = new MarkdownUnitDefinitionGateway({
+    rootDir,
+    productDocsRoot,
+    designDocsRoot,
+  });
   const metadataReader = new FileSystemMetadataReader({ rootDir });
-  const designDocument = new MarkdownDesignDocumentGateway({ rootDir });
+  const designDocument = new MarkdownDesignDocumentGateway({ rootDir, designDocsRoot });
   const inceptionPlan = new FileSystemInceptionPlanGateway({ rootDir });
   const workItemMigrationSource = new FileSystemWorkItemMigrationSourceGateway({ rootDir });
   const workItemMigrationApply = new FileSystemWorkItemMigrationApplyGateway({ rootDir });
@@ -46,6 +73,7 @@ export function createTraceabilityModelModule(rootDir: string) {
     designDocumentPort: designDocument,
     storyCatalogPort: storyCatalog,
     inceptionPlanPort: inceptionPlan,
+    storyCatalogPath,
   });
   const storyIdAliasResolver = new StoryIdAliasResolver(storyCatalog);
 

package/scripts/harness/traceability-model/domain/services/traceability-chain-builder.ts

@@ -17,7 +17,7 @@ import type { StoryIdLike } from '../value-objects/story-reference.js';
 import { TraceabilityChain } from '../value-objects/traceability-chain.js';
 
 const PROJECT_RELATIVE_PATH_PATTERN = /^(docs|scripts|inception)\//;
-const STORY_CATALOG_PATH = 'docs/product/user_stories.md';
+const DEFAULT_STORY_CATALOG_PATH = 'docs/product/user_stories.md';
 
 const createPath = (value: string): ProjectRelativePathLike =>
   Object.freeze({
@@ -136,6 +136,7 @@ export class TraceabilityChainBuilder {
   private readonly designDocumentPort: DesignDocumentPort;
   private readonly storyCatalogPort: StoryCatalogPort;
   private readonly inceptionPlanPort: InceptionPlanPort;
+  private readonly storyCatalogPath: ProjectRelativePathLike;
 
   constructor(deps: {
     readonly metadataReaderPort: MetadataReaderPort;
@@ -143,12 +144,16 @@ export class TraceabilityChainBuilder {
     readonly designDocumentPort: DesignDocumentPort;
     readonly storyCatalogPort: StoryCatalogPort;
     readonly inceptionPlanPort: InceptionPlanPort;
+    readonly storyCatalogPath?: string;
   }) {
     this.metadataReaderPort = deps.metadataReaderPort;
     this.unitDefinitionPort = deps.unitDefinitionPort;
     this.designDocumentPort = deps.designDocumentPort;
     this.storyCatalogPort = deps.storyCatalogPort;
     this.inceptionPlanPort = deps.inceptionPlanPort;
+    this.storyCatalogPath = createPath(
+      deps.storyCatalogPath ?? DEFAULT_STORY_CATALOG_PATH,
+    );
   }
 
   async build(origin: string | ProjectRelativePathLike): Promise<TraceabilityChain> {
@@ -235,7 +240,7 @@ export class TraceabilityChainBuilder {
         designToStoryLinks.push(
           createLink({
             from: designDocument,
-            to: createPath(STORY_CATALOG_PATH),
+            to: this.storyCatalogPath,
             linkType: 'design-to-story',
             resolved: false,
           }),
@@ -248,7 +253,7 @@ export class TraceabilityChainBuilder {
         designToStoryLinks.push(
           createLink({
             from: designDocument,
-            to: createPath(STORY_CATALOG_PATH),
+            to: this.storyCatalogPath,
             linkType: 'design-to-story',
             resolved: storyResolved,
           }),
@@ -265,7 +270,7 @@ export class TraceabilityChainBuilder {
         );
         storyToPlanLinks.push(
           createLink({
-            from: createPath(STORY_CATALOG_PATH),
+            from: this.storyCatalogPath,
             to:
               planRoot ??
               createPlaceholderPath(

package/scripts/harness/traceability-model/domain/value-objects/project-relative-path.ts

@@ -2,10 +2,8 @@
  * @layer domain
  * @unit traceability-model
  *
- * docs/ または scripts/ 配下のPOSIX相対パス
+ * プロジェクト相対POSIXパス
  */
-const ALLOWED_PROJECT_ROOTS = new Set(['docs', 'scripts']);
-
 export class ProjectRelativePathError extends Error {
   readonly value: string;
 
@@ -42,7 +40,7 @@ const normalizeSegments = (rawValue: string): readonly string[] => {
       return segment;
     });
 
-  if (segments.length === 0 || !ALLOWED_PROJECT_ROOTS.has(segments[0])) {
+  if (segments.length === 0) {
     throw new ProjectRelativePathError(rawValue);
   }
 

package/scripts/harness/traceability-model/infrastructure/gateways/markdown-design-document-gateway.ts

@@ -21,18 +21,22 @@ import { parseWorkItemFrontmatter } from "../parsers/work-item-frontmatter-parse
 
 export interface MarkdownDesignDocumentGatewayDeps {
   readonly rootDir: string;
+  readonly designDocsRoot?: string;
 }
 
 export class MarkdownDesignDocumentGateway implements DesignDocumentPort {
   private readonly rootDir: string;
+  private readonly designDocsRoot: string;
   private readonly contentCache = new Map<string, string>();
 
   constructor(deps: MarkdownDesignDocumentGatewayDeps) {
     this.rootDir = deps.rootDir;
+    this.designDocsRoot = deps.designDocsRoot ?? path.join("docs", "product", "construction");
   }
 
   async listByUnit(unitName: string): Promise<readonly ProjectRelativePathLike[]> {
-    const constructionDir = path.join(this.rootDir, "docs", "product", "construction", unitName);
+    const constructionRoot = path.posix.join(this.designDocsRoot, unitName);
+    const constructionDir = path.join(this.rootDir, constructionRoot);
 
     if (!fs.existsSync(constructionDir)) {
       return [];
@@ -43,7 +47,7 @@ export class MarkdownDesignDocumentGateway implements DesignDocumentPort {
 
     for (const entry of entries) {
       if (entry.endsWith(".md")) {
-        results.push(ProjectRelativePath.create(`docs/product/construction/${unitName}/${entry}`));
+        results.push(ProjectRelativePath.create(path.posix.join(constructionRoot, entry)));
       }
     }
 

package/scripts/harness/traceability-model/infrastructure/gateways/markdown-story-catalog-gateway.ts

@@ -13,16 +13,23 @@ import { parseStoryCatalog } from '../parsers/story-catalog-parser.js';
 
 export interface MarkdownStoryCatalogGatewayDeps {
   readonly rootDir: string;
+  readonly storyCatalogPath?: string;
 }
 
 export class MarkdownStoryCatalogGateway implements StoryCatalogPort {
   private readonly rootDir: string;
+  private readonly storyCatalogPath: string;
   private cachedStoryIds: readonly StoryIdLike[] | null = null;
   private cachedAliasMap: ReadonlyMap<string, StoryIdLike> | null = null;
   private cachedMtime: number | null = null;
 
   constructor(deps: MarkdownStoryCatalogGatewayDeps) {
     this.rootDir = deps.rootDir;
+    this.storyCatalogPath = deps.storyCatalogPath ?? path.join(
+      'docs',
+      'product',
+      'user_stories.md',
+    );
   }
 
   async getAllStoryIds(): Promise<readonly StoryIdLike[]> {
@@ -48,12 +55,7 @@ export class MarkdownStoryCatalogGateway implements StoryCatalogPort {
   }
 
   private async ensureLoaded(): Promise<void> {
-    const filePath = path.join(
-      this.rootDir,
-      'docs',
-      'product',
-      'user_stories.md',
-    );
+    const filePath = path.join(this.rootDir, this.storyCatalogPath);
 
     let currentMtime: number;
     try {

package/scripts/harness/traceability-model/infrastructure/gateways/markdown-unit-definition-gateway.ts

@@ -15,14 +15,20 @@ const UNIT_ID_PATTERN = /Unit\s+ID\*{0,2}\s*[:：]\s*(\S+)/;
 
 export interface MarkdownUnitDefinitionGatewayDeps {
   readonly rootDir: string;
+  readonly productDocsRoot?: string;
+  readonly designDocsRoot?: string;
 }
 
 export class MarkdownUnitDefinitionGateway implements UnitDefinitionPort {
   private readonly rootDir: string;
+  private readonly productDocsRoot: string;
+  private readonly designDocsRoot: string;
   private cachedUnitNames: readonly string[] | null = null;
 
   constructor(deps: MarkdownUnitDefinitionGatewayDeps) {
     this.rootDir = deps.rootDir;
+    this.productDocsRoot = deps.productDocsRoot ?? path.join('docs', 'product');
+    this.designDocsRoot = deps.designDocsRoot ?? path.join('docs', 'product', 'construction');
   }
 
   async getAllUnitNames(): Promise<readonly string[]> {
@@ -47,7 +53,7 @@ export class MarkdownUnitDefinitionGateway implements UnitDefinitionPort {
       return null;
     }
 
-    const constructionPath = `docs/product/construction/${unitName}`;
+    const constructionPath = path.posix.join(this.designDocsRoot, unitName);
     const absolutePath = path.join(this.rootDir, constructionPath);
 
     if (!fs.existsSync(absolutePath)) {
@@ -68,7 +74,7 @@ export class MarkdownUnitDefinitionGateway implements UnitDefinitionPort {
       return;
     }
 
-    const unitsDir = path.join(this.rootDir, 'docs', 'product', 'units');
+    const unitsDir = path.join(this.rootDir, this.productDocsRoot, 'units');
     if (!fs.existsSync(unitsDir)) {
       this.cachedUnitNames = Object.freeze([]);
       return;

package/scripts/harness/traceability-model/presentation/cli/validate-metadata-command-handler.ts

@@ -110,7 +110,7 @@ export class ValidateMetadataCommandHandler {
           results: Object.freeze([]),
           text:
             `Error: invalid file path: "${err.value}"\n` +
-            `  Hint: paths must be project-relative and start with 'docs/' or 'scripts/'.`,
+            `  Hint: paths must be project-relative POSIX paths without '..' segments.`,
         });
       }
       return Object.freeze({