phasegate 0.160.4 → 0.160.5

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.160.5] - 2026-05-14
+
+### Fixed
+
+- **WI-189 — umbrella CLI UX cleanup** — aligns `validate --format json` with the global JSON contract, makes `scaffold-design` default to dry-run with explicit `--apply`, fixes bypass audit empty-range wording, and synchronizes public help for scaffold, quick-mode, and delegate commands.
+
 ## [0.160.4] - 2026-05-14
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.160.4",
+  "version": "0.160.5",
   "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/ci-governance/application/dto/scaffold-design-input.ts

@@ -1,8 +1,10 @@
 // @unit ci-governance
 // @layer application
+// @work-item-id WI-189
 
 export interface ScaffoldDesignInput {
   readonly unit: string;
   readonly phase: string;
+  readonly dryRun?: boolean;
   readonly force?: boolean;
 }

package/scripts/harness/ci-governance/application/dto/scaffold-design-output.ts

@@ -1,11 +1,13 @@
 // @unit ci-governance
 // @layer application
+// @work-item-id WI-189
 
 export interface ScaffoldDesignOutput {
   readonly targetPath: string;
   readonly templatePath: string;
   readonly unit: string;
   readonly phase: string;
+  readonly dryRun: boolean;
   readonly written: boolean;
   readonly alreadyExists: boolean;
   readonly overwritten: boolean;

package/scripts/harness/ci-governance/application/usecases/scaffold-design-usecase.ts

@@ -1,5 +1,6 @@
 // @unit ci-governance
 // @layer application
+// @work-item-id WI-189
 
 import { DesignPhase } from '../../domain/value-objects/design-phase.js';
 import type { TemplateRepositoryPort } from '../../domain/ports/template-repository-port.js';
@@ -21,18 +22,33 @@ export class ScaffoldDesignUseCase {
     }
     const phase = DesignPhase.create(input.phase);
     const unit = input.unit.trim();
+    const dryRun = input.dryRun === true;
     const force = input.force === true;
 
     const templatePath = this.templates.resolvePath(phase);
     const targetPath = this.writer.resolvePath(unit, phase);
     const alreadyExists = await this.writer.exists(unit, phase);
 
+    if (dryRun) {
+      return {
+        targetPath,
+        templatePath,
+        unit,
+        phase: phase.value,
+        dryRun: true,
+        written: false,
+        alreadyExists,
+        overwritten: false,
+      };
+    }
+
     if (alreadyExists && !force) {
       return {
         targetPath,
         templatePath,
         unit,
         phase: phase.value,
+        dryRun: false,
         written: false,
         alreadyExists: true,
         overwritten: false,
@@ -48,6 +64,7 @@ export class ScaffoldDesignUseCase {
       templatePath,
       unit,
       phase: phase.value,
+      dryRun: false,
       written: true,
       alreadyExists,
       overwritten: alreadyExists && force,

package/scripts/harness/ci-governance/presentation/handlers/scaffold-design-handler.ts

@@ -1,5 +1,6 @@
 // @unit ci-governance
 // @layer presentation
+// @work-item-id WI-189
 
 import { DesignPhase } from '../../domain/value-objects/design-phase.js';
 import type { ScaffoldDesignUseCase } from '../../application/usecases/scaffold-design-usecase.js';
@@ -7,6 +8,8 @@ import type { ScaffoldDesignUseCase } from '../../application/usecases/scaffold-
 export interface ScaffoldDesignHandlerArgs {
   readonly unit?: string;
   readonly phase?: string;
+  readonly dryRun?: boolean;
+  readonly apply?: boolean;
   readonly force?: boolean;
   readonly format?: 'human' | 'json';
 }
@@ -21,6 +24,12 @@ export class ScaffoldDesignHandler {
 
   async handle(args: ScaffoldDesignHandlerArgs): Promise<ScaffoldDesignHandlerResult> {
     const format = args.format ?? 'human';
+    const apply = args.apply === true;
+    const dryRun = args.dryRun === true || !apply;
+
+    if (args.dryRun === true && apply) {
+      return this.fail(format, '--dry-run と --apply は同時に指定できません', 2);
+    }
 
     if (!args.unit || args.unit.trim().length === 0) {
       return this.fail(format, '--unit <unit-id> は必須です', 2);
@@ -45,6 +54,7 @@ export class ScaffoldDesignHandler {
       result = await this.useCase.execute({
         unit: args.unit,
         phase: args.phase,
+        dryRun,
         force: args.force,
       });
     } catch (err) {
@@ -61,10 +71,22 @@ export class ScaffoldDesignHandler {
 
     if (result.alreadyExists && !result.written) {
       return {
-        exitCode: 2,
+        exitCode: result.dryRun ? 0 : 2,
+        output: [
+          result.dryRun ? `dry-run: 既に存在します: ${result.targetPath}` : `既に存在します: ${result.targetPath}`,
+          result.dryRun ? '書き込むには --apply を指定してください。' : '上書きするには --force を指定してください。',
+        ].join('\n'),
+      };
+    }
+
+    if (result.dryRun) {
+      return {
+        exitCode: 0,
         output: [
-          `既に存在します: ${result.targetPath}`,
-          '上書きするには --force を指定してください。',
+          `dry-run: 設計文書を生成予定: ${result.targetPath}`,
+          `テンプレ: ${result.templatePath}`,
+          `Unit: ${result.unit} / phase: ${result.phase}`,
+          '書き込むには --apply を指定してください。',
         ].join('\n'),
       };
     }

package/scripts/harness/integrations/pre-commit.ts

@@ -3,6 +3,7 @@
  * @layer presentation
  * @work-item-id WI-141
  * @work-item-id WI-109
+ * @work-item-id WI-189
  *
  * Pre-commit CLI entry.
  * Runs L2 validators against staged TypeScript files AND design-document
@@ -533,6 +534,11 @@ function hasCompleteBypassTrailerSet(results: readonly BypassTrailerValidationRe
   return results.some((result) => result.hasAnyBypassTrailer && result.complete);
 }
 
+function toBypassAuditStdout(stdout: string, changedFiles: readonly string[]): string {
+  if (changedFiles.length > 0) return stdout;
+  return stdout.replace("No staged files to check. Skipping.", "No changed files in range to check. Skipping.");
+}
+
 export async function runBypassAudit(
   deps: PreCommitDeps,
   options: BypassAuditOptions = {},
@@ -554,7 +560,7 @@ export async function runBypassAudit(
 
   const sections = [
     `${BOLD}[phasegate]${RESET} Bypass audit (${baseRef}..${headRef})`,
-    result.stdout,
+    toBypassAuditStdout(result.stdout, changedFiles),
   ];
   let exitCode = result.exitCode;
   if (result.exitCode !== 0 && !hasCompleteBypassTrailerSet(bypassResults)) {

package/scripts/harness/main.ts

@@ -7,6 +7,7 @@
  * @work-item-id WI-175
  * @work-item-id WI-176
  * @work-item-id WI-184
+ * @work-item-id WI-189
  *
  * Phasegate CLI エントリポイント。
  * 各Unitの Composition Root からハンドラーを取得し、コマンドに応じてディスパッチする。
@@ -156,7 +157,8 @@ Setup:
                                 --with-husky, --with-ci, --yes)
   update-skills                Alias for reconcile (kept for compatibility)
   doctor                       Diagnose silent installation failures (--json, --strict, --agent <claude|codex|both>, --report-out <path>)
-  scaffold-wi <unit> <type>    Create docs/inception/{unit}/WI-XXX/description.md
+  scaffold-wi <unit|_cross> <story|issue|chore>
+                               Create docs/inception/{unit}/WI-XXX/description.md
   emit-agent-rules             Print AGENTS.md / CLAUDE.md WI workflow rules block
   install                      Install phasegate managed files (--dry-run|--apply, --force)
   uninstall                    Uninstall phasegate managed files (--dry-run|--apply, --force)
@@ -183,8 +185,9 @@ Commands:
 
   lint                         Run lint checks (--json, --target <path>)
 
-  validate                     Run validators (--layer L2|L3|L4|all; L0 prints runtime hook info, --unit, --format human|agent|ci)
+  validate                     Run validators (--layer L2|L3|L4|all; L0 prints runtime hook info, --unit, --format human|agent|ci|json, --json)
   ci-check                     CI check (--quick for quick mode, --fail-on-reject, --dry-run, --files)
+  check-change-category        Classify changed paths for quick mode (--paths <csv>, --format human|json)
 
   phasegate:check-ready         Check ready status (--json)
   phasegate:check-phase         Check phase gate (--unit <unitId>, --json)
@@ -211,7 +214,7 @@ Gate semantics:
   config:plan                  Plan safe config changes (--intent <l4-strict|codex-hooks|ci-fail-on-warning|baseline-reset|quick-mode-strict>, --dry-run, --json)
   ci:check-repetition          Check error repetition (--code <errorCode>, --reset, --json)
   baseline                     Create retrofit baseline snapshot (--dry-run, --force, --paths <glob,glob,...>, --json)
-  scaffold-design              Scaffold a design doc (--unit <id>, --phase <logical|domain|uiux|unit-test|it-test>, --force, --json)
+  scaffold-design              Scaffold a design doc (--unit <id>, --phase <logical|domain|uiux|unit-test|it-test>, --dry-run|--apply, --force, --json)
 
   skill:execute-tdd-cycle      Execute TDD cycle (--unit, --story, --desc, --phase RED|GREEN|REFACTOR, --passed)
   skill:check-coverage         Check coverage (--story <storyId>, --json)
@@ -409,7 +412,8 @@ function parseValidateFormat(args: readonly string[]): "human" | "agent" | "ci"
   const raw = parseFlag(args, "--format");
   if (raw === undefined) return undefined;
   if (raw === "human" || raw === "agent" || raw === "ci") return raw;
-  throw new Error(`Invalid --format value for validate: '${raw}'. Supported values: human, agent, ci.`);
+  if (raw === "json") return "ci";
+  throw new Error(`Invalid --format value for validate: '${raw}'. Supported values: human, agent, ci, json.`);
 }
 
 function levenshtein(a: string, b: string): number {
@@ -546,7 +550,8 @@ Run validators against the project. Without --layer, runs all enabled validator
 
 Options:
   --layer <L0|L2|L3|L4>           Run only the specified validator layer; L0 prints runtime hook info
-  --json                          Output machine-readable JSON
+  --format <human|agent|ci|json>  Output format; json is an alias for ci JSON
+  --json                          Output machine-readable JSON when --format is omitted
   --help, -h                      Show this help`,
   lint: `Usage: phasegate lint [options]
 
@@ -626,6 +631,28 @@ Options:
 Examples:
   phasegate check-change-category --paths src/foo.ts,src/bar.ts
   phasegate check-change-category --paths src/foo.ts --format json`,
+  "scaffold-wi": `Usage: phasegate scaffold-wi <unit|_cross> <story|issue|chore>
+
+Create docs/inception/{unit}/WI-XXX/description.md.
+
+Arguments:
+  <unit|_cross>              Unit id or _cross for cross-cutting work items.
+  <story|issue|chore>        Work item type.
+
+Options:
+  --help, -h                 Show this help`,
+  "scaffold-design": `Usage: phasegate scaffold-design --unit <id> --phase <phase> [options]
+
+Scaffold a product construction design document.
+
+Options:
+  --unit <id>                Unit id under docs/product/construction.
+  --phase <phase>            logical, domain, uiux, unit-test, or it-test.
+  --dry-run                  Preview target and template without writing (default).
+  --apply                    Write the scaffold.
+  --force                    Overwrite an existing target when applying.
+  --json                     Output machine-readable JSON.
+  --help, -h                 Show this help`,
   "ci:generate-template": `Usage: phasegate ci:generate-template [options]
 
 Generates a CI template configuration.
@@ -643,6 +670,15 @@ Options:
 Examples:
   phasegate ci:generate-template --type aidlc-gate
   phasegate ci:generate-template --preset strict --type pre-commit --render`,
+  "delegate-sonnet": `Usage: phasegate delegate-sonnet [...args]
+
+Delegate a task to Sonnet 4.6 by forwarding all args to scripts/delegate-sonnet.sh.
+
+Arguments:
+  [...args]                  Task text and options consumed by the delegate script.
+
+Options:
+  --help, -h                 Show this help`,
 };
 
 function printSubcommandHelp(command: string): void {
@@ -2191,7 +2227,7 @@ async function main(): Promise<void> {
         const layer = parseFlag(args, "--layer") as "L0" | "L2" | "L3" | "L4" | "all" | undefined;
         const unit = parseFlag(args, "--unit");
         const phase = parseFlag(args, "--phase");
-        const format = parseValidateFormat(args);
+        const format = parseValidateFormat(args) ?? (json ? "ci" : undefined);
         // WI-094 / ADR-017: --fail-on-warning / --no-fail-on-warning / 未指定→config値
         const failOnWarning = parseTriStateFlag(args, "--fail-on-warning", "--no-fail-on-warning");
         const noL4 = hasFlag(args, "--no-l4");
@@ -2206,7 +2242,7 @@ async function main(): Promise<void> {
           targetPaths,
         });
         console.log(result.output);
-        if (layer === "L2" || layer === "all") {
+        if ((layer === "L2" || layer === "all") && format !== "ci") {
           await printStoryReflectionValidationSummary(rootDir, unit);
         }
         process.exit(result.exitCode);
@@ -2492,11 +2528,15 @@ Examples:
         const mod = buildCiGovernance(rootDir, harnessRoot);
         const unit = parseFlag(args, "--unit") ?? "";
         const phase = parseFlag(args, "--phase") ?? "";
+        const dryRun = hasFlag(args, "--dry-run");
+        const apply = hasFlag(args, "--apply");
         const force = hasFlag(args, "--force");
         const format = json ? "json" : "human";
         const result = await mod.scaffoldDesignHandler.handle({
           unit,
           phase,
+          dryRun,
+          apply,
           force,
           format,
         });