phasegate 0.39.0 → 0.44.0

package/docs/guide/cli-reference.md

@@ -66,6 +66,21 @@ Commands exposed as npm scripts (`npm run <command>`).
 | `render-errors` | `--format human\|agent\|ci` | Render errors |
 | `validate-fix` | `--code <code>` | Validate fix code example |
 
+### `list-errors` と `render-errors` の使い分け
+
+ISSUE-005 P3-10 で明確化された境界:
+
+- **`list-errors`** — **定義駆動**。`HarnessError` Value Object の**静的な定義**を出力する。
+  コードを実行しないため、常に安定した結果を返す。`--format json` と組み合わせて**異なる
+  バージョン間の定義差分を比較**する用途に向く。
+- **`render-errors`** — **ランタイム駆動**。実行時に蓄積されたエラーの**蓄積履歴**を整形する。
+  まだエラーが記録されていない環境では空を返すため、テストデータや実行痕跡を前提とする。
+  CI ログ向けの詳細フォーマット (`--format ci`) やエージェント送信向けの構造化 (`--format agent`)
+  に向く。
+
+**差分比較を行いたい場合は `list-errors --format json`** を使い、`render-errors` は runtime 観測用と
+位置付けること。
+
 ---
 
 ## Skill Quality

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.39.0",
+  "version": "0.44.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "Apache-2.0",

package/scripts/harness/ci-governance/application/usecases/generate-ci-template-usecase.ts

@@ -9,7 +9,7 @@ import type { TemplateGenerator } from '../../domain/services/template-generator
 import type { GenerateCiTemplateInput } from '../dto/generate-ci-template-input.js';
 import type { GenerateCiTemplateOutput } from '../dto/generate-ci-template-output.js';
 import { CiTemplate } from '../../domain/aggregates/ci-template.js';
-import { isTemplateType } from '../../domain/types/template-type.js';
+import { isTemplateType, TEMPLATE_TYPES } from '../../domain/types/template-type.js';
 
 export class GenerateCiTemplateUseCase {
   constructor(private readonly templateGenerator: TemplateGenerator) {}
@@ -18,6 +18,10 @@ export class GenerateCiTemplateUseCase {
     const { presetId, templateType } = input;
 
     if (!isTemplateType(templateType)) {
+      const validValues = TEMPLATE_TYPES.map((t) => `'${t}'`).join(', ');
+      const hint = /github|gitlab|circle|jenkins|travis|actions/i.test(String(templateType))
+        ? ` (Hint: --type specifies the template purpose, not the CI platform. Use one of: ${validValues})`
+        : ` (valid: ${validValues})`;
       return {
         templateType: templateType as any,
         presetRef: presetId,
@@ -26,7 +30,7 @@ export class GenerateCiTemplateUseCase {
         failOnWarning: false,
         validationErrors: [{
           code: 'CI_TEMPLATE_INVALID_TYPE',
-          message: `INV-1: Invalid templateType: ${templateType}`,
+          message: `INV-1: Invalid templateType: ${templateType}${hint}`,
         }],
       };
     }

package/scripts/harness/harness-api/infrastructure/adapters/validator-system-execution-adapter.ts

@@ -45,8 +45,17 @@ export class ValidatorSystemExecutionAdapter implements ValidatorExecutionPort {
       },
 
       async runDriftDetection(): Promise<DriftItem[]> {
-        // validator-system does not implement drift detection
-        return [];
+        // ISSUE-005 P1-5: L4-001 の DriftDetectionService を直接呼び出し、
+        // phasegate:detect-drift と validate --layer L4 の結果を一致させる
+        const { createValidatorSystemModule } = await import('../../../validator-system/composition-root.js');
+        const mod = createValidatorSystemModule();
+        const reports = await mod.driftDetectionService.detect();
+        return reports.map((r) => ({
+          direction: r.direction,
+          unit: r.unitName,
+          element: r.element,
+          recommendation: r.recommendation,
+        }));
       },
     };
   }

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

@@ -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)
 
@@ -698,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);
@@ -760,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';

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/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')[];
 }

package/scripts/harness/validator-system/application/use-cases/run-full-validation-usecase.ts

