phasegate 0.140.0 → 0.142.0

package/scripts/harness/traceability-model/infrastructure/gateways/file-system-work-item-status-gateway.ts

@@ -0,0 +1,240 @@
+// @unit traceability-model
+// @layer infrastructure
+// @work-item-id WI-126
+
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import * as path from "node:path";
+import type { WorkItemStatusPort } from "../../domain/ports/work-item-status-port.js";
+import type { WorkItemFrontmatter } from "../../domain/value-objects/work-item-frontmatter.js";
+import type {
+  WorkItemStatusApplyResult,
+  WorkItemStatusInput,
+  WorkItemStatusReport,
+} from "../../domain/value-objects/work-item-status-report.js";
+import { parseWorkItemFrontmatter } from "../parsers/work-item-frontmatter-parser.js";
+
+const WI_DIR_PATTERN = /^WI-\d+$/;
+const MARKDOWN_PATTERN = /\.mdx?$/;
+const SOURCE_PATTERN = /\.(?:ts|tsx|js|jsx)$/;
+const SKIPPED_DIRS = new Set(["archive", "_shared", "_operation", "share", "node_modules", ".git"]);
+
+export interface FileSystemWorkItemStatusGatewayDeps {
+  readonly rootDir: string;
+  readonly inceptionRoot?: string;
+  readonly productRoot?: string;
+  readonly sourceRoot?: string;
+  readonly testRoot?: string;
+}
+
+export class FileSystemWorkItemStatusGateway implements WorkItemStatusPort {
+  private readonly rootDir: string;
+  private readonly inceptionRoot: string;
+  private readonly productRoot: string;
+  private readonly sourceRoot: string;
+  private readonly testRoot: string;
+
+  constructor(deps: FileSystemWorkItemStatusGatewayDeps) {
+    this.rootDir = deps.rootDir;
+    this.inceptionRoot = deps.inceptionRoot ?? "docs/inception";
+    this.productRoot = deps.productRoot ?? "docs/product";
+    this.sourceRoot = deps.sourceRoot ?? "scripts/harness";
+    this.testRoot = deps.testRoot ?? "scripts/harness/__tests__";
+  }
+
+  async listWorkItemStatusInputs(): Promise<readonly WorkItemStatusInput[]> {
+    const entries = await this.listDescriptions(this.inceptionRoot);
+    const productFiles = await this.listFiles(this.productRoot, MARKDOWN_PATTERN);
+    const sourceFiles = (await this.listFiles(this.sourceRoot, SOURCE_PATTERN)).filter(
+      (filePath) => !filePath.startsWith(this.testRoot),
+    );
+    const testFiles = await this.listFiles(this.testRoot, SOURCE_PATTERN);
+
+    const inputs: WorkItemStatusInput[] = [];
+    for (const entry of entries) {
+      const content = await readFile(path.join(this.rootDir, entry.descriptionPath), "utf8");
+      const frontmatter = parseWorkItemFrontmatter(content);
+      if (frontmatter === null) continue;
+
+      const aliases = this.aliasesFor(frontmatter);
+      const productReflectionPaths = await this.filesContainingAny(productFiles, aliases);
+      const implementationPaths = await this.filesContainingAny(sourceFiles, aliases);
+      const testPaths = await this.filesContainingAny(testFiles, aliases);
+      const wiDir = path.posix.dirname(entry.descriptionPath);
+      const existingInceptionArtifacts = await this.existingInceptionArtifacts(wiDir);
+
+      inputs.push(Object.freeze({
+        descriptionPath: entry.descriptionPath,
+        directoryId: entry.directoryId,
+        ownerUnit: entry.ownerUnit,
+        frontmatter,
+        requiredInceptionArtifacts: this.requiredInceptionArtifacts(frontmatter),
+        existingInceptionArtifacts,
+        affectedUnits: this.affectedUnits(entry.ownerUnit, frontmatter),
+        productReflectionPaths,
+        implementationPaths,
+        testPaths,
+      }));
+    }
+    return Object.freeze(inputs.sort((a, b) => a.descriptionPath.localeCompare(b.descriptionPath)));
+  }
+
+  async applyDerivedStatuses(
+    reports: readonly WorkItemStatusReport[],
+  ): Promise<WorkItemStatusApplyResult> {
+    const updated: WorkItemStatusReport[] = [];
+    const unchanged: WorkItemStatusReport[] = [];
+    for (const report of reports) {
+      if (!report.stale) {
+        unchanged.push(report);
+        continue;
+      }
+      const absolutePath = path.join(this.rootDir, report.descriptionPath);
+      const content = await readFile(absolutePath, "utf8");
+      const nextContent = this.replaceStatusLine(content, report.derivedStatus);
+      await writeFile(absolutePath, nextContent, "utf8");
+      updated.push(report);
+    }
+    return Object.freeze({
+      updated: Object.freeze(updated),
+      unchanged: Object.freeze(unchanged),
+    });
+  }
+
+  private async listDescriptions(relativeDir: string): Promise<readonly {
+    readonly descriptionPath: string;
+    readonly directoryId: string;
+    readonly ownerUnit: string | null;
+  }[]> {
+    const results: {
+      descriptionPath: string;
+      directoryId: string;
+      ownerUnit: string | null;
+    }[] = [];
+    await this.collectDescriptions(relativeDir, results);
+    return results;
+  }
+
+  private async collectDescriptions(
+    relativeDir: string,
+    results: { descriptionPath: string; directoryId: string; ownerUnit: string | null }[],
+  ): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(path.join(this.rootDir, relativeDir), { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKIPPED_DIRS.has(entry.name)) continue;
+      const childDir = path.posix.join(relativeDir, entry.name);
+      if (WI_DIR_PATTERN.test(entry.name)) {
+        results.push({
+          descriptionPath: path.posix.join(childDir, "description.md"),
+          directoryId: entry.name,
+          ownerUnit: this.ownerUnitFor(childDir),
+        });
+        continue;
+      }
+      await this.collectDescriptions(childDir, results);
+    }
+  }
+
+  private ownerUnitFor(wiDir: string): string | null {
+    const relative = wiDir.slice(this.inceptionRoot.length).replace(/^\/+/, "");
+    const first = relative.split("/")[0];
+    if (!first || first === "_cross") return null;
+    return first;
+  }
+
+  private async listFiles(relativeDir: string, pattern: RegExp): Promise<readonly string[]> {
+    const results: string[] = [];
+    await this.collectFiles(relativeDir, pattern, results);
+    return Object.freeze(results.sort());
+  }
+
+  private async collectFiles(relativeDir: string, pattern: RegExp, results: string[]): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(path.join(this.rootDir, relativeDir), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (SKIPPED_DIRS.has(entry.name)) continue;
+      const childPath = path.posix.join(relativeDir, entry.name);
+      if (entry.isDirectory()) {
+        await this.collectFiles(childPath, pattern, results);
+      } else if (entry.isFile() && pattern.test(entry.name)) {
+        results.push(childPath);
+      }
+    }
+  }
+
+  private async filesContainingAny(files: readonly string[], aliases: readonly string[]): Promise<readonly string[]> {
+    const results: string[] = [];
+    for (const filePath of files) {
+      const content = await readFile(path.join(this.rootDir, filePath), "utf8");
+      if (aliases.some((alias) => this.containsWorkItemAnnotation(content, alias))) {
+        results.push(filePath);
+      }
+    }
+    return Object.freeze(results);
+  }
+
+  private containsWorkItemAnnotation(content: string, alias: string): boolean {
+    const escaped = alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`@(work-item-id|story-id|issue-id|story)\\s+[^\\n]*\\b${escaped}\\b`).test(content);
+  }
+
+  private aliasesFor(frontmatter: WorkItemFrontmatter): readonly string[] {
+    return Object.freeze([frontmatter.id, frontmatter.legacyId].filter((value): value is string => Boolean(value)));
+  }
+
+  private requiredInceptionArtifacts(frontmatter: WorkItemFrontmatter): readonly string[] {
+    switch (frontmatter.type) {
+      case "story":
+        return Object.freeze(["description.md", "logical_design.md", "domain_model.md", "unit_test_design.md"]);
+      case "issue":
+        return Object.freeze(["description.md", "logical_design.md", "domain_model.md"]);
+      case "refactor":
+        return Object.freeze(["description.md", "logical_design.md"]);
+      case "fix":
+      case "chore":
+        return Object.freeze(["description.md"]);
+    }
+  }
+
+  private async existingInceptionArtifacts(wiDir: string): Promise<readonly string[]> {
+    try {
+      const entries = await readdir(path.join(this.rootDir, wiDir), { withFileTypes: true });
+      return Object.freeze(entries.filter((entry) => entry.isFile()).map((entry) => entry.name));
+    } catch {
+      return Object.freeze([]);
+    }
+  }
+
+  private affectedUnits(ownerUnit: string | null, frontmatter: WorkItemFrontmatter): readonly string[] {
+    if (frontmatter.affects && frontmatter.affects.length > 0) {
+      return Object.freeze([...frontmatter.affects]);
+    }
+    if (ownerUnit) return Object.freeze([ownerUnit]);
+    return Object.freeze([]);
+  }
+
+  private replaceStatusLine(content: string, status: string): string {
+    if (!content.startsWith("---")) {
+      throw new Error("description.md frontmatter is missing");
+    }
+    const frontmatterEnd = content.indexOf("\n---", 4);
+    if (frontmatterEnd === -1) {
+      throw new Error("description.md frontmatter is not closed");
+    }
+    const frontmatter = content.slice(0, frontmatterEnd);
+    if (!/(\nstatus:\s*)[^\n]+/.test(frontmatter)) {
+      throw new Error("description.md frontmatter status is missing");
+    }
+    const nextFrontmatter = frontmatter.replace(/(\nstatus:\s*)[^\n]+/, `$1${status}`);
+    return nextFrontmatter + content.slice(frontmatterEnd);
+  }
+}

