phasegate 0.160.7 → 0.160.9

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.160.9] - 2026-05-15
+
+### Fixed
+
+- **WI-201 — config plan apply discoverability** — documents `config:plan --apply` in subcommand help, top-level help, and CLI reference so agents can discover the managed config apply path from `--help`.
+
+## [0.160.8] - 2026-05-15
+
+### Fixed
+
+- **WI-201 — managed config plan apply path** — adds `config:plan --apply` for applicable config patch plans, records rollback backups before mutating `phasegate.config.json`, advertises managed apply commands in config-plan guidance, and points config edit blocks back to the reviewed dry-run/apply workflow.
+
 ## [0.160.6] - 2026-05-14
 
 ### Fixed

package/docs/guide/cli-reference.md

@@ -28,7 +28,7 @@ Command names in this document are split into three surfaces:
 | `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json`; `--force` handles managed conflict cases. |
 | `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to current package templates and refresh manifest hashes; `--force` allows managed-file replacement with backup. |
 | `setup:agent` | Agent-readable setup planner and optional apply path. Options: `--intent <minimal\|recommended\|strict\|ci-only\|agent-hooks\|retrofit>`, `--agent <claude\|codex\|both>`, `--workflow <standard\|strict>`, `--with-husky`, `--with-ci`, `--dry-run`, `--apply`, `--json`. <!-- @work-item-id WI-172 --> |
-| `config:plan` | Agent-readable configuration change planner. Options: `--intent <l4-strict\|codex-hooks\|ci-fail-on-warning\|baseline-reset\|quick-mode-strict>`, `--dry-run`, `--json`. <!-- @work-item-id WI-173 --> |
+| `config:plan` | Agent-readable configuration change planner. Options: `--intent <l4-strict\|codex-hooks\|ci-fail-on-warning\|baseline-reset\|quick-mode-strict\|retrofit-bootstrap\|planning-mode-relax>`, `--dry-run`, `--apply`, `--json`. <!-- @work-item-id WI-173 --> <!-- @work-item-id WI-201 --> |
 | `update-skills` | Compatibility alias for `reconcile`; use `reconcile` for new automation. |
 | `scaffold-wi <unit> <type>` | Create `docs/inception/{unit}/WI-XXX/description.md` using the next free WI number. |
 | `emit-agent-rules` | Print the AGENTS.md / CLAUDE.md WI workflow rules block. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.160.7",
+  "version": "0.160.9",
   "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/agent-integration/application/usecases/handle-pre-tool-use-usecase.ts

@@ -2,6 +2,7 @@
  * @layer application
  * @unit agent-integration
  * @story H11-02
+ * @work-item-id WI-201
  *
  * HandlePreToolUseUseCase
  * PreToolUse Hook処理のオーケストレーション
@@ -237,6 +238,31 @@ export class HandlePreToolUseUseCase {
     unitId: string | undefined,
   ): HandlePreToolUseOutput {
     const fp = blockedFilePath ?? "不明なファイル";
+    if (result.dominantCategory === "config" && /(?:^|\/)phasegate\.config\.json$/.test(fp)) {
+      const dryRunCommand = "phasegate config:plan --intent retrofit-bootstrap --dry-run --json";
+      const applyCommand = "phasegate config:plan --intent retrofit-bootstrap --apply --json";
+      const lines = [
+        `Full mode 必須変更が検出されました: ${fp}`,
+        "カテゴリ: config",
+      ];
+      if (result.rejectionRule) {
+        lines.push(`判定ルール: ${result.rejectionRule}`);
+      }
+      if (result.rejectionReason) {
+        lines.push(`理由: ${result.rejectionReason}`);
+      }
+      lines.push(`次のアクション: ${dryRunCommand} で差分を確認し、承認後に ${applyCommand} を実行してください。`);
+
+      return {
+        shouldBlock: true,
+        blockedFilePath,
+        blockReason: "FULL_MODE_REQUIRED",
+        error: { message: lines.join("\n") },
+        fullModeRejectionRule: result.rejectionRule,
+        fullModeDominantCategory: result.dominantCategory,
+        nextAction: `${dryRunCommand} && ${applyCommand}`,
+      };
+    }
     const lines: string[] = [`Full mode 必須変更が検出されました: ${fp}`];
     if (result.dominantCategory) {
       lines.push(`カテゴリ: ${result.dominantCategory}`);
@@ -373,6 +399,11 @@ export class HandlePreToolUseUseCase {
       message: (fp) =>
         `保護ファイルへの書き込みがブロックされました: ${fp}\nバージョン変更を含む package.json の更新は /quick-implementor スキルを使用してください。`,
     },
+    {
+      pattern: /(?:^|\/)phasegate\.config\.json$/,
+      message: (fp) =>
+        `保護ファイルへの書き込みがブロックされました: ${fp}\n設定変更は CLI 経由で計画・適用してください: phasegate config:plan --intent retrofit-bootstrap --dry-run --json / phasegate config:plan --intent retrofit-bootstrap --apply --json`,
+    },
     {
       pattern: /(?:^|\/)harness\.config\.json$/,
       message: (fp) =>

package/scripts/harness/main.ts

@@ -13,6 +13,7 @@
  * @work-item-id WI-196
  * @work-item-id WI-197
  * @work-item-id WI-200
+ * @work-item-id WI-201
  *
  * Phasegate CLI エントリポイント。
  * 各Unitの Composition Root からハンドラーを取得し、コマンドに応じてディスパッチする。
@@ -25,6 +26,7 @@ import {
   readFile as fsReadFile,
   readdir as fsReaddir,
   readlink as fsReadlink,
+  rename as fsRename,
   writeFile as fsWriteFile,
 } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -217,7 +219,7 @@ Gate semantics:
   refresh-claude-md            Refresh CLAUDE.md standard sections (--dry-run, --apply, --json)
   p2:check-agent-context       Check AGENTS.md / CLAUDE.md freshness (--threshold-days <n>, --json)
   setup:agent                  Plan agent-driven setup (--intent <minimal|recommended|strict|ci-only|agent-hooks|retrofit>, --agent <claude|codex|both>, --dry-run|--apply, --json)
-  config:plan                  Plan safe config changes (--intent <l4-strict|codex-hooks|ci-fail-on-warning|baseline-reset|quick-mode-strict|retrofit-bootstrap|planning-mode-relax>, --dry-run, --json)
+  config:plan                  Plan safe config changes (--intent <l4-strict|codex-hooks|ci-fail-on-warning|baseline-reset|quick-mode-strict|retrofit-bootstrap|planning-mode-relax>, --dry-run|--apply, --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>, --dry-run|--apply, --force, --json)
@@ -538,6 +540,7 @@ Intents:
 
 Options:
   --dry-run
+  --apply
   --json
   --help, -h                      Show this help`,
   reconcile: `Usage: phasegate reconcile [options]
@@ -811,6 +814,12 @@ interface ConfigPatchPreview {
   readonly operations: readonly ConfigPatchOperation[];
 }
 
+interface ConfigApplyResult {
+  readonly changed: boolean;
+  readonly backupPath: string;
+  readonly appliedOperations: readonly ConfigPatchOperation[];
+}
+
 function parseInitPhasePreset(value: string | undefined): InitPhasePreset | undefined {
   if (value === undefined) return undefined;
   if (value === "full" || value === "standard" || value === "minimal" || value === "custom") {
@@ -1267,6 +1276,40 @@ function buildConfigPatchPreview(intent: ConfigChangeIntent, before: unknown | n
   };
 }
 
+function configPlanBackupPath(rootDir: string, now: Date): string {
+  const stamp = now.toISOString().replaceAll(":", "-");
+  return join(rootDir, ".phasegate", "backups", `phasegate.config.${stamp}.json`);
+}
+
+async function applyConfigPlan(rootDir: string, plan: Awaited<ReturnType<typeof buildConfigChangePlan>>): Promise<ConfigApplyResult> {
+  const patch = plan.configPatch;
+  if (patch.applicability !== "applicable") {
+    throw new Error(`config plan is not applicable: ${patch.blockedReason ?? patch.applicability}`);
+  }
+  if (patch.operations.length === 0) {
+    throw new Error("config plan has no operations to apply.");
+  }
+  if (!isPlainRecord(patch.after)) {
+    throw new Error("config plan after-state must be a JSON object.");
+  }
+
+  const configPath = join(rootDir, patch.path);
+  const backupPath = configPlanBackupPath(rootDir, new Date());
+  await fsMkdir(dirname(backupPath), { recursive: true });
+  const beforeText = patch.before === null ? "" : `${JSON.stringify(patch.before, null, 2)}\n`;
+  await fsWriteFile(backupPath, beforeText, "utf8");
+
+  const tempPath = `${configPath}.tmp-${process.pid}-${Date.now()}`;
+  await fsWriteFile(tempPath, `${JSON.stringify(patch.after, null, 2)}\n`, "utf8");
+  await fsRename(tempPath, configPath);
+
+  return {
+    changed: true,
+    backupPath: backupPath.slice(rootDir.length + 1),
+    appliedOperations: patch.operations,
+  };
+}
+
 function hasStructuredInstallError(value: unknown): boolean {
   return isPlainRecord(value) && isPlainRecord(value.error);
 }
@@ -1284,7 +1327,7 @@ async function buildConfigChangePlan(rootDir: string, intent: ConfigChangeIntent
       targets: ["phasegate.config.json: layers.L4.enabled", "phasegate.config.json: layers.L4.failOnWarning"],
       managedTargets: ["phasegate.config.json"],
       externalActions: [],
-      commands: ["phasegate validate --layer L4 --fail-on-warning --format human"],
+      commands: ["phasegate config:plan --intent l4-strict --apply --json", "phasegate validate --layer L4 --fail-on-warning --format human"],
       validations: ["phasegate phasegate:detect-drift --json", "phasegate phasegate:check-ready"],
       risks: ["L4 findings may be advisory today but become blocking when fail-on-warning is enabled."],
     },
@@ -1300,7 +1343,7 @@ async function buildConfigChangePlan(rootDir: string, intent: ConfigChangeIntent
       targets: [".github/workflows/phasegate-aidlc-gate.yml", "phasegate.config.json"],
       managedTargets: [".github/workflows/phasegate-aidlc-gate.yml", "phasegate.config.json"],
       externalActions: [{ id: "github-actions-first-run", label: "Trigger or inspect the first GitHub Actions PhaseGate run.", command: null, blocking: false }],
-      commands: ["phasegate install --with-ci --apply", "phasegate validate --layer L4 --fail-on-warning"],
+      commands: ["phasegate install --with-ci --apply", "phasegate config:plan --intent ci-fail-on-warning --apply --json", "phasegate validate --layer L4 --fail-on-warning"],
       validations: ["phasegate doctor", "phasegate ci:generate-template --type aidlc-gate --render"],
       risks: ["Existing warning-only projects may start failing CI after rollout."],
     },
@@ -1316,7 +1359,7 @@ async function buildConfigChangePlan(rootDir: string, intent: ConfigChangeIntent
       targets: ["phasegate.config.json: quickMode"],
       managedTargets: ["phasegate.config.json"],
       externalActions: [],
-      commands: ["phasegate check-change-category --paths <changed-files> --format json"],
+      commands: ["phasegate config:plan --intent quick-mode-strict --apply --json", "phasegate check-change-category --paths <changed-files> --format json"],
       validations: ["phasegate ci-check --quick --dry-run", "phasegate phasegate:check-ready"],
       risks: ["More changes will require Full Mode validation before commit."],
     },
@@ -1324,7 +1367,7 @@ async function buildConfigChangePlan(rootDir: string, intent: ConfigChangeIntent
       targets: ["phasegate.config.json: planningMode.default", "phasegate.config.json: phaseDependencies.override", "phasegate.config.json: quickMode.relaxedGates"],
       managedTargets: ["phasegate.config.json"],
       externalActions: [],
-      commands: ["phasegate baseline --dry-run", "phasegate config:plan --intent retrofit-bootstrap --json"],
+      commands: ["phasegate baseline --dry-run", "phasegate config:plan --intent retrofit-bootstrap --json", "phasegate config:plan --intent retrofit-bootstrap --apply --json"],
       validations: ["phasegate validate-metadata docs/inception/_shared/*.md", "phasegate check-phase-gate --level 2"],
       risks: ["Manual planning mode accepts existing retrofit planning evidence; review the patch before applying it to avoid weakening greenfield projects."],
     },
@@ -1332,7 +1375,7 @@ async function buildConfigChangePlan(rootDir: string, intent: ConfigChangeIntent
       targets: ["phasegate.config.json: planningMode.default"],
       managedTargets: ["phasegate.config.json"],
       externalActions: [],
-      commands: ["phasegate config:plan --intent planning-mode-relax --json"],
+      commands: ["phasegate config:plan --intent planning-mode-relax --json", "phasegate config:plan --intent planning-mode-relax --apply --json"],
       validations: ["phasegate check-phase-gate --level 2", "phasegate phasegate:check-ready"],
       risks: ["Manual planning mode reduces PhaseGate's QA enforcement for plan documents until strict planning is restored."],
     },
@@ -1975,13 +2018,42 @@ async function main(): Promise<void> {
       }
 
       case "config:plan": {
-        const KNOWN_CONFIG_PLAN_FLAGS = ["--intent", "--dry-run", "--json"];
+        const KNOWN_CONFIG_PLAN_FLAGS = ["--intent", "--dry-run", "--apply", "--json"];
         const flagError = validateKnownFlags(args, KNOWN_CONFIG_PLAN_FLAGS);
         if (flagError) {
           console.error(flagError);
           process.exit(2);
         }
+        const apply = hasFlag(args, "--apply");
+        if (apply && hasFlag(args, "--dry-run")) {
+          console.error("Error: --apply and --dry-run cannot be used together.");
+          process.exit(2);
+        }
         const plan = await buildConfigChangePlan(rootDir, parseConfigChangeIntent(parseFlag(args, "--intent")));
+        if (apply) {
+          try {
+            const applyResult = await applyConfigPlan(rootDir, plan);
+            const output = { ...plan, applyResult };
+            if (json) {
+              console.log(JSON.stringify(output, null, 2));
+            } else {
+              console.log(`phasegate config:plan apply (${plan.intent})`);
+              console.log(`changed: ${applyResult.changed}`);
+              console.log(`backup: ${applyResult.backupPath}`);
+              console.log("Applied operations:");
+              for (const operation of applyResult.appliedOperations) console.log(`- ${operation.op} ${operation.pointer}`);
+            }
+            process.exit(0);
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (json) {
+              console.log(JSON.stringify({ intent: plan.intent, refused: true, error: message, configPatch: plan.configPatch }, null, 2));
+            } else {
+              console.error(`Error: ${message}`);
+            }
+            process.exit(1);
+          }
+        }
         if (json) {
           console.log(JSON.stringify(plan, null, 2));
         } else {