phasegate 0.160.20 → 0.160.21

package/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **WI-217 — personal inception/product consistency** — makes L4-002 validate configured personal documentation roots, scopes L4-004 freshness to `paths.designDocs`, adds personal hook L4 backstop behavior for `.phasegate-local` docs, and lets `scaffold-wi` use custom IDs and personal inception roots.
+
 ## [0.160.16] - 2026-05-22
 
 ### Fixed

package/docs/templates/personal/hooks/pre-commit

@@ -18,4 +18,20 @@ if [ "${HARNESS_QUICK_MODE:-0}" = "1" ]; then
 else
   $PHASEGATE_CMD validate --layer L2 --format human
 fi
+L2_EXIT=$?
+if [ $L2_EXIT -ne 0 ]; then
+  echo "PhaseGate L2 validation failed."
+  exit 1
+fi
+
+STAGED_FILES="$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null || true)"
+if printf '%s\n' "$STAGED_FILES" | grep -E '^\.phasegate-local/(inception|product)/' >/dev/null 2>&1; then
+  $PHASEGATE_CMD validate --layer L4 --format human --fail-on-warning
+  L4_EXIT=$?
+  if [ $L4_EXIT -ne 0 ]; then
+    echo "PhaseGate local inception/product consistency failed."
+    exit 1
+  fi
+fi
 
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.160.20",
+  "version": "0.160.21",
   "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

@@ -2,6 +2,7 @@
  * @layer application
  * @unit config-foundation
  * @work-item-id WI-133 / WI-156
+ * @work-item-id WI-217
  */
 import type { HarnessConfigV2 } from '../../domain/harness-config.js';
 
@@ -27,19 +28,26 @@ export function toValidatorSystemConfig(resolvedConfig: HarnessConfigV2 | undefi
     'pointer-validator': 'L4-005',
     'skill-catalog-drift': 'L4-006',
   }, /^L4-\d{3}$/);
