@mmerterden/multi-agent-pipeline 12.11.0 → 13.0.0

package/install/codex.mjs

@@ -0,0 +1,478 @@
+/**
+ * Codex CLI installer.
+ *
+ * Lays down `~/.codex/{skills/multi-agent,multi-agent-refs,agents,prompts,
+ * scripts,lib,schemas}/` plus the managed block in `~/.codex/AGENTS.md`, and
+ * registers the dev-toolkit MCP server through the `codex` CLI.
+ *
+ * Shape note: this target follows the **Claude Code** thin-dispatcher layout,
+ * not the Copilot CLI fan-out. Codex assembles every discovered skill's
+ * name + description into a single prompt block and silently drops entries once
+ * that block overflows - measured at install-design time, one 142-skill plugin
+ * surfaced only 75 of its skills AND evicted an unrelated user skill. So the
+ * pipeline contributes exactly one skill (`multi-agent`) and keeps its 42
+ * sub-command specs as reference files that cost nothing until read. Converting
+ * them into peer skills would silently lose pipeline commands.
+ *
+ * @module install/codex
+ */
+
+import { existsSync, readFileSync, readdirSync, rmSync } from "fs";
+import { join } from "path";
+import { execFileSync } from "child_process";
+
+import {
+  copyDir,
+  copyFile,
+  countFiles,
+  ensureDir,
+  ensureRealDir,
+  isDryRun,
+  wipeDir,
+  writeFile,
+} from "./_common.mjs";
+import { DEV_ONLY_SCRIPTS, countDevOnlyFiles } from "./_dev-only-files.mjs";
+import { installCodexAgents } from "./_codex-agents.mjs";
+import { generateCodexInstructions } from "./_codex-instructions.mjs";
+import { mergeManagedBlock } from "./_managed-block.mjs";
+
+/** Start of the pipeline-managed span in `~/.codex/AGENTS.md`. */
+export const AGENTS_MD_START_MARKER = "# Multi-Agent Development Pipeline";
+
+/** Explicit end marker written after the pipeline section. */
+export const AGENTS_MD_END_MARKER = "<!-- multi-agent-pipeline:codex-instructions:end -->";
+
+/** MCP server the pipeline's `/multi-agent:test` + design-check flows depend on. */
+export const MCP_SERVER_NAME = "dev-toolkit";
+const MCP_SERVER_PACKAGE = "@mmerterden/dev-toolkit-mcp";
+
+/**
+ * `$HOME/.claude/...` path rewrites applied to every file installed into the
+ * Codex tree.
+ *
+ * Two categories, and the split is deliberate:
+ *
+ * - **CLI-owned trees** (refs, agents, scripts, lib, schemas, and the command
+ *   specs) are installed under `~/.codex/`, so their references must point
+ *   there. A Codex-only install has no `~/.claude` tree at all.
+ * - **Shared state** (`logs/`, `multi-agent-preferences.json`, `knowledge/`) is
+ *   intentionally NOT rewritten. `~/.claude` is the cross-host state root - it
+ *   is what makes `:resume` / `:log` / `:status` work on a task started from a
+ *   different CLI. Copilot CLI already behaves this way.
+ *
+ * Order matters: the command-spec rule must run before the generic `commands`
+ * rule, and both before the bare-directory rules.
+ *
+ * @type {ReadonlyArray<{from: RegExp, to: string}>}
+ */
+export const CODEX_PATH_REWRITES = Object.freeze([
+  // The dispatcher itself. MUST come first: the rules below match the bare
+  // `commands/multi-agent` prefix, and `\b` treats the `.` in `multi-agent.md`
+  // as a boundary - so a later-ordered rule rewrites this filename into
+  // `multi-agent-refs/commands.md`, a path that does not exist. On Codex the
+  // dispatcher is the router skill.
+  {
+    from: /\$HOME\/\.claude\/commands\/multi-agent\.md/g,
+    to: "$HOME/.codex/skills/multi-agent/SKILL.md",
+  },
+  { from: /~\/\.claude\/commands\/multi-agent\.md/g, to: "~/.codex/skills/multi-agent/SKILL.md" },
+  // Sub-command specs become reference files under the Codex refs tree.
+  {
+    from: /\$HOME\/\.claude\/commands\/multi-agent\b/g,
+    to: "$HOME/.codex/multi-agent-refs/commands",
+  },
+  { from: /~\/\.claude\/commands\/multi-agent\b/g, to: "~/.codex/multi-agent-refs/commands" },
+  // Standalone command specs (sim-test.md, deploy.md, ...) land in the same
+  // refs/commands dir, so these generic rules follow the multi-agent ones.
+  { from: /\$HOME\/\.claude\/commands\b/g, to: "$HOME/.codex/multi-agent-refs/commands" },
+  { from: /~\/\.claude\/commands\b/g, to: "~/.codex/multi-agent-refs/commands" },
+  { from: /\$HOME\/\.claude\/multi-agent-refs\b/g, to: "$HOME/.codex/multi-agent-refs" },
+  { from: /~\/\.claude\/multi-agent-refs\b/g, to: "~/.codex/multi-agent-refs" },
+  { from: /\$HOME\/\.claude\/agents\b/g, to: "$HOME/.codex/agents" },
+  { from: /~\/\.claude\/agents\b/g, to: "~/.codex/agents" },
+  { from: /\$HOME\/\.claude\/scripts\b/g, to: "$HOME/.codex/scripts" },
+  { from: /~\/\.claude\/scripts\b/g, to: "~/.codex/scripts" },
+  { from: /\$HOME\/\.claude\/lib\b/g, to: "$HOME/.codex/lib" },
+  { from: /~\/\.claude\/lib\b/g, to: "~/.codex/lib" },
+  { from: /\$HOME\/\.claude\/schemas\b/g, to: "$HOME/.codex/schemas" },
+  { from: /~\/\.claude\/schemas\b/g, to: "~/.codex/schemas" },
+  // The convention rules the analysis phase falls back to when a project ships
+  // no standards file. Dangling here means that fallback silently yields
+  // nothing, so the tree is installed on Codex too.
+  { from: /\$HOME\/\.claude\/rules\b/g, to: "$HOME/.codex/rules" },
+  { from: /~\/\.claude\/rules\b/g, to: "~/.codex/rules" },
+  // Personas are Markdown on Claude Code and generated TOML on Codex, so the
+  // directory rewrite above is not enough: `agents/code-reviewer.md` has to
+  // become `agents/code-reviewer.toml` or every persona reference in the refs
+  // resolves to nothing. Runs last, after the directory rules.
+  { from: /(\$HOME|~)\/\.codex\/agents\/([a-z0-9-]+)\.md\b/g, to: "$1/.codex/agents/$2.toml" },
+]);
+
+/**
+ * Apply the Codex path map to a file's text.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function rewriteCodexPaths(text) {
+  let out = text;
+  for (const { from, to } of CODEX_PATH_REWRITES) out = out.replace(from, to);
+  return out;
+}
+
+/**
+ * Rewrite the dispatcher's frontmatter for Codex.
+ *
+ * Codex requires `name` + `description`. `allowed-tools` is a Claude Code
+ * concept and `description-tr` is an installed-Claude-tree localization
+ * artifact, so both are dropped - the same rule the Copilot transform follows.
+ *
+ * @param {string} raw - dispatcher SKILL.md content
+ * @param {string} name - skill name to declare
+ * @returns {string}
+ */
+export function toCodexSkill(raw, name) {
+  const lines = raw.split("\n");
+  if (lines[0]?.trim() !== "---") {
+    return `---\nname: ${name}\ndescription: "Multi-agent development pipeline orchestrator"\n---\n\n${raw}`;
+  }
+
+  let description = "";
+  let i = 1;
+  for (; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      i++;
+      break;
+    }
+    const m = /^description:\s*(.*)$/.exec(lines[i]);
+    if (m) description = m[1].trim();
+  }
+
+  const body = lines.slice(i).join("\n").replace(/^\n+/, "");
+  const front = [
+    "---",
+    `name: ${name}`,
+    `description: ${description || '"Multi-agent pipeline"'}`,
+    "---",
+  ];
+  return `${front.join("\n")}\n\n${body}`;
+}
+
+/**
+ * @param {{
+ *   home: string,
+ *   pipelineSrc: string,
+ *   indexOnly: boolean,
+ *   useSymlinks: boolean,
+ *   platformFlag: "ios"|"android"|"all",
+ * }} ctx
+ */
+export function installCodex(ctx) {
+  // `indexOnly` and `platformFlag` are intentionally not read. Both exist to
+  // shrink the 428-file external skills tree, which this target never installs:
+  // Codex gets one router skill, so there is nothing for either flag to reduce.
+  // Documented rather than silently dropped, so a future reader does not "fix"
+  // it by wiring flags that would have no effect.
+  const { home, pipelineSrc, useSymlinks } = ctx;
+
+  const CODEX_DIR = join(home, ".codex");
+  const CODEX_SKILLS = join(CODEX_DIR, "skills");
+  const CODEX_MA_REFS = join(CODEX_DIR, "multi-agent-refs");
+  const CODEX_AGENTS = join(CODEX_DIR, "agents");
+  const CODEX_PROMPTS = join(CODEX_DIR, "prompts");
+  const CODEX_SCRIPTS = join(CODEX_DIR, "scripts");
+  const CODEX_LIB = join(CODEX_DIR, "lib");
+  const CODEX_SCHEMAS = join(CODEX_DIR, "schemas");
+  const CODEX_RULES = join(CODEX_DIR, "rules");
+
+  console.log("  [Codex CLI] Installing pipeline orchestrator...");
+  ensureDir(CODEX_DIR);
+
+  installRouterSkill(pipelineSrc, CODEX_SKILLS);
+  installRefs(pipelineSrc, CODEX_MA_REFS);
+  installPersonas(pipelineSrc, CODEX_AGENTS);
+  installPrompt(CODEX_PROMPTS);
+  installScripts(pipelineSrc, CODEX_SCRIPTS, useSymlinks);
+  installTree("lib", pipelineSrc, CODEX_LIB, useSymlinks);
+  installTree("schemas", pipelineSrc, CODEX_SCHEMAS, useSymlinks);
+  installTree("rules", pipelineSrc, CODEX_RULES, useSymlinks);
+  writeAgentsMd(join(CODEX_DIR, "AGENTS.md"));
+  ensureSharedPreferences(home, pipelineSrc);
+  registerMcpServer();
+
+  console.log("");
+}
+
+/**
+ * Write the single router skill, and prune per-command skill dirs left by any
+ * install that predates the one-skill layout.
+ */
+function installRouterSkill(pipelineSrc, skillsDir) {
+  const dispatcherSrc = join(pipelineSrc, "commands", "multi-agent", "SKILL.md");
+  if (!existsSync(dispatcherSrc)) return;
+
+  // ensureRealDir only swaps a --link-era symlink for a real dir; ensureDir
+  // creates a missing one. Every owned tree below needs both.
+  ensureRealDir(skillsDir);
+  ensureDir(skillsDir);
+  pruneLegacyCommandSkills(skillsDir);
+
+  const raw = readFileSync(dispatcherSrc, "utf-8");
+  const skill = rewriteCodexPaths(toCodexSkill(raw, "multi-agent"));
+  const dest = join(skillsDir, "multi-agent");
+  ensureDir(dest);
+  writeFile(join(dest, "SKILL.md"), skill);
+  console.log(`    -> 1 router skill written to ${dest} (42 command specs stay as refs)`);
+}
+
+/**
+ * A pre-router install (or a hand-copied Copilot tree) leaves
+ * `multi-agent-<cmd>/` skill dirs behind. Each one costs a slot in the skills
+ * block, which is exactly the overflow this layout avoids, so remove them.
+ */
+function pruneLegacyCommandSkills(skillsDir) {
+  if (!existsSync(skillsDir)) return;
+  let pruned = 0;
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (!entry.name.startsWith("multi-agent-")) continue;
+    if (isDryRun()) {
+      console.log(`    [dry-run] would prune per-command skill dir ${join(skillsDir, entry.name)}`);
+      pruned++;
+      continue;
+    }
+    try {
+      rmSync(join(skillsDir, entry.name), { recursive: true, force: true });
+      pruned++;
+    } catch {
+      /* non-fatal */
+    }
+  }
+  if (pruned > 0) {
+    console.log(
+      `    -> pruned ${pruned} per-command skill dir(s) (they overflow the skills block)`,
+    );
+  }
+}
+
+/**
+ * Install the reference tree: the shared `multi-agent-refs/` docs plus the 42
+ * sub-command specs, all path-rewritten. These are read on demand and never
+ * enter the skills block.
+ */
+function installRefs(pipelineSrc, dest) {
+  const refsSrc = join(pipelineSrc, "multi-agent-refs");
+  const commandsSrc = join(pipelineSrc, "commands", "multi-agent");
+
+  ensureRealDir(dest);
+  ensureDir(dest);
+  wipeDir(dest);
+
+  let count = 0;
+  if (existsSync(refsSrc)) count += copyTreeRewritten(refsSrc, dest);
+
+  // The 42 sub-command specs. Skip ONLY the top-level dispatcher SKILL.md -
+  // it already shipped as the router skill. The filter is on the path relative
+  // to the copy root, not the basename: every sub-command spec is itself named
+  // SKILL.md, so a basename filter would copy 42 empty directories and leave
+  // the orchestrator with nothing to read.
+  if (existsSync(commandsSrc)) {
+    count += copyTreeRewritten(commandsSrc, join(dest, "commands"), (rel) => rel !== "SKILL.md");
+  }
+
+  // Standalone Claude Code command specs (sim-test, deploy, archive-guard, ...).
+  // The router delegates to these by path, so a Codex install that omits them
+  // leaves those routes dangling.
+  const standaloneSrc = join(pipelineSrc, "commands");
+  if (existsSync(standaloneSrc)) {
+    count += copyTreeRewritten(standaloneSrc, join(dest, "commands"), (rel) =>
+      /^[^/]+\.md$/.test(rel),
+    );
+  }
+
+  console.log(`    -> ${count} reference file(s) copied to ${dest}`);
+}
+
+/**
+ * Recursively copy a tree, applying the Codex path map to text files.
+ *
+ * Not `copyDir` from `_common.mjs`: that copies bytes, and every ref file here
+ * carries `$HOME/.claude/...` references that must be retargeted.
+ *
+ * @param {string} src
+ * @param {string} dest
+ * @param {(relPath: string) => boolean} [filter] - receives the path relative to
+ *   the copy root (POSIX-separated), not the basename. Return false to skip.
+ * @param {string} [relBase] - internal: accumulated relative path
+ * @returns {number} files written
+ */
+function copyTreeRewritten(src, dest, filter, relBase = "") {
+  const TEXT = /\.(md|json|sh|mjs|js|txt|ya?ml|toml)$/i;
+  let n = 0;
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const from = join(src, entry.name);
+    const to = join(dest, entry.name);
+    const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      n += copyTreeRewritten(from, to, filter, rel);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (filter && !filter(rel)) continue;
+    ensureDir(dest);
+    const raw = readFileSync(from, TEXT.test(entry.name) ? "utf-8" : null);
+    writeFile(to, TEXT.test(entry.name) ? rewriteCodexPaths(raw) : raw);
+    n++;
+  }
+  return n;
+}
+
+function installPersonas(pipelineSrc, dest) {
+  const agentsSrc = join(pipelineSrc, "agents");
+  if (!existsSync(agentsSrc)) return;
+  const written = installCodexAgents(agentsSrc, dest);
+  console.log(`    -> ${written} persona(s) generated as Codex agent TOML in ${dest}`);
+}
+
+/**
+ * `~/.codex/prompts/multi-agent.md` gives Codex a real `/multi-agent` slash
+ * command. It is a two-line router into the skill, not a second copy of the
+ * orchestrator - one spec, two entry points.
+ */
+function installPrompt(promptsDir) {
+  ensureRealDir(promptsDir);
+  ensureDir(promptsDir);
+  const body = [
+    "Run the multi-agent development pipeline.",
+    "",
+    "Load the orchestrator spec at `$HOME/.codex/skills/multi-agent/SKILL.md` and follow it",
+    "for the input below. Sub-command specs are at",
+    "`$HOME/.codex/multi-agent-refs/commands/<cmd>/SKILL.md`; phase specs are at",
+    "`$HOME/.codex/multi-agent-refs/phases/`. Read them on demand as the spec directs.",
+    "",
+    "Input: $ARGUMENTS",
+    "",
+  ].join("\n");
+  writeFile(join(promptsDir, "multi-agent.md"), body);
+  console.log(`    -> /multi-agent prompt written to ${promptsDir}`);
+}
+
+/**
+ * Copy `pipeline/scripts` minus the maintainer-only set.
+ *
+ * Same exclusion the Claude Code and Copilot CLI targets apply: smokes, evals
+ * and release tooling are not part of a user install. Without this the Codex
+ * tree carries ~146 extra files nobody runs, and the cross-target parity
+ * assertion in `smoke-install-layout.sh` fails.
+ */
+function installScripts(pipelineSrc, dest, useSymlinks) {
+  const src = join(pipelineSrc, "scripts");
+  if (!existsSync(src)) return;
+  if (!useSymlinks) {
+    ensureRealDir(dest);
+    ensureDir(dest);
+  }
+  wipeDir(dest);
+  copyDir(src, dest, { exclude: DEV_ONLY_SCRIPTS, useSymlinks });
+  const excluded = countDevOnlyFiles(src);
+  console.log(
+    `    -> ${countFiles(src) - excluded} script file(s) copied to ${dest} (${excluded} dev-only excluded)`,
+  );
+}
+
+/**
+ * Copy a pipeline tree verbatim (lib / schemas). These are executed, not read
+ * as prose, and they resolve their own paths at runtime.
+ */
+function installTree(name, pipelineSrc, dest, useSymlinks) {
+  const src = join(pipelineSrc, name);
+  if (!existsSync(src)) return;
+  if (!useSymlinks) {
+    ensureRealDir(dest);
+    ensureDir(dest);
+  }
+  wipeDir(dest);
+  copyDir(src, dest, { useSymlinks });
+  console.log(`    -> ${countFiles(src)} ${name} file(s) copied to ${dest}`);
+}
+
+function writeAgentsMd(path) {
+  const result = mergeManagedBlock({
+    path,
+    body: generateCodexInstructions(),
+    startMarker: AGENTS_MD_START_MARKER,
+    endMarker: AGENTS_MD_END_MARKER,
+  });
+  const verb =
+    result === "created"
+      ? "Created"
+      : result === "appended"
+        ? "Appended pipeline section to"
+        : "Updated pipeline section in";
+  console.log(`    -> ${verb} ${path}`);
+}
+
+/**
+ * Seed `~/.claude/multi-agent-preferences.json` when it is absent.
+ *
+ * Preferences are cross-host state, not a Claude Code artifact: every phase
+ * reads them and the orchestrator is specified to warn and stop when they are
+ * missing. A Codex-only install would otherwise produce a complete tree that
+ * halts on the first run, because only the Claude Code target creates the file.
+ *
+ * Existing files are never overwritten.
+ */
+function ensureSharedPreferences(home, pipelineSrc) {
+  const prefsPath = join(home, ".claude", "multi-agent-preferences.json");
+  if (existsSync(prefsPath)) return;
+  const template = join(pipelineSrc, "preferences-template.json");
+  if (!existsSync(template)) return;
+  ensureDir(join(home, ".claude"));
+  copyFile(template, prefsPath);
+  console.log(`    -> seeded shared preferences at ${prefsPath}`);
+}
+
+/**
+ * Register the dev-toolkit MCP server via the `codex` CLI.
+ *
+ * Deliberately NOT a hand-written `[mcp_servers.*]` block in `config.toml`:
+ * Codex owns that file (it writes `[marketplaces.*]` and `[plugins."x@y"]`
+ * itself), `codex mcp add` is idempotent, and Codex's own plugin-creator
+ * reference says to manipulate config through commands rather than by editing
+ * it. Hand-merging TOML here would be the riskiest write in this installer for
+ * no benefit.
+ */
+function registerMcpServer() {
+  if (isDryRun()) {
+    console.log(
+      `    [dry-run] would run: codex mcp add ${MCP_SERVER_NAME} -- npx -y ${MCP_SERVER_PACKAGE}`,
+    );
+    return;
+  }
+  // Opt-out for hermetic installs. Registration shells out to `codex`, so its
+  // result depends on whether the binary is present - which makes the install
+  // layout non-deterministic across machines and CI. The layout smoke sets this
+  // so its fingerprint stays stable.
+  if (process.env.MULTI_AGENT_SKIP_MCP_REGISTER === "1") {
+    console.log("    -> skipped MCP registration (MULTI_AGENT_SKIP_MCP_REGISTER=1)");
+    return;
+  }
+  try {
+    // Bounded: an installer must never hang on a child process. `codex mcp add`
+    // is a local config write and returns in milliseconds.
+    execFileSync("codex", ["mcp", "add", MCP_SERVER_NAME, "--", "npx", "-y", MCP_SERVER_PACKAGE], {
+      stdio: "pipe",
+      timeout: 20_000,
+    });
+    console.log(`    -> registered the ${MCP_SERVER_NAME} MCP server`);
+  } catch (e) {
+    const why =
+      e?.code === "ENOENT" ? "codex not on PATH" : (e?.message || "unknown error").split("\n")[0];
+    console.log(`    -> skipped MCP registration (${why})`);
+    console.log(
+      `       run manually: codex mcp add ${MCP_SERVER_NAME} -- npx -y ${MCP_SERVER_PACKAGE}`,
+    );
+  }
+}
+
+export { generateCodexInstructions };

package/install/copilot.mjs

@@ -8,7 +8,7 @@
  * @module install/copilot
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "fs";
+import { existsSync, mkdirSync, readdirSync, rmSync } from "fs";
 import { join } from "path";
 
 import {
@@ -20,11 +20,11 @@ import {
   isDryRun,
   removePipelineAgentFiles,
   wipeDir,
-  writeFile,
 } from "./_common.mjs";
 import { copyExternalSkillsFiltered } from "./_platform-filter.mjs";
 import { DEV_ONLY_SCRIPTS, countDevOnlyFiles } from "./_dev-only-files.mjs";
 import { generateCopilotInstructions } from "./_copilot-instructions.mjs";
+import { legacyTrailingContent, mergeManagedBlock } from "./_managed-block.mjs";
 
 /**
  * @param {{
@@ -69,91 +69,41 @@ export const INSTRUCTIONS_START_MARKER = "# Multi-Agent Development Pipeline";
 export const INSTRUCTIONS_END_MARKER = "<!-- multi-agent-pipeline:copilot-instructions:end -->";
 
 /**
- * Legacy files (written before the end marker existed) have no explicit
- * terminator. Bound the pipeline span at the next top-level "# " heading
- * after the start marker when one exists OUTSIDE fenced code blocks (the
- * pipeline body carries bash comments like "# Bootstrap once ..." inside
- * fences that must not be mistaken for headings); otherwise the span runs
- * to EOF, which matches the pre-marker behavior.
+ * Pre-v5.0 pipeline sections that predate the stable marker. These blocks
+ * ("## Multi-Agent Task Orchestrator", "## Instruction Sync") were written by
+ * older install scripts and now contradict the current generator output.
  *
- * @param {string} section - file content from the start marker onward
- * @returns {string} user content trailing the pipeline span ("" if none)
+ * Match strategy: end at EXPLICIT next-section markers - either the pipeline
+ * marker itself, or a known user-preserved heading. A generic `\n## ` sentinel
+ * is unsafe because bash code fences inside the body contain lines like
+ * `# Personal repos` which would be mistaken for markdown headings and
+ * truncate the match early.
  */
-export function legacyTrailingContent(section) {
-  const lines = section.split("\n");
-  let inFence = false;
-  for (let i = 1; i < lines.length; i++) {
-    if (/^\s*(```|~~~)/.test(lines[i])) {
-      inFence = !inFence;
-      continue;
-    }
-    if (!inFence && /^# /.test(lines[i])) return lines.slice(i).join("\n");
-  }
-  return "";
-}
-
-function writeInstructionsFile(path) {
-  const pipelineSection = generateCopilotInstructions();
-  const managedBlock = pipelineSection.trimEnd() + "\n\n" + INSTRUCTIONS_END_MARKER + "\n";
-
-  if (!existsSync(path)) {
-    writeFile(path, managedBlock);
-    console.log("    -> Created copilot-instructions.md with pipeline");
-    return;
-  }
-
-  let existing = readFileSync(path, "utf-8");
-  const marker = INSTRUCTIONS_START_MARKER;
-
-  // Drift cleanup (v5.6.2): detect pre-v5.0 pipeline sections that predate
-  // the stable marker and strip them. These blocks ("## Multi-Agent Task
-  // Orchestrator", "## Instruction Sync") were written by older install
-  // scripts and now contradict the current generator output.
-  //
-  // Match strategy: end at EXPLICIT next-section markers - either the
-  // pipeline marker itself, or a known user-preserved heading. Using a
-  // generic `\n## ` sentinel is unsafe because bash code fences inside the
-  // body contain lines like `# Personal repos` which would be mistaken for
-  // markdown headings and truncate the match early.
+const COPILOT_DRIFT_PATTERNS = (() => {
   const nextSectionEnd =
     "(?=\\n## Git Identity Routing|\\n## GitHub Account Routing|\\n## Hooks & Context Management|\\n# Multi-Agent Development Pipeline|$)";
-  const orchestratorRe = new RegExp(
-    "\\n---\\n+## Multi-Agent Task Orchestrator[\\s\\S]*?" + nextSectionEnd,
-  );
-  const instructionSyncRe = new RegExp("\\n---\\n+## Instruction Sync[\\s\\S]*?" + nextSectionEnd);
+  return [
+    new RegExp("\\n---\\n+## Multi-Agent Task Orchestrator[\\s\\S]*?" + nextSectionEnd),
+    new RegExp("\\n---\\n+## Instruction Sync[\\s\\S]*?" + nextSectionEnd),
+  ];
+})();
 
-  let cleaned = false;
-  if (orchestratorRe.test(existing)) {
-    existing = existing.replace(orchestratorRe, "");
-    cleaned = true;
-  }
-  if (instructionSyncRe.test(existing)) {
-    existing = existing.replace(instructionSyncRe, "");
-    cleaned = true;
-  }
+function writeInstructionsFile(path) {
+  const result = mergeManagedBlock({
+    path,
+    body: generateCopilotInstructions(),
+    startMarker: INSTRUCTIONS_START_MARKER,
+    endMarker: INSTRUCTIONS_END_MARKER,
+    driftPatterns: COPILOT_DRIFT_PATTERNS,
+  });
 
-  if (existing.includes(marker)) {
-    const startIdx = existing.indexOf(marker);
-    const before = existing.slice(0, startIdx).trimEnd();
-    const fromStart = existing.slice(startIdx);
-    // Replace only the start..end span. User content appended AFTER the
-    // pipeline section (below the end marker, or below the next top-level
-    // heading in legacy files) is preserved.
-    const endIdx = fromStart.indexOf(INSTRUCTIONS_END_MARKER);
-    const trailing =
-      endIdx >= 0
-        ? fromStart.slice(endIdx + INSTRUCTIONS_END_MARKER.length)
-        : legacyTrailingContent(fromStart);
-    let out = before.length > 0 ? before + "\n\n" : "";
-    out += managedBlock;
-    const trailingClean = trailing.replace(/^[\r\n]+/, "").trimEnd();
-    if (trailingClean.length > 0) out += "\n" + trailingClean + "\n";
-    writeFile(path, out);
-    const suffix = cleaned ? " (also scrubbed pre-v5.0 drift section)" : "";
-    console.log(`    -> Updated existing pipeline section in copilot-instructions.md${suffix}`);
-  } else {
-    writeFile(path, existing.trimEnd() + "\n\n" + managedBlock);
+  if (result === "created") {
+    console.log("    -> Created copilot-instructions.md with pipeline");
+  } else if (result === "appended") {
     console.log("    -> Appended pipeline section to copilot-instructions.md");
+  } else {
+    const suffix = result === "updated+scrubbed" ? " (also scrubbed pre-v5.0 drift section)" : "";
+    console.log(`    -> Updated existing pipeline section in copilot-instructions.md${suffix}`);
   }
 }
 
@@ -321,3 +271,7 @@ function installSkills(opts) {
 }
 
 export { generateCopilotInstructions };
+// Re-exported for the install tests, which assert the legacy bounding rule
+// through this module. The implementation moved to _managed-block.mjs in
+// v13.0.0 so Codex CLI could reuse it.
+export { legacyTrailingContent };