@@ -32,22 +32,50 @@ export class RunFullValidationUseCase {
   }
 
   async execute(input: RunFullValidationInput): Promise<AggregatedValidationReport> {
+    // ISSUE-005 P1-4: targetLayers で絞り込み。未指定時は従来の includeL4 挙動を維持。
     const includeL4 = input.includeL4 !== false;
+    const defaultLayers: readonly ('L2' | 'L3' | 'L4')[] = includeL4
+      ? ['L2', 'L3', 'L4']
+      : ['L2', 'L3'];
+    const effectiveLayers = input.targetLayers ?? defaultLayers;
+    const runL2 = effectiveLayers.includes('L2');
+    const runL3 = effectiveLayers.includes('L3');
+    const runL4 = effectiveLayers.includes('L4');
 
-    const l2Results = await this.l2UseCase.execute({
-      targetPaths: input.targetPaths,
-      unitName: input.unitName,
-      currentPhase: input.currentPhase,
-    });
+    type Result = {
+      validatorId: string;
+      passed: boolean;
+      errors: readonly {
+        code: string;
+        severity: string;
+        message: string;
+        suggestion: string;
+        [key: string]: unknown;
+      }[];
+      durationMs: number;
+      skipped?: boolean;
+    };
 
-    const l3Results = await this.l3UseCase.execute({
-      targetPaths: input.targetPaths,
-      coverageReportPath: input.coverageReportPath,
-      requirementMatrixPath: input.requirementMatrixPath,
-    });
+    let l2Results: readonly Result[] = [];
+    if (runL2) {
+      l2Results = await this.l2UseCase.execute({
+        targetPaths: input.targetPaths,
+        unitName: input.unitName,
+        currentPhase: input.currentPhase,
+      });
+    }
+
+    let l3Results: readonly Result[] = [];
+    if (runL3) {
+      l3Results = await this.l3UseCase.execute({
+        targetPaths: input.targetPaths,
+        coverageReportPath: input.coverageReportPath,
+        requirementMatrixPath: input.requirementMatrixPath,
+      });
+    }
 
-    let l4Results: readonly { validatorId: string; passed: boolean; errors: readonly { code: string; severity: string; message: string; suggestion: string; [key: string]: unknown }[]; durationMs: number; skipped?: boolean }[] = [];
-    if (includeL4) {
+    let l4Results: readonly Result[] = [];
+    if (runL4) {
       l4Results = await this.l4UseCase.execute({
         targetUnits: input.targetUnits,
       });

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

@@ -100,6 +100,7 @@ export interface ValidatorSystemModule {
   runQuickModeUseCase: RunQuickModeUseCase;
   aggregateValidationResultsUseCase: AggregateValidationResultsUseCase;
   runFullValidationUseCase: RunFullValidationUseCase;
+  driftDetectionService: DriftDetectionService;
   handlers: {
     runValidators: RunValidatorsHandler;
     runQuickMode: RunQuickModeHandler;
@@ -229,6 +230,7 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
     runQuickModeUseCase,
     aggregateValidationResultsUseCase,
     runFullValidationUseCase,
+    driftDetectionService,
     handlers,
   };
 }

package/scripts/harness/validator-system/domain/services/l4/drift-detection-service.ts

@@ -9,10 +9,20 @@ import { DriftReport } from '../../value-objects/drift-report.js';
 
 export interface DriftDetectionDesignDocumentPort {
   getElements(targetUnits?: readonly string[]): Promise<string[]>;
+  /**
+   * ISSUE-005 P3-9: element → unit 名のマップ。
+   * 実装されていれば DriftReport.unitName の解決に使われる (fallback: 'unknown')。
+   */
+  getElementUnitMap?(targetUnits?: readonly string[]): Promise<Record<string, string>>;
 }
 
 export interface DriftDetectionSourceCodeAnalyzerPort {
   getElements(targetUnits?: readonly string[]): Promise<string[]>;
+  /**
+   * ISSUE-005 P3-9: element → unit 名のマップ。
+   * 実装されていれば DriftReport.unitName の解決に使われる (fallback: 'unknown')。
+   */
+  getElementUnitMap?(targetUnits?: readonly string[]): Promise<Record<string, string>>;
 }
 
 export interface DriftDetectionServiceDeps {
@@ -33,6 +43,23 @@ export class DriftDetectionService {
     const designElements = await this.designDocumentPort.getElements(targetUnits);
     const codeElements = await this.sourceCodeAnalyzerPort.getElements(targetUnits);
 
+    // ISSUE-005 P3-9: element → unit のマップを取得し、DriftReport.unitName の解決に使う
+    const designUnitMap = this.designDocumentPort.getElementUnitMap
+      ? await this.designDocumentPort.getElementUnitMap(targetUnits)
+      : {};
+    const codeUnitMap = this.sourceCodeAnalyzerPort.getElementUnitMap
+      ? await this.sourceCodeAnalyzerPort.getElementUnitMap(targetUnits)
+      : {};
+
+    const resolveUnit = (element: string): string => {
+      return (
+        designUnitMap[element] ??
+        codeUnitMap[element] ??
+        targetUnits?.[0] ??
+        'unknown'
+      );
+    };
+
     const designSet = new Set(designElements);
     const codeSet = new Set(codeElements);
 
@@ -44,7 +71,7 @@ export class DriftDetectionService {
         reports.push(
           DriftReport.create({
             direction: 'design→code',
-            unitName: (targetUnits?.[0]) ?? 'unknown',
+            unitName: resolveUnit(element),
             element,
             description: `設計に存在するがコードに存在しない: ${element}`,
             recommendation: `${element} をコードに実装してください`,
@@ -59,7 +86,7 @@ export class DriftDetectionService {
         reports.push(
           DriftReport.create({
             direction: 'code→design',
-            unitName: (targetUnits?.[0]) ?? 'unknown',
+            unitName: resolveUnit(element),
             element,
             description: `コードに存在するが設計に存在しない: ${element}`,
             recommendation: `${element} を設計文書に追記するか、コードから削除してください`,

package/scripts/harness/validator-system/infrastructure/adapters/biome-ast-source-code-analyzer-adapter.ts

@@ -44,6 +44,23 @@ export class BiomeAstSourceCodeAnalyzerAdapter implements SourceCodeAnalyzerPort
     const results = await this.analyzeExports(targetUnits);
     return results.flatMap((result) => result.exports.map((entry) => entry.name));
   }
+
+  /**
+   * ISSUE-005 P3-9: element 名から unit 名を引けるマップを返す。
+   * 同名 export が複数 unit に存在する場合は最初に見つかった unit を採用する。
+   */
+  async getElementUnitMap(targetUnits?: readonly string[]): Promise<Record<string, string>> {
+    const results = await this.analyzeExports(targetUnits);
+    const map: Record<string, string> = {};
+    for (const result of results) {
+      for (const entry of result.exports) {
+        if (!(entry.name in map)) {
+          map[entry.name] = result.unitName;
+        }
+      }
+    }
+    return map;
+  }
 }
 
 type ExportType = SourceAnalysisResult['exports'][number]['type'];

package/scripts/harness/validator-system/infrastructure/adapters/markdown-design-document-adapter.ts

@@ -8,9 +8,55 @@ import type { DesignDocumentPort, StructuredDesignDoc } from '../../domain/ports
 import { readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 
-const SECTION_PATTERN = /^#{2,3}\s+(.+)/gm;
 const ADR_PATTERN = /ADR-\d{3}/g;
 
+// ISSUE-005 P3-8: メタ見出し / 議論用セクションを drift 対象から除外するマーカー。
+// 見出し行の直後 (同一行末 or 次の非空行) に置かれたコメントを拾う。
+const SKIP_MARKER = /<!--\s*@drift-check\s*:\s*skip\s*-->/i;
+
+// 見出し文字列のうち、デフォルトで drift 対象から外す既知のメタパターン。
+// Unit 設計ドキュメントで頻出する「議論用」「自己評価」系セクション。
+const DEFAULT_META_HEADING_PATTERNS = [
+  /engineering[- ]perspective/i,
+  /自己評価/,
+  /レビュー(観点|コメント)/,
+  /議論/,
+  /TODO|未決事項|Open\s+Questions?/i,
+  /変更履歴|Change\s*Log/i,
+  /参考文献|References?/i,
+];
+
+function isMetaHeading(name: string): boolean {
+  return DEFAULT_META_HEADING_PATTERNS.some((p) => p.test(name));
+}
+
+function extractConceptNames(markdown: string): string[] {
+  const lines = markdown.split(/\r?\n/);
+  const headings: string[] = [];
+  const headingRegex = /^(#{2,3})\s+(.+?)\s*$/;
+  for (let i = 0; i < lines.length; i++) {
+    const m = headingRegex.exec(lines[i]);
+    if (!m) continue;
+    const name = m[2].trim();
+    // 見出し行自体にスキップマーカーが付いている
+    if (SKIP_MARKER.test(lines[i])) continue;
+    // 次の非空行にスキップマーカーが付いている
+    // ただし、次行が新しい見出しの場合はそれ自身の注釈なので無視する
+    let j = i + 1;
+    while (j < lines.length && lines[j].trim() === '') j++;
+    if (
+      j < lines.length &&
+      !headingRegex.test(lines[j]) &&
+      SKIP_MARKER.test(lines[j])
+    ) continue;
+    // 既知のメタ見出しは暗黙的にスキップ
+    if (isMetaHeading(name)) continue;
+    // 名前から末尾のスキップマーカーを落とす (念のため)
+    headings.push(name.replace(SKIP_MARKER, '').trim());
+  }
+  return headings;
+}
+
 export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
   private readonly docsRoot: string;
   private readonly cache = new Map<string, StructuredDesignDoc>();
@@ -38,10 +84,7 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
         const doc: StructuredDesignDoc = {
           unitName,
           docPath,
-          concepts: Array.from(markdown.matchAll(SECTION_PATTERN), (match) => ({
-            name: match[1].trim(),
-            type: 'class',
-          })),
+          concepts: extractConceptNames(markdown).map((name) => ({ name, type: 'class' })),
           layerDependencies: [],
           adrRefs: Array.from(new Set(markdown.match(ADR_PATTERN) ?? [])),
         };
@@ -64,6 +107,23 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
     return docs.flatMap((doc) => doc.concepts.map((concept) => concept.name));
   }
 
+  /**
+   * ISSUE-005 P3-9: element 名から unit 名を引けるマップを返す。
+   * 同名 element が複数 unit に存在する場合は最初に見つかった unit を採用する。
+   */
+  async getElementUnitMap(targetUnits?: readonly string[]): Promise<Record<string, string>> {
+    const docs = await this.loadDesignDocuments(targetUnits);
+    const map: Record<string, string> = {};
+    for (const doc of docs) {
+      for (const concept of doc.concepts) {
+        if (!(concept.name in map)) {
+          map[concept.name] = doc.unitName;
+        }
+      }
+    }
+    return map;
+  }
+
   private async listUnitNames(): Promise<string[]> {
     try {
       const entries = await readdir(this.docsRoot, { withFileTypes: true });

package/scripts/harness/validator-system/presentation/handlers/run-validators-handler.ts

@@ -110,12 +110,21 @@ export class RunValidatorsHandler {
         return { output, exitCode: l1Report.overallPassed ? 0 : 1 };
       }
 
+      // ISSUE-005 P1-4: args.layer を targetLayers にマップ
+      let targetLayers: readonly ('L2' | 'L3' | 'L4')[] | undefined;
+      if (args.layer === 'L2') targetLayers = ['L2'];
+      else if (args.layer === 'L3') targetLayers = ['L3'];
+      else if (args.layer === 'L4') targetLayers = ['L4'];
+      else if (args.layer === 'all') targetLayers = ['L2', 'L3', 'L4'];
+      // undefined → フィルタなし（従来挙動）
+
       const report = await this.useCase.execute({
         targetPaths: args.targetPaths ?? [],
         unitName: args.unit ?? '',
         currentPhase: args.phase ?? '',
         includeL4: !args.noL4,
         failOnWarning: args.failOnWarning,
+        targetLayers,
       });
 
       const format = args.format ?? 'human';