phasegate 0.32.0 → 0.44.0

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

@@ -1,37 +1,37 @@
-// @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 (phase-gate / metadata / test-quality) against staged
+ * TypeScript 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';
 
-// ─── ANSI Helpers ───
-
-const GREEN = "\x1b[32m";
-const BOLD = "\x1b[1m";
-const DIM = "\x1b[2m";
-const RED = "\x1b[31m";
-const RESET = "\x1b[0m";
-
-// ─── Staged File Detection ───
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
 
 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 +39,60 @@ 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;
-  }
-}
-
-// ─── 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 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,
+  };
 }
 
-// ─── 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;
-  }
-
-  // Get staged .ts files, filtering excluded paths
-  const allStaged = getStagedFiles();
-  const tsFiles = allStaged
-    .filter((f) => f.endsWith(".ts"))
-    .filter((f) => !isExcludedPath(f, config));
+  const stagedFiles = getStagedFiles();
+  const tsFiles = stagedFiles.filter((f) => f.endsWith('.ts'));
 
   if (tsFiles.length === 0) {
-    console.log(`${DIM}[harness] No relevant TypeScript files staged. Skipping.${RESET}`);
-    return;
+    process.stdout.write(`${DIM}[phasegate] No staged TypeScript files. Skipping.${RESET}\n`);
+    process.exit(0);
   }
 
-  console.log(`${BOLD}[harness]${RESET} Pre-commit check (${tsFiles.length} file(s))`);
-
-  const allErrors: HarnessError[] = [];
+  process.stdout.write(`${BOLD}[phasegate]${RESET} Pre-commit check (${tsFiles.length} file(s))\n`);
 
