hatch3r 1.7.0 → 1.7.1

package/dist/cli/index.js

@@ -14,7 +14,7 @@ var HATCH3R_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    HATCH3R_VERSION = "1.7.0";
+    HATCH3R_VERSION = "1.7.1";
   }
 });
 
@@ -307,7 +307,8 @@ ${MANAGED_BLOCK_END}`;
   }
   const before = existingContent.substring(0, startIdx);
   const after = existingContent.substring(endIdx + MANAGED_BLOCK_END.length);
-  return `${before}${block}${after}`;
+  const result = `${before}${block}${after}`;
+  return result.endsWith("\n") ? result : result + "\n";
 }
 function extractManagedBlock(content) {
   const startIdx = content.indexOf(MANAGED_BLOCK_START);
@@ -330,7 +331,8 @@ function extractCustomContent(content) {
 function wrapInManagedBlock(content) {
   return `${MANAGED_BLOCK_START}
 ${content.trim()}
-${MANAGED_BLOCK_END}`;
+${MANAGED_BLOCK_END}
+`;
 }
 function hasManagedBlock(content) {
   return content.includes(MANAGED_BLOCK_START) && content.includes(MANAGED_BLOCK_END);
@@ -1307,7 +1309,8 @@ async function safeWriteFile(filePath, content, options = {}) {
   if (options.managedContent) {
     if (!hasManagedBlock(existingContent)) {
       if (options.appendIfNoBlock) {
-        const prepended = [content.trim(), "", existingContent.trimStart()].join("\n");
+        let prepended = [content.trim(), "", existingContent.trimStart()].join("\n");
+        if (!prepended.endsWith("\n")) prepended += "\n";
         if (skipIfUnchanged && prepended === existingContent) {
           return { path: filePath, action: "unchanged" };
         }
@@ -2319,7 +2322,9 @@ var init_archive = __esm({
 var hatchJson_exports = {};
 __export(hatchJson_exports, {
   addManagedFile: () => addManagedFile,
+  applyPreservedManifestFields: () => applyPreservedManifestFields,
   createManifest: () => createManifest,
+  extractPreservedManifestFields: () => extractPreservedManifestFields,
   isValidGitBranchName: () => isValidGitBranchName,
   migrateManifest: () => migrateManifest,
   readManifest: () => readManifest,
@@ -2590,6 +2595,64 @@ function addManagedFile(manifest, filePath) {
 function removeManagedFile(manifest, filePath) {
   manifest.managedFiles = manifest.managedFiles.filter((f) => f !== filePath);
 }
+function extractPreservedManifestFields(manifest) {
+  const out = {};
+  if (manifest.board) out.board = manifest.board;
+  if (manifest.costTracking) out.costTracking = manifest.costTracking;
+  if (manifest.specs) out.specs = manifest.specs;
+  if (manifest.userContent) out.userContent = manifest.userContent;
+  if (manifest.hooks) out.hooks = manifest.hooks;
+  if (manifest.models) out.models = manifest.models;
+  if (manifest.claude) out.claude = manifest.claude;
+  if (manifest.repos) out.repos = manifest.repos;
+  if (manifest.packages) out.packages = manifest.packages;
+  if (manifest.workspace) out.workspace = manifest.workspace;
+  if (manifest.worktree?.extraPatterns !== void 0 || manifest.worktree?.nodeModules !== void 0) {
+    out.worktreeExtras = {};
+    if (manifest.worktree.extraPatterns !== void 0) {
+      out.worktreeExtras.extraPatterns = manifest.worktree.extraPatterns;
+    }
+    if (manifest.worktree.nodeModules !== void 0) {
+      out.worktreeExtras.nodeModules = manifest.worktree.nodeModules;
+    }
+  }
+  return out;
+}
+function applyPreservedManifestFields(manifest, preserved) {
+  if (preserved.board) {
+    if (manifest.board) {
+      manifest.board = {
+        ...preserved.board,
+        owner: manifest.board.owner,
+        repo: manifest.board.repo,
+        defaultBranch: manifest.board.defaultBranch ?? preserved.board.defaultBranch
+      };
+    } else {
+      manifest.board = {
+        ...preserved.board,
+        owner: manifest.owner || preserved.board.owner,
+        repo: manifest.repo || preserved.board.repo
+      };
+    }
+  }
+  if (preserved.costTracking) manifest.costTracking = preserved.costTracking;
+  if (preserved.specs) manifest.specs = preserved.specs;
+  if (preserved.userContent) manifest.userContent = preserved.userContent;
+  if (preserved.hooks) manifest.hooks = preserved.hooks;
+  if (preserved.models) manifest.models = preserved.models;
+  if (preserved.claude) manifest.claude = preserved.claude;
+  if (preserved.repos) manifest.repos = preserved.repos;
+  if (preserved.packages) manifest.packages = preserved.packages;
+  if (preserved.workspace) manifest.workspace = preserved.workspace;
+  if (preserved.worktreeExtras && manifest.worktree?.enabled) {
+    if (preserved.worktreeExtras.extraPatterns !== void 0) {
+      manifest.worktree.extraPatterns = preserved.worktreeExtras.extraPatterns;
+    }
+    if (preserved.worktreeExtras.nodeModules !== void 0) {
+      manifest.worktree.nodeModules = preserved.worktreeExtras.nodeModules;
+    }
+  }
+}
 var init_hatchJson = __esm({
   "src/manifest/hatchJson.ts"() {
     "use strict";
@@ -2954,205 +3017,498 @@ var init_canonical = __esm({
   }
 });
 
-// src/content/tags.ts
-function isLanguageTag(tag) {
-  return tag.startsWith("lang:");
-}
-function resolveLanguageTags(projectLanguages) {
-  const result = /* @__PURE__ */ new Set();
-  for (const lang of projectLanguages) {
-    const tag = LANGUAGE_TO_TAG[lang];
-    if (tag) result.add(tag);
-  }
-  return result;
-}
-function filterByLanguages(items, projectLanguages) {
-  if (projectLanguages.length === 0) return [...items];
-  const relevant = resolveLanguageTags(projectLanguages);
-  return items.filter((item) => {
-    if (item.protected) return true;
-    const itemLangTags = item.tags.filter(isLanguageTag);
-    if (itemLangTags.length === 0) return true;
-    return itemLangTags.some((t) => relevant.has(t));
-  });
-}
-var TAG_CORE, TAG_PLANNING, TAG_IMPLEMENTATION, TAG_REVIEW, TAG_DEVOPS, TAG_MAINTENANCE, TAG_BOARD, TAG_SECURITY, TAG_A11Y, TAG_PERFORMANCE, TAG_CUSTOMIZE, TAG_LANG_TYPESCRIPT, TAG_LANG_PYTHON, TAG_LANG_GO, TAG_LANG_RUST, TAG_LANG_JAVA, TAG_LANG_RUBY, WORKFLOW_TAGS, DOMAIN_TAGS, LANGUAGE_TO_TAG;
-var init_tags = __esm({
-  "src/content/tags.ts"() {
-    "use strict";
-    TAG_CORE = "core";
-    TAG_PLANNING = "planning";
-    TAG_IMPLEMENTATION = "implementation";
-    TAG_REVIEW = "review";
-    TAG_DEVOPS = "devops";
-    TAG_MAINTENANCE = "maintenance";
-    TAG_BOARD = "board";
-    TAG_SECURITY = "security";
-    TAG_A11Y = "a11y";
-    TAG_PERFORMANCE = "performance";
-    TAG_CUSTOMIZE = "customize";
-    TAG_LANG_TYPESCRIPT = "lang:typescript";
-    TAG_LANG_PYTHON = "lang:python";
-    TAG_LANG_GO = "lang:go";
-    TAG_LANG_RUST = "lang:rust";
-    TAG_LANG_JAVA = "lang:java";
-    TAG_LANG_RUBY = "lang:ruby";
-    WORKFLOW_TAGS = [
-      TAG_CORE,
-      TAG_PLANNING,
-      TAG_IMPLEMENTATION,
-      TAG_REVIEW,
-      TAG_DEVOPS,
-      TAG_MAINTENANCE
-    ];
-    DOMAIN_TAGS = [
-      TAG_BOARD,
-      TAG_SECURITY,
-      TAG_A11Y,
-      TAG_PERFORMANCE,
-      TAG_CUSTOMIZE
-    ];
-    LANGUAGE_TO_TAG = {
-      typescript: TAG_LANG_TYPESCRIPT,
-      javascript: TAG_LANG_TYPESCRIPT,
-      // JS projects also benefit from TS rules
-      python: TAG_LANG_PYTHON,
-      go: TAG_LANG_GO,
-      rust: TAG_LANG_RUST,
-      java: TAG_LANG_JAVA,
-      kotlin: TAG_LANG_JAVA,
-      // Kotlin shares Java ecosystem
-      ruby: TAG_LANG_RUBY
-    };
-  }
-});
-
-// src/content/index.ts
-import { readFile as readFile9, readdir as readdir6, cp as cp2, mkdir as mkdir4, rm as rm2, stat as stat5 } from "fs/promises";
-import { createHash as createHash3 } from "crypto";
-import { join as join12, dirname as dirname6, normalize, isAbsolute, posix as posix2 } from "path";
-function assertSafePath(relativePath, label2) {
-  const sanitized = relativePath.replace(/\0/g, "");
-  const normalized = normalize(sanitized);
-  if (normalized.startsWith("..") || isAbsolute(normalized)) {
-    throw new HatchError(`Unsafe path detected in ${label2}: ${relativePath}`, 1, "FS_ERROR");
-  }
-  if (sanitized !== relativePath) {
-    throw new HatchError(`Unsafe path detected in ${label2}: ${relativePath}`, 1, "FS_ERROR");
-  }
+// src/pipeline/agentToolAllowlist.ts
+function getAgentToolPolicy(agentId) {
+  return policyMap.get(agentId);
 }
-function extractContentReferences(content) {
-  const refs = /* @__PURE__ */ new Set();
-  const pattern = /`((?:cmd-)?hatch3r-[a-z0-9-]+)`/g;
-  let match;
-  while ((match = pattern.exec(content)) !== null) {
-    refs.add(match[1]);
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  let curr = new Array(b.length + 1);
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1,
+        // insertion
+        prev[j] + 1,
+        // deletion
+        prev[j - 1] + cost
+        // substitution
+      );
+    }
+    [prev, curr] = [curr, prev];
   }
-  return [...refs];
+  return prev[b.length];
 }
-async function validateCrossReferences(contentRoot, index) {
-  const warnings = [];
-  const allIds = new Set(index.items.map((item) => item.id));
-  for (const item of index.items) {
-    let content;
-    try {
-      const filePath = item.type === "skill" ? join12(contentRoot, item.relativePath, "SKILL.md") : join12(contentRoot, `${item.relativePath}`);
-      content = await readFile9(filePath, "utf-8");
-    } catch {
-      continue;
-    }
-    const refs = extractContentReferences(content);
-    for (const ref of refs) {
-      if (ref === item.id) continue;
-      if (!allIds.has(ref) && !allIds.has(`${COMMAND_ID_PREFIX}${ref}`)) {
-        warnings.push(
-          `${item.type} "${item.id}" references "${ref}" which does not exist in the content index`
-        );
-      }
+function suggestNearestCategory(tool) {
+  let bestMatch;
+  let bestDistance = Infinity;
+  for (const known of ALL_TOOL_CATEGORIES) {
+    const dist = levenshtein(tool, known);
+    if (dist < bestDistance) {
+      bestDistance = dist;
+      bestMatch = known;
     }
   }
-  return { warnings };
+  return bestDistance <= 2 ? bestMatch : void 0;
 }
-function validateOrchestrationDependencies(selection) {
+function validateToolPolicies(policies = AGENT_TOOL_POLICIES) {
   const warnings = [];
-  const selectedAgents = new Set(selection.items.agents);
-  const hasOrchestration = selection.items.rules.includes("hatch3r-agent-orchestration");
-  if (!hasOrchestration) return warnings;
-  for (const agentId of ORCHESTRATION_REQUIRED_AGENTS) {
-    if (!selectedAgents.has(agentId)) {
+  const knownCategories = new Set(ALL_TOOL_CATEGORIES);
+  for (const policy of policies) {
+    if (policy.allowedTools.length === 0) {
+      warnings.push(`Agent "${policy.agentId}" has an empty tool allowlist \u2014 it cannot invoke any tools.`);
+    }
+    const hasAll = ALL_TOOL_CATEGORIES.every(
+      (cat) => policy.allowedTools.includes(cat)
+    );
+    if (hasAll) {
       warnings.push(
-        `Orchestration pipeline requires agent "${agentId}" but it is not in the content selection. The 4-phase pipeline (Research \u2192 Implement \u2192 Review \u2192 Quality) will be incomplete.`
+        `Agent "${policy.agentId}" has access to all tool categories \u2014 consider restricting to least privilege.`
       );
     }
+    for (const tool of policy.allowedTools) {
+      if (!knownCategories.has(tool)) {
+        const suggestion = suggestNearestCategory(tool);
+        const didYouMean = suggestion ? ` Did you mean "${suggestion}"?` : "";
+        throw new HatchError(
+          `Invalid tool policy for agent "${policy.agentId}": unknown tool category "${tool}".${didYouMean} Valid categories: ${ALL_TOOL_CATEGORIES.join(", ")}.`,
+          1,
+          "VALIDATION_ERROR"
+        );
+      }
+    }
   }
   return warnings;
 }
-function typeIdKey(type, id) {
-  return `${type}:${id}`;
-}
-function getAllItemsById(index, id) {
-  return index.items.filter((item) => item.id === id);
-}
-function applyCommandPrefix(id, type) {
-  return type === "command" ? `${COMMAND_ID_PREFIX}${id}` : id;
-}
-async function scanContentRoot(rootPath, source, items) {
-  for (const config of CONTENT_TYPE_CONFIGS) {
-    if (source === "user" && config.type !== "agent" && config.type !== "skill" && config.type !== "rule" && config.type !== "command" && config.type !== "hook") {
-      continue;
-    }
-    const dirPath = join12(rootPath, config.dir);
-    if (config.strategy === "subdirectory") {
-      let dirents;
-      try {
-        dirents = (await readdir6(dirPath, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
-      } catch (err) {
-        if (err.code === "ENOENT") continue;
-        throw err;
-      }
-      for (const dirent of dirents) {
-        if (!dirent.isDirectory()) continue;
-        const skillPath = join12(dirPath, dirent.name, "SKILL.md");
-        try {
-          const raw = await readFile9(skillPath, "utf-8");
-          const { metadata } = parseFrontmatter(raw);
-          const rawId = metadata.id || metadata.name || dirent.name;
-          const id = applyCommandPrefix(rawId, config.type);
-          const item = {
-            id,
-            type: config.type,
-            description: metadata.description ?? "",
-            tags: metadata.tags ?? [],
-            protected: metadata.protected,
-            relativePath: posix2.join(config.dir, dirent.name),
-            source
-          };
-          if (source === "user") {
-            const adapters = parseAdaptersFrontmatter(raw);
-            if (adapters) item.adapters = adapters;
-          }
-          items.push(item);
-        } catch (err) {
-          if (err.code !== "ENOENT") throw err;
-        }
-      }
-    } else {
-      let entries;
-      try {
-        const all = await readdir6(dirPath);
-        entries = all.filter((f) => f.endsWith(".md")).sort();
-      } catch (err) {
-        if (err.code === "ENOENT") continue;
-        throw err;
-      }
-      for (const file of entries) {
-        const filePath = join12(dirPath, file);
-        const raw = await readFile9(filePath, "utf-8");
-        const { metadata } = parseFrontmatter(raw);
-        const rawId = metadata.id || metadata.name || file.replace(/\.md$/, "");
-        const id = applyCommandPrefix(rawId, config.type);
-        const item = {
-          id,
+var AGENT_TOOL_POLICIES, policyMap, ALL_TOOL_CATEGORIES;
+var init_agentToolAllowlist = __esm({
+  "src/pipeline/agentToolAllowlist.ts"() {
+    "use strict";
+    init_types();
+    AGENT_TOOL_POLICIES = [
+      {
+        agentId: "hatch3r-researcher",
+        allowedTools: ["read", "search", "web", "mcp"],
+        description: "Read-only research: file reading, code search, web research, MCP queries. No write or execute."
+      },
+      {
+        agentId: "hatch3r-implementer",
+        allowedTools: ["read", "search", "write", "execute"],
+        description: "Code implementation: file read/write, code search, command execution (tests, linters). No git, board, or web."
+      },
+      {
+        agentId: "hatch3r-reviewer",
+        allowedTools: ["read", "search"],
+        description: "Code review: file reading and code search only. No write, execute, git, or board."
+      },
+      {
+        agentId: "hatch3r-fixer",
+        allowedTools: ["read", "search", "write", "execute"],
+        description: "Fix application: file read/write, code search, command execution. No git, board, or web."
+      },
+      {
+        agentId: "hatch3r-test-writer",
+        allowedTools: ["read", "search", "write", "execute"],
+        description: "Test writing: file read/write, code search, test execution. No git, board, or web."
+      },
+      {
+        agentId: "hatch3r-security-auditor",
+        allowedTools: ["read", "search", "execute"],
+        description: "Security audit: file reading, code search, security tool execution. No write, git, board, or web."
+      },
+      {
+        agentId: "hatch3r-docs-writer",
+        allowedTools: ["read", "search", "write"],
+        description: "Documentation: file read/write, code search. No execute, git, board, or web."
+      },
+      {
+        agentId: "hatch3r-lint-fixer",
+        allowedTools: ["read", "search", "write", "execute"],
+        description: "Lint fixing: file read/write, code search, linter execution. No git, board, or web."
+      },
+      {
+        agentId: "hatch3r-a11y-auditor",
+        allowedTools: ["read", "search", "execute"],
+        description: "Accessibility audit: file reading, code search, a11y tool execution. No write, git, board, or web."
+      },
+      {
+        agentId: "hatch3r-perf-profiler",
+        allowedTools: ["read", "search", "execute"],
+        description: "Performance profiling: file reading, code search, profiler execution. No write, git, board, or web."
+      },
+      {
+        agentId: "hatch3r-dependency-auditor",
+        allowedTools: ["read", "search", "execute"],
+        description: "Dependency audit: file reading, code search, audit tool execution. No write, git, board, or web."
+      },
+      {
+        agentId: "hatch3r-architect",
+        allowedTools: ["read", "search", "write"],
+        description: "Architecture: file read/write (docs/ADRs), code search. No execute, git, board, or web."
+      },
+      {
+        agentId: "hatch3r-devops",
+        allowedTools: ["read", "search", "write", "execute"],
+        description: "DevOps: file read/write, code search, CI/CD command execution. No git, board, or web."
+      },
+      {
+        agentId: "hatch3r-ci-watcher",
+        allowedTools: ["read", "search"],
+        description: "CI monitoring: file reading, code search. No write, execute, git, board, or web."
+      },
+      {
+        agentId: "hatch3r-context-rules",
+        allowedTools: ["read", "search"],
+        description: "Context loading: file reading and code search only. No write, execute, git, board, or web."
+      },
+      {
+        agentId: "hatch3r-learnings-loader",
+        allowedTools: ["read", "search"],
+        description: "Learnings loading: file reading and code search only. No write, execute, git, board, or web."
+      }
+    ];
+    policyMap = new Map(
+      AGENT_TOOL_POLICIES.map((p) => [p.agentId, p])
+    );
+    ALL_TOOL_CATEGORIES = [
+      "read",
+      "search",
+      "write",
+      "execute",
+      "web",
+      "mcp",
+      "git",
+      "board"
+    ];
+  }
+});
+
+// src/pipeline/adapterToolTranslator.ts
+function toClaudeToolsFrontmatter(agentId) {
+  const policy = getAgentToolPolicy(agentId);
+  if (!policy) return null;
+  const tools = resolveNativeTools(policy.allowedTools, CLAUDE_CATEGORY_MAP);
+  if (tools.length === 0) return null;
+  return tools.join(", ");
+}
+function toCopilotToolsFrontmatter(agentId) {
+  const policy = getAgentToolPolicy(agentId);
+  if (!policy) return null;
+  const tools = resolveNativeTools(policy.allowedTools, COPILOT_CATEGORY_MAP);
+  return tools.length === 0 ? null : tools;
+}
+function toWindsurfToolsFrontmatter(agentId) {
+  const policy = getAgentToolPolicy(agentId);
+  if (!policy) return null;
+  const tools = resolveNativeTools(policy.allowedTools, WINDSURF_CATEGORY_MAP);
+  if (tools.length === 0) return null;
+  return tools.join(", ");
+}
+function toCursorReadonlyFrontmatter(agentId) {
+  const policy = getAgentToolPolicy(agentId);
+  if (!policy) return null;
+  const hasWrite = policy.allowedTools.includes("write");
+  const hasExecute = policy.allowedTools.includes("execute");
+  return !hasWrite && !hasExecute;
+}
+function getAskUserToolEntry(adapter) {
+  return ASK_USER_TOOLS[adapter] ?? null;
+}
+function toAskUserPlatformNote(adapter) {
+  const entry = getAskUserToolEntry(adapter);
+  if (entry === null) {
+    return [
+      `**Platform:** No documented native question tool for \`${adapter}\`.`,
+      "Use the Plain-Text Fallback Template below for every ASK checkpoint."
+    ].join(" ");
+  }
+  const hint = entry.invocationHint ? ` ${entry.invocationHint}` : "";
+  return [
+    `**Platform:** Invoke the \`${entry.name}\` tool for every ASK checkpoint on \`${adapter}\`.${hint}`,
+    "Use the Plain-Text Fallback Template only when the tool cannot represent the question (e.g., long free-text answers)."
+  ].join(" ");
+}
+function buildAskUserPlatformTable() {
+  const rows = Object.entries(ASK_USER_TOOLS).map(([adapter, entry]) => {
+    if (entry === null) {
+      return `| \`${adapter}\` | _No documented native tool \u2014 use the Plain-Text Fallback Template below._ |`;
+    }
+    return `| \`${adapter}\` | Invoke the \`${entry.name}\` tool for every ASK checkpoint. |`;
+  });
+  return [
+    "| Adapter | Platform-Native Question Tool |",
+    "|---------|-------------------------------|",
+    ...rows
+  ].join("\n");
+}
+function substituteCanonicalPlatformMarker(content) {
+  if (!content.includes(PLATFORM_TOOL_MARKER)) return content;
+  return content.split(PLATFORM_TOOL_MARKER).join(buildAskUserPlatformTable());
+}
+function resolveNativeTools(categories, map) {
+  const out = /* @__PURE__ */ new Set();
+  for (const cat of categories) {
+    const native = map[cat];
+    if (!native) continue;
+    for (const t of native) out.add(t);
+  }
+  return [...out];
+}
+var CLAUDE_CATEGORY_MAP, COPILOT_CATEGORY_MAP, WINDSURF_CATEGORY_MAP, ASK_USER_TOOLS, PLATFORM_TOOL_MARKER;
+var init_adapterToolTranslator = __esm({
+  "src/pipeline/adapterToolTranslator.ts"() {
+    "use strict";
+    init_agentToolAllowlist();
+    CLAUDE_CATEGORY_MAP = {
+      read: ["Read", "NotebookRead"],
+      search: ["Grep", "Glob"],
+      write: ["Edit", "MultiEdit", "Write", "NotebookEdit"],
+      execute: ["Bash"],
+      web: ["WebSearch", "WebFetch"],
+      mcp: [],
+      // MCP tools are scoped via the `mcpServers` frontmatter field, not `tools`.
+      git: ["Bash"],
+      // Git is driven via Bash; callers that grant git retain execute semantics.
+      board: []
+      // Project-board tooling is MCP-driven; see mcp mapping.
+    };
+    COPILOT_CATEGORY_MAP = {
+      read: ["read"],
+      search: ["search"],
+      write: ["edit"],
+      execute: ["execute"],
+      web: ["web"],
+      mcp: [],
+      // MCP exposure is controlled via `mcp-servers`, not `tools`.
+      git: ["execute"],
+      board: []
+    };
+    WINDSURF_CATEGORY_MAP = CLAUDE_CATEGORY_MAP;
+    ASK_USER_TOOLS = {
+      claude: { name: "AskUserQuestion" },
+      cursor: null,
+      copilot: null,
+      windsurf: null,
+      codex: null,
+      cline: null,
+      opencode: null,
+      amp: null,
+      aider: null,
+      kiro: null,
+      goose: null,
+      zed: null,
+      "amazon-q": null,
+      gemini: null,
+      antigravity: null
+    };
+    PLATFORM_TOOL_MARKER = "<!-- HATCH3R:PLATFORM-TOOL -->";
+  }
+});
+
+// src/content/tags.ts
+function isLanguageTag(tag) {
+  return tag.startsWith("lang:");
+}
+function resolveLanguageTags(projectLanguages) {
+  const result = /* @__PURE__ */ new Set();
+  for (const lang of projectLanguages) {
+    const tag = LANGUAGE_TO_TAG[lang];
+    if (tag) result.add(tag);
+  }
+  return result;
+}
+function filterByLanguages(items, projectLanguages) {
+  if (projectLanguages.length === 0) return [...items];
+  const relevant = resolveLanguageTags(projectLanguages);
+  return items.filter((item) => {
+    if (item.protected) return true;
+    const itemLangTags = item.tags.filter(isLanguageTag);
+    if (itemLangTags.length === 0) return true;
+    return itemLangTags.some((t) => relevant.has(t));
+  });
+}
+var TAG_CORE, TAG_PLANNING, TAG_IMPLEMENTATION, TAG_REVIEW, TAG_DEVOPS, TAG_MAINTENANCE, TAG_BOARD, TAG_SECURITY, TAG_A11Y, TAG_PERFORMANCE, TAG_CUSTOMIZE, TAG_LANG_TYPESCRIPT, TAG_LANG_PYTHON, TAG_LANG_GO, TAG_LANG_RUST, TAG_LANG_JAVA, TAG_LANG_RUBY, WORKFLOW_TAGS, DOMAIN_TAGS, LANGUAGE_TO_TAG;
+var init_tags = __esm({
+  "src/content/tags.ts"() {
+    "use strict";
+    TAG_CORE = "core";
+    TAG_PLANNING = "planning";
+    TAG_IMPLEMENTATION = "implementation";
+    TAG_REVIEW = "review";
+    TAG_DEVOPS = "devops";
+    TAG_MAINTENANCE = "maintenance";
+    TAG_BOARD = "board";
+    TAG_SECURITY = "security";
+    TAG_A11Y = "a11y";
+    TAG_PERFORMANCE = "performance";
+    TAG_CUSTOMIZE = "customize";
+    TAG_LANG_TYPESCRIPT = "lang:typescript";
+    TAG_LANG_PYTHON = "lang:python";
+    TAG_LANG_GO = "lang:go";
+    TAG_LANG_RUST = "lang:rust";
+    TAG_LANG_JAVA = "lang:java";
+    TAG_LANG_RUBY = "lang:ruby";
+    WORKFLOW_TAGS = [
+      TAG_CORE,
+      TAG_PLANNING,
+      TAG_IMPLEMENTATION,
+      TAG_REVIEW,
+      TAG_DEVOPS,
+      TAG_MAINTENANCE
+    ];
+    DOMAIN_TAGS = [
+      TAG_BOARD,
+      TAG_SECURITY,
+      TAG_A11Y,
+      TAG_PERFORMANCE,
+      TAG_CUSTOMIZE
+    ];
+    LANGUAGE_TO_TAG = {
+      typescript: TAG_LANG_TYPESCRIPT,
+      javascript: TAG_LANG_TYPESCRIPT,
+      // JS projects also benefit from TS rules
+      python: TAG_LANG_PYTHON,
+      go: TAG_LANG_GO,
+      rust: TAG_LANG_RUST,
+      java: TAG_LANG_JAVA,
+      kotlin: TAG_LANG_JAVA,
+      // Kotlin shares Java ecosystem
+      ruby: TAG_LANG_RUBY
+    };
+  }
+});
+
+// src/content/index.ts
+import { readFile as readFile9, readdir as readdir6, cp as cp2, mkdir as mkdir4, rm as rm2, stat as stat5 } from "fs/promises";
+import { createHash as createHash3 } from "crypto";
+import { join as join12, dirname as dirname6, normalize, isAbsolute, posix as posix2 } from "path";
+function assertSafePath(relativePath, label2) {
+  const sanitized = relativePath.replace(/\0/g, "");
+  const normalized = normalize(sanitized);
+  if (normalized.startsWith("..") || isAbsolute(normalized)) {
+    throw new HatchError(`Unsafe path detected in ${label2}: ${relativePath}`, 1, "FS_ERROR");
+  }
+  if (sanitized !== relativePath) {
+    throw new HatchError(`Unsafe path detected in ${label2}: ${relativePath}`, 1, "FS_ERROR");
+  }
+}
+function extractContentReferences(content) {
+  const refs = /* @__PURE__ */ new Set();
+  const pattern = /`((?:cmd-)?hatch3r-[a-z0-9-]+)`/g;
+  let match;
+  while ((match = pattern.exec(content)) !== null) {
+    refs.add(match[1]);
+  }
+  return [...refs];
+}
+async function validateCrossReferences(contentRoot, index) {
+  const warnings = [];
+  const allIds = new Set(index.items.map((item) => item.id));
+  for (const item of index.items) {
+    let content;
+    try {
+      const filePath = item.type === "skill" ? join12(contentRoot, item.relativePath, "SKILL.md") : join12(contentRoot, `${item.relativePath}`);
+      content = await readFile9(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+    const refs = extractContentReferences(content);
+    for (const ref of refs) {
+      if (ref === item.id) continue;
+      if (!allIds.has(ref) && !allIds.has(`${COMMAND_ID_PREFIX}${ref}`)) {
+        warnings.push(
+          `${item.type} "${item.id}" references "${ref}" which does not exist in the content index`
+        );
+      }
+    }
+  }
+  return { warnings };
+}
+function validateOrchestrationDependencies(selection) {
+  const warnings = [];
+  const selectedAgents = new Set(selection.items.agents);
+  const hasOrchestration = selection.items.rules.includes("hatch3r-agent-orchestration");
+  if (!hasOrchestration) return warnings;
+  for (const agentId of ORCHESTRATION_REQUIRED_AGENTS) {
+    if (!selectedAgents.has(agentId)) {
+      warnings.push(
+        `Orchestration pipeline requires agent "${agentId}" but it is not in the content selection. The 4-phase pipeline (Research \u2192 Implement \u2192 Review \u2192 Quality) will be incomplete.`
+      );
+    }
+  }
+  return warnings;
+}
+function typeIdKey(type, id) {
+  return `${type}:${id}`;
+}
+function getAllItemsById(index, id) {
+  return index.items.filter((item) => item.id === id);
+}
+function applyCommandPrefix(id, type) {
+  return type === "command" ? `${COMMAND_ID_PREFIX}${id}` : id;
+}
+async function scanContentRoot(rootPath, source, items) {
+  for (const config of CONTENT_TYPE_CONFIGS) {
+    if (source === "user" && config.type !== "agent" && config.type !== "skill" && config.type !== "rule" && config.type !== "command" && config.type !== "hook") {
+      continue;
+    }
+    const dirPath = join12(rootPath, config.dir);
+    if (config.strategy === "subdirectory") {
+      let dirents;
+      try {
+        dirents = (await readdir6(dirPath, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+      } catch (err) {
+        if (err.code === "ENOENT") continue;
+        throw err;
+      }
+      for (const dirent of dirents) {
+        if (!dirent.isDirectory()) continue;
+        const skillPath = join12(dirPath, dirent.name, "SKILL.md");
+        try {
+          const raw = await readFile9(skillPath, "utf-8");
+          const { metadata } = parseFrontmatter(raw);
+          const rawId = metadata.id || metadata.name || dirent.name;
+          const id = applyCommandPrefix(rawId, config.type);
+          const item = {
+            id,
+            type: config.type,
+            description: metadata.description ?? "",
+            tags: metadata.tags ?? [],
+            protected: metadata.protected,
+            relativePath: posix2.join(config.dir, dirent.name),
+            source
+          };
+          if (source === "user") {
+            const adapters = parseAdaptersFrontmatter(raw);
+            if (adapters) item.adapters = adapters;
+          }
+          items.push(item);
+        } catch (err) {
+          if (err.code !== "ENOENT") throw err;
+        }
+      }
+    } else {
+      let entries;
+      try {
+        const all = await readdir6(dirPath);
+        entries = all.filter((f) => f.endsWith(".md")).sort();
+      } catch (err) {
+        if (err.code === "ENOENT") continue;
+        throw err;
+      }
+      for (const file of entries) {
+        const filePath = join12(dirPath, file);
+        const raw = await readFile9(filePath, "utf-8");
+        const { metadata } = parseFrontmatter(raw);
+        const rawId = metadata.id || metadata.name || file.replace(/\.md$/, "");
+        const id = applyCommandPrefix(rawId, config.type);
+        const item = {
+          id,
           type: config.type,
           description: metadata.description ?? "",
           tags: metadata.tags ?? [],
@@ -3470,8 +3826,26 @@ async function copySelectedContent(contentRoot, agentsDir, selection, index, opt
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
+  await substitutePlatformToolMarker(agentsDir);
   return copied;
 }
+async function substitutePlatformToolMarker(agentsDir) {
+  const sharedDir = join12(agentsDir, "agents", "shared");
+  let entries;
+  try {
+    entries = await readdir6(sharedDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return;
+    throw err;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const filePath = join12(sharedDir, entry.name);
+    const content = await readFile9(filePath, "utf-8");
+    if (!content.includes(PLATFORM_TOOL_MARKER)) continue;
+    await atomicWriteFile(filePath, substituteCanonicalPlatformMarker(content));
+  }
+}
 async function buildSelectionsFromDisk(agentsDir) {
   const items = {
     agents: [],
@@ -3624,6 +3998,7 @@ var init_content = __esm({
     "use strict";
     init_canonical();
     init_safeWrite();
+    init_adapterToolTranslator();
     init_types();
     init_tags();
     ORCHESTRATION_REQUIRED_AGENTS = [
@@ -3947,8 +4322,7 @@ async function generateRootAgentsMd(agentsDir) {
     return { full: AGENTS_MD_FULL, inner: AGENTS_MD_INNER };
   }
   const inner = sections.join("\n");
-  const full = `${wrapInManagedBlock(inner)}
-`;
+  const full = wrapInManagedBlock(inner);
   return { full, inner };
 }
 async function generateCanonicalAgentsMd(agentsDir) {
@@ -4172,8 +4546,7 @@ You are running the **minimal** content preset \u2014 only core agents and workf
       "- Skills: `/.agents/skills/`",
       "- Commands: `/.agents/commands/`"
     ].join("\n");
-    AGENTS_MD_FULL = `${wrapInManagedBlock(AGENTS_MD_INNER)}
-`;
+    AGENTS_MD_FULL = wrapInManagedBlock(AGENTS_MD_INNER);
   }
 });
 
@@ -4609,6 +4982,7 @@ var init_base = __esm({
     init_customization();
     init_mcp_utils();
     init_hooks();
+    init_adapterToolTranslator();
     BaseAdapter = class {
       warnings = [];
       /**
@@ -4805,9 +5179,10 @@ var init_base = __esm({
         );
         const minimal = this.isMinimal(ctx);
         for (const rule of rules) {
-          const { content, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, rule);
+          const { content: raw, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, rule);
           this.warnings.push(...warnings);
           if (skip) continue;
+          const content = this.substituteAskUserMarker(raw);
           const desc = overrides.description ?? rule.description;
           if (minimal) {
             lines.push(`## ${rule.id}`, "", this.stripMinimal(content), "");
@@ -4824,9 +5199,10 @@ var init_base = __esm({
         const agents = await this.readUserFacingCanonicalFiles(ctx.agentsDir, "agents");
         const minimal = this.isMinimal(ctx);
         for (const agent of agents) {
-          const { content, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, agent);
+          const { content: raw, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, agent);
           this.warnings.push(...warnings);
           if (skip) continue;
+          const content = this.substituteAskUserMarker(raw);
           const model = resolveAgentModel(agent.id, agent, ctx.manifest, overrides);
           const desc = overrides.description ?? agent.description;
           const fmt = model ? (formatModel ?? defaultModelFormat)(model) : void 0;
@@ -4848,9 +5224,10 @@ var init_base = __esm({
         const results = [];
         const skills = await this.readTrackedCanonicalFiles(ctx.agentsDir, "skills");
         for (const skill of skills) {
-          const { content, skip, warnings } = await applyCustomizationRaw(ctx.projectRoot, skill);
+          const { content: raw, skip, warnings } = await applyCustomizationRaw(ctx.projectRoot, skill);
           this.warnings.push(...warnings);
           if (skip) continue;
+          const content = this.substituteAskUserMarker(raw);
           results.push(output(pathFn(skill.id), wrapInManagedBlock(content), content));
         }
         return results;
@@ -4861,9 +5238,10 @@ var init_base = __esm({
         const results = [];
         const skills = await this.readTrackedCanonicalFiles(ctx.agentsDir, "skills");
         for (const skill of skills) {
-          const { content, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, skill);
+          const { content: raw, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, skill);
           this.warnings.push(...warnings);
           if (skip) continue;
+          const content = this.substituteAskUserMarker(raw);
           const desc = overrides.description ?? skill.description;
           const fm = `---
 name: ${skill.id}
@@ -4881,9 +5259,10 @@ ${wrapInManagedBlock(content)}`, content));
         const results = [];
         const commands = await this.readUserFacingCanonicalFiles(ctx.agentsDir, "commands");
         for (const cmd of commands) {
-          const { content, skip, warnings } = await applyCustomizationRaw(ctx.projectRoot, cmd);
+          const { content: raw, skip, warnings } = await applyCustomizationRaw(ctx.projectRoot, cmd);
           this.warnings.push(...warnings);
           if (skip) continue;
+          const content = this.substituteAskUserMarker(raw);
           results.push(output(pathFn(cmd.id), wrapInManagedBlock(content), content));
         }
         return results;
@@ -4937,469 +5316,240 @@ ${wrapInManagedBlock(content)}`, content));
         return ctx.generationMode === "minimal";
       }
       /**
-       * Strip verbose content for minimal generation mode.
-       * Removes markdown comments, collapses excessive blank lines,
-       * strips decorative formatting, and trims descriptions.
+       * Replace the `<!-- HATCH3R:PLATFORM-TOOL -->` marker in canonical content
+       * with the per-adapter platform-note paragraph. Idempotent and a no-op
+       * when the marker is absent.
+       *
+       * See agents/shared/user-question-protocol.md and
+       * src/pipeline/adapterToolTranslator.ts::toAskUserPlatformNote.
        */
-      stripMinimal(content) {
-        let result = content;
-        result = result.replace(/<!--[\s\S]*?-->/g, "");
-        result = result.replace(/^[-*_]{3,}\s*$/gm, "");
-        result = result.replace(/\n{3,}/g, "\n\n");
-        result = result.trim();
-        return result;
-      }
-    };
-  }
-});
-
-// src/adapters/aider.ts
-var AiderAdapter;
-var init_aider = __esm({
-  "src/adapters/aider.ts"() {
-    "use strict";
-    init_types();
-    init_managedBlocks();
-    init_base();
-    AiderAdapter = class extends BaseAdapter {
-      name = "aider";
-      async doGenerate(ctx) {
-        const inner = [
-          ...await this.bridgeHeader(ctx),
-          ...await this.inlineRules(ctx),
-          ...await this.inlineAgents(ctx)
-        ].join("\n").trim();
-        const results = [
-          output("CONVENTIONS.md", wrapInManagedBlock(inner), inner)
-        ];
-        results.push(
-          ...await this.processSkillsRaw(ctx, (id) => `.aider/skills/${toPrefixedId(id)}/SKILL.md`)
-        );
-        results.push(output(".aider.conf.yml", [
-          "# Managed by hatch3r \u2014 do not edit manually",
-          "read:",
-          "  - CONVENTIONS.md",
-          "  - .agents/AGENTS.md",
-          "auto-lint: true",
-          ""
-        ].join("\n")));
-        return results;
-      }
-    };
-  }
-});
-
-// src/adapters/amazonq.ts
-function mapToAmazonQEvent(event) {
-  const mapping = {
-    "session-start": "agentSpawn",
-    "pre-commit": "preToolUse",
-    "file-save": "postToolUse",
-    "post-merge": "postToolUse",
-    "ci-failure": "stop"
-  };
-  return mapping[event] ?? null;
-}
-var AmazonQAdapter;
-var init_amazonq = __esm({
-  "src/adapters/amazonq.ts"() {
-    "use strict";
-    init_types();
-    init_managedBlocks();
-    init_base();
-    init_customization();
-    AmazonQAdapter = class extends BaseAdapter {
-      name = "amazon-q";
-      async doGenerate(ctx) {
-        const results = [];
-        const inner = [
-          ...await this.bridgeHeader(ctx),
-          ...await this.inlineRules(ctx),
-          ...await this.inlineAgents(ctx)
-        ].join("\n").trim();
-        results.push(output(".amazonq/rules/hatch3r-agents.md", wrapInManagedBlock(inner), inner));
-        results.push(
-          ...await this.processSkillsRaw(ctx, (id) => `.amazonq/rules/hatch3r-skill-${id}.md`)
-        );
-        const mcp = await this.readFilteredMcp(ctx);
-        if (mcp && Object.keys(mcp).length > 0) {
-          const entries = this.buildStdMcpEntries(mcp, "shell");
-          if (Object.keys(entries).length > 0) {
-            results.push(output(".amazonq/mcp.json", JSON.stringify({ mcpServers: entries }, null, 2)));
-          }
-        }
-        const hooks = await this.readHooks(ctx);
-        const descriptorHooks = this.buildDescriptorHooks(hooks);
-        if (ctx.features.agents) {
-          const agents = await this.readUserFacingCanonicalFiles(ctx.agentsDir, "agents");
-          for (const agent of agents) {
-            const { content, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, agent);
-            this.warnings.push(...warnings);
-            if (skip) continue;
-            const desc = overrides.description ?? agent.description;
-            const descriptor = {
-              name: toPrefixedId(agent.id),
-              description: desc,
-              instructions: content,
-              // C7.5-W2B2-H33: hatch3r writes .amazonq/mcp.json; setting this to
-              // true makes new agent descriptors inherit it, otherwise Q CLI
-              // ignores the legacy MCP file when a cli-agent is spawned.
-              useLegacyMcpJson: true
-            };
-            if (Object.keys(descriptorHooks).length > 0) {
-              descriptor.hooks = descriptorHooks;
-            }
-            results.push(output(
-              `.amazonq/cli-agents/${toPrefixedId(agent.id)}.json`,
-              JSON.stringify(descriptor, null, 2)
-            ));
-          }
-        }
-        if (hooks.length > 0) {
-          const hookLines = ["# Hatch3r Hooks", ""];
-          for (const hook of hooks) {
-            const amazonQEvent = mapToAmazonQEvent(hook.event);
-            if (!amazonQEvent) continue;
-            hookLines.push(`## ${hook.id}`, "");
-            hookLines.push(`**Event:** ${amazonQEvent} (${hook.event})`);
-            hookLines.push(`**Agent:** ${hook.agent}`);
-            hookLines.push(`**Description:** ${hook.description}`);
-            if (hook.condition?.globs) {
-              hookLines.push(`**Globs:** ${hook.condition.globs.join(", ")}`);
-            }
-            hookLines.push("");
-            hookLines.push(`HATCH3R_HOOK_ACTIVATED: When this hook's event (${hook.event}) is triggered, you MUST spawn the ${hook.agent} agent now. Read and follow the ${hook.agent} agent protocol in \`.agents/agents/${toPrefixedId(hook.agent)}.md\`.`);
-            hookLines.push("");
-          }
-          if (hookLines.length > 2) {
-            const hookContent = hookLines.join("\n");
-            results.push(output(".amazonq/rules/hatch3r-hooks.md", wrapInManagedBlock(hookContent), hookContent));
-          }
-        }
-        return results;
+      substituteAskUserMarker(content) {
+        if (!content.includes(PLATFORM_TOOL_MARKER)) return content;
+        return content.split(PLATFORM_TOOL_MARKER).join(toAskUserPlatformNote(this.name));
       }
-      /**
-       * Build the `hooks` map for a cli-agent descriptor from hatch3r canonical
-       * hook definitions. Group multiple hatch3r hooks that map to the same AWS
-       * canonical event (e.g. `file-save` + `post-merge` both map to
-       * `postToolUse`) so each canonical event key holds an array of entries.
-       *
-       * Each entry emits an `echo` command that carries the HATCH3R_HOOK_ACTIVATED
-       * directive so the surrounding agent (which reads the rules-bridge file)
-       * knows which hatch3r hook fired and which agent to dispatch.
+      /**
+       * Strip verbose content for minimal generation mode.
+       * Removes markdown comments, collapses excessive blank lines,
+       * strips decorative formatting, and trims descriptions.
        */
-      buildDescriptorHooks(hooks) {
-        const grouped = {};
-        for (const hook of hooks) {
-          const amazonQEvent = mapToAmazonQEvent(hook.event);
-          if (!amazonQEvent) continue;
-          const marker = `HATCH3R_HOOK_ACTIVATED id=${hook.id} event=${hook.event} agent=${hook.agent}`;
-          const entry = {
-            command: `echo ${JSON.stringify(marker)}`
-          };
-          (grouped[amazonQEvent] ??= []).push(entry);
-        }
-        return grouped;
+      stripMinimal(content) {
+        let result = content;
+        result = result.replace(/<!--[\s\S]*?-->/g, "");
+        result = result.replace(/^[-*_]{3,}\s*$/gm, "");
+        result = result.replace(/\n{3,}/g, "\n\n");
+        result = result.trim();
+        return result;
       }
     };
   }
 });
 
-// src/adapters/amp.ts
-var AmpAdapter;
-var init_amp = __esm({
-  "src/adapters/amp.ts"() {
+// src/adapters/aider.ts
+var AiderAdapter;
+var init_aider = __esm({
+  "src/adapters/aider.ts"() {
     "use strict";
+    init_types();
+    init_managedBlocks();
     init_base();
-    AmpAdapter = class extends BaseAdapter {
-      name = "amp";
+    AiderAdapter = class extends BaseAdapter {
+      name = "aider";
       async doGenerate(ctx) {
-        const results = [];
-        const mcp = await this.readFilteredMcp(ctx);
-        if (mcp && Object.keys(mcp).length > 0) {
-          const entries = this.buildStdMcpEntries(mcp, "shell");
-          if (Object.keys(entries).length > 0) {
-            results.push(output(".amp/settings.json", JSON.stringify({ "amp.mcpServers": entries }, null, 2)));
-          }
-        }
+        const inner = [
+          ...await this.bridgeHeader(ctx),
+          ...await this.inlineRules(ctx),
+          ...await this.inlineAgents(ctx)
+        ].join("\n").trim();
+        const results = [
+          output("CONVENTIONS.md", wrapInManagedBlock(inner), inner)
+        ];
+        results.push(
+          ...await this.processSkillsRaw(ctx, (id) => `.aider/skills/${toPrefixedId(id)}/SKILL.md`)
+        );
+        results.push(output(".aider.conf.yml", [
+          "# Managed by hatch3r \u2014 do not edit manually",
+          "read:",
+          "  - CONVENTIONS.md",
+          "  - .agents/AGENTS.md",
+          "auto-lint: true",
+          ""
+        ].join("\n")));
         return results;
       }
     };
   }
 });
 
-// src/adapters/antigravity.ts
-var AntigravityAdapter;
-var init_antigravity = __esm({
-  "src/adapters/antigravity.ts"() {
+// src/adapters/amazonq.ts
+function mapToAmazonQEvent(event) {
+  const mapping = {
+    "session-start": "agentSpawn",
+    "pre-commit": "preToolUse",
+    "file-save": "postToolUse",
+    "post-merge": "postToolUse",
+    "ci-failure": "stop"
+  };
+  return mapping[event] ?? null;
+}
+var AmazonQAdapter;
+var init_amazonq = __esm({
+  "src/adapters/amazonq.ts"() {
     "use strict";
     init_types();
     init_managedBlocks();
     init_base();
-    AntigravityAdapter = class extends BaseAdapter {
-      name = "antigravity";
+    init_customization();
+    AmazonQAdapter = class extends BaseAdapter {
+      name = "amazon-q";
       async doGenerate(ctx) {
         const results = [];
         const inner = [
-          ...await this.bridgeHeader(ctx, ".agents/AGENTS.md"),
+          ...await this.bridgeHeader(ctx),
           ...await this.inlineRules(ctx),
           ...await this.inlineAgents(ctx)
         ].join("\n").trim();
-        results.push(output(".antigravity/rules.md", wrapInManagedBlock(inner), inner));
+        results.push(output(".amazonq/rules/hatch3r-agents.md", wrapInManagedBlock(inner), inner));
         results.push(
-          ...await this.processSkillsRaw(ctx, (id) => `.agent/skills/${toPrefixedId(id)}/SKILL.md`)
+          ...await this.processSkillsRaw(ctx, (id) => `.amazonq/rules/hatch3r-skill-${id}.md`)
         );
         const mcp = await this.readFilteredMcp(ctx);
         if (mcp && Object.keys(mcp).length > 0) {
           const entries = this.buildStdMcpEntries(mcp, "shell");
-          if (Object.keys(entries).length > 0) {
-            results.push(output(".antigravity/settings.json", JSON.stringify({ mcpServers: entries }, null, 2)));
-          }
-        }
-        return results;
-      }
-    };
-  }
-});
-
-// src/pipeline/agentToolAllowlist.ts
-function getAgentToolPolicy(agentId) {
-  return policyMap.get(agentId);
-}
-function levenshtein(a, b) {
-  if (a === b) return 0;
-  if (a.length === 0) return b.length;
-  if (b.length === 0) return a.length;
-  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
-  let curr = new Array(b.length + 1);
-  for (let i = 1; i <= a.length; i++) {
-    curr[0] = i;
-    for (let j = 1; j <= b.length; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      curr[j] = Math.min(
-        curr[j - 1] + 1,
-        // insertion
-        prev[j] + 1,
-        // deletion
-        prev[j - 1] + cost
-        // substitution
-      );
-    }
-    [prev, curr] = [curr, prev];
-  }
-  return prev[b.length];
-}
-function suggestNearestCategory(tool) {
-  let bestMatch;
-  let bestDistance = Infinity;
-  for (const known of ALL_TOOL_CATEGORIES) {
-    const dist = levenshtein(tool, known);
-    if (dist < bestDistance) {
-      bestDistance = dist;
-      bestMatch = known;
-    }
-  }
-  return bestDistance <= 2 ? bestMatch : void 0;
-}
-function validateToolPolicies(policies = AGENT_TOOL_POLICIES) {
-  const warnings = [];
-  const knownCategories = new Set(ALL_TOOL_CATEGORIES);
-  for (const policy of policies) {
-    if (policy.allowedTools.length === 0) {
-      warnings.push(`Agent "${policy.agentId}" has an empty tool allowlist \u2014 it cannot invoke any tools.`);
-    }
-    const hasAll = ALL_TOOL_CATEGORIES.every(
-      (cat) => policy.allowedTools.includes(cat)
-    );
-    if (hasAll) {
-      warnings.push(
-        `Agent "${policy.agentId}" has access to all tool categories \u2014 consider restricting to least privilege.`
-      );
-    }
-    for (const tool of policy.allowedTools) {
-      if (!knownCategories.has(tool)) {
-        const suggestion = suggestNearestCategory(tool);
-        const didYouMean = suggestion ? ` Did you mean "${suggestion}"?` : "";
-        throw new HatchError(
-          `Invalid tool policy for agent "${policy.agentId}": unknown tool category "${tool}".${didYouMean} Valid categories: ${ALL_TOOL_CATEGORIES.join(", ")}.`,
-          1,
-          "VALIDATION_ERROR"
-        );
-      }
-    }
-  }
-  return warnings;
-}
-var AGENT_TOOL_POLICIES, policyMap, ALL_TOOL_CATEGORIES;
-var init_agentToolAllowlist = __esm({
-  "src/pipeline/agentToolAllowlist.ts"() {
-    "use strict";
-    init_types();
-    AGENT_TOOL_POLICIES = [
-      {
-        agentId: "hatch3r-researcher",
-        allowedTools: ["read", "search", "web", "mcp"],
-        description: "Read-only research: file reading, code search, web research, MCP queries. No write or execute."
-      },
-      {
-        agentId: "hatch3r-implementer",
-        allowedTools: ["read", "search", "write", "execute"],
-        description: "Code implementation: file read/write, code search, command execution (tests, linters). No git, board, or web."
-      },
-      {
-        agentId: "hatch3r-reviewer",
-        allowedTools: ["read", "search"],
-        description: "Code review: file reading and code search only. No write, execute, git, or board."
-      },
-      {
-        agentId: "hatch3r-fixer",
-        allowedTools: ["read", "search", "write", "execute"],
-        description: "Fix application: file read/write, code search, command execution. No git, board, or web."
-      },
-      {
-        agentId: "hatch3r-test-writer",
-        allowedTools: ["read", "search", "write", "execute"],
-        description: "Test writing: file read/write, code search, test execution. No git, board, or web."
-      },
-      {
-        agentId: "hatch3r-security-auditor",
-        allowedTools: ["read", "search", "execute"],
-        description: "Security audit: file reading, code search, security tool execution. No write, git, board, or web."
-      },
-      {
-        agentId: "hatch3r-docs-writer",
-        allowedTools: ["read", "search", "write"],
-        description: "Documentation: file read/write, code search. No execute, git, board, or web."
-      },
-      {
-        agentId: "hatch3r-lint-fixer",
-        allowedTools: ["read", "search", "write", "execute"],
-        description: "Lint fixing: file read/write, code search, linter execution. No git, board, or web."
-      },
-      {
-        agentId: "hatch3r-a11y-auditor",
-        allowedTools: ["read", "search", "execute"],
-        description: "Accessibility audit: file reading, code search, a11y tool execution. No write, git, board, or web."
-      },
-      {
-        agentId: "hatch3r-perf-profiler",
-        allowedTools: ["read", "search", "execute"],
-        description: "Performance profiling: file reading, code search, profiler execution. No write, git, board, or web."
-      },
-      {
-        agentId: "hatch3r-dependency-auditor",
-        allowedTools: ["read", "search", "execute"],
-        description: "Dependency audit: file reading, code search, audit tool execution. No write, git, board, or web."
-      },
-      {
-        agentId: "hatch3r-architect",
-        allowedTools: ["read", "search", "write"],
-        description: "Architecture: file read/write (docs/ADRs), code search. No execute, git, board, or web."
-      },
-      {
-        agentId: "hatch3r-devops",
-        allowedTools: ["read", "search", "write", "execute"],
-        description: "DevOps: file read/write, code search, CI/CD command execution. No git, board, or web."
-      },
-      {
-        agentId: "hatch3r-ci-watcher",
-        allowedTools: ["read", "search"],
-        description: "CI monitoring: file reading, code search. No write, execute, git, board, or web."
-      },
-      {
-        agentId: "hatch3r-context-rules",
-        allowedTools: ["read", "search"],
-        description: "Context loading: file reading and code search only. No write, execute, git, board, or web."
-      },
-      {
-        agentId: "hatch3r-learnings-loader",
-        allowedTools: ["read", "search"],
-        description: "Learnings loading: file reading and code search only. No write, execute, git, board, or web."
+          if (Object.keys(entries).length > 0) {
+            results.push(output(".amazonq/mcp.json", JSON.stringify({ mcpServers: entries }, null, 2)));
+          }
+        }
+        const hooks = await this.readHooks(ctx);
+        const descriptorHooks = this.buildDescriptorHooks(hooks);
+        if (ctx.features.agents) {
+          const agents = await this.readUserFacingCanonicalFiles(ctx.agentsDir, "agents");
+          for (const agent of agents) {
+            const { content, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, agent);
+            this.warnings.push(...warnings);
+            if (skip) continue;
+            const desc = overrides.description ?? agent.description;
+            const descriptor = {
+              name: toPrefixedId(agent.id),
+              description: desc,
+              instructions: content,
+              // C7.5-W2B2-H33: hatch3r writes .amazonq/mcp.json; setting this to
+              // true makes new agent descriptors inherit it, otherwise Q CLI
+              // ignores the legacy MCP file when a cli-agent is spawned.
+              useLegacyMcpJson: true
+            };
+            if (Object.keys(descriptorHooks).length > 0) {
+              descriptor.hooks = descriptorHooks;
+            }
+            results.push(output(
+              `.amazonq/cli-agents/${toPrefixedId(agent.id)}.json`,
+              JSON.stringify(descriptor, null, 2)
+            ));
+          }
+        }
+        if (hooks.length > 0) {
+          const hookLines = ["# Hatch3r Hooks", ""];
+          for (const hook of hooks) {
+            const amazonQEvent = mapToAmazonQEvent(hook.event);
+            if (!amazonQEvent) continue;
+            hookLines.push(`## ${hook.id}`, "");
+            hookLines.push(`**Event:** ${amazonQEvent} (${hook.event})`);
+            hookLines.push(`**Agent:** ${hook.agent}`);
+            hookLines.push(`**Description:** ${hook.description}`);
+            if (hook.condition?.globs) {
+              hookLines.push(`**Globs:** ${hook.condition.globs.join(", ")}`);
+            }
+            hookLines.push("");
+            hookLines.push(`HATCH3R_HOOK_ACTIVATED: When this hook's event (${hook.event}) is triggered, you MUST spawn the ${hook.agent} agent now. Read and follow the ${hook.agent} agent protocol in \`.agents/agents/${toPrefixedId(hook.agent)}.md\`.`);
+            hookLines.push("");
+          }
+          if (hookLines.length > 2) {
+            const hookContent = hookLines.join("\n");
+            results.push(output(".amazonq/rules/hatch3r-hooks.md", wrapInManagedBlock(hookContent), hookContent));
+          }
+        }
+        return results;
       }
-    ];
-    policyMap = new Map(
-      AGENT_TOOL_POLICIES.map((p) => [p.agentId, p])
-    );
-    ALL_TOOL_CATEGORIES = [
-      "read",
-      "search",
-      "write",
-      "execute",
-      "web",
-      "mcp",
-      "git",
-      "board"
-    ];
+      /**
+       * Build the `hooks` map for a cli-agent descriptor from hatch3r canonical
+       * hook definitions. Group multiple hatch3r hooks that map to the same AWS
+       * canonical event (e.g. `file-save` + `post-merge` both map to
+       * `postToolUse`) so each canonical event key holds an array of entries.
+       *
+       * Each entry emits an `echo` command that carries the HATCH3R_HOOK_ACTIVATED
+       * directive so the surrounding agent (which reads the rules-bridge file)
+       * knows which hatch3r hook fired and which agent to dispatch.
+       */
+      buildDescriptorHooks(hooks) {
+        const grouped = {};
+        for (const hook of hooks) {
+          const amazonQEvent = mapToAmazonQEvent(hook.event);
+          if (!amazonQEvent) continue;
+          const marker = `HATCH3R_HOOK_ACTIVATED id=${hook.id} event=${hook.event} agent=${hook.agent}`;
+          const entry = {
+            command: `echo ${JSON.stringify(marker)}`
+          };
+          (grouped[amazonQEvent] ??= []).push(entry);
+        }
+        return grouped;
+      }
+    };
   }
 });
 
-// src/pipeline/adapterToolTranslator.ts
-function toClaudeToolsFrontmatter(agentId) {
-  const policy = getAgentToolPolicy(agentId);
-  if (!policy) return null;
-  const tools = resolveNativeTools(policy.allowedTools, CLAUDE_CATEGORY_MAP);
-  if (tools.length === 0) return null;
-  return tools.join(", ");
-}
-function toCopilotToolsFrontmatter(agentId) {
-  const policy = getAgentToolPolicy(agentId);
-  if (!policy) return null;
-  const tools = resolveNativeTools(policy.allowedTools, COPILOT_CATEGORY_MAP);
-  return tools.length === 0 ? null : tools;
-}
-function toWindsurfToolsFrontmatter(agentId) {
-  const policy = getAgentToolPolicy(agentId);
-  if (!policy) return null;
-  const tools = resolveNativeTools(policy.allowedTools, WINDSURF_CATEGORY_MAP);
-  if (tools.length === 0) return null;
-  return tools.join(", ");
-}
-function toCursorReadonlyFrontmatter(agentId) {
-  const policy = getAgentToolPolicy(agentId);
-  if (!policy) return null;
-  const hasWrite = policy.allowedTools.includes("write");
-  const hasExecute = policy.allowedTools.includes("execute");
-  return !hasWrite && !hasExecute;
-}
-function resolveNativeTools(categories, map) {
-  const out = /* @__PURE__ */ new Set();
-  for (const cat of categories) {
-    const native = map[cat];
-    if (!native) continue;
-    for (const t of native) out.add(t);
-  }
-  return [...out];
-}
-var CLAUDE_CATEGORY_MAP, COPILOT_CATEGORY_MAP, WINDSURF_CATEGORY_MAP;
-var init_adapterToolTranslator = __esm({
-  "src/pipeline/adapterToolTranslator.ts"() {
+// src/adapters/amp.ts
+var AmpAdapter;
+var init_amp = __esm({
+  "src/adapters/amp.ts"() {
     "use strict";
-    init_agentToolAllowlist();
-    CLAUDE_CATEGORY_MAP = {
-      read: ["Read", "NotebookRead"],
-      search: ["Grep", "Glob"],
-      write: ["Edit", "MultiEdit", "Write", "NotebookEdit"],
-      execute: ["Bash"],
-      web: ["WebSearch", "WebFetch"],
-      mcp: [],
-      // MCP tools are scoped via the `mcpServers` frontmatter field, not `tools`.
-      git: ["Bash"],
-      // Git is driven via Bash; callers that grant git retain execute semantics.
-      board: []
-      // Project-board tooling is MCP-driven; see mcp mapping.
+    init_base();
+    AmpAdapter = class extends BaseAdapter {
+      name = "amp";
+      async doGenerate(ctx) {
+        const results = [];
+        const mcp = await this.readFilteredMcp(ctx);
+        if (mcp && Object.keys(mcp).length > 0) {
+          const entries = this.buildStdMcpEntries(mcp, "shell");
+          if (Object.keys(entries).length > 0) {
+            results.push(output(".amp/settings.json", JSON.stringify({ "amp.mcpServers": entries }, null, 2)));
+          }
+        }
+        return results;
+      }
     };
-    COPILOT_CATEGORY_MAP = {
-      read: ["read"],
-      search: ["search"],
-      write: ["edit"],
-      execute: ["execute"],
-      web: ["web"],
-      mcp: [],
-      // MCP exposure is controlled via `mcp-servers`, not `tools`.
-      git: ["execute"],
-      board: []
+  }
+});
+
+// src/adapters/antigravity.ts
+var AntigravityAdapter;
+var init_antigravity = __esm({
+  "src/adapters/antigravity.ts"() {
+    "use strict";
+    init_types();
+    init_managedBlocks();
+    init_base();
+    AntigravityAdapter = class extends BaseAdapter {
+      name = "antigravity";
+      async doGenerate(ctx) {
+        const results = [];
+        const inner = [
+          ...await this.bridgeHeader(ctx, ".agents/AGENTS.md"),
+          ...await this.inlineRules(ctx),
+          ...await this.inlineAgents(ctx)
+        ].join("\n").trim();
+        results.push(output(".antigravity/rules.md", wrapInManagedBlock(inner), inner));
+        results.push(
+          ...await this.processSkillsRaw(ctx, (id) => `.agent/skills/${toPrefixedId(id)}/SKILL.md`)
+        );
+        const mcp = await this.readFilteredMcp(ctx);
+        if (mcp && Object.keys(mcp).length > 0) {
+          const entries = this.buildStdMcpEntries(mcp, "shell");
+          if (Object.keys(entries).length > 0) {
+            results.push(output(".antigravity/settings.json", JSON.stringify({ mcpServers: entries }, null, 2)));
+          }
+        }
+        return results;
+      }
     };
-    WINDSURF_CATEGORY_MAP = CLAUDE_CATEGORY_MAP;
   }
 });
 
@@ -6120,7 +6270,7 @@ var init_packageManager = __esm({
 });
 
 // src/adapters/copilot.ts
-var CopilotAdapter;
+var COPILOT_ENFORCEMENT_ADDENDUM, CopilotAdapter;
 var init_copilot = __esm({
   "src/adapters/copilot.ts"() {
     "use strict";
@@ -6132,6 +6282,30 @@ var init_copilot = __esm({
     init_customization();
     init_packageManager();
     init_adapterToolTranslator();
+    COPILOT_ENFORCEMENT_ADDENDUM = `## Copilot Enforcement Model (no hook surface)
+
+GitHub Copilot Chat does not expose a PreToolUse or pre-edit hook
+(see \`src/adapters/index.ts\` \u2014 \`copilot\` is the only adapter with
+\`hooks: false\` in \`ADAPTER_CAPABILITIES\`). Hatch3r cannot block
+code-writing tool calls server-side for Copilot. Enforcement is
+therefore trust-based \u2014 the directives in this file and in
+\`.github/instructions/\` are normative, not advisory.
+
+Self-detectable drift indicators (halt the current turn if any appear):
+
+- Missing pipeline-state header on a tracked Tier 2+ task (see
+  \`hatch3r-agent-orchestration\` \u2192 Per-Turn Pipeline-State Header).
+- A call to \`replace_string_in_file\`, \`multi_replace_string_in_file\`,
+  \`create_file\`, or any code-writing tool before the user has
+  confirmed the Pre-Implementation Summary on a Tier 3 task (see
+  \`hatch3r-deep-context\` \u2192 Tier 3 \u2014 Deep).
+- An \`Edit\` / \`Write\` invocation from the orchestrator turn that
+  did not immediately follow a SUCCESS report from \`hatch3r-implementer\`
+  via the \`Task\` tool.
+
+On any drift, halt and re-delegate via \`hatch3r-implementer\` (Phase 2)
+or \`hatch3r-fixer\` (Phase 3). The only carve-out is \`hatch3r-quick-change\`
+Tier 1 trivial single-line edits per its declared scope.`;
     CopilotAdapter = class extends BaseAdapter {
       name = "copilot";
       async doGenerate(ctx) {
@@ -6142,9 +6316,10 @@ var init_copilot = __esm({
           const rules = await readCanonicalFiles(ctx.agentsDir, "rules", this.warnings);
           const sortedRules = sortByPrecedence(rules);
           for (const rule of sortedRules) {
-            const { content, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, rule);
+            const { content: rawContent, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, rule);
             this.warnings.push(...warnings);
             if (skip) continue;
+            const content = this.substituteAskUserMarker(rawContent);
             const scope = overrides.scope ?? rule.scope;
             if (scope && scope !== "always") {
               scopedRules.push({ rule: { ...rule, description: overrides.description ?? rule.description }, content, scope });
@@ -6162,6 +6337,8 @@ var init_copilot = __esm({
           "",
           bridgeOrchestration,
           "",
+          COPILOT_ENFORCEMENT_ADDENDUM,
+          "",
           "## Hatch3r Rules",
           "",
           ...alwaysRules.map(
@@ -6199,7 +6376,7 @@ jobs:
         run: ${build}`;
         results.push(output(
           ".github/workflows/copilot-setup-steps.yml",
-          wrapInManagedBlock(copilotSetupStepsInner) + "\n",
+          wrapInManagedBlock(copilotSetupStepsInner),
           copilotSetupStepsInner
         ));
         for (const { rule, content, scope } of scopedRules) {
@@ -6227,9 +6404,10 @@ ${wrapInManagedBlock(body)}`,
         if (ctx.features.agents) {
           const agents = await this.readUserFacingCanonicalFiles(ctx.agentsDir, "agents");
           for (const agent of agents) {
-            const { content, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, agent);
+            const { content: rawContent, skip, overrides, warnings } = await applyCustomization(ctx.projectRoot, agent);
             this.warnings.push(...warnings);
             if (skip) continue;
+            const content = this.substituteAskUserMarker(rawContent);
             const model = resolveAgentModel(agent.id, agent, ctx.manifest, overrides);
             const desc = overrides.description ?? agent.description;
             const prefixedId = toPrefixedId(agent.id);
@@ -7166,28 +7344,28 @@ var init_adapters = __esm({
     };
     adapterCache = /* @__PURE__ */ new Map();
     ADAPTER_CAPABILITIES = {
-      cursor: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true },
-      claude: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true },
-      gemini: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true },
-      cline: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true },
-      codex: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true },
-      "amazon-q": { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true },
-      copilot: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: true, prompts: true, githubAgents: true, worktree: true, customization: true, modelOverride: true },
-      opencode: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true },
+      cursor: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false },
+      claude: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: true },
+      gemini: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false },
+      cline: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false },
+      codex: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
+      "amazon-q": { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
+      copilot: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: true, prompts: true, githubAgents: true, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false },
+      opencode: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
       // C7.5-W2B2-H31 (D9-SA9.7.1): Windsurf shipped Cascade Hooks in v1.13.12 (2026-01-25).
       // Hatch3r emits `.windsurf/hooks.json` per docs.windsurf.com/windsurf/cascade/hooks.md.
-      windsurf: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true },
+      windsurf: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: true, prompts: false, githubAgents: false, worktree: true, customization: true, modelOverride: true, nativeQuestionTool: false },
       // Amp reads AGENTS.md natively; the root file is written by generateRootAgentsMd()
       // in init/update, not by this adapter. Amp also reads skills natively from
       // `.agents/skills/` — populated by copyHatch3rFiles, not re-emitted by this
       // adapter (re-emission corrupts SKILL.md frontmatter via managed-block wrap).
       // doGenerate() emits MCP settings only.
-      amp: { agents: false, skills: false, rules: false, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true },
-      kiro: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true },
-      aider: { agents: true, skills: true, rules: true, hooks: false, mcp: false, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true },
-      goose: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true },
-      zed: { agents: true, skills: false, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: false, modelOverride: false },
-      antigravity: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true }
+      amp: { agents: false, skills: false, rules: false, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
+      kiro: { agents: true, skills: true, rules: true, hooks: true, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
+      aider: { agents: true, skills: true, rules: true, hooks: false, mcp: false, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
+      goose: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false },
+      zed: { agents: true, skills: false, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: false, modelOverride: false, nativeQuestionTool: false },
+      antigravity: { agents: true, skills: true, rules: true, hooks: false, mcp: true, commands: false, prompts: false, githubAgents: false, worktree: false, customization: true, modelOverride: true, nativeQuestionTool: false }
     };
   }
 });
@@ -11115,6 +11293,62 @@ tags: [<tag>, ...]
 The loader agent applies content-security and integrity checks to every
 entry; see \`hatch3r-learnings-loader\` for the full protocol.
 
+## Recommended First Learning \u2014 Pipeline Drift
+
+Copy the markdown block below into \`.agents/learnings/pipeline-drift-rule-73.md\`
+to prime your AI tool against the bypass pattern reported in hatch3r
+issue #73 (GitHub Copilot Chat skipping the four-phase sub-agent
+pipeline on Tier-3 epics). The \`hatch3r-learnings-loader\` agent will
+surface it on session start.
+
+\`\`\`markdown
+---
+id: pipeline-drift-rule-73
+category: pitfall
+area: orchestration
+recorded: 2026-05-12
+source: manual
+confidence: high
+author: human
+tags: [orchestration, copilot, drift]
+---
+
+## Learning
+
+The hatch3r four-phase sub-agent pipeline (Research -> Implement ->
+Review -> Quality) is trust-based on Copilot Chat \u2014 Copilot has
+\`hooks: false\` in \`src/adapters/index.ts\`, exposes no PreToolUse /
+pre-edit hook, and does not surface its chat transcript to external
+processes. Drift is invisible by default: Copilot can call
+\`multi_replace_string_in_file\` / \`create_file\` inline on a Tier-3
+task and the build can still pass.
+
+Self-detectable signals:
+
+- The orchestrator's reply does NOT start with the
+  \`[hatch3r-pipeline: phase N | last: ... | next: ...]\` header on
+  a tracked Tier 2+ task -> halt and re-ground.
+- A code-writing tool was called before the user confirmed the
+  Pre-Implementation Summary on a Tier 3 task -> bypass mode.
+- An \`Edit\` / \`Write\` / equivalent fired from the orchestrator
+  turn rather than from inside a \`hatch3r-implementer\` Task
+  sub-agent -> bypass mode.
+
+## Evidence
+
+- Issue: https://github.com/hatch3r-dev/hatch3r/issues/73
+- Rules: \`rules/hatch3r-agent-orchestration.md\` (Per-Turn
+  Pipeline-State Header, Mandatory Delegation Directive);
+  \`rules/hatch3r-deep-context.md\` (Tier 3 \u2014 Deep hard gate).
+- Adapter capability: \`src/adapters/index.ts\` \u2014 \`copilot\` is the
+  only adapter with \`hooks: false\`.
+\`\`\`
+
+Customize the \`recorded\` date and \`tags\` to match your setup.
+Adapters other than Copilot also benefit from this learning when
+the bypass pattern is plausible on their host (e.g., long-context
+sessions on any adapter).
+
 Delete this README once you have authored real learnings.
 `;
 function selectionHasBoardContent(selection) {
@@ -11200,7 +11434,12 @@ async function runInitInner(options) {
   s1.succeed(step(1, totalSteps, `Canonical files created (${countSelectionItems(contentSelection)} items)`));
   const s2 = createSpinner(step(2, totalSteps, "Preparing manifest..."));
   s2.start();
-  const manifest = createManifest({ platform, owner, repo, namespace, project, defaultBranch, tools, features, mcpServers, content: contentSelection, languages: repoInfo.languages, worktreeEnabled, customization });
+  const effectiveCustomization = customization ?? existingManifest?.customization;
+  const manifest = createManifest({ platform, owner, repo, namespace, project, defaultBranch, tools, features, mcpServers, content: contentSelection, languages: repoInfo.languages, worktreeEnabled, customization: effectiveCustomization });
+  const preservedFields = options.preservedManifestFields ?? (existingManifest ? extractPreservedManifestFields(existingManifest) : void 0);
+  if (preservedFields) {
+    applyPreservedManifestFields(manifest, preservedFields);
+  }
   s2.succeed(step(2, totalSteps, "Manifest prepared"));
   const s3 = createSpinner(
     step(3, totalSteps, `Generating ${tools.map((t) => TOOL_DISPLAY_NAMES[t] ?? t).join(", ")} output...`)
@@ -12069,6 +12308,7 @@ function resolveToolsFromOpts(toolsFlag, repoInfo) {
 }
 
 // src/cli/commands/clean.ts
+init_hatchJson();
 function captureConfig(manifest) {
   return {
     platform: manifest.platform ?? "github",
@@ -12087,7 +12327,8 @@ function captureConfig(manifest) {
       items: { agents: [], skills: [], rules: [], commands: [], prompts: [], hooks: [], githubAgents: [] }
     },
     worktreeEnabled: manifest.worktree?.enabled ?? false,
-    customization: manifest.customization
+    customization: manifest.customization,
+    preservedFields: extractPreservedManifestFields(manifest)
   };
 }
 function printInventory(inventory) {
@@ -12237,6 +12478,10 @@ async function cleanCommand(opts = {}) {
           // manifest preserves integration config and per-artifact overrides
           // across a clean -> reinit cycle.
           customization: config.customization,
+          // 1.7.1: carry full platform/user manifest state (board IDs,
+          // costTracking, specs, extension config, worktree extras) forward
+          // so a clean -> reinit cycle no longer wipes them.
+          preservedManifestFields: config.preservedFields,
           // Reinit-after-clean already prompted the user; suppress runInit's
           // own post-init create-prompt so we do not stack two confirmations.
           yes: true
@@ -13039,7 +13284,7 @@ function normalizeToRepoPath(absPath, rootDir) {
   const rel = relative6(rootDir, absPath);
   return sep5 === "/" ? rel : rel.split(sep5).join(posix3.sep);
 }
-function buildProvenanceManifest(hatchVersion, rootDir, perAdapterOutputs) {
+function buildProvenanceManifest(hatchVersion, rootDir, perAdapterOutputs, previousManifest) {
   const entries = [];
   for (const { adapter, outputs } of perAdapterOutputs) {
     for (const out of outputs) {
@@ -13056,6 +13301,9 @@ function buildProvenanceManifest(hatchVersion, rootDir, perAdapterOutputs) {
     if (byAdapter !== 0) return byAdapter;
     return a.path.localeCompare(b.path);
   });
+  if (previousManifest && previousManifest.hatchVersion === hatchVersion && provenanceEntriesEqual(previousManifest.entries, entries)) {
+    return previousManifest;
+  }
   return {
     version: 1,
     generated: (/* @__PURE__ */ new Date()).toISOString(),
@@ -13063,10 +13311,62 @@ function buildProvenanceManifest(hatchVersion, rootDir, perAdapterOutputs) {
     entries
   };
 }
+function provenanceEntriesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const ea = a[i];
+    const eb = b[i];
+    if (ea.adapter !== eb.adapter) return false;
+    if (ea.path !== eb.path) return false;
+    if (ea.sourceFiles.length !== eb.sourceFiles.length) return false;
+    for (let j = 0; j < ea.sourceFiles.length; j++) {
+      if (ea.sourceFiles[j] !== eb.sourceFiles[j]) return false;
+    }
+  }
+  return true;
+}
 async function writeProvenanceManifest(agentsDir, manifest) {
   const filePath = join31(agentsDir, PROVENANCE_FILE);
   await atomicWriteFile(filePath, JSON.stringify(manifest, null, 2) + "\n");
 }
+async function readProvenanceManifest(agentsDir) {
+  const filePath = join31(agentsDir, PROVENANCE_FILE);
+  let raw;
+  try {
+    raw = await readFile22(filePath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    if (err instanceof SyntaxError) return null;
+    throw err;
+  }
+  if (!isProvenanceManifest(parsed)) return null;
+  return parsed;
+}
+function isProvenanceManifest(data) {
+  if (typeof data !== "object" || data === null) return false;
+  const obj = data;
+  if (typeof obj.version !== "number") return false;
+  if (typeof obj.generated !== "string") return false;
+  if (typeof obj.hatchVersion !== "string") return false;
+  if (!Array.isArray(obj.entries)) return false;
+  for (const e of obj.entries) {
+    if (typeof e !== "object" || e === null) return false;
+    const entry = e;
+    if (typeof entry.adapter !== "string") return false;
+    if (typeof entry.path !== "string") return false;
+    if (!Array.isArray(entry.sourceFiles)) return false;
+    for (const s of entry.sourceFiles) {
+      if (typeof s !== "string") return false;
+    }
+  }
+  return true;
+}
 
 // src/cli/commands/sync.ts
 init_archive();
@@ -13442,12 +13742,16 @@ async function syncCommand(opts = {}) {
         `Integrity manifest regenerated with ${successfulAdapters.length}/${m.tools.length} adapters successful. Re-run sync after resolving errors to produce a complete manifest.`
       );
     }
+    const previousProvenanceManifest = await readProvenanceManifest(agentsDir);
     const provenanceManifest = buildProvenanceManifest(
       HATCH3R_VERSION,
       rootDir,
-      perAdapterOutputs
+      perAdapterOutputs,
+      previousProvenanceManifest
     );
-    await writeProvenanceManifest(agentsDir, provenanceManifest);
+    if (provenanceManifest !== previousProvenanceManifest) {
+      await writeProvenanceManifest(agentsDir, provenanceManifest);
+    }
     const orphanDiag = formatOrphanCleanupDiagnostic(orphanEntries);
     if (orphanDiag) warn(orphanDiag);
     const mergedByAdapter = { ...previousManagedByAdapter };