phasegate 0.152.8 → 0.153.0

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

@@ -1,6 +1,8 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-146
+// @work-item-id WI-174
+// @work-item-id WI-175
 
 import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -12,7 +14,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 +38,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 {
@@ -43,6 +48,16 @@ export interface RunInstallResult {
   readonly refused: readonly InstallPlanItem[];
   readonly changed: readonly InstallPlanItem[];
   readonly backupDir: string | null;
+  readonly error?: TargetAwareApplyError;
+}
+
+export interface TargetAwareApplyError {
+  readonly target: string;
+  readonly operation: string;
+  readonly code: string;
+  readonly likelyCause: string;
+  readonly recovery: string;
+  readonly partialChanges: readonly string[];
 }
 
 interface InstallTarget {
@@ -58,6 +73,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 +148,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, "\\$&");
 }
@@ -166,6 +227,26 @@ function hasCustomJson(content: string | null): boolean {
   }
 }
 
+function errorCode(error: unknown): string {
+  if (isRecord(error) && typeof error.code === "string") return error.code;
+  return "UNKNOWN";
+}
+
+function likelyCauseFor(code: string): string {
+  if (code === "EPERM") return "The filesystem or sandbox denied this write operation.";
+  if (code === "EACCES") return "The current user does not have permission to write this target.";
+  if (code === "EROFS") return "The project is on a read-only filesystem.";
+  if (code === "ENOTDIR") return "A parent path exists but is not a directory.";
+  return "The managed target could not be written.";
+}
+
+function recoveryFor(code: string, target: string): string {
+  if (code === "EPERM") return `Review sandbox or filesystem permissions for ${target}, then rerun phasegate setup:agent --apply or phasegate install --apply.`;
+  if (code === "EACCES") return `Fix ownership or permissions for ${target}, then rerun phasegate install --apply.`;
+  if (code === "EROFS") return `Move the project to a writable filesystem or rerun in a writable workspace before applying ${target}.`;
+  return `Inspect ${target}, run phasegate install --dry-run --json, then rerun with --apply after resolving the filesystem issue.`;
+}
+
 function shellRepairMode(content: string | null): RepairMode {
   if (content === null || content.trim().length === 0 || content.includes(SHELL_BEGIN)) return "mechanical";
   return "ai-assisted";
@@ -192,6 +273,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 +289,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;
@@ -233,9 +320,23 @@ export class RunInstallUseCase {
         await this.backup(input.projectRoot, target.path, backupDir);
       }
 
-      await mkdir(dirname(absolutePath), { recursive: true });
-      await writeFile(absolutePath, next, "utf8");
-      if (target.executable) await chmod(absolutePath, 0o755);
+        try {
+          await mkdir(dirname(absolutePath), { recursive: true });
+        } catch (error) {
+          return this.withApplyError({ plan, refused, changed, backupDir }, target.path, "mkdir", error);
+        }
+        try {
+          await writeFile(absolutePath, next, "utf8");
+        } catch (error) {
+          return this.withApplyError({ plan, refused, changed, backupDir }, target.path, "writeFile", error);
+        }
+        if (target.executable) {
+          try {
+            await chmod(absolutePath, 0o755);
+          } catch (error) {
+            return this.withApplyError({ plan, refused, changed, backupDir }, target.path, "chmod", error);
+          }
+        }
       changed.push(item);
 
       const mode = before === null ? "created" : "merged";
@@ -264,9 +365,17 @@ export class RunInstallUseCase {
       const item = await this.planSkillLink(input.projectRoot, linkPath);
       plan.push(item);
       if (!input.apply || !item.changed) continue;
-      await mkdir(join(input.projectRoot, "skills"), { recursive: true });
-      await mkdir(dirname(join(input.projectRoot, linkPath)), { recursive: true });
-      await symlink("../skills", join(input.projectRoot, linkPath), process.platform === "win32" ? "junction" : "dir");
+      try {
+        await mkdir(join(input.projectRoot, "skills"), { recursive: true });
+        await mkdir(dirname(join(input.projectRoot, linkPath)), { recursive: true });
+      } catch (error) {
+        return this.withApplyError({ plan, refused, changed, backupDir }, linkPath, "mkdir", error);
+      }
+      try {
+        await symlink("../skills", join(input.projectRoot, linkPath), process.platform === "win32" ? "junction" : "dir");
+      } catch (error) {
+        return this.withApplyError({ plan, refused, changed, backupDir }, linkPath, "symlink", error);
+      }
       changed.push(item);
       const hash = this.hashCalculator.compute("../skills");
       const existingEntry = baseManifest.findEntry(linkPath);
@@ -286,12 +395,36 @@ export class RunInstallUseCase {
     }
 
     if (input.apply && changed.length > 0) {
-      await this.manifestRepository.save(input.projectRoot, manifest);
+      try {
+        await this.manifestRepository.save(input.projectRoot, manifest);
+      } catch (error) {
+        return this.withApplyError({ plan, refused, changed, backupDir }, ".phasegate/manifest.json", "manifest-save", error);
+      }
     }
 
     return { plan, refused, changed, backupDir };
   }
 
+  private withApplyError(
+    result: RunInstallResult,
+    target: string,
+    operation: string,
+    error: unknown,
+  ): RunInstallResult {
+    const code = errorCode(error);
+    return {
+      ...result,
+      error: {
+        target,
+        operation,
+        code,
+        likelyCause: likelyCauseFor(code),
+        recovery: recoveryFor(code, target),
+        partialChanges: result.changed.map((item) => item.path),
+      },
+    };
+  }
+
   private createTargets(options: {
     readonly includeClaude: boolean;
     readonly includeCodex: boolean;
@@ -300,10 +433,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 +495,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 +508,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

@@ -1,6 +1,7 @@
 // @unit installation
 // @layer presentation
 // @work-item-id WI-146
+// @work-item-id WI-175
 
 import type { RunInstallUseCase } from "../../application/usecases/run-install.js";
 
@@ -12,6 +13,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 {
@@ -27,7 +35,7 @@ export class InstallHandler {
     if (input.json) {
       return {
         stdout: JSON.stringify(result, null, 2),
-        exitCode: result.refused.length > 0 ? 1 : 0,
+        exitCode: result.refused.length > 0 || result.error !== undefined ? 1 : 0,
       };
     }
     const lines = [
@@ -38,13 +46,20 @@ export class InstallHandler {
       }),
     ];
     if (result.backupDir !== null) lines.push(`backups: ${result.backupDir}`);
+    if (result.error !== undefined) {
+      lines.push("");
+      lines.push(`Apply error: ${result.error.target} ${result.error.operation} failed with ${result.error.code}`);
+      lines.push(`Cause: ${result.error.likelyCause}`);
+      lines.push(`Recovery: ${result.error.recovery}`);
+      if (result.error.partialChanges.length > 0) lines.push(`Partial changes: ${result.error.partialChanges.join(", ")}`);
+    }
     if (result.refused.length > 0) {
       lines.push("");
       lines.push("Refused ai-assisted/manual targets. Re-run with --force after reviewing the hint.");
     }
     return {
       stdout: lines.join("\n"),
-      exitCode: result.refused.length > 0 ? 1 : 0,
+      exitCode: result.refused.length > 0 || result.error !== undefined ? 1 : 0,
     };
   }
 }