package/scripts/harness/traceability-model/presentation/cli/work-item-status-command-handler.ts

@@ -0,0 +1,103 @@
+// @unit traceability-model
+// @layer presentation
+// @work-item-id WI-126
+
+import type { ApplyWorkItemStatusUseCase } from "../../application/usecases/apply-work-item-status-usecase.js";
+import type { DeriveWorkItemStatusUseCase } from "../../application/usecases/derive-work-item-status-usecase.js";
+import type {
+  WorkItemStatusApplyResult,
+  WorkItemStatusReport,
+} from "../../domain/value-objects/work-item-status-report.js";
+
+export interface WorkItemStatusCommandInput {
+  readonly dryRun?: boolean;
+  readonly apply?: boolean;
+  readonly json?: boolean;
+  readonly failOnStale?: boolean;
+  readonly id?: string;
+}
+
+export interface WorkItemStatusCommandOutput {
+  readonly exitCode: 0 | 1 | 2;
+  readonly text: string;
+  readonly reports: readonly WorkItemStatusReport[];
+}
+
+export interface WorkItemStatusCommandHandlerDeps {
+  readonly deriveWorkItemStatusUseCase: Pick<DeriveWorkItemStatusUseCase, "execute">;
+  readonly applyWorkItemStatusUseCase: Pick<ApplyWorkItemStatusUseCase, "execute">;
+}
+
+export class WorkItemStatusCommandHandler {
+  private readonly deriveWorkItemStatusUseCase: Pick<DeriveWorkItemStatusUseCase, "execute">;
+  private readonly applyWorkItemStatusUseCase: Pick<ApplyWorkItemStatusUseCase, "execute">;
+
+  constructor(deps: WorkItemStatusCommandHandlerDeps) {
+    this.deriveWorkItemStatusUseCase = deps.deriveWorkItemStatusUseCase;
+    this.applyWorkItemStatusUseCase = deps.applyWorkItemStatusUseCase;
+  }
+
+  async execute(input: WorkItemStatusCommandInput): Promise<Readonly<WorkItemStatusCommandOutput>> {
+    if (input.apply && input.dryRun) {
+      return Object.freeze({
+        exitCode: 2,
+        text: "Error: --dry-run and --apply cannot be used together",
+        reports: Object.freeze([]),
+      });
+    }
+    if (!input.apply && !input.dryRun) {
+      return Object.freeze({
+        exitCode: 2,
+        text: "Error: either --dry-run or --apply is required",
+        reports: Object.freeze([]),
+      });
+    }
+
+    if (input.apply) {
+      const result = await this.applyWorkItemStatusUseCase.execute({ id: input.id });
+      const reports = Object.freeze([...result.updated, ...result.unchanged]);
+      return Object.freeze({
+        exitCode: 0,
+        text: input.json ? JSON.stringify(result, null, 2) : this.formatApply(result),
+        reports,
+      });
+    }
+
+    const allReports = await this.deriveWorkItemStatusUseCase.execute();
+    const reports = input.id
+      ? allReports.filter((report) => report.id === input.id)
+      : allReports;
+    const stale = reports.some((report) => report.stale);
+    return Object.freeze({
+      exitCode: stale && input.failOnStale ? 1 : 0,
+      text: input.json ? JSON.stringify({ reports }, null, 2) : this.formatReports(reports),
+      reports,
+    });
+  }
+
+  private formatReports(reports: readonly WorkItemStatusReport[]): string {
+    const lines = ["Work item status report"];
+    for (const report of reports) {
+      const marker = report.stale ? "STALE" : "OK";
+      lines.push(
+        `[${marker}] ${report.id}: current=${report.currentStatus} derived=${report.derivedStatus}`,
+        `  path: ${report.descriptionPath}`,
+        `  reason: ${report.reason}`,
+        `  next: ${report.nextAction}`,
+      );
+    }
+    return lines.join("\n");
+  }
+
+  private formatApply(result: WorkItemStatusApplyResult): string {
+    const lines = ["Work item status apply"];
+    for (const report of result.updated) {
+      lines.push(`updated ${report.id}: ${report.currentStatus} -> ${report.derivedStatus}`);
+    }
+    if (result.updated.length === 0) {
+      lines.push("no updates required");
+    }
+    lines.push(`unchanged: ${result.unchanged.length}`);
+    return lines.join("\n");
+  }
+}

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

