phasegate 0.264.0 → 0.283.0

package/scripts/harness/main.ts

@@ -694,8 +694,8 @@ Options:
   --agent <claude|codex|both>     Agent context and hook targets (default: both)
   --skills <core|all>             Rendered agent context skill mode (default: all)
   --workflow <standard|strict>    Rendered agent context workflow mode (default: standard)
-  --with-husky                    Include Husky hook targets
-  --with-ci                       Include GitHub Actions target
+  --with-husky                    Include Husky hook targets (opt-in; omitted by default)
+  --with-ci                       Include GitHub Actions target (opt-in; omitted by default)
   --personal                      Use local-only install: no package.json, agent docs, Husky, CI, .gitignore, GitHub CLI, secrets, or CI setting writes.
                                   With --agent claude, initializes .phasegate-local config/settings/skills and ignored .claude shims.
   --json                          Output machine-readable JSON
@@ -1855,7 +1855,18 @@ function emitV2SchemaWarningOnce(sourcePath: string): void {
   );
 }
 
-async function loadResolvedConfig(): Promise<HarnessConfigV2 | undefined> {
+/**
+ * 不正 config でも fail-open（警告 + 既定設定で続行）にするコマンド。
+ * GitHub #40: config 検証の fail-closed が dispatch より上流にあると、pre-tool-use hook
+ * 経由で Write/Edit/Bash が全遮断され、config 自身を修復する経路が消える（自己修復
+ * デッドロック）。hook（エージェントのツール遮断点）と doctor（自己診断）は復旧経路
+ * として常に起動可能でなければならない。validate / ci-check 等の検査系コマンドは
+ * fail-closed を維持する（gated スコープへの書き込みは hook 内の phase-gate 判定が
+ * 引き続き fail-closed でブロックする）。
+ */
+const CONFIG_FAIL_OPEN_COMMANDS: ReadonlySet<string> = new Set(["hook", "doctor"]);
+
+async function loadResolvedConfig(command?: string): Promise<HarnessConfigV2 | undefined> {
   try {
     const configModule = createConfigFoundationModule();
     const result = await configModule.usecases.loadResolvedConfigUseCase.execute();
@@ -1866,6 +1877,15 @@ async function loadResolvedConfig(): Promise<HarnessConfigV2 | undefined> {
   } catch (error) {
     if (error instanceof ConfigValidationError) {
       process.stderr.write(`Invalid phasegate.config.json: ${error.message}\n`);
+      if (command !== undefined && CONFIG_FAIL_OPEN_COMMANDS.has(command)) {
+        process.stderr.write(
+          "Warning: continuing with default settings so diagnosis and self-repair stay possible. Fix the reported path in phasegate.config.json to restore full gating.\n",
+        );
+        return undefined;
+      }
+      process.stderr.write(
+        "Recovery: fix the reported path/type in phasegate.config.json (or restore it from version control). `phasegate doctor` and agent hooks remain available while the config is invalid.\n",
+      );
       process.exit(2);
     }
     if (error instanceof ConfigNotFoundError) {
@@ -1942,7 +1962,7 @@ async function main(): Promise<void> {
   const json = hasFlag(args, "--json");
 
   // Cross-unit wiring: 設定を先に解決し、各Unit に注入する
-  const resolvedConfig = command.startsWith("world:") ? undefined : await loadResolvedConfig();
+  const resolvedConfig = command.startsWith("world:") ? undefined : await loadResolvedConfig(command);
 
   try {
     switch (command) {
@@ -2346,8 +2366,8 @@ async function main(): Promise<void> {
           force: hasFlag(args, "--force"),
           includeClaude,
           includeCodex,
-          includeHusky: !personal,
-          includeCi: !personal,
+          includeHusky: !personal && hasFlag(args, "--with-husky"),
+          includeCi: !personal && hasFlag(args, "--with-ci"),
           skillSet: skillSetRaw,
           workflow: parseWorkflowMode(workflowRaw),
           agent,

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 {
@@ -186,7 +190,8 @@ export class RunL3ValidatorsUseCase {
                   code: "L3-003",
                   severity: "error",
                   message: `coverageThreshold=${threshold}% が設定されていますがカバレッジレポートが見つかりません（テストをカバレッジ付きで実行してください）`,
-                  suggestion: "vitest --coverage 等でカバレッジレポートを生成してから再実行してください",
+                  suggestion:
+                    '次のいずれかで解消してください: (a) テストをカバレッジ付きで実行してレポートを生成する（例: vitest --coverage）、(b) カバレッジゲートを opt-out するなら config の layers.L3.coverageThreshold を 0 に設定する、(c) 非 JS/TS プロジェクトなら project.languages を宣言する（例: ["python"]。L3-003 自体が unsupported-language SKIP になる）',
                 },
               ],
               0,
@@ -224,7 +229,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/infrastructure/adapters/harness-config-validator-config-adapter.ts

@@ -5,11 +5,15 @@
  * @work-item-id WI-212
  * @work-item-id WI-301
  * @work-item-id WI-302
+ * @work-item-id WI-319
+ * @work-item-id WI-328
  *
  * HarnessConfigValidatorConfigAdapter — ValidatorConfigPort実装
  * HarnessConfigV2からLayerConfig VOを構築する
  */
 
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { ValidatorConfigPort } from "../../domain/ports/validator-config-port.js";
 import { LayerConfig } from "../../domain/value-objects/layer-config.js";
 import { ValidatorId } from "../../domain/value-objects/validator-id.js";
@@ -38,11 +42,92 @@ export interface HarnessConfigV2Like {
   world?: { enabled?: boolean };
 }
 
+/**
+ * WI-319 (github#39): project.languages 未宣言時にファイルシステムから言語を検出するためのマーカー定義。
+ * typescript は package.json の存在自体を根拠にできない（phasegate 導入時に phasegate 用
+ * package.json が置かれるため）ので、この表には含めず hasTypescriptMarker() で個別判定する。
+ */
+const LANGUAGE_MARKER_FILES: ReadonlyArray<{ readonly language: string; readonly markers: readonly string[] }> = [
+  { language: "python", markers: ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt"] },
+  { language: "go", markers: ["go.mod"] },
+  { language: "rust", markers: ["Cargo.toml"] },
+  { language: "java", markers: ["pom.xml", "build.gradle", "build.gradle.kts"] },
+  { language: "ruby", markers: ["Gemfile"] },
+  { language: "php", markers: ["composer.json"] },
+];
+
+/** WI-328: 実効言語リストの出所。status 表示等で「なぜこの言語判定になったか」を示す。 */
+export type ProjectLanguageSource = "declared" | "detected" | "fallback";
+
+export interface ResolvedProjectLanguages {
+  readonly languages: readonly string[];
+  readonly source: ProjectLanguageSource;
+}
+
+/**
+ * WI-328 (github#39 残課題): 実効言語リストとその出所を解決する唯一の実装。
+ * getProjectLanguages()（WI-319 の検出ロジック）と phasegate:status の言語表示が
+ * 同じテーブル・同じ優先順位を共有するために export する。
+ *
+ * 優先順位:
+ * 1. declared — config の project.languages 宣言（従来どおり最優先）
+ * 2. detected — project root のマーカーファイルから検出（WI-319 / github#39）
+ * 3. fallback — 検出ゼロなら typescript フォールバック（純 JS リポジトリ等の挙動維持）
+ */
+export function resolveProjectLanguages(
+  declaredLanguages: readonly string[] | undefined,
+  rootDir: string,
+): ResolvedProjectLanguages {
+  if (declaredLanguages && declaredLanguages.length > 0) {
+    return { languages: [...declaredLanguages], source: "declared" };
+  }
+  const detected = detectLanguagesFromFilesystem(rootDir);
+  if (detected.length > 0) {
+    return { languages: detected, source: "detected" };
+  }
+  return { languages: ["typescript"], source: "fallback" };
+}
+
+function detectLanguagesFromFilesystem(rootDir: string): string[] {
+  const detected: string[] = [];
+  if (hasTypescriptMarker(rootDir)) detected.push("typescript");
+  for (const { language, markers } of LANGUAGE_MARKER_FILES) {
+    if (markers.some((marker) => existsSync(join(rootDir, marker)))) {
+      detected.push(language);
+    }
+  }
+  return detected;
+}
+
+/**
+ * typescript の根拠は tsconfig.json の存在、または package.json の
+ * dependencies / devDependencies に typescript があることのみ。
+ * package.json の存在自体は根拠にしない（phasegate 導入時に phasegate 用
+ * package.json が置かれるため、誤検出の原因になる）。
+ */
+function hasTypescriptMarker(rootDir: string): boolean {
+  if (existsSync(join(rootDir, "tsconfig.json"))) return true;
+  const packageJsonPath = join(rootDir, "package.json");
+  if (!existsSync(packageJsonPath)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    return parsed.dependencies?.typescript !== undefined || parsed.devDependencies?.typescript !== undefined;
+  } catch {
+    // parse 失敗は typescript 根拠なしとして扱う（throw しない）
+    return false;
+  }
+}
+
 export class HarnessConfigValidatorConfigAdapter implements ValidatorConfigPort {
   private readonly config: HarnessConfigV2Like;
+  private readonly rootDir: string;
 
-  constructor(config: HarnessConfigV2Like) {
+  constructor(config: HarnessConfigV2Like, rootDir: string = process.cwd()) {
     this.config = config;
+    this.rootDir = rootDir;
   }
 
   async getLayerConfig(layer: "L2" | "L3" | "L4"): Promise<LayerConfig> {
@@ -95,8 +180,9 @@ export class HarnessConfigValidatorConfigAdapter implements ValidatorConfigPort
   }
 
   async getProjectLanguages(): Promise<readonly string[]> {
-    const languages = this.config.project?.languages;
-    return languages && languages.length > 0 ? [...languages] : ["typescript"];
+    // WI-319 の宣言優先 → FS 検出 → typescript フォールバックの解決は
+    // resolveProjectLanguages() に一本化（WI-328 で status 表示と共有）。
+    return [...resolveProjectLanguages(this.config.project?.languages, this.rootDir).languages];
   }
 
   private normalizeValidatorId(idOrName: string): string {

package/scripts/harness/validator-system/infrastructure/adapters/nyquist-ac-coverage-policy-adapter.ts

@@ -18,18 +18,25 @@
  * （layers.L3.requirementMatrixPath）から供給される。未指定時は既定値
  * `.harness/requirement-test-matrix.json` を用いる。マトリクスが不在の場合は
  * fail-closed で「設定されているが不在」という実行可能なメッセージを返す。
+ *
+ * FRESH PROJECT SKIP (WI-324): 例外として「matrix 不在 かつ StoryCatalog の
+ * story がゼロ」の場合のみ skipped=true を返す。phasegate 導入直後（story 未作成・
+ * matrix 未生成）のオンボーディングを fail-closed で阻害しないため。story が
+ * 1件でも存在するのに matrix が不在なら「あるべき matrix が消えた事故」として
+ * 従来どおり fail-closed。story 数の取得自体に失敗した場合も判定不能として
+ * 保守的に fail-closed 側へ倒す。
  */
-import { access } from 'node:fs/promises';
-import { isAbsolute, join } from 'node:path';
-import type { AcCoveragePolicyPort } from '../../domain/ports/ac-coverage-policy-port.js';
-import type { HarnessErrorLike } from '../../domain/value-objects/validation-result.js';
+import { access } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import type { AcCoveragePolicyPort } from "../../domain/ports/ac-coverage-policy-port.js";
+import type { HarnessErrorLike } from "../../domain/value-objects/validation-result.js";
 
-const DEFAULT_MATRIX_PATH = '.harness/requirement-test-matrix.json';
+const DEFAULT_MATRIX_PATH = ".harness/requirement-test-matrix.json";
 
 function toL3004Error(message: string, suggestion: string): HarnessErrorLike {
   return {
-    code: { value: 'L3-004', toString: () => 'L3-004' },
-    severity: { value: 'error', toString: () => 'error' },
+    code: { value: "L3-004", toString: () => "L3-004" },
+    severity: { value: "error", toString: () => "error" },
     message,
     suggestion,
   };
@@ -39,21 +46,29 @@ export class NyquistAcCoveragePolicyAdapter implements AcCoveragePolicyPort {
   async checkCoverage(context: { matrixFilePath?: string }): Promise<{
     passed: boolean;
     errors: readonly HarnessErrorLike[];
+    skipped?: boolean;
+    skipReason?: string;
   }> {
     const rootDir = process.cwd();
     const relativeOrAbsolute =
-      context.matrixFilePath && context.matrixFilePath.length > 0
-        ? context.matrixFilePath
-        : DEFAULT_MATRIX_PATH;
-    const matrixFilePath = isAbsolute(relativeOrAbsolute)
-      ? relativeOrAbsolute
-      : join(rootDir, relativeOrAbsolute);
+      context.matrixFilePath && context.matrixFilePath.length > 0 ? context.matrixFilePath : DEFAULT_MATRIX_PATH;
+    const matrixFilePath = isAbsolute(relativeOrAbsolute) ? relativeOrAbsolute : join(rootDir, relativeOrAbsolute);
 
     // マトリクス不在は threshold-configured-but-absent と同様に fail-closed で
     // 明確なメッセージを返す（ENOENT の生メッセージで落とさない）。
+    // 例外（WI-324）: story がゼロのフレッシュプロジェクトのみ SKIP を返す。
     try {
       await access(matrixFilePath);
     } catch {
+      if (await this.hasZeroStories(rootDir)) {
+        return {
+          passed: true,
+          errors: [],
+          skipped: true,
+          skipReason:
+            "story 未作成のため L3-004 をスキップ（story 作成後に requirement-test-matrix を生成すると有効化されます）",
+        };
+      }
       return {
         passed: false,
         errors: [
@@ -69,7 +84,7 @@ export class NyquistAcCoveragePolicyAdapter implements AcCoveragePolicyPort {
       // 有効 storyId 一覧を traceability-model の StoryCatalog から取得する（REAL registry）
       const storyIds = await this.loadValidStoryIds(rootDir);
 
-      const { createNyquistValidationModule } = await import('../../../nyquist-validation/composition-root.js');
+      const { createNyquistValidationModule } = await import("../../../nyquist-validation/composition-root.js");
       const mod = createNyquistValidationModule({
         getStoryIds: async () => storyIds,
       });
@@ -79,9 +94,7 @@ export class NyquistAcCoveragePolicyAdapter implements AcCoveragePolicyPort {
 
       return {
         passed: output.passed,
-        errors: output.errors.map((err) =>
-          toL3004Error(err.message, ''),
-        ),
+        errors: output.errors.map((err) => toL3004Error(err.message, "")),
       };
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
@@ -91,19 +104,35 @@ export class NyquistAcCoveragePolicyAdapter implements AcCoveragePolicyPort {
         errors: [
           toL3004Error(
             `AC網羅ゲートの検査に失敗しました（fail-closed）: ${message}`,
-            'requirement-test-matrix.json の存在・形式・スキーマ整合性を確認してください',
+            "requirement-test-matrix.json の存在・形式・スキーマ整合性を確認してください",
           ),
         ],
       };
     }
   }
 
+  /**
+   * WI-324: 「story がゼロ」判定。StoryCatalog（traceability-model）の登録 story 数を
+   * シグナルとする。StoryCatalog は requirement-test-matrix の生成元と同じ
+   * user_stories.md を読むため、「matrix が本来存在しうるか」と一貫した判定になる。
+   * catalog 読み込み自体が失敗した場合（config 不正等）は判定不能として false を返し、
+   * 呼び出し側を保守的に fail-closed へ倒す。
+   */
+  private async hasZeroStories(rootDir: string): Promise<boolean> {
+    try {
+      const storyIds = await this.loadValidStoryIds(rootDir);
+      return storyIds.length === 0;
+    } catch {
+      return false;
+    }
+  }
+
   private async loadValidStoryIds(rootDir: string): Promise<readonly string[]> {
-    const { createConfigFoundationModule } = await import('../../../config-foundation/composition-root.js');
+    const { createConfigFoundationModule } = await import("../../../config-foundation/composition-root.js");
     const configModule = createConfigFoundationModule();
     const resolvedConfig = await configModule.usecases.loadResolvedConfigUseCase.execute();
 
-    const { createTraceabilityModelModule } = await import('../../../traceability-model/composition-root.js');
+    const { createTraceabilityModelModule } = await import("../../../traceability-model/composition-root.js");
     const traceModule = createTraceabilityModelModule(rootDir, {
       pathRoots: { designDocsRoot: resolvedConfig.config.paths.designDocs },
     });