phasegate 0.161.0 → 0.163.0

package/scripts/harness/installation/application/usecases/run-install.ts

@@ -19,7 +19,6 @@
 
 import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink, readdir, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { readModelDelegationPolicy, renderSkillForModelDelegation } from "../../../setup/skill-deployer.js";
 import { DeploymentEntry } from "../../domain/deployment-entry.js";
 import { DeploymentManifest } from "../../domain/deployment-manifest.js";
 import type { ManagedBlockInput } from "../../domain/managed-block.js";
@@ -27,6 +26,7 @@ import type { RepairMode } from "../../domain/repair-mode.js";
 import { getBundledSkillsForSet, type SkillSet } from "../bundled-skill-selection.js";
 import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
 import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
+import type { ModelDelegationPort } from "../ports/model-delegation-port.js";
 
 type InstallAction = "missing" | "will-merge" | "will-skip" | "will-overwrite";
 type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "markdown-managed" | "text-managed" | "copy" | "copy-dir" | "symlink";
@@ -40,6 +40,10 @@ export interface InstallPlanItem {
   readonly summary: string;
   readonly diff: string;
   readonly skillHint: string | null;
+  // Non-null when a target could not be applied cleanly and the user must act
+  // (e.g. a pre-existing git hook that phasegate will not overwrite). Surfaces
+  // situations that would otherwise be silently skipped.
+  readonly warning: string | null;
 }
 
 export interface RunInstallInput {
@@ -135,13 +139,14 @@ async function copyDirectory(src: string, dest: string): Promise<void> {
 }
 
 async function copySelectedSkillDirectories(
+  modelDelegation: ModelDelegationPort,
   harnessRoot: string,
   projectRoot: string,
   targetRoot: string,
   skills: readonly string[],
 ): Promise<void> {
   await mkdir(targetRoot, { recursive: true });
-  const modelDelegationPolicy = await readModelDelegationPolicy(projectRoot);
+  const modelDelegationPolicy = await modelDelegation.readPolicy(projectRoot);
   for (const skill of skills) {
     const source = join(harnessRoot, "skills", skill);
     const target = join(targetRoot, skill);
@@ -150,7 +155,7 @@ async function copySelectedSkillDirectories(
     if (modelDelegationPolicy === "none") {
       const skillPath = join(target, "SKILL.md");
       const content = await readFile(skillPath, "utf8");
-      await writeFile(skillPath, renderSkillForModelDelegation(content, modelDelegationPolicy), "utf8");
+      await writeFile(skillPath, modelDelegation.renderSkill(content, modelDelegationPolicy), "utf8");
     }
   }
 }
@@ -165,8 +170,28 @@ async function listSelectedBundledSkills(harnessRoot: string, skillSet: SkillSet
     .sort();
 }
 
+// Canonical, key-order-independent serialization used as a dedup key when
+// merging hook arrays. Plain `JSON.stringify` is sensitive to object key order,
+// so two structurally identical hook entries authored with different key orders
+// would be treated as distinct and appended on every merge, breaking merge
+// idempotency. Sorting keys recursively makes the key stable.
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(record).sort()) {
+      sorted[key] = canonicalize(record[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
 function normalizeJsonEntry(value: unknown): string {
-  return JSON.stringify(value);
+  return JSON.stringify(canonicalize(value));
 }
 
 function mergeHookArrays(existing: unknown, incoming: unknown): unknown[] {
@@ -344,6 +369,7 @@ export class RunInstallUseCase {
   constructor(
     private readonly manifestRepository: ManifestRepositoryPort,
     private readonly hashCalculator: HashCalculatorPort,
+    private readonly modelDelegation: ModelDelegationPort,
   ) {}
 
   async execute(input: RunInstallInput): Promise<RunInstallResult> {
@@ -384,6 +410,18 @@ export class RunInstallUseCase {
       const next = unmanagedPersonalRuntimeFile ? before : this.merge(target, before, template, input.phasegateVersion);
       const didChange = before !== next;
       const action = this.actionFor(before, didChange, input.force);
+      // A `copy` target with a pre-existing, non-matching file is left untouched
+      // (merge returns `before`). For executable git hooks this means the
+      // phasegate hook is NOT wired in — warn instead of skipping silently.
+      const preservedExistingHook =
+        target.strategy === "copy"
+        && target.executable === true
+        && before !== null
+        && before.trim() !== template.trim()
+        && !input.force;
+      const warning = preservedExistingHook
+        ? `${target.path}: an existing hook was found and left unchanged; phasegate's checks are NOT wired in. Merge the phasegate hook manually (or rerun with --force to back up and overwrite).`
+        : null;
       const item: InstallPlanItem = {
         path: target.path,
         action,
@@ -392,9 +430,12 @@ export class RunInstallUseCase {
         changed: didChange,
         summary: unmanagedPersonalRuntimeFile
           ? `${target.path}: existing non-phasegate runtime path requires manual review`
-          : didChange ? `${target.path}: ${action}` : `${target.path}: already up to date`,
+          : warning !== null
+            ? warning
+            : didChange ? `${target.path}: ${action}` : `${target.path}: already up to date`,
         diff: unmanagedPersonalRuntimeFile ? "manual review required" : this.diffSummary(before, next),
         skillHint: repairMode === "ai-assisted" ? SKILL_HINT : null,
+        warning,
       };
       plan.push(item);
 
@@ -458,7 +499,7 @@ export class RunInstallUseCase {
       plan.push(item);
       if (input.apply && item.changed && item.repairMode === "mechanical") {
         try {
-          await copySelectedSkillDirectories(input.harnessRoot, input.projectRoot, join(input.projectRoot, skillPath), selectedPersonalSkills);
+          await copySelectedSkillDirectories(this.modelDelegation, input.harnessRoot, input.projectRoot, join(input.projectRoot, skillPath), selectedPersonalSkills);
           await writeFile(
             join(input.projectRoot, skillPath, ".harness-version"),
             `${JSON.stringify({ version: input.phasegateVersion, deployedAt: new Date().toISOString(), skillSet }, null, 2)}\n`,
@@ -548,6 +589,7 @@ export class RunInstallUseCase {
         summary: "~/.codex/config.toml: personal mode does not write user-level Codex feature flags; enable hooks manually when needed",
         diff: "manual Codex hooks feature enablement may be required",
         skillHint: null,
+        warning: null,
       });
     }
 
@@ -803,6 +845,7 @@ export class RunInstallUseCase {
           summary: `${relativePath}: existing non-directory skills path requires manual review`,
           diff: "manual review required",
           skillHint: null,
+          warning: null,
         };
       }
     } catch {}
@@ -830,6 +873,7 @@ export class RunInstallUseCase {
       summary: changed ? `${relativePath}: deploy bundled skills` : `${relativePath}: already up to date`,
       diff: changed ? `+ ${skills.length} bundled skills (${skillSet})` : "no changes",
       skillHint: null,
+      warning: null,
     };
   }
 
@@ -870,12 +914,13 @@ export class RunInstallUseCase {
       summary: changed ? "skills: deploy shared bundled skills" : "skills: already up to date",
       diff: changed ? `+ ${skills.length} bundled skills (${skillSet})` : "no changes",
       skillHint: null,
+      warning: null,
     };
   }
 
   private async deploySharedSkills(input: RunInstallInput, skills: readonly string[], skillSet: SkillSet): Promise<void> {
     const targetRoot = join(input.projectRoot, "skills");
-    await copySelectedSkillDirectories(input.harnessRoot, input.projectRoot, targetRoot, skills);
+    await copySelectedSkillDirectories(this.modelDelegation, input.harnessRoot, input.projectRoot, targetRoot, skills);
     await writeFile(
       join(targetRoot, ".harness-version"),
       `${JSON.stringify({ version: input.phasegateVersion, deployedAt: new Date().toISOString(), skillSet }, null, 2)}\n`,
@@ -927,6 +972,7 @@ export class RunInstallUseCase {
           summary: `${relativePath}: already linked`,
           diff: "no changes",
           skillHint: null,
+          warning: null,
         };
       }
       return {
@@ -938,6 +984,7 @@ export class RunInstallUseCase {
         summary: `${relativePath}: existing non-phasegate path requires manual review`,
         diff: "manual review required",
         skillHint: null,
+        warning: null,
       };
     } catch {
       try {
@@ -952,6 +999,7 @@ export class RunInstallUseCase {
             summary: `${relativePath}: parent path exists and requires manual review`,
             diff: "manual review required",
             skillHint: null,
+            warning: null,
           };
         }
       } catch {}
@@ -964,6 +1012,7 @@ export class RunInstallUseCase {
         summary: `${relativePath}: create symlink`,
         diff: `+ symlink ${target}`,
         skillHint: null,
+        warning: null,
       };
     }
   }

package/scripts/harness/installation/application/usecases/run-reconcile.ts

@@ -9,7 +9,6 @@
 
 import { access, chmod, copyFile, lstat, mkdir, readFile, readlink, readdir, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
-import { readModelDelegationPolicy, renderSkillForModelDelegation } from "../../../setup/skill-deployer.js";
 import { DeploymentEntry } from "../../domain/deployment-entry.js";
 import { DeploymentManifest } from "../../domain/deployment-manifest.js";
 import type { ManagedBlockInput } from "../../domain/managed-block.js";
@@ -17,6 +16,7 @@ import type { RepairMode } from "../../domain/repair-mode.js";
 import { getBundledSkillsForSet, type SkillSet } from "../bundled-skill-selection.js";
 import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
 import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
+import type { ModelDelegationPort } from "../ports/model-delegation-port.js";
 
 type ReconcileAction = "missing-manifest" | "update" | "add" | "link" | "skip" | "refuse";
 type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "markdown-managed" | "copy-dir" | "symlink" | "unknown";
@@ -99,13 +99,14 @@ async function copyDirectory(src: string, dest: string): Promise<void> {
 }
 
 async function copySelectedSkillDirectories(
+  modelDelegation: ModelDelegationPort,
   harnessRoot: string,
   projectRoot: string,
   targetRoot: string,
   skills: readonly string[],
 ): Promise<void> {
   await mkdir(targetRoot, { recursive: true });
-  const modelDelegationPolicy = await readModelDelegationPolicy(projectRoot);
+  const modelDelegationPolicy = await modelDelegation.readPolicy(projectRoot);
   for (const skill of skills) {
     const source = join(harnessRoot, "skills", skill);
     const target = join(targetRoot, skill);
@@ -114,7 +115,7 @@ async function copySelectedSkillDirectories(
     if (modelDelegationPolicy === "none") {
       const skillPath = join(target, "SKILL.md");
       const content = await readFile(skillPath, "utf8");
-      await writeFile(skillPath, renderSkillForModelDelegation(content, modelDelegationPolicy), "utf8");
+      await writeFile(skillPath, modelDelegation.renderSkill(content, modelDelegationPolicy), "utf8");
     }
   }
 }
@@ -129,18 +130,19 @@ async function listSelectedBundledSkills(harnessRoot: string, skillSet: SkillSet
 }
 
 async function hasRenderedSkillDrift(
+  modelDelegation: ModelDelegationPort,
   harnessRoot: string,
   projectRoot: string,
   targetRoot: string,
   skills: readonly string[],
 ): Promise<boolean> {
-  const modelDelegationPolicy = await readModelDelegationPolicy(projectRoot);
+  const modelDelegationPolicy = await modelDelegation.readPolicy(projectRoot);
   for (const skill of skills) {
     const current = await readTextOrNull(join(targetRoot, skill, "SKILL.md"));
     if (current === null) return true;
     const source = await readTextOrNull(join(harnessRoot, "skills", skill, "SKILL.md"));
     if (source === null) continue;
-    const expected = renderSkillForModelDelegation(source, modelDelegationPolicy);
+    const expected = modelDelegation.renderSkill(source, modelDelegationPolicy);
     if (current !== expected) return true;
   }
   return false;
@@ -265,6 +267,7 @@ export class RunReconcileUseCase {
   constructor(
     private readonly manifestRepository: ManifestRepositoryPort,
     private readonly hashCalculator: HashCalculatorPort,
+    private readonly modelDelegation: ModelDelegationPort,
   ) {}
 
   async execute(input: RunReconcileInput): Promise<RunReconcileResult> {
@@ -523,6 +526,7 @@ export class RunReconcileUseCase {
     const missingManifest = manifest.findEntry(SHARED_SKILLS_VERSION_PATH) === null
       || skills.some((skill) => manifest.findEntry(`skills/${skill}`) === null);
     const renderedSkillDrift = await hasRenderedSkillDrift(
+      this.modelDelegation,
       input.harnessRoot,
       input.projectRoot,
       this.resolveProjectPath(input.projectRoot, "skills"),
@@ -551,7 +555,7 @@ export class RunReconcileUseCase {
 
   private async deploySharedSkills(input: RunReconcileInput, skills: readonly string[], skillSet: SkillSet): Promise<void> {
     const targetRoot = this.resolveProjectPath(input.projectRoot, "skills");
-    await copySelectedSkillDirectories(input.harnessRoot, input.projectRoot, targetRoot, skills);
+    await copySelectedSkillDirectories(this.modelDelegation, input.harnessRoot, input.projectRoot, targetRoot, skills);
     await writeFile(
       join(targetRoot, ".harness-version"),
       `${JSON.stringify({ version: input.phasegateVersion, deployedAt: new Date().toISOString(), skillSet }, null, 2)}\n`,
@@ -579,6 +583,7 @@ export class RunReconcileUseCase {
     const missingManifest = manifest.findEntry(`${relativePath}/.harness-version`) === null
       || skills.some((skill) => manifest.findEntry(`${relativePath}/${skill}`) === null);
     const renderedSkillDrift = await hasRenderedSkillDrift(
+      this.modelDelegation,
       input.harnessRoot,
       input.projectRoot,
       this.resolveProjectPath(input.projectRoot, relativePath),
@@ -600,7 +605,7 @@ export class RunReconcileUseCase {
       apply: async () => {
         if (!changed) return null;
         const targetRoot = this.resolveProjectPath(input.projectRoot, relativePath);
-        await copySelectedSkillDirectories(input.harnessRoot, input.projectRoot, targetRoot, skills);
+        await copySelectedSkillDirectories(this.modelDelegation, input.harnessRoot, input.projectRoot, targetRoot, skills);
         await writeFile(
           join(targetRoot, ".harness-version"),
           `${JSON.stringify({ version: input.phasegateVersion, deployedAt: new Date().toISOString(), skillSet }, null, 2)}\n`,

package/scripts/harness/installation/composition-root.ts

@@ -26,6 +26,7 @@ import type { UninstallReverseStrategy } from "./domain/ports/uninstall-reverse-
 import { FileSystemManifestRepositoryAdapter } from "./infrastructure/adapters/file-system-manifest-repository-adapter.js";
 import { NodeCryptoHashAdapter } from "./infrastructure/adapters/node-crypto-hash-adapter.js";
 import { NodeFsFileInspectorAdapter } from "./infrastructure/adapters/node-fs-file-inspector-adapter.js";
+import { SkillDeployerModelDelegationAdapter } from "./infrastructure/adapters/skill-deployer-model-delegation-adapter.js";
 import { DoctorHandler } from "./presentation/cli/doctor-handler.js";
 import { InstallHandler } from "./presentation/cli/install-handler.js";
 import { ReconcileHandler } from "./presentation/cli/reconcile-handler.js";
@@ -43,6 +44,7 @@ export function createInstallationModule() {
   const inspector = new NodeFsFileInspectorAdapter();
   const manifestRepository = new FileSystemManifestRepositoryAdapter();
   const hashCalculator = new NodeCryptoHashAdapter();
+  const modelDelegation = new SkillDeployerModelDelegationAdapter();
   const checks = [
     new ClaudeHookMissingCheck(),
     new ClaudeContextMissingCheck(),
@@ -58,8 +60,8 @@ export function createInstallationModule() {
     new WiWorkflowDriftCheck(),
   ];
   const runDoctorDiagnosticsUseCase = new RunDoctorDiagnosticsUseCase(checks, inspector, manifestRepository);
-  const runInstallUseCase = new RunInstallUseCase(manifestRepository, hashCalculator);
-  const runReconcileUseCase = new RunReconcileUseCase(manifestRepository, hashCalculator);
+  const runInstallUseCase = new RunInstallUseCase(manifestRepository, hashCalculator, modelDelegation);
+  const runReconcileUseCase = new RunReconcileUseCase(manifestRepository, hashCalculator, modelDelegation);
   const runUninstallUseCase = new RunUninstallUseCase(manifestRepository, hashCalculator);
   return {
     manifestRepository,

package/scripts/harness/installation/infrastructure/adapters/skill-deployer-model-delegation-adapter.ts

@@ -0,0 +1,16 @@
+// @unit installation
+// @layer infrastructure
+// @work-item-id WI-219
+
+import { readModelDelegationPolicy, renderSkillForModelDelegation } from "../../../setup/skill-deployer.js";
+import type { ModelDelegationPolicy, ModelDelegationPort } from "../../application/ports/model-delegation-port.js";
+
+export class SkillDeployerModelDelegationAdapter implements ModelDelegationPort {
+  readPolicy(projectRoot: string): Promise<ModelDelegationPolicy> {
+    return readModelDelegationPolicy(projectRoot);
+  }
+
+  renderSkill(content: string, policy: ModelDelegationPolicy): string {
+    return renderSkillForModelDelegation(content, policy);
+  }
+}

package/scripts/harness/installation/presentation/cli/install-handler.ts

@@ -44,7 +44,8 @@ export class InstallHandler {
       input.apply ? `phasegate install${input.personal ? " --personal" : ""} apply` : `phasegate install${input.personal ? " --personal" : ""} dry-run`,
       ...result.plan.map((item) => {
         const hint = item.skillHint ? `; hint: ${item.skillHint}` : "";
-        return `- ${item.path}: ${item.action} (${item.repairMode}, ${item.strategy}); diff: ${item.diff}${hint}`;
+        const warn = item.warning ? `\n  WARNING: ${item.warning}` : "";
+        return `- ${item.path}: ${item.action} (${item.repairMode}, ${item.strategy}); diff: ${item.diff}${hint}${warn}`;
       }),
     ];
     if (result.backupDir !== null) lines.push(`backups: ${result.backupDir}`);

package/scripts/harness/main.ts

@@ -38,6 +38,7 @@ import {
   writeFile as fsWriteFile,
 } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 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";
@@ -335,21 +336,42 @@ async function listFilesRecursive(root: string): Promise<string[]> {
   }
 }
 
-async function nextWorkItemId(rootDir: string, inceptionRoot = "docs/inception"): Promise<string> {
-  const files = await listFilesRecursive(join(rootDir, inceptionRoot));
+// Normalize path separators so scanning works on Windows (`\`) as well as POSIX.
+export function toPosixPath(filePath: string): string {
+  return filePath.replace(/\\/g, "/");
+}
+
+// Derive the next WI id from an already-collected list of file paths. Exposed
+// (with the file list injected) so the numbering rules — Windows separator
+// handling and dynamic zero-pad width past WI-999 — can be unit tested without
+// touching the filesystem.
+export function computeNextWorkItemId(files: readonly string[]): string {
   let max = 0;
+  let maxWidth = 3;
   for (const file of files) {
-    const match = file.match(/\/WI-(\d{3})\/description\.md$/);
-    if (match) max = Math.max(max, Number(match[1]));
+    const match = toPosixPath(file).match(/\/WI-(\d+)\/description\.md$/);
+    if (match) {
+      max = Math.max(max, Number(match[1]));
+      maxWidth = Math.max(maxWidth, match[1].length);
+    }
   }
-  return `WI-${String(max + 1).padStart(3, "0")}`;
+  const next = max + 1;
+  return `WI-${String(next).padStart(maxWidth, "0")}`;
+}
+
+async function nextWorkItemId(rootDir: string, inceptionRoot = "docs/inception"): Promise<string> {
+  const files = await listFilesRecursive(join(rootDir, inceptionRoot));
+  return computeNextWorkItemId(files);
 }
 
 async function countLegacyPlansWithoutWorkItems(rootDir: string): Promise<number> {
   const files = await listFilesRecursive(join(rootDir, "docs", "inception"));
-  const hasWorkItem = files.some((file) => /\/WI-\d{3}\/description\.md$/.test(file));
+  const hasWorkItem = files.some((file) => /\/WI-\d+\/description\.md$/.test(toPosixPath(file)));
   if (hasWorkItem) return 0;
-  return files.filter((file) => file.includes("/codding_plan/") || file.endsWith("_plan.md")).length;
+  return files.filter((file) => {
+    const posix = toPosixPath(file);
+    return posix.includes("/codding_plan/") || posix.endsWith("_plan.md");
+  }).length;
 }
 
 async function scaffoldInceptionRoots(rootDir: string, unit: string | null = null, inceptionRoot = "docs/inception"): Promise<void> {
@@ -1378,11 +1400,11 @@ function buildConfigPatchPreview(intent: ConfigChangeIntent, before: unknown | n
   const configIntents: Record<ConfigChangeIntent, readonly { readonly pointer: string; readonly path: readonly string[]; readonly value: unknown }[]> = {
     "l4-strict": [
       { pointer: "/layers/L4/enabled", path: ["layers", "L4", "enabled"], value: true },
-      { pointer: "/layers/L4/failOnWarning", path: ["layers", "L4", "failOnWarning"], value: true },
+      { pointer: "/validate/failOnWarning", path: ["validate", "failOnWarning"], value: true },
     ],
     "ci-fail-on-warning": [
       { pointer: "/ci/enabled", path: ["ci", "enabled"], value: true },
-      { pointer: "/layers/L4/failOnWarning", path: ["layers", "L4", "failOnWarning"], value: true },
+      { pointer: "/validate/failOnWarning", path: ["validate", "failOnWarning"], value: true },
     ],
     "quick-mode-strict": [
       { pointer: "/quickMode/allowedCategories", path: ["quickMode", "allowedCategories"], value: ["bugfix"] },
@@ -1483,7 +1505,7 @@ async function buildConfigChangePlan(rootDir: string, intent: ConfigChangeIntent
     readonly risks: readonly string[];
   }> = {
     "l4-strict": {
-      targets: ["phasegate.config.json: layers.L4.enabled", "phasegate.config.json: layers.L4.failOnWarning"],
+      targets: ["phasegate.config.json: layers.L4.enabled", "phasegate.config.json: validate.failOnWarning"],
       managedTargets: ["phasegate.config.json"],
       externalActions: [],
       commands: ["phasegate config:plan --intent l4-strict --apply --json", "phasegate validate --layer L4 --fail-on-warning --format human"],
@@ -2766,9 +2788,28 @@ async function main(): Promise<void> {
       }
 
       case "phasegate:generate-matrix": {
+        // REAL registry: 有効 storyId 一覧を traceability-model の StoryCatalog から取得する。
+        // 空スタブだと生成マトリクスの storyId 整合性検査が事実上 no-op になるため配線する。
+        // config・catalog が読めない環境（config 不在など）では空配列にフォールバックし、
+        // マトリクス生成自体は継続する。
+        const loadCatalogStoryIds = async (): Promise<readonly string[]> => {
+          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(process.cwd(), {
+              pathRoots: { designDocsRoot: resolvedConfig.config.paths.designDocs },
+            });
+            const catalogStoryIds = await traceModule.storyCatalog.getAllStoryIds();
+            return catalogStoryIds.map((s) => s.value);
+          } catch {
+            return [];
+          }
+        };
         const { createNyquistValidationModule } = await import("./nyquist-validation/composition-root.js");
         const mod = createNyquistValidationModule({
-          getStoryIds: async () => [],
+          getStoryIds: loadCatalogStoryIds,
         });
         const flags: Record<string, boolean | string> = {};
         if (json) flags.json = true;
@@ -3250,4 +3291,19 @@ Examples:
   }
 }
 
-main();
+// Only run the CLI when this module is the process entry point. Guarding this
+// keeps `main()` from executing (and calling process.exit) when the module is
+// imported for unit testing of exported helpers such as computeNextWorkItemId.
+function isMainModule(): boolean {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return resolve(entry) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main();
+}

package/scripts/harness/nyquist-validation/application/dto/generate-matrix-output.ts

@@ -3,6 +3,13 @@
 // @work-item-id WI-125
 // @work-item-id WI-131
 
+// Intent coverage 系の型は domain 層（value-objects/intent-coverage）を正準とし、
+// application 層はそれを参照・再エクスポートする（domain ← application の正しい依存方向）。
+import type {
+  IntentCoverageStatus as DomainIntentCoverageStatus,
+  IntentCoverageItem as DomainIntentCoverageItem,
+} from '../../domain/value-objects/intent-coverage.js';
+
 export interface RequirementSourceDto {
   readonly storyId: string;
   readonly acIds: readonly string[];
@@ -48,14 +55,9 @@ export interface OrphanTestDto {
   readonly testName?: string;
 }
 
-export type IntentCoverageStatus = 'observed' | 'weakly-observed' | 'unobserved';
+export type IntentCoverageStatus = DomainIntentCoverageStatus;
 
-export interface IntentCoverageItemDto {
-  readonly storyId: string;
-  readonly acId: string;
-  readonly status: IntentCoverageStatus;
-  readonly warnings: readonly string[];
-}
+export type IntentCoverageItemDto = DomainIntentCoverageItem;
 
 export interface MatrixGenerationReportDto {
   readonly missingTests: readonly MissingTestDto[];

package/scripts/harness/nyquist-validation/domain/services/matrix-validation-service.ts

@@ -23,11 +23,25 @@ interface RawStoryMappingEntry {
   storyId: string;
 }
 
+/**
+ * requirement-test-matrix.json から storyId を持つエントリを抽出する。
+ *
+ * スキーマ準拠の実データはトップレベルキー `stories`（各要素が `{ storyId, storyMappings }`）
+ * を用いる。旧来のテスト・入力ではトップレベル `storyMappings` を用いる場合があるため
+ * 両形式に対応する。以前は `storyMappings` のみを参照していたため、スキーマ準拠の実データ
+ * （`stories` 形式）に対しては常に空配列を返し、storyId 整合性検査が事実上 no-op だった。
+ */
 function extractStoryMappings(rawData: unknown): RawStoryMappingEntry[] {
   if (rawData === null || typeof rawData !== 'object') return [];
   const obj = rawData as Record<string, unknown>;
-  if (!Array.isArray(obj['storyMappings'])) return [];
-  return (obj['storyMappings'] as unknown[]).map((item) => {
+
+  const source = Array.isArray(obj['stories'])
+    ? (obj['stories'] as unknown[])
+    : Array.isArray(obj['storyMappings'])
+      ? (obj['storyMappings'] as unknown[])
+      : [];
+
+  return source.map((item) => {
     const entry = item as Record<string, unknown>;
     return { storyId: String(entry['storyId'] ?? '') };
   });
@@ -53,7 +67,9 @@ export class MatrixValidationService {
     const storyMappings = extractStoryMappings(rawData);
 
     const errors: NyquistHarnessError[] = [];
+    const seenStoryIds = new Set<string>();
     for (const sm of storyMappings) {
+      // storyId 整合性: 有効 storyId 一覧に含まれるか照合する
       if (!validStoryIds.includes(sm.storyId)) {
         errors.push({
           code: 'L3-004',
@@ -61,6 +77,15 @@ export class MatrixValidationService {
           message: `未登録のstoryIdです: ${sm.storyId}`,
         });
       }
+      // INV-1: 同一 storyId の StoryMapping は1つのみ存在する（重複を検出）
+      if (seenStoryIds.has(sm.storyId)) {
+        errors.push({
+          code: 'L3-004',
+          severity: 'error',
+          message: `storyIdが重複しています: ${sm.storyId}`,
+        });
+      }
+      seenStoryIds.add(sm.storyId);
     }
 
     if (errors.length === 0) {

package/scripts/harness/nyquist-validation/domain/services/requirement-intent-coverage-service.ts

@@ -3,12 +3,12 @@
 // @work-item-id WI-131
 
 import type {
-  IntentCoverageItemDto,
-  MatrixStoryDto,
-} from '../../application/dto/generate-matrix-output.js';
+  IntentCoverageItem,
+  IntentCoverageStory,
+} from '../value-objects/intent-coverage.js';
 
 export class RequirementIntentCoverageService {
-  evaluate(stories: readonly MatrixStoryDto[]): readonly IntentCoverageItemDto[] {
+  evaluate(stories: readonly IntentCoverageStory[]): readonly IntentCoverageItem[] {
     return stories.flatMap((story) => story.storyMappings.map((mapping) => {
       if (mapping.testReferences.length === 0) {
         return {

package/scripts/harness/nyquist-validation/domain/value-objects/intent-coverage.ts

@@ -0,0 +1,33 @@
+// @layer domain
+// @unit nyquist-validation
+// @work-item-id WI-131
+//
+// RequirementIntentCoverageService が入出力に用いるドメイン層の型定義。
+// 依存方向是正: これまで domain 層のサービスが application/dto から型を import しており
+// domain → application の逆流（レイヤー依存違反）が発生していた。型の正準を domain 層へ
+// 移し、application 層の DTO はここを参照する（domain ← application の正しい向き）。
+
+export interface IntentCoverageTestReference {
+  readonly filePath: string;
+  readonly testType: 'unit' | 'it' | 'scenario';
+  readonly testName?: string;
+}
+
+export interface IntentCoverageAcMapping {
+  readonly acId: string;
+  readonly testReferences: readonly IntentCoverageTestReference[];
+}
+
+export interface IntentCoverageStory {
+  readonly storyId: string;
+  readonly storyMappings: readonly IntentCoverageAcMapping[];
+}
+
+export type IntentCoverageStatus = 'observed' | 'weakly-observed' | 'unobserved';
+
+export interface IntentCoverageItem {
+  readonly storyId: string;
+  readonly acId: string;
+  readonly status: IntentCoverageStatus;
+  readonly warnings: readonly string[];
+}

package/scripts/harness/nyquist-validation/infrastructure/adapters/markdown-requirement-source-adapter.ts

@@ -6,7 +6,9 @@ import { readFile } from 'node:fs/promises';
 import type { RequirementSourcePort } from '../../application/usecases/generate-requirement-test-matrix-usecase.js';
 import type { RequirementSourceDto } from '../../application/dto/generate-matrix-output.js';
 
-const STORY_HEADING = /^###\s+(H\d{2}-\d{2}):/;
+// StoryId は HXX-XX 形式に加え Phase 2 拡張 Epic の HF\d+-XX 形式も許容する
+// （traceability-model の StoryId 正規表現と整合）。旧 /H\d{2}-\d{2}/ は HF2-01 を取りこぼしていた。
+const STORY_HEADING = /^###\s+(H(?:F\d+|\d{2})-\d{2}):/;
 const AC_ITEM = /^\s*-\s+\[[ xX]\]\s+(AC-[1-9][0-9]*):/;
 
 export class MarkdownRequirementSourceAdapter implements RequirementSourcePort {

package/scripts/harness/nyquist-validation/infrastructure/adapters/type-script-test-reference-source-adapter.ts

@@ -7,7 +7,10 @@ import path from 'node:path';
 import type { TestReferenceSourcePort } from '../../application/usecases/generate-requirement-test-matrix-usecase.js';
 import type { TestReferenceSourceDto } from '../../application/dto/generate-matrix-output.js';
 
-const STORY_TAG = /@story(?:-id)?\s+(H\d{2}-\d{2})/;
+// StoryId は HXX-XX 形式に加え Phase 2 拡張 Epic の HF\d+-XX 形式も許容する
+// （markdown-requirement-source-adapter の STORY_HEADING / traceability-model の StoryId 正規表現と整合）。
+// 旧 /H\d{2}-\d{2}/ は HF2-01 等を取りこぼし、正しく注釈されたテストが「テストなし」と誤判定されていた。
+const STORY_TAG = /@story(?:-id)?\s+(H(?:F\d+|\d{2})-\d{2})/;
 const TEST_NAME = /\b(?:it|test)(?:\.each\([^)]*\))?\s*\(\s*['"`]([^'"`]+)['"`]/g;
 
 async function collectTestFiles(root: string): Promise<readonly string[]> {