phasegate 0.283.0 → 0.315.0

package/scripts/harness/harness-error/infrastructure/registry/l4-error-definitions.ts

@@ -3,73 +3,88 @@
  * @unit harness-error
  * @work-item-id WI-156
  */
-import { AdrRef } from '../../domain/value-objects/adr-ref.js';
-import { ErrorCode } from '../../domain/value-objects/error-code.js';
-import { ErrorDefinition } from '../../domain/value-objects/error-definition.js';
-import { FixExample } from '../../domain/value-objects/fix-example.js';
-import { Severity } from '../../domain/value-objects/severity.js';
+import { AdrRef } from "../../domain/value-objects/adr-ref.js";
+import { ErrorCode } from "../../domain/value-objects/error-code.js";
+import { ErrorDefinition } from "../../domain/value-objects/error-definition.js";
+import { FixExample } from "../../domain/value-objects/fix-example.js";
+import { Severity } from "../../domain/value-objects/severity.js";
 
 function createDefinition(input: {
   code: string;
   title: string;
-  category: 'phase_gate' | 'architecture' | 'dependency' | 'quality' | 'security' | 'performance' | 'consistency' | 'metadata';
+  category:
+    | "phase_gate"
+    | "architecture"
+    | "dependency"
+    | "quality"
+    | "security"
+    | "performance"
+    | "consistency"
+    | "metadata";
   ownerValidatorId: string;
   defaultFixExample: string;
+  defaultRemediationType?: "mechanical" | "ai-assisted" | "manual";
 }): ErrorDefinition {
   return ErrorDefinition.create({
     code: ErrorCode.create(input.code),
     title: input.title,
     category: input.category,
-    defaultSeverity: Severity.create('warning'),
+    defaultSeverity: Severity.create("warning"),
     adrRefRequired: true,
-    defaultAdrRef: AdrRef.create('ADR-004'),
+    defaultAdrRef: AdrRef.create("ADR-004"),
     fixExampleRequired: true,
     defaultFixExample: FixExample.create(input.defaultFixExample),
     ownerValidatorId: input.ownerValidatorId,
+    defaultRemediationType: input.defaultRemediationType ?? null,
   });
 }
 
 export const L4_ERROR_DEFINITIONS = Object.freeze([
   createDefinition({
-    code: 'L4-001',
-    title: '設計と実装の乖離が検出された',
-    category: 'consistency',
-    ownerValidatorId: 'drift-detect',
+    code: "L4-001",
+    title: "設計と実装の乖離が検出された",
+    category: "consistency",
+    ownerValidatorId: "drift-detect",
     defaultFixExample: 'const actual = "align implementation with design";',
+    // WI-335: design drift の解消は設計意図の理解が必要で機械適用不能だが、
+    // AI エージェントが設計文書を読んで自己修正できる（ai-assisted）。
+    defaultRemediationType: "ai-assisted",
   }),
   createDefinition({
-    code: 'L4-002',
-    title: '文書間の整合性が崩れている',
-    category: 'consistency',
-    ownerValidatorId: 'consistency-check',
+    code: "L4-002",
+    title: "文書間の整合性が崩れている",
+    category: "consistency",
+    ownerValidatorId: "consistency-check",
     defaultFixExample: 'const actual = "synchronize documentation";',
+    // WI-335: 文書間整合の回復は「どちらの記述が正か」の判断を伴う（ai-assisted）。
+    defaultRemediationType: "ai-assisted",
   }),
   createDefinition({
-    code: 'L4-003',
-    title: '未使用コードが検出された',
-    category: 'consistency',
-    ownerValidatorId: 'dead-code',
+    code: "L4-003",
+    title: "未使用コードが検出された",
+    category: "consistency",
+    ownerValidatorId: "dead-code",
     defaultFixExample: 'const actual = "remove unused export";',
   }),
   createDefinition({
-    code: 'L4-004',
-    title: '設計ドキュメントの鮮度が閾値を超過した',
-    category: 'consistency',
-    ownerValidatorId: 'doc-freshness',
+    code: "L4-004",
+    title: "設計ドキュメントの鮮度が閾値を超過した",
+    category: "consistency",
+    ownerValidatorId: "doc-freshness",
     defaultFixExample: 'const actual = "review or refresh stale design document";',
   }),
   createDefinition({
-    code: 'L4-005',
-    title: '設計ドキュメント内のポインタ参照が解決できない',
-    category: 'consistency',
-    ownerValidatorId: 'pointer-validation',
+    code: "L4-005",
+    title: "設計ドキュメント内のポインタ参照が解決できない",
+    category: "consistency",
+    ownerValidatorId: "pointer-validation",
     defaultFixExample: 'const actual = "fix unresolved document pointer";',
   }),
   createDefinition({
-    code: 'L4-006',
-    title: 'スキルカタログ数とドキュメント宣言が一致しない',
-    category: 'consistency',
-    ownerValidatorId: 'skill-catalog-drift',
+    code: "L4-006",
+    title: "スキルカタログ数とドキュメント宣言が一致しない",
+    category: "consistency",
+    ownerValidatorId: "skill-catalog-drift",
     defaultFixExample: 'const actual = "update skill count declarations with the skill catalog";',
   }),
 ]);

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

@@ -1,9 +1,10 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-215
+// @work-item-id WI-343
 
 import type { FileInspectorPort } from "../ports/file-inspector-port.js";
-import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { HeuristicCheck, HeuristicCheckContext } from "../../domain/ports/heuristic-check.js";
 import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
 import { createFinding, projectPath } from "./check-utils.js";
 
@@ -15,20 +16,25 @@ export class ClaudeContextMissingCheck implements HeuristicCheck {
   private readonly projectTarget = "CLAUDE.md";
   private readonly legacyTarget = ".claude/CLAUDE.local.md";
 
-  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+  async run(
+    projectRoot: string,
+    inspector: FileInspectorPort,
+    context?: HeuristicCheckContext,
+  ): Promise<DiagnosticFinding | null> {
     const content = await inspector.readText(projectPath(projectRoot, this.target));
-    if (content?.includes(MARKDOWN_BEGIN) === true && content.includes("PhaseGate")) return null;
+    if (content?.includes(MARKDOWN_BEGIN) === true && /phasegate/i.test(content)) return null;
     const projectContent = await inspector.readText(projectPath(projectRoot, this.projectTarget));
-    if (projectContent?.includes(MARKDOWN_BEGIN) === true && projectContent.includes("PhaseGate")) return null;
+    if (projectContent?.includes(MARKDOWN_BEGIN) === true && /phasegate/i.test(projectContent)) return null;
 
     const legacyContent = await inspector.readText(projectPath(projectRoot, this.legacyTarget));
+    const target = context?.installationMode === "project" ? this.projectTarget : this.target;
     return createFinding({
       checkId: this.checkId,
       severity: "red",
-      target: this.target,
-      message: legacyContent?.includes("PhaseGate") === true
+      target,
+      message: legacyContent !== null && /phasegate/i.test(legacyContent)
         ? ".claude/CLAUDE.local.md は Claude Code の documented discovery path ではありません"
-        : ".claude/CLAUDE.md に runtime-visible PhaseGate context がありません",
+        : `${target} に runtime-visible PhaseGate context がありません`,
       repairMode: "mechanical",
     });
   }

package/scripts/harness/installation/application/checks/config-status-check.ts

@@ -0,0 +1,52 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-330
+
+import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { ConfigStatusProbePort } from "../ports/config-status-probe-port.js";
+import type { FileInspectorPort } from "../ports/file-inspector-port.js";
+import { createFinding } from "./check-utils.js";
+
+/**
+ * WI-330 (GitHub #40 恒久化): phasegate.config.json の存在・妥当性を doctor で可視化する。
+ * - missing        → warn（既定設定の fail-open で動作していることをユーザーに知らせる）
+ * - invalid-json / invalid-schema → red（意図した設定が適用されていない）
+ * - valid          → finding なし
+ */
+export class ConfigStatusCheck implements HeuristicCheck {
+  readonly checkId = "config-status" as const;
+
+  constructor(private readonly probe: ConfigStatusProbePort) {}
+
+  async run(projectRoot: string, _inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const result = await this.probe.probe(projectRoot);
+    if (result.status === "valid") {
+      return null;
+    }
+    if (result.status === "missing") {
+      return createFinding({
+        checkId: this.checkId,
+        severity: "warn",
+        target: result.configPath,
+        message:
+          "phasegate.config.json が存在しません（既定設定の fail-open モードで動作中）。`phasegate init` で生成できます",
+        repairMode: "mechanical",
+        repairHint: "npx phasegate init",
+      });
+    }
+    const reason = result.status === "invalid-json" ? "JSON 構文エラー" : "スキーマ違反";
+    const detail = result.detail !== null && result.detail.length > 0 ? ` — ${result.detail}` : "";
+    return createFinding({
+      checkId: this.checkId,
+      severity: "red",
+      target: result.configPath,
+      message: `phasegate.config.json が${reason}で壊れており、ユーザーの意図した設定が適用されていません（既定設定の fail-open モードで動作中）${detail}`,
+      repairMode: "manual",
+      repairHint:
+        result.status === "invalid-json"
+          ? "phasegate.config.json の JSON 構文エラーを修正するか、version control から復元してください"
+          : "報告されたパス・型のスキーマ違反を phasegate.config.json 上で修正するか、version control から復元してください",
+    });
+  }
+}

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

@@ -1,6 +1,7 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-145
+// @work-item-id WI-340
 
 import type { FileInspectorPort } from "../ports/file-inspector-port.js";
 import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
@@ -22,6 +23,11 @@ export class HuskyPreCommitMissingCheck implements HeuristicCheck {
         "main.ts check-phase-gate",
         "$HARNESS_CMD lint",
         "$HARNESS_CMD check-phase-gate",
+        "phasegate pre-commit",
+        "main.ts pre-commit",
+        "$PHASEGATE_CMD lint",
+        "$PHASEGATE_CMD check-phase-gate",
+        "$PHASEGATE_CMD pre-commit",
       ])
     ) {
       return null;

package/scripts/harness/installation/application/ports/config-status-probe-port.ts

@@ -0,0 +1,9 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-330
+
+import type { ConfigStatusProbeResult } from "../../domain/config-status.js";
+
+export interface ConfigStatusProbePort {
+  probe(projectRoot: string): Promise<ConfigStatusProbeResult>;
+}

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

@@ -4,11 +4,15 @@
 // @work-item-id WI-178
 // @work-item-id WI-208
 // @work-item-id WI-215
+// @work-item-id WI-330
+// @work-item-id WI-343
 
-import { DiagnosticReport } from "../../domain/diagnostic-report.js";
 import type { CheckId } from "../../domain/check-id.js";
+import type { ConfigStatus } from "../../domain/config-status.js";
 import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import { DiagnosticReport } from "../../domain/diagnostic-report.js";
 import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { ConfigStatusProbePort } from "../ports/config-status-probe-port.js";
 import type { FileInspectorPort } from "../ports/file-inspector-port.js";
 import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
 
@@ -29,6 +33,7 @@ export interface RunDoctorDiagnosticsOutput {
   readonly report: DiagnosticReport;
   readonly agent: DoctorAgentScope;
   readonly installationMode: "project" | "personal";
+  readonly configStatus: ConfigStatus;
   readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[];
   readonly exitCode: number;
 }
@@ -48,15 +53,22 @@ export class RunDoctorDiagnosticsUseCase {
     private readonly checks: readonly HeuristicCheck[],
     private readonly inspector: FileInspectorPort,
     private readonly manifestRepository: ManifestRepositoryPort,
+    private readonly configStatusProbe: ConfigStatusProbePort,
   ) {}
 
   async execute(input: RunDoctorDiagnosticsInput): Promise<RunDoctorDiagnosticsOutput> {
     const agent = input.agent ?? "both";
     const manifest = await this.manifestRepository.load(input.projectRoot).catch(() => null);
-    const installationMode = manifest?.findEntry(".phasegate-local/phasegate.config.json") !== null && manifest !== null ? "personal" : "project";
-    const rawFindings = (await Promise.all(
-      this.checks.map((check) => check.run(input.projectRoot, this.inspector)),
-    )).filter((finding) => finding !== null);
+    const installationMode =
+      manifest?.findEntry(".phasegate-local/phasegate.config.json") !== null && manifest !== null
+        ? "personal"
+        : "project";
+    const configStatus = (await this.configStatusProbe.probe(input.projectRoot)).status;
+    const rawFindings = (
+      await Promise.all(
+        this.checks.map((check) => check.run(input.projectRoot, this.inspector, { installationMode })),
+      )
+    ).filter((finding) => finding !== null);
     const { findings, scopedOutFindings } = this.applyPersonalScope(
       this.applyAgentScope(rawFindings, agent),
       installationMode,
@@ -66,6 +78,7 @@ export class RunDoctorDiagnosticsUseCase {
       report,
       agent,
       installationMode,
+      configStatus,
       scopedOutFindings,
       exitCode: this.decideExitCode(report, input.strict),
     };
@@ -74,7 +87,10 @@ export class RunDoctorDiagnosticsUseCase {
   private applyAgentScope(
     findings: readonly DiagnosticFinding[],
     agent: DoctorAgentScope,
-  ): { readonly findings: readonly DiagnosticFinding[]; readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[] } {
+  ): {
+    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[] = [];
@@ -93,9 +109,15 @@ export class RunDoctorDiagnosticsUseCase {
   }
 
   private applyPersonalScope(
-    scoped: { readonly findings: readonly DiagnosticFinding[]; readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[] },
+    scoped: {
+      readonly findings: readonly DiagnosticFinding[];
+      readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[];
+    },
     installationMode: "project" | "personal",
-  ): { readonly findings: readonly DiagnosticFinding[]; readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[] } {
+  ): {
+    readonly findings: readonly DiagnosticFinding[];
+    readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[];
+  } {
     if (installationMode !== "personal") return scoped;
     const applicable: DiagnosticFinding[] = [];
     const scopedOut: ScopedOutDiagnosticFinding[] = [...scoped.scopedOutFindings];

package/scripts/harness/installation/application/usecases/run-install.ts

@@ -18,6 +18,7 @@
 // @work-item-id WI-219
 // @work-item-id WI-315
 // @work-item-id WI-326
+// @work-item-id WI-331
 
 import {
   access,
@@ -121,6 +122,7 @@ const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
 const MARKDOWN_END = "<!-- phasegate:managed-section:end -->";
 const USER_SECTION_BEGIN = "<!-- phasegate:user-section:start -->";
 const USER_SECTION_END = "<!-- phasegate:user-section:end -->";
+const USER_SECTION_PLACEHOLDER = "Project-specific agent instructions go here.";
 const TEXT_BEGIN = "# phasegate personal install exclude (BEGIN)";
 const TEXT_END = "# phasegate personal install exclude (END)";
 const PERSONAL_AGENT_RUNTIME_FILES = new Set([
@@ -301,11 +303,18 @@ function extractUserSectionBody(content: string | null): string | null {
   return body.length === 0 ? null : body;
 }
 
-// The CLAUDE.md template nests the user-section inside the managed section, so
-// replacing the managed block wholesale would wipe user-authored instructions
-// with the template placeholder. Re-inject the existing user-section body into
-// the incoming block. Templates whose managed block carries no user-section
-// markers (e.g. AGENTS.md) are returned unchanged.
+function hasUserSectionMarkers(content: string): boolean {
+  const start = content.indexOf(USER_SECTION_BEGIN);
+  const end = content.indexOf(USER_SECTION_END);
+  return start !== -1 && end !== -1 && start < end;
+}
+
+// Legacy (pre-WI-331) templates nested the user-section inside the managed
+// section, so replacing the managed block wholesale would wipe user-authored
+// instructions with the template placeholder. Re-inject the existing
+// user-section body into the incoming block. Blocks without user-section
+// markers (all current templates) are returned unchanged; the outside-of-block
+// migration for those is handled in mergeManagedMarkdown.
 function restoreUserSection(block: string, existing: string | null): string {
   const start = block.indexOf(USER_SECTION_BEGIN);
   const end = block.indexOf(USER_SECTION_END);
@@ -317,12 +326,36 @@ function restoreUserSection(block: string, existing: string | null): string {
 
 function mergeManagedMarkdown(existing: string | null, incoming: string): string {
   if (existing === null || existing.trim().length === 0) return `${incoming.trim()}\n`;
-  const block = restoreUserSection(managedMarkdownBlock(incoming), existing);
+  const incomingBlock = managedMarkdownBlock(incoming);
   const pattern = new RegExp(`${escapeRegExp(MARKDOWN_BEGIN)}[\\s\\S]*?${escapeRegExp(MARKDOWN_END)}`);
-  // Replacer function keeps user-authored text (now part of the block) from
-  // being interpreted as `$`-substitution patterns by String.replace.
-  if (pattern.test(existing)) return existing.replace(pattern, () => block).replace(/\s*$/, "\n");
-  return `${block}\n\n${existing.replace(/\s*$/, "\n")}`;
+  if (!pattern.test(existing)) return `${incomingBlock}\n\n${existing.replace(/\s*$/, "\n")}`;
+
+  const blockStart = existing.indexOf(MARKDOWN_BEGIN);
+  const blockEnd = existing.indexOf(MARKDOWN_END) + MARKDOWN_END.length;
+  const existingBlock = existing.slice(blockStart, blockEnd);
+  const outsideBlock = existing.slice(0, blockStart) + existing.slice(blockEnd);
+  const block = restoreUserSection(incomingBlock, existing);
+  // Replacer function keeps user-authored text (possibly part of the block)
+  // from being interpreted as `$`-substitution patterns by String.replace.
+  let next = existing.replace(pattern, () => block);
+
+  // Structure migration (WI-331): the existing file nests the user-section
+  // inside the managed block (old template shape) while the incoming block
+  // keeps it outside. Replacing the block would drop the user-authored body,
+  // so relocate it to just after the managed block — the position the current
+  // template uses. When a user-section already exists outside the block, keep
+  // that one and do not duplicate.
+  if (
+    hasUserSectionMarkers(existingBlock) &&
+    !hasUserSectionMarkers(incomingBlock) &&
+    !hasUserSectionMarkers(outsideBlock)
+  ) {
+    const body = extractUserSectionBody(existingBlock) ?? USER_SECTION_PLACEHOLDER;
+    const insertAt = next.indexOf(MARKDOWN_END) + MARKDOWN_END.length;
+    const relocated = `\n\n## User Section\n\n${USER_SECTION_BEGIN}\n${body}\n${USER_SECTION_END}`;
+    next = `${next.slice(0, insertAt)}${relocated}${next.slice(insertAt)}`;
+  }
+  return next.replace(/\s*$/, "\n");
 }
 
 function renderAgentContextTemplate(
@@ -351,7 +384,7 @@ function renderAgentContextTemplate(
     .replaceAll("{{PHASEGATE_COMMANDS}}", commands)
     .replaceAll("{{PHASEGATE_SKILLS}}", options.skillSet === "core" ? "- `core skills`" : "- `all bundled skills`")
     .replaceAll("{{PHASEGATE_PRESETS}}", "- `minimal`\n- `standard`\n- `full`\n- `custom`")
-    .replaceAll("{{PHASEGATE_USER_SECTION}}", "Project-specific agent instructions go here.");
+    .replaceAll("{{PHASEGATE_USER_SECTION}}", USER_SECTION_PLACEHOLDER);
 }
 
 function escapeRegExp(value: string): string {

package/scripts/harness/installation/application/usecases/run-reconcile.ts

@@ -9,6 +9,7 @@
 // @work-item-id WI-264
 // @work-item-id WI-315
 // @work-item-id WI-326
+// @work-item-id WI-331
 
 import {
   access,
@@ -92,6 +93,7 @@ const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
 const MARKDOWN_END = "<!-- phasegate:managed-section:end -->";
 const USER_SECTION_BEGIN = "<!-- phasegate:user-section:start -->";
 const USER_SECTION_END = "<!-- phasegate:user-section:end -->";
+const USER_SECTION_PLACEHOLDER = "Project-specific agent instructions go here.";
 const SHARED_SKILLS_VERSION_PATH = "skills/.harness-version";
 const HARNESS_VERSION_BASENAME = ".harness-version";
 const SKILL_ROOT_PREFIXES = ["skills", ".claude/skills", ".codex/skills"] as const;
@@ -265,11 +267,18 @@ function extractUserSectionBody(content: string | null): string | null {
   return body.length === 0 ? null : body;
 }
 
-// The CLAUDE.md template nests the user-section inside the managed section, so
-// replacing the managed block wholesale would wipe user-authored instructions
-// with the template placeholder. Re-inject the existing user-section body into
-// the incoming block. Templates whose managed block carries no user-section
-// markers (e.g. AGENTS.md) are returned unchanged.
+function hasUserSectionMarkers(content: string): boolean {
+  const start = content.indexOf(USER_SECTION_BEGIN);
+  const end = content.indexOf(USER_SECTION_END);
+  return start !== -1 && end !== -1 && start < end;
+}
+
+// Legacy (pre-WI-331) templates nested the user-section inside the managed
+// section, so replacing the managed block wholesale would wipe user-authored
+// instructions with the template placeholder. Re-inject the existing
+// user-section body into the incoming block. Blocks without user-section
+// markers (all current templates) are returned unchanged; the outside-of-block
+// migration for those is handled in reconcileManagedMarkdown.
 function restoreUserSection(block: string, existing: string | null): string {
   const start = block.indexOf(USER_SECTION_BEGIN);
   const end = block.indexOf(USER_SECTION_END);
@@ -281,12 +290,36 @@ function restoreUserSection(block: string, existing: string | null): string {
 
 function reconcileManagedMarkdown(existing: string | null, incoming: string): string {
   if (existing === null || existing.trim().length === 0) return `${incoming.trim()}\n`;
-  const block = restoreUserSection(managedMarkdownBlock(incoming), existing);
+  const incomingBlock = managedMarkdownBlock(incoming);
   const pattern = new RegExp(`${escapeRegExp(MARKDOWN_BEGIN)}[\\s\\S]*?${escapeRegExp(MARKDOWN_END)}`);
-  // Replacer function keeps user-authored text (now part of the block) from
-  // being interpreted as `$`-substitution patterns by String.replace.
-  if (pattern.test(existing)) return existing.replace(pattern, () => block).replace(/\s*$/, "\n");
-  return `${block}\n\n${existing.replace(/\s*$/, "\n")}`;
+  if (!pattern.test(existing)) return `${incomingBlock}\n\n${existing.replace(/\s*$/, "\n")}`;
+
+  const blockStart = existing.indexOf(MARKDOWN_BEGIN);
+  const blockEnd = existing.indexOf(MARKDOWN_END) + MARKDOWN_END.length;
+  const existingBlock = existing.slice(blockStart, blockEnd);
+  const outsideBlock = existing.slice(0, blockStart) + existing.slice(blockEnd);
+  const block = restoreUserSection(incomingBlock, existing);
+  // Replacer function keeps user-authored text (possibly part of the block)
+  // from being interpreted as `$`-substitution patterns by String.replace.
+  let next = existing.replace(pattern, () => block);
+
+  // Structure migration (WI-331): the existing file nests the user-section
+  // inside the managed block (old template shape) while the incoming block
+  // keeps it outside. Replacing the block would drop the user-authored body,
+  // so relocate it to just after the managed block — the position the current
+  // template uses. When a user-section already exists outside the block, keep
+  // that one and do not duplicate.
+  if (
+    hasUserSectionMarkers(existingBlock) &&
+    !hasUserSectionMarkers(incomingBlock) &&
+    !hasUserSectionMarkers(outsideBlock)
+  ) {
+    const body = extractUserSectionBody(existingBlock) ?? USER_SECTION_PLACEHOLDER;
+    const insertAt = next.indexOf(MARKDOWN_END) + MARKDOWN_END.length;
+    const relocated = `\n\n## User Section\n\n${USER_SECTION_BEGIN}\n${body}\n${USER_SECTION_END}`;
+    next = `${next.slice(0, insertAt)}${relocated}${next.slice(insertAt)}`;
+  }
+  return next.replace(/\s*$/, "\n");
 }
 
 function renderAgentContextTemplate(template: string): string {
@@ -308,7 +341,7 @@ function renderAgentContextTemplate(template: string): string {
     .replaceAll("{{PHASEGATE_COMMANDS}}", commands)
     .replaceAll("{{PHASEGATE_SKILLS}}", "- `all bundled skills`")
     .replaceAll("{{PHASEGATE_PRESETS}}", "- `minimal`\n- `standard`\n- `full`\n- `custom`")
-    .replaceAll("{{PHASEGATE_USER_SECTION}}", "Project-specific agent instructions go here.");
+    .replaceAll("{{PHASEGATE_USER_SECTION}}", USER_SECTION_PLACEHOLDER);
 }
 
 function reconcilePackageJson(existing: Record<string, unknown>, version: string): Record<string, unknown> {

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

@@ -3,26 +3,29 @@
 // @work-item-id WI-145
 // @work-item-id WI-148
 // @work-item-id WI-215
+// @work-item-id WI-330
 
+import { CiWorkflowMissingCheck } from "./application/checks/ci-workflow-missing-check.js";
 import { ClaudeContextMissingCheck } from "./application/checks/claude-context-missing-check.js";
 import { ClaudeHookMissingCheck } from "./application/checks/claude-hook-missing-check.js";
 import { ClaudeSkillsSymlinkCheck } from "./application/checks/claude-skills-symlink-check.js";
 import { CodexContextMissingCheck } from "./application/checks/codex-context-missing-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 { ConfigStatusCheck } from "./application/checks/config-status-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 { WiWorkflowDriftCheck } from "./application/checks/wi-workflow-drift-check.js";
+import { RunDoctorDiagnosticsUseCase } from "./application/usecases/run-doctor-diagnostics.js";
 import { RunInstallUseCase } from "./application/usecases/run-install.js";
 import { RunReconcileUseCase } from "./application/usecases/run-reconcile.js";
 import { RunUninstallUseCase } from "./application/usecases/run-uninstall.js";
-import { RunDoctorDiagnosticsUseCase } from "./application/usecases/run-doctor-diagnostics.js";
 import type { MergeStrategy } from "./domain/ports/merge-strategy.js";
 import type { ReconcileStrategy } from "./domain/ports/reconcile-strategy.js";
 import type { UninstallReverseStrategy } from "./domain/ports/uninstall-reverse-strategy.js";
+import { ConfigStatusProbeAdapter } from "./infrastructure/adapters/config-status-probe-adapter.js";
 import { FileSystemManifestRepositoryAdapter } from "./infrastructure/adapters/file-system-manifest-repository-adapter.js";
 import { NodeCryptoHashAdapter } from "./infrastructure/adapters/node-crypto-hash-adapter.js";
 import { NodeFsFileInspectorAdapter } from "./infrastructure/adapters/node-fs-file-inspector-adapter.js";
@@ -45,6 +48,7 @@ export function createInstallationModule() {
   const manifestRepository = new FileSystemManifestRepositoryAdapter();
   const hashCalculator = new NodeCryptoHashAdapter();
   const modelDelegation = new SkillDeployerModelDelegationAdapter();
+  const configStatusProbe = new ConfigStatusProbeAdapter();
   const checks = [
     new ClaudeHookMissingCheck(),
     new ClaudeContextMissingCheck(),
@@ -58,8 +62,14 @@ export function createInstallationModule() {
     new ClaudeSkillsSymlinkCheck(),
     new CodexSkillsSymlinkCheck(),
     new WiWorkflowDriftCheck(),
+    new ConfigStatusCheck(configStatusProbe),
   ];
-  const runDoctorDiagnosticsUseCase = new RunDoctorDiagnosticsUseCase(checks, inspector, manifestRepository);
+  const runDoctorDiagnosticsUseCase = new RunDoctorDiagnosticsUseCase(
+    checks,
+    inspector,
+    manifestRepository,
+    configStatusProbe,
+  );
   const runInstallUseCase = new RunInstallUseCase(manifestRepository, hashCalculator, modelDelegation);
   const runReconcileUseCase = new RunReconcileUseCase(manifestRepository, hashCalculator, modelDelegation);
   const runUninstallUseCase = new RunUninstallUseCase(manifestRepository, hashCalculator);

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

@@ -2,6 +2,7 @@
 // @layer domain
 // @work-item-id WI-145
 // @work-item-id WI-215
+// @work-item-id WI-330
 
 export const CHECK_IDS = [
   "claude-hook-missing",
@@ -16,6 +17,7 @@ export const CHECK_IDS = [
   "claude-skills-symlink",
   "codex-skills-symlink",
   "wi-workflow-drift",
+  "config-status",
 ] as const;
 
 export type CheckId = (typeof CHECK_IDS)[number];

package/scripts/harness/installation/domain/config-status.ts

@@ -0,0 +1,17 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-330
+
+export const CONFIG_STATUSES = ["missing", "invalid-json", "invalid-schema", "valid"] as const;
+
+export type ConfigStatus = (typeof CONFIG_STATUSES)[number];
+
+export function isConfigStatus(value: string): value is ConfigStatus {
+  return (CONFIG_STATUSES as readonly string[]).includes(value);
+}
+
+export interface ConfigStatusProbeResult {
+  readonly status: ConfigStatus;
+  readonly configPath: string;
+  readonly detail: string | null;
+}

package/scripts/harness/installation/domain/ports/heuristic-check.ts

@@ -1,12 +1,21 @@
 // @unit installation
 // @layer domain
 // @work-item-id WI-145
+// @work-item-id WI-343
 
 import type { CheckId } from "../check-id.js";
 import type { DiagnosticFinding } from "../diagnostic-finding.js";
 import type { FileInspector } from "./file-inspector.js";
 
+export interface HeuristicCheckContext {
+  readonly installationMode: "project" | "personal";
+}
+
 export interface HeuristicCheck {
   readonly checkId: CheckId;
-  run(projectRoot: string, inspector: FileInspector): Promise<DiagnosticFinding | null>;
+  run(
+    projectRoot: string,
+    inspector: FileInspector,
+    context?: HeuristicCheckContext,
+  ): Promise<DiagnosticFinding | null>;
 }