phasegate 0.152.7 → 0.152.9

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

@@ -1,6 +1,7 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-146
+// @work-item-id WI-174
 
 import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -12,7 +13,7 @@ import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.j
 import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
 
 type InstallAction = "missing" | "will-merge" | "will-skip" | "will-overwrite";
-type StrategyType = "json" | "shell" | "yaml-add" | "package-json";
+type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "markdown-managed";
 
 export interface InstallPlanItem {
   readonly path: string;
@@ -36,6 +37,9 @@ export interface RunInstallInput {
   readonly includeCodex?: boolean;
   readonly includeHusky?: boolean;
   readonly includeCi?: boolean;
+  readonly skillSet?: "core" | "all";
+  readonly workflow?: "standard" | "strict";
+  readonly agent?: "claude" | "codex" | "both";
 }
 
 export interface RunInstallResult {
@@ -58,6 +62,8 @@ const PHASEGATE_SCRIPT_VERSION = "^0.0.0";
 
 const SHELL_BEGIN = "# === phasegate managed (BEGIN) ===";
 const SHELL_END = "# === phasegate managed (END) ===";
+const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
+const MARKDOWN_END = "<!-- phasegate:managed-section:end -->";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -131,6 +137,50 @@ function mergeShell(existing: string | null, incoming: string): string {
   return `${existing.replace(/\s*$/, "\n\n")}${block}\n`;
 }
 
+function managedMarkdownBlock(content: string): string {
+  const start = content.indexOf(MARKDOWN_BEGIN);
+  const end = content.indexOf(MARKDOWN_END);
+  if (start === -1 || end === -1 || end < start) return content.trim();
+  return content.slice(start, end + MARKDOWN_END.length).trim();
+}
+
+function mergeManagedMarkdown(existing: string | null, incoming: string): string {
+  const block = managedMarkdownBlock(incoming);
+  if (existing === null || existing.trim().length === 0) return `${incoming.trim()}\n`;
+  const pattern = new RegExp(`${escapeRegExp(MARKDOWN_BEGIN)}[\\s\\S]*?${escapeRegExp(MARKDOWN_END)}`);
+  if (pattern.test(existing)) return existing.replace(pattern, block).replace(/\s*$/, "\n");
+  return `${block}\n\n${existing.replace(/\s*$/, "\n")}`;
+}
+
+function renderAgentContextTemplate(
+  template: string,
+  options: {
+    readonly agent: "claude" | "codex" | "both";
+    readonly skillSet: "core" | "all";
+    readonly workflow: "standard" | "strict";
+    readonly includeHusky: boolean;
+    readonly includeCi: boolean;
+  },
+): string {
+  const commands = [
+    "- `phasegate doctor`",
+    "- `phasegate phasegate:check-ready`",
+    "- `phasegate validate --layer L2 --format human`",
+    "- `phasegate setup:agent --dry-run`",
+    "- `phasegate config:plan --intent l4-strict --dry-run`",
+  ].join("\n");
+  return template
+    .replaceAll("{{PHASEGATE_AGENT}}", options.agent)
+    .replaceAll("{{PHASEGATE_SKILLS_MODE}}", options.skillSet)
+    .replaceAll("{{PHASEGATE_WORKFLOW}}", options.workflow)
+    .replaceAll("{{PHASEGATE_HUSKY_STATE}}", options.includeHusky ? "managed" : "not managed by this setup run")
+    .replaceAll("{{PHASEGATE_CI_STATE}}", options.includeCi ? "managed" : "not managed by this setup run")
+    .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.");
+}
+
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -192,6 +242,9 @@ export class RunInstallUseCase {
     const includeCodex = input.includeCodex ?? true;
     const includeHusky = input.includeHusky ?? true;
     const includeCi = input.includeCi ?? true;
+    const skillSet = input.skillSet ?? "all";
+    const workflow = input.workflow ?? "standard";
+    const agent = input.agent ?? (includeClaude && includeCodex ? "both" : includeCodex ? "codex" : "claude");
     const targets = this.createTargets({ includeClaude, includeCodex, includeHusky, includeCi });
     const existingManifest = await this.manifestRepository.load(input.projectRoot);
     const baseManifest = existingManifest ?? DeploymentManifest.create(input.phasegateVersion);
@@ -205,7 +258,10 @@ export class RunInstallUseCase {
     for (const target of targets) {
       const absolutePath = join(input.projectRoot, target.path);
       const before = await readTextOrNull(absolutePath);
-      const template = await readFile(join(input.harnessRoot, target.templatePath), "utf8");
+      const rawTemplate = await readFile(join(input.harnessRoot, target.templatePath), "utf8");
+      const template = target.strategy === "markdown-managed"
+        ? renderAgentContextTemplate(rawTemplate, { agent, skillSet, workflow, includeHusky, includeCi })
+        : rawTemplate;
       const repairMode = this.repairMode(target, before);
       const next = this.merge(target, before, template, input.phasegateVersion);
       const didChange = before !== next;
@@ -300,10 +356,26 @@ export class RunInstallUseCase {
   }): readonly InstallTarget[] {
     return [
       ...(options.includeClaude
-        ? [{ path: ".claude/settings.json", strategy: "json" as const, templatePath: "templates/.claude/settings.json" }]
+        ? [
+            { path: ".claude/settings.json", strategy: "json" as const, templatePath: "templates/.claude/settings.json" },
+            {
+              path: "CLAUDE.md",
+              strategy: "markdown-managed" as const,
+              templatePath: "docs/templates/agent-context/CLAUDE.md.template.md",
+              block: { start: MARKDOWN_BEGIN, end: MARKDOWN_END, content: "phasegate CLAUDE.md managed section" },
+            },
+          ]
         : []),
       ...(options.includeCodex
-        ? [{ path: ".codex/hooks.json", strategy: "json" as const, templatePath: "templates/.codex/hooks.json" }]
+        ? [
+            { path: ".codex/hooks.json", strategy: "json" as const, templatePath: "templates/.codex/hooks.json" },
+            {
+              path: "AGENTS.md",
+              strategy: "markdown-managed" as const,
+              templatePath: "docs/templates/agent-context/AGENTS.md.template.md",
+              block: { start: MARKDOWN_BEGIN, end: MARKDOWN_END, content: "phasegate AGENTS.md managed section" },
+            },
+          ]
         : []),
       ...(options.includeHusky
         ? [
@@ -346,6 +418,7 @@ export class RunInstallUseCase {
   private repairMode(target: InstallTarget, before: string | null): RepairMode {
     if (target.strategy === "shell") return shellRepairMode(before);
     if (target.strategy === "json") return jsonRepairMode(before);
+    if (target.strategy === "markdown-managed") return "mechanical";
     return "mechanical";
   }
 
@@ -358,6 +431,7 @@ export class RunInstallUseCase {
   private merge(target: InstallTarget, before: string | null, template: string, version: string): string {
     if (target.strategy === "yaml-add") return before ?? template;
     if (target.strategy === "shell") return mergeShell(before, template);
+    if (target.strategy === "markdown-managed") return mergeManagedMarkdown(before, template);
     if (target.strategy === "package-json") {
       const existing = before === null ? {} : (JSON.parse(before) as unknown);
       const merged = mergePackageJson(isRecord(existing) ? existing : {}, version || PHASEGATE_SCRIPT_VERSION);

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

@@ -1,6 +1,7 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-148
+// @work-item-id WI-174
 
 import { access, chmod, copyFile, lstat, mkdir, readFile, readlink, symlink, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
@@ -12,7 +13,7 @@ import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
 import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
 
 type ReconcileAction = "missing-manifest" | "update" | "add" | "link" | "skip" | "refuse";
-type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "symlink" | "unknown";
+type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "markdown-managed" | "symlink" | "unknown";
 
 export interface ReconcilePlanItem {
   readonly path: string;
@@ -52,6 +53,8 @@ interface ReconcileTarget {
 const SKILL_HINT = "invoke /phasegate-config-doctor";
 const SHELL_BEGIN = "# === phasegate managed (BEGIN) ===";
 const SHELL_END = "# === phasegate managed (END) ===";
+const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
+const MARKDOWN_END = "<!-- phasegate:managed-section:end -->";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -136,6 +139,41 @@ function reconcileShell(existing: string | null, incoming: string): string {
   return `${existing.replace(/\s*$/, "\n\n")}${incomingBlock}\n`;
 }
 
+function managedMarkdownBlock(content: string): string {
+  const start = content.indexOf(MARKDOWN_BEGIN);
+  const end = content.indexOf(MARKDOWN_END);
+  if (start === -1 || end === -1 || end < start) return content.trim();
+  return content.slice(start, end + MARKDOWN_END.length).trim();
+}
+
+function reconcileManagedMarkdown(existing: string | null, incoming: string): string {
+  const block = managedMarkdownBlock(incoming);
+  if (existing === null || existing.trim().length === 0) return `${incoming.trim()}\n`;
+  const pattern = new RegExp(`${escapeRegExp(MARKDOWN_BEGIN)}[\\s\\S]*?${escapeRegExp(MARKDOWN_END)}`);
+  if (pattern.test(existing)) return existing.replace(pattern, block).replace(/\s*$/, "\n");
+  return `${block}\n\n${existing.replace(/\s*$/, "\n")}`;
+}
+
+function renderAgentContextTemplate(template: string): string {
+  const commands = [
+    "- `phasegate doctor`",
+    "- `phasegate phasegate:check-ready`",
+    "- `phasegate validate --layer L2 --format human`",
+    "- `phasegate setup:agent --dry-run`",
+    "- `phasegate config:plan --intent l4-strict --dry-run`",
+  ].join("\n");
+  return template
+    .replaceAll("{{PHASEGATE_AGENT}}", "both")
+    .replaceAll("{{PHASEGATE_SKILLS_MODE}}", "all")
+    .replaceAll("{{PHASEGATE_WORKFLOW}}", "standard")
+    .replaceAll("{{PHASEGATE_HUSKY_STATE}}", "managed")
+    .replaceAll("{{PHASEGATE_CI_STATE}}", "managed")
+    .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.");
+}
+
 function reconcilePackageJson(existing: Record<string, unknown>, version: string): Record<string, unknown> {
   const devDependencies = isRecord(existing.devDependencies) ? existing.devDependencies : {};
   const scripts = isRecord(existing.scripts) ? existing.scripts : {};
@@ -259,7 +297,8 @@ export class RunReconcileUseCase {
     if (before === null) return this.planMissingTarget(input, target);
     const currentHash = this.hashCalculator.compute(before);
     const matchesManifest = currentHash.equals(entry.hash);
-    const template = target.templatePath ? await readFile(join(input.harnessRoot, target.templatePath), "utf8") : "";
+    const rawTemplate = target.templatePath ? await readFile(join(input.harnessRoot, target.templatePath), "utf8") : "";
+    const template = target.strategy === "markdown-managed" ? renderAgentContextTemplate(rawTemplate) : rawTemplate;
     const next = entry.mode === "created" && target.strategy !== "package-json"
       ? template
       : this.reconcileContent(target, before, template, input.phasegateVersion);
@@ -290,7 +329,8 @@ export class RunReconcileUseCase {
     if (target.strategy === "symlink") return this.planSymlink(input.projectRoot, target.path);
     const absolutePath = this.resolveProjectPath(input.projectRoot, target.path);
     const before = await readTextOrNull(absolutePath);
-    const template = target.templatePath ? await readFile(join(input.harnessRoot, target.templatePath), "utf8") : "";
+    const rawTemplate = target.templatePath ? await readFile(join(input.harnessRoot, target.templatePath), "utf8") : "";
+    const template = target.strategy === "markdown-managed" ? renderAgentContextTemplate(rawTemplate) : rawTemplate;
     const next = before === null && target.strategy !== "package-json"
       ? template
       : this.reconcileContent(target, before, template, input.phasegateVersion);
@@ -350,6 +390,7 @@ export class RunReconcileUseCase {
   private reconcileContent(target: ReconcileTarget, before: string | null, template: string, version: string): string {
     if (target.strategy === "yaml-add") return template;
     if (target.strategy === "shell") return reconcileShell(before, template);
+    if (target.strategy === "markdown-managed") return reconcileManagedMarkdown(before, template);
     if (target.strategy === "package-json") {
       const existing = before === null ? {} : (JSON.parse(before) as unknown);
       return `${JSON.stringify(reconcilePackageJson(isRecord(existing) ? existing : {}, version), null, 2)}\n`;
@@ -362,7 +403,19 @@ export class RunReconcileUseCase {
   private createTargets(): readonly ReconcileTarget[] {
     return [
       { path: ".claude/settings.json", strategy: "json", templatePath: "templates/.claude/settings.json" },
+      {
+        path: "CLAUDE.md",
+        strategy: "markdown-managed",
+        templatePath: "docs/templates/agent-context/CLAUDE.md.template.md",
+        block: { start: MARKDOWN_BEGIN, end: MARKDOWN_END, content: "phasegate CLAUDE.md managed section" },
+      },
       { path: ".codex/hooks.json", strategy: "json", templatePath: "templates/.codex/hooks.json" },
+      {
+        path: "AGENTS.md",
+        strategy: "markdown-managed",
+        templatePath: "docs/templates/agent-context/AGENTS.md.template.md",
+        block: { start: MARKDOWN_BEGIN, end: MARKDOWN_END, content: "phasegate AGENTS.md managed section" },
+      },
       {
         path: ".husky/pre-commit",
         strategy: "shell",
@@ -401,7 +454,7 @@ export class RunReconcileUseCase {
 
   private managedBlockFor(path: string, strategy: StrategyType): ManagedBlockInput | null {
     if (strategy === "shell") return { start: SHELL_BEGIN, end: SHELL_END, content: `phasegate ${path} managed block` };
-    if (strategy === "json" || strategy === "package-json") {
+    if (strategy === "json" || strategy === "package-json" || strategy === "markdown-managed") {
       return { start: "phasegate structured merge", end: "phasegate structured merge", content: `${strategy}:${path}` };
     }
     return null;

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

@@ -1,6 +1,7 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-147
+// @work-item-id WI-174
 
 import { access, copyFile, lstat, mkdir, readFile, readlink, rm, rmdir, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
@@ -10,7 +11,7 @@ import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
 import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
 
 type UninstallAction = "missing-manifest" | "delete" | "unlink" | "reverse-merge" | "skip" | "refuse";
-type StrategyType = "created" | "json" | "shell" | "package-json" | "symlink" | "yaml-add" | "unknown";
+type StrategyType = "created" | "json" | "shell" | "package-json" | "markdown-managed" | "symlink" | "yaml-add" | "unknown";
 
 export interface UninstallPlanItem {
   readonly path: string;
@@ -42,6 +43,8 @@ export interface RunUninstallResult {
 const SKILL_HINT = "invoke /phasegate-config-doctor";
 const SHELL_BEGIN = "# === phasegate managed (BEGIN) ===";
 const SHELL_END = "# === phasegate managed (END) ===";
+const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
+const MARKDOWN_END = "<!-- phasegate:managed-section:end -->";
 const PHASEGATE_SCRIPT_PREFIX = "phasegate:";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -108,6 +111,11 @@ export function reverseShellMerge(currentContent: string): string {
   return currentContent.replace(pattern, "\n").replace(/\n{3,}/g, "\n\n").replace(/\s*$/, "\n").replace(/^\n/, "");
 }
 
+export function reverseManagedMarkdown(currentContent: string): string {
+  const pattern = new RegExp(`\\n?${escapeRegExp(MARKDOWN_BEGIN)}[\\s\\S]*?${escapeRegExp(MARKDOWN_END)}\\n?`);
+  return currentContent.replace(pattern, "\n").replace(/\n{3,}/g, "\n\n").replace(/\s*$/, "\n").replace(/^\n/, "");
+}
+
 export function reversePackageJsonMerge(currentContent: string): string {
   const parsed = JSON.parse(currentContent) as unknown;
   const result = isRecord(parsed) ? { ...parsed } : {};
@@ -300,6 +308,7 @@ export class RunUninstallUseCase {
 
   private async reverseMerged(harnessRoot: string, path: string, currentContent: string, strategy: StrategyType): Promise<string> {
     if (strategy === "shell") return currentContent.includes(SHELL_BEGIN) ? reverseShellMerge(currentContent) : currentContent;
+    if (strategy === "markdown-managed") return currentContent.includes(MARKDOWN_BEGIN) ? reverseManagedMarkdown(currentContent) : currentContent;
     if (strategy === "package-json") return reversePackageJsonMerge(currentContent);
     if (strategy === "json") return reverseJsonMerge(currentContent, await readFile(join(harnessRoot, this.templateFor(path)), "utf8"));
     throw new Error(`Unsupported merged strategy: ${strategy}`);
@@ -309,6 +318,7 @@ export class RunUninstallUseCase {
     if (mode === "symlink") return "symlink";
     if (mode === "created") return path.endsWith(".yml") || path.endsWith(".yaml") ? "yaml-add" : "created";
     if (path === "package.json") return "package-json";
+    if (path === "AGENTS.md" || path === "CLAUDE.md") return "markdown-managed";
     if (path.endsWith(".json")) return "json";
     if (path.startsWith(".husky/")) return "shell";
     return "unknown";
@@ -317,6 +327,8 @@ export class RunUninstallUseCase {
   private templateFor(path: string): string {
     if (path === ".claude/settings.json") return "templates/.claude/settings.json";
     if (path === ".codex/hooks.json") return "templates/.codex/hooks.json";
+    if (path === "CLAUDE.md") return "docs/templates/agent-context/CLAUDE.md.template.md";
+    if (path === "AGENTS.md") return "docs/templates/agent-context/AGENTS.md.template.md";
     throw new Error(`No template for ${path}`);
   }
 

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

@@ -12,6 +12,13 @@ export interface InstallHandlerInput {
   readonly apply: boolean;
   readonly force: boolean;
   readonly json: boolean;
+  readonly includeClaude?: boolean;
+  readonly includeCodex?: boolean;
+  readonly includeHusky?: boolean;
+  readonly includeCi?: boolean;
+  readonly skillSet?: "core" | "all";
+  readonly workflow?: "standard" | "strict";
+  readonly agent?: "claude" | "codex" | "both";
 }
 
 export interface InstallHandlerResult {