phasegate 0.152.8 → 0.153.0

package/scripts/harness/main.ts

@@ -3,6 +3,8 @@
  * @layer presentation
  * @work-item-id WI-090 / WI-091
  * @work-item-id WI-113 / WI-142
+ * @work-item-id WI-171 / WI-172 / WI-173
+ * @work-item-id WI-175
  *
  * Phasegate CLI エントリポイント。
  * 各Unitの Composition Root からハンドラーを取得し、コマンドに応じてディスパッチする。
@@ -155,6 +157,8 @@ Setup:
   install                      Install phasegate managed files (--dry-run|--apply, --force)
   uninstall                    Uninstall phasegate managed files (--dry-run|--apply, --force)
   reconcile                    Reconcile phasegate managed files (--dry-run|--apply, --force)
+  setup:agent                  Diagnose repo setup and produce/apply an agent-readable setup plan
+  config:plan                  Produce an agent-readable configuration change plan
 
 Commands:
   enable-feature <name>        Enable a harness feature
@@ -193,6 +197,8 @@ Commands:
   ci:auto-refresh-agent-context Refresh AGENTS.md / CLAUDE.md (--dry-run, --apply, --json)
   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>, --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)
@@ -482,8 +488,38 @@ Options:
   --dry-run                       Preview target actions without writing (default)
   --apply                         Write merge results and manifest
   --force                         Force ai-assisted/manual targets after backing up existing files
+  --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
   --json                          Output machine-readable JSON
   --help, -h                      Show this help`,
+  "setup:agent": `Usage: phasegate setup:agent [options]
+
+Diagnose repository setup and produce an agent-readable setup plan.
+
+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
+  --help, -h                      Show this help`,
+  "config:plan": `Usage: phasegate config:plan --intent <intent> [options]
+
+Produce an agent-readable configuration change plan.
+
+Intents:
+  l4-strict, codex-hooks, ci-fail-on-warning, baseline-reset, quick-mode-strict
+
+Options:
+  --dry-run
+  --json
+  --help, -h                      Show this help`,
   reconcile: `Usage: phasegate reconcile [options]
 
 Reconcile PhaseGate-managed files with the current bundled templates.
@@ -685,6 +721,34 @@ function parseCoverageThreshold(raw: string | undefined): number {
 }
 
 type InitPhasePreset = "full" | "standard" | "minimal" | "custom";
+type AgentTarget = "claude" | "codex" | "both";
+type SetupIntent = "minimal" | "recommended" | "strict" | "ci-only" | "agent-hooks" | "retrofit";
+type ConfigChangeIntent = "l4-strict" | "codex-hooks" | "ci-fail-on-warning" | "baseline-reset" | "quick-mode-strict";
+type SetupCompletenessStatus = "configured" | "planned" | "manual" | "not-applicable" | "unknown";
+
+interface SetupCompletenessEntry {
+  readonly area: string;
+  readonly status: SetupCompletenessStatus;
+  readonly evidence: readonly string[];
+  readonly nextAction: string | null;
+  readonly risk: string | null;
+}
+
+interface ConfigPatchOperation {
+  readonly op: "add" | "replace";
+  readonly pointer: string;
+  readonly before: unknown;
+  readonly after: unknown;
+}
+
+interface ConfigPatchPreview {
+  readonly path: "phasegate.config.json";
+  readonly applicability: "applicable" | "not-applicable" | "blocked";
+  readonly blockedReason: string | null;
+  readonly before: unknown;
+  readonly after: unknown;
+  readonly operations: readonly ConfigPatchOperation[];
+}
 
 function parseInitPhasePreset(value: string | undefined): InitPhasePreset | undefined {
   if (value === undefined) return undefined;
@@ -694,6 +758,384 @@ function parseInitPhasePreset(value: string | undefined): InitPhasePreset | unde
   return undefined;
 }
 