@@ -9,38 +9,28 @@ import { ValidatorId } from '../../domain/value-objects/validator-id.js';
 import { ValidationResult } from '../../domain/value-objects/validation-result.js';
 import { ItTestMockDetectionService } from '../../domain/services/it-test-mock-detection-service.js';
 import { StubCommentDetectionService } from '../../domain/services/stub-comment-detection-service.js';
-import { CliE2eTestExistenceService } from '../../domain/services/cli-e2e-test-existence-service.js';
 import { ValidationResultContractMapper } from '../mappers/validation-result-contract-mapper.js';
 import type { ValidationResultContract } from '../dto/validation-result-contract.js';
 import type { RunL1ValidatorsInput } from '../dto/run-l1-validators-input.js';
 import type { ItTestFileAnalyzerPort } from '../../domain/ports/it-test-file-analyzer-port.js';
 import type { SourceFileTextScannerPort } from '../../domain/ports/source-file-text-scanner-port.js';
-import type { CliCommandRegistryPort } from '../../domain/ports/cli-command-registry-port.js';
-import type { E2eTestFileRegistryPort } from '../../domain/ports/e2e-test-file-registry-port.js';
 
 export interface RunL1ValidatorsUseCaseDeps {
   itTestFileAnalyzerPort: ItTestFileAnalyzerPort;
   sourceFileTextScannerPort: SourceFileTextScannerPort;
-  cliCommandRegistryPort?: CliCommandRegistryPort;
-  e2eTestFileRegistryPort?: E2eTestFileRegistryPort;
   contractMapper: ValidationResultContractMapper;
 }
 
 export class RunL1ValidatorsUseCase {
   private readonly itTestFileAnalyzerPort: ItTestFileAnalyzerPort;
   private readonly sourceFileTextScannerPort: SourceFileTextScannerPort;
-  private readonly cliCommandRegistryPort: CliCommandRegistryPort | undefined;
-  private readonly e2eTestFileRegistryPort: E2eTestFileRegistryPort | undefined;
   private readonly mapper: ValidationResultContractMapper;
   private readonly itTestMockDetectionService = new ItTestMockDetectionService();
   private readonly stubCommentDetectionService = new StubCommentDetectionService();
-  private readonly cliE2eTestExistenceService = new CliE2eTestExistenceService();
 
   constructor(deps: RunL1ValidatorsUseCaseDeps) {
     this.itTestFileAnalyzerPort = deps.itTestFileAnalyzerPort;
     this.sourceFileTextScannerPort = deps.sourceFileTextScannerPort;
-    this.cliCommandRegistryPort = deps.cliCommandRegistryPort;
-    this.e2eTestFileRegistryPort = deps.e2eTestFileRegistryPort;
     this.mapper = deps.contractMapper;
   }
 
@@ -49,7 +39,6 @@ export class RunL1ValidatorsUseCase {
 
     results.push(await this.runL1017(input));
     results.push(await this.runL1018(input));
-    results.push(await this.runL2013());
 
     return this.mapper.toContracts(results);
   }
@@ -115,38 +104,6 @@ export class RunL1ValidatorsUseCase {
     }
   }
 
-  /** H08-09: L2-013 CLIコマンドE2Eテスト存在チェック (Should) */
-  private async runL2013(): Promise<ValidationResult> {
-    const validatorId = ValidatorId.create('L2-013');
-    if (!this.cliCommandRegistryPort || !this.e2eTestFileRegistryPort) {
-      return ValidationResult.skip(validatorId);
-    }
-    const start = Date.now();
-    try {
-      const commands = await this.cliCommandRegistryPort.getRegisteredCommands();
-      const e2eFiles = await this.e2eTestFileRegistryPort.getE2eTestFiles();
-      const report = this.cliE2eTestExistenceService.check(commands, e2eFiles);
-      const durationMs = Date.now() - start;
-      if (report.hasViolations()) {
-        const errors = report.toMessages().map((msg) => ({
-          code: { value: 'L2-013', toString: () => 'L2-013' },
-          severity: { value: 'error', toString: () => 'error' },
-          message: msg,
-          suggestion: 'Add an E2E test for each registered CLI command in cli-harness.test.ts.',
-        }));
-        return ValidationResult.fail(validatorId, errors, durationMs);
-      }
-      return ValidationResult.pass(validatorId, durationMs);
-    } catch (err) {
-      const durationMs = Date.now() - start;
-      return ValidationResult.fail(validatorId, [{
-        code: { value: 'L2-013', toString: () => 'L2-013' },
-        severity: { value: 'error', toString: () => 'error' },
-        message: `L2-013 execution failed: ${err instanceof Error ? err.message : String(err)}`,
-        suggestion: '',
-      }], durationMs);
-    }
-  }
 }
 
-// @story-id H08-07
+// @story-id H08-07

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

@@ -16,6 +16,9 @@ import type { ValidatorConfigPort } from '../../domain/ports/validator-config-po
 import type { PhaseGatePolicyPort } from '../../domain/ports/phase-gate-policy-port.js';
 import type { MetadataPolicyPort } from '../../domain/ports/metadata-policy-port.js';
 import type { TestQualityAnalyzerPort } from '../../domain/ports/test-quality-analyzer-port.js';
+import type { CliCommandRegistryPort } from '../../domain/ports/cli-command-registry-port.js';
+import type { E2eTestFileRegistryPort } from '../../domain/ports/e2e-test-file-registry-port.js';
+import { CliE2eTestExistenceService } from '../../domain/services/cli-e2e-test-existence-service.js';
 
 export interface RunL2ValidatorsUseCaseDeps {
   validatorRegistry: ValidatorRegistry;
@@ -25,6 +28,8 @@ export interface RunL2ValidatorsUseCaseDeps {
   phaseGatePolicyPort?: PhaseGatePolicyPort;
   metadataPolicyPort?: MetadataPolicyPort;
   testQualityAnalyzerPort?: TestQualityAnalyzerPort;
+  cliCommandRegistryPort?: CliCommandRegistryPort;
+  e2eTestFileRegistryPort?: E2eTestFileRegistryPort;
 }
 
 export class RunL2ValidatorsUseCase {
@@ -35,6 +40,9 @@ export class RunL2ValidatorsUseCase {
   private readonly phaseGatePolicyPort?: PhaseGatePolicyPort;
   private readonly metadataPolicyPort?: MetadataPolicyPort;
   private readonly testQualityAnalyzerPort?: TestQualityAnalyzerPort;
+  private readonly cliCommandRegistryPort?: CliCommandRegistryPort;
+  private readonly e2eTestFileRegistryPort?: E2eTestFileRegistryPort;
+  private readonly cliE2eTestExistenceService = new CliE2eTestExistenceService();
 
   constructor(deps: RunL2ValidatorsUseCaseDeps) {
     this.registry = deps.validatorRegistry;
@@ -44,6 +52,8 @@ export class RunL2ValidatorsUseCase {
     this.phaseGatePolicyPort = deps.phaseGatePolicyPort;
     this.metadataPolicyPort = deps.metadataPolicyPort;
     this.testQualityAnalyzerPort = deps.testQualityAnalyzerPort;
+    this.cliCommandRegistryPort = deps.cliCommandRegistryPort;
+    this.e2eTestFileRegistryPort = deps.e2eTestFileRegistryPort;
   }
 
   async execute(input: RunL2ValidatorsInput): Promise<readonly ValidationResultContract[]> {
@@ -122,6 +132,26 @@ export class RunL2ValidatorsUseCase {
       }
     }
 
+    if (this.cliCommandRegistryPort && this.e2eTestFileRegistryPort) {
+      const l2013Result = overrideMap.get('L2-013');
+      if (l2013Result && !l2013Result.skipped) {
+        const commands = await this.cliCommandRegistryPort.getRegisteredCommands();
+        const e2eFiles = await this.e2eTestFileRegistryPort.getE2eTestFiles();
+        const report = this.cliE2eTestExistenceService.check(commands, e2eFiles);
+        if (report.hasViolations()) {
+          const errors = report.toMessages().map((msg) => ({
+            code: { value: 'L2-013', toString: () => 'L2-013' },
+            severity: { value: 'error', toString: () => 'error' },
+            message: msg,
+            suggestion: 'Add an E2E test for each registered CLI command in cli-harness.test.ts.',
+          }));
+          overrideMap.set('L2-013', ValidationResult.fail(ValidatorId.create('L2-013'), errors, 0));
+        } else {
+          overrideMap.set('L2-013', ValidationResult.pass(ValidatorId.create('L2-013'), 0));
+        }
+      }
+    }
+
     const finalResults = definitions.map(
       (definition) => overrideMap.get(definition.validatorId.value) ?? ValidationResult.skip(definition.validatorId),
     );

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

@@ -109,7 +109,7 @@ export class RunL4ValidatorsUseCase {
     }
 
     if (!layerConfig.enabled && !input.forceLayerEnabled) {
-      return [];
+      return this.mapper.toContracts(definitions.map((definition) => ValidationResult.skip(definition.validatorId)));
     }
 
     const effectiveLayerConfig = input.forceLayerEnabled && !layerConfig.enabled

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

@@ -45,7 +45,7 @@ import { join } from 'node:path';
 const DEFAULT_CONFIG = {
   preset: 'standard' as const,
   layers: {
-    L2: { enabled: true, validators: ['L2-001', 'L2-002', 'L2-003'] },
+    L2: { enabled: true, validators: ['L2-001', 'L2-002', 'L2-003', 'L2-013'] },
     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'] },
   },
@@ -77,6 +77,7 @@ function buildDefaultRegistry(): ValidatorRegistry {
     createDef('L2-001', 'L2', 'always', 'PhaseGatePolicyPort'),
     createDef('L2-002', 'L2', 'always', 'MetadataPolicyPort'),
     createDef('L2-003', 'L2', 'always'),
+    createDef('L2-013', 'L2', 'always', 'CliE2eTestExistenceService'),
     createDef('L3-001', 'L3', 'always'),
     createDef('L3-002', 'L3', 'strictOnly'),
     createDef('L3-003', 'L3', 'always'),
@@ -123,6 +124,18 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
   const securityScannerPort = new FileSystemSecurityPatternScannerAdapter();
   const performanceScannerPort = new AstPerformanceScannerAdapter();
 
+  const docsRoot = join(process.cwd(), 'docs/product/construction');
+  const cwd = process.cwd();
+  const e2eTestFileRegistryPort = new E2eTestFileRegistryAdapter({ e2eTestRoot: join(cwd, 'scripts/harness/__tests__/e2e') });
+  const cliCommandRegistryPort = new CliCommandRegistryAdapter({
+    commands: [
+      'validate', 'lint', 'ci-check',
+      'phasegate:check-ready', 'phasegate:check-phase', 'phasegate:ci-check',
+      'phasegate:detect-drift', 'phasegate:lint', 'phasegate:complete-check',
+      'phasegate:impact-analysis', 'phasegate:status',
+    ],
+  });
+
   const runL2ValidatorsUseCase = new RunL2ValidatorsUseCase({
     validatorRegistry: registry,
     validatorExecutionService: executionService,
@@ -131,6 +144,8 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
     phaseGatePolicyPort,
     metadataPolicyPort,
     testQualityAnalyzerPort,
+    e2eTestFileRegistryPort,
+    cliCommandRegistryPort,
   });
 
   const runL3ValidatorsUseCase = new RunL3ValidatorsUseCase({
@@ -143,7 +158,6 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
     performanceScannerPort,
   });
 
-  const docsRoot = join(process.cwd(), 'docs/product/construction');
   const markdownDesignDocumentPort = new MarkdownDesignDocumentAdapter(docsRoot);
   const sourceCodeAnalyzerAdapter = new BiomeAstSourceCodeAnalyzerAdapter();
   const adrReferencePort = new AdrFoundationReferenceAdapter();
@@ -182,26 +196,15 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
   });
 
   const aggregateValidationResultsUseCase = new AggregateValidationResultsUseCase();
-  const KNOWN_CLI_COMMANDS = [
-    'validate', 'lint', 'ci-check', 'detect-drift',
-    'phasegate:check-ready', 'phasegate:check-phase', 'phasegate:ci-check',
-    'phasegate:detect-drift', 'phasegate:lint', 'phasegate:complete-check',
-    'phasegate:impact-analysis', 'phasegate:status',
-  ];
-  const cwd = process.cwd();
   const itTestFileAnalyzerPort = new ItTestFileAnalyzerAdapter({
     itTestRoot: join(cwd, 'scripts/harness/__tests__/integration'),
     // アダプター自体のテストファイルは vi.mock() を使用しているため誤検知防止で除外
     excludePattern: /it-test-file-analyzer-adapter\.test\.ts$/,
   });
   const sourceFileTextScannerPort = new SourceFileTextScannerAdapter({ sourceRoot: join(cwd, 'scripts/harness') });
-  const e2eTestFileRegistryPort = new E2eTestFileRegistryAdapter({ e2eTestRoot: join(cwd, 'scripts/harness/__tests__/e2e') });
-  const cliCommandRegistryPort = new CliCommandRegistryAdapter({ commands: KNOWN_CLI_COMMANDS });
   const runL1ValidatorsUseCase = new RunL1ValidatorsUseCase({
     itTestFileAnalyzerPort,
     sourceFileTextScannerPort,
-    e2eTestFileRegistryPort,
-    cliCommandRegistryPort,
     contractMapper,
   });
 

package/scripts/harness/validator-system/domain/services/cli-e2e-test-existence-service.ts

@@ -5,15 +5,46 @@ import { CliE2eTestCoverageReport, type CliCommandCoverageEntry } from '../value
 
 export class CliE2eTestExistenceService {
   check(commands: readonly string[], e2eTestFiles: readonly string[]): CliE2eTestCoverageReport {
+    if (e2eTestFiles.length === 0) {
+      return CliE2eTestCoverageReport.create(
+        commands.map((commandName) => ({
+          commandName,
+          hasE2eTest: false,
+          status: 'limitation',
+          evidence: 'No CLI E2E test suite found in this project.',
+        })),
+      );
+    }
+
     const e2eContent = e2eTestFiles.join('\n').toLowerCase();
 
-    const entries: CliCommandCoverageEntry[] = commands.map((commandName) => ({
-      commandName,
-      hasE2eTest: e2eContent.includes(commandName.toLowerCase()),
-    }));
+    const entries: CliCommandCoverageEntry[] = commands.map((commandName) => {
+      const evidence = this.findCoverageEvidence(commandName, e2eContent);
+      return {
+        commandName,
+        hasE2eTest: evidence !== null,
+        status: evidence === null ? 'missing' : 'covered',
+        evidence: evidence ?? undefined,
+      };
+    });
 
     return CliE2eTestCoverageReport.create(entries);
   }
+
+  private findCoverageEvidence(commandName: string, e2eContent: string): string | null {
+    const escaped = commandName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const invocationPatterns = [
+      new RegExp(`\\brun\\(\\s*['"\`]${escaped}['"\`]`),
+      new RegExp(`\\brunin(?:cwd)?\\([^\\n]*['"\`]${escaped}['"\`]`),
+      new RegExp(`unknown command:\\s*${escaped}`),
+      new RegExp(`usage:\\s*phasegate\\s+${escaped}`),
+    ];
+    if (invocationPatterns.some((pattern) => pattern.test(e2eContent))) {
+      return commandName;
+    }
+
+    return e2eContent.includes(commandName.toLowerCase()) ? commandName : null;
+  }
 }
 
-// @story-id H08-07
+// @story-id H08-07

package/scripts/harness/validator-system/domain/value-objects/cli-e2e-test-coverage-report.ts

@@ -9,6 +9,8 @@
 export interface CliCommandCoverageEntry {
   readonly commandName: string;
   readonly hasE2eTest: boolean;
+  readonly status?: 'covered' | 'missing' | 'limitation';
+  readonly evidence?: string;
 }
 
 export class CliE2eTestCoverageReport {
@@ -28,7 +30,11 @@ export class CliE2eTestCoverageReport {
   }
 
   uncoveredCommands(): readonly CliCommandCoverageEntry[] {
-    return this.entries.filter((e) => !e.hasE2eTest);
+    return this.entries.filter((e) => !e.hasE2eTest && e.status !== 'limitation');
+  }
+
+  limitations(): readonly CliCommandCoverageEntry[] {
+    return this.entries.filter((e) => e.status === 'limitation');
   }
 
   hasViolations(): boolean {
@@ -42,4 +48,4 @@ export class CliE2eTestCoverageReport {
   }
 }
 
-// @story-id H08-07
+// @story-id H08-07