phasegate 0.144.1 → 0.145.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.145.0] - 2026-05-11
+
+### Added
+
+- **WI-145 — installation doctor / manifest foundation** — `phasegate doctor` を追加し、Claude / Codex hooks、Husky hooks、CI workflow、package dependency、skills symlink の 9 checks で inert / partial installation を診断できるようにした。
+  - `--json`、`--strict`、`--report-out` に対応し、4 fixture (`no-phasegate` / `inert-install` / `partial-install` / `full-install`) の golden integration test で出力と exit code を固定した。
+  - init / update-skills 経路で `.phasegate/manifest.json` の薄い書き出しを開始し、manifest entries の `path` / `mode` / `hash` / `deployedAt` を unit test で固定した。
+  - doctor の false positive / false negative を防ぐため、9 checks すべてに unit test を追加した。
+
+### Fixed
+
+- **WI-145 follow-up — L1 blocker cleanup** — validator-system の integration test fixture 内にあった internal module mock 文字列が L1-017 に検出されていた既存違反を解消した。
+
 ## [0.144.1] - 2026-05-10
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.144.1",
+  "version": "0.145.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/checks/check-utils.ts

@@ -0,0 +1,65 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import { join } from "node:path";
+import type { CheckId } from "../../domain/check-id.js";
+import { DiagnosticFinding, type DiagnosticSeverity } from "../../domain/diagnostic-finding.js";
+import type { RepairMode } from "../../domain/repair-mode.js";
+import { RepairTable } from "../../domain/repair-table.js";
+import type { SuggestedSkill } from "../../domain/suggested-skill.js";
+
+const PHASEGATE_REPAIR_HINT = "npx phasegate install --apply";
+
+export function projectPath(projectRoot: string, relativePath: string): string {
+  return join(projectRoot, relativePath);
+}
+
+export function containsPhasegateHook(value: unknown): boolean {
+  if (typeof value === "string") {
+    return value.includes("npx phasegate hook") || value.includes("phasegate hook");
+  }
+  if (Array.isArray(value)) return value.some((item) => containsPhasegateHook(item));
+  if (value !== null && typeof value === "object") {
+    return Object.values(value as Record<string, unknown>).some((item) => containsPhasegateHook(item));
+  }
+  return false;
+}
+
+export function hasUserCustomization(value: unknown): boolean {
+  if (value === null || value === undefined) return false;
+  if (typeof value === "string") return value.trim().length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "object") return Object.keys(value as Record<string, unknown>).length > 0;
+  return false;
+}
+
+export function scriptHasPhasegateBlock(content: string, commands: readonly string[]): boolean {
+  return commands.some((command) => content.includes(command));
+}
+
+export function createFinding(input: {
+  readonly checkId: CheckId;
+  readonly severity: DiagnosticSeverity;
+  readonly target: string;
+  readonly message: string;
+  readonly repairMode: RepairMode;
+  readonly repairHint?: string | null;
+  readonly suggestedSkill?: SuggestedSkill | null;
+}): DiagnosticFinding {
+  return DiagnosticFinding.create({
+    checkId: input.checkId,
+    severity: input.severity,
+    target: input.target,
+    message: input.message,
+    repairMode: input.repairMode,
+    repairHint: input.repairHint ?? (input.repairMode === "mechanical" ? PHASEGATE_REPAIR_HINT : null),
+    suggestedSkill: input.suggestedSkill ?? new RepairTable().lookup(input.checkId),
+  });
+}
+
+export function skillTargetLooksValid(target: string | null): boolean {
+  if (target === null) return false;
+  const normalized = target.replaceAll("\\", "/").replace(/\/+$/, "");
+  return normalized === "skills" || normalized === "../skills" || normalized.endsWith("/skills");
+}

package/scripts/harness/installation/application/checks/ci-workflow-missing-check.ts

@@ -0,0 +1,29 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import type { FileInspectorPort } from "../ports/file-inspector-port.js";
+import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import { createFinding, projectPath } from "./check-utils.js";
+
+export class CiWorkflowMissingCheck implements HeuristicCheck {
+  readonly checkId = "ci-workflow-missing" as const;
+  private readonly target = ".github/workflows/";
+
+  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const files = await inspector.listFiles(projectPath(projectRoot, this.target));
+    const hasPhasegateWorkflow = files.some((file) => {
+      const normalized = file.toLowerCase();
+      return normalized.includes("phasegate") || normalized.includes("aidlc-gate") || normalized.includes("consistency-check");
+    });
+    if (hasPhasegateWorkflow) return null;
+    return createFinding({
+      checkId: this.checkId,
+      severity: "warn",
+      target: this.target,
+      message: ".github/workflows/ に phasegate workflow がありません",
+      repairMode: "manual",
+    });
+  }
+}

package/scripts/harness/installation/application/checks/claude-hook-missing-check.ts

@@ -0,0 +1,45 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import type { FileInspectorPort } from "../ports/file-inspector-port.js";
+import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import { containsPhasegateHook, createFinding, hasUserCustomization, projectPath } from "./check-utils.js";
+
+export class ClaudeHookMissingCheck implements HeuristicCheck {
+  readonly checkId = "claude-hook-missing" as const;
+  private readonly target = ".claude/settings.json";
+
+  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const absolutePath = projectPath(projectRoot, this.target);
+    const exists = await inspector.exists(absolutePath);
+    if (!exists) {
+      return createFinding({
+        checkId: this.checkId,
+        severity: "red",
+        target: this.target,
+        message: ".claude/settings.json に phasegate hook が登録されていません",
+        repairMode: "mechanical",
+      });
+    }
+    const json = await inspector.readJson(absolutePath);
+    if (json === null) {
+      return createFinding({
+        checkId: this.checkId,
+        severity: "red",
+        target: this.target,
+        message: ".claude/settings.json を JSON として読めないため phasegate hook を確認できません",
+        repairMode: "manual",
+      });
+    }
+    if (containsPhasegateHook(json)) return null;
+    return createFinding({
+      checkId: this.checkId,
+      severity: "red",
+      target: this.target,
+      message: ".claude/settings.json に phasegate hook が登録されていません",
+      repairMode: hasUserCustomization(json) ? "ai-assisted" : "mechanical",
+    });
+  }
+}

package/scripts/harness/installation/application/checks/claude-skills-symlink-check.ts

@@ -0,0 +1,25 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import type { FileInspectorPort } from "../ports/file-inspector-port.js";
+import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import { createFinding, projectPath, skillTargetLooksValid } from "./check-utils.js";
+
+export class ClaudeSkillsSymlinkCheck implements HeuristicCheck {
+  readonly checkId = "claude-skills-symlink" as const;
+  private readonly target = ".claude/skills";
+
+  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const link = await inspector.readSymlink(projectPath(projectRoot, this.target));
+    if (skillTargetLooksValid(link)) return null;
+    return createFinding({
+      checkId: this.checkId,
+      severity: "red",
+      target: this.target,
+      message: ".claude/skills が phasegate skills を指していません",
+      repairMode: link === null ? "mechanical" : "manual",
+    });
+  }
+}

package/scripts/harness/installation/application/checks/codex-hook-missing-check.ts

@@ -0,0 +1,44 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import type { FileInspectorPort } from "../ports/file-inspector-port.js";
+import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import { containsPhasegateHook, createFinding, hasUserCustomization, projectPath } from "./check-utils.js";
+
+export class CodexHookMissingCheck implements HeuristicCheck {
+  readonly checkId = "codex-hook-missing" as const;
+  private readonly target = ".codex/hooks.json";
+
+  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const absolutePath = projectPath(projectRoot, this.target);
+    if (!(await inspector.exists(absolutePath))) {
+      return createFinding({
+        checkId: this.checkId,
+        severity: "red",
+        target: this.target,
+        message: ".codex/hooks.json に phasegate hook が登録されていません",
+        repairMode: "mechanical",
+      });
+    }
+    const json = await inspector.readJson(absolutePath);
+    if (json === null) {
+      return createFinding({
+        checkId: this.checkId,
+        severity: "red",
+        target: this.target,
+        message: ".codex/hooks.json を JSON として読めないため phasegate hook を確認できません",
+        repairMode: "manual",
+      });
+    }
+    if (containsPhasegateHook(json)) return null;
+    return createFinding({
+      checkId: this.checkId,
+      severity: "red",
+      target: this.target,
+      message: ".codex/hooks.json に phasegate hook が登録されていません",
+      repairMode: hasUserCustomization(json) ? "ai-assisted" : "mechanical",
+    });
+  }
+}

package/scripts/harness/installation/application/checks/codex-skills-symlink-check.ts

@@ -0,0 +1,25 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import type { FileInspectorPort } from "../ports/file-inspector-port.js";
+import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import { createFinding, projectPath, skillTargetLooksValid } from "./check-utils.js";
+
+export class CodexSkillsSymlinkCheck implements HeuristicCheck {
+  readonly checkId = "codex-skills-symlink" as const;
+  private readonly target = ".codex/skills";
+
+  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const link = await inspector.readSymlink(projectPath(projectRoot, this.target));
+    if (skillTargetLooksValid(link)) return null;
+    return createFinding({
+      checkId: this.checkId,
+      severity: "red",
+      target: this.target,
+      message: ".codex/skills が phasegate skills を指していません",
+      repairMode: link === null ? "mechanical" : "manual",
+    });
+  }
+}

package/scripts/harness/installation/application/checks/husky-commit-msg-missing-check.ts

@@ -0,0 +1,25 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import type { FileInspectorPort } from "../ports/file-inspector-port.js";
+import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import { createFinding, projectPath, scriptHasPhasegateBlock } from "./check-utils.js";
+
+export class HuskyCommitMsgMissingCheck implements HeuristicCheck {
+  readonly checkId = "husky-commit-msg-missing" as const;
+  private readonly target = ".husky/commit-msg";
+
+  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const content = await inspector.readText(projectPath(projectRoot, this.target));
+    if (content !== null && scriptHasPhasegateBlock(content, ["phasegate commit-msg"])) return null;
+    return createFinding({
+      checkId: this.checkId,
+      severity: "red",
+      target: this.target,
+      message: ".husky/commit-msg に phasegate commit-msg hook がありません",
+      repairMode: content === null || content.trim().length === 0 ? "mechanical" : "ai-assisted",
+    });
+  }
+}

package/scripts/harness/installation/application/checks/husky-pre-commit-missing-check.ts

@@ -0,0 +1,37 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import type { FileInspectorPort } from "../ports/file-inspector-port.js";
+import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import { createFinding, projectPath, scriptHasPhasegateBlock } from "./check-utils.js";
+
+export class HuskyPreCommitMissingCheck implements HeuristicCheck {
+  readonly checkId = "husky-pre-commit-missing" as const;
+  private readonly target = ".husky/pre-commit";
+
+  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const content = await inspector.readText(projectPath(projectRoot, this.target));
+    if (
+      content !== null &&
+      scriptHasPhasegateBlock(content, [
+        "phasegate lint",
+        "phasegate check-phase-gate",
+        "main.ts lint",
+        "main.ts check-phase-gate",
+        "$HARNESS_CMD lint",
+        "$HARNESS_CMD check-phase-gate",
+      ])
+    ) {
+      return null;
+    }
+    return createFinding({
+      checkId: this.checkId,
+      severity: "red",
+      target: this.target,
+      message: ".husky/pre-commit に phasegate lint hook がありません",
+      repairMode: content === null || content.trim().length === 0 ? "mechanical" : "ai-assisted",
+    });
+  }
+}

package/scripts/harness/installation/application/checks/husky-pre-push-missing-check.ts

@@ -0,0 +1,25 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import type { FileInspectorPort } from "../ports/file-inspector-port.js";
+import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import { createFinding, projectPath, scriptHasPhasegateBlock } from "./check-utils.js";
+
+export class HuskyPrePushMissingCheck implements HeuristicCheck {
+  readonly checkId = "husky-pre-push-missing" as const;
+  private readonly target = ".husky/pre-push";
+
+  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const content = await inspector.readText(projectPath(projectRoot, this.target));
+    if (content !== null && scriptHasPhasegateBlock(content, ["phasegate bypass:audit"])) return null;
+    return createFinding({
+      checkId: this.checkId,
+      severity: "warn",
+      target: this.target,
+      message: ".husky/pre-push に phasegate bypass:audit hook がありません",
+      repairMode: "mechanical",
+    });
+  }
+}

package/scripts/harness/installation/application/checks/package-json-devdep-missing-check.ts

@@ -0,0 +1,37 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import type { FileInspectorPort } from "../ports/file-inspector-port.js";
+import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import { createFinding, projectPath } from "./check-utils.js";
+
+interface PackageJson {
+  readonly name?: string;
+  readonly dependencies?: Record<string, string>;
+  readonly devDependencies?: Record<string, string>;
+}
+
+export class PackageJsonDevdepMissingCheck implements HeuristicCheck {
+  readonly checkId = "package-json-devdep-missing" as const;
+  private readonly target = "package.json";
+
+  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const pkg = await inspector.readJson<PackageJson>(projectPath(projectRoot, this.target));
+    if (
+      pkg?.name === "phasegate" ||
+      pkg?.devDependencies?.phasegate !== undefined ||
+      pkg?.dependencies?.phasegate !== undefined
+    ) {
+      return null;
+    }
+    return createFinding({
+      checkId: this.checkId,
+      severity: "red",
+      target: this.target,
+      message: "package.json の devDependencies に phasegate がありません",
+      repairMode: "mechanical",
+    });
+  }
+}

package/scripts/harness/installation/application/ports/file-inspector-port.ts

@@ -0,0 +1,11 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+export interface FileInspectorPort {
+  exists(absolutePath: string): Promise<boolean>;
+  readText(absolutePath: string): Promise<string | null>;
+  readJson<T = unknown>(absolutePath: string): Promise<T | null>;
+  readSymlink(absolutePath: string): Promise<string | null>;
+  listFiles(absolutePath: string): Promise<string[]>;
+}

package/scripts/harness/installation/application/ports/hash-calculator-port.ts

@@ -0,0 +1,9 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import type { Hash } from "../../domain/hash.js";
+
+export interface HashCalculatorPort {
+  compute(content: string | Buffer): Hash;
+}

package/scripts/harness/installation/application/ports/manifest-repository-port.ts

@@ -0,0 +1,12 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import type { DeploymentManifest } from "../../domain/deployment-manifest.js";
+
+export interface ManifestRepositoryPort {
+  load(projectRoot: string): Promise<DeploymentManifest | null>;
+  save(projectRoot: string, manifest: DeploymentManifest): Promise<void>;
+  exists(projectRoot: string): Promise<boolean>;
+  archive(projectRoot: string): Promise<void>;
+}

package/scripts/harness/installation/application/usecases/run-doctor-diagnostics.ts

@@ -0,0 +1,44 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import { DiagnosticReport } from "../../domain/diagnostic-report.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 interface RunDoctorDiagnosticsInput {
+  readonly projectRoot: string;
+  readonly strict: boolean;
+}
+
+export interface RunDoctorDiagnosticsOutput {
+  readonly report: DiagnosticReport;
+  readonly exitCode: number;
+}
+
+export class RunDoctorDiagnosticsUseCase {
+  constructor(
+    private readonly checks: readonly HeuristicCheck[],
+    private readonly inspector: FileInspectorPort,
+    private readonly manifestRepository: ManifestRepositoryPort,
+  ) {}
+
+  async execute(input: RunDoctorDiagnosticsInput): Promise<RunDoctorDiagnosticsOutput> {
+    await this.manifestRepository.load(input.projectRoot).catch(() => null);
+    const findings = (await Promise.all(
+      this.checks.map((check) => check.run(input.projectRoot, this.inspector)),
+    )).filter((finding) => finding !== null);
+    const report = DiagnosticReport.create(findings);
+    return {
+      report,
+      exitCode: this.decideExitCode(report, input.strict),
+    };
+  }
+
+  private decideExitCode(report: DiagnosticReport, strict: boolean): number {
+    if (report.hasRedFlag()) return 1;
+    if (strict && report.hasWarning()) return 1;
+    return 0;
+  }
+}

package/scripts/harness/installation/application/wrappers/skill-deployer-manifest-builder.ts

@@ -0,0 +1,38 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-145
+
+import { DeploymentEntry } from "../../domain/deployment-entry.js";
+import { DeploymentManifest } from "../../domain/deployment-manifest.js";
+import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
+
+export interface DeployManifestRecord {
+  readonly path: string;
+  readonly mode: "created" | "merged" | "symlink";
+  readonly contentForHash: string;
+  readonly block?: {
+    readonly start: string;
+    readonly end: string;
+    readonly content: string;
+  } | null;
+}
+
+export class SkillDeployerManifestBuilder {
+  constructor(private readonly hashCalculator: HashCalculatorPort) {}
+
+  build(version: string, records: readonly DeployManifestRecord[], deployedAt = new Date().toISOString()): DeploymentManifest {
+    let manifest = DeploymentManifest.create(version, deployedAt);
+    for (const record of records) {
+      manifest = manifest.addEntry(
+        DeploymentEntry.create({
+          path: record.path,
+          mode: record.mode,
+          block: record.block ?? null,
+          hash: this.hashCalculator.compute(record.contentForHash),
+          deployedAt,
+        }),
+      );
+    }
+    return manifest;
+  }
+}

package/scripts/harness/installation/composition-root.ts

@@ -0,0 +1,39 @@
+// @unit installation
+// @layer presentation
+// @work-item-id WI-145
+
+import { ClaudeHookMissingCheck } from "./application/checks/claude-hook-missing-check.js";
+import { ClaudeSkillsSymlinkCheck } from "./application/checks/claude-skills-symlink-check.js";
+import { CodexHookMissingCheck } from "./application/checks/codex-hook-missing-check.js";
+import { CodexSkillsSymlinkCheck } from "./application/checks/codex-skills-symlink-check.js";
+import { CiWorkflowMissingCheck } from "./application/checks/ci-workflow-missing-check.js";
+import { HuskyCommitMsgMissingCheck } from "./application/checks/husky-commit-msg-missing-check.js";
+import { HuskyPreCommitMissingCheck } from "./application/checks/husky-pre-commit-missing-check.js";
+import { HuskyPrePushMissingCheck } from "./application/checks/husky-pre-push-missing-check.js";
+import { PackageJsonDevdepMissingCheck } from "./application/checks/package-json-devdep-missing-check.js";
+import { RunDoctorDiagnosticsUseCase } from "./application/usecases/run-doctor-diagnostics.js";
+import { FileSystemManifestRepositoryAdapter } from "./infrastructure/adapters/file-system-manifest-repository-adapter.js";
+import { NodeFsFileInspectorAdapter } from "./infrastructure/adapters/node-fs-file-inspector-adapter.js";
+import { DoctorHandler } from "./presentation/cli/doctor-handler.js";
+
+export function createInstallationModule() {
+  const inspector = new NodeFsFileInspectorAdapter();
+  const manifestRepository = new FileSystemManifestRepositoryAdapter();
+  const checks = [
+    new ClaudeHookMissingCheck(),
+    new CodexHookMissingCheck(),
+    new HuskyPreCommitMissingCheck(),
+    new HuskyCommitMsgMissingCheck(),
+    new HuskyPrePushMissingCheck(),
+    new CiWorkflowMissingCheck(),
+    new PackageJsonDevdepMissingCheck(),
+    new ClaudeSkillsSymlinkCheck(),
+    new CodexSkillsSymlinkCheck(),
+  ];
+  const runDoctorDiagnosticsUseCase = new RunDoctorDiagnosticsUseCase(checks, inspector, manifestRepository);
+  return {
+    manifestRepository,
+    runDoctorDiagnosticsUseCase,
+    doctorHandler: new DoctorHandler(runDoctorDiagnosticsUseCase),
+  };
+}

package/scripts/harness/installation/domain/check-id.ts

@@ -0,0 +1,21 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-145
+
+export const CHECK_IDS = [
+  "claude-hook-missing",
+  "codex-hook-missing",
+  "husky-pre-commit-missing",
+  "husky-commit-msg-missing",
+  "husky-pre-push-missing",
+  "ci-workflow-missing",
+  "package-json-devdep-missing",
+  "claude-skills-symlink",
+  "codex-skills-symlink",
+] as const;
+
+export type CheckId = (typeof CHECK_IDS)[number];
+
+export function isCheckId(value: string): value is CheckId {
+  return (CHECK_IDS as readonly string[]).includes(value);
+}