+  const effectiveL4Validators = usesCustomDocumentRoots(resolvedConfig)
+    ? includeValidator(l4Validators, 'L4-002')
+    : l4Validators;
 
   return {
     project: { preset: resolvedConfig.project.preset },
+    paths: {
+      designDocs: resolvedConfig.paths.designDocs,
+      inceptionDocs: resolvedConfig.paths.inceptionDocs,
+    },
     layers: {
       L2: { enabled: resolvedConfig.layers.L2.enabled, validators: ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014', 'L2-015'] },
       L3: {
         enabled: resolvedConfig.layers.L3.enabled,
-        ...(l3Validators.length > 0 ? { validators: l3Validators } : {}),
+        validators: l3Validators.length > 0 ? l3Validators : ['L3-001', 'L3-002', 'L3-003', 'L3-004'],
         coverageThreshold: resolvedConfig.layers.L3.coverageThreshold,
       },
       L4: {
         enabled: resolvedConfig.layers.L4.enabled,
-        ...(l4Validators.length > 0 ? { validators: l4Validators } : {}),
+        validators: effectiveL4Validators.length > 0 ? effectiveL4Validators : ['L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005', 'L4-006'],
       },
     },
     harnesses: {
@@ -53,6 +61,15 @@ export function toValidatorSystemConfig(resolvedConfig: HarnessConfigV2 | undefi
   };
 }
 
+function usesCustomDocumentRoots(resolvedConfig: HarnessConfigV2): boolean {
+  return resolvedConfig.paths.designDocs !== 'docs/product/construction'
+    || resolvedConfig.paths.inceptionDocs !== 'docs/inception';
+}
+
+function includeValidator(validators: readonly string[], validatorId: string): readonly string[] {
+  return validators.includes(validatorId) ? validators : [...validators, validatorId];
+}
+
 function normalizeValidators(
   validators: readonly string[],
   aliases: Readonly<Record<string, string>>,

package/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json

@@ -435,9 +435,7 @@
       "additionalProperties": false,
       "required": [
         "designDocs",
-        "inceptionDocs",
-        "principlesDocs",
-        "folderRulesDoc"
+        "inceptionDocs"
       ],
       "properties": {
         "designDocs": {

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,
+    };
+  }
 }

package/scripts/harness/validator-system/domain/value-objects/validation-result.ts

@@ -22,6 +22,7 @@ export interface ValidationResultRawProps {
   readonly errors: readonly HarnessErrorLike[];
   readonly durationMs: number;
   readonly skipped: boolean;
+  readonly skipReason?: string;
 }
 
 export class ValidationResult {
@@ -30,6 +31,7 @@ export class ValidationResult {
   readonly errors: readonly HarnessErrorLike[];
   readonly durationMs: number;
   readonly skipped: boolean;
+  readonly skipReason?: string;
 
   private constructor(props: ValidationResultRawProps) {
     this.validatorId = props.validatorId;
@@ -37,6 +39,7 @@ export class ValidationResult {
     this.errors = Object.freeze([...props.errors]);
     this.durationMs = props.durationMs;
     this.skipped = props.skipped;
+    this.skipReason = props.skipReason;
     Object.freeze(this);
   }
 
@@ -71,6 +74,10 @@ export class ValidationResult {
     return new ValidationResult({ validatorId, passed: true, errors: [], durationMs: 0, skipped: true });
   }
 
+  static skipWithReason(validatorId: ValidatorId, skipReason: string): ValidationResult {
+    return new ValidationResult({ validatorId, passed: true, errors: [], durationMs: 0, skipped: true, skipReason });
+  }
+
   hasErrors(): boolean {
     return this.errors.length > 0;
   }

package/scripts/harness/validator-system/infrastructure/adapters/file-system-work-item-reflection-adapter.ts

@@ -0,0 +1,102 @@
+/**
+ * @layer infrastructure
+ * @unit validator-system
+ * @work-item-id WI-217
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import type {
+  WorkItemReflectionPort,
+  WorkItemReflectionSnapshot,
+} from '../../domain/services/l4/consistency-check-service.js';
+
+const DESCRIPTION_FILE = 'description.md';
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/;
+const WORK_ITEM_ANNOTATION_PATTERN = /@work-item-id\s+([^<\r\n]+)/g;
+
+function normalizePath(value: string): string {
+  return value.replace(/\\/g, '/');
+}
+
+async function listFiles(root: string): Promise<string[]> {
+  try {
+    const entries = await readdir(root, { withFileTypes: true });
+    const files: string[] = [];
+    for (const entry of entries) {
+      const path = join(root, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...(await listFiles(path)));
+      } else if (entry.isFile()) {
+        files.push(path);
+      }
+    }
+    return files;
+  } catch {
+    return [];
+  }
+}
+
+function extractFrontmatterValue(markdown: string, key: string): string | undefined {
+  const frontmatter = FRONTMATTER_PATTERN.exec(markdown)?.[1];
+  if (!frontmatter) return undefined;
+  const pattern = new RegExp(`^${key}:\\s*(.+?)\\s*$`, 'm');
+  return pattern.exec(frontmatter)?.[1]?.replace(/^["']|["']$/g, '').trim();
+}
+
+function extractWorkItemRefs(markdown: string): string[] {
+  const refs = new Set<string>();
+  for (const match of markdown.matchAll(WORK_ITEM_ANNOTATION_PATTERN)) {
+    const raw = match[1].replace(/-->.*/, '');
+    for (const token of raw.split(/[,\s]+/).map((part) => part.trim()).filter(Boolean)) {
+      if (/^[A-Za-z][A-Za-z0-9_-]*-\d+(?:-\d+)*$/.test(token)) {
+        refs.add(token);
+      }
+    }
+  }
+  return [...refs];
+}
+
+export class FileSystemWorkItemReflectionAdapter implements WorkItemReflectionPort {
+  constructor(private readonly projectRoot: string) {}
+
+  async collect(input: {
+    readonly inceptionRoot: string;
+    readonly designRoot: string;
+  }): Promise<WorkItemReflectionSnapshot> {
+    const inceptionRoot = join(this.projectRoot, input.inceptionRoot);
+    const designRoot = join(this.projectRoot, input.designRoot);
+    const descriptionFiles = (await listFiles(inceptionRoot))
+      .filter((path) => path.endsWith(`/${DESCRIPTION_FILE}`));
+
+    if (descriptionFiles.length === 0) {
+      return {
+        workItems: [],
+        productRefs: [],
+        skipReason: `no work item descriptions found under ${input.inceptionRoot}`,
+      };
+    }
+
+    const workItems: Array<WorkItemReflectionSnapshot['workItems'][number]> = [];
+    for (const path of descriptionFiles) {
+      const markdown = await readFile(path, 'utf8');
+      const id = extractFrontmatterValue(markdown, 'id');
+      if (!id) continue;
+      workItems.push({
+        id,
+        path: normalizePath(relative(this.projectRoot, path)),
+        type: extractFrontmatterValue(markdown, 'type'),
+      });
+    }
+
+    const productRefs: Array<WorkItemReflectionSnapshot['productRefs'][number]> = [];
+    const productFiles = (await listFiles(designRoot)).filter((path) => path.endsWith('.md'));
+    for (const path of productFiles) {
+      const markdown = await readFile(path, 'utf8');
+      for (const id of extractWorkItemRefs(markdown)) {
+        productRefs.push({ id, path: normalizePath(relative(this.projectRoot, path)) });
+      }
+    }
+
+    return { workItems, productRefs };
+  }
+}

package/scripts/harness/validator-system/presentation/formatters/agent-validation-result-formatter.ts

@@ -18,6 +18,9 @@ export class AgentValidationResultFormatter {
       lines.push(`VALIDATOR: ${result.validatorId}`);
       lines.push(`STATUS: ${result.skipped ? 'SKIPPED' : result.passed ? 'PASSED' : 'FAILED'}`);
       lines.push(`DURATION: ${result.durationMs}ms`);
+      if (result.skipped && result.skipReason) {
+        lines.push(`SKIP_REASON: ${result.skipReason}`);
+      }
       if (result.errors.length > 0) {
         lines.push('ERRORS:');
         for (const error of result.errors) {

package/scripts/harness/validator-system/presentation/formatters/human-validation-result-formatter.ts

@@ -25,6 +25,9 @@ export class HumanValidationResultFormatter {
             ? 'FAIL'
             : 'WARN';
       lines.push(`[${status}] ${result.validatorId} (${result.durationMs}ms)`);
+      if (result.skipped && result.skipReason) {
+        lines.push(`  → ${result.skipReason}`);
+      }
       for (const error of result.errors) {
         lines.push(`  ⚠ ${error.message}`);
         lines.push(`  → ${error.suggestion}`);