phasegate 0.160.19 → 0.160.21

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

@@ -4,14 +4,15 @@
 // @work-item-id WI-174
 // @work-item-id WI-198
 // @work-item-id WI-210
+// @work-item-id WI-216
 
 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 { getSkillsForSet, type SkillSet } 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";
 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";
 
@@ -95,8 +96,18 @@ async function copyDirectory(src: string, dest: string): Promise<void> {
   }
 }
 
+async function copySelectedSkillDirectories(harnessRoot: string, targetRoot: string, skills: readonly string[]): Promise<void> {
+  await mkdir(targetRoot, { recursive: true });
+  for (const skill of skills) {
+    const source = join(harnessRoot, "skills", skill);
+    const target = join(targetRoot, skill);
+    await rm(target, { recursive: true, force: true });
+    await copyDirectory(source, target);
+  }
+}
+
 async function listSelectedBundledSkills(harnessRoot: string, skillSet: SkillSet): Promise<string[]> {
-  const allowed = new Set(getSkillsForSet(skillSet));
+  const allowed = new Set(getBundledSkillsForSet(skillSet));
   const entries = await readdir(join(harnessRoot, "skills"), { withFileTypes: true });
   return entries
     .filter((entry) => entry.isDirectory() && allowed.has(entry.name))
@@ -285,12 +296,21 @@ export class RunReconcileUseCase {
       }
     }
 
