phasegate 0.155.0 → 0.157.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.157.0] - 2026-05-13
+
+### Changed
+
+- **WI-179 — scoped-out doctor repair guidance** — suppresses `repairHint` and `suggestedSkill` for unselected-agent `scopedOutFindings`, adds explicit repair applicability markers, and updates CLI/troubleshooting/skill guidance so scoped doctor output is harder to misread as repair work.
+
 ## [0.154.0] - 2026-05-13
 
 ### Added

package/docs/guide/cli-reference.md

@@ -24,7 +24,7 @@ Command names in this document are split into three surfaces:
 |---|---|
 | `init --name <name>` | Legacy-compatible bootstrap for new projects: deploy skills, generate config, and optionally add hooks/CI. Options: `--preset <full\|standard\|minimal\|custom>`, `--skills <core\|all>`, `--agent <claude\|codex\|both>`, `--workflow <standard\|strict>`, `--with-husky`, `--with-ci`, `--yes`. |
 | `install --dry-run` / `--apply` | Idempotently merge PhaseGate into an existing project, preserve user content, add package scripts/devDependency, create selected `AGENTS.md` / `CLAUDE.md` managed sections, and write `.phasegate/manifest.json`. `--agent <claude\|codex\|both>`, `--skills <core\|all>`, and `--workflow <standard\|strict>` affect rendered agent context; `--force` replaces managed targets after backup. |
-| `doctor` | Diagnose silent or partial installations and report repair hints (`--json`, `--strict`, `--report-out <path>`). `--report-out` writes exactly to the supplied path, not to `reporting.outputDir`. |
+| `doctor` | Diagnose silent or partial installations and report repair hints (`--json`, `--strict`, `--agent <claude\|codex\|both>`, `--report-out <path>`). `--agent` defaults to `both`; single-agent scopes keep shared targets applicable and mark the other agent's findings as not applicable. `--report-out` writes exactly to the supplied path, not to `reporting.outputDir`. |
 | `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 --> |
@@ -40,7 +40,7 @@ Command names in this document are split into three surfaces:
 
 <!-- @work-item-id WI-158 -->
 
-Setup lifecycle commands support JSON for automation where shown by help: `install --json`, `reconcile --json`, `uninstall --json`, and `doctor --json`. `doctor --report-out <path>` persists the doctor JSON payload to that exact path. Relative paths are resolved from the project root; absolute paths are used as-is.
+Setup lifecycle commands support JSON for automation where shown by help: `install --json`, `reconcile --json`, `uninstall --json`, and `doctor --json`. `doctor --agent claude --json` and `doctor --agent codex --json` include `scope` and `scopedOutFindings` so agents can distinguish selected-agent readiness from full-install diagnostics. Scoped-out findings suppress immediate repair guidance with `repairHint: null`, `suggestedSkill: null`, and `repairHintApplicability: "only-if-agent-selected"`. `doctor --report-out <path>` persists the doctor JSON payload to that exact path. Relative paths are resolved from the project root; absolute paths are used as-is. <!-- @work-item-id WI-178, WI-179 -->
 
 This is separate from `reporting.outputDir`. The configured report directory is used by phase-dependency / phase-gate reporting, while regression-suite result files are fixed under `reports/regression/` and status/drift JSON is emitted to stdout.
 

package/docs/guide/troubleshooting.md

@@ -63,6 +63,8 @@ The planner output is intentionally agent-readable: detected state, questions, p
 
 `doctor` green means the local managed setup is consistent for the inspected targets. It does not prove user-level Codex feature flags, hosted GitHub Actions execution, npm registry state, or team policy acceptance.
 
+By default, `phasegate doctor` inspects the full Claude + Codex + shared setup. For a deliberate single-agent setup, use `phasegate doctor --agent claude --json` or `phasegate doctor --agent codex --json`. Single-agent reports keep shared targets applicable and place the unselected agent's findings under `scopedOutFindings` with `applicability: "not-applicable"`; those findings are explanatory, not repair targets for the selected agent. Their `repairHint` and `suggestedSkill` fields are intentionally `null`; `repairHintApplicability: "only-if-agent-selected"` means the repair guidance matters only if the user chooses that agent. <!-- @work-item-id WI-178, WI-179 -->
+
 Check `plan.completeness` in `setup:agent --json`:
 
 - `configured`: PhaseGate found local evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.155.0",
+  "version": "0.157.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/installation/application/usecases/run-doctor-diagnostics.ts

@@ -1,22 +1,38 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-145
+// @work-item-id WI-178
 
 import { DiagnosticReport } from "../../domain/diagnostic-report.js";
+import type { CheckId } from "../../domain/check-id.js";
+import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
 import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
 import type { FileInspectorPort } from "../ports/file-inspector-port.js";
 import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
 
+export type DoctorAgentScope = "claude" | "codex" | "both";
+
+export interface ScopedOutDiagnosticFinding {
+  readonly finding: DiagnosticFinding;
+  readonly scopeReason: string;
+}
+
 export interface RunDoctorDiagnosticsInput {
   readonly projectRoot: string;
   readonly strict: boolean;
+  readonly agent?: DoctorAgentScope;
 }
 
 export interface RunDoctorDiagnosticsOutput {
   readonly report: DiagnosticReport;
+  readonly agent: DoctorAgentScope;
+  readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[];
   readonly exitCode: number;
 }
 
+const CLAUDE_ONLY_CHECKS = new Set<CheckId>(["claude-hook-missing", "claude-skills-symlink"]);
+const CODEX_ONLY_CHECKS = new Set<CheckId>(["codex-hook-missing", "codex-skills-symlink"]);
+
 export class RunDoctorDiagnosticsUseCase {
   constructor(
     private readonly checks: readonly HeuristicCheck[],
@@ -25,17 +41,42 @@ export class RunDoctorDiagnosticsUseCase {
   ) {}
 
   async execute(input: RunDoctorDiagnosticsInput): Promise<RunDoctorDiagnosticsOutput> {
+    const agent = input.agent ?? "both";
     await this.manifestRepository.load(input.projectRoot).catch(() => null);
-    const findings = (await Promise.all(
+    const rawFindings = (await Promise.all(
       this.checks.map((check) => check.run(input.projectRoot, this.inspector)),
     )).filter((finding) => finding !== null);
+    const { findings, scopedOutFindings } = this.applyAgentScope(rawFindings, agent);
     const report = DiagnosticReport.create(findings);
     return {
       report,
+      agent,
+      scopedOutFindings,
       exitCode: this.decideExitCode(report, input.strict),
     };
   }
 
+  private applyAgentScope(
+    findings: readonly DiagnosticFinding[],
+    agent: DoctorAgentScope,
+  ): { readonly findings: readonly DiagnosticFinding[]; readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[] } {
+    if (agent === "both") return { findings, scopedOutFindings: [] };
+    const scopedOutChecks = agent === "claude" ? CODEX_ONLY_CHECKS : CLAUDE_ONLY_CHECKS;
+    const applicable: DiagnosticFinding[] = [];
+    const scopedOut: ScopedOutDiagnosticFinding[] = [];
+    for (const finding of findings) {
+      if (scopedOutChecks.has(finding.checkId)) {
+        scopedOut.push({
+          finding,
+          scopeReason: `${finding.checkId} belongs to an unselected agent for doctor --agent ${agent}.`,
+        });
+      } else {
+        applicable.push(finding);
+      }
+    }
+    return { findings: applicable, scopedOutFindings: scopedOut };
+  }
+
   private decideExitCode(report: DiagnosticReport, strict: boolean): number {
     if (report.hasRedFlag()) return 1;
     if (strict && report.hasWarning()) return 1;

package/scripts/harness/installation/presentation/cli/doctor-handler.ts

@@ -1,10 +1,11 @@
 // @unit installation
 // @layer presentation
 // @work-item-id WI-145
+// @work-item-id WI-178
 
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join } from "node:path";
-import type { RunDoctorDiagnosticsUseCase } from "../../application/usecases/run-doctor-diagnostics.js";
+import type { DoctorAgentScope, RunDoctorDiagnosticsUseCase } from "../../application/usecases/run-doctor-diagnostics.js";
 import { DiagnosticReportFormatter } from "../formatters/diagnostic-report-formatter.js";
 
 export interface DoctorHandlerInput {
@@ -13,6 +14,7 @@ export interface DoctorHandlerInput {
   readonly json: boolean;
   readonly reportOut: string | null;
   readonly phasegateVersion: string;
+  readonly agent?: DoctorAgentScope;
 }
 
 export interface DoctorHandlerOutput {
@@ -30,9 +32,12 @@ export class DoctorHandler {
     const result = await this.useCase.execute({
       projectRoot: input.projectRoot,
       strict: input.strict,
+      agent: input.agent,
     });
     const formatInput = {
       report: result.report,
+      agent: result.agent,
+      scopedOutFindings: result.scopedOutFindings,
       phasegateVersion: input.phasegateVersion,
       projectRoot: input.projectRoot,
       exitCode: result.exitCode,

package/scripts/harness/installation/presentation/formatters/diagnostic-report-formatter.ts

@@ -1,11 +1,16 @@
 // @unit installation
 // @layer presentation
 // @work-item-id WI-145
+// @work-item-id WI-178
+// @work-item-id WI-179
 
+import type { DoctorAgentScope, ScopedOutDiagnosticFinding } from "../../application/usecases/run-doctor-diagnostics.js";
 import type { DiagnosticReport } from "../../domain/diagnostic-report.js";
 
 export interface DiagnosticReportFormatterInput {
   readonly report: DiagnosticReport;
+  readonly agent: DoctorAgentScope;
+  readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[];
   readonly phasegateVersion: string;
   readonly projectRoot: string;
   readonly exitCode: number;
@@ -18,8 +23,27 @@ export class DiagnosticReportFormatter {
         schemaVersion: "1.0",
         phasegateVersion: input.phasegateVersion,
         projectRoot: input.projectRoot,
+        scope: {
+          agent: input.agent,
+          description: scopeDescription(input.agent),
+        },
         overallStatus: input.report.overallStatus,
-        findings: input.report.findings.map((finding) => finding.toJSON()),
+        findings: input.report.findings.map((finding) => ({
+          ...finding.toJSON(),
+          applicability: "applicable",
+          repairHintApplicability: "applicable",
+        })),
+        scopedOutFindings: input.scopedOutFindings.map(({ finding, scopeReason }) => {
+          const json = finding.toJSON();
+          return {
+            ...json,
+            repairHint: null,
+            suggestedSkill: null,
+            applicability: "not-applicable",
+            repairHintApplicability: "only-if-agent-selected",
+            scopeReason,
+          };
+        }),
         exitCode: input.exitCode,
       },
       null,
@@ -31,6 +55,7 @@ export class DiagnosticReportFormatter {
     const lines = [
       `phasegate doctor v${input.phasegateVersion}`,
       `Project: ${input.projectRoot}`,
+      `Scope: ${input.agent} (${scopeDescription(input.agent)})`,
       "",
     ];
     for (const finding of input.report.findings) {
@@ -47,7 +72,16 @@ export class DiagnosticReportFormatter {
     const redCount = input.report.findings.filter((finding) => finding.severity === "red").length;
     const warnCount = input.report.findings.filter((finding) => finding.severity === "warn").length;
     lines.push(`Status: ${input.report.overallStatus.toUpperCase()} (${input.report.findings.length} findings: ${redCount} red, ${warnCount} warn)`);
+    if (input.scopedOutFindings.length > 0) {
+      lines.push(`Scoped out: ${input.scopedOutFindings.length} informational findings not applicable to --agent ${input.agent}; not repair targets for this scope.`);
+    }
     lines.push(`Exit: ${input.exitCode}`);
     return lines.join("\n");
   }
 }
+
+function scopeDescription(agent: DoctorAgentScope): string {
+  if (agent === "claude") return "Claude Code and shared setup targets; Codex-only findings are not applicable.";
+  if (agent === "codex") return "Codex and shared setup targets; Claude-only findings are not applicable.";
+  return "Full setup diagnostics for Claude, Codex, and shared targets.";
+}

package/scripts/harness/main.ts

@@ -152,7 +152,7 @@ Setup:
                                 --skills <core|all>, --agent <claude|codex|both>, --workflow <standard|strict>,
                                 --with-husky, --with-ci, --yes)
   update-skills                Alias for reconcile (kept for compatibility)
-  doctor                       Diagnose silent installation failures (--json, --strict, --report-out <path>)
+  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
   emit-agent-rules             Print AGENTS.md / CLAUDE.md WI workflow rules block
   install                      Install phasegate managed files (--dry-run|--apply, --force)
@@ -772,6 +772,16 @@ function parseAgentTarget(value: string | undefined, fallback: AgentTarget = "bo
   return fallback;
 }
 
+function parseRequiredAgentTarget(value: string | undefined, fallback: AgentTarget = "both"): AgentTarget | null {
+  if (value === undefined) return fallback;
+  if (value === "claude" || value === "codex" || value === "both") return value;
+  return null;
+}
+
+function doctorValidationCommand(agent: AgentTarget): string {
+  return agent === "both" ? "phasegate doctor" : `phasegate doctor --agent ${agent}`;
+}
+
 function parseSetupIntent(value: string | undefined): SetupIntent {
   if (
     value === "minimal" ||
@@ -863,6 +873,7 @@ function buildSetupCompleteness(input: {
 }): readonly SetupCompletenessEntry[] {
   const includeClaude = input.agent === "claude" || input.agent === "both";
   const includeCodex = input.agent === "codex" || input.agent === "both";
+  const doctorCommand = doctorValidationCommand(input.agent);
   const agentHooksConfigured = (!includeClaude || input.checks.claudeSettings) && (!includeCodex || input.checks.codexHooks);
   const agentContextConfigured = (!includeClaude || input.checks.claudeMd) && (!includeCodex || input.checks.agentsMd);
   const entries: SetupCompletenessEntry[] = [
@@ -872,7 +883,7 @@ function buildSetupCompleteness(input: {
       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.",
+      nextAction: `Run setup:agent --apply, then ${doctorCommand}.`,
     }),
     setupCompletenessEntry({
       area: "agent-hooks",
@@ -922,7 +933,7 @@ function buildSetupCompleteness(input: {
       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.",
+      nextAction: `Run ${doctorCommand}, phasegate phasegate:check-ready, and phasegate validate --layer L2 --format human.`,
     }),
   ];
 
@@ -994,6 +1005,7 @@ function buildAgentReadiness(input: {
 }): readonly AgentReadinessEntry[] {
   const includeClaude = input.agent === "claude" || input.agent === "both";
   const includeCodex = input.agent === "codex" || input.agent === "both";
+  const doctorCommand = doctorValidationCommand(input.agent);
   const sharedConfigured =
     input.checks.packageJson &&
     input.checks.phasegateConfig &&
@@ -1045,7 +1057,7 @@ function buildAgentReadiness(input: {
       plannedEvidence: [
         "setup:agent will create or refresh package scripts, phasegate.config.json, skills, and selected Husky/CI targets.",
       ],
-      nextAction: "Run setup:agent --apply, then phasegate doctor, phasegate phasegate:check-ready, and phasegate validate --layer L2 --format human.",
+      nextAction: `Run setup:agent --apply, then ${doctorCommand}, phasegate phasegate:check-ready, and phasegate validate --layer L2 --format human.`,
       risk: input.withCi ? "A hosted CI run remains an external manual check." : undefined,
     }),
   ];
@@ -1103,7 +1115,7 @@ async function buildAgentSetupPlan(rootDir: string, input: {
       "Backups are written under .phasegate/backups when force is used on changed managed files.",
     ],
     validation: [
-      "phasegate doctor",
+      doctorValidationCommand(input.agent),
       "phasegate phasegate:check-ready",
       "phasegate validate --layer L2 --format human",
     ],
@@ -1728,6 +1740,17 @@ async function main(): Promise<void> {
       }
 
       case "doctor": {
+        const KNOWN_DOCTOR_FLAGS = ["--json", "--strict", "--agent", "--report-out"];
+        const flagError = validateKnownFlags(args, KNOWN_DOCTOR_FLAGS);
+        if (flagError) {
+          console.error(flagError);
+          process.exit(2);
+        }
+        const agent = parseRequiredAgentTarget(parseFlag(args, "--agent"), "both");
+        if (agent === null) {
+          console.error(`Invalid --agent value: "${parseFlag(args, "--agent")}". Use "claude", "codex", or "both".`);
+          process.exit(2);
+        }
         const mod = createInstallationModule();
         const phasegateVersion = await getHarnessVersion(harnessRoot);
         const result = await mod.doctorHandler.execute({
@@ -1736,6 +1759,7 @@ async function main(): Promise<void> {
           json,
           reportOut: parseFlag(args, "--report-out") ?? null,
           phasegateVersion,
+          agent,
         });
         console.log(result.stdout);
         process.exit(result.exitCode);

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

@@ -127,6 +127,7 @@ product-architect で Unit を作り、いくつかの logical_design を書い
 #### 観点 9: setup lifecycle と doctor finding
 
 - `phasegate doctor --json` の finding に `repairMode: "ai-assisted"` と `suggestedSkill.skillName = "phasegate-config-doctor"` がある → 本 skill が merge 方針、保持する user content、実行すべき `install --apply` / `--force` / `reconcile --apply` を提案する
+- Claude-only / Codex-only 導入後は `phasegate doctor --agent claude --json` または `phasegate doctor --agent codex --json` を使って selected agent の readiness を読む。`scopedOutFindings` は未選択 agent の `not-applicable` 情報なので、ユーザーがその agent を導入したいと言っていない限り repair 提案にしない。`repairHint: null` / `suggestedSkill: null` は意図的な抑制で、`repairHintApplicability: "only-if-agent-selected"` はその agent を選んだ場合だけ修復 guidance が意味を持つという印である。<!-- @work-item-id WI-178, WI-179 -->
 - `repairHint` がある mechanical finding → 原則として hint のコマンドを優先し、実行前に対象ファイルと manifest の差分を確認
 - manifest parse error → `.phasegate/manifest.json` を手で修復する前に backup / uninstall / reinstall の選択肢を提示
 - reconcile / uninstall が refuse → user modified managed target として扱い、`--force` のリスクと backup path を説明して承認を取る

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

@@ -132,6 +132,8 @@ docs/guide/                          # phasegate リポジトリ自体 (dogfood)
 
 `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 -->
 
