phasegate 0.264.0 → 0.315.0

package/scripts/harness/skill-quality/infrastructure/adapters/file-system-requirement-test-matrix-adapter.ts

@@ -2,26 +2,69 @@
  * @layer infrastructure
  * @unit skill-quality
  * @work-item-id WI-188
+ * @work-item-id WI-341
  */
-import { readFile } from 'node:fs/promises';
-import type { RequirementTestMatrixPort, RequirementTestMatrix } from '../../domain/ports/requirement-test-matrix-port.js';
-import { SkillQualityError } from '../../domain/errors/skill-quality-error.js';
+import { readFile } from "node:fs/promises";
+import { SkillQualityError } from "../../domain/errors/skill-quality-error.js";
+import type {
+  RequirementTestMatrix,
+  RequirementTestMatrixPort,
+} from "../../domain/ports/requirement-test-matrix-port.js";
+
+interface GeneratedMatrixAcMapping {
+  readonly acId: string;
+  readonly testReferences: readonly unknown[];
+}
+
+interface GeneratedMatrixStory {
+  readonly storyId: string;
+  readonly storyMappings: readonly GeneratedMatrixAcMapping[];
+}
 
 export class FileSystemRequirementTestMatrixAdapter implements RequirementTestMatrixPort {
-  constructor(private readonly matrixFilePath: string = '.harness/requirement-test-matrix.json') {}
+  constructor(private readonly matrixFilePath: string = ".harness/requirement-test-matrix.json") {}
 
   async read(storyId: string): Promise<RequirementTestMatrix> {
     let raw: string;
     try {
-      raw = await readFile(this.matrixFilePath, 'utf-8');
+      raw = await readFile(this.matrixFilePath, "utf-8");
     } catch {
-      throw new SkillQualityError('MATRIX_FILE_NOT_FOUND', `requirement-test-matrix.json not found at ${this.matrixFilePath}`);
+      throw new SkillQualityError(
+        "MATRIX_FILE_NOT_FOUND",
+        `requirement-test-matrix.json not found at ${this.matrixFilePath}`,
+      );
     }
-    const data = JSON.parse(raw) as Record<string, unknown>;
+    let data: Record<string, unknown>;
+    try {
+      data = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      throw new SkillQualityError(
+        "MATRIX_FILE_NOT_FOUND",
+        `requirement-test-matrix.json could not be parsed at ${this.matrixFilePath}`,
+      );
+    }
+
+    if (Array.isArray(data.stories)) {
+      const story = (data.stories as GeneratedMatrixStory[]).find((candidate) => candidate.storyId === storyId);
+      if (story === undefined) {
+        throw new SkillQualityError("STORY_NOT_FOUND", `Story ${storyId} not found in ${this.matrixFilePath}`);
+      }
+
+      const uncoveredIds = story.storyMappings
+        .filter((mapping) => !Array.isArray(mapping.testReferences) || mapping.testReferences.length === 0)
+        .map((mapping) => mapping.acId);
+      return {
+        storyId,
+        total: story.storyMappings.length,
+        covered: story.storyMappings.length - uncoveredIds.length,
+        uncoveredIds,
+      };
+    }
+
     const rootEntry = data as { total?: unknown; covered?: unknown; uncoveredIds?: unknown };
     const explicitEntry = data[storyId];
     if (explicitEntry === undefined && rootEntry.total === undefined) {
-      throw new SkillQualityError('STORY_NOT_FOUND', `Story ${storyId} not found in ${this.matrixFilePath}`);
+      throw new SkillQualityError("STORY_NOT_FOUND", `Story ${storyId} not found in ${this.matrixFilePath}`);
     }
     const entry = (explicitEntry ?? data) as { total: number; covered: number; uncoveredIds: string[] };
     return {

package/scripts/harness/skill-quality/presentation/handlers/check-coverage-handler.ts

@@ -2,12 +2,14 @@
  * @layer presentation
  * @unit skill-quality
  * @work-item-id WI-188
+ * @work-item-id WI-341
  */
-import type { CheckCoverageUseCase } from '../../application/usecases/check-coverage-usecase.js';
+import type { CheckCoverageUseCase } from "../../application/usecases/check-coverage-usecase.js";
+import { SkillQualityError } from "../../domain/errors/skill-quality-error.js";
 
 export interface CheckCoverageArgs {
   storyId: string;
-  format?: 'human' | 'json';
+  format?: "human" | "json";
 }
 
 export class CheckCoverageHandler {
@@ -16,9 +18,9 @@ export class CheckCoverageHandler {
   async handle(args: CheckCoverageArgs): Promise<{ exitCode: number; message: string }> {
     try {
       const output = await this.useCase.execute({ storyId: args.storyId });
-      const format = args.format ?? 'human';
+      const format = args.format ?? "human";
 
-      if (format === 'json') {
+      if (format === "json") {
         return { exitCode: output.meetsThreshold ? 0 : 1, message: JSON.stringify(output, null, 2) };
       }
 
@@ -26,7 +28,7 @@ export class CheckCoverageHandler {
       const codeRate = output.coverageReport.codeCoverage.lineCoverage.toFixed(1);
       const msg = `Requirement coverage: ${reqRate}% (threshold: ${output.requirementThreshold}%)\nCode coverage: ${codeRate}% (threshold: ${output.codeThreshold}%)`;
 
-      if (output.skipped === true && output.skipReason === 'no-tests') {
+      if (output.skipped === true && output.skipReason === "no-tests") {
         return { exitCode: 0, message: `Coverage SKIPPED (no tests)\n${msg}` };
       }
 
@@ -35,7 +37,12 @@ export class CheckCoverageHandler {
       }
       return { exitCode: 1, message: `Coverage FAILED\n${msg}` };
     } catch (err) {
-      return { exitCode: 2, message: `Error: ${err instanceof Error ? err.message : String(err)}` };
+      const message = err instanceof Error ? err.message : String(err);
+      if (args.format === "json") {
+        const code = err instanceof SkillQualityError ? err.code : "UNEXPECTED_ERROR";
+        return { exitCode: 2, message: JSON.stringify({ error: { code, message } }, null, 2) };
+      }
+      return { exitCode: 2, message: `Error: ${message}` };
     }
   }
 }

package/scripts/harness/traceability-model/domain/value-objects/work-item-frontmatter.ts

@@ -1,5 +1,6 @@
 // @unit traceability-model
 // @layer domain
+// @work-item-id WI-337
 /**
  * WorkItemFrontmatter — 設計文書 frontmatter から抽出した WI メタデータ（H03-04 / ISSUE-026 Phase A-2）。
  *
@@ -8,7 +9,7 @@
  */
 
 export type WorkItemType = 'story' | 'issue' | 'fix' | 'refactor' | 'chore';
-export type WorkItemSeverity = 'trivial' | 'normal' | 'high';
+export type WorkItemSeverity = 'trivial' | 'normal' | 'medium' | 'high' | 'critical' | 'major';
 export type WorkItemStatus =
   | 'drafted'
   | 'reflected'
@@ -47,7 +48,10 @@ export const WORK_ITEM_TYPES: ReadonlySet<WorkItemType> = new Set([
 export const WORK_ITEM_SEVERITIES: ReadonlySet<WorkItemSeverity> = new Set([
   'trivial',
   'normal',
+  'medium',
   'high',
+  'critical',
+  'major',
 ]);
 
 export const WORK_ITEM_STATUSES: ReadonlySet<WorkItemStatus> = new Set([

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

@@ -1,6 +1,7 @@
 // @unit traceability-model
 // @layer infrastructure
 // @work-item-id WI-106
+// @work-item-id WI-337
 
 import { readdir, readFile } from "node:fs/promises";
 import * as path from "node:path";
@@ -8,6 +9,7 @@ import type {
   WorkItemIdentityEntry,
   WorkItemIdentityPort,
 } from "../../domain/ports/work-item-identity-port.js";
+import { WorkItemFrontmatterValidationError } from "../../domain/value-objects/work-item-frontmatter.js";
 import { parseWorkItemFrontmatter } from "../parsers/work-item-frontmatter-parser.js";
 
 const WI_DIR_PATTERN = /^WI-\d+$/;
@@ -67,7 +69,10 @@ export class FileSystemWorkItemIdentityGateway implements WorkItemIdentityPort {
     try {
       const content = await readFile(path.join(this.rootDir, descriptionPath), "utf8");
       return parseWorkItemFrontmatter(content)?.id ?? null;
-    } catch {
+    } catch (error) {
+      if (error instanceof WorkItemFrontmatterValidationError) {
+        console.warn(`[phasegate] warning: ${descriptionPath} をスキップしました: ${error.message}`);
+      }
       return null;
     }
   }

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

@@ -1,11 +1,15 @@
 // @unit traceability-model
 // @layer infrastructure
 // @work-item-id WI-126 / WI-140
+// @work-item-id WI-337
 
 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 WorkItemFrontmatter,
+  WorkItemFrontmatterValidationError,
+} from "../../domain/value-objects/work-item-frontmatter.js";
 import type {
   WorkItemStatusApplyResult,
   WorkItemStatusInput,
@@ -52,7 +56,16 @@ export class FileSystemWorkItemStatusGateway implements WorkItemStatusPort {
     const inputs: WorkItemStatusInput[] = [];
     for (const entry of entries) {
       const content = await readFile(path.join(this.rootDir, entry.descriptionPath), "utf8");
-      const frontmatter = parseWorkItemFrontmatter(content);
+      let frontmatter: WorkItemFrontmatter | null;
+      try {
+        frontmatter = parseWorkItemFrontmatter(content);
+      } catch (error) {
+        if (error instanceof WorkItemFrontmatterValidationError) {
+          console.warn(`[phasegate] warning: ${entry.descriptionPath} をスキップしました: ${error.message}`);
+          continue;
+        }
+        throw error;
+      }
       if (frontmatter === null) continue;
 
       const aliases = this.aliasesFor(frontmatter);

package/scripts/harness/validator-system/application/use-cases/aggregate-validation-results-usecase.ts

@@ -4,9 +4,9 @@
  *
  * AggregateValidationResultsUseCase — H08-05: バリデータ結果統合集約
  */
-import type { ValidationResultContract } from '../dto/validation-result-contract.js';
-import type { AggregateResultsInput } from '../dto/aggregate-results-input.js';
-import type { AggregatedValidationReport } from '../dto/aggregated-validation-report.js';
+import { isEffectivelyPassed } from "../../domain/services/effective-severity-policy.js";
+import type { AggregateResultsInput } from "../dto/aggregate-results-input.js";
+import type { AggregatedValidationReport } from "../dto/aggregated-validation-report.js";
 
 export class AggregateValidationResultsUseCase {
   execute(input: AggregateResultsInput): AggregatedValidationReport {
@@ -24,7 +24,7 @@ export class AggregateValidationResultsUseCase {
     }[] = [];
     let totalErrors = 0;
     let totalWarnings = 0;
-    const errorsByLayer: Record<'L2' | 'L3' | 'L4', number> = { L2: 0, L3: 0, L4: 0 };
+    const errorsByLayer: Record<"L2" | "L3" | "L4", number> = { L2: 0, L3: 0, L4: 0 };
 
     for (const result of results) {
       if (result.skipped) {
@@ -32,12 +32,9 @@ export class AggregateValidationResultsUseCase {
         continue;
       }
 
-      // ADR-017: warning-only validator fail は failOnWarning=false で overall PASS、true で従来挙動 (FAIL)
-      const hasNonWarningError = result.errors.some((e) => e.severity !== 'warning');
-      const hasWarnings = result.errors.some((e) => e.severity === 'warning');
-      const isEmptyFail = !result.passed && result.errors.length === 0;
-      const hasFail =
-        !result.passed && (isEmptyFail || hasNonWarningError || (failOnWarning && hasWarnings));
+      // ADR-017 / WI-332: warning-only validator fail は failOnWarning=false で overall PASS、
+      // true で従来挙動 (FAIL)。実効判定は domain の共有実装 isEffectivelyPassed に一本化。
+      const hasFail = !isEffectivelyPassed(result, failOnWarning);
 
       if (hasFail) {
         failedValidators++;
@@ -54,7 +51,7 @@ export class AggregateValidationResultsUseCase {
         };
         allErrors.push(errorEntry);
 
-        if (error.severity === 'warning') {
+        if (error.severity === "warning") {
           totalWarnings++;
         } else {
           totalErrors++;
@@ -62,9 +59,9 @@ export class AggregateValidationResultsUseCase {
 
         // レイヤー別集計
         const code = error.code;
-        if (code.startsWith('L2-')) errorsByLayer.L2++;
-        else if (code.startsWith('L3-')) errorsByLayer.L3++;
-        else if (code.startsWith('L4-')) errorsByLayer.L4++;
+        if (code.startsWith("L2-")) errorsByLayer.L2++;
+        else if (code.startsWith("L3-")) errorsByLayer.L3++;
+        else if (code.startsWith("L4-")) errorsByLayer.L4++;
       }
     }
 

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

@@ -3,6 +3,8 @@
  * @unit validator-system
  * @work-item-id WI-212
  * @work-item-id WI-302
+ * @work-item-id WI-317
+ * @work-item-id WI-324
  *
  * RunL3ValidatorsUseCase — H08-02: L3バリデータ実行
  */
@@ -22,8 +24,8 @@ import {
   type ValidatorExecutionService,
 } from "../../domain/services/validator-execution-service.js";
 import { ValidatorLanguageCapabilityService } from "../../domain/services/validator-language-capability-service.js";
-import { WorldConstraintRederivationService } from "../../domain/services/world-constraint-rederivation-service.js";
 import type { ValidatorRegistry } from "../../domain/services/validator-registry.js";
+import { WorldConstraintRederivationService } from "../../domain/services/world-constraint-rederivation-service.js";
 import type { HarnessErrorLike } from "../../domain/value-objects/validation-result.js";
 import { ValidationResult } from "../../domain/value-objects/validation-result.js";
 import { ValidatorId } from "../../domain/value-objects/validator-id.js";
@@ -133,8 +135,10 @@ export class RunL3ValidatorsUseCase {
     );
 
     // L3-003: カバレッジ判定（カバレッジゲートはオプトイン）
-    // - coverageThreshold 未設定 → SKIP（透過的に判定をスキップ。getCoverage() は呼ばない）
-    // - coverageThreshold 設定あり → getCoverage() を try/catch で包み FAIL-CLOSED で判定する
+    // - coverageThreshold 未設定 or 0 → SKIP（透過的に判定をスキップ。getCoverage() は呼ばない）
+    //   0 は正規の opt-out（ドメイン VO L3Config.hasCoverageGate() の「threshold > 0 でのみ有効」と整合。
+    //   minimal preset の coverageThreshold: 0 もこの opt-out 意図。WI-317 / github#37）
+    // - coverageThreshold > 0 → getCoverage() を try/catch で包み FAIL-CLOSED で判定する
     //   - 閾値未満 → FAIL / 閾値以上 → PASS
     //   - レポート不在などで getCoverage() が失敗 → FAIL（合格扱いにしない）
     // このブロックは例外を送出せず、L3-003 の per-validator 結果のみを差し替える。
@@ -145,12 +149,12 @@ export class RunL3ValidatorsUseCase {
       const l3003Id = ValidatorId.create("L3-003");
       const threshold = layerConfig.getThreshold("coverageThreshold");
 
-      if (threshold === null) {
+      if (threshold === null || threshold === 0) {
         overrideMap.set(
           "L3-003",
           ValidationResult.skipWithReason(
             l3003Id,
-            "coverageThreshold が未設定のためカバレッジ判定をスキップ（カバレッジゲートはオプトイン）",
+            "coverageThreshold が未設定/0 のためカバレッジ判定をスキップ（カバレッジゲートはオプトイン。0 で opt-out）",
           ),
         );
       } else {
@@ -167,6 +171,9 @@ export class RunL3ValidatorsUseCase {
                     severity: "error",
                     message: `カバレッジ不足: 現在値 ${coverageData.overallCoverage}%、不足 ${threshold - coverageData.overallCoverage}%`,
                     suggestion: `テストカバレッジを ${threshold}% 以上に引き上げてください`,
+                    // WI-335: 閾値未達の解消はテスト追加（AI/人間の判断）が必要。
+                    // L3-003 の registry 既定は mechanical だが、この finding は機械適用不能なので明示的に上書きする。
+                    remediationType: "ai-assisted",
                   },
                 ],
                 0,
@@ -186,7 +193,13 @@ export class RunL3ValidatorsUseCase {
                   code: "L3-003",
                   severity: "error",
                   message: `coverageThreshold=${threshold}% が設定されていますがカバレッジレポートが見つかりません（テストをカバレッジ付きで実行してください）`,
-                  suggestion: "vitest --coverage 等でカバレッジレポートを生成してから再実行してください",
+                  // WI-335: 選択肢 (b)「layers.L3.coverageThreshold を 0 に設定する」は config 編集のみで
+                  // 完結する機械適用可能な opt-out（WI-317 / github#37）なので mechanical と宣言する。
+                  // この文言（layers.L3.coverageThreshold を 0）を変える場合は remediation-round-trip
+                  // テスト（機械適用器が同じ文言を解析する）が fail する。
+                  suggestion:
+                    '次のいずれかで解消してください: (a) テストをカバレッジ付きで実行してレポートを生成する（例: vitest --coverage）、(b) カバレッジゲートを opt-out するなら config の layers.L3.coverageThreshold を 0 に設定する、(c) 非 JS/TS プロジェクトなら project.languages を宣言する（例: ["python"]。L3-003 自体が unsupported-language SKIP になる）',
+                  remediationType: "mechanical",
                 },
               ],
               0,
@@ -224,7 +237,19 @@ export class RunL3ValidatorsUseCase {
         const policyResult = await this.acCoveragePolicyPort.checkCoverage({
           matrixFilePath: input.requirementMatrixPath,
         });
-        if (!policyResult.passed) {
+        // WI-324: フレッシュプロジェクト（story 未作成・matrix 未生成）は policy adapter が
+        // skipped=true を返すので、L3-003 の opt-out と同じ表現で skipWithReason に変換する。
+        // story が存在するのに matrix が不在の場合は従来どおり fail-closed（下の分岐）。
+        if (policyResult.skipped) {
+          overrideMap.set(
+            "L3-004",
+            ValidationResult.skipWithReason(
+              ValidatorId.create("L3-004"),
+              policyResult.skipReason ??
+                "story 未作成のため L3-004 をスキップ（story 作成後に requirement-test-matrix を生成すると有効化されます）",
+            ),
+          );
+        } else if (!policyResult.passed) {
           overrideMap.set("L3-004", ValidationResult.fail(ValidatorId.create("L3-004"), [...policyResult.errors], 0));
         }
       }

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

@@ -8,6 +8,7 @@
  * @work-item-id WI-301
  * @work-item-id WI-302
  * @work-item-id WI-305
+ * @work-item-id WI-322
  */
 
 import { join } from "node:path";
@@ -73,7 +74,9 @@ const DEFAULT_CONFIG = {
     L3: {
       enabled: true,
       validators: ["L3-001", "L3-002", "L3-003", "L3-004", "L3-006", "L3-007"],
-      coverageThreshold: 90,
+      // WI-322 (github#37 残課題): カバレッジゲートはオプトイン（WI-317）。config なし環境の
+      // fallback で 90% を強制しない。0 = 正規の opt-out（L3-003 は透過 SKIP になる）。
+      coverageThreshold: 0,
       bundleSizeLimit: 512000,
       requirementMatrixPath: ".harness/requirement-test-matrix.json",
     },

package/scripts/harness/validator-system/domain/ports/ac-coverage-policy-port.ts

@@ -4,11 +4,20 @@
  *
  * AcCoveragePolicyPort — nyquist-validation AcCoverageGatePolicy（L3-004）
  */
-import type { HarnessErrorLike } from '../value-objects/validation-result.js';
+import type { HarnessErrorLike } from "../value-objects/validation-result.js";
 
 export interface AcCoveragePolicyPort {
   checkCoverage(context: { matrixFilePath?: string }): Promise<{
     passed: boolean;
     errors: readonly HarnessErrorLike[];
+    /**
+     * WI-324: フレッシュプロジェクト（story 未作成・matrix 未生成）では L3-004 を
+     * fail-closed ではなく SKIP として扱う。true の場合、上位（RunL3ValidatorsUseCase）は
+     * skipReason 付きの skipWithReason 結果へ変換する。省略時（既存実装・既存モック）は
+     * 従来どおり passed/errors のみで判定される（後方互換 optional）。
+     */
+    skipped?: boolean;
+    /** skipped=true のときの人間可読なスキップ理由。 */
+    skipReason?: string;
   }>;
 }

package/scripts/harness/validator-system/domain/services/effective-severity-policy.ts

@@ -0,0 +1,39 @@
+// @unit validator-system
+// @layer domain
+// @work-item-id WI-332
+
+/**
+ * effective-severity-policy — 実効 severity 判定の単一ソース (ADR-017 / ADR-021)。
+ *
+ * validator 1件が「実質 pass」かを severity-aware に判定するルール。
+ * WI-332 以前は同じ判定式が 3 箇所（validate 集約 usecase / harness-api CiCheckResult /
+ * pre-commit の手動集約）に複製・乖離しており、#38（complete-check だけ warning-only で
+ * exit 1）型の回帰を招いた。以後、実効判定は必ずこの関数を経由すること。
+ *
+ * 判定ルール（ADR-017 Decision の集計セマンティクスそのもの）:
+ * - skipped: 実質 pass
+ * - passed=true: 実質 pass
+ * - passed=false かつ error severity（!= warning）を含む: fail
+ * - passed=false かつ errors=[]（severity 判定不能）: 安全側に倒して fail
+ * - passed=false かつ warning のみ: failOnWarning=false（既定）で実質 pass、true で fail
+ */
+
+/**
+ * 判定に必要な最小構造。validator-system の ValidationResultContract と
+ * harness-api の ValidatorCheckItem の双方が構造的に満たす。
+ */
+export interface EffectiveSeverityCheckItem {
+  readonly passed: boolean;
+  readonly skipped?: boolean;
+  readonly errors?: readonly { readonly severity: string }[];
+}
+
+export function isEffectivelyPassed(item: EffectiveSeverityCheckItem, failOnWarning = false): boolean {
+  if (item.skipped || item.passed) return true;
+  const errors = item.errors ?? [];
+  const hasNonWarningError = errors.some((e) => e.severity !== "warning");
+  const hasWarnings = errors.some((e) => e.severity === "warning");
+  const isEmptyFail = errors.length === 0;
+  const hasFail = isEmptyFail || hasNonWarningError || (failOnWarning && hasWarnings);
+  return !hasFail;
+}

package/scripts/harness/validator-system/domain/value-objects/consistency-report.ts

@@ -6,7 +6,7 @@
  * ConsistencyReport 値オブジェクト
  * 設計文書間のレイヤー整合性検証結果VO（L4-002専用）
  */
-import type { HarnessErrorLike } from './validation-result.js';
+import type { HarnessErrorLike } from "./validation-result.js";
 
 export interface MismatchPair {
   readonly expected: string;
@@ -48,10 +48,12 @@ export class ConsistencyReport {
   // ADR-017 / WI-094: error catalog の defaultSeverity: warning と整合
   toHarnessErrors(): readonly HarnessErrorLike[] {
     return this.mismatchPairs.map((pair) => ({
-      code: { value: 'L4-002', toString: () => 'L4-002' },
-      severity: { value: 'warning', toString: () => 'warning' },
+      code: { value: "L4-002", toString: () => "L4-002" },
+      severity: { value: "warning", toString: () => "warning" },
       message: `レイヤー整合性違反: expected "${pair.expected}" but got "${pair.actual}" at ${pair.location}`,
-      suggestion: pair.nextAction ?? '設計文書間のレイヤー依存方向を統一してください',
+      suggestion: pair.nextAction ?? "設計文書間のレイヤー依存方向を統一してください",
+      // WI-335: 文書間整合の回復は「どちらの記述が正か」の判断を伴う（ai-assisted）。
+      remediationType: "ai-assisted" as const,
     }));
   }
 }

package/scripts/harness/validator-system/domain/value-objects/drift-report.ts

@@ -5,9 +5,9 @@
  * DriftReport 値オブジェクト
  * 設計文書とコード実装の双方向乖離検出結果VO（L4-001専用）
  */
-import type { HarnessErrorLike } from './validation-result.js';
+import type { HarnessErrorLike } from "./validation-result.js";
 
-export type DriftDirection = 'design→code' | 'code→design';
+export type DriftDirection = "design→code" | "code→design";
 
 export interface DriftReportProps {
   readonly direction: DriftDirection;
@@ -29,14 +29,16 @@ export class DriftReport {
     this.direction = props.direction;
     this.unitName = props.unitName;
     this.element = props.element;
-    this.recommendation = props.recommendation ?? (props.description ?? '');
+    this.recommendation = props.recommendation ?? props.description ?? "";
     this.location = Object.freeze(props.location ?? {});
     Object.freeze(this);
   }
 
   static create(props: DriftReportProps): DriftReport {
-    if (props.direction !== 'design→code' && props.direction !== 'code→design') {
-      throw new Error(`Invalid DriftReport direction: "${props.direction}". Must be "design→code" or "code→design" (INV-10)`);
+    if (props.direction !== "design→code" && props.direction !== "code→design") {
+      throw new Error(
+        `Invalid DriftReport direction: "${props.direction}". Must be "design→code" or "code→design" (INV-10)`,
+      );
     }
     return new DriftReport(props);
   }
@@ -44,10 +46,13 @@ export class DriftReport {
   toHarnessError(): HarnessErrorLike {
     // ADR-017 / WI-094: error catalog の defaultSeverity: warning と整合
     return {
-      code: { value: 'L4-001', toString: () => 'L4-001' },
-      severity: { value: 'warning', toString: () => 'warning' },
+      code: { value: "L4-001", toString: () => "L4-001" },
+      severity: { value: "warning", toString: () => "warning" },
       message: `乖離検出 [${this.direction}] Unit: ${this.unitName}, Element: ${this.element}`,
       suggestion: this.recommendation,
+      // WI-335: design drift の解消は設計意図の理解が必要で機械適用不能。AI が設計文書を
+      // 読んで自己修正できる分類（ai-assisted）。
+      remediationType: "ai-assisted",
     };
   }
 

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

@@ -5,7 +5,7 @@
  * ValidationResult 値オブジェクト
  * バリデータ実行結果のスナップショット（不変）
  */
-import type { ValidatorId } from './validator-id.js';
+import type { ValidatorId } from "./validator-id.js";
 
 /** HarnessError の最小互換型（harness-error Unit の HarnessError との疎結合） */
 export interface HarnessErrorLike {
@@ -13,6 +13,12 @@ export interface HarnessErrorLike {
   readonly severity: { readonly value?: string; toString(): string };
   readonly message: string;
   readonly suggestion: string;
+  /**
+   * WI-335: suggestion の修復方式分類。未設定は 'manual' 扱い（機械適用可能と過剰宣言しない）。
+   * 'mechanical' を宣言したエラーは remediation-round-trip テストで
+   * 「エラー → suggestion を機械適用 → 再実行 → pass」が CI 保証される。
+   */
+  readonly remediationType?: "mechanical" | "ai-assisted" | "manual";
   [key: string]: unknown;
 }
 
@@ -49,10 +55,12 @@ export class ValidationResult {
       throw new Error(`ValidationResult durationMs must be >= 0 (got: ${props.durationMs})`);
     }
     if (props.passed && props.errors.length > 0) {
-      throw new Error('ValidationResult invariant violation: passed=true but errors is not empty (INV-5)');
+      throw new Error("ValidationResult invariant violation: passed=true but errors is not empty (INV-5)");
     }
     if (props.skipped && (!props.passed || props.errors.length > 0)) {
-      throw new Error('ValidationResult invariant violation: skipped=true requires passed=true and empty errors (INV-8)');
+      throw new Error(
+        "ValidationResult invariant violation: skipped=true requires passed=true and empty errors (INV-8)",
+      );
     }
     return new ValidationResult(props);
   }

package/scripts/harness/validator-system/infrastructure/adapters/file-system-security-pattern-scanner-adapter.ts

@@ -5,11 +5,12 @@
  *
  * FileSystemSecurityPatternScannerAdapter — SecurityPatternScannerPort実装
  */
-import type { SecurityPatternScannerPort } from '../../domain/ports/security-pattern-scanner-port.js';
-import type { HarnessErrorLike } from '../../domain/value-objects/validation-result.js';
-import { readFile } from 'node:fs/promises';
 
-const ALLOWLIST_MARKER = 'phasegate-allow-secret-fixture';
+import { readFile } from "node:fs/promises";
+import type { SecurityPatternScannerPort } from "../../domain/ports/security-pattern-scanner-port.js";
+import type { HarnessErrorLike } from "../../domain/value-objects/validation-result.js";
+
+const ALLOWLIST_MARKER = "phasegate-allow-secret-fixture";
 
 interface SecurityPattern {
   readonly ruleId: string;
@@ -18,15 +19,15 @@ interface SecurityPattern {
 }
 
 const SECURITY_PATTERNS: readonly SecurityPattern[] = Object.freeze([
-  { ruleId: 'secret.openai', pattern: /\b(?:sk|rk|sess)-[a-zA-Z0-9_-]{20,}\b/g, description: 'OpenAI token family' },
-  { ruleId: 'secret.github', pattern: /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g, description: 'GitHub token family' },
-  { ruleId: 'secret.aws-access-key', pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, description: 'AWS access key id' },
-  { ruleId: 'secret.npm', pattern: /\bnpm_[A-Za-z0-9]{24,}\b/g, description: 'npm token family' },
-  { ruleId: 'secret.slack', pattern: /\bxox[abprs]-[A-Za-z0-9-]{20,}\b/g, description: 'Slack token family' },
+  { ruleId: "secret.openai", pattern: /\b(?:sk|rk|sess)-[a-zA-Z0-9_-]{20,}\b/g, description: "OpenAI token family" },
+  { ruleId: "secret.github", pattern: /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g, description: "GitHub token family" },
+  { ruleId: "secret.aws-access-key", pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, description: "AWS access key id" },
+  { ruleId: "secret.npm", pattern: /\bnpm_[A-Za-z0-9]{24,}\b/g, description: "npm token family" },
+  { ruleId: "secret.slack", pattern: /\bxox[abprs]-[A-Za-z0-9-]{20,}\b/g, description: "Slack token family" },
   {
-    ruleId: 'secret.keyword-context',
+    ruleId: "secret.keyword-context",
     pattern: /\b(?:API_KEY|api_key|apikey|password|PASSWORD|passwd|secret|token)\b\s*[:=]\s*["'][^"']{8,}["']/g,
-    description: 'keyword-context secret',
+    description: "keyword-context secret",
   },
 ]);
 
@@ -39,8 +40,8 @@ export class FileSystemSecurityPatternScannerAdapter implements SecurityPatternS
 
     for (const filePath of targetPaths) {
       try {
-        const content = await readFile(filePath, 'utf-8');
-        const lines = content.split('\n');
+        const content = await readFile(filePath, "utf-8");
+        const lines = content.split("\n");
         lines.forEach((line, idx) => {
           // WI-120: allowlist は行/領域スコープ。以前はファイル内のどこかに
           // マーカーが 1 つでもあればファイル全体をスキップしていたため、同一
@@ -54,12 +55,14 @@ export class FileSystemSecurityPatternScannerAdapter implements SecurityPatternS
             pattern.lastIndex = 0;
             const matches = [...line.matchAll(pattern)];
             for (const match of matches) {
-              const secretValue = match[0] ?? '';
+              const secretValue = match[0] ?? "";
               findings.push({
-                code: { value: 'L3-001', toString: () => 'L3-001' },
-                severity: { value: 'error', toString: () => 'error' },
+                code: { value: "L3-001", toString: () => "L3-001" },
+                severity: { value: "error", toString: () => "error" },
                 message: `セキュリティ問題: ${description} (${ruleId}) at ${filePath}:${idx + 1} value=${redactSecret(secretValue)}`,
                 suggestion: `${ruleId}: 秘密情報は環境変数または秘密管理サービスを使用してください。fixture/docs のダミー値は ${ALLOWLIST_MARKER} を明示してください。`,
+                // WI-335: 秘密情報の無効化・ローテーション・保管方式の選定は人間の判断が必須（manual）。
+                remediationType: "manual",
               });
             }
           }
@@ -88,6 +91,6 @@ function isAllowlisted(line: string, previousLine: string | undefined): boolean
 
 function redactSecret(secretValue: string): string {
   const value = secretValue.trim();
-  if (value.length <= 8) return '<redacted>';
+  if (value.length <= 8) return "<redacted>";
   return `${value.slice(0, 3)}...<redacted:${value.length}>`;
 }