-    if (this.manifestIntendsSharedSkills(manifest)) {
+    const personalInstall = this.isPersonalManifest(manifest);
+    if (!personalInstall && this.manifestIntendsSharedSkills(manifest)) {
       const sharedSkills = await listSelectedBundledSkills(input.harnessRoot, "all");
       const outcome = await this.planSharedSkills(input, manifest, sharedSkills, "all");
       outcomes.push(outcome);
       plan.push(outcome.item);
     }
+    if (personalInstall) {
+      const personalSkills = await listSelectedBundledSkills(input.harnessRoot, "all");
+      for (const skillPath of this.personalSkillPaths(manifest)) {
+        const outcome = await this.planPersonalSkills(input, manifest, skillPath, personalSkills, "all");
+        outcomes.push(outcome);
+        plan.push(outcome.item);
+      }
+    }
 
     if (!input.apply || refused.length > 0) {
       return { plan, refused, changed, backupDir: null };
@@ -311,6 +331,12 @@ export class RunReconcileUseCase {
           for (const skill of sharedSkills) {
             nextManifest = nextManifest.addEntry(this.createdEntry(`skills/${skill}`, this.sharedSkillHashInput(skill, input.phasegateVersion, "all")));
           }
+        } else if (outcome.item.strategy === "copy-dir" && (outcome.item.path === ".claude/skills" || outcome.item.path === ".codex/skills")) {
+          const personalSkills = await listSelectedBundledSkills(input.harnessRoot, "all");
+          nextManifest = nextManifest.addEntry(this.createdEntry(`${outcome.item.path}/.harness-version`, this.personalSkillsVersionHashInput(outcome.item.path, input.phasegateVersion, "all", personalSkills)));
+          for (const skill of personalSkills) {
+            nextManifest = nextManifest.addEntry(this.createdEntry(`${outcome.item.path}/${skill}`, this.personalSkillHashInput(outcome.item.path, skill, input.phasegateVersion, "all")));
+          }
         } else {
           const mode = outcome.item.strategy === "symlink" ? "symlink" : outcome.item.action === "add" ? "created" : (manifest.findEntry(outcome.item.path)?.mode ?? "merged");
           nextManifest = nextManifest.addEntry(
@@ -435,6 +461,19 @@ export class RunReconcileUseCase {
       || manifest.entries.some((entry) => entry.path.startsWith("skills/"));
   }
 
+  private isPersonalManifest(manifest: DeploymentManifest): boolean {
+    return manifest.findEntry(".phasegate-local/phasegate.config.json") !== null
+      || manifest.entries.some((entry) => (entry.path === ".claude/skills" || entry.path === ".codex/skills") && entry.mode === "created")
+      || manifest.entries.some((entry) => entry.path.startsWith(".claude/skills/") || entry.path.startsWith(".codex/skills/"));
+  }
+
+  private personalSkillPaths(manifest: DeploymentManifest): Array<".claude/skills" | ".codex/skills"> {
+    const paths = new Set<".claude/skills" | ".codex/skills">();
+    if (manifest.findEntry(".claude/skills") !== null || manifest.entries.some((entry) => entry.path.startsWith(".claude/skills/"))) paths.add(".claude/skills");
+    if (manifest.findEntry(".codex/skills") !== null || manifest.entries.some((entry) => entry.path.startsWith(".codex/skills/"))) paths.add(".codex/skills");
+    return [...paths].sort();
+  }
+
   private async planSharedSkills(
     input: RunReconcileInput,
     manifest: DeploymentManifest,
@@ -475,13 +514,7 @@ export class RunReconcileUseCase {
 
   private async deploySharedSkills(input: RunReconcileInput, skills: readonly string[], skillSet: SkillSet): Promise<void> {
     const targetRoot = this.resolveProjectPath(input.projectRoot, "skills");
-    await mkdir(targetRoot, { recursive: true });
-    for (const skill of skills) {
-      const source = join(input.harnessRoot, "skills", skill);
-      const target = join(targetRoot, skill);
-      await rm(target, { recursive: true, force: true });
-      await copyDirectory(source, target);
-    }
+    await copySelectedSkillDirectories(input.harnessRoot, targetRoot, skills);
     await writeFile(
       join(targetRoot, ".harness-version"),
       `${JSON.stringify({ version: input.phasegateVersion, deployedAt: new Date().toISOString(), skillSet }, null, 2)}\n`,
@@ -489,6 +522,52 @@ export class RunReconcileUseCase {
     );
   }
 
+  private async planPersonalSkills(
+    input: RunReconcileInput,
+    manifest: DeploymentManifest,
+    relativePath: ".claude/skills" | ".codex/skills",
+    skills: readonly string[],
+    skillSet: SkillSet,
+  ) {
+    const versionPath = this.resolveProjectPath(input.projectRoot, `${relativePath}/.harness-version`);
+    const versionContent = await readTextOrNull(versionPath);
+    const expectedVersion = `"version": "${input.phasegateVersion}"`;
+    let missingSkill = false;
+    for (const skill of skills) {
+      if (!(await exists(this.resolveProjectPath(input.projectRoot, `${relativePath}/${skill}/SKILL.md`)))) {
+        missingSkill = true;
+        break;
+      }
+    }
+    const missingManifest = manifest.findEntry(`${relativePath}/.harness-version`) === null
+      || skills.some((skill) => manifest.findEntry(`${relativePath}/${skill}`) === null);
+    const changed = versionContent === null || !versionContent.includes(expectedVersion) || missingSkill || missingManifest;
+    return {
+      item: this.item(
+        relativePath,
+        changed ? "add" : "skip",
+        "mechanical",
+        "copy-dir",
+        changed,
+        changed ? `${relativePath}: deploy bundled skills` : `${relativePath}: already up to date`,
+        changed ? `+ ${skills.length} bundled skills (${skillSet})` : "no changes",
+        null,
+      ),
+      needsBackup: false,
+      apply: async () => {
+        if (!changed) return null;
+        const targetRoot = this.resolveProjectPath(input.projectRoot, relativePath);
+        await copySelectedSkillDirectories(input.harnessRoot, targetRoot, skills);
+        await writeFile(
+          join(targetRoot, ".harness-version"),
+          `${JSON.stringify({ version: input.phasegateVersion, deployedAt: new Date().toISOString(), skillSet }, null, 2)}\n`,
+          "utf8",
+        );
+        return this.personalSkillsVersionHashInput(relativePath, input.phasegateVersion, skillSet, skills);
+      },
+    };
+  }
+
   private createdEntry(path: string, hashInput: string): DeploymentEntry {
     return DeploymentEntry.create({
       path,
@@ -507,6 +586,14 @@ export class RunReconcileUseCase {
     return `shared-skill:${skill}:${version}:${skillSet}`;
   }
 
+  private personalSkillsVersionHashInput(path: string, version: string, skillSet: SkillSet, skills: readonly string[]): string {
+    return `personal-skills-version:${path}:${version}:${skillSet}:${skills.join(",")}`;
+  }
+
+  private personalSkillHashInput(path: string, skill: string, version: string, skillSet: SkillSet): string {
+    return `personal-skill:${path}:${skill}:${version}:${skillSet}`;
+  }
+
   private reconcileContent(target: ReconcileTarget, before: string | null, template: string, version: string): string {
     if (target.strategy === "yaml-add") return template;
     if (target.strategy === "shell") return reconcileShell(before, template);

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

@@ -6,8 +6,9 @@
 // @work-item-id WI-207
 // @work-item-id WI-208
 // @work-item-id WI-209
+// @work-item-id WI-216
 
-import { access, copyFile, lstat, mkdir, readFile, readlink, rm, rmdir, writeFile } from "node:fs/promises";
+import { access, copyFile, lstat, mkdir, readFile, readdir, readlink, rm, rmdir, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
 import type { DeploymentEntry } from "../../domain/deployment-entry.js";
 import type { RepairMode } from "../../domain/repair-mode.js";
@@ -222,7 +223,7 @@ export class RunUninstallUseCase {
     const strategy = this.strategyFor(entry.path, entry.mode);
     if (entry.mode === "symlink") return this.planSymlink(input.projectRoot, entry);
     if (entry.mode === "created" && await this.isDirectory(absolutePath)) {
-      return this.planCreatedDirectory(input.projectRoot, entry);
+      return this.planCreatedDirectory(input, entry);
     }
     const currentContent = await readTextOrNull(absolutePath);
     if (currentContent === null && strategy !== "symlink") {
@@ -271,8 +272,9 @@ export class RunUninstallUseCase {
     }
   }
 
-  private async planCreatedDirectory(projectRoot: string, entry: DeploymentEntry) {
-    const absolutePath = this.resolveProjectPath(projectRoot, entry.path);
+  private async planCreatedDirectory(input: RunUninstallInput, entry: DeploymentEntry) {
+    if (entry.path === ".claude/skills" || entry.path === ".codex/skills") return this.planLegacyPersonalSkillsDirectory(input, entry);
+    const absolutePath = this.resolveProjectPath(input.projectRoot, entry.path);
     return {
       item: this.item(
         entry.path,
@@ -291,10 +293,39 @@ export class RunUninstallUseCase {
     };
   }
 
+  private async planLegacyPersonalSkillsDirectory(input: RunUninstallInput, entry: DeploymentEntry) {
+    const absolutePath = this.resolveProjectPath(input.projectRoot, entry.path);
+    const bundledSkills = await this.listBundledSkills(input.harnessRoot);
+    return {
+      item: this.item(
+        entry.path,
+        "delete",
+        "mechanical",
+        "created",
+        true,
+        `${entry.path}: remove managed bundled skills from legacy personal catalog`,
+        `- ${bundledSkills.length} bundled skills and .harness-version`,
+        null,
+      ),
+      needsBackup: false,
+      apply: async () => {
+        for (const skill of bundledSkills) {
+          await rm(join(absolutePath, skill), { recursive: true, force: true });
+        }
+        await rm(join(absolutePath, ".harness-version"), { force: true });
+      },
+    };
+  }
+
+  private async listBundledSkills(harnessRoot: string): Promise<string[]> {
+    const entries = await readdir(join(harnessRoot, "skills"), { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  }
+
   private async planCreated(projectRoot: string, entry: DeploymentEntry, currentContent: string) {
     const absolutePath = this.resolveProjectPath(projectRoot, entry.path);
     const currentHash = this.hashCalculator.compute(currentContent);
-    const matchesManifest = currentHash.equals(entry.hash);
+    const matchesManifest = currentHash.equals(entry.hash) || entry.path.endsWith("/.harness-version") || entry.path === "skills/.harness-version";
     const repairMode: RepairMode = matchesManifest ? "mechanical" : "ai-assisted";
     return {
       item: this.item(

package/scripts/harness/main.ts

@@ -18,6 +18,7 @@
  * @work-item-id WI-205
  * @work-item-id WI-206
  * @work-item-id WI-213
+ * @work-item-id WI-217
  *
  * Phasegate CLI エントリポイント。
  * 各Unitの Composition Root からハンドラーを取得し、コマンドに応じてディスパッチする。
@@ -169,7 +170,7 @@ Setup:
                                 --with-husky, --with-ci, --yes)
   update-skills                Alias for reconcile (kept for compatibility)
   doctor                       Diagnose silent installation failures (--json, --strict, --personal, --agent <claude|codex|both>, --report-out <path>)
-  scaffold-wi <unit|_cross> <story|issue|chore>
+  scaffold-wi <unit|_cross> <story|issue|fix|refactor|chore>
                                Create docs/inception/{unit}/WI-XXX/description.md
   emit-agent-rules             Print AGENTS.md / CLAUDE.md WI workflow rules block
   install                      Install phasegate managed files (--dry-run|--apply, --force, --personal, --agent <claude|codex|both>)
@@ -280,14 +281,14 @@ function hasFlag(args: readonly string[], flag: string): boolean {
 }
 
 type WorkflowMode = "standard" | "strict";
-type ScaffoldWorkItemType = "story" | "issue" | "chore";
+type ScaffoldWorkItemType = "story" | "issue" | "fix" | "refactor" | "chore";
 
 function parseWorkflowMode(value: string | undefined): WorkflowMode {
   return value === "strict" ? "strict" : "standard";
 }
 
 function parseScaffoldWorkItemType(value: string | undefined): ScaffoldWorkItemType | null {
-  if (value === "story" || value === "issue" || value === "chore") return value;
+  if (value === "story" || value === "issue" || value === "fix" || value === "refactor" || value === "chore") return value;
   return null;
 }
 
@@ -319,8 +320,8 @@ async function listFilesRecursive(root: string): Promise<string[]> {
   }
 }
 
-async function nextWorkItemId(rootDir: string): Promise<string> {
-  const files = await listFilesRecursive(join(rootDir, "docs", "inception"));
+async function nextWorkItemId(rootDir: string, inceptionRoot = "docs/inception"): Promise<string> {
+  const files = await listFilesRecursive(join(rootDir, inceptionRoot));
   let max = 0;
   for (const file of files) {
     const match = file.match(/\/WI-(\d{3})\/description\.md$/);
@@ -336,19 +337,25 @@ async function countLegacyPlansWithoutWorkItems(rootDir: string): Promise<number
   return files.filter((file) => file.includes("/codding_plan/") || file.endsWith("_plan.md")).length;
 }
 
-async function scaffoldInceptionRoots(rootDir: string, unit: string | null = null): Promise<void> {
-  await fsMkdir(join(rootDir, "docs", "inception", "_shared"), { recursive: true });
-  await fsMkdir(join(rootDir, "docs", "inception", "_cross"), { recursive: true });
+async function scaffoldInceptionRoots(rootDir: string, unit: string | null = null, inceptionRoot = "docs/inception"): Promise<void> {
+  await fsMkdir(join(rootDir, inceptionRoot, "_shared"), { recursive: true });
+  await fsMkdir(join(rootDir, inceptionRoot, "_cross"), { recursive: true });
   if (unit && unit !== "_cross" && unit !== "_shared") {
-    await fsMkdir(join(rootDir, "docs", "inception", unit), { recursive: true });
-    await fsWriteFile(join(rootDir, "docs", "inception", unit, ".gitkeep"), "", "utf8").catch(() => undefined);
+    await fsMkdir(join(rootDir, inceptionRoot, unit), { recursive: true });
+    await fsWriteFile(join(rootDir, inceptionRoot, unit, ".gitkeep"), "", "utf8").catch(() => undefined);
   }
 }
 
-async function scaffoldWorkItem(rootDir: string, unit: string, type: ScaffoldWorkItemType): Promise<string> {
-  const id = await nextWorkItemId(rootDir);
-  await scaffoldInceptionRoots(rootDir, unit);
-  const targetBase = unit === "_cross" ? join(rootDir, "docs", "inception", "_cross") : join(rootDir, "docs", "inception", unit);
+async function scaffoldWorkItem(
+  rootDir: string,
+  unit: string,
+  type: ScaffoldWorkItemType,
+  options: { readonly id?: string; readonly inceptionRoot?: string } = {},
+): Promise<string> {
+  const inceptionRoot = options.inceptionRoot ?? "docs/inception";
+  const id = options.id ?? await nextWorkItemId(rootDir, inceptionRoot);
+  await scaffoldInceptionRoots(rootDir, unit, inceptionRoot);
+  const targetBase = unit === "_cross" ? join(rootDir, inceptionRoot, "_cross") : join(rootDir, inceptionRoot, unit);
   const targetDir = join(targetBase, id);
   await fsMkdir(targetDir, { recursive: true });
   const descriptionPath = join(targetDir, "description.md");
@@ -754,15 +761,18 @@ Options:
 Examples:
   phasegate check-change-category --paths src/foo.ts,src/bar.ts
   phasegate check-change-category --paths src/foo.ts --format json`,
-  "scaffold-wi": `Usage: phasegate scaffold-wi <unit|_cross> <story|issue|chore>
+  "scaffold-wi": `Usage: phasegate scaffold-wi <unit|_cross> <story|issue|fix|refactor|chore> [options]
 
 Create docs/inception/{unit}/WI-XXX/description.md.
 
 Arguments:
   <unit|_cross>              Unit id or _cross for cross-cutting work items.
-  <story|issue|chore>        Work item type.
+  <story|issue|fix|refactor|chore>
+                              Work item type.
 
 Options:
+  --id <work-item-id>        Use the supplied id instead of allocating WI-XXX.
+  --root <path>              Inception root. Defaults to docs/inception, or personal paths.inceptionDocs.
   --help, -h                 Show this help`,
   "scaffold-design": `Usage: phasegate scaffold-design --unit <id> --phase <phase> [options]
 
@@ -2035,13 +2045,25 @@ async function main(): Promise<void> {
       }
 
       case "scaffold-wi": {
+        const KNOWN_SCAFFOLD_WI_FLAGS = ["--id", "--root"];
+        const flagError = validateKnownFlags(args, KNOWN_SCAFFOLD_WI_FLAGS);
+        if (flagError) {
+          console.error(flagError);
+          process.exit(2);
+        }
         const unit = args[1];
         const type = parseScaffoldWorkItemType(args[2]);
         if (!unit || !type) {
-          console.error("Usage: phasegate scaffold-wi <unit|_cross> <story|issue|chore>");
+          console.error("Usage: phasegate scaffold-wi <unit|_cross> <story|issue|fix|refactor|chore> [--id <work-item-id>] [--root <path>]");
           process.exit(2);
         }
-        const descriptionPath = await scaffoldWorkItem(rootDir, unit, type);
+        const configuredPersonalRoot = resolvedConfig?.paths.inceptionDocs?.startsWith(".phasegate-local/")
+          ? resolvedConfig.paths.inceptionDocs
+          : undefined;
+        const descriptionPath = await scaffoldWorkItem(rootDir, unit, type, {
+          id: parseFlag(args, "--id"),
+          inceptionRoot: parseFlag(args, "--root") ?? configuredPersonalRoot,
+        });
         console.log(`Created ${descriptionPath}`);
         process.exit(0);
         break;

package/scripts/harness/validator-system/application/dto/validation-result-contract.ts

@@ -18,4 +18,5 @@ export interface ValidationResultContract {
   }[];
   readonly durationMs: number;
   readonly skipped?: boolean;
+  readonly skipReason?: string;
 }

package/scripts/harness/validator-system/application/mappers/validation-result-contract-mapper.ts

@@ -24,6 +24,7 @@ export class ValidationResultContractMapper {
       }),
       durationMs: result.durationMs,
       skipped: result.skipped,
+      ...(result.skipReason ? { skipReason: result.skipReason } : {}),
     };
   }
 

package/scripts/harness/validator-system/application/use-cases/run-l4-validators-usecase.ts

@@ -2,6 +2,7 @@
  * @layer application
  * @unit validator-system
  * @work-item-id WI-107 / WI-156
+ * @work-item-id WI-217
  *
  * RunL4ValidatorsUseCase — H08-03: L4バリデータ実行
  */
@@ -70,6 +71,10 @@ export interface RunL4ValidatorsUseCaseDeps {
   deadCodeDetectionService?: DeadCodeDetectionService;
   architectureSemanticAnalysisService?: ArchitectureSemanticAnalysisService;
   skillCatalogDriftPort?: SkillCatalogDriftPort;
+  pathRoots?: {
+    readonly inceptionRoot: string;
+    readonly designRoot: string;
+  };
   checkDocFreshnessUseCase?: CheckDocFreshnessUseCasePort;
   validateDocPointersUseCase?: ValidateDocPointersUseCasePort;
 }
@@ -85,6 +90,7 @@ export class RunL4ValidatorsUseCase {
   private readonly architectureSemanticAnalysisService?: ArchitectureSemanticAnalysisService;
   private readonly skillCatalogDriftPort?: SkillCatalogDriftPort;
   private readonly skillCatalogDriftService = new SkillCatalogDriftService();
+  private readonly pathRoots: { readonly inceptionRoot: string; readonly designRoot: string };
   private readonly checkDocFreshnessUseCase?: CheckDocFreshnessUseCasePort;
   private readonly validateDocPointersUseCase?: ValidateDocPointersUseCasePort;
 
@@ -98,6 +104,10 @@ export class RunL4ValidatorsUseCase {
     this.deadCodeDetectionService = deps.deadCodeDetectionService;
     this.architectureSemanticAnalysisService = deps.architectureSemanticAnalysisService;
     this.skillCatalogDriftPort = deps.skillCatalogDriftPort;
+    this.pathRoots = deps.pathRoots ?? {
+      inceptionRoot: 'docs/inception',
+      designRoot: 'docs/product/construction',
+    };
     this.checkDocFreshnessUseCase = deps.checkDocFreshnessUseCase;
     this.validateDocPointersUseCase = deps.validateDocPointersUseCase;
   }
@@ -158,13 +168,25 @@ export class RunL4ValidatorsUseCase {
       const l4002Result = overrideMap.get('L4-002');
       if (l4002Result && !l4002Result.skipped) {
         const report = await this.consistencyCheckService.check(input.targetUnits ? [...input.targetUnits] : undefined);
+        const reflectionResult = this.usesConfiguredDocumentRoots()
+          ? await this.consistencyCheckService.checkWorkItemReflection(this.pathRoots)
+          : undefined;
         const architectureSemanticErrors = this.architectureSemanticAnalysisService
           ? await this.architectureSemanticAnalysisService.analyze()
           : [];
-        if (report.hasMismatches() || architectureSemanticErrors.length > 0) {
+        if (report.hasMismatches() || (reflectionResult?.report.hasMismatches() ?? false) || architectureSemanticErrors.length > 0) {
           overrideMap.set(
             'L4-002',
-            ValidationResult.fail(ValidatorId.create('L4-002'), [...report.toHarnessErrors(), ...architectureSemanticErrors], 0),
+            ValidationResult.fail(
+              ValidatorId.create('L4-002'),
+              [...report.toHarnessErrors(), ...(reflectionResult?.report.toHarnessErrors() ?? []), ...architectureSemanticErrors],
+              0,
+            ),
+          );
+        } else if (reflectionResult?.skipReason && !report.hasMismatches() && architectureSemanticErrors.length === 0) {
+          overrideMap.set(
+            'L4-002',
+            ValidationResult.skipWithReason(ValidatorId.create('L4-002'), reflectionResult.skipReason),
           );
         }
       }
@@ -187,7 +209,10 @@ export class RunL4ValidatorsUseCase {
     if (this.checkDocFreshnessUseCase) {
       const l4004Result = overrideMap.get('L4-004');
       if (l4004Result && !l4004Result.skipped) {
-        const freshnessOutput = await this.checkDocFreshnessUseCase.execute({ format: 'json' });
+        const freshnessOutput = await this.checkDocFreshnessUseCase.execute({
+          format: 'json',
+          targetPattern: `${this.pathRoots.designRoot.replace(/\/+$/g, '')}/**/*.md`,
+        });
         const errors = this.toDocFreshnessHarnessErrors(freshnessOutput);
         overrideMap.set(
           'L4-004',
@@ -251,6 +276,10 @@ export class RunL4ValidatorsUseCase {
     return [...executionErrors, ...freshnessFindings];
   }
 
+  private usesConfiguredDocumentRoots(): boolean {
+    return this.pathRoots.inceptionRoot !== 'docs/inception' || this.pathRoots.designRoot !== 'docs/product/construction';
+  }
+
   private toPointerValidationHarnessErrors(output: ValidateDocPointersOutputContract): readonly ValidationResult['errors'][number][] {
     const executionErrors = output.errors.map((error) => this.toHarnessErrorLike(
       'L4-005',

package/scripts/harness/validator-system/composition-root.ts

@@ -4,6 +4,7 @@
  *
  * DI 組み立て — validator-system の全依存関係を構築する
  * @work-item-id WI-110 / WI-111 / WI-132 / WI-133 / WI-136 / WI-137 / WI-138 / WI-156
+ * @work-item-id WI-217
  */
 import { ValidatorId } from './domain/value-objects/validator-id.js';
 import { ValidatorDefinition } from './domain/value-objects/validator-definition.js';
@@ -37,6 +38,7 @@ import { AdrFoundationReferenceAdapter } from './infrastructure/adapters/adr-fou
 import { ImportGraphSourceAnalysisAdapter } from './infrastructure/adapters/import-graph-source-analysis-adapter.js';
 import { FileSystemArchitectureSemanticSourceAdapter } from './infrastructure/adapters/file-system-architecture-semantic-source-adapter.js';
 import { FileSystemSkillCatalogDriftAdapter } from './infrastructure/adapters/file-system-skill-catalog-drift-adapter.js';
+import { FileSystemWorkItemReflectionAdapter } from './infrastructure/adapters/file-system-work-item-reflection-adapter.js';
 import { DriftDetectionService } from './domain/services/l4/drift-detection-service.js';
 import { ConsistencyCheckService } from './domain/services/l4/consistency-check-service.js';
 import { DeadCodeDetectionService } from './domain/services/l4/dead-code-detection-service.js';
@@ -55,6 +57,10 @@ const DEFAULT_CONFIG = {
     L3: { enabled: true, validators: ['L3-001', 'L3-002', 'L3-003', 'L3-004'], coverageThreshold: 90, bundleSizeLimit: 512000 },
     L4: { enabled: true, validators: ['L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005', 'L4-006'] },
   },
+  paths: {
+    designDocs: 'docs/product/construction',
+    inceptionDocs: 'docs/inception',
+  },
   validate: { failOnWarning: false },
   architecture: {
     capabilityPolicies: {
@@ -149,8 +155,10 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
   const workItemStatusPolicyPort = new TraceabilityWorkItemStatusPolicyAdapter(process.cwd());
   const contractTraceabilityPolicyPort = new FileSystemContractTraceabilityPolicyAdapter();
 
-  const docsRoot = join(process.cwd(), 'docs/product/construction');
   const cwd = process.cwd();
+  const designDocsRoot = configData.paths?.designDocs ?? 'docs/product/construction';
+  const inceptionDocsRoot = configData.paths?.inceptionDocs ?? 'docs/inception';
+  const docsRoot = join(cwd, designDocsRoot);
   const e2eTestFileRegistryPort = new E2eTestFileRegistryAdapter({ e2eTestRoot: join(cwd, 'scripts/harness/__tests__/e2e') });
   const cliCommandRegistryPort = new CliCommandRegistryAdapter({
     commands: [
@@ -191,6 +199,7 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
   const sourceAnalysisPort = new ImportGraphSourceAnalysisAdapter();
   const architectureSemanticSourcePort = new FileSystemArchitectureSemanticSourceAdapter();
   const skillCatalogDriftPort = new FileSystemSkillCatalogDriftAdapter(cwd);
+  const workItemReflectionPort = new FileSystemWorkItemReflectionAdapter(cwd);
 
   const driftDetectionService = new DriftDetectionService({
     designDocumentPort: markdownDesignDocumentPort,
@@ -199,6 +208,7 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
   const consistencyCheckService = new ConsistencyCheckService({
     designDocumentPort: markdownDesignDocumentPort,
     adrReferencePort,
+    workItemReflectionPort,
   });
   const deadCodeDetectionService = new DeadCodeDetectionService({
     sourceAnalysisPort,
@@ -219,6 +229,10 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
     deadCodeDetectionService,
     architectureSemanticAnalysisService,
     skillCatalogDriftPort,
+    pathRoots: {
+      inceptionRoot: inceptionDocsRoot,
+      designRoot: designDocsRoot,
+    },
     checkDocFreshnessUseCase: phase2Extensions.checkDocFreshnessUseCase,
     validateDocPointersUseCase: phase2Extensions.validateDocPointersUseCase,
   });

package/scripts/harness/validator-system/domain/services/l4/consistency-check-service.ts

@@ -7,6 +7,7 @@
  * 設計文書間のレイヤー整合性検証（L4-002）
  */
 import { ConsistencyReport } from '../../value-objects/consistency-report.js';
+import type { MismatchPair } from '../../value-objects/consistency-report.js';
 
 export interface ConsistencyDesignDocumentPort {
   getLayerAnnotations(targetDocs?: readonly string[]): Promise<Record<string, string>>;
@@ -16,24 +17,47 @@ export interface ConsistencyAdrReferencePort {
   exists(adrRef: string): Promise<boolean>;
 }
 
+export interface WorkItemReflectionSnapshot {
+  readonly workItems: readonly {
+    readonly id: string;
+    readonly path: string;
+    readonly type?: string;
+  }[];
+  readonly productRefs: readonly {
+    readonly id: string;
+    readonly path: string;
+  }[];
+  readonly skipReason?: string;
+}
+
+export interface WorkItemReflectionPort {
+  collect(input: {
+    readonly inceptionRoot: string;
+    readonly designRoot: string;
+  }): Promise<WorkItemReflectionSnapshot>;
+}
+
 export interface ConsistencyCheckServiceDeps {
   designDocumentPort: ConsistencyDesignDocumentPort;
   adrReferencePort: ConsistencyAdrReferencePort;
+  workItemReflectionPort?: WorkItemReflectionPort;
 }
 
 export class ConsistencyCheckService {
   private readonly designDocumentPort: ConsistencyDesignDocumentPort;
   private readonly adrReferencePort: ConsistencyAdrReferencePort;
+  private readonly workItemReflectionPort?: WorkItemReflectionPort;
 
   constructor(deps: ConsistencyCheckServiceDeps) {
     this.designDocumentPort = deps.designDocumentPort;
     this.adrReferencePort = deps.adrReferencePort;
+    this.workItemReflectionPort = deps.workItemReflectionPort;
   }
 
   async check(targetDocs?: readonly string[]): Promise<ConsistencyReport> {
     const layerAnnotations = await this.designDocumentPort.getLayerAnnotations(targetDocs);
 
-    const mismatchPairs: { expected: string; actual: string; location: string }[] = [];
+    const mismatchPairs: MismatchPair[] = [];
     const checkTargets = Object.keys(layerAnnotations);
 
     for (const [location, annotation] of Object.entries(layerAnnotations)) {
@@ -75,4 +99,57 @@ export class ConsistencyCheckService {
       checkedAt: new Date().toISOString(),
     });
   }
+
+  async checkWorkItemReflection(input: {
+    readonly inceptionRoot: string;
+    readonly designRoot: string;
+  }): Promise<{ readonly report: ConsistencyReport; readonly skipReason?: string }> {
+    if (!this.workItemReflectionPort) {
+      return {
+        report: ConsistencyReport.create({ mismatchPairs: [], checkTargets: [], checkedAt: new Date().toISOString() }),
+        skipReason: 'work item reflection scanner is not configured',
+      };
+    }
+
+    const snapshot = await this.workItemReflectionPort.collect(input);
+    const checkTargets = [
+      ...snapshot.workItems.map((item) => `${item.path}#work-item:${item.id}`),
+      ...snapshot.productRefs.map((ref) => `${ref.path}#work-item:${ref.id}`),
+    ];
+    const productRefIds = new Set(snapshot.productRefs.map((ref) => ref.id));
+    const workItemIds = new Set(snapshot.workItems.map((item) => item.id));
+    const reflectionRequiredItems = snapshot.workItems.filter((item) => item.type !== 'chore');
+    const mismatchPairs: MismatchPair[] = [];
+
+    for (const item of reflectionRequiredItems) {
+      if (!productRefIds.has(item.id)) {
+        mismatchPairs.push({
+          expected: `product docs contain @work-item-id ${item.id}`,
+          actual: 'missing product reflection',
+          location: item.path,
+          nextAction: `Add @work-item-id ${item.id} to the matching product construction document under ${input.designRoot}.`,
+        });
+      }
+    }
+
+    for (const ref of snapshot.productRefs) {
+      if (!workItemIds.has(ref.id)) {
+        mismatchPairs.push({
+          expected: `inception description exists for ${ref.id}`,
+          actual: 'orphan product reflection',
+          location: ref.path,
+          nextAction: `Create or restore an inception description for ${ref.id} under ${input.inceptionRoot}, or remove the stale product annotation.`,
+        });
+      }
+    }
+
+    return {
+      report: ConsistencyReport.create({
+        mismatchPairs,
+        checkTargets,
+        checkedAt: new Date().toISOString(),
+      }),
+      skipReason: snapshot.skipReason,
+    };
+  }
 }