phasegate 0.283.0 → 0.315.0

package/scripts/harness/harness-error/domain/services/harness-error-factory.ts

@@ -5,33 +5,36 @@
  * HarnessErrorFactory ドメインサービス
  * ErrorDefinitionRegistry と Domain ポートを組み合わせて HarnessError を生成する唯一の入口
  */
-import { AdrReferenceNotFoundError } from '../errors/adr-reference-not-found-error.js';
-import { EmptyMessageError } from '../errors/empty-message-error.js';
-import { EmptySuggestionError } from '../errors/empty-suggestion-error.js';
-import { InvalidFixExampleError } from '../errors/invalid-fix-example-error.js';
-import { MissingAdrRefError } from '../errors/missing-adr-ref-error.js';
-import { MissingFixExampleError } from '../errors/missing-fix-example-error.js';
-import type { AdrExistenceCheckerPort } from '../ports/adr-existence-checker-port.js';
-import type { FixExampleValidatorPort } from '../ports/fix-example-validator-port.js';
-import { AdrRef } from '../value-objects/adr-ref.js';
-import { ErrorCode } from '../value-objects/error-code.js';
-import { FixExample } from '../value-objects/fix-example.js';
-import { HarnessError } from '../value-objects/harness-error.js';
-import { Severity } from '../value-objects/severity.js';
-import type { ErrorDefinitionRegistry } from './error-definition-registry.js';
-import type { SeverityContractEnforcer } from './severity-contract-enforcer.js';
+import { AdrReferenceNotFoundError } from "../errors/adr-reference-not-found-error.js";
+import { EmptyMessageError } from "../errors/empty-message-error.js";
+import { EmptySuggestionError } from "../errors/empty-suggestion-error.js";
+import { InvalidFixExampleError } from "../errors/invalid-fix-example-error.js";
+import { MissingAdrRefError } from "../errors/missing-adr-ref-error.js";
+import { MissingFixExampleError } from "../errors/missing-fix-example-error.js";
+import type { AdrExistenceCheckerPort } from "../ports/adr-existence-checker-port.js";
+import type { FixExampleValidatorPort } from "../ports/fix-example-validator-port.js";
+import { AdrRef } from "../value-objects/adr-ref.js";
+import { ErrorCode } from "../value-objects/error-code.js";
+import { FixExample } from "../value-objects/fix-example.js";
+import { HarnessError } from "../value-objects/harness-error.js";
+import type { RemediationType } from "../value-objects/remediation-type.js";
+import { Severity } from "../value-objects/severity.js";
+import type { ErrorDefinitionRegistry } from "./error-definition-registry.js";
+import type { SeverityContractEnforcer } from "./severity-contract-enforcer.js";
 
 export interface CreateHarnessErrorParams {
   readonly code: string;
   readonly message: string;
   readonly suggestion: string;
   readonly validatorId: string;
-  readonly requestedSeverity?: 'error' | 'warning';
+  readonly requestedSeverity?: "error" | "warning";
   readonly adrRef?: string | null;
   readonly fixExample?: string | null;
   readonly suggestedSkill?: string | null;
   readonly scaffoldCommand?: string | null;
   readonly templatePath?: string | null;
+  /** WI-335: suggestion の修復方式分類。省略時は ErrorDefinition の既定に従う。 */
+  readonly remediationType?: RemediationType | null;
 }
 
 export interface HarnessErrorFactoryDeps {
@@ -68,18 +71,14 @@ export class HarnessErrorFactory {
     const definition = this.registry.getDefinition(errorCode);
 
     // 3. severity 解決
-    const requestedSeverity = input.requestedSeverity
-      ? Severity.create(input.requestedSeverity)
-      : undefined;
-    const effectiveSeverity =
-      this.severityContractEnforcer.resolveEffectiveSeverity(
-        requestedSeverity,
-        definition.defaultSeverity
-      );
+    const requestedSeverity = input.requestedSeverity ? Severity.create(input.requestedSeverity) : undefined;
+    const effectiveSeverity = this.severityContractEnforcer.resolveEffectiveSeverity(
+      requestedSeverity,
+      definition.defaultSeverity,
+    );
 
     // 4. ADR 解決
-    const explicitAdrRef =
-      input.adrRef != null ? AdrRef.create(input.adrRef) : undefined;
+    const explicitAdrRef = input.adrRef != null ? AdrRef.create(input.adrRef) : undefined;
     const resolvedAdrRef = definition.resolveAdrRef(explicitAdrRef);
 
     // 5. ADR 必須チェック
@@ -96,12 +95,8 @@ export class HarnessErrorFactory {
     }
 
     // 7. fix_example 解決
-    const explicitFixExample =
-      input.fixExample != null
-        ? FixExample.create(input.fixExample)
-        : undefined;
-    const resolvedFixExample =
-      definition.resolveFixExample(explicitFixExample);
+    const explicitFixExample = input.fixExample != null ? FixExample.create(input.fixExample) : undefined;
+    const resolvedFixExample = definition.resolveFixExample(explicitFixExample);
 
     // 8. fix_example 必須チェック
     if (definition.requiresFixExample() && resolvedFixExample === null) {
@@ -117,7 +112,7 @@ export class HarnessErrorFactory {
       });
       if (!validationResult.passed) {
         throw new InvalidFixExampleError(
-          `fix_example の検証に失敗しました (code=${errorCode.toString()}): ${validationResult.reason}`
+          `fix_example の検証に失敗しました (code=${errorCode.toString()}): ${validationResult.reason}`,
         );
       }
     }
@@ -126,6 +121,7 @@ export class HarnessErrorFactory {
     const resolvedSuggestedSkill = definition.resolveSuggestedSkill(input.suggestedSkill);
     const resolvedScaffoldCommand = definition.resolveScaffoldCommand(input.scaffoldCommand);
     const resolvedTemplatePath = definition.resolveTemplatePath(input.templatePath);
+    const resolvedRemediationType = definition.resolveRemediationType(input.remediationType);
 
     // 11. HarnessError 生成と凍結
     const harnessError = new HarnessError({
@@ -138,6 +134,7 @@ export class HarnessErrorFactory {
       suggestedSkill: resolvedSuggestedSkill,
       scaffoldCommand: resolvedScaffoldCommand,
       templatePath: resolvedTemplatePath,
+      remediationType: resolvedRemediationType,
     });
 
     return Object.freeze(harnessError);

package/scripts/harness/harness-error/domain/value-objects/error-definition.ts

@@ -5,21 +5,22 @@
  * エラー定義値オブジェクト
  * エラーコードごとの正規定義（タイトル、カテゴリ、severity、ADR/fix_example要否）を不変で保持する
  */
-import { InvalidErrorDefinitionError } from '../errors/invalid-error-definition-error.js';
-import type { AdrRef } from './adr-ref.js';
-import type { ErrorCode } from './error-code.js';
-import type { FixExample } from './fix-example.js';
-import type { Severity } from './severity.js';
+import { InvalidErrorDefinitionError } from "../errors/invalid-error-definition-error.js";
+import type { AdrRef } from "./adr-ref.js";
+import type { ErrorCode } from "./error-code.js";
+import type { FixExample } from "./fix-example.js";
+import type { RemediationType } from "./remediation-type.js";
+import type { Severity } from "./severity.js";
 
 export type ErrorDefinitionCategory =
-  | 'phase_gate'
-  | 'architecture'
-  | 'dependency'
-  | 'quality'
-  | 'security'
-  | 'performance'
-  | 'consistency'
-  | 'metadata';
+  | "phase_gate"
+  | "architecture"
+  | "dependency"
+  | "quality"
+  | "security"
+  | "performance"
+  | "consistency"
+  | "metadata";
 
 export interface ErrorDefinitionProps {
   readonly code: ErrorCode;
@@ -34,6 +35,8 @@ export interface ErrorDefinitionProps {
   readonly defaultSuggestedSkill?: string | null;
   readonly defaultScaffoldCommand?: string | null;
   readonly defaultTemplatePath?: string | null;
+  /** WI-335: このエラーコードの既定修復方式。未設定（null）は 'manual' 扱い（後方互換）。 */
+  readonly defaultRemediationType?: RemediationType | null;
 }
 
 export class ErrorDefinition {
@@ -49,6 +52,7 @@ export class ErrorDefinition {
   readonly defaultSuggestedSkill: string | null;
   readonly defaultScaffoldCommand: string | null;
   readonly defaultTemplatePath: string | null;
+  readonly defaultRemediationType: RemediationType | null;
 
   private constructor(props: ErrorDefinitionProps) {
     this.code = props.code;
@@ -63,19 +67,18 @@ export class ErrorDefinition {
     this.defaultSuggestedSkill = props.defaultSuggestedSkill ?? null;
     this.defaultScaffoldCommand = props.defaultScaffoldCommand ?? null;
     this.defaultTemplatePath = props.defaultTemplatePath ?? null;
+    this.defaultRemediationType = props.defaultRemediationType ?? null;
     Object.freeze(this);
   }
 
   static create(props: ErrorDefinitionProps): ErrorDefinition {
     if (!props.ownerValidatorId || props.ownerValidatorId.trim().length === 0) {
-      throw new InvalidErrorDefinitionError(
-        'ownerValidatorId は空文字であってはなりません。'
-      );
+      throw new InvalidErrorDefinitionError("ownerValidatorId は空文字であってはなりません。");
     }
 
     if (props.defaultAdrRef !== null && !props.adrRefRequired) {
       throw new InvalidErrorDefinitionError(
-        'defaultAdrRef を持つ場合は adrRefRequired を true にしなければなりません。'
+        "defaultAdrRef を持つ場合は adrRefRequired を true にしなければなりません。",
       );
     }
 
@@ -128,6 +131,14 @@ export class ErrorDefinition {
     return this.defaultTemplatePath;
   }
 
+  /** WI-335: 明示指定を優先し、なければ定義既定の修復方式を返す（未定義は null = 'manual' 扱い）。 */
+  resolveRemediationType(explicit?: RemediationType | null): RemediationType | null {
+    if (explicit) {
+      return explicit;
+    }
+    return this.defaultRemediationType;
+  }
+
   equals(other: ErrorDefinition): boolean {
     const adrRefEqual =
       this.defaultAdrRef === null && other.defaultAdrRef === null

package/scripts/harness/harness-error/domain/value-objects/harness-error.ts

@@ -5,14 +5,15 @@
  * HarnessError 中心モデル（不変値オブジェクト）
  * 集約を持たず、全属性を不変で保持する値オブジェクトとして設計
  */
-import type { AdrRef } from './adr-ref.js';
-import type { ErrorCode } from './error-code.js';
-import type { FixExample } from './fix-example.js';
-import type { Severity } from './severity.js';
+import type { AdrRef } from "./adr-ref.js";
+import type { ErrorCode } from "./error-code.js";
+import type { FixExample } from "./fix-example.js";
+import { DEFAULT_REMEDIATION_TYPE, type RemediationType } from "./remediation-type.js";
+import type { Severity } from "./severity.js";
 
 export interface HarnessErrorContract {
   readonly code: string;
-  readonly severity: 'error' | 'warning';
+  readonly severity: "error" | "warning";
   readonly message: string;
   readonly suggestion: string;
   readonly adr_ref?: string;
@@ -20,6 +21,7 @@ export interface HarnessErrorContract {
   readonly suggested_skill?: string;
   readonly scaffold_command?: string;
   readonly template_path?: string;
+  readonly remediation_type?: RemediationType;
 }
 
 export interface HarnessErrorProps {
@@ -32,6 +34,8 @@ export interface HarnessErrorProps {
   readonly suggestedSkill?: string | null;
   readonly scaffoldCommand?: string | null;
   readonly templatePath?: string | null;
+  /** WI-335: suggestion の修復方式分類。未設定（null）は 'manual' 扱い（後方互換）。 */
+  readonly remediationType?: RemediationType | null;
 }
 
 export class HarnessError {
@@ -44,6 +48,7 @@ export class HarnessError {
   readonly suggestedSkill: string | null;
   readonly scaffoldCommand: string | null;
   readonly templatePath: string | null;
+  readonly remediationType: RemediationType | null;
 
   constructor(props: HarnessErrorProps) {
     this.code = props.code;
@@ -55,6 +60,7 @@ export class HarnessError {
     this.suggestedSkill = props.suggestedSkill ?? null;
     this.scaffoldCommand = props.scaffoldCommand ?? null;
     this.templatePath = props.templatePath ?? null;
+    this.remediationType = props.remediationType ?? null;
   }
 
   equals(other: HarnessError): boolean {
@@ -81,7 +87,8 @@ export class HarnessError {
       fixExampleEqual &&
       this.suggestedSkill === other.suggestedSkill &&
       this.scaffoldCommand === other.scaffoldCommand &&
-      this.templatePath === other.templatePath
+      this.templatePath === other.templatePath &&
+      this.remediationType === other.remediationType
     );
   }
 
@@ -105,6 +112,21 @@ export class HarnessError {
     return this.templatePath !== null;
   }
 
+  /**
+   * WI-335: 実効修復方式。未分類は安全側の 'manual' 扱い（機械適用可能と過剰宣言しない）。
+   */
+  effectiveRemediationType(): RemediationType {
+    return this.remediationType ?? DEFAULT_REMEDIATION_TYPE;
+  }
+
+  /**
+   * WI-335: suggestion を機械適用すれば必ず解消すると宣言されたエラーか。
+   * true のエラーは remediation-round-trip テストで「案内 → 機械適用 → 再実行 → pass」が保証される。
+   */
+  isMechanicallyRemediable(): boolean {
+    return this.effectiveRemediationType() === "mechanical";
+  }
+
   toContract(): Readonly<HarnessErrorContract> {
     const contract: HarnessErrorContract = {
       code: this.code.toString(),
@@ -112,12 +134,11 @@ export class HarnessError {
       message: this.message,
       suggestion: this.suggestion,
       ...(this.adrRef !== null ? { adr_ref: this.adrRef.toString() } : {}),
-      ...(this.fixExample !== null
-        ? { fix_example: this.fixExample.toString() }
-        : {}),
+      ...(this.fixExample !== null ? { fix_example: this.fixExample.toString() } : {}),
       ...(this.suggestedSkill !== null ? { suggested_skill: this.suggestedSkill } : {}),
       ...(this.scaffoldCommand !== null ? { scaffold_command: this.scaffoldCommand } : {}),
       ...(this.templatePath !== null ? { template_path: this.templatePath } : {}),
+      ...(this.remediationType !== null ? { remediation_type: this.remediationType } : {}),
     };
     return Object.freeze(contract);
   }

package/scripts/harness/harness-error/domain/value-objects/remediation-type.ts

@@ -0,0 +1,30 @@
+/**
+ * @layer domain
+ * @unit harness-error
+ * @work-item-id WI-335
+ *
+ * RemediationType — suggested action（suggestion）の修復方式分類
+ *
+ * phasegate の中核価値は「エラー + 次の 1 手」でエージェントの自己修正を駆動することにある。
+ * この分類は「案内された 1 手が本当に従えば直るか」を機械保証するための宣言であり、
+ * mechanical と宣言されたエラーは往復テスト
+ * （scripts/harness/__tests__/integration/validator-system/remediation-round-trip.test.ts）
+ * で「エラー → suggestion を機械適用 → 再実行 → pass」が CI 保証される。
+ *
+ * - mechanical:  suggestion の操作を解釈なしで機械適用でき、適用すれば必ず解消する
+ *                （例: L2-002 の「// @unit を先頭コメントに追加」、
+ *                      L3-003 の「layers.L3.coverageThreshold を 0 に設定して opt-out」）
+ * - ai-assisted: 修復に AI/人間の判断・設計理解が必要（例: L4 系の design drift 解消）
+ * - manual:      人間の判断が必須（例: L3-001 秘密情報の無効化・ローテーション）。
+ *                未分類のエラーも安全側でこの扱いとする（default）
+ */
+export type RemediationType = "mechanical" | "ai-assisted" | "manual";
+
+/** 未分類エラーの既定値。機械適用可能と過剰宣言しない安全側の値。 */
+export const DEFAULT_REMEDIATION_TYPE: RemediationType = "manual";
+
+const VALID_REMEDIATION_TYPES: readonly RemediationType[] = Object.freeze(["mechanical", "ai-assisted", "manual"]);
+
+export function isRemediationType(value: unknown): value is RemediationType {
+  return typeof value === "string" && (VALID_REMEDIATION_TYPES as readonly string[]).includes(value);
+}

package/scripts/harness/harness-error/infrastructure/registry/l2-error-definitions.ts

@@ -2,64 +2,79 @@
  * @layer infrastructure
  * @unit harness-error
  */
-import { AdrRef } from '../../domain/value-objects/adr-ref.js';
-import { ErrorCode } from '../../domain/value-objects/error-code.js';
-import { ErrorDefinition } from '../../domain/value-objects/error-definition.js';
-import { FixExample } from '../../domain/value-objects/fix-example.js';
-import { Severity } from '../../domain/value-objects/severity.js';
+import { AdrRef } from "../../domain/value-objects/adr-ref.js";
+import { ErrorCode } from "../../domain/value-objects/error-code.js";
+import { ErrorDefinition } from "../../domain/value-objects/error-definition.js";
+import { FixExample } from "../../domain/value-objects/fix-example.js";
+import { Severity } from "../../domain/value-objects/severity.js";
 
 function createDefinition(input: {
   code: string;
   title: string;
-  category: 'phase_gate' | 'architecture' | 'dependency' | 'quality' | 'security' | 'performance' | 'consistency' | 'metadata';
+  category:
+    | "phase_gate"
+    | "architecture"
+    | "dependency"
+    | "quality"
+    | "security"
+    | "performance"
+    | "consistency"
+    | "metadata";
   ownerValidatorId: string;
   defaultFixExample: string;
   defaultSuggestedSkill?: string;
   defaultScaffoldCommand?: string;
   defaultTemplatePath?: string;
+  defaultRemediationType?: "mechanical" | "ai-assisted" | "manual";
 }): ErrorDefinition {
   return ErrorDefinition.create({
     code: ErrorCode.create(input.code),
     title: input.title,
     category: input.category,
-    defaultSeverity: Severity.create('error'),
+    defaultSeverity: Severity.create("error"),
     adrRefRequired: true,
-    defaultAdrRef: AdrRef.create('ADR-002'),
+    defaultAdrRef: AdrRef.create("ADR-002"),
     fixExampleRequired: true,
     defaultFixExample: FixExample.create(input.defaultFixExample),
     ownerValidatorId: input.ownerValidatorId,
     defaultSuggestedSkill: input.defaultSuggestedSkill ?? null,
     defaultScaffoldCommand: input.defaultScaffoldCommand ?? null,
     defaultTemplatePath: input.defaultTemplatePath ?? null,
+    defaultRemediationType: input.defaultRemediationType ?? null,
   });
 }
 
 export const L2_ERROR_DEFINITIONS = Object.freeze([
   createDefinition({
-    code: 'L2-001',
-    title: 'Phase Gate の前提条件に違反している',
-    category: 'phase_gate',
-    ownerValidatorId: 'phase-gate',
-    defaultFixExample:
-      "const requiredPlanPath = 'docs/inception/harness-error/it_test_logic_plan.md';",
-    defaultSuggestedSkill: '/story-implementor',
-    defaultScaffoldCommand: 'npx phasegate scaffold-design --unit <unit-id> --phase logical',
-    defaultTemplatePath: 'templates/logical_design.template.md',
+    code: "L2-001",
+    title: "Phase Gate の前提条件に違反している",
+    category: "phase_gate",
+    ownerValidatorId: "phase-gate",
+    defaultFixExample: "const requiredPlanPath = 'docs/inception/harness-error/it_test_logic_plan.md';",
+    defaultSuggestedSkill: "/story-implementor",
+    defaultScaffoldCommand: "npx phasegate scaffold-design --unit <unit-id> --phase logical",
+    // WI-356 (issue #29): 旧値 "templates/logical_design.template.md" は phasegate 本体の
+    // パッケージ内にしか存在せず、導入先 repo からは到達できない到達不能パスだった。
+    // hook の block メッセージでこのパスを案内された agent は必ず空振りする。
+    // 導入先 repo で実際に読める参照（skill 定義）を指す。skills/ が未配置の
+    // personal install 経路でも `npx phasegate skills info <name>` で stdout から読める。
+    defaultTemplatePath: "skills/logical-designer/SKILL.md",
   }),
   createDefinition({
-    code: 'L2-002',
-    title: 'メタデータが不足している',
-    category: 'metadata',
-    ownerValidatorId: 'metadata',
-    defaultFixExample:
-      '/**\n * @unit harness-error\n * @layer infrastructure\n */\nconst actual = true;',
+    code: "L2-002",
+    title: "メタデータが不足している",
+    category: "metadata",
+    ownerValidatorId: "metadata",
+    defaultFixExample: "/**\n * @unit harness-error\n * @layer infrastructure\n */\nconst actual = true;",
+    // WI-335: suggestion（// @unit / @layer を先頭コメントに追加）は解釈なしで機械適用可能。
+    // remediation-round-trip テストで「エラー → 機械適用 → 再実行 → pass」が CI 保証される。
+    defaultRemediationType: "mechanical",
   }),
   createDefinition({
-    code: 'L2-003',
-    title: 'テスト品質規約に違反している',
-    category: 'quality',
-    ownerValidatorId: 'test-quality',
-    defaultFixExample:
-      "const actual = sut.execute();\nexpect(actual).toBeDefined();",
+    code: "L2-003",
+    title: "テスト品質規約に違反している",
+    category: "quality",
+    ownerValidatorId: "test-quality",
+    defaultFixExample: "const actual = sut.execute();\nexpect(actual).toBeDefined();",
   }),
 ]);

package/scripts/harness/harness-error/infrastructure/registry/l3-error-definitions.ts

@@ -2,60 +2,77 @@
  * @layer infrastructure
  * @unit harness-error
  */
-import { AdrRef } from '../../domain/value-objects/adr-ref.js';
-import { ErrorCode } from '../../domain/value-objects/error-code.js';
-import { ErrorDefinition } from '../../domain/value-objects/error-definition.js';
-import { FixExample } from '../../domain/value-objects/fix-example.js';
-import { Severity } from '../../domain/value-objects/severity.js';
+import { AdrRef } from "../../domain/value-objects/adr-ref.js";
+import { ErrorCode } from "../../domain/value-objects/error-code.js";
+import { ErrorDefinition } from "../../domain/value-objects/error-definition.js";
+import { FixExample } from "../../domain/value-objects/fix-example.js";
+import { Severity } from "../../domain/value-objects/severity.js";
 
 function createDefinition(input: {
   code: string;
   title: string;
-  category: 'phase_gate' | 'architecture' | 'dependency' | 'quality' | 'security' | 'performance' | 'consistency' | 'metadata';
+  category:
+    | "phase_gate"
+    | "architecture"
+    | "dependency"
+    | "quality"
+    | "security"
+    | "performance"
+    | "consistency"
+    | "metadata";
   ownerValidatorId: string;
   defaultFixExample: string;
+  defaultRemediationType?: "mechanical" | "ai-assisted" | "manual";
 }): ErrorDefinition {
   return ErrorDefinition.create({
     code: ErrorCode.create(input.code),
     title: input.title,
     category: input.category,
-    defaultSeverity: Severity.create('error'),
+    defaultSeverity: Severity.create("error"),
     adrRefRequired: true,
-    defaultAdrRef: AdrRef.create('ADR-003'),
+    defaultAdrRef: AdrRef.create("ADR-003"),
     fixExampleRequired: true,
     defaultFixExample: FixExample.create(input.defaultFixExample),
     ownerValidatorId: input.ownerValidatorId,
+    defaultRemediationType: input.defaultRemediationType ?? null,
   });
 }
 
 export const L3_ERROR_DEFINITIONS = Object.freeze([
   createDefinition({
-    code: 'L3-001',
-    title: 'セキュリティ上の問題が検出された',
-    category: 'security',
-    ownerValidatorId: 'security',
+    code: "L3-001",
+    title: "セキュリティ上の問題が検出された",
+    category: "security",
+    ownerValidatorId: "security",
     defaultFixExample: "const token = process.env.API_TOKEN ?? '';",
+    // WI-335: 秘密情報の無効化・ローテーション・保管方式の選定は人間の判断が必須。
+    // 「機械適用すれば直る」とは宣言しない（過剰宣言の禁止）。
+    defaultRemediationType: "manual",
   }),
   createDefinition({
-    code: 'L3-002',
-    title: 'パフォーマンス上の問題が検出された',
-    category: 'performance',
-    ownerValidatorId: 'performance',
-    defaultFixExample:
-      'const actual = await Promise.all(tasks.map((task) => task()));',
+    code: "L3-002",
+    title: "パフォーマンス上の問題が検出された",
+    category: "performance",
+    ownerValidatorId: "performance",
+    defaultFixExample: "const actual = await Promise.all(tasks.map((task) => task()));",
   }),
   createDefinition({
-    code: 'L3-003',
-    title: 'カバレッジ閾値を下回っている',
-    category: 'quality',
-    ownerValidatorId: 'coverage',
-    defaultFixExample: 'const actualCoverage = 0.95;',
+    code: "L3-003",
+    title: "カバレッジ閾値を下回っている",
+    category: "quality",
+    ownerValidatorId: "coverage",
+    defaultFixExample: "const actualCoverage = 0.95;",
+    // WI-335: カバレッジゲートは config の layers.L3.coverageThreshold: 0 で機械的に opt-out
+    // できる正規経路を持つ（WI-317 / github#37）。remediation-round-trip テストで
+    // 「レポート不在エラー → suggestion の opt-out を機械適用 → 再実行 → SKIP（実効 pass）」を CI 保証。
+    // ※ 閾値未達そのもの（テスト追加が必要）を emit する側は ai-assisted を明示指定する。
+    defaultRemediationType: "mechanical",
   }),
   createDefinition({
-    code: 'L3-004',
-    title: '要件とテストのトレーサビリティが不足している',
-    category: 'consistency',
-    ownerValidatorId: 'nyquist',
+    code: "L3-004",
+    title: "要件とテストのトレーサビリティが不足している",
+    category: "consistency",
+    ownerValidatorId: "nyquist",
     defaultFixExample: 'const storyId = "H06-01";',
   }),
 ]);