phasegate 0.156.0 → 0.158.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.158.0] - 2026-05-13
+
+### Changed
+
+- **WI-180 — scoped-out doctor effective repair contract** — adds current-scope repair target and repair-mode applicability fields to doctor JSON, lists scoped-out check IDs in human output, and updates docs/skills so single-agent diagnostics are harder to misread.
+
+## [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

@@ -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 --agent claude --json` and `doctor --agent codex --json` include `scope` and `scopedOutFindings` so agents can distinguish selected-agent readiness from full-install diagnostics. `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 -->
+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`, `currentScopeRepairTarget: false`, `repairHintApplicability: "only-if-agent-selected"`, and `repairModeApplicability: "only-if-agent-selected"`; applicable `findings[]` use `currentScopeRepairTarget: true` with applicable repair fields. `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, WI-180 -->
 
 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,7 +63,7 @@ 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. <!-- @work-item-id WI-178 -->
+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`; `currentScopeRepairTarget: false`, `repairHintApplicability: "only-if-agent-selected"`, and `repairModeApplicability: "only-if-agent-selected"` mean the original repair fields only become actionable if the user chooses that agent. Applicable `findings[]` use `currentScopeRepairTarget: true` and applicable repair fields. <!-- @work-item-id WI-178, WI-179, WI-180 -->
 
 Check `plan.completeness` in `setup:agent --json`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.156.0",
+  "version": "0.158.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/presentation/formatters/diagnostic-report-formatter.ts

@@ -2,6 +2,8 @@
 // @layer presentation
 // @work-item-id WI-145
 // @work-item-id WI-178
+// @work-item-id WI-179
+// @work-item-id WI-180
 
 import type { DoctorAgentScope, ScopedOutDiagnosticFinding } from "../../application/usecases/run-doctor-diagnostics.js";
 import type { DiagnosticReport } from "../../domain/diagnostic-report.js";
@@ -30,12 +32,23 @@ export class DiagnosticReportFormatter {
         findings: input.report.findings.map((finding) => ({
           ...finding.toJSON(),
           applicability: "applicable",
+          currentScopeRepairTarget: true,
+          repairHintApplicability: "applicable",
+          repairModeApplicability: "applicable",
         })),
-        scopedOutFindings: input.scopedOutFindings.map(({ finding, scopeReason }) => ({
-          ...finding.toJSON(),
-          applicability: "not-applicable",
-          scopeReason,
-        })),
+        scopedOutFindings: input.scopedOutFindings.map(({ finding, scopeReason }) => {
+          const json = finding.toJSON();
+          return {
+            ...json,
+            repairHint: null,
+            suggestedSkill: null,
+            applicability: "not-applicable",
+            currentScopeRepairTarget: false,
+            repairHintApplicability: "only-if-agent-selected",
+            repairModeApplicability: "only-if-agent-selected",
+            scopeReason,
+          };
+        }),
         exitCode: input.exitCode,
       },
       null,
@@ -65,7 +78,8 @@ export class DiagnosticReportFormatter {
     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} findings not applicable to --agent ${input.agent}`);
+      const checkIds = input.scopedOutFindings.map(({ finding }) => finding.checkId).join(", ");
+      lines.push(`Scoped out: ${input.scopedOutFindings.length} informational findings not applicable to --agent ${input.agent}; not repair targets for this scope: ${checkIds}.`);
     }
     lines.push(`Exit: ${input.exitCode}`);
     return lines.join("\n");

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

@@ -127,7 +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 提案にしない。<!-- @work-item-id WI-178 -->
+- 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` は意図的な抑制で、`currentScopeRepairTarget: false` と `repairModeApplicability: "only-if-agent-selected"` は raw `repairMode` が current scope の修復指示ではないという印である。<!-- @work-item-id WI-178, WI-179, WI-180 -->
 - `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,7 +132,7 @@ 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 情報」であり修復対象ではないと説明する。full doctor は両 agent を導入したい場合の診断として扱う。<!-- @work-item-id WI-178 -->
+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` は意図的な抑制で、`currentScopeRepairTarget: false` と `repairModeApplicability: "only-if-agent-selected"` は `repairMode` が current scope の修復指示ではないという印である。full doctor は両 agent を導入したい場合の診断として扱う。<!-- @work-item-id WI-178, WI-179, WI-180 -->
 
 `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 -->