phasegate 0.125.0 → 0.127.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.127.0] - 2026-05-08
+
+### Fixed
+
+- **WI-091 — `layers.L4.enabled: false` 無視 / `--help` がサブコマンドで no-op / drift-detect が括弧 qualifier で破綻する 3 件を解消 (GitHub Issue #4)** — 外部レポーター nakataj-mti が pnpm monorepo 環境 (defense `standard` / architecture `clean`) で報告した 5 件の bug+DX gap (`L4.enabled` 無視 / warning でも overall FAIL / `--help` 副作用走行 / `paths` 設定が L2-001 に未配線 / drift element の括弧 qualifier 破綻) のうち、リスクの低い 3 件 (#1, #3, #5 immediate) を本リリースで先行修正。残る #2 (severity 集計セマンティクス) と #4 (paths threading 完成) は後続 WI に切り出す方針 (本 description の `スコープ外` 参照)。
+  - **finding #1 — L4 enabled gate 追加 (`run-l4-validators-usecase.ts`)**: L3 (`run-l3-validators-usecase.ts:74-78`) と対称な `if (!layerConfig.enabled) return [];` ガードを `getLayerConfig` 直後に追加。`layers.L4.enabled: false` 設定で drift / consistency / dead-code service が呼ばれず、空配列を返すことで集計層で SKIP として表示される。dogfood 再現済 (`/tmp/phasegate-dogfood-wi091`, phasegate@0.126.0)。整合性テスト 2 ケース (`IT-UC-RunL4-007/008`) 追加。
+  - **finding #3 — `--help` / `-h` を全 subcommand に pre-dispatch で集約 (`main.ts`)**: 51 個の subcommand のうち 3 個のみが inline `--help` を持っており、残り ~48 個は silent ignore で `update-skills --help` → 8 skills 再 deploy / `phasegate:detect-drift --help` → drift 実 run / `validate --help` → phase gate 実走 という副作用走行を起こしていた。`main()` 内に `SUBCOMMAND_HELP` table (13 entry) と `printSubcommandHelp` helper を追加し、`switch(command)` の手前で `hasFlag(args, "--help") || hasFlag(args, "-h")` を最優先で解釈 → usage 出力 + exit 0。table 未登録の subcommand は `Usage: phasegate <cmd> [options]\n(use 'phasegate --help' for the full command reference)` の generic fallback で exit 0。dogfood 再現済 3 ケースが本 fix で停止することを spawn 経由 5 ケース (副作用ナシ確認込み) で検証。
+  - **finding #5 immediate — drift-detect の design heading から括弧 qualifier を normalize (`markdown-design-document-adapter.ts`)**: `extractConceptNames` が markdown heading から `（〜）` / `(〜)` qualifier (例: `（エンティティ・新規）`, `(legacy)`) を strip しないため code 側 class 名と exact match できず false-positive drift を出していた問題を解消。半角・全角括弧両対応、global flag で連続 / 複数 qualifier (`Foo（A）（B）` → `Foo`) も処理、strip 後 0 文字になる病的 heading は concepts に含めない。source code 側 (`biome-ast-source-code-analyzer-adapter.ts`) は AST node name から識別子のみ取得 (括弧含まず) のため design 側 normalize で十分。整合性テスト 4 ケース (`IT-REPO-DesignDoc-007〜010`) 追加。`pointers:` block 仕様による element → file path 明示は別 WI に切り出し。
+  - **既存 inline `--help` 処理は残置**: `main.ts` の 3 箇所 (line 982 / 1028 / 1112) は pre-dispatch で hit する関係で dead code 化するが本 commit では削除せず (テスト互換性確保のため)。clean-up は別 commit で漸進可。
+  - **テスト**: 全 3514 テスト (前回 3510 + 新規 11: finding #1 で 2 + finding #3 で 5 + finding #5 で 4) グリーン。L1 lint 違反なし。
+  - **スコープ外 (別 WI 起票予定)**: finding #2 (warning-severity でも overall FAIL の集計セマンティクス) は ADR レベルの後方互換戦略判断が必要なため story-implementor 案件として分離。finding #4 (`paths.designDocs` を L2-001 へ完全 threading) は WI-085 で `inceptionDocs` 側のみ通った threading 漏れの補完で phase-nodes 3 ファイル + traceability-model 2 ファイルの placeholder 化を伴う story-implementor 案件として分離。
+
+## [0.126.0] - 2026-05-08
+
+### Fixed
+
+- **WI-090 — `phasegate init` が unknown flag を silent ignore する問題を解消** — 例えば `phasegate init --skill-set core` (typo: 正しくは `--skills core`) を実行すると、従来は `--skill-set` 値が無視されて default の `all` で deploy されていた。本リリースで unknown flag を **exit 2 + suggestion** として error 化。
+  - **新規ヘルパー**: `scripts/harness/main.ts` に `validateKnownFlags` / `findClosestFlag` / `levenshtein` の 3 関数を inline 追加 (presentation layer の zero-dep CLI parser に組み込み、commander/yargs などの外部依存は追加しない方針を維持)。
+  - **挙動**: `init` 冒頭で `KNOWN_INIT_FLAGS = ["--name", "--preset", "--skills", "--agent", "--with-husky", "--yes"]` と照合し、未知の `--xxx` または `--xxx=value` を検出すると Levenshtein 距離 ≤ 4 の closest flag を `Did you mean '...'?` で提示、該当無しなら known flags の列挙を提示して exit 2。
+  - **互換性**: 既存の正しい flag 利用 (`--skills core` / `--name foo` 等) には一切影響しない。`--yes` は既存 user の script 互換のため known flag として受理 (no-op)。
+  - **help line 修正**: `main.ts` の `printUsage()` で表示される `init` 説明行に `--skills <core|all>` と `--yes` を追記 (従来 `--skills` が help から欠落していた)。
+  - **テスト追加**: 4 integration ケース (`scripts/harness/__tests__/integration/harness-api/init-flag-validation.integration.test.ts`):
+    - `--skill-set core` typo は `Did you mean '--skills'?` を出して exit 2
+    - `--skill-set=core` (=value 形式の typo) も同様に検出
+    - `--xyz-totally-unknown` は known flags の列挙を出して exit 2
+    - 正しい組み合わせ `--name foo --skills all --agent claude --yes` は flag validation で reject されない
+  - 全 3503 テスト (前回 3499 + 新規 4) グリーン、L1 lint 違反なし。
+  - **スコープ外**: 他 subcommand (update-skills / migrate / lint / validate / etc.) への validateKnownFlags 展開は段階適用のため別 WI。`--help` per subcommand 実装も別 WI。
+
 ## [0.125.0] - 2026-05-08
 
 ### Changed

package/package.json

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

package/scripts/harness/main.ts

@@ -81,7 +81,8 @@ Usage: phasegate <command> [options]
 
 Setup:
   init                         Initialize project: deploy skills + design docs + phasegate.config.json
-                               (--name <project-name>, --preset <full|standard|minimal|custom>, --agent <claude|codex|both>, --with-husky)
+                               (--name <project-name>, --preset <full|standard|minimal|custom>,
+                                --skills <core|all>, --agent <claude|codex|both>, --with-husky, --yes)
   update-skills                Re-deploy skills from current harness version
 
 Commands:
@@ -166,6 +167,180 @@ function hasFlag(args: readonly string[], flag: string): boolean {
   return args.includes(flag);
 }
 
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+    }
+  }
+  return dp[m][n];
+}
+
+function findClosestFlag(input: string, known: readonly string[]): string | undefined {
+  let best: string | undefined;
+  let bestDist = Number.POSITIVE_INFINITY;
+  for (const flag of known) {
+    const dist = levenshtein(input, flag);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = flag;
+    }
+  }
+  return bestDist <= 4 ? best : undefined;
+}
+
+function validateKnownFlags(args: readonly string[], known: readonly string[]): string | null {
+  const knownSet = new Set(known);
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) {
+      i++;
+      continue;
+    }
+    const flagName = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+    if (knownSet.has(flagName)) {
+      i++;
+      continue;
+    }
+    const suggestion = findClosestFlag(flagName, known);
+    return suggestion
+      ? `Error: unknown flag '${flagName}'. Did you mean '${suggestion}'?`
+      : `Error: unknown flag '${flagName}'. Known flags: ${known.join(", ")}`;
+  }
+  return null;
+}
+
+const SUBCOMMAND_HELP: Record<string, string> = {
+  init: `Usage: phasegate init [options]
+
+Initialize phasegate in the current project: deploy skills + design docs + phasegate.config.json.
+
+Options:
+  --name <project-name>           Project name (default: "my-project")
+  --preset <full|standard|minimal|custom>   Phase dependency preset (default: "standard")
+  --skills <core|all>             Skill set to deploy (default: "all")
+  --agent <claude|codex|both>     Agent integration target (default: "claude")
+  --with-husky                    Install Husky pre-commit hooks
+  --yes                           Skip confirmation prompts
+  --help, -h                      Show this help`,
+  "update-skills": `Usage: phasegate update-skills [options]
+
+Redeploy skills in .claude/skills/ from the installed phasegate version. WARNING: overwrites existing skill files.
+
+Options:
+  --skills <core|all>             Skill set to deploy
+  --agent <claude|codex|both>     Agent integration target
+  --help, -h                      Show this help`,
+  validate: `Usage: phasegate validate [options]
+
+Run validators against the project. Without --layer, runs all enabled layers (L0/L2/L3/L4).
+
+Options:
+  --layer <L0|L2|L3|L4>           Run only the specified layer
+  --json                          Output machine-readable JSON
+  --help, -h                      Show this help`,
+  lint: `Usage: phasegate lint [options]
+
+Run L1 Biome AST checks across the project.
+
+Options:
+  --json                          Output machine-readable JSON
+  --help, -h                      Show this help`,
+  migrate: `Usage: phasegate migrate [options]
+
+Migrate phasegate.config.json from older schema versions. Backs up the original to phasegate.config.json.bak.
+
+Options:
+  --dry-run                       Preview changes without writing
+  --help, -h                      Show this help`,
+  "list-errors": `Usage: phasegate list-errors [options]
+
+List validator error catalog entries.
+
+Options:
+  --layer <L0|L1|L2|L3|L4>        Filter by layer
+  --format <table|json>           Output format (default: "table")
+  --help, -h                      Show this help`,
+  "phasegate:status": `Usage: phasegate phasegate:status
+
+Display harness status (enabled validators, schema version, hook deployment).`,
+  "phasegate:detect-drift": `Usage: phasegate phasegate:detect-drift [options]
+
+Run L4-001 drift detection between design documents and source code. WARNING: scans the project filesystem.
+
+Options:
+  --json                          Output machine-readable JSON (default for this command)
+  --help, -h                      Show this help`,
+  "phasegate:check-ready": `Usage: phasegate phasegate:check-ready
+
+Check whether the harness is ready (config valid, hooks deployed).`,
+  "phasegate:complete-check": `Usage: phasegate phasegate:complete-check
+
+Run completion check (used by Stop hook). Validates phase-gate, metadata, and test-quality.`,
+  "phasegate:check-phase": `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, -h        Show this help.
+
+Examples:
+  phasegate phasegate:check-phase --unit harness-api
+  phasegate phasegate:check-phase harness-api --json`,
+  "check-change-category": `Usage: phasegate check-change-category --paths <csv> [options]
+
+Classify changed file paths into quick-mode categories and report
+whether Full Mode is required.
+
+Options:
+  --paths <csv>              Comma-separated file paths to classify.
+  --format <human|json>      Output format. Default: human.
+  --fail-on-full-required    Exit with code 1 when Full Mode is required.
+  --help, -h                 Show this help.
+
+Examples:
+  phasegate check-change-category --paths src/foo.ts,src/bar.ts
+  phasegate check-change-category --paths src/foo.ts --format json`,
+  "ci:generate-template": `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`,
+};
+
+function printSubcommandHelp(command: string): void {
+  const help = SUBCOMMAND_HELP[command];
+  if (help) {
+    console.log(help);
+  } else {
+    console.log(`Usage: phasegate ${command} [options]`);
+    console.log("(use 'phasegate --help' for the full command reference)");
+  }
+}
+
 /** フラグとその値を除いた位置引数のみを返す */
 function parsePositionalArgs(args: readonly string[], flagsWithValues: readonly string[] = []): string[] {
   const result: string[] = [];
@@ -425,6 +600,12 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
+  // Pre-dispatch: 全 subcommand で --help / -h を最優先で解釈し usage 出力 (副作用走行を防ぐ — WI-091 finding #3)
+  if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
+    printSubcommandHelp(command);
+    process.exit(0);
+  }
+
   const json = hasFlag(args, "--json");
 
   // Cross-unit wiring: 設定を先に解決し、各Unit に注入する