+Claude-only / Codex-only setup の確認では、full `phasegate doctor` と scoped doctor を区別する。ユーザーが `setup:agent --agent claude` を選んだ場合は `phasegate doctor --agent claude --json` を優先し、`scopedOutFindings` の Codex finding は「未選択 agent の not-applicable 情報」であり修復対象ではないと説明する。`repairHint: null` / `suggestedSkill: null` は意図的な抑制で、`repairHintApplicability: "only-if-agent-selected"` はその agent を選んだ場合だけ修復 guidance が意味を持つという印である。full doctor は両 agent を導入したい場合の診断として扱う。<!-- @work-item-id WI-178, WI-179 -->
+
 `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 -->
 
 Claude Code readiness の質問では `npx phasegate setup:agent --agent claude --dry-run --json` を案内し、`plan.agentReadiness` の `claude` / `shared` が `configured` なら setup ではなく作業導線へ進める。最短ルートは、WI の確認または起票、`docs/inception/.../{WI-XXX}/` への計画/設計、`docs/product/...` への `@work-item-id WI-XXX` 反映、`phasegate phasegate:check-ready` または該当 `validate` の実行である。`setup:agent --apply --json` の structured `error` は troubleshooting に委譲し、`target` / `operation` / `code` / `recovery` を読ませる。<!-- @work-item-id WI-177 -->