-  // Load and run enabled validators in order
-  for (const entry of VALIDATOR_REGISTRY) {
-    if (!isHarnessEnabled(config, entry.harnessKey, "L2_precommit")) {
-      continue;
-    }
+  const mod = createValidatorSystemModule();
+  const results = await mod.runL2ValidatorsUseCase.execute({
+    targetPaths: tsFiles,
+    unitName: '',
+    currentPhase: '',
+  });
 
-    const runValidator = await loadValidator(entry);
-    if (!runValidator) {
-      continue;
-    }
+  const report = buildReport(results);
+  process.stdout.write(`${new HumanValidationResultFormatter().format(report)}\n`);
 
-    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 (errorCount > 0) {
-    console.log(`\n${RED}${BOLD}[harness] Commit blocked.${RESET}`);
+  if (!report.overallPassed) {
+    process.stdout.write(`\n${RED}${BOLD}[phasegate] Commit blocked.${RESET}\n`);
     process.exit(1);
   }
-
-  console.log(`${GREEN}[harness]${RESET} All checks passed.`);
+  process.stdout.write(`\n${GREEN}[phasegate]${RESET} All checks passed.\n`);
+  process.exit(0);
 }
 
 main().catch((err) => {
-  console.error(`${RED}[harness] Unexpected error:${RESET}`, err);
-  process.exit(1);
+  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,10 +29,11 @@ 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, SKILL_CATEGORIES, getCategoryForSkill } from './setup/skill-deployer.js';
+import { deploySkills, deployHookScripts, getDeployedVersion, getHarnessVersion, initHarnessConfig, deployDesignDocs, deployHuskyHook, 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';
+import { ConfigNotFoundError, ConfigPersistenceError } from './config-foundation/infrastructure/repositories/file-system-config-repository.js';
 
 /**
  * main.ts (scripts/harness/main.ts) から2階層上がパッケージルート。
@@ -51,8 +52,8 @@ function printUsage(): void {
 Usage: phasegate <command> [options]
 
 Setup:
-  init                         Initialize project: deploy skills + create phasegate.config.json
-                               (--name <project-name>, --preset <full|standard|minimal|custom>)
+  init                         Initialize project: deploy skills + design docs + phasegate.config.json
+                               (--name <project-name>, --preset <full|standard|minimal|custom>, --with-husky)
   update-skills                Re-deploy skills from current harness version
 
 Commands:
@@ -84,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)
 
@@ -105,6 +106,9 @@ 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)
+  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)
 
 Skills:
   skills list                  List all available skills
@@ -265,10 +269,22 @@ async function loadStoryReflectionProvider(
     };
     reporting?: { outputDir?: string };
   };
+  let content: string;
+  try {
+    content = await fsReadFile(configPath, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Warning: failed to read phasegate.config.json: ${message}\n`);
+    return null;
+  }
   try {
-    const content = await fsReadFile(configPath, 'utf8');
     raw = JSON.parse(content);
-  } catch {
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Warning: phasegate.config.json is not valid JSON: ${message}\n`);
     return null;
   }
   const section: PhaseDepConfigSection = {
@@ -325,7 +341,15 @@ async function loadResolvedConfig(): Promise<HarnessConfigV2 | undefined> {
       process.stderr.write(`Invalid phasegate.config.json: ${error.message}\n`);
       process.exit(2);
     }
-
+    if (error instanceof ConfigNotFoundError) {
+      return undefined;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof ConfigPersistenceError) {
+      process.stderr.write(`Warning: phasegate.config.json is not valid JSON: ${message}\n`);
+    } else {
+      process.stderr.write(`Warning: failed to load phasegate.config.json: ${message}\n`);
+    }
     return undefined;
   }
 }
@@ -379,6 +403,11 @@ async function main(): Promise<void> {
         const result = await deploySkills(harnessRoot, rootDir, skillSet);
         const configResult = await initHarnessConfig(rootDir, projectName, phasePreset);
         const hooksResult = await deployHookScripts(harnessRoot, rootDir);
+        const designDocsResult = await deployDesignDocs(harnessRoot, rootDir);
+        const withHusky = hasFlag(args, '--with-husky');
+        const huskyResult = withHusky
+          ? await deployHuskyHook(harnessRoot, rootDir)
+          : null;
         console.log(`✓ Skills deployed to ${result.targetDir} (${result.deployedSkills.length} skills, set: ${skillSet})`);
         if (configResult.created) {
           console.log(`✓ phasegate.config.json created`);
@@ -393,6 +422,19 @@ async function main(): Promise<void> {
         } else if (hooksResult.scriptsDeployed > 0) {
           console.log(`  .claude/settings.json already exists, skipped`);
         }
+        if (designDocsResult.copiedFiles.length > 0) {
+          console.log(`✓ Design docs deployed (${designDocsResult.copiedFiles.length} files)`);
+        }
+        for (const skipped of designDocsResult.skippedFiles) {
+          console.log(`  ${skipped} already exists, skipped`);
+        }
+        if (huskyResult !== null) {
+          if (huskyResult.created) {
+            console.log(`✓ .husky/pre-commit deployed`);
+          } else {
+            console.log(`  .husky/pre-commit already exists, skipped`);
+          }
+        }
         console.log(`✓ Harness v${result.version} initialized`);
         console.log('');
         console.log('Next steps:');
@@ -656,8 +698,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);
@@ -685,7 +748,7 @@ async function main(): Promise<void> {
         const flags: Record<string, boolean | string> = {};
         if (json) flags.json = true;
         await mod.handlers.status.handle({}, flags);
-        await printStoryReflectionStatusLine(rootDir);
+        if (!json) await printStoryReflectionStatusLine(rootDir);
         break;
       }
 
@@ -718,6 +781,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';
@@ -914,6 +996,49 @@ async function main(): Promise<void> {
         break;
       }
 
+      // ── agent integration / hooks ──
+      case 'hook': {
+        const subCommand = args[1];
+        if (!subCommand) {
+          console.error('Usage: phasegate hook <pre-tool-use|post-tool-use|stop>');
+          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',
+        };
+        const fileName = hookFileName[subCommand];
+        if (!fileName) {
+          console.error(`Unknown hook subcommand: ${subCommand}`);
+          console.error('Usage: phasegate hook <pre-tool-use|post-tool-use|stop>');
+          process.exit(2);
+        }
+        const hookPath = join(harnessRoot, 'scripts/harness/agent-integration/presentation', fileName);
+        await import(hookPath);
+        break;
+      }
+
+      case 'pre-commit': {
+        const preCommitPath = join(harnessRoot, 'scripts/harness/integrations/pre-commit.js');
+        await import(preCommitPath);
+        break;
+      }
+
+      case 'delegate-sonnet': {
+        const { spawn } = await import('node:child_process');
+        const scriptPath = join(harnessRoot, 'scripts/delegate-sonnet.sh');
+        const forwardArgs = args.slice(1);
+        const child = spawn('bash', [scriptPath, ...forwardArgs], { stdio: 'inherit' });
+        await new Promise<void>((_, reject) => {
+          child.on('exit', (code) => {
+            process.exit(code ?? 1);
+          });
+          child.on('error', reject);
+        });
+        break;
+      }
+
       // ── skills ──
       case 'skills': {
         const subCommand = args[1];

package/scripts/harness/phase2-extensions/infrastructure/adapters/git-log-document-age-adapter.ts

@@ -17,13 +17,19 @@ export class GitLogDocumentAgeAdapter implements DocumentAgePort {
   constructor(
     private readonly projectRoot: string,
     private readonly nowProvider: () => Date = () => new Date(),
-    private readonly gitLogExecutor: (command: string, options: { cwd: string }) => Buffer = execSync,
+    private readonly gitLogExecutor: (
+      command: string,
+      options: { cwd: string; stdio?: readonly ['pipe', 'pipe', 'pipe'] },
+    ) => Buffer = execSync,
   ) {}
 
   async getAge(documentPath: string): Promise<DocumentAge> {
     try {
       const output = this.gitLogExecutor(`git log --format=%ai -1 -- "${documentPath}"`, {
         cwd: this.projectRoot,
+        // ISSUE-005 P1-3: fresh repo では "fatal: your current branch ... does not have
+        // any commits yet" が 34回 stderr に漏れる。pipe に束ねて静音化する。
+        stdio: ['pipe', 'pipe', 'pipe'] as const,
       })
         .toString()
         .trim();

package/scripts/harness/quick-mode/infrastructure/adapters/git-diff-changed-files-adapter.ts

@@ -42,9 +42,17 @@ export class GitDiffChangedFilesAdapter {
   getChangedFiles(): readonly ChangedFile[] {
     let output: string;
 
+    // ISSUE-005 P1-3: fresh repo (HEAD 未作成) では `git diff ... HEAD` が fatal
+    // になるため、HEAD の存在を事前確認して命令を切り替える
+    const hasHead = this.hasHead();
+    const command = hasHead
+      ? 'git diff --name-status --cached HEAD'
+      : 'git diff --name-status --cached';
+
     try {
-      output = childProcess.execSync('git diff --name-status --cached HEAD', {
+      output = childProcess.execSync(command, {
         encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
       }) as string;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -89,4 +97,15 @@ export class GitDiffChangedFilesAdapter {
 
     return Object.freeze(files);
   }
+
+  private hasHead(): boolean {
+    try {
+      childProcess.execSync('git rev-parse --verify HEAD', {
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
 }

package/scripts/harness/regression-suite/composition-root.ts

@@ -40,7 +40,10 @@ export function buildRegressionSuite(baseDir: string): RegressionSuiteCompositio
   const suiteRegistryPort = new StaticSuiteRegistryAdapter();
   const testRunnerPort = new VitestTestRunnerAdapter();
   const configQueryPort = new HarnessConfigQueryAdapter();
-  const ciGateResultWriterPort = new JsonCiGateResultWriterAdapter(baseDir);
+  // ISSUE-005 P2-7: リポジトリ直下ではなく reports/regression/ 配下に出力する
+  const ciGateResultWriterPort = new JsonCiGateResultWriterAdapter(
+    path.join(baseDir, 'reports', 'regression'),
+  );
   const importAnalyzerPort = new BiomeAstImportAnalyzerAdapter();
   const v0SpecReaderPort = new FileSystemV0SpecReaderAdapter(baseDir);
   const migrationMappingRepositoryPort = new MarkdownMigrationMappingRepositoryAdapter(

package/scripts/harness/setup/skill-deployer.ts

@@ -292,3 +292,102 @@ export async function initHarnessConfig(
   await fs.writeFile(configPath, JSON.stringify(template, null, 2) + '\n', 'utf-8');
   return { created: true, path: configPath };
 }
+
+export interface DeployDesignDocsResult {
+  copiedFiles: string[];
+  skippedFiles: string[];
+}
+
+/**
+ * 設計原則ドキュメントを対象プロジェクトの docs/ にデプロイする。
+ * - docs/folder_management_rules.md → <projectRoot>/docs/folder_management_rules.md
+ * - docs/principles/*.md → <projectRoot>/docs/principles/*.md
+ * 既存ファイルは上書きせずスキップする。
+ */
+export async function deployDesignDocs(
+  harnessRoot: string,
+  projectRoot: string,
+): Promise<DeployDesignDocsResult> {
+  const copiedFiles: string[] = [];
+  const skippedFiles: string[] = [];
+  const docsTargetDir = join(projectRoot, 'docs');
+  const principlesTargetDir = join(docsTargetDir, 'principles');
+
+  await fs.mkdir(docsTargetDir, { recursive: true });
+  await fs.mkdir(principlesTargetDir, { recursive: true });
+
+  const folderRulesRelativePath = join('docs', 'folder_management_rules.md');
+  const folderRulesSource = join(harnessRoot, folderRulesRelativePath);
+  const folderRulesTarget = join(projectRoot, folderRulesRelativePath);
+
+  try {
+    await fs.access(folderRulesTarget);
+    skippedFiles.push(folderRulesRelativePath);
+  } catch {
+    try {
+      await fs.access(folderRulesSource);
+      await fs.copyFile(folderRulesSource, folderRulesTarget);
+      copiedFiles.push(folderRulesRelativePath);
+    } catch {
+      // 配置元が存在しない場合はスキップ
+    }
+  }
+
+  const principlesSourceDir = join(harnessRoot, 'docs', 'principles');
+
+  try {
+    const principleEntries = await fs.readdir(principlesSourceDir, { withFileTypes: true });
+    const principleFiles = principleEntries
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+      .map((entry) => entry.name)
+      .sort();
+
+    for (const principleFile of principleFiles) {
+      const relativePath = join('docs', 'principles', principleFile);
+      const sourcePath = join(principlesSourceDir, principleFile);
+      const targetPath = join(projectRoot, relativePath);
+
+      try {
+        await fs.access(targetPath);
+        skippedFiles.push(relativePath);
+      } catch {
+        await fs.copyFile(sourcePath, targetPath);
+        copiedFiles.push(relativePath);
+      }
+    }
+  } catch {
+    // principles ディレクトリが存在しない場合はスキップ
+  }
+
+  return { copiedFiles, skippedFiles };
+}
+
+export interface DeployHuskyHookResult {
+  created: boolean;
+  path: string;
+}
+
+/**
+ * husky pre-commit フックを対象プロジェクトの .husky/ にデプロイする。
+ * 既存があればスキップする。実行権限 0o755 を付与する。
+ */
+export async function deployHuskyHook(
+  harnessRoot: string,
+  projectRoot: string,
+): Promise<DeployHuskyHookResult> {
+  const targetPath = join(projectRoot, '.husky', 'pre-commit');
+
+  try {
+    await fs.access(targetPath);
+    return { created: false, path: targetPath };
+  } catch {
+    // 配置先が存在しない場合は新規作成
+  }
+
+  const sourcePath = join(harnessRoot, 'templates', '.husky', 'pre-commit');
+  await fs.mkdir(join(projectRoot, '.husky'), { recursive: true });
+  await fs.copyFile(sourcePath, targetPath);
+  await fs.chmod(targetPath, 0o755);
+
+  return { created: true, path: targetPath };
+}

package/scripts/harness/validator-system/application/dto/run-full-validation-input.ts

@@ -13,4 +13,9 @@ export interface RunFullValidationInput {
   readonly failOnWarning?: boolean;
   readonly coverageReportPath?: string;
   readonly requirementMatrixPath?: string;
+  /**
+   * ISSUE-005 P1-4: 実行レイヤー絞り込み。未指定は全レイヤー実行。
+   * 指定された場合、`includeL4` より優先される。
+   */
+  readonly targetLayers?: readonly ('L2' | 'L3' | 'L4')[];
 }