phasegate 0.129.0 → 0.130.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ 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
@@ -17,7 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **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**: npm publish 後に、別ディレクトリで `npx phasegate@0.129.0` を使って `phasegate:detect-drift` / `validate --layer L4` / pre-commit 経路を確認する。
+  - **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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.129.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/index.ts

@@ -1,5 +1,5 @@
 // @unit config-foundation
-// @layer public-api
+// @layer application
 
 export { createConfigFoundationModule } from './composition-root.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/integrations/pre-commit.ts

@@ -49,6 +49,19 @@ async function loadValidatorSystemConfig(): Promise<object | undefined> {
   }
 }
 
+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));
 }
@@ -319,7 +332,10 @@ export async function runPreCommitCli(): Promise<void> {
   try {
     const stagedFiles = getStagedFiles();
     const validatorMod = createValidatorSystemModule(await loadValidatorSystemConfig());
-    const traceabilityMod = createTraceabilityModelModule(process.cwd());
+    const traceabilityMod = createTraceabilityModelModule(
+      process.cwd(),
+      await loadTraceabilityModelOptions(),
+    );
 
     const result = await runPreCommit(
       stagedFiles,
@@ -351,7 +367,10 @@ export async function runCommitMsgCli(commitMessagePath: string | undefined): Pr
     const stagedFiles = getStagedFiles();
     const commitMessage = await readFile(commitMessagePath, "utf-8");
     const validatorMod = createValidatorSystemModule(await loadValidatorSystemConfig());
-    const traceabilityMod = createTraceabilityModelModule(process.cwd());
+    const traceabilityMod = createTraceabilityModelModule(
+      process.cwd(),
+      await loadTraceabilityModelOptions(),
+    );
 
     const result = await runPreCommit(
       stagedFiles,

package/scripts/harness/main.ts

@@ -67,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);
@@ -834,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"),
@@ -901,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({