@@ -434,6 +615,12 @@ async function main(): Promise<void> {
     switch (command) {
       // ── harness setup ──
       case "init": {
+        const KNOWN_INIT_FLAGS = ["--name", "--preset", "--skills", "--agent", "--with-husky", "--yes"];
+        const flagError = validateKnownFlags(args, KNOWN_INIT_FLAGS);
+        if (flagError) {
+          console.error(flagError);
+          process.exit(2);
+        }
         const projectName = parseFlag(args, "--name") ?? "my-project";
         const rawPhasePreset = parseFlag(args, "--preset");
         if (

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

@@ -69,6 +69,10 @@ export class RunL4ValidatorsUseCase {
       throw new ValidatorExecutionError(`Failed to get L4 LayerConfig: ${err instanceof Error ? err.message : String(err)}`, err);
     }
 
+    if (!layerConfig.enabled) {
+      return [];
+    }
+
     const results = this.executionService.execute(definitions, [layerConfig]);
     const overrideMap = new Map<string, ValidationResult>(results.map((result) => [result.validatorId.value, result]));
 

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

@@ -52,7 +52,15 @@ function extractConceptNames(markdown: string): string[] {
     // 既知のメタ見出しは暗黙的にスキップ
     if (isMetaHeading(name)) continue;
     // 名前から末尾のスキップマーカーを落とす (念のため)
-    headings.push(name.replace(SKIP_MARKER, '').trim());
+    // WI-091 finding #5: `（〜）` / `(〜)` qualifier (例: `（エンティティ・新規）`) を strip
+    // して code 側の class 名と exact match できるようにする
+    const stripped = name
+      .replace(SKIP_MARKER, '')
+      .replace(/[（(][^）)]*[）)]/g, '')
+      .trim();
+    if (stripped.length > 0) {
+      headings.push(stripped);
+    }
   }
   return headings;
 }