+function parseAgentTarget(value: string | undefined, fallback: AgentTarget = "both"): AgentTarget {
+  if (value === "claude" || value === "codex" || value === "both") return value;
+  return fallback;
+}
+
+function parseSetupIntent(value: string | undefined): SetupIntent {
+  if (
+    value === "minimal" ||
+    value === "recommended" ||
+    value === "strict" ||
+    value === "ci-only" ||
+    value === "agent-hooks" ||
+    value === "retrofit"
+  ) {
+    return value;
+  }
+  return "recommended";
+}
+
+function parseConfigChangeIntent(value: string | undefined): ConfigChangeIntent {
+  if (
+    value === "l4-strict" ||
+    value === "codex-hooks" ||
+    value === "ci-fail-on-warning" ||
+    value === "baseline-reset" ||
+    value === "quick-mode-strict"
+  ) {
+    return value;
+  }
+  return "l4-strict";
+}
+
+async function projectFileExists(rootDir: string, relativePath: string): Promise<boolean> {
+  try {
+    await fsReadFile(join(rootDir, relativePath));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function setupCompletenessEntry(input: {
+  readonly area: string;
+  readonly included: boolean;
+  readonly configured: boolean;
+  readonly plannedEvidence: string;
+  readonly configuredEvidence: string;
+  readonly nextAction: string;
+  readonly risk?: string;
+}): SetupCompletenessEntry {
+  if (!input.included) {
+    return {
+      area: input.area,
+      status: "not-applicable",
+      evidence: ["Not selected for this setup intent/options."],
+      nextAction: null,
+      risk: null,
+    };
+  }
+  if (input.configured) {
+    return {
+      area: input.area,
+      status: "configured",
+      evidence: [input.configuredEvidence],
+      nextAction: null,
+      risk: input.risk ?? null,
+    };
+  }
+  return {
+    area: input.area,
+    status: "planned",
+    evidence: [input.plannedEvidence],
+    nextAction: input.nextAction,
+    risk: input.risk ?? null,
+  };
+}
+
+function buildSetupCompleteness(input: {
+  readonly intent: SetupIntent;
+  readonly agent: AgentTarget;
+  readonly withHusky: boolean;
+  readonly withCi: boolean;
+  readonly checks: {
+    readonly packageJson: boolean;
+    readonly phasegateConfig: boolean;
+    readonly claudeSettings: boolean;
+    readonly codexHooks: boolean;
+    readonly agentsMd: boolean;
+    readonly claudeMd: boolean;
+    readonly huskyPreCommit: boolean;
+    readonly ciWorkflow: boolean;
+    readonly skillsVersion: boolean;
+  };
+}): readonly SetupCompletenessEntry[] {
+  const includeClaude = input.agent === "claude" || input.agent === "both";
+  const includeCodex = input.agent === "codex" || input.agent === "both";
+  const agentHooksConfigured = (!includeClaude || input.checks.claudeSettings) && (!includeCodex || input.checks.codexHooks);
+  const agentContextConfigured = (!includeClaude || input.checks.claudeMd) && (!includeCodex || input.checks.agentsMd);
+  const entries: SetupCompletenessEntry[] = [
+    setupCompletenessEntry({
+      area: "local-config",
+      included: true,
+      configured: input.checks.packageJson && input.checks.phasegateConfig,
+      configuredEvidence: "package.json and phasegate.config.json are present.",
+      plannedEvidence: "setup:agent will create or merge package.json scripts and phasegate.config.json.",
+      nextAction: "Run setup:agent --apply, then phasegate doctor.",
+    }),
+    setupCompletenessEntry({
+      area: "agent-hooks",
+      included: includeClaude || includeCodex,
+      configured: agentHooksConfigured,
+      configuredEvidence: "Selected agent hook settings are present.",
+      plannedEvidence: "setup:agent will create or refresh selected agent hook settings.",
+      nextAction: "Run setup:agent --apply for selected agents.",
+      risk: includeCodex ? "Codex user-level hook feature enablement remains a manual external check." : undefined,
+    }),
+    setupCompletenessEntry({
+      area: "agent-context",
+      included: includeClaude || includeCodex,
+      configured: agentContextConfigured,
+      configuredEvidence: "Selected AGENTS.md / CLAUDE.md managed context files are present.",
+      plannedEvidence: "setup:agent will create or refresh selected managed agent context sections.",
+      nextAction: "Run setup:agent --apply and review preserved user-owned content.",
+    }),
+    setupCompletenessEntry({
+      area: "skills",
+      included: true,
+      configured: input.checks.skillsVersion,
+      configuredEvidence: "skills/.harness-version is present.",
+      plannedEvidence: "setup:agent will deploy bundled PhaseGate skills.",
+      nextAction: "Run setup:agent --apply to deploy skills.",
+    }),
+    setupCompletenessEntry({
+      area: "git-hooks",
+      included: input.withHusky,
+      configured: input.checks.huskyPreCommit,
+      configuredEvidence: ".husky/pre-commit is present.",
+      plannedEvidence: "setup:agent will create or refresh Husky pre-commit, commit-msg, and pre-push hooks.",
+      nextAction: "Run setup:agent --apply --with-husky.",
+    }),
+    setupCompletenessEntry({
+      area: "ci",
+      included: input.withCi,
+      configured: input.checks.ciWorkflow,
+      configuredEvidence: ".github/workflows/phasegate-aidlc-gate.yml is present.",
+      plannedEvidence: "setup:agent will create or refresh the GitHub Actions PhaseGate workflow.",
+      nextAction: "Run setup:agent --apply --with-ci.",
+      risk: "A hosted CI run is still an external manual check.",
+    }),
+    setupCompletenessEntry({
+      area: "validation",
+      included: true,
+      configured: input.checks.packageJson && input.checks.phasegateConfig,
+      configuredEvidence: "Local validation commands can be run against the configured project.",
+      plannedEvidence: "Validation commands are planned after setup apply.",
+      nextAction: "Run phasegate doctor, phasegate phasegate:check-ready, and phasegate validate --layer L2 --format human.",
+    }),
+  ];
+
+  const externalActions: string[] = [];
+  if (includeCodex) externalActions.push("Run codex features enable codex_hooks if Codex hooks are not enabled for the user.");
+  if (input.withCi) externalActions.push("Trigger or inspect the first GitHub Actions PhaseGate workflow run.");
+  if (input.intent === "strict") externalActions.push("Confirm team policy accepts strict local and CI enforcement.");
+  entries.push({
+    area: "external-actions",
+    status: externalActions.length > 0 ? "manual" : "not-applicable",
+    evidence: externalActions.length > 0 ? externalActions : ["No external manual checks selected for this setup run."],
+    nextAction: externalActions.length > 0 ? externalActions.join(" ") : null,
+    risk: externalActions.length > 0 ? "PhaseGate cannot prove these user-level or hosted-service states from local files." : null,
+  });
+  return entries;
+}
+
+async function buildAgentSetupPlan(rootDir: string, input: {
+  readonly intent: SetupIntent;
+  readonly agent: AgentTarget;
+  readonly withHusky: boolean;
+  readonly withCi: boolean;
+  readonly workflow: WorkflowMode;
+}) {
+  const checks = {
+    packageJson: await projectFileExists(rootDir, "package.json"),
+    phasegateConfig: await projectFileExists(rootDir, "phasegate.config.json"),
+    claudeSettings: await projectFileExists(rootDir, ".claude/settings.json"),
+    codexHooks: await projectFileExists(rootDir, ".codex/hooks.json"),
+    agentsMd: await projectFileExists(rootDir, "AGENTS.md"),
+    claudeMd: await projectFileExists(rootDir, "CLAUDE.md"),
+    huskyPreCommit: await projectFileExists(rootDir, ".husky/pre-commit"),
+    ciWorkflow: await projectFileExists(rootDir, ".github/workflows/phasegate-aidlc-gate.yml"),
+    skillsVersion: await projectFileExists(rootDir, "skills/.harness-version"),
+  };
+  const includeClaude = input.agent === "claude" || input.agent === "both";
+  const includeCodex = input.agent === "codex" || input.agent === "both";
+  const changes = [
+    !checks.packageJson ? "Add phasegate devDependency and phasegate scripts to package.json." : "Keep existing package.json and merge missing phasegate scripts only.",
+    !checks.phasegateConfig ? `Create phasegate.config.json for ${input.workflow} workflow.` : "Keep existing phasegate.config.json; review config:plan before changing policy.",
+    includeClaude ? "Create or refresh .claude/settings.json and CLAUDE.md managed section." : null,
+    includeCodex ? "Create or refresh .codex/hooks.json and AGENTS.md managed section." : null,
+    input.withHusky ? "Create or refresh Husky pre-commit, commit-msg, and pre-push backstops." : "Leave Husky hooks unmanaged in this setup run.",
+    input.withCi ? "Create or refresh GitHub Actions PhaseGate workflow." : "Leave CI workflow unmanaged in this setup run.",
+  ].filter((item): item is string => item !== null);
+  const questions = [
+    input.intent === "recommended" ? "Do you want both Claude and Codex context files, or only the agent you actively use?" : null,
+    input.intent === "retrofit" ? "Should existing hooks/workflows be preserved as user-owned content or migrated into PhaseGate managed blocks?" : null,
+    input.intent === "ci-only" ? "Should local hooks remain disabled while CI enforces the same checks?" : null,
+    input.workflow !== "strict" ? "Do you want strict WI/product reflection enforcement now, or after the first green run?" : null,
+  ].filter((item): item is string => item !== null);
+  return {
+    intent: input.intent,
+    agent: input.agent,
+    detected: checks,
+    completeness: buildSetupCompleteness({ ...input, checks }),
+    questions,
+    changes,
+    risks: [
+      "Existing user content outside PhaseGate managed markers is preserved.",
+      "Manual review is still required when a managed target has complex user edits and --force is not used.",
+    ],
+    rollback: [
+      "Run phasegate uninstall --dry-run to preview reversal.",
+      "Run phasegate uninstall --apply after reviewing the managed targets.",
+      "Backups are written under .phasegate/backups when force is used on changed managed files.",
+    ],
+    validation: [
+      "phasegate doctor",
+      "phasegate phasegate:check-ready",
+      "phasegate validate --layer L2 --format human",
+    ],
+  };
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function readProjectJson(rootDir: string, relativePath: string): Promise<unknown | null> {
+  try {
+    return JSON.parse(await fsReadFile(join(rootDir, relativePath), "utf8")) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+function withNestedValue(source: unknown, path: readonly string[], value: unknown): Record<string, unknown> {
+  const root = isPlainRecord(source) ? { ...source } : {};
+  let cursor = root;
+  for (const segment of path.slice(0, -1)) {
+    const next = cursor[segment];
+    cursor[segment] = isPlainRecord(next) ? { ...next } : {};
+    cursor = cursor[segment] as Record<string, unknown>;
+  }
+  cursor[path[path.length - 1]] = value;
+  return root;
+}
+
+function getNestedValue(source: unknown, path: readonly string[]): unknown {
+  let cursor = source;
+  for (const segment of path) {
+    if (!isPlainRecord(cursor)) return undefined;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+
+function buildConfigPatchPreview(intent: ConfigChangeIntent, before: unknown | null): ConfigPatchPreview {
+  const configIntents: Record<ConfigChangeIntent, readonly { readonly pointer: string; readonly path: readonly string[]; readonly value: unknown }[]> = {
+    "l4-strict": [
+      { pointer: "/layers/L4/enabled", path: ["layers", "L4", "enabled"], value: true },
+      { pointer: "/layers/L4/failOnWarning", path: ["layers", "L4", "failOnWarning"], value: true },
+    ],
+    "ci-fail-on-warning": [
+      { pointer: "/ci/enabled", path: ["ci", "enabled"], value: true },
+      { pointer: "/layers/L4/failOnWarning", path: ["layers", "L4", "failOnWarning"], value: true },
+    ],
+    "quick-mode-strict": [
+      { pointer: "/quickMode/allowedCategories", path: ["quickMode", "allowedCategories"], value: ["chore"] },
+      { pointer: "/quickMode/relaxedGates", path: ["quickMode", "relaxedGates"], value: [] },
+    ],
+    "codex-hooks": [],
+    "baseline-reset": [],
+  };
+  const changes = configIntents[intent];
+  if (changes.length === 0) {
+    return {
+      path: "phasegate.config.json",
+      applicability: "not-applicable",
+      blockedReason: "Selected intent does not require a local phasegate.config.json mutation.",
+      before,
+      after: before,
+      operations: [],
+    };
+  }
+  let after: unknown = before;
+  const operations: ConfigPatchOperation[] = [];
+  for (const change of changes) {
+    const previous = getNestedValue(after, change.path);
+    after = withNestedValue(after, change.path, change.value);
+    operations.push({
+      op: previous === undefined ? "add" : "replace",
+      pointer: change.pointer,
+      before: previous ?? null,
+      after: change.value,
+    });
+  }
+  return {
+    path: "phasegate.config.json",
+    applicability: "applicable",
+    blockedReason: null,
+    before,
+    after,
+    operations,
+  };
+}
+
+function hasStructuredInstallError(value: unknown): boolean {
+  return isPlainRecord(value) && isPlainRecord(value.error);
+}
+
+async function buildConfigChangePlan(rootDir: string, intent: ConfigChangeIntent) {
+  const catalog: Record<ConfigChangeIntent, {
+    readonly targets: readonly string[];
+    readonly managedTargets: readonly string[];
+    readonly externalActions: readonly { readonly id: string; readonly label: string; readonly command: string | null; readonly blocking: boolean }[];
+    readonly commands: readonly string[];
+    readonly validations: readonly string[];
+    readonly risks: readonly string[];
+  }> = {
+    "l4-strict": {
+      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"],
+      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."],
+    },
+    "codex-hooks": {
+      targets: [".codex/hooks.json", "AGENTS.md", ".codex/skills"],
+      managedTargets: [".codex/hooks.json", "AGENTS.md", ".codex/skills"],
+      externalActions: [{ id: "codex-hooks-feature", label: "Enable Codex user-level hooks feature.", command: "codex features enable codex_hooks", blocking: true }],
+      commands: ["phasegate install --agent codex --apply", "codex features enable codex_hooks"],
+      validations: ["phasegate doctor --json", "phasegate phasegate:status --json"],
+      risks: ["Codex apply_patch writes still require the pre-commit backstop for full coverage."],
+    },
+    "ci-fail-on-warning": {
+      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"],
+      validations: ["phasegate doctor", "phasegate ci:generate-template --type aidlc-gate --render"],
+      risks: ["Existing warning-only projects may start failing CI after rollout."],
+    },
+    "baseline-reset": {
+      targets: [".phasegate/baseline.json"],
+      managedTargets: [".phasegate/baseline.json"],
+      externalActions: [],
+      commands: ["phasegate baseline --dry-run", "phasegate baseline --force --json"],
+      validations: ["phasegate phasegate:status --json", "phasegate phasegate:check-ready"],
+      risks: ["A reset can hide historical drift if reviewed without the generated diff."],
+    },
+    "quick-mode-strict": {
+      targets: ["phasegate.config.json: quickMode"],
+      managedTargets: ["phasegate.config.json"],
+      externalActions: [],
+      commands: ["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."],
+    },
+  };
+  const before = await readProjectJson(rootDir, "phasegate.config.json");
+  return {
+    intent,
+    ...catalog[intent],
+    configPatch: buildConfigPatchPreview(intent, before),
+    diffExplanation: "Review the listed targets first, apply through PhaseGate managed commands where possible, then run the validations in order.",
+    rollback: "Use git diff for config changes; use phasegate uninstall/reconcile dry-runs for managed setup targets.",
+  };
+}
+
 type RuleSeverity = "error" | "warning" | "off";
 
 function toRuleSeverity(value: string): RuleSeverity {
@@ -999,6 +1441,9 @@ async function main(): Promise<void> {
           includeCodex: deployCodex,
           includeHusky: withHusky,
           includeCi: withCi,
+          skillSet,
+          workflow,
+          agent,
         });
         console.log(
           `✓ Skills deployed to ${result.targetDir} (${result.deployedSkills.length} skills, set: ${skillSet})`,
@@ -1131,7 +1576,7 @@ async function main(): Promise<void> {
           console.log("  • Q&A about phasegate concepts: invoke /phasegate-toolkit-guide");
           console.log("  • Diagnose & tune phasegate.config.json: invoke /phasegate-config-doctor");
         }
-        process.exit(0);
+        process.exit(hasStructuredInstallError(installResult) ? 1 : 0);
         break;
       }
 
@@ -1196,7 +1641,7 @@ async function main(): Promise<void> {
       }
 
       case "install": {
-        const KNOWN_INSTALL_FLAGS = ["--dry-run", "--apply", "--force", "--json"];
+        const KNOWN_INSTALL_FLAGS = ["--dry-run", "--apply", "--force", "--json", "--agent", "--skills", "--workflow", "--with-husky", "--with-ci"];
         const flagError = validateKnownFlags(args, KNOWN_INSTALL_FLAGS);
         if (flagError) {
           console.error(flagError);
@@ -1204,6 +1649,19 @@ async function main(): Promise<void> {
         }
         const apply = hasFlag(args, "--apply");
         const dryRun = hasFlag(args, "--dry-run") || !apply;
+        const agent = parseAgentTarget(parseFlag(args, "--agent"), "both");
+        const skillSetRaw = parseFlag(args, "--skills") ?? "all";
+        if (skillSetRaw !== "core" && skillSetRaw !== "all") {
+          console.error(`Invalid --skills value: "${skillSetRaw}". Use "core" or "all".`);
+          process.exit(2);
+        }
+        const workflowRaw = parseFlag(args, "--workflow");
+        if (workflowRaw !== undefined && workflowRaw !== "standard" && workflowRaw !== "strict") {
+          console.error(`Invalid --workflow value: "${workflowRaw}". Use "standard" or "strict".`);
+          process.exit(2);
+        }
+        const includeClaude = agent === "claude" || agent === "both";
+        const includeCodex = agent === "codex" || agent === "both";
         const mod = createInstallationModule();
         const phasegateVersion = await getHarnessVersion(harnessRoot);
         const result = await mod.installHandler.execute({
@@ -1213,6 +1671,13 @@ async function main(): Promise<void> {
           dryRun,
           apply,
           force: hasFlag(args, "--force"),
+          includeClaude,
+          includeCodex,
+          includeHusky: true,
+          includeCi: true,
+          skillSet: skillSetRaw,
+          workflow: parseWorkflowMode(workflowRaw),
+          agent,
           json,
         });
         console.log(result.stdout);
@@ -1220,6 +1685,95 @@ async function main(): Promise<void> {
         break;
       }
 
+      case "setup:agent": {
+        const KNOWN_SETUP_AGENT_FLAGS = ["--intent", "--agent", "--workflow", "--with-husky", "--with-ci", "--dry-run", "--apply", "--force", "--json"];
+        const flagError = validateKnownFlags(args, KNOWN_SETUP_AGENT_FLAGS);
+        if (flagError) {
+          console.error(flagError);
+          process.exit(2);
+        }
+        const intent = parseSetupIntent(parseFlag(args, "--intent"));
+        const agent = parseAgentTarget(parseFlag(args, "--agent"), "both");
+        const workflow = parseWorkflowMode(parseFlag(args, "--workflow") ?? (intent === "strict" ? "strict" : "standard"));
+        const withCi = hasFlag(args, "--with-ci") || intent === "ci-only" || intent === "strict";
+        const withHusky = hasFlag(args, "--with-husky") || intent === "agent-hooks" || intent === "strict";
+        let plan = await buildAgentSetupPlan(rootDir, { intent, agent, withHusky, withCi, workflow });
+        const apply = hasFlag(args, "--apply");
+        let installResult: unknown = null;
+        let bootstrapResult: unknown = null;
+        if (apply) {
+          const skillResult = await deploySkills(harnessRoot, rootDir, "all");
+          const packageResult = await ensurePhasegatePackageDependency(rootDir, skillResult.version);
+          const configResult = await initHarnessConfig(rootDir, "my-project", workflow === "strict" ? "full" : "standard", {
+            ciEnabled: withCi,
+            workflow,
+          });
+          bootstrapResult = {
+            skillsDeployed: skillResult.deployedSkills.length,
+            packageDependency: packageResult,
+            configCreated: configResult.created,
+          };
+          const mod = createInstallationModule();
+          const phasegateVersion = await getHarnessVersion(harnessRoot);
+          installResult = await mod.runInstallUseCase.execute({
+            projectRoot: rootDir,
+            harnessRoot,
+            phasegateVersion,
+            dryRun: false,
+            apply: true,
+            force: hasFlag(args, "--force"),
+            includeClaude: agent === "claude" || agent === "both",
+            includeCodex: agent === "codex" || agent === "both",
+            includeHusky: withHusky,
+            includeCi: withCi,
+            skillSet: "all",
+            workflow,
+            agent,
+          });
+          plan = await buildAgentSetupPlan(rootDir, { intent, agent, withHusky, withCi, workflow });
+        }
+        const output = { plan, applied: apply, bootstrapResult, installResult };
+        if (json) {
+          console.log(JSON.stringify(output, null, 2));
+        } else {
+          console.log(`phasegate setup:agent ${apply ? "apply" : "dry-run"} (${intent}, ${agent})`);
+          for (const change of plan.changes) console.log(`- ${change}`);
+          if (plan.questions.length > 0) {
+            console.log("");
+            console.log("Questions:");
+            for (const question of plan.questions) console.log(`- ${question}`);
+          }
+          console.log("");
+          console.log("Validation:");
+          for (const command of plan.validation) console.log(`- ${command}`);
+        }
+        process.exit(0);
+        break;
+      }
+
+      case "config:plan": {
+        const KNOWN_CONFIG_PLAN_FLAGS = ["--intent", "--dry-run", "--json"];
+        const flagError = validateKnownFlags(args, KNOWN_CONFIG_PLAN_FLAGS);
+        if (flagError) {
+          console.error(flagError);
+          process.exit(2);
+        }
+        const plan = await buildConfigChangePlan(rootDir, parseConfigChangeIntent(parseFlag(args, "--intent")));
+        if (json) {
+          console.log(JSON.stringify(plan, null, 2));
+        } else {
+          console.log(`phasegate config:plan (${plan.intent})`);
+          console.log("Targets:");
+          for (const target of plan.targets) console.log(`- ${target}`);
+          console.log("Commands:");
+          for (const command of plan.commands) console.log(`- ${command}`);
+          console.log("Validation:");
+          for (const validation of plan.validations) console.log(`- ${validation}`);
+        }
+        process.exit(0);
+        break;
+      }
+
       case "uninstall": {
         const KNOWN_UNINSTALL_FLAGS = ["--dry-run", "--apply", "--force", "--json"];
         const flagError = validateKnownFlags(args, KNOWN_UNINSTALL_FLAGS);

package/skills/phasegate-config-doctor/SKILL.md

@@ -39,6 +39,7 @@ phasegate を導入した直後の config は単純な default で、実プロ
 | Codex hooks | `.codex/hooks.json` | managed hook JSON と Codex hook 配線確認 |
 | Husky scripts | `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push` | pre-commit backstop と bypass audit の確認 |
 | CI workflows | `.github/workflows/*` | `phasegate-aidlc-gate.yml` や既存 workflow との競合確認 |
+| agent context | `AGENTS.md`, `CLAUDE.md` | PhaseGate managed section、lesson pointer section、user-owned content の境界確認 |
 
 **schema は必要なときだけ Read** (enum 違反疑い時など): `node_modules/phasegate/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json` (or `harness-config-v2.schema.json` if v2)。
 
@@ -131,6 +132,9 @@ product-architect で Unit を作り、いくつかの logical_design を書い
 - reconcile / uninstall が refuse → user modified managed target として扱い、`--force` のリスクと backup path を説明して承認を取る
 - Codex の `codex_hooks` feature flag は user-level setting。project-local `install` では変更されないため、必要なら `codex features enable codex_hooks` を案内
 - Codex native `apply_patch` bypass は hook で完全捕捉できない。`.husky/pre-commit` の `phasegate pre-commit` が backstop になるため、Husky 配線を診断対象に含める
+- 初回 setup / retrofit / CI-only / agent-hooks の判断が曖昧な場合は `npx phasegate setup:agent --dry-run --json` を先に使い、検出済み状態、質問、変更案、rollback、validation を根拠として提案する。<!-- @work-item-id WI-172 -->
+- 「L4 を厳しめにして」「Codex hook を有効にして」「CI で warning を fail にして」などの自然言語依頼は、`npx phasegate config:plan --intent <intent> --dry-run --json` で対象ファイル、コマンド、リスク、検証を確認してから diff を提案する。<!-- @work-item-id WI-173 -->
+- `AGENTS.md` は標準運用ルールの managed section と lesson pointer section を分ける。`ci:auto-refresh-agent-context --apply` は lesson pointers 専用 section を更新し、標準運用ルールや user-owned content を置換してはいけない。<!-- @work-item-id WI-174 -->
 
 ### Step 3: 診断レポート
 

package/skills/phasegate-toolkit-guide/SKILL.md

@@ -123,12 +123,17 @@ docs/guide/                          # phasegate リポジトリ自体 (dogfood)
 - 「.phasegate/manifest.json や hook-skip-events は何？」
 
 **参照先**:
+- 最短導線: `docs/guide/getting-started.md`
+- recipes: `docs/guide/recipes.md`
+- troubleshooting: `docs/guide/troubleshooting.md`
 - 新規導入: `docs/guide/installation.md`
 - 既存プロジェクト導入: `docs/guide/retrofit-adoption.md`
 - setup artifact / doctor finding / legacy artifact: `docs/guide/setup-artifacts.md`
 
 `setup-artifacts.md` は managed target / generated artifact / runtime state / legacy artifact / user-level setting の分類を持つ。`doctor --report-out` は明示 path への出力で、`.phasegate/last-doctor-report.json` は固定生成物ではない点もここを参照する。<!-- @work-item-id WI-153 -->
 
+`setup:agent` は初回 setup / retrofit / CI-only / agent hook 有効化の agent-readable planner、`config:plan` は安全な設定変更 intent planner。質問が「次に何を実行するか」「この変更はどの file/validation に対応するか」に寄っている場合は、これらの guide と CLI を案内する。<!-- @work-item-id WI-171, WI-172, WI-173 -->
+
 ### 8. skill 一覧と使い分け
 
 ユーザー質問例: