phasegate 0.39.0 → 0.62.0

package/scripts/harness/integrations/pre-commit.ts

@@ -1,37 +1,82 @@
-// @layer infrastructure
 /**
- * Harness Engineering - Pre-commit Integration
+ * @unit harness-api
+ * @layer presentation
  *
- * Reads harness config, determines which validators to run,
- * and executes enabled checks against staged files.
+ * Pre-commit CLI entry.
+ * Runs L2 validators against staged TypeScript files AND design-document
+ * metadata checks against staged Markdown files. Invoked from `.husky/pre-commit`
+ * or `npx phasegate pre-commit`.
  *
- * Called from .husky/pre-commit.
- * Exit code 0 = pass, non-zero = block commit.
+ * Exit codes:
+ *   0 = pass (or nothing to check)
+ *   1 = validation failure (commit blocked)
+ *   2 = runtime error
  */
 
-import { execSync } from "node:child_process";
-import { loadConfig, isHarnessEnabled } from "../core/config-loader.js";
-import { isExcludedPath } from "../core/metadata-parser.js";
-import type { HarnessError } from "../core/error-reporter.js";
-import { createError, formatForHuman } from "../core/error-reporter.js";
+import { execSync } from 'node:child_process';
+import { createValidatorSystemModule } from '../validator-system/composition-root.js';
+import { HumanValidationResultFormatter } from '../validator-system/presentation/formatters/human-validation-result-formatter.js';
+import type { AggregatedValidationReport } from '../validator-system/application/dto/aggregated-validation-report.js';
+import type { ValidationResultContract } from '../validator-system/application/dto/validation-result-contract.js';
+import { createTraceabilityModelModule } from '../traceability-model/composition-root.js';
+import type { ValidateMetadataCommandOutput } from '../traceability-model/presentation/cli/validate-metadata-command-handler.js';
+
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+const TS_EXTENSION = '.ts';
+const MD_EXTENSION = '.md';
+const TEST_FILE_SUFFIXES = Object.freeze([
+  '.test.ts',
+  '.test.tsx',
+  '.spec.ts',
+  '.spec.tsx',
+]);
+
+function isTestFile(path: string): boolean {
+  return TEST_FILE_SUFFIXES.some((suffix) => path.endsWith(suffix));
+}
 
-// ─── ANSI Helpers ───
+interface RunL2Input {
+  readonly targetPaths: readonly string[];
+  readonly unitName: string;
+  readonly currentPhase: string;
+}
 
-const GREEN = "\x1b[32m";
-const BOLD = "\x1b[1m";
-const DIM = "\x1b[2m";
-const RED = "\x1b[31m";
-const RESET = "\x1b[0m";
+interface RunL2UseCaseLike {
+  execute(input: RunL2Input): Promise<readonly ValidationResultContract[]>;
+}
 
-// ─── Staged File Detection ───
+interface ValidateMetadataInput {
+  readonly filePaths: readonly string[];
+  readonly json?: boolean;
+}
+
+interface ValidateMetadataHandlerLike {
+  execute(input: ValidateMetadataInput): Promise<ValidateMetadataCommandOutput>;
+}
+
+export interface PreCommitDeps {
+  readonly runL2ValidatorsUseCase: RunL2UseCaseLike;
+  readonly validateMetadataCommandHandler: ValidateMetadataHandlerLike;
+}
+
+export interface PreCommitResult {
+  readonly exitCode: 0 | 1 | 2;
+  readonly stdout: string;
+}
 
 function getStagedFiles(): string[] {
   try {
-    const output = execSync("git diff --cached --name-only --diff-filter=ACM", {
-      encoding: "utf-8",
+    const output = execSync('git diff --cached --name-only --diff-filter=ACM', {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
     });
     return output
-      .split("\n")
+      .split('\n')
       .map((f) => f.trim())
       .filter((f) => f.length > 0);
   } catch {
@@ -39,126 +84,115 @@ function getStagedFiles(): string[] {
   }
 }
 
-// ─── Dynamic Validator Loading ───
-
-type ValidatorFn = (files: string[], config: import("../core/config-schema.js").HarnessConfig) => Array<{
-  rule: string;
-  severity: "error" | "warning";
-  file: string;
-  message: string;
-  suggestion?: string;
-}>;
-
-interface ValidatorEntry {
-  name: string;
-  harnessKey: keyof import("../core/config-schema.js").HarnessesConfig;
-  category: import("../core/error-reporter.js").HarnessError["category"];
-  importPath: string;
-  exportName: string;
-}
-
-const VALIDATOR_REGISTRY: ValidatorEntry[] = [
-  { name: "phase-gate", harnessKey: "phaseGate", category: "phase_gate", importPath: "../validators/phase-gate.js", exportName: "runPhaseGateCheck" },
-  { name: "architecture", harnessKey: "architecture", category: "architecture", importPath: "../validators/architecture.js", exportName: "runArchitectureCheck" },
-  { name: "dependency", harnessKey: "dependency", category: "dependency", importPath: "../validators/dependency.js", exportName: "runDependencyCheck" },
-  { name: "test-quality", harnessKey: "testQuality", category: "quality", importPath: "../validators/test-quality.js", exportName: "runTestQualityCheck" },
-  { name: "security", harnessKey: "security", category: "security", importPath: "../validators/security.js", exportName: "runSecurityCheck" },
-  { name: "performance", harnessKey: "performance", category: "performance", importPath: "../validators/performance.js", exportName: "runPerformanceCheck" },
-  { name: "consistency", harnessKey: "consistency", category: "consistency", importPath: "../validators/consistency.js", exportName: "runConsistencyCheck" },
-  { name: "metadata", harnessKey: "metadata", category: "quality", importPath: "../validators/metadata.js", exportName: "runMetadataCheck" },
-];
-
-async function loadValidator(entry: ValidatorEntry): Promise<ValidatorFn | null> {
-  try {
-    const mod = await import(entry.importPath);
-    return mod[entry.exportName] ?? null;
-  } catch {
-    // Validator not yet implemented, skip gracefully
-    return null;
-  }
+function buildReport(
+  results: readonly ValidationResultContract[],
+): AggregatedValidationReport {
+  const passed = results.filter((r) => r.passed && !r.skipped).length;
+  const failed = results.filter((r) => !r.passed && !r.skipped).length;
+  const skipped = results.filter((r) => r.skipped).length;
+  const allErrors = results.flatMap((r) => r.errors);
+  const errorCount = allErrors.filter((e) => e.severity === 'error').length;
+  const warnCount = allErrors.filter((e) => e.severity === 'warning').length;
+  return {
+    overallPassed: failed === 0,
+    totalValidators: results.length,
+    passedValidators: passed,
+    failedValidators: failed,
+    skippedValidators: skipped,
+    allErrors,
+    summary: {
+      totalErrors: errorCount,
+      totalWarnings: warnCount,
+      errorsByLayer: { L2: errorCount, L3: 0, L4: 0 },
+    },
+    results,
+  };
 }
 
-// ─── Convert Validator Errors to HarnessErrors ───
-
-function toHarnessErrors(
-  validatorErrors: Array<{ rule: string; severity: "error" | "warning"; file: string; message: string; suggestion?: string }>,
-  entry: ValidatorEntry,
-): HarnessError[] {
-  return validatorErrors.map((err) =>
-    createError({
-      code: `HARNESS-${err.rule.toUpperCase().replace(/[^A-Z0-9]/g, "-")}`,
-      severity: err.severity,
-      category: entry.category,
-      location: { file: err.file },
-      message: {
-        short: err.message,
-        detailed: err.message,
-        agentInstruction: err.suggestion ?? "",
-      },
-      metadata: { timestamp: new Date().toISOString(), validator: entry.name, layer: "L2" },
-    }),
-  );
+function maxExitCode(a: 0 | 1 | 2, b: 0 | 1 | 2): 0 | 1 | 2 {
+  return (Math.max(a, b) as 0 | 1 | 2);
 }
 
-// ─── Main ───
-
-async function main(): Promise<void> {
-  const config = loadConfig();
-
-  // Check if L2 (pre-commit) layer is enabled
-  if (!config.layers.L2_precommit.enabled) {
-    console.log(`${DIM}[harness] L2 Pre-commit layer is disabled. Skipping.${RESET}`);
-    return;
+export async function runPreCommit(
+  stagedFiles: readonly string[],
+  deps: PreCommitDeps,
+): Promise<PreCommitResult> {
+  const tsFiles = stagedFiles.filter((f) => f.endsWith(TS_EXTENSION));
+  const mdFiles = stagedFiles.filter((f) => f.endsWith(MD_EXTENSION));
+  const testFiles = tsFiles.filter((f) => isTestFile(f));
+  const metadataFiles = [...mdFiles, ...testFiles];
+
+  if (tsFiles.length === 0 && mdFiles.length === 0) {
+    return {
+      exitCode: 0,
+      stdout: `${DIM}[phasegate] No staged files to check. Skipping.${RESET}`,
+    };
   }
 
-  // Get staged .ts files, filtering excluded paths
-  const allStaged = getStagedFiles();
-  const tsFiles = allStaged
-    .filter((f) => f.endsWith(".ts"))
-    .filter((f) => !isExcludedPath(f, config));
-
-  if (tsFiles.length === 0) {
-    console.log(`${DIM}[harness] No relevant TypeScript files staged. Skipping.${RESET}`);
-    return;
-  }
-
-  console.log(`${BOLD}[harness]${RESET} Pre-commit check (${tsFiles.length} file(s))`);
-
-  const allErrors: HarnessError[] = [];
+  const sections: string[] = [];
+  sections.push(
+    `${BOLD}[phasegate]${RESET} Pre-commit check ` +
+      `(${tsFiles.length} .ts file(s), ${mdFiles.length} .md file(s))`,
+  );
 
-  // Load and run enabled validators in order
-  for (const entry of VALIDATOR_REGISTRY) {
-    if (!isHarnessEnabled(config, entry.harnessKey, "L2_precommit")) {
-      continue;
-    }
+  let exitCode: 0 | 1 | 2 = 0;
 
-    const runValidator = await loadValidator(entry);
-    if (!runValidator) {
-      continue;
+  if (tsFiles.length > 0) {
+    const results = await deps.runL2ValidatorsUseCase.execute({
+      targetPaths: tsFiles,
+      unitName: '',
+      currentPhase: '',
+    });
+    const report = buildReport(results);
+    sections.push('');
+    sections.push(`${BOLD}== TypeScript 実装 (${tsFiles.length} file(s)) ==${RESET}`);
+    sections.push(new HumanValidationResultFormatter().format(report));
+    if (!report.overallPassed) {
+      exitCode = maxExitCode(exitCode, 1);
     }
-
-    console.log(`  ${DIM}Running ${entry.name}...${RESET}`);
-    const errors = runValidator(tsFiles, config);
-    allErrors.push(...toHarnessErrors(errors, entry));
   }
 
-  // Report results
-  const errorCount = allErrors.filter((e) => e.severity === "error").length;
-
-  if (allErrors.length > 0) {
-    console.log();
-    console.log(formatForHuman(allErrors, config));
+  if (metadataFiles.length > 0) {
+    const metadataResult = await deps.validateMetadataCommandHandler.execute({
+      filePaths: metadataFiles,
+    });
+    sections.push('');
+    sections.push(
+      `${BOLD}== 設計 / テスト メタデータ注釈 (${metadataFiles.length} file(s)) ==${RESET}`,
+    );
+    sections.push(metadataResult.text);
+    exitCode = maxExitCode(exitCode, metadataResult.exitCode);
   }
 
-  if (errorCount > 0) {
-    console.log(`\n${RED}${BOLD}[harness] Commit blocked.${RESET}`);
-    process.exit(1);
+  sections.push('');
+  if (exitCode === 0) {
+    sections.push(`${GREEN}[phasegate]${RESET} All checks passed.`);
+  } else {
+    sections.push(`${RED}${BOLD}[phasegate] Commit blocked.${RESET}`);
   }
 
-  console.log(`${GREEN}[harness]${RESET} All checks passed.`);
+  return {
+    exitCode,
+    stdout: sections.join('\n'),
+  };
 }
 
-main().catch((err) => {
-  console.error(`${RED}[harness] Unexpected error:${RESET}`, err);
-  process.exit(1);
-});
+export async function runPreCommitCli(): Promise<void> {
+  try {
+    const stagedFiles = getStagedFiles();
+    const validatorMod = createValidatorSystemModule();
+    const traceabilityMod = createTraceabilityModelModule(process.cwd());
+
+    const result = await runPreCommit(stagedFiles, {
+      runL2ValidatorsUseCase: validatorMod.runL2ValidatorsUseCase,
+      validateMetadataCommandHandler: traceabilityMod.validateMetadataCommandHandler,
+    });
+
+    process.stdout.write(`${result.stdout}\n`);
+    process.exit(result.exitCode);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${RED}[phasegate] Unexpected error:${RESET} ${msg}\n`);
+    process.exit(2);
+  }
+}

package/scripts/harness/main.ts

@@ -29,7 +29,7 @@ import { buildCiGovernance } from './ci-governance/composition-root.js';
 import { createSkillQualityHandlers } from './skill-quality/composition-root.js';
 import { buildRegressionSuite } from './regression-suite/composition-root.js';
 import { buildPhase2Extensions } from './phase2-extensions/composition-root.js';
-import { deploySkills, deployHookScripts, getDeployedVersion, getHarnessVersion, initHarnessConfig, deployDesignDocs, deployHuskyHook, SKILL_CATEGORIES, getCategoryForSkill } from './setup/skill-deployer.js';
+import { deploySkills, deployHookScripts, getDeployedVersion, getHarnessVersion, initHarnessConfig, deployDesignDocs, deployHuskyHook, deployCodexHooks, SKILL_CATEGORIES, getCategoryForSkill } from './setup/skill-deployer.js';
 import type { SkillSet } from './setup/skill-deployer.js';
 import type { HarnessConfigV2 } from './config-foundation/domain/harness-config.js';
 import { ConfigValidationError } from './config-foundation/domain/errors/config-validation-error.js';
@@ -53,7 +53,7 @@ Usage: phasegate <command> [options]
 
 Setup:
   init                         Initialize project: deploy skills + design docs + phasegate.config.json
-                               (--name <project-name>, --preset <full|standard|minimal|custom>, --with-husky)
+                               (--name <project-name>, --preset <full|standard|minimal|custom>, --agent <claude|codex|both>, --with-husky)
   update-skills                Re-deploy skills from current harness version
 
 Commands:
@@ -85,7 +85,7 @@ Commands:
   phasegate:complete-check       Complete L2-L4 check (--json)
   phasegate:impact-analysis      Impact analysis for story (<storyId>, --json)
 
-  ci:generate-template         Generate CI template (--preset <id>, --type <type>, --render, --json)
+  ci:generate-template         Generate CI template (--preset <id>, --type <aidlc-gate|consistency-check|pre-commit>, --render, --json)
   ci:migrate-agents-md         Migrate AGENTS.md (--dry-run, --validate-only, --json)
   ci:check-repetition          Check error repetition (--code <errorCode>, --reset, --json)
 
@@ -106,7 +106,8 @@ Commands:
   p2:check-freshness             Check doc freshness (--pattern <glob>, --dry-run, --format text|json)
   p2:validate-pointers           Validate doc pointers (--include-urls, --format text|json)
   p2:generate-e2e-template       Generate E2E test template (--phase <phase>, --output <path>)
-  hook <pre-tool-use|post-tool-use|stop>  Run Claude Code hook (reads JSON from stdin)
+  p2:check-initial-creation      Detect long-lived initial_creation:true docs (--pattern <glob>, --format text|json)
+  hook <pre-tool-use|post-tool-use|stop|session-start|user-prompt-submit>  Run agent hook (reads JSON from stdin; writes JSON to stdout for session-start/user-prompt-submit)
   pre-commit                              Run L2 pre-commit validators on staged files
   delegate-sonnet [...args]               Delegate task to Sonnet 4.6 (forwards args to scripts/delegate-sonnet.sh)
 
@@ -400,9 +401,22 @@ async function main(): Promise<void> {
           process.exit(2);
         }
         const skillSet: SkillSet = skillSetRaw;
+        const agentRaw = parseFlag(args, '--agent') ?? 'claude';
+        if (agentRaw !== 'claude' && agentRaw !== 'codex' && agentRaw !== 'both') {
+          console.error(`Invalid --agent value: "${agentRaw}". Use "claude", "codex", or "both".`);
+          process.exit(2);
+        }
+        const agent = agentRaw;
+        const deployClaude = agent === 'claude' || agent === 'both';
+        const deployCodex = agent === 'codex' || agent === 'both';
         const result = await deploySkills(harnessRoot, rootDir, skillSet);
         const configResult = await initHarnessConfig(rootDir, projectName, phasePreset);
-        const hooksResult = await deployHookScripts(harnessRoot, rootDir);
+        const hooksResult = deployClaude
+          ? await deployHookScripts(harnessRoot, rootDir)
+          : { scriptsDeployed: 0, settingsCreated: false };
+        const codexResult = deployCodex
+          ? await deployCodexHooks(harnessRoot, rootDir)
+          : null;
         const designDocsResult = await deployDesignDocs(harnessRoot, rootDir);
         const withHusky = hasFlag(args, '--with-husky');
         const huskyResult = withHusky
@@ -422,6 +436,13 @@ async function main(): Promise<void> {
         } else if (hooksResult.scriptsDeployed > 0) {
           console.log(`  .claude/settings.json already exists, skipped`);
         }
+        if (codexResult !== null) {
+          if (codexResult.created) {
+            console.log(`✓ .codex/hooks.json deployed`);
+          } else {
+            console.log(`  .codex/hooks.json already exists, skipped`);
+          }
+        }
         if (designDocsResult.copiedFiles.length > 0) {
           console.log(`✓ Design docs deployed (${designDocsResult.copiedFiles.length} files)`);
         }
@@ -435,7 +456,7 @@ async function main(): Promise<void> {
             console.log(`  .husky/pre-commit already exists, skipped`);
           }
         }
-        console.log(`✓ Harness v${result.version} initialized`);
+        console.log(`✓ Harness v${result.version} initialized (agent: ${agent})`);
         console.log('');
         console.log('Next steps:');
         if (skillSet === 'core') {
@@ -444,7 +465,14 @@ async function main(): Promise<void> {
           console.log('  1. Run the product-architect skill to start AIDLC');
         }
         console.log('  2. Customize phasegate.config.json if needed');
-        console.log('  3. Edit .claude/scripts/hook-config.json to set target directories');
+        if (deployClaude) {
+          console.log('  3. Edit .claude/scripts/hook-config.json to set target directories');
+        }
+        if (deployCodex) {
+          console.log(`  ${deployClaude ? '4' : '3'}. Enable Codex hooks: codex features enable codex_hooks`);
+          console.log(`  ${deployClaude ? '5' : '4'}. (Recommended) Install pre-commit backstop: rerun with --with-husky or set up husky manually`);
+          console.log(`     See docs/guide/codex-integration.md for the native apply_patch limitation.`);
+        }
         process.exit(0);
         break;
       }
@@ -698,8 +726,29 @@ async function main(): Promise<void> {
       }
 
       case 'phasegate:check-phase': {
+        // ISSUE-005 P2-6: --help / --json を positional として食わないようにする
+        if (hasFlag(args, '--help')) {
+          process.stdout.write([
+            'Usage: phasegate phasegate:check-phase [options]',
+            '',
+            'Check phase gate for a specific unit.',
+            '',
+            'Options:',
+            '  --unit <unitId>   Target unit ID (e.g., harness-api). If omitted,',
+            '                    the first positional argument is used.',
+            '  --json            Output result as JSON.',
+            '  --help            Show this help.',
+            '',
+            'Examples:',
+            '  phasegate phasegate:check-phase --unit harness-api',
+            '  phasegate phasegate:check-phase harness-api --json',
+            '',
+          ].join('\n'));
+          return;
+        }
         const mod = createHarnessApiModule();
-        const unit = parseFlag(args, '--unit') ?? args[1] ?? '';
+        const positional = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
+        const unit = parseFlag(args, '--unit') ?? positional ?? '';
         const flags: Record<string, boolean | string> = {};
         if (json) flags.json = true;
         await mod.handlers.checkPhase.handle({ unit }, flags);
@@ -760,6 +809,25 @@ async function main(): Promise<void> {
 
       // ── ci-governance ──
       case 'ci:generate-template': {
+        if (hasFlag(args, '--help')) {
+          console.log(`Usage: phasegate ci:generate-template [options]
+
+Generates a CI template configuration.
+
+Options:
+  --preset <id>    Preset name (e.g. standard, strict). Required.
+  --type <type>    Template purpose (NOT CI platform name). One of:
+                     aidlc-gate        — AIDLC phase gate checks
+                     consistency-check — Doc/code consistency checks
+                     pre-commit        — Pre-commit hook template
+  --render         Render the template to stdout
+  --json           Output in JSON format
+
+Examples:
+  phasegate ci:generate-template --preset standard --type aidlc-gate
+  phasegate ci:generate-template --preset strict --type pre-commit --render`);
+          process.exit(0);
+        }
         const mod = buildCiGovernance(rootDir);
         const presetId = parseFlag(args, '--preset') ?? 'default';
         const templateType = parseFlag(args, '--type') ?? 'aidlc-gate';
@@ -956,22 +1024,34 @@ async function main(): Promise<void> {
         break;
       }
 
+      case 'p2:check-initial-creation': {
+        const mod = buildPhase2Extensions(rootDir, resolvedConfig ?? undefined);
+        const p2args = args.slice(1);
+        const result = await mod.checkInitialCreationExpirationHandler.handle(p2args);
+        console.log(result.stdout);
+        process.exit(result.exitCode);
+        break;
+      }
+
       // ── agent integration / hooks ──
       case 'hook': {
         const subCommand = args[1];
+        const usage = 'Usage: phasegate hook <pre-tool-use|post-tool-use|stop|session-start|user-prompt-submit>';
         if (!subCommand) {
-          console.error('Usage: phasegate hook <pre-tool-use|post-tool-use|stop>');
+          console.error(usage);
           process.exit(2);
         }
         const hookFileName: Record<string, string> = {
           'pre-tool-use': 'pre-tool-use-hook.js',
           'post-tool-use': 'post-tool-use-hook.js',
           'stop': 'stop-hook.js',
+          'session-start': 'session-start-hook.js',
+          'user-prompt-submit': 'user-prompt-submit-hook.js',
         };
         const fileName = hookFileName[subCommand];
         if (!fileName) {
           console.error(`Unknown hook subcommand: ${subCommand}`);
-          console.error('Usage: phasegate hook <pre-tool-use|post-tool-use|stop>');
+          console.error(usage);
           process.exit(2);
         }
         const hookPath = join(harnessRoot, 'scripts/harness/agent-integration/presentation', fileName);
@@ -981,7 +1061,10 @@ async function main(): Promise<void> {
 
       case 'pre-commit': {
         const preCommitPath = join(harnessRoot, 'scripts/harness/integrations/pre-commit.js');
-        await import(preCommitPath);
+        const preCommitMod = (await import(preCommitPath)) as {
+          runPreCommitCli: () => Promise<void>;
+        };
+        await preCommitMod.runPreCommitCli();
         break;
       }
 

package/scripts/harness/phase2-extensions/application/dto/check-initial-creation-expiration-input.ts

@@ -0,0 +1,9 @@
+/**
+ * @layer application
+ * @unit phase2-extensions
+ */
+export interface CheckInitialCreationExpirationInput {
+  targetPattern?: string;
+  format?: 'text' | 'json';
+  dryRun?: boolean;
+}

package/scripts/harness/phase2-extensions/application/dto/check-initial-creation-expiration-output.ts

@@ -0,0 +1,17 @@
+/**
+ * @layer application
+ * @unit phase2-extensions
+ */
+import type { HarnessErrorContract } from '../../../harness-error/application/dto/harness-error-contract.js';
+import type { InitialCreationExpirationResult } from '../../domain/services/initial-creation-expiration-check-service.js';
+
+export interface CheckInitialCreationExpirationOutput {
+  results: InitialCreationExpirationResult[];
+  summary: {
+    total: number;
+    ok: number;
+    warn: number;
+  };
+  warnings: HarnessErrorContract[];
+  errors: HarnessErrorContract[];
+}

package/scripts/harness/phase2-extensions/application/usecases/check-initial-creation-expiration-usecase.ts

@@ -0,0 +1,103 @@
+/**
+ * @layer application
+ * @unit phase2-extensions
+ */
+import type { CheckInitialCreationExpirationInput } from '../dto/check-initial-creation-expiration-input.js';
+import type { CheckInitialCreationExpirationOutput } from '../dto/check-initial-creation-expiration-output.js';
+import type { InitialCreationExpirationConfigPort } from '../../domain/ports/initial-creation-expiration-config-port.js';
+import type { DocumentScannerPort } from '../../domain/ports/document-scanner-port.js';
+import type { FrontmatterReaderPort } from '../../domain/ports/frontmatter-reader-port.js';
+import type { InitialCreationAgePort } from '../../domain/ports/initial-creation-age-port.js';
+import type { InitialCreationExpirationCheckService } from '../../domain/services/initial-creation-expiration-check-service.js';
+import type { HarnessErrorContract } from '../../../harness-error/application/dto/harness-error-contract.js';
+import type { InitialCreationExpirationResult } from '../../domain/services/initial-creation-expiration-check-service.js';
+
+export class CheckInitialCreationExpirationUseCase {
+  constructor(
+    private readonly configPort: InitialCreationExpirationConfigPort,
+    private readonly scannerPort: DocumentScannerPort,
+    private readonly frontmatterReaderPort: FrontmatterReaderPort,
+    private readonly agePort: InitialCreationAgePort,
+    private readonly checkService: InitialCreationExpirationCheckService,
+  ) {}
+
+  async execute(input: CheckInitialCreationExpirationInput): Promise<CheckInitialCreationExpirationOutput> {
+    try {
+      const allRules = await this.configPort.loadRules();
+      const filteredRules = input.targetPattern
+        ? allRules.filter((rule) => rule.documentPattern === input.targetPattern)
+        : allRules;
+
+      const results: InitialCreationExpirationResult[] = [];
+      const warnings: HarnessErrorContract[] = [];
+
+      for (const rule of filteredRules) {
+        if (!rule.isEnabled()) {
+          continue;
+        }
+
+        const documentPaths = await this.scannerPort.scan(rule.documentPattern);
+
+        for (const documentPath of documentPaths) {
+          const fmResult = await this.frontmatterReaderPort.read(documentPath);
+
+          if (fmResult.parseError !== null) {
+            warnings.push({
+              code: 'L4-232',
+              severity: 'warning',
+              message: `frontmatter parse failed for ${documentPath}: ${fmResult.parseError}`,
+              suggestion: 'YAML 構文を確認してください',
+            });
+            continue;
+          }
+
+          if (fmResult.flags === null || fmResult.flags.initialCreation !== true) {
+            continue;
+          }
+
+          const age = await this.agePort.getAge(documentPath);
+          const checkResult = this.checkService.check(rule, age, documentPath);
+          results.push(checkResult);
+
+          if (checkResult.level === 'warn') {
+            warnings.push({
+              code: 'L4-231',
+              severity: 'warning',
+              message: checkResult.message,
+              suggestion: 'frontmatter を削除し @story-id 注釈を付与してください',
+            });
+          }
+        }
+      }
+
+      const summary = {
+        total: results.length,
+        ok: results.filter((result) => result.level === 'ok').length,
+        warn: results.filter((result) => result.level === 'warn').length,
+      };
+
+      return {
+        results,
+        summary,
+        warnings,
+        errors: [],
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'unknown error';
+
+      return {
+        results: [],
+        summary: { total: 0, ok: 0, warn: 0 },
+        warnings: [],
+        errors: [
+          {
+            code: 'L4-299',
+            severity: 'error',
+            message,
+            suggestion: 'phasegate.config.json を確認してください',
+          },
+        ],
+      };
+    }
+  }
+}