agentic-team 0.0.0-stage → 6.2.0

package/bin/index.js

@@ -0,0 +1,1334 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const platformsLib = require("./platforms");
+
+const targetDir = process.cwd();
+const templateDir = path.join(__dirname, "..", "template");
+const pkgVersion = require("../package.json").version;
+
+// Plugin-to-standalone mapping: plugin root dirs → .claude/ subdirs
+const PLUGIN_TO_CLAUDE = {
+  agents: ".claude/agents",
+  commands: ".claude/commands/orchestra",
+  rules: ".claude/rules",
+  skills: ".claude/skills",
+  hooks: ".claude/hooks",
+};
+
+const ORCHESTRA_SECTION_START = "<!-- orchestra -->";
+const ORCHESTRA_SECTION_END = "<!-- /orchestra -->";
+
+// User directories to preserve during upgrade
+// roles is here because /orchestra:create-role writes custom roles into it.
+// Without it, upgrading deletes every role the user created.
+const ORCHESTRA_USER_DIRS = ["milestones", "blueprints", "roles"];
+const CLAUDE_USER_DIRS = ["skills", "rules"];
+
+// An upgrade is destructive in the middle: .orchestra/ is removed and rebuilt
+// before the user's data goes back. Everything saved for that window lives in
+// one directory carrying a marker, and the marker is removed only once the
+// restore has actually finished. A run that finds a marked backup did not
+// write it — so it refuses rather than clearing the only copy of somebody's
+// milestones.
+const BACKUP_DIR_PREFIX = ".orchestra-backup-run-";
+const BACKUP_MARKER = "IN_PROGRESS";
+
+// The pre-4.2 scheme used one directory per backed-up folder and deleted them
+// at the start of the next run. A leftover therefore means the previous run
+// died mid-way, and it is evidence, not litter.
+const LEGACY_BACKUPS = [
+  ...["milestones", "blueprints", "roles"].map((d) => `.orchestra-backup-${d}`),
+  ...["skills", "rules"].map((d) => `.claude-backup-${d}`),
+  ".orchestra-backup-config.yml",
+];
+
+// Keys this project used to have and no longer reads. The merge preserves an
+// unknown key on purpose — it is config somebody wrote — but a preserved key
+// that nothing reads looks live and is not, so the upgrade names it instead of
+// keeping it silently.
+const RETIRED_CONFIG_KEYS = [
+  ["delivery.mode", "removed in 6.0.0 — --auto decides who merges; every task gets a PR"],
+  [
+    "pipeline.models",
+    "removed in 7.0.0 — one model (pipeline.model); a phase carries effort instead",
+  ],
+  ["pipeline.default_complexity", "removed in 7.0.0 — pipeline.default_effort"],
+];
+
+const ALLOW_PERMISSIONS = [
+  "Bash(*)",
+  "Read(*)",
+  "Write(*)",
+  "Edit(*)",
+  "Glob(*)",
+  "Grep(*)",
+  "Agent(*)",
+  "WebFetch(*)",
+  "WebSearch(*)",
+];
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const platforms = platformsLib.takePlatformsArg(args);
+  const flags = { skipPermissions: false, help: false, platforms: platforms?.list ?? null };
+
+  for (const [i, arg] of args.entries()) {
+    if (platforms?.used.has(i)) continue;
+    switch (arg) {
+      case "--dangerously-skip-permissions":
+        flags.skipPermissions = true;
+        break;
+      case "--help":
+      case "-h":
+        flags.help = true;
+        break;
+      default:
+        // Ignore files passed by lint-staged or other tools
+        break;
+    }
+  }
+
+  return flags;
+}
+
+function showHelp() {
+  console.log("");
+  console.log("  Usage: npx agentic-team [command] [options]");
+  console.log("");
+  console.log("  Commands:");
+  console.log("    (none)          Install or upgrade Orchestra in the current directory");
+  console.log("    new <name>      Create a GitHub repository, clone it, and install into it");
+  console.log("");
+  console.log("  Options:");
+  console.log("    --public                         new: create a public repository");
+  console.log(
+    "    --platforms <list>               web,expo,ios,android,backend — install only these",
+  );
+  console.log("                                     (default: project.platforms, else detected)");
+  console.log("    --dangerously-skip-permissions   Auto-allow all tool permissions");
+  console.log("    --help, -h                       Show this help");
+  console.log("");
+  console.log("  Examples:");
+  console.log("    npx agentic-team");
+  console.log("    npx agentic-team --platforms ios,backend");
+  console.log("    npx agentic-team new daily-intake");
+  console.log("");
+}
+
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else if (entry.isSymbolicLink()) {
+      // Dereference rather than recreate: a relative link that resolved in
+      // the package will not resolve in the user's tree.
+      try {
+        fs.unlinkSync(destPath);
+      } catch {
+        // Optional: on a fresh install there is nothing to remove. The unlink
+        // is only here to clear a stale link left by a previous version.
+      }
+      fs.copyFileSync(fs.realpathSync(srcPath), destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// A user's own entry, copied as it is. Unlike copyDirRecursive, a symlink
+// stays a link with its target text unchanged: fs.cpSync rewrites a relative
+// link to an absolute path on this machine, and throws on a dangling one.
+function copyAsIs(src, dest) {
+  const st = fs.lstatSync(src);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (st.isSymbolicLink()) {
+    fs.symlinkSync(fs.readlinkSync(src), dest);
+  } else if (st.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const name of fs.readdirSync(src)) copyAsIs(path.join(src, name), path.join(dest, name));
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function rmDirRecursive(dir) {
+  if (!fs.existsSync(dir)) return;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      rmDirRecursive(fullPath);
+    } else {
+      fs.unlinkSync(fullPath);
+    }
+  }
+  fs.rmdirSync(dir);
+}
+
+/** Backups from a run that never finished restoring. Never delete these. */
+function findUnfinishedBackups() {
+  const found = [];
+  for (const entry of fs.readdirSync(targetDir)) {
+    if (entry.startsWith(BACKUP_DIR_PREFIX)) {
+      if (fs.existsSync(path.join(targetDir, entry, BACKUP_MARKER))) found.push(entry);
+      continue;
+    }
+    if (LEGACY_BACKUPS.includes(entry)) found.push(entry);
+  }
+  return found;
+}
+
+/**
+ * Merge the user's config.yml onto the template's.
+ *
+ * The template supplies the structure and every comment; the user's file
+ * supplies the values. A key the template does not know about is carried over
+ * rather than dropped — it is config somebody wrote on purpose.
+ *
+ * Indentation decides nesting, so this does not care how deep the file goes.
+ * A block sequence is merged as a unit: a list the user edited replaces the
+ * template's list entirely. Merging the *members* would be worse than either
+ * choice, because it would resurrect entries the user deliberately removed.
+ *
+ * Every helper lives inside this function on purpose: test/merge-config.test.js
+ * extracts it by regex and evaluates it alone.
+ */
+function mergeConfigYaml(userContent, templateContent) {
+  const KEY = /^([A-Za-z_][\w_-]*):\s*(.*)$/;
+  const ITEM = /^-\s*(.*)$/;
+
+  // A scalar leaf parses to a string, a block sequence to an array, anything
+  // else to a map.
+  function parseYaml(lines) {
+    const root = {};
+    const stack = [{ indent: -2, node: root, parent: null, key: null }];
+
+    for (const raw of lines) {
+      const text = raw.trim();
+      if (text === "" || text.startsWith("#")) continue;
+      const indent = raw.search(/\S/);
+
+      const item = ITEM.exec(text);
+      if (item) {
+        while (stack.length > 1 && stack[stack.length - 1].indent >= indent) stack.pop();
+        const top = stack[stack.length - 1];
+        if (!top.parent) continue;
+        if (!Array.isArray(top.parent[top.key])) top.parent[top.key] = [];
+        top.parent[top.key].push(item[1]);
+        continue;
+      }
+
+      const kv = KEY.exec(text);
+      if (!kv) continue;
+
+      while (stack.length > 1 && stack[stack.length - 1].indent >= indent) stack.pop();
+      const parent = stack[stack.length - 1].node;
+      const key = kv[1];
+      const value = kv[2].trim();
+
+      if (value === "") {
+        // A map or a list — whichever the lines below turn out to be.
+        const node = {};
+        parent[key] = node;
+        stack.push({ indent, node, parent, key });
+      } else {
+        parent[key] = value;
+      }
+    }
+    return root;
+  }
+
+  function lookup(node, keyPath) {
+    let cur = node;
+    for (const k of keyPath) {
+      if (!cur || typeof cur !== "object" || Array.isArray(cur)) return undefined;
+      cur = cur[k];
+    }
+    return cur;
+  }
+
+  function serialize(node, indent) {
+    const out = [];
+    const pad = " ".repeat(indent);
+    for (const [k, v] of Object.entries(node)) {
+      if (Array.isArray(v)) {
+        out.push(`${pad}${k}:`);
+        for (const it of v) out.push(`${pad}  - ${it}`);
+      } else if (v && typeof v === "object") {
+        out.push(`${pad}${k}:`);
+        out.push(...serialize(v, indent + 2));
+      } else {
+        out.push(`${pad}${k}: ${v}`);
+      }
+    }
+    return out;
+  }
+
+  // What the user has and the template has never heard of, at any depth.
+  function extras(userNode, tmplNode) {
+    const out = {};
+    for (const [k, v] of Object.entries(userNode)) {
+      const t = tmplNode ? tmplNode[k] : undefined;
+      if (t === undefined) {
+        out[k] = v;
+        continue;
+      }
+      const bothMaps =
+        v &&
+        typeof v === "object" &&
+        !Array.isArray(v) &&
+        t &&
+        typeof t === "object" &&
+        !Array.isArray(t);
+      if (!bothMaps) continue;
+      const sub = extras(v, t);
+      if (Object.keys(sub).length) out[k] = sub;
+    }
+    return out;
+  }
+
+  const userParsed = parseYaml(userContent.split("\n"));
+  const templateParsed = parseYaml(templateContent.split("\n"));
+
+  const merged = [];
+  const keyPath = [];
+  const indents = [];
+  let replacedList = false;
+
+  for (const raw of templateContent.split("\n")) {
+    const text = raw.trim();
+
+    // The user's list has already been written in place of this one.
+    if (replacedList) {
+      if (ITEM.test(text)) continue;
+      replacedList = false;
+    }
+
+    if (text === "" || text.startsWith("#") || ITEM.test(text)) {
+      merged.push(raw);
+      continue;
+    }
+
+    const kv = KEY.exec(text);
+    if (!kv) {
+      merged.push(raw);
+      continue;
+    }
+
+    const indent = raw.search(/\S/);
+    while (indents.length && indents[indents.length - 1] >= indent) {
+      indents.pop();
+      keyPath.pop();
+    }
+    keyPath.push(kv[1]);
+    indents.push(indent);
+
+    const userValue = lookup(userParsed, keyPath);
+
+    if (kv[2].trim() === "") {
+      merged.push(raw);
+      if (Array.isArray(userValue) && Array.isArray(lookup(templateParsed, keyPath))) {
+        const pad = " ".repeat(indent + 2);
+        for (const it of userValue) merged.push(`${pad}- ${it}`);
+        replacedList = true;
+      }
+      continue;
+    }
+
+    if (typeof userValue === "string") {
+      merged.push(`${" ".repeat(indent)}${kv[1]}: ${userValue}`);
+      continue;
+    }
+    merged.push(raw);
+  }
+
+  // Carried-over keys, split by depth.
+  //
+  // A nested one has to go *inside* the block it belongs to. Emitting it at
+  // the end produced a second `delivery:` at top level, and YAML rejects a
+  // duplicate map key outright — so an upgrade of any config with a custom
+  // key under a known section wrote a file that no longer parsed. The key was
+  // preserved, technically, in a file nothing could read.
+  const carriedAll = extras(userParsed, templateParsed);
+  const nested = {};
+  const topLevel = {};
+  for (const [k, v] of Object.entries(carriedAll)) {
+    const inTemplate = templateParsed[k] !== undefined;
+    if (inTemplate && v && typeof v === "object" && !Array.isArray(v)) nested[k] = v;
+    else topLevel[k] = v;
+  }
+
+  // Insert each nested group at the end of its section — the line before the
+  // next top-level key, so it lands under the right parent.
+  for (const [section, body] of Object.entries(nested)) {
+    const start = merged.findIndex((l) => l.startsWith(`${section}:`));
+    if (start === -1) {
+      topLevel[section] = body;
+      continue;
+    }
+    let end = start + 1;
+    while (end < merged.length && !/^[A-Za-z_]/.test(merged[end])) end++;
+    while (end > start + 1 && merged[end - 1].trim() === "") end--;
+    merged.splice(
+      end,
+      0,
+      "",
+      "  # ── Preserved from your previous config ──",
+      ...serialize(body, 2),
+    );
+  }
+
+  const carried = serialize(topLevel, 0);
+  if (carried.length) {
+    merged.push("", "# ── Preserved from your previous config ──", ...carried);
+  }
+
+  return merged.join("\n");
+}
+
+function extractOrchestraSection(content) {
+  const startIdx = content.indexOf(ORCHESTRA_SECTION_START);
+  if (startIdx === -1) return null;
+  const endIdx = content.indexOf(ORCHESTRA_SECTION_END, startIdx);
+  if (endIdx === -1) return content.slice(startIdx);
+  return content.slice(startIdx, endIdx + ORCHESTRA_SECTION_END.length);
+}
+
+/**
+ * Smart merge for user directories (skills, rules, blueprints):
+ * - entries present in template = system files → always updated from template
+ * - .orchestra.md files = legacy system files → skip (backward compat)
+ * - remaining entries = user files → preserved
+ */
+function smartMergeDir(backupPath, restorePath, templateDirPath) {
+  const templateFiles = fs.existsSync(templateDirPath) ? fs.readdirSync(templateDirPath) : [];
+  const backupFiles = fs.readdirSync(backupPath).filter((f) => f !== ".gitkeep");
+  let restored = 0;
+
+  for (const file of backupFiles) {
+    // Skip system entries: in template OR legacy .orchestra.md files
+    if (templateFiles.includes(file) || file.endsWith(".orchestra.md")) continue;
+
+    const srcFile = path.join(backupPath, file);
+    try {
+      const stat = fs.lstatSync(srcFile);
+      const destFile = path.join(restorePath, file);
+      if (stat.isDirectory()) {
+        copyDirRecursive(srcFile, destFile);
+      } else if (stat.isFile()) {
+        fs.copyFileSync(srcFile, destFile);
+      }
+      // Skip broken symlinks and other non-regular entries
+      restored++;
+    } catch {
+      // Entry inaccessible — skip silently
+    }
+  }
+
+  return restored;
+}
+
+// Which files Orchestra put down, recorded at install time.
+//
+// Rules carry a `.orchestra.md` suffix, so both the upgrade and the hook can
+// tell a system rule from one the user wrote. Skills lost that marker when
+// they became directories, and nothing replaced it: the hook now blocks every
+// skill including the user's own — the extension point docs/skills.md tells
+// them to use — and the upgrade restores a retired system skill forever,
+// because it cannot tell it from a skill somebody wrote.
+//
+// The manifest is that marker, for everything, in one place both sides read.
+const MANIFEST_PATH = ".orchestra/.installed.json";
+
+/**
+ * Every file the template installs for these platforms: its repo-relative
+ * POSIX destination and its source in the package. An empty platform list is
+ * everything.
+ */
+function templateEntries(platforms, keepSkills) {
+  const out = [];
+  const walk = (dir, prefix) => {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const rel = `${prefix}/${entry.name}`;
+      const src = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(src, rel);
+      else if (platformsLib.selected(rel, platforms, keepSkills)) out.push({ rel, src });
+    }
+  };
+  walk(path.join(templateDir, ".orchestra"), ".orchestra");
+  for (const [pluginDir, claudeSubdir] of Object.entries(PLUGIN_TO_CLAUDE)) {
+    walk(path.join(templateDir, pluginDir), claudeSubdir);
+  }
+  return out.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+}
+
+/**
+ * Copy the template's files for these platforms into the project. A rule
+ * loses the sections marked for other platforms; every file keeps its name,
+ * so the manifest and the system-file hook see the same paths either way.
+ */
+function installTemplate(entries, platforms) {
+  for (const { rel, src } of entries) {
+    const dest = path.join(targetDir, ...rel.split("/"));
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    // Dereference rather than recreate: a relative link that resolved in the
+    // package will not resolve in the user's tree.
+    const real = fs.realpathSync(src);
+    try {
+      if (fs.lstatSync(dest).isSymbolicLink()) fs.unlinkSync(dest);
+    } catch {
+      // Optional: on a fresh install there is nothing at dest yet.
+    }
+    if (rel.startsWith(".claude/rules/") && rel.endsWith(".md")) {
+      const text = fs.readFileSync(real, "utf-8");
+      fs.writeFileSync(dest, platformsLib.filterSections(text, platforms));
+    } else {
+      fs.copyFileSync(real, dest);
+    }
+  }
+}
+
+/** Names in a platform list that are not platforms. */
+const unknownPlatforms = (list) => list.filter((p) => !platformsLib.PLATFORMS.includes(p));
+
+/**
+ * Which platforms this run installs for, and where that answer came from:
+ * the flag (already validated), then the config, then detection. A config
+ * naming something that is not a platform is refused, not narrowed around —
+ * dropping the name once retired a platform's files and rewrote the user's
+ * list without it.
+ */
+function resolvePlatforms(flagValue, configText, detect) {
+  if (flagValue) return { list: flagValue, source: "--platforms" };
+  const configured = platformsLib.readConfigPlatforms(configText || "");
+  const bad = unknownPlatforms(configured);
+  if (bad.length) return { error: `project.platforms in config.yml names ${bad.join(", ")}` };
+  if (configured.length) return { list: configured, source: "config.yml" };
+  return { list: detect(), source: "detected" };
+}
+
+function readManifest() {
+  const p = path.join(targetDir, MANIFEST_PATH);
+  if (!fs.existsSync(p)) return null;
+  try {
+    const m = JSON.parse(fs.readFileSync(p, "utf-8"));
+    if (Array.isArray(m?.files)) return m;
+    console.log("  [!] .orchestra/.installed.json has no files list — nothing retired this run");
+    return null;
+  } catch {
+    // A corrupt manifest means retirement cannot run this time. Reported, and
+    // not fatal: the install itself is still correct without it.
+    console.log("  [!] .orchestra/.installed.json is not valid JSON — nothing retired this run");
+    return null;
+  }
+}
+
+function writeManifest(files) {
+  fs.writeFileSync(
+    path.join(targetDir, MANIFEST_PATH),
+    `${JSON.stringify({ version: pkgVersion, files }, null, 2)}\n`,
+  );
+}
+
+/**
+ * Delete what a previous install put down and this one does not: a file this
+ * version no longer ships, or one for a platform the project no longer lists.
+ * `alsoRetire` adds paths no manifest records, for an install older than it.
+ *
+ * Without it a retired skill is indistinguishable from one the user wrote, so
+ * it survives every future upgrade and keeps teaching whatever it taught.
+ */
+function retireRemoved(previous, current, alsoRetire = []) {
+  const keep = new Set(current);
+  let removed = 0;
+  for (const rel of new Set([...(previous?.files || []), ...alsoRetire])) {
+    if (keep.has(rel)) continue;
+    const full = path.join(targetDir, rel);
+    // The manifest is a committed file anyone can edit. An entry that leaves
+    // the project is never deleted.
+    if (!full.startsWith(targetDir + path.sep)) continue;
+    if (!fs.existsSync(full)) continue;
+    fs.unlinkSync(full);
+    // The directory it lived in is ours too when nothing is left in it.
+    let dir = path.dirname(full);
+    while (dir.startsWith(targetDir + path.sep) && fs.readdirSync(dir).length === 0) {
+      fs.rmdirSync(dir);
+      dir = path.dirname(dir);
+    }
+    removed++;
+  }
+  return removed;
+}
+
+// Shared by every registerXHook below: is this hook's own script already one
+// of the commands under this settings.hooks[event] array? Three call sites
+// asked the identical question before this was pulled out.
+function hookAlreadyRegistered(entries, marker) {
+  return (entries || []).some((entry) =>
+    (entry.hooks || []).some((h) => typeof h.command === "string" && h.command.includes(marker)),
+  );
+}
+
+// A hook is only enforcement once it is registered. Shipping the script
+// without this leaves an executable nobody runs — the exact failure the rules
+// exist to prevent.
+//
+// settings.json rather than settings.local.json: this encodes a team rule,
+// not a personal preference, and it is meant to be committed.
+function registerHooks() {
+  const claudeDir = path.join(targetDir, ".claude");
+  const settingsPath = path.join(claudeDir, "settings.json");
+  // biome-ignore lint/suspicious/noTemplateCurlyInString: a shell parameter expansion, resolved by bash at hook time — not a JS template.
+  const command = 'bash "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/protect-system-files.sh"';
+
+  if (!fs.existsSync(claudeDir)) fs.mkdirSync(claudeDir, { recursive: true });
+
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    } catch {
+      // A malformed settings.json disables every setting in it. Refuse to
+      // overwrite someone's file on the strength of a parse error.
+      console.log("  [!] .claude/settings.json is not valid JSON — hook not registered");
+      return;
+    }
+  }
+
+  settings.hooks = settings.hooks || {};
+  const pre = settings.hooks.PreToolUse || [];
+
+  // Merge, never replace: another hook on the same matcher belongs to
+  // somebody else.
+  const already = hookAlreadyRegistered(pre, "protect-system-files");
+  if (already) {
+    console.log("  [~] Role-boundary hook already registered");
+    return;
+  }
+
+  pre.push({ matcher: "Write|Edit", hooks: [{ type: "command", command }] });
+  settings.hooks.PreToolUse = pre;
+  fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  console.log("  [+] Role-boundary hook registered (blocks edits to installed system files)");
+}
+
+// The second guard: a session that declared a role stays inside it. Bash as
+// well as Write|Edit, because what the PM did outside its scope was open a
+// pull request, and that is a shell command, not a file write.
+function registerRoleHook() {
+  const settingsPath = path.join(targetDir, ".claude", "settings.json");
+  // biome-ignore lint/suspicious/noTemplateCurlyInString: a shell parameter expansion, resolved by bash at hook time — not a JS template.
+  const command = 'bash "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/enforce-role.sh"';
+  let settings = {};
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  } catch {
+    // registerHooks() ran first and already said the file is unreadable or
+    // not JSON; a second message for the same file would be noise.
+    return;
+  }
+  settings.hooks = settings.hooks || {};
+  const pre = settings.hooks.PreToolUse || [];
+  if (hookAlreadyRegistered(pre, "enforce-role")) return;
+  // Agent and Workflow as well: a PM launched a multi-agent code review
+  // because the word "ultracode" in the user's message told the platform to
+  // use the Workflow tool, and prose saying "cannot review code" lost. And
+  // the ClickUp connector, so a status written by the PM can be refused.
+  pre.push({
+    matcher: "Bash|Write|Edit|Agent|Workflow|mcp__.*clickup_(create|update)_task",
+    hooks: [{ type: "command", command }],
+  });
+  settings.hooks.PreToolUse = pre;
+
+  // No role runs a workflow — lead fans out with the Agent tool, the PM
+  // launches two named agents, and nothing else orchestrates. Denied at the
+  // permission layer so the tool is not there to be talked into.
+  settings.permissions = settings.permissions || {};
+  const deny = new Set(settings.permissions.deny || []);
+  deny.add("Workflow");
+  settings.permissions.deny = [...deny];
+
+  fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  console.log("  [+] Role-scope hook registered (a declared role stays inside its ownership)");
+}
+
+// Review rounds are capped per phase. The cap was prose in lead.md, and a run
+// read the user's "loop until clean" as overriding it and went nine rounds on
+// one phase. See .claude/hooks/review-rounds.sh.
+function registerReviewRoundsHook() {
+  const settingsPath = path.join(targetDir, ".claude", "settings.json");
+  // biome-ignore lint/suspicious/noTemplateCurlyInString: a shell parameter expansion, resolved by bash at hook time — not a JS template.
+  const command = 'bash "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/review-rounds.sh"';
+  let settings = {};
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  } catch {
+    // registerHooks() ran first and already said the file is unreadable or
+    // not JSON; a second message for the same file would be noise.
+    return;
+  }
+  settings.hooks = settings.hooks || {};
+  const pre = settings.hooks.PreToolUse || [];
+  if (hookAlreadyRegistered(pre, "review-rounds")) return;
+  pre.push({ matcher: "Agent", hooks: [{ type: "command", command }] });
+  settings.hooks.PreToolUse = pre;
+  fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  console.log(
+    "  [+] Review-round hook registered (a phase gets at most stuck_retry_limit reviews)",
+  );
+}
+
+// The fourth guard, and the only one that never blocks: context.md's own
+// bookkeeping (a phase marked done, an in-progress phase) is otherwise
+// checked only when a human happens to reread it. PreCompact cannot block
+// compaction and its own additionalContext is undocumented, so the audit it
+// runs there only writes findings to disk; SessionStart's documented
+// "compact" matcher is what actually surfaces them, right after compaction
+// lands. See .claude/hooks/audit-context.sh.
+function registerContextAuditHook() {
+  const settingsPath = path.join(targetDir, ".claude", "settings.json");
+  // biome-ignore lint/suspicious/noTemplateCurlyInString: a shell parameter expansion, resolved by bash at hook time — not a JS template.
+  const command = 'bash "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/audit-context.sh"';
+  let settings = {};
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  } catch {
+    // registerHooks() ran first and already said the file is unreadable or
+    // not JSON; a second message for the same file would be noise.
+    return;
+  }
+  settings.hooks = settings.hooks || {};
+
+  const preDone = hookAlreadyRegistered(settings.hooks.PreCompact, "audit-context");
+  const startDone = hookAlreadyRegistered(settings.hooks.SessionStart, "audit-context");
+  if (preDone && startDone) {
+    console.log("  [~] Context-audit hook already registered");
+    return;
+  }
+
+  if (!preDone) {
+    const pre = settings.hooks.PreCompact || [];
+    pre.push({ hooks: [{ type: "command", command }] });
+    settings.hooks.PreCompact = pre;
+  }
+  if (!startDone) {
+    const start = settings.hooks.SessionStart || [];
+    start.push({ matcher: "compact", hooks: [{ type: "command", command }] });
+    settings.hooks.SessionStart = start;
+  }
+
+  fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  console.log("  [+] Context-audit hook registered (flags context.md defects after compaction)");
+}
+
+function setupPermissions() {
+  const claudeDir = path.join(targetDir, ".claude");
+  const settingsPath = path.join(claudeDir, "settings.local.json");
+
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true });
+  }
+
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    } catch {
+      // Falling back to {} would write an empty permissions file over one the
+      // user still has, and they would find out the next time a tool asked.
+      // registerHooks refuses on the same parse error; so does this.
+      console.log(
+        "  [!] .claude/settings.local.json is not valid JSON — permissions not configured",
+      );
+      return;
+    }
+  }
+
+  if (!settings.permissions) settings.permissions = {};
+  const existing = settings.permissions.allow || [];
+  const merged = [...new Set([...existing, ...ALLOW_PERMISSIONS])];
+  settings.permissions.allow = merged;
+
+  fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+
+  const added = merged.length - existing.length;
+  if (added > 0) {
+    console.log(`  [+] Permissions configured (${added} rules added)`);
+  } else {
+    console.log("  [~] Permissions already configured");
+  }
+}
+
+/**
+ * Create a repository and install into it.
+ *
+ * Deliberately stops before `/orchestra:setup`. Setup is a conversation — it
+ * asks what you are building — and that conversation has to happen inside the
+ * new project, where the project's own CLAUDE.md and role boundaries are
+ * loaded. Run from the agentic-team repo instead, an agent would be wearing
+ * the system maintainer's contract at the moment it starts building an app.
+ */
+function newProject(argv) {
+  const platforms = platformsLib.takePlatformsArg(argv);
+  const name = argv.find((a, i) => !a.startsWith("-") && !platforms?.used.has(i));
+  const isPublic = argv.includes("--public");
+
+  if (!name) {
+    console.log("  [x] Usage: npx agentic-team new <name>");
+    process.exitCode = 1;
+    return;
+  }
+  // GitHub's own rule, checked here so the failure names the reason rather
+  // than arriving as an API error four steps later.
+  if (!/^[A-Za-z0-9._-]+$/.test(name) || name === "." || name === "..") {
+    console.log(`  [x] "${name}" is not a usable repository name — letters, digits, . _ - only`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Checked before the repository exists: the installer would refuse a typo
+  // only after GitHub already has an empty repository by that name.
+  if (platforms && (!platforms.list.length || unknownPlatforms(platforms.list).length)) {
+    console.log(`  [x] --platforms takes a comma list of: ${platformsLib.PLATFORMS.join(", ")}`);
+    process.exitCode = 1;
+    return;
+  }
+  const forward = platforms ? ["--platforms", platforms.list.join(",")] : [];
+
+  const dir = path.resolve(targetDir, name);
+  if (fs.existsSync(dir)) {
+    console.log(`  [x] ${name}/ already exists here. Refusing to write into it.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const gh = (args, opts = {}) =>
+    execFileSync("gh", args, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], ...opts });
+
+  try {
+    gh(["auth", "status"]);
+  } catch {
+    // Not something to work around: creating a repository needs the user's
+    // own credentials, and this is the one step they have to do themselves.
+    console.log("  [x] gh is not available or not authenticated.");
+    console.log("      Install it, then run: gh auth login");
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log("");
+  console.log("  Orchestra — new project");
+  console.log("");
+
+  try {
+    gh(["repo", "create", name, isPublic ? "--public" : "--private", "--clone"], {
+      cwd: targetDir,
+      stdio: ["ignore", "pipe", "inherit"],
+    });
+  } catch {
+    console.log(`  [x] Could not create ${name}. It may already exist on GitHub.`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`  [+] repository created and cloned into ${name}/`);
+
+  // The installer runs unchanged, in the new directory. Copying its logic here
+  // would give the manifest, the upgrade path and the hook registration a
+  // second implementation to drift from.
+  execFileSync(process.execPath, [__filename, ...forward], { cwd: dir, stdio: "inherit" });
+}
+
+function run() {
+  const flags = parseArgs();
+  if (flags.help) {
+    showHelp();
+    return;
+  }
+
+  // Refused before anything is touched: a typo in the flag would otherwise
+  // install for the wrong platforms and retire the right ones. An empty list
+  // means "everything", which is never what a flag asking for platforms meant.
+  if (flags.platforms && (!flags.platforms.length || unknownPlatforms(flags.platforms).length)) {
+    console.log("");
+    console.log(
+      `  [x] Unknown platform: ${unknownPlatforms(flags.platforms).join(", ") || "(none given)"}`,
+    );
+    console.log(`      Expected any of: ${platformsLib.PLATFORMS.join(", ")}`);
+    console.log("");
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log("");
+  console.log("  Orchestra — AI Team Orchestration");
+  console.log(`  Installing into: ${targetDir}`);
+  console.log("");
+
+  const orchestraSrc = path.join(templateDir, ".orchestra");
+  const orchestraDest = path.join(targetDir, ".orchestra");
+  const claudeDest = path.join(targetDir, ".claude");
+  const isUpgrade = fs.existsSync(orchestraDest);
+  // Read before anything is copied: after the install the manifest describes
+  // this version, and what a previous one left behind is no longer knowable.
+  const previousManifest = readManifest();
+  // Asked separately: a manifest that exists but does not parse is not an old
+  // install, and treating it as one sweeps user files the manifest would have
+  // told apart. Read now, because the upgrade removes .orchestra/ below.
+  const manifestExisted = fs.existsSync(path.join(targetDir, MANIFEST_PATH));
+
+  // Also before the copy: the upgrade's config merge cannot keep a block-form
+  // list over the template's flow-form `platforms: []`, so the answer is
+  // taken from the user's file as it stands and written back afterwards.
+  const configBefore = path.join(orchestraDest, "config.yml");
+  let detected = null;
+  const detect = () => {
+    detected ??= platformsLib.detectPlatforms(targetDir);
+    return detected;
+  };
+  const profile = resolvePlatforms(
+    flags.platforms,
+    fs.existsSync(configBefore) ? fs.readFileSync(configBefore, "utf-8") : "",
+    detect,
+  );
+  if (profile.error) {
+    console.log(`  [x] ${profile.error}.`);
+    console.log(
+      `      Expected any of: ${platformsLib.PLATFORMS.join(", ")}. Nothing was changed.`,
+    );
+    console.log("");
+    process.exitCode = 1;
+    return;
+  }
+  // Read before the upgrade moves milestones/ aside.
+  const phaseSkills = platformsLib.phaseSkills(targetDir);
+  const entries = templateEntries(profile.list, phaseSkills);
+  const allEntries = templateEntries([]);
+
+  if (isUpgrade) {
+    // A backup nobody finished restoring holds the only copy of the user's
+    // work. Refuse rather than clear it — the old code deleted these at the
+    // top of the next run, which turned an interrupted upgrade into a
+    // permanent loss.
+    const unfinished = findUnfinishedBackups();
+    if (unfinished.length) {
+      console.log("  [x] A previous install did not finish restoring your data.");
+      console.log("");
+      console.log("      It is still here, untouched:");
+      for (const b of unfinished) console.log(`        ${b}`);
+      console.log("");
+      console.log("      Copy what you need back into .orchestra/ (milestones/ first;");
+      console.log("      files you kept at its root are under orchestra-extra/),");
+      console.log("      delete the entry above, then run this again.");
+      console.log("");
+      process.exitCode = 1;
+      return;
+    }
+
+    // One backup directory for the whole run, created only if there is
+    // something to put in it, and marked until the restore has happened.
+    let backupRoot = null;
+    const backups = {};
+    // Nothing is at risk until .orchestra/ is actually removed. A failure
+    // before that point loses nothing, so the backup is litter rather than
+    // evidence and must not block the next run.
+    let destructiveStarted = false;
+    let restored = false;
+
+    try {
+      function ensureBackupRoot() {
+        if (backupRoot) return backupRoot;
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        backupRoot = path.join(targetDir, BACKUP_DIR_PREFIX + stamp);
+        fs.mkdirSync(backupRoot, { recursive: true });
+        fs.writeFileSync(
+          path.join(backupRoot, BACKUP_MARKER),
+          "This upgrade has not finished restoring. Do not delete this directory.\n",
+        );
+        return backupRoot;
+      }
+
+      function backupDir(sourceDir, type, dir) {
+        if (!fs.existsSync(sourceDir)) return;
+        const files = fs.readdirSync(sourceDir).filter((f) => f !== ".gitkeep");
+        if (files.length === 0) return;
+        const backupPath = path.join(ensureBackupRoot(), type, dir);
+        copyDirRecursive(sourceDir, backupPath);
+        backups[`${type}:${dir}`] = { backupPath, type, dir };
+        const label = type === "orchestra" ? ".orchestra/" : ".claude/";
+        console.log(`  [~] Backed up ${label}${dir}/ (${files.length} items)`);
+      }
+
+      // ── Backup user data ──
+      for (const dir of ORCHESTRA_USER_DIRS) {
+        backupDir(path.join(orchestraDest, dir), "orchestra", dir);
+      }
+      // .claude/ user dirs — the user may have added custom skills or rules.
+      for (const dir of CLAUDE_USER_DIRS) {
+        backupDir(path.join(claudeDest, dir), "claude", dir);
+      }
+
+      const configPath = path.join(orchestraDest, "config.yml");
+      let configBackup = null;
+      if (fs.existsSync(configPath)) {
+        configBackup = path.join(ensureBackupRoot(), "config.yml");
+        fs.copyFileSync(configPath, configBackup);
+        console.log("  [~] Backed up config.yml");
+      }
+
+      // Anything else at the root of .orchestra/ is the user's, and the
+      // removal below would take it. Back it up with the rest.
+      const strays = [];
+      if (fs.existsSync(orchestraDest)) {
+        const known = new Set([
+          ...ORCHESTRA_USER_DIRS,
+          "config.yml",
+          ".installed.json",
+          // A file an earlier version installed and this one retires is not
+          // the user's; retireRemoved deletes it after the install.
+          ...(previousManifest?.files || [])
+            .filter((f) => f.startsWith(".orchestra/"))
+            .map((f) => f.split("/")[1]),
+          ...(fs.existsSync(orchestraSrc) ? fs.readdirSync(orchestraSrc) : []),
+        ]);
+        for (const name of fs.readdirSync(orchestraDest)) {
+          // Finder's .DS_Store is nobody's work and not worth a line per upgrade.
+          if (known.has(name) || name === ".gitkeep" || name === ".DS_Store") continue;
+          const backupPath = path.join(ensureBackupRoot(), "orchestra-extra", name);
+          copyAsIs(path.join(orchestraDest, name), backupPath);
+          strays.push({ name, backupPath });
+          // .sessions/ is Orchestra's own runtime state — role markers and
+          // review-round counts — kept so an upgrade does not reset a cap.
+          if (name !== ".sessions") console.log(`  [~] Preserving .orchestra/${name}`);
+        }
+      }
+
+      // ── Clean install ──
+      // From here until the restore completes, the user's data exists only
+      // inside backupRoot.
+      destructiveStarted = true;
+      rmDirRecursive(orchestraDest);
+      console.log("  [~] Removed old .orchestra/");
+
+      // Remove old .claude/ orchestra files (agents, commands) but keep user files
+      const claudeOrchestraDirs = ["agents", "commands"];
+      for (const dir of claudeOrchestraDirs) {
+        const dirPath = path.join(claudeDest, dir);
+        if (fs.existsSync(dirPath)) {
+          const files = fs.readdirSync(dirPath);
+          for (const file of files) {
+            if (
+              file === "conductor.md" ||
+              file === "lead.md" ||
+              file === "reviewer.md" ||
+              file === "orchestra"
+            ) {
+              const fullPath = path.join(dirPath, file);
+              if (fs.statSync(fullPath).isDirectory()) {
+                rmDirRecursive(fullPath);
+              } else {
+                fs.unlinkSync(fullPath);
+              }
+            }
+          }
+        }
+      }
+
+      installTemplate(entries, profile.list);
+      console.log("  [+] .orchestra/ installed");
+      console.log("  [+] .claude/ orchestra files installed");
+
+      // ── Restore user data ──
+      for (const { backupPath, type, dir } of Object.values(backups)) {
+        const baseDest = type === "orchestra" ? orchestraDest : claudeDest;
+        const restorePath = path.join(baseDest, dir);
+        // Plugin structure: claude dirs sit at the template root, orchestra
+        // dirs under .orchestra/.
+        const templateDirPath =
+          type === "orchestra" ? path.join(orchestraSrc, dir) : path.join(templateDir, dir);
+
+        if (dir === "milestones") {
+          if (fs.existsSync(restorePath)) rmDirRecursive(restorePath);
+          copyDirRecursive(backupPath, restorePath);
+          console.log("  [+] Restored milestones/");
+        } else {
+          const count = smartMergeDir(backupPath, restorePath, templateDirPath);
+          if (count > 0) {
+            console.log(`  [+] Restored ${count} user files in ${dir}/`);
+          }
+          console.log(`  [~] Updated system files in ${dir}/`);
+        }
+      }
+
+      for (const { name, backupPath } of strays) {
+        const dest = path.join(orchestraDest, name);
+        fs.rmSync(dest, { recursive: true, force: true });
+        copyAsIs(backupPath, dest);
+      }
+
+      // Merge config.yml: new template keys added, user values preserved
+      if (configBackup && fs.existsSync(configBackup)) {
+        const userConfig = fs.readFileSync(configBackup, "utf-8");
+        const templateConfig = fs.readFileSync(path.join(orchestraDest, "config.yml"), "utf-8");
+        const mergedConfig = mergeConfigYaml(userConfig, templateConfig);
+        fs.writeFileSync(path.join(orchestraDest, "config.yml"), mergedConfig);
+        console.log("  [+] Merged config.yml (user values preserved, new keys added)");
+      }
+
+      restored = true;
+    } finally {
+      if (backupRoot && (restored || !destructiveStarted)) {
+        // The marker goes first: if removing the directory then fails, what
+        // is left is an unmarked leftover rather than a blocked next run.
+        fs.unlinkSync(path.join(backupRoot, BACKUP_MARKER));
+        rmDirRecursive(backupRoot);
+      } else if (backupRoot) {
+        console.log("");
+        console.log("  [x] Install failed part-way. Your data is preserved in:");
+        console.log(`        ${path.basename(backupRoot)}`);
+        console.log("      No later run will delete it.");
+        console.log("");
+      }
+    }
+
+    // A milestone written before the split keeps decisions and the journal
+    // inside context.md. The script moves them out losslessly, new files
+    // first, so a failure here leaves context.md whole.
+    const contextScript = path.join(orchestraDest, "scripts", "context.mjs");
+    if (fs.existsSync(contextScript)) {
+      try {
+        const out = execFileSync(process.execPath, [contextScript, "migrate"], {
+          cwd: targetDir,
+          encoding: "utf8",
+        });
+        for (const line of out.split("\n").filter(Boolean)) console.log(`  [~] ${line}`);
+      } catch (e) {
+        // Not fatal: the install itself is complete and context.md is whole,
+        // because the split writes the new files before it touches it. What
+        // is left is one command, and the message names it.
+        console.log(`  [!] context.md not split (${e.message.split("\n")[0]}); run it again with`);
+        console.log("      node .orchestra/scripts/context.mjs migrate");
+      }
+    }
+  } else {
+    // ── Fresh install ──
+    installTemplate(entries, profile.list);
+    console.log("  [+] .orchestra/ installed");
+    console.log("  [+] .claude/ installed");
+  }
+
+  // ── Record what was installed ──
+  const installed = entries.map((e) => e.rel);
+  // The manifest retires what this project no longer lists. An install from
+  // before the manifest has none, so its files for other platforms would look
+  // like the user's own; only then is every such template path retired. With
+  // a manifest, a path it does not list is the user's — somebody who writes
+  // their own skill under a name a dropped platform freed keeps it.
+  const unselected =
+    isUpgrade && !manifestExisted
+      ? allEntries.map((e) => e.rel).filter((rel) => !installed.includes(rel))
+      : [];
+  const retired = retireRemoved(previousManifest, installed, unselected);
+  if (retired > 0) {
+    console.log(`  [~] Removed ${retired} system file(s) this install no longer ships`);
+  }
+  writeManifest(installed);
+
+  // ── Record the platforms ──
+  const cfgPath = path.join(orchestraDest, "config.yml");
+  if (fs.existsSync(cfgPath)) {
+    const text = fs.readFileSync(cfgPath, "utf-8");
+    const next = platformsLib.writeConfigPlatforms(text, profile.list);
+    if (next === null) {
+      console.log("  [!] project: in config.yml is an inline map — platforms not written back.");
+      console.log("      Write it as a block, with platforms: [ios] indented under project:");
+    } else {
+      fs.writeFileSync(cfgPath, next);
+    }
+  }
+  if (profile.list.length) {
+    const skipped = allEntries.length - entries.length;
+    console.log(
+      `  [~] Platforms: ${profile.list.join(", ")} (${profile.source})` +
+        (skipped ? ` — ${skipped} file(s) for other platforms not installed` : ""),
+    );
+    if (profile.source === "detected") {
+      console.log(
+        "      Wrong? Edit project.platforms in .orchestra/config.yml, or pass --platforms.",
+      );
+    } else {
+      // The list is trusted once written, so an app added later is said out
+      // loud on every run rather than silently left out.
+      const unlisted = detect().filter((p) => !profile.list.includes(p));
+      if (unlisted.length) {
+        console.log(
+          `  [!] The repository also looks like ${unlisted.join(", ")}, which project.platforms does not list.`,
+        );
+        console.log("      Add it to project.platforms if this project builds for it.");
+      }
+    }
+  } else {
+    console.log(
+      "  [~] Platforms: none set — everything installed. Set project.platforms or pass --platforms to narrow it.",
+    );
+  }
+
+  // A skill kept only because a phase names it is said, so it is not mistaken
+  // for one the profile chose; a name that exists nowhere is a broken plan.
+  const keptOnlyByPhase = [...phaseSkills].filter(
+    (n) =>
+      platformsLib.SKILLS[n] !== undefined &&
+      !allEntries.some(
+        (e) =>
+          e.rel.startsWith(`.claude/skills/${n}/`) && platformsLib.selected(e.rel, profile.list),
+      ),
+  );
+  if (keptOnlyByPhase.length) {
+    console.log(
+      `  [~] Kept for other platforms because a phase names them: ${keptOnlyByPhase.join(", ")}`,
+    );
+  }
+  const missing = [...phaseSkills].filter(
+    (n) => !fs.existsSync(path.join(targetDir, ".claude", "skills", n, "SKILL.md")),
+  );
+  if (missing.length) {
+    console.log(`  [!] A phase names a skill that does not exist: ${missing.join(", ")}`);
+  }
+
+  // ── Handle CLAUDE.md ──
+  const templateClaudeMd = fs.readFileSync(path.join(templateDir, "CLAUDE.md"), "utf-8");
+  const targetClaudeMdPath = path.join(targetDir, "CLAUDE.md");
+
+  if (fs.existsSync(targetClaudeMdPath)) {
+    let existingContent = fs.readFileSync(targetClaudeMdPath, "utf-8");
+    const orchestraSection = extractOrchestraSection(templateClaudeMd);
+
+    if (!orchestraSection) {
+      console.log("  [!] Could not extract Orchestra section from template");
+      return;
+    }
+
+    if (existingContent.includes(ORCHESTRA_SECTION_START)) {
+      const existingSection = extractOrchestraSection(existingContent);
+      if (existingSection) {
+        existingContent = existingContent.replace(existingSection, orchestraSection);
+      }
+      console.log("  [~] CLAUDE.md updated (Orchestra section replaced)");
+    } else {
+      existingContent = `${existingContent.trimEnd()}\n\n${orchestraSection}\n`;
+      console.log("  [+] CLAUDE.md updated (Orchestra section appended)");
+    }
+
+    fs.writeFileSync(targetClaudeMdPath, existingContent);
+  } else {
+    fs.copyFileSync(path.join(templateDir, "CLAUDE.md"), targetClaudeMdPath);
+    console.log("  [+] CLAUDE.md created");
+  }
+
+  // PM writes milestones here and CLAUDE.md asks whether the directory is
+  // empty — a question that reads badly against a directory that does not
+  // exist. The installer never created it, so a fresh project had neither.
+  const milestones = path.join(orchestraDest, "milestones");
+  if (!fs.existsSync(milestones)) {
+    fs.mkdirSync(milestones, { recursive: true });
+    fs.writeFileSync(path.join(milestones, ".gitkeep"), "");
+  }
+
+  // In tracker mode lead caches the fetched requirements under each
+  // milestone's .cache/. Committing them would put a second copy of the
+  // requirement in the repo, which is the duplication that mode exists to
+  // remove — so the ignore ships with the directory rather than being
+  // something the user finds out about after the first commit.
+  const milestonesIgnore = path.join(milestones, ".gitignore");
+  if (!fs.existsSync(milestonesIgnore)) {
+    fs.writeFileSync(
+      milestonesIgnore,
+      "# Requirements fetched from the tracker, per run. Never authority,\n" +
+        "# never committed — see .claude/rules/tracker-authority.orchestra.md\n" +
+        ".cache/\n",
+    );
+  }
+
+  // Which role each Claude Code session declared, written by the role hook.
+  // Per machine and per session; a committed marker would tell the next
+  // clone it is a PM.
+  const sessionsIgnore = path.join(targetDir, ".orchestra", ".sessions", ".gitignore");
+  if (!fs.existsSync(sessionsIgnore)) {
+    fs.mkdirSync(path.dirname(sessionsIgnore), { recursive: true });
+    fs.writeFileSync(sessionsIgnore, "*\n!.gitignore\n");
+  }
+  // .claude/hooks/audit-context.sh keys its scratch file by session_id under
+  // this same .orchestra/.sessions/ directory, so the *!.gitignore ignore
+  // above already covers it — never authority, never committed, no separate
+  // gitignore entry to maintain.
+
+  // ── Handle permissions ──
+  if (flags.skipPermissions) {
+    setupPermissions();
+  }
+
+  registerHooks();
+  registerRoleHook();
+  registerReviewRoundsHook();
+  registerContextAuditHook();
+
+  // The previous message sent a fresh repo straight to the PM, while the
+  // CLAUDE.md it had just written says to point at setup before anything else.
+  // The first screen a new user reads contradicted the system it installed.
+  // A native app at the root has neither apps/ nor a package.json, so
+  // detection counts too.
+  const scaffolded =
+    fs.existsSync(path.join(targetDir, "apps")) ||
+    fs.existsSync(path.join(targetDir, "package.json")) ||
+    detect().length > 0;
+
+  // Preserved, and said out loud. Silently keeping a key nothing reads is how
+  // somebody spends an afternoon wondering why their setting has no effect.
+  const cfgFile = path.join(orchestraDest, "config.yml");
+  const cfgAfter = fs.existsSync(cfgFile) ? fs.readFileSync(cfgFile, "utf-8") : "";
+  const retiredKeys = RETIRED_CONFIG_KEYS.filter(([key]) => {
+    const [section, leaf] = key.split(".");
+    const at = cfgAfter.indexOf(`\n${section}:`);
+    if (at === -1) return false;
+    const rest = cfgAfter.slice(at + 1);
+    const end = rest.search(/\n[a-z_]+:/);
+    return new RegExp(`^\\s+${leaf}:`, "m").test(end === -1 ? rest : rest.slice(0, end));
+  });
+  if (retiredKeys.length) {
+    console.log("");
+    for (const [key, why] of retiredKeys) {
+      console.log(`  [~] ${key} is kept but no longer read — ${why}`);
+    }
+  }
+
+  console.log("");
+  console.log(isUpgrade ? "  Done! Orchestra is up to date." : "  Done! Orchestra is ready.");
+  console.log("");
+  console.log("  Next steps — in Claude Code, from this project:");
+  console.log("");
+  if (!scaffolded) {
+    console.log("    /orchestra:setup    scaffold the app. once, before anything else.");
+  }
+  console.log("    /orchestra:pm       plan a milestone");
+  console.log("    /orchestra:start    execute it — in a second terminal");
+  console.log("");
+  console.log("    /orchestra:help     everything else");
+  console.log("");
+}
+
+// Only when executed, never when required. Without this guard, importing
+// this file to reach one of its helpers installs Orchestra over the caller's
+// working directory — which is exactly as bad as it sounds.
+if (require.main === module) {
+  if (process.argv[2] === "new") newProject(process.argv.slice(3));
+  else run();
+}