arcane-cli 1.5.0 → 1.6.0

package/dist/index.js

@@ -6,11 +6,11 @@ const require = __createRequire(import.meta.url);
 import { Command } from "commander";
 import { createRequire as createRequire2 } from "module";
 import { fileURLToPath } from "url";
-import { dirname as dirname11, join as join18 } from "path";
+import { dirname as dirname11, join as join19 } from "path";
 
 // src/commands/init.ts
-import { select as select2, confirm, input as input2 } from "@inquirer/prompts";
-import { dirname as dirname4, join as join6 } from "path";
+import { select as select3, confirm as confirm2, input as input3 } from "@inquirer/prompts";
+import { dirname as dirname4, join as join7 } from "path";
 import chalk2 from "chalk";
 
 // src/modules/copier.ts
@@ -140,11 +140,13 @@ var ManifestCorruptError = class extends Error {
   }
 };
 var ManifestInvalidFieldError = class extends Error {
+  field;
   constructor(manifestPath2, field, value) {
     super(
       `Manifest at "${manifestPath2}" has an unsupported value for "${field}": ${JSON.stringify(value)}.`
     );
     this.name = "ManifestInvalidFieldError";
+    this.field = field;
   }
 };
 var MANIFEST_FILE = ".arcane.json";
@@ -152,6 +154,12 @@ var VALID_TRACKING_MODES = ["internal", "external"];
 var VALID_EXTERNAL_PROVIDERS = ["ado", "github", "jira", "other"];
 var VALID_CONTENT_SENSITIVITY = ["standard", "sensitive"];
 var VALID_PUSH_POLICIES = ["open", "guarded", "blocked"];
+var MANIFEST_ENUM_VALUES = {
+  tracking_mode: VALID_TRACKING_MODES,
+  external_provider: VALID_EXTERNAL_PROVIDERS,
+  content_sensitivity: VALID_CONTENT_SENSITIVITY,
+  push_policy: VALID_PUSH_POLICIES
+};
 var VALID_INSTALL_SCOPES = ["repo", "user"];
 function isValidFanoutPath(file) {
   return file.length > 0 && !file.startsWith("/") && !/^[a-zA-Z]:/.test(file) && !file.includes("\\") && !file.split("/").includes("..") && !/[\r\n\0]/.test(file);
@@ -181,13 +189,16 @@ function validateSecretsScanExcludePrefixes(value, filePath) {
     throw new ManifestInvalidFieldError(filePath, "secretsScanExcludePrefixes", value);
   }
 }
+function isValidIdeaTags(value) {
+  return isRecord(value) && (value["mode"] === "extend" || value["mode"] === "replace") && Array.isArray(value["tags"]) && value["tags"].every((tag) => typeof tag === "string" && tag.trim() !== "");
+}
 function manifestPath(targetDir) {
   return path2.join(targetDir, MANIFEST_FILE);
 }
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function validateTrackingFields(manifest, filePath) {
+function validateManifestFields(manifest, filePath) {
   if (manifest.tracking_mode !== void 0 && !VALID_TRACKING_MODES.includes(manifest.tracking_mode)) {
     throw new ManifestInvalidFieldError(filePath, "tracking_mode", manifest.tracking_mode);
   }
@@ -222,6 +233,9 @@ function validateTrackingFields(manifest, filePath) {
   if (manifest.fanout !== void 0 && !isValidFanoutRecord(manifest.fanout)) {
     throw new ManifestInvalidFieldError(filePath, "fanout", manifest.fanout);
   }
+  if (manifest.idea_tags !== void 0 && !isValidIdeaTags(manifest.idea_tags)) {
+    throw new ManifestInvalidFieldError(filePath, "idea_tags", manifest.idea_tags);
+  }
 }
 async function readManifest(targetDir) {
   const filePath = manifestPath(targetDir);
@@ -240,7 +254,7 @@ async function readManifest(targetDir) {
   } catch {
     throw new ManifestCorruptError(filePath);
   }
-  validateTrackingFields(manifest, filePath);
+  validateManifestFields(manifest, filePath);
   return manifest;
 }
 async function resolveSecretsScanExcludePrefixes(targetDir) {
@@ -262,7 +276,16 @@ async function resolveSecretsScanExcludePrefixes(targetDir) {
 }
 async function writeManifest(targetDir, manifest) {
   const filePath = manifestPath(targetDir);
-  await writeFile2(filePath, JSON.stringify(manifest, null, 2), "utf-8");
+  let existing = "";
+  try {
+    existing = await readFile2(filePath, "utf-8");
+  } catch {
+    existing = "";
+  }
+  const eol = existing.includes("\r\n") ? "\r\n" : "\n";
+  const trailingNewline = /\r?\n$/.test(existing) ? eol : "";
+  const body = JSON.stringify(manifest, null, 2).replaceAll("\n", eol);
+  await writeFile2(filePath, body + trailingNewline, "utf-8");
 }
 function addComponent(manifest, component) {
   return {
@@ -2637,10 +2660,10 @@ async function runAgentsList(targetDir, scope = "repo") {
   console.log();
 }
 
-// src/modules/push-safety.ts
-import { mkdir as mkdir5, readFile as readFile6, writeFile as writeFile7, chmod, access as access3, rm as rm4, readdir as readdir5 } from "fs/promises";
-import { constants } from "fs";
-import { join as join5, resolve as resolve2, dirname as dirname3, basename } from "path";
+// src/modules/hub.ts
+import { confirm, select as select2, input as input2 } from "@inquirer/prompts";
+import { readdir as readdir5, writeFile as writeFile7 } from "fs/promises";
+import { join as join5 } from "path";
 
 // src/modules/git.ts
 import { execFile } from "child_process";
@@ -2860,7 +2883,371 @@ async function ensureLocalPullRebase(cwd) {
   }
 }
 
+// src/modules/ado-context.ts
+function remoteUrlHost(url) {
+  const trimmed = url.trim();
+  if (trimmed.includes("://")) {
+    try {
+      return new URL(trimmed).hostname.toLowerCase() || void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  const scp = /^(?:[^@/\s]+@)?([^:/\s]+):/.exec(trimmed);
+  if (!scp || /^[a-zA-Z]$/.test(scp[1])) return void 0;
+  return scp[1].toLowerCase();
+}
+function isAdoRemoteUrl(url) {
+  const host = remoteUrlHost(url);
+  if (host === void 0) return false;
+  return host === "dev.azure.com" || host.endsWith(".dev.azure.com") || host.endsWith(".visualstudio.com");
+}
+async function detectAdoContext(targetDir) {
+  let stdout;
+  try {
+    ({ stdout } = await runGit(targetDir, ["config", "--get-regexp", "^remote\\..*\\.url$"]));
+  } catch {
+    return false;
+  }
+  return stdout.split("\n").map((line) => line.slice(line.indexOf(" ") + 1)).some((url) => url.trim() !== "" && isAdoRemoteUrl(url));
+}
+
+// src/modules/hub.ts
+async function askTrackingQuestions(targetDir) {
+  const ado = targetDir !== void 0 && await detectAdoContext(targetDir);
+  const tracking_mode = await select2({
+    message: "How will work be tracked in this repo?",
+    choices: [
+      {
+        value: "internal",
+        name: "Track work in this repo (TODO.md / PRDs)",
+        description: "Spells keep TODOs, PRDs and stories in this repository's own files."
+      },
+      {
+        value: "external",
+        name: "Track work in an external tracker (Azure DevOps / GitHub / Jira / other)",
+        description: "Spells tie PRDs, commits and PRs to items in the tracker you pick next."
+      }
+    ],
+    ...ado ? { default: "external" } : {}
+  });
+  if (tracking_mode !== "external") return { tracking_mode, external_provider: null };
+  const external_provider = await select2({
+    message: "Which external tracker?",
+    choices: [
+      {
+        value: "ado",
+        name: "Azure DevOps",
+        description: "Each PRD needs an ADO work item ID; plans follow your process template's item types."
+      },
+      {
+        value: "github",
+        name: "GitHub Issues",
+        description: "Uses the gh CLI; an issue number is optional and linked from commits and PRs when known."
+      },
+      {
+        value: "jira",
+        name: "Jira",
+        description: "No Jira automation yet: spells note linking as a TODO and keep planning in this repo."
+      },
+      {
+        value: "other",
+        name: "Other",
+        description: "No automation: spells note linking as a TODO and keep planning in this repo."
+      }
+    ],
+    ...ado ? { default: "ado" } : {}
+  });
+  return { tracking_mode, external_provider };
+}
+var MANIFEST_RETROFITS = [
+  {
+    field: "role",
+    flag: "--role <hub|consumer>",
+    needsRetrofit: (m) => m.role === void 0,
+    ask: async () => {
+      const isHub = await confirm({
+        message: "Will this repo manage other ventures as a hub? (idea books, spell-manifest promotion, venture registry)",
+        default: false
+      });
+      return { role: isHub ? "hub" : "consumer" };
+    }
+  },
+  {
+    field: "tracking_mode",
+    flag: "--tracking-mode <internal|external>",
+    needsRetrofit: (m) => m.tracking_mode === void 0,
+    // Mirrors init.ts's Step 5b branching exactly (EF-14 D5): docs-only
+    // profiles get a silent default, full/lite get asked -- through the same
+    // askTrackingQuestions init uses, so the two cannot drift.
+    ask: async (manifest, targetDir) => {
+      if (manifest.profile === "governance-only" || manifest.profile === "methodology" || manifest.profile === "docs") {
+        return { tracking_mode: "internal", external_provider: null };
+      }
+      return askTrackingQuestions(targetDir);
+    }
+  },
+  {
+    field: "content_sensitivity",
+    flag: "--content-sensitivity <standard|sensitive>",
+    needsRetrofit: (m) => m.content_sensitivity === void 0,
+    // EF-12. Asked for every profile -- a code repo can hold sensitive records
+    // too -- and defaults to "standard", so an operator who just presses enter
+    // keeps today's behaviour exactly.
+    ask: async () => {
+      const content_sensitivity = await select2({
+        message: "How should agents treat this repository's contents?",
+        choices: [
+          {
+            value: "standard",
+            name: "Standard \u2014 agents may quote contents in journals and decisions"
+          },
+          {
+            value: "sensitive",
+            name: "Sensitive \u2014 agents reference documents by path, never transcribe them"
+          }
+        ],
+        default: "standard"
+      });
+      return { content_sensitivity };
+    }
+  },
+  {
+    field: "subject_root",
+    flag: "--subject-root <path>",
+    // EF-07. Only the docs profile is asked: other profiles describe code or a
+    // venture portfolio, where "what is this repo about" is already answered.
+    // A docs install that legitimately holds several subjects answers
+    // "portfolio" and stays unset -- so this retrofit deliberately does NOT
+    // re-ask on every update. It is gated on the field being absent AND the
+    // profile being docs, and once answered (either way) it never fires again,
+    // because "portfolio" writes an explicit empty marker.
+    needsRetrofit: (m) => m.profile === "docs" && m.subject_root === void 0,
+    ask: async () => {
+      const shape = await select2({
+        message: "What does this repository hold?",
+        choices: [
+          {
+            value: "root",
+            name: "One subject, at the repository root (documents sit alongside Arcane's files)"
+          },
+          { value: "subdir", name: "One subject, in its own directory" },
+          { value: "portfolio", name: "Several subjects or ventures" }
+        ]
+      });
+      if (shape === "root") return { subject_root: "." };
+      if (shape === "subdir") {
+        const answer = await input2({
+          message: "Directory holding the subject's documents:",
+          default: "docs",
+          validate: (v) => isValidSubjectRoot(v.trim() || "docs") || "Must be a relative path inside the repository (no leading /, drive letter, or ..)."
+        });
+        return { subject_root: answer.trim() || "docs" };
+      }
+      return { subject_root: null };
+    }
+  },
+  {
+    field: "push_policy",
+    flag: "--push-policy <open|guarded|blocked>",
+    needsRetrofit: (m) => m.push_policy === void 0,
+    // EF-09. Defaults to "open", so an operator who just presses enter keeps
+    // today's behaviour exactly. NOTE: this only records the choice -- unlike
+    // init, the retrofit does not install the hook or disable the push URL,
+    // because an update should not silently start blocking pushes in a repo
+    // someone is mid-workflow in (ARC-034 decision 7). ARC-049 decision 2:
+    // update prints pushPolicyNotice() instead, naming `spell block-push`.
+    ask: async () => {
+      const push_policy = await select2({
+        message: "Should this repository be allowed to push to a remote?",
+        choices: [
+          { value: "open", name: "Yes \u2014 normal repository" },
+          { value: "guarded", name: "Sensitive, but keep push working \u2014 remind me instead" },
+          { value: "blocked", name: "No \u2014 block pushes" }
+        ],
+        default: "open"
+      });
+      return { push_policy };
+    }
+  }
+];
+function pushPolicyNotice(policy) {
+  if (policy === "blocked") {
+    return [
+      "",
+      '  ! Required action: push_policy is now recorded as "blocked", but it is NOT enforced yet.',
+      "    `spell update` never installs push controls. Pushes from this repository still work",
+      "    until you run:",
+      "",
+      "      spell block-push",
+      ""
+    ];
+  }
+  if (policy === "guarded") {
+    return [
+      "",
+      '  push_policy is now recorded as "guarded". Nothing is installed for it: `spell doctor`',
+      "  reports it, and push-performing spells state the policy and ask before pushing.",
+      ""
+    ];
+  }
+  return [];
+}
+async function runManifestRetrofits(manifest, targetDir) {
+  const applicable = MANIFEST_RETROFITS.filter((r) => r.needsRetrofit(manifest));
+  if (applicable.length === 0) return {};
+  console.log();
+  console.log(
+    `This install predates ${applicable.length} manifest field${applicable.length === 1 ? "" : "s"} -- a couple of quick questions:`
+  );
+  let patch = {};
+  for (const retrofit of applicable) {
+    const answer = await retrofit.ask({ ...manifest, ...patch }, targetDir);
+    patch = { ...patch, ...answer };
+  }
+  return patch;
+}
+function manifestFlagLine(manifest) {
+  const pending = MANIFEST_RETROFITS.filter((r) => r.needsRetrofit(manifest));
+  if (pending.length === 0) return void 0;
+  const lines = [`spell update ${pending.map((r) => r.flag).join(" ")}`];
+  if (pending.some((r) => r.field === "tracking_mode")) {
+    lines.push("(--tracking-mode external also needs --external-provider <ado|github|jira|other>)");
+  }
+  return lines;
+}
+var ManifestFlagError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ManifestFlagError";
+  }
+};
+var FLAG_NAMES = {
+  role: "--role",
+  tracking_mode: "--tracking-mode",
+  external_provider: "--external-provider",
+  content_sensitivity: "--content-sensitivity",
+  subject_root: "--subject-root",
+  push_policy: "--push-policy"
+};
+var PUSH_POLICY_STRICTNESS = { open: 0, guarded: 1, blocked: 2 };
+function hasManifestFlags(flags) {
+  return flags !== void 0 && Object.values(flags).some((v) => v !== void 0);
+}
+function resolveManifestFlags(flags, current, manifestPath2) {
+  if (!hasManifestFlags(flags)) return {};
+  const requested = {};
+  if (flags.role !== void 0) requested.role = flags.role;
+  if (flags.trackingMode !== void 0) requested.tracking_mode = flags.trackingMode;
+  if (flags.externalProvider !== void 0) requested.external_provider = flags.externalProvider;
+  if (flags.contentSensitivity !== void 0) requested.content_sensitivity = flags.contentSensitivity;
+  if (flags.subjectRoot !== void 0) requested.subject_root = flags.subjectRoot;
+  if (flags.pushPolicy !== void 0) requested.push_policy = flags.pushPolicy;
+  const invalid = (error) => {
+    const allowed = error.field === "role" ? ["hub", "consumer"] : MANIFEST_ENUM_VALUES[error.field];
+    const hint = allowed ? ` Valid values: ${allowed.join(", ")}.` : "";
+    return new ManifestFlagError(`Invalid ${FLAG_NAMES[error.field] ?? error.field}: ${error.message}${hint}`);
+  };
+  if (requested.role !== void 0 && requested.role !== "hub" && requested.role !== "consumer") {
+    throw invalid(new ManifestInvalidFieldError(manifestPath2, "role", requested.role));
+  }
+  try {
+    validateManifestFields(requested, manifestPath2);
+  } catch (error) {
+    if (error instanceof ManifestInvalidFieldError) throw invalid(error);
+    throw error;
+  }
+  if (requested.external_provider !== void 0 && requested.tracking_mode !== "external") {
+    throw new ManifestFlagError("--external-provider applies only together with --tracking-mode external.");
+  }
+  if (requested.tracking_mode === "external" && requested.external_provider === void 0) {
+    throw new ManifestFlagError(
+      "--tracking-mode external needs --external-provider <ado|github|jira|other> as well."
+    );
+  }
+  if (requested.tracking_mode === "internal") requested.external_provider = null;
+  const patch = {};
+  for (const field of Object.keys(FLAG_NAMES)) {
+    if (!(field in requested)) continue;
+    const value = requested[field];
+    const recorded = current[field];
+    if (recorded === void 0) {
+      patch[field] = value;
+      continue;
+    }
+    if (field === "push_policy") {
+      const from = PUSH_POLICY_STRICTNESS[recorded];
+      const to = PUSH_POLICY_STRICTNESS[value];
+      if (to < from) {
+        throw new ManifestFlagError(
+          `--push-policy ${String(value)} would loosen this repository's recorded push_policy "${String(recorded)}". No flag can loosen it: run \`spell unblock-push\` from an interactive terminal.`
+        );
+      }
+      if (to > from) patch[field] = value;
+      continue;
+    }
+    if (recorded === value) continue;
+    const flag = field === "external_provider" && flags.externalProvider === void 0 ? "--tracking-mode" : FLAG_NAMES[field];
+    throw new ManifestFlagError(
+      `${flag} conflicts with the recorded ${field}: ${JSON.stringify(recorded)}. A flag only answers a question that has no recorded answer; change .arcane.json deliberately if the recorded value is wrong.`
+    );
+  }
+  return patch;
+}
+function describeFlagPatch(patch) {
+  return Object.entries(patch).filter(([field]) => field in FLAG_NAMES).map(([field, value]) => `${field}: ${JSON.stringify(value)}`);
+}
+async function offerRegistryScaffold(targetDir, businessRoot) {
+  const registryPath = join5(targetDir, businessRoot, "registry.json");
+  if (await fileExists(registryPath)) return;
+  const businessRootPath = join5(targetDir, businessRoot);
+  let ventureDirs;
+  try {
+    const entries = await readdir5(businessRootPath, { withFileTypes: true });
+    ventureDirs = entries.filter((e) => e.isDirectory() && e.name !== "_template").map((e) => e.name);
+  } catch {
+    return;
+  }
+  if (ventureDirs.length === 0) return;
+  console.log();
+  const scaffold = await confirm({
+    message: `Found ${ventureDirs.length} folder${ventureDirs.length === 1 ? "" : "s"} under ${businessRoot}/ -- scaffold ${businessRoot}/registry.json from them?`,
+    default: true
+  });
+  if (!scaffold) return;
+  const ventures = {};
+  for (const slug of ventureDirs) {
+    const include = await confirm({ message: `  Include "${slug}"?`, default: true });
+    if (!include) continue;
+    ventures[slug] = {
+      name: slug,
+      aliases: [],
+      status: "active",
+      visibility: "private",
+      ownership: "llc",
+      tracking: "none",
+      repos: []
+    };
+  }
+  if (Object.keys(ventures).length === 0) {
+    console.log("  No ventures selected -- registry not created.");
+    return;
+  }
+  const registry = {
+    _comment: "Hub-owned venture registry. Private. Never installed or modified by spell update. Seeded by the retrofit wizard -- review and enrich (aliases, ownership, tracking, clones) before relying on it.",
+    updated: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+    ventures
+  };
+  await writeFile7(registryPath, JSON.stringify(registry, null, 2) + "\n", "utf-8");
+  console.log(
+    `  \u2713 Scaffolded ${businessRoot}/registry.json with ${Object.keys(ventures).length} venture(s).`
+  );
+}
+
 // src/modules/push-safety.ts
+import { mkdir as mkdir5, readFile as readFile6, writeFile as writeFile8, chmod, access as access3, rm as rm4, readdir as readdir6 } from "fs/promises";
+import { constants } from "fs";
+import { join as join6, resolve as resolve2, dirname as dirname3, basename } from "path";
 var DISABLED_PUSH_URL = "arcane-push-blocked-run-spell-unblock-push://this-repository";
 var NO_PUSH_URL_MARKER = (remote) => `remote.${remote}.arcaneHadNoPushUrl`;
 var ARCANE_HOOKS_DIR = ".arcane/hooks";
@@ -2951,10 +3338,10 @@ async function repositoryRoot(cwd) {
   return cwd;
 }
 async function hookFilePath(cwd, hookName = "pre-push") {
-  return join5(await repositoryRoot(cwd), ARCANE_HOOKS_DIR, hookName);
+  return join6(await repositoryRoot(cwd), ARCANE_HOOKS_DIR, hookName);
 }
 async function hooksPathValue(cwd) {
-  return join5(await repositoryRoot(cwd), ARCANE_HOOKS_DIR).replace(/\\/g, "/");
+  return join6(await repositoryRoot(cwd), ARCANE_HOOKS_DIR).replace(/\\/g, "/");
 }
 async function installHook(cwd, hookName, body) {
   const root = await repositoryRoot(cwd);
@@ -2973,12 +3360,12 @@ async function installHook(cwd, hookName, body) {
       return { status: "refused-default-hooks", hooks: displaced };
     }
   }
-  const hookPath = join5(root, ARCANE_HOOKS_DIR, hookName);
+  const hookPath = join6(root, ARCANE_HOOKS_DIR, hookName);
   if (existing !== void 0 && await hookFileMatches(cwd, hookName, body)) {
     return { status: "already-ours" };
   }
-  await mkdir5(join5(root, ARCANE_HOOKS_DIR), { recursive: true });
-  await writeFile7(hookPath, body, "utf-8");
+  await mkdir5(join6(root, ARCANE_HOOKS_DIR), { recursive: true });
+  await writeFile8(hookPath, body, "utf-8");
   await chmod(hookPath, 493);
   await runGit(cwd, ["config", "--local", "core.hooksPath", await hooksPathValue(cwd)]);
   return { status: "installed", path: hookPath };
@@ -3022,12 +3409,12 @@ async function defaultHooks(cwd) {
   let hooksDir;
   try {
     const { stdout } = await runGit(cwd, ["rev-parse", "--git-common-dir"]);
-    hooksDir = join5(resolve2(cwd, stdout.trim()), "hooks");
+    hooksDir = join6(resolve2(cwd, stdout.trim()), "hooks");
   } catch {
     return [];
   }
   try {
-    return (await readdir5(hooksDir)).filter((name) => !name.endsWith(".sample")).sort();
+    return (await readdir6(hooksDir)).filter((name) => !name.endsWith(".sample")).sort();
   } catch {
     return [];
   }
@@ -3058,10 +3445,10 @@ async function removeHook(cwd, hookName) {
     await rm4(await hookFilePath(cwd, hookName), { force: true });
   } catch {
   }
-  const hooksDir = join5(root, ARCANE_HOOKS_DIR);
+  const hooksDir = join6(root, ARCANE_HOOKS_DIR);
   let remaining = [];
   try {
-    remaining = await readdir5(hooksDir);
+    remaining = await readdir6(hooksDir);
   } catch {
     remaining = [];
   }
@@ -3281,6 +3668,60 @@ function describeError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return message.split("\n")[0].trim();
 }
+function hookInForce(outcome) {
+  return outcome.status === "installed" || outcome.status === "already-ours";
+}
+async function applyBlockedPushControls(cwd, options = {}) {
+  const messages = [];
+  const say = (level, text) => {
+    const message = { level, text };
+    messages.push(message);
+    options.emit?.(message);
+  };
+  const hook = await installPrePushHook(cwd);
+  if (hook.status === "refused-unreadable-config") {
+    say(
+      "warning",
+      "Did not install the pre-push hook: git could not report the current core.hooksPath (unreadable config, or a git too old for `--show-scope`). Installing without knowing whether another hook manager owns that setting could silently disable it. Fix the config and run `spell doctor`."
+    );
+  } else if (hook.status === "refused-default-hooks") {
+    say(
+      "warning",
+      `Did not install the pre-push hook: this repository has hooks in git's default directory (${hook.hooks.join(", ")}). Setting core.hooksPath would silently stop them running. Move them under \`${ARCANE_HOOKS_DIR}\` yourself and re-run, or add the push guard to your existing pre-push hook.`
+    );
+  } else if (hook.status === "refused-foreign-hooks-path") {
+    say(
+      "warning",
+      `Did not install the pre-push hook: core.hooksPath is already "${hook.existing}" (${describeConfigScope(hook.scope)}), so another hook manager owns it. Overwriting would silently disable those hooks. Chain an Arcane pre-push guard into that directory yourself, or unset core.hooksPath first.`
+    );
+  } else {
+    say("info", "Installed a pre-push hook that blocks pushes from this repository.");
+  }
+  if (options.stopOnHookRefusal === true && !hookInForce(hook)) {
+    return { hook, urls: [], stoppedAtHook: true, messages };
+  }
+  const urls = await disablePushUrls(cwd);
+  const unprotected = urls.filter((u) => u.status === "failed");
+  if (unprotected.length > 0) {
+    say(
+      "warning",
+      `Could not disable the push URL for: ${unprotected.map((u) => `${u.remote} (${u.reason ?? "unknown error"})`).join("; ")}. Those remotes are still pushable with \`--no-verify\`. Run \`spell doctor\` \u2014 it lists exactly which remotes are still live.`
+    );
+  }
+  if (urls.length === 0) {
+    say(
+      "warning",
+      "No remote is configured, so only the pre-push hook is active. A remote added later will NOT have its push URL disabled automatically, and a `--no-verify` push to it would succeed. Run `spell doctor` after adding one \u2014 it reports this gap."
+    );
+  } else {
+    const covered = urls.filter((u) => u.status !== "failed").map((u) => u.remote);
+    if (covered.length > 0) {
+      say("info", `Disabled the push URL for: ${covered.join(", ")} (fetch still works).`);
+    }
+  }
+  say("info", "Run `spell unblock-push` from a terminal to undo this.");
+  return { hook, urls, stoppedAtHook: false, messages };
+}
 
 // src/modules/secrets-scan.ts
 var SECRETS_RULES = [
@@ -3390,6 +3831,13 @@ function buildProfileDescription(components, profile) {
 }
 async function runInit(options, targetDir, assetsDir, packageVersion) {
   if (options.user) {
+    if (hasManifestFlags(options.manifestFlags)) {
+      console.error(
+        "\n  \u2717 The manifest-question flags describe a repository; the user tier has none of those fields.\n"
+      );
+      process.exit(1);
+      return;
+    }
     await runInitUser(options, targetDir, assetsDir, packageVersion);
     return;
   }
@@ -3398,13 +3846,27 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       `Invalid profile "${options.profile}". Valid options: ${VALID_PROFILES.join(", ")}`
     );
   }
+  let flags = {};
   try {
-    await readManifest(targetDir);
-    console.log(chalk2.hex("#a855f7")(`
-  \u2726 Arcane v${packageVersion}
-`));
-    console.log('Already initialized. Run "spell update" to update existing files.');
-    return;
+    flags = resolveManifestFlags(options.manifestFlags, {}, join7(targetDir, ".arcane.json"));
+  } catch (err) {
+    if (!(err instanceof ManifestFlagError)) throw err;
+    console.error(`
+  \u2717 ${err.message}
+`);
+    process.exit(1);
+    return;
+  }
+  try {
+    await readManifest(targetDir);
+    console.log(chalk2.hex("#a855f7")(`
+  \u2726 Arcane v${packageVersion}
+`));
+    console.log('Already initialized. Run "spell update" to update existing files.');
+    if (hasManifestFlags(options.manifestFlags)) {
+      console.log("Pass the same manifest-question flags to `spell update` to record them here.");
+    }
+    return;
   } catch (err) {
     if (!(err instanceof ManifestNotFoundError)) throw err;
   }
@@ -3435,7 +3897,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
         );
         printInfo("Running spell init will add new files to your working tree.");
         console.log();
-        const continueAnyway = await confirm({
+        const continueAnyway = await confirm2({
           message: "Continue anyway?",
           default: true
         });
@@ -3456,7 +3918,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   let profile = options.profile;
   if (!profile) {
     const profiles = listProfiles();
-    profile = await select2({
+    profile = await select3({
       message: "Select an installation profile:\n",
       choices: profiles.map((p) => {
         const profileComponents2 = getProfile(p.id);
@@ -3481,7 +3943,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
     }
     if (storeVersion !== void 0) {
       console.log();
-      const useTier = await confirm({
+      const useTier = await confirm2({
         message: `This machine has an Arcane user tier (v${storeVersion}). Use it for this repository's spells instead of installing copies here?`,
         default: preferred === "user"
       });
@@ -3504,7 +3966,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   console.log(`  ${previewParts.join(" \xB7 ")}`);
   console.log();
   if (!options.dryRun && !options.profile) {
-    const proceed = await confirm({
+    const proceed = await confirm2({
       message: "Proceed with installation?",
       default: true
     });
@@ -3519,7 +3981,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
     const installedFiles = [];
     const fileHashes = {};
     for (const file of component.files) {
-      const srcPath = join6(assetsDir, component.sourceOverrides?.[file] ?? file);
+      const srcPath = join7(assetsDir, component.sourceOverrides?.[file] ?? file);
       if (options.dryRun) {
         printDryRun(`Would copy: ${file}`);
       } else {
@@ -3536,7 +3998,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       fileCount++;
     }
     for (const dir of component.directories ?? []) {
-      const srcDirPath = join6(assetsDir, dir);
+      const srcDirPath = join7(assetsDir, dir);
       if (options.dryRun) {
         printDryRun(`Would copy directory: ${dir}/`);
       } else {
@@ -3565,7 +4027,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   if (options.dryRun) {
     if (hasAgents) {
       const agentFiles = await import("fs").then(
-        (fsModule) => fsModule.promises.readdir(join6(assetsDir, "agents"))
+        (fsModule) => fsModule.promises.readdir(join7(assetsDir, "agents"))
       );
       const yamlFiles = agentFiles.filter((f) => f.endsWith(".yaml")).sort();
       printDryRun("Would run agent setup (interactive):");
@@ -3577,10 +4039,10 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
     printDryRun(`Would initialize with profile "${profile}" \u2014 ${fileCount} files`);
     return;
   }
-  let role;
-  if (!options.profile) {
+  let role = flags.role;
+  if (role === void 0 && !options.profile) {
     console.log();
-    const isHub = await confirm({
+    const isHub = await confirm2({
       message: "Will this repo manage other ventures as a hub? (idea books, spell-manifest promotion, venture registry)",
       default: false
     });
@@ -3588,36 +4050,20 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   }
   let tracking_mode;
   let external_provider;
-  if (profile === "governance-only" || profile === "methodology" || profile === "docs") {
+  if (flags.tracking_mode !== void 0) {
+    tracking_mode = flags.tracking_mode;
+    external_provider = flags.external_provider ?? null;
+  } else if (profile === "governance-only" || profile === "methodology" || profile === "docs") {
     tracking_mode = "internal";
     external_provider = null;
   } else if (!options.profile) {
     console.log();
-    tracking_mode = await select2({
-      message: "How will work be tracked in this repo?",
-      choices: [
-        { value: "internal", name: "Track work in this repo (TODO.md / PRDs)" },
-        { value: "external", name: "Track work in an external tracker (Azure DevOps / GitHub / Jira / other)" }
-      ]
-    });
-    if (tracking_mode === "external") {
-      external_provider = await select2({
-        message: "Which external tracker?",
-        choices: [
-          { value: "ado", name: "Azure DevOps" },
-          { value: "github", name: "GitHub Issues" },
-          { value: "jira", name: "Jira" },
-          { value: "other", name: "Other" }
-        ]
-      });
-    } else {
-      external_provider = null;
-    }
+    ({ tracking_mode, external_provider } = await askTrackingQuestions(targetDir));
   }
-  let subject_root;
-  if (profile === "docs" && !options.profile) {
+  let subject_root = flags.subject_root;
+  if (subject_root === void 0 && profile === "docs" && !options.profile) {
     console.log();
-    const shape = await select2({
+    const shape = await select3({
       message: "What does this repository hold?",
       choices: [
         {
@@ -3631,7 +4077,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
     if (shape === "root") {
       subject_root = ".";
     } else if (shape === "subdir") {
-      const answer = await input2({
+      const answer = await input3({
         message: "Directory holding the subject's documents:",
         default: "docs",
         validate: (v) => isValidSubjectRoot(v.trim() || "docs") || "Must be a relative path inside the repository (no leading /, drive letter, or ..)."
@@ -3641,10 +4087,10 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       subject_root = null;
     }
   }
-  let content_sensitivity;
-  if (!options.profile) {
+  let content_sensitivity = flags.content_sensitivity;
+  if (content_sensitivity === void 0 && !options.profile) {
     console.log();
-    content_sensitivity = await select2({
+    content_sensitivity = await select3({
       message: "How should agents treat this repository's contents?",
       choices: [
         { value: "standard", name: "Standard \u2014 agents may quote contents in journals and decisions" },
@@ -3656,10 +4102,10 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       default: "standard"
     });
   }
-  let push_policy;
-  if (!options.profile) {
+  let push_policy = flags.push_policy;
+  if (push_policy === void 0 && !options.profile) {
     console.log();
-    push_policy = await select2({
+    push_policy = await select3({
       message: "Should this repository be allowed to push to a remote?",
       choices: [
         { value: "open", name: "Yes \u2014 normal repository" },
@@ -3686,43 +4132,23 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   };
   await writeManifest(targetDir, manifest);
   printSuccess(`Initialized with profile "${profile}" \u2014 ${fileCount} files installed`);
+  const flagLine = options.profile ? manifestFlagLine(manifest) : void 0;
+  if (flagLine) {
+    printInfo("Some setup questions were left unanswered. Answer them without a prompt with:");
+    for (const line of flagLine) printInfo(`  ${line}`);
+  }
   if (push_policy === "blocked" || push_policy === "guarded") {
     try {
       if (push_policy === "blocked") {
-        const hook = await installPrePushHook(targetDir);
-        if (hook.status === "refused-unreadable-config") {
-          printWarning(
-            "Did not install the pre-push hook: git could not report the current core.hooksPath (unreadable config, or a git too old for `--show-scope`). Installing without knowing whether another hook manager owns that setting could silently disable it. Fix the config and run `spell doctor`."
-          );
-        } else if (hook.status === "refused-default-hooks") {
-          printWarning(
-            `Did not install the pre-push hook: this repository has hooks in git's default directory (${hook.hooks.join(", ")}). Setting core.hooksPath would silently stop them running. Move them under \`${ARCANE_HOOKS_DIR}\` yourself and re-run, or add the push guard to your existing pre-push hook.`
-          );
-        } else if (hook.status === "refused-foreign-hooks-path") {
-          printWarning(
-            `Did not install the pre-push hook: core.hooksPath is already "${hook.existing}" (${describeConfigScope(hook.scope)}), so another hook manager owns it. Overwriting would silently disable those hooks. Chain an Arcane pre-push guard into that directory yourself, or unset core.hooksPath first.`
-          );
-        } else {
-          printInfo("Installed a pre-push hook that blocks pushes from this repository.");
-        }
-        const urls = await disablePushUrls(targetDir);
-        const unprotected = urls.filter((u) => u.status === "failed");
-        if (unprotected.length > 0) {
-          printWarning(
-            `Could not disable the push URL for: ${unprotected.map((u) => `${u.remote} (${u.reason ?? "unknown error"})`).join("; ")}. Those remotes are still pushable with \`--no-verify\`. Run \`spell doctor\` \u2014 it lists exactly which remotes are still live.`
-          );
-        }
-        if (urls.length === 0) {
+        const controls = await applyBlockedPushControls(targetDir, {
+          emit: (m) => m.level === "warning" ? printWarning(m.text) : printInfo(m.text)
+        });
+        if (!hookInForce(controls.hook) || controls.urls.some((u) => u.status === "failed")) {
           printWarning(
-            "No remote is configured, so only the pre-push hook is active. A remote added later will NOT have its push URL disabled automatically, and a `--no-verify` push to it would succeed. Run `spell doctor` after adding one \u2014 it reports this gap."
+            'push_policy is recorded as "blocked", but the block is not fully in force. Resolve the cause above, then run `spell block-push`; `spell doctor` shows exactly what is missing.'
           );
-        } else {
-          const covered = urls.filter((u) => u.status !== "failed").map((u) => u.remote);
-          if (covered.length > 0) {
-            printInfo(`Disabled the push URL for: ${covered.join(", ")} (fetch still works).`);
-          }
+          process.exitCode = 1;
         }
-        printInfo("Run `spell unblock-push` from a terminal to undo this.");
       } else {
         printInfo(
           "Marked as push-guarded. No technical control was installed \u2014 check the remote is the one you intend before pushing. `spell doctor` will keep reminding you."
@@ -3768,7 +4194,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   let agentsConfigured = false;
   if (hasAgents && !options.profile) {
     console.log();
-    const setupAgents = await confirm({
+    const setupAgents = await confirm2({
       message: "\u{1F916} Set up your agent team? (names, roles, AI tool configs)",
       default: true
     });
@@ -3814,6 +4240,11 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
       '"--profile" does not apply to "--user": the user tier always installs every spell and nothing else.'
     );
   }
+  if (hasManifestFlags(options.manifestFlags)) {
+    throw new Error(
+      'The manifest-question flags do not apply to "--user": they describe a repository, and the user tier is not one.'
+    );
+  }
   try {
     await readManifest(storeRoot);
     console.log(chalk2.hex("#a855f7")(`
@@ -3847,7 +4278,7 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
     for (const id of spellIds) {
       for (const client of ["codex", "claude"]) {
         const relativePath = USER_FANOUT_PATHS[client](id);
-        if (await fileExists(join6(homeDir, relativePath))) {
+        if (await fileExists(join7(homeDir, relativePath))) {
           printDryRun(`Would leave alone (exists, not written by Arcane): ~/${relativePath}`);
         } else {
           printDryRun(`Would write: ~/${relativePath}`);
@@ -3865,7 +4296,7 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
     const installedFiles = [];
     const fileHashes = {};
     for (const file of component.files) {
-      const srcPath = join6(assetsDir, component.sourceOverrides?.[file] ?? file);
+      const srcPath = join7(assetsDir, component.sourceOverrides?.[file] ?? file);
       fileHashes[file] = await copyFile(srcPath, storeRoot, file, { force: options.force });
       installedFiles.push(file);
       fileCount++;
@@ -3911,7 +4342,7 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
 }
 
 // src/commands/add.ts
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
   let manifest;
   try {
@@ -3947,7 +4378,7 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
   const installedFiles = [];
   const fileHashes = {};
   for (const file of component.files) {
-    const srcPath = join7(assetsDir, component.sourceOverrides?.[file] ?? file);
+    const srcPath = join8(assetsDir, component.sourceOverrides?.[file] ?? file);
     if (options.dryRun) {
       console.log(`  [dry-run] Would copy: ${file}`);
     } else {
@@ -3957,7 +4388,7 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
     fileCount++;
   }
   for (const dir of component.directories ?? []) {
-    const srcDirPath = join7(assetsDir, dir);
+    const srcDirPath = join8(assetsDir, dir);
     if (options.dryRun) {
       console.log(`  [dry-run] Would copy directory: ${dir}/`);
     } else {
@@ -3994,194 +4425,6 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
 import { dirname as dirname5, join as join9 } from "path";
 import { readFile as readFile7, writeFile as writeFile9 } from "fs/promises";
 
-// src/modules/hub.ts
-import { confirm as confirm2, select as select3, input as input3 } from "@inquirer/prompts";
-import { readdir as readdir6, writeFile as writeFile8 } from "fs/promises";
-import { join as join8 } from "path";
-var MANIFEST_RETROFITS = [
-  {
-    field: "role",
-    needsRetrofit: (m) => m.role === void 0,
-    ask: async () => {
-      const isHub = await confirm2({
-        message: "Will this repo manage other ventures as a hub? (idea books, spell-manifest promotion, venture registry)",
-        default: false
-      });
-      return { role: isHub ? "hub" : "consumer" };
-    }
-  },
-  {
-    field: "tracking_mode",
-    needsRetrofit: (m) => m.tracking_mode === void 0,
-    // Mirrors init.ts's Step 5b branching exactly (EF-14 D5): docs-only
-    // profiles get a silent default, full/lite get asked.
-    ask: async (manifest) => {
-      if (manifest.profile === "governance-only" || manifest.profile === "methodology" || manifest.profile === "docs") {
-        return { tracking_mode: "internal", external_provider: null };
-      }
-      const tracking_mode = await select3({
-        message: "How will work be tracked in this repo?",
-        choices: [
-          { value: "internal", name: "Track work in this repo (TODO.md / PRDs)" },
-          { value: "external", name: "Track work in an external tracker (Azure DevOps / GitHub / Jira / other)" }
-        ]
-      });
-      if (tracking_mode === "external") {
-        const external_provider = await select3({
-          message: "Which external tracker?",
-          choices: [
-            { value: "ado", name: "Azure DevOps" },
-            { value: "github", name: "GitHub Issues" },
-            { value: "jira", name: "Jira" },
-            { value: "other", name: "Other" }
-          ]
-        });
-        return { tracking_mode, external_provider };
-      }
-      return { tracking_mode, external_provider: null };
-    }
-  },
-  {
-    field: "content_sensitivity",
-    needsRetrofit: (m) => m.content_sensitivity === void 0,
-    // EF-12. Asked for every profile -- a code repo can hold sensitive records
-    // too -- and defaults to "standard", so an operator who just presses enter
-    // keeps today's behaviour exactly.
-    ask: async () => {
-      const content_sensitivity = await select3({
-        message: "How should agents treat this repository's contents?",
-        choices: [
-          {
-            value: "standard",
-            name: "Standard \u2014 agents may quote contents in journals and decisions"
-          },
-          {
-            value: "sensitive",
-            name: "Sensitive \u2014 agents reference documents by path, never transcribe them"
-          }
-        ],
-        default: "standard"
-      });
-      return { content_sensitivity };
-    }
-  },
-  {
-    field: "subject_root",
-    // EF-07. Only the docs profile is asked: other profiles describe code or a
-    // venture portfolio, where "what is this repo about" is already answered.
-    // A docs install that legitimately holds several subjects answers
-    // "portfolio" and stays unset -- so this retrofit deliberately does NOT
-    // re-ask on every update. It is gated on the field being absent AND the
-    // profile being docs, and once answered (either way) it never fires again,
-    // because "portfolio" writes an explicit empty marker.
-    needsRetrofit: (m) => m.profile === "docs" && m.subject_root === void 0,
-    ask: async () => {
-      const shape = await select3({
-        message: "What does this repository hold?",
-        choices: [
-          {
-            value: "root",
-            name: "One subject, at the repository root (documents sit alongside Arcane's files)"
-          },
-          { value: "subdir", name: "One subject, in its own directory" },
-          { value: "portfolio", name: "Several subjects or ventures" }
-        ]
-      });
-      if (shape === "root") return { subject_root: "." };
-      if (shape === "subdir") {
-        const answer = await input3({
-          message: "Directory holding the subject's documents:",
-          default: "docs",
-          validate: (v) => isValidSubjectRoot(v.trim() || "docs") || "Must be a relative path inside the repository (no leading /, drive letter, or ..)."
-        });
-        return { subject_root: answer.trim() || "docs" };
-      }
-      return { subject_root: null };
-    }
-  },
-  {
-    field: "push_policy",
-    needsRetrofit: (m) => m.push_policy === void 0,
-    // EF-09. Defaults to "open", so an operator who just presses enter keeps
-    // today's behaviour exactly. NOTE: this only records the choice -- unlike
-    // init, the retrofit does not install the hook or disable the push URL,
-    // because an update should not silently start blocking pushes in a repo
-    // someone is mid-workflow in. doctor reports the gap instead.
-    ask: async () => {
-      const push_policy = await select3({
-        message: "Should this repository be allowed to push to a remote?",
-        choices: [
-          { value: "open", name: "Yes \u2014 normal repository" },
-          { value: "guarded", name: "Sensitive, but keep push working \u2014 remind me instead" },
-          { value: "blocked", name: "No \u2014 block pushes" }
-        ],
-        default: "open"
-      });
-      return { push_policy };
-    }
-  }
-];
-async function runManifestRetrofits(manifest) {
-  const applicable = MANIFEST_RETROFITS.filter((r) => r.needsRetrofit(manifest));
-  if (applicable.length === 0) return {};
-  console.log();
-  console.log(
-    `This install predates ${applicable.length} manifest field${applicable.length === 1 ? "" : "s"} -- a couple of quick questions:`
-  );
-  let patch = {};
-  for (const retrofit of applicable) {
-    const answer = await retrofit.ask({ ...manifest, ...patch });
-    patch = { ...patch, ...answer };
-  }
-  return patch;
-}
-async function offerRegistryScaffold(targetDir, businessRoot) {
-  const registryPath = join8(targetDir, businessRoot, "registry.json");
-  if (await fileExists(registryPath)) return;
-  const businessRootPath = join8(targetDir, businessRoot);
-  let ventureDirs;
-  try {
-    const entries = await readdir6(businessRootPath, { withFileTypes: true });
-    ventureDirs = entries.filter((e) => e.isDirectory() && e.name !== "_template").map((e) => e.name);
-  } catch {
-    return;
-  }
-  if (ventureDirs.length === 0) return;
-  console.log();
-  const scaffold = await confirm2({
-    message: `Found ${ventureDirs.length} folder${ventureDirs.length === 1 ? "" : "s"} under ${businessRoot}/ -- scaffold ${businessRoot}/registry.json from them?`,
-    default: true
-  });
-  if (!scaffold) return;
-  const ventures = {};
-  for (const slug of ventureDirs) {
-    const include = await confirm2({ message: `  Include "${slug}"?`, default: true });
-    if (!include) continue;
-    ventures[slug] = {
-      name: slug,
-      aliases: [],
-      status: "active",
-      visibility: "private",
-      ownership: "llc",
-      tracking: "none",
-      repos: []
-    };
-  }
-  if (Object.keys(ventures).length === 0) {
-    console.log("  No ventures selected -- registry not created.");
-    return;
-  }
-  const registry = {
-    _comment: "Hub-owned venture registry. Private. Never installed or modified by spell update. Seeded by the retrofit wizard -- review and enrich (aliases, ownership, tracking, clones) before relying on it.",
-    updated: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
-    ventures
-  };
-  await writeFile8(registryPath, JSON.stringify(registry, null, 2) + "\n", "utf-8");
-  console.log(
-    `  \u2713 Scaffolded ${businessRoot}/registry.json with ${Object.keys(ventures).length} venture(s).`
-  );
-}
-
 // src/modules/merge3.ts
 var CONFLICT_START = "<<<<<<< yours (edited)";
 var CONFLICT_MID = "=======";
@@ -4345,6 +4588,14 @@ async function missingTierWarning(scope, spellScope, homeDir) {
     ];
   }
 }
+function reportFlagPatch(flagPatch, before, after, dryRun) {
+  console.log(`
+${dryRun ? "[dry-run] Would record" : "Recorded"} from flags:`);
+  for (const line of describeFlagPatch(flagPatch)) console.log(`    ${line}`);
+  if (!dryRun && after.push_policy !== before.push_policy) {
+    for (const line of pushPolicyNotice(after.push_policy)) console.log(line);
+  }
+}
 function defaultScopePatch(options, manifest) {
   if (options.defaultScope === void 0) return void 0;
   if (manifest.default_spell_scope === options.defaultScope) return void 0;
@@ -4353,6 +4604,9 @@ function defaultScopePatch(options, manifest) {
 function migrateLegacyComponents(components) {
   const out = [];
   const seen = /* @__PURE__ */ new Set();
+  const inheritedFiles = [];
+  const inheritedHashes = {};
+  let carrier = null;
   for (const entry of components) {
     const replacements = LEGACY_COMPONENT_MIGRATIONS[entry.name];
     if (!replacements) {
@@ -4361,13 +4615,24 @@ function migrateLegacyComponents(components) {
       out.push(entry);
       continue;
     }
+    for (const file of entry.files) {
+      if (!inheritedFiles.includes(file)) inheritedFiles.push(file);
+      const hash = entry.fileHashes?.[file];
+      if (hash !== void 0 && inheritedHashes[file] === void 0) {
+        inheritedHashes[file] = hash;
+      }
+    }
     for (const name of replacements) {
+      carrier ??= name;
       if (seen.has(name)) continue;
       seen.add(name);
       out.push({ name, files: [], installedVersion: entry.installedVersion });
     }
   }
-  return out;
+  return {
+    components: out,
+    inherited: { files: inheritedFiles, fileHashes: inheritedHashes, carrier }
+  };
 }
 async function resolveOrphan(targetDir, file, recordedHash, prune) {
   try {
@@ -4392,6 +4657,19 @@ async function resolveOrphan(targetDir, file, recordedHash, prune) {
   console.log(`  Pruned orphaned file: ${file}`);
   return "pruned";
 }
+async function retainReportedOrphan(targetDir, file, recordedHash, into) {
+  try {
+    validateTargetPath(targetDir, file);
+  } catch {
+    return;
+  }
+  if (!await fileExists(join9(targetDir, file))) return;
+  if (!into.files.includes(file)) into.files.push(file);
+  if (recordedHash !== void 0) {
+    into.fileHashes ??= {};
+    into.fileHashes[file] = recordedHash;
+  }
+}
 function findReadoptedSpellComponents(components, scope = "repo", spellScope = "repo") {
   if (scope !== "repo" || spellScope !== "repo") return /* @__PURE__ */ new Set();
   return new Set(
@@ -4460,6 +4738,27 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     return;
   }
   const scope = resolvedScope.scope;
+  let flagPatch = {};
+  if (hasManifestFlags(options.manifestFlags)) {
+    if (scope !== "repo") {
+      console.error(
+        "\n  \u2717 The manifest-question flags describe a repository; the user tier has none of those fields.\n"
+      );
+      process.exit(1);
+      return;
+    }
+    try {
+      flagPatch = resolveManifestFlags(options.manifestFlags, manifest, join9(targetDir, ".arcane.json"));
+    } catch (err) {
+      if (!(err instanceof ManifestFlagError)) throw err;
+      console.error(`
+  \u2717 ${err.message}
+`);
+      process.exit(1);
+      return;
+    }
+  }
+  const answered = { ...manifest, ...flagPatch };
   const spellScope = effectiveSpellScope(manifest);
   const readopted = findReadoptedSpellComponents(manifest.components, scope, spellScope);
   const homeDir = dirname5(targetDir);
@@ -4500,6 +4799,10 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     const unmanaged = findUnmanagedTrackedFiles(manifest.components, scope, spellScope);
     if (missing.length === 0 && unmanaged.length === 0) {
       console.log("Already up to date.");
+      if (scope === "repo" && Object.keys(flagPatch).length > 0) {
+        if (!options.dryRun) await writeManifest(targetDir, answered);
+        reportFlagPatch(flagPatch, manifest, answered, options.dryRun);
+      }
       if (scope === "user") {
         const fanout = await syncUserTierFanout({
           ownedClients: SPELL_FANOUT_CLIENTS,
@@ -4532,6 +4835,10 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   }
   if (manifest.components.length === 0) {
     console.log("No components installed. Nothing to update.");
+    if (scope === "repo" && Object.keys(flagPatch).length > 0) {
+      if (!options.dryRun) await writeManifest(targetDir, answered);
+      reportFlagPatch(flagPatch, manifest, answered, options.dryRun);
+    }
     return;
   }
   let fileCount = 0;
@@ -4539,7 +4846,17 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   const conflictedFiles = [];
   const customizedShims = [];
   const orphanReport = [];
-  const componentsToUpdate = migrateLegacyComponents(manifest.components);
+  const orphanCandidates = [];
+  const { components: componentsToUpdate, inherited } = migrateLegacyComponents(manifest.components);
+  if (inherited.carrier !== null) {
+    for (const file of inherited.files) {
+      orphanCandidates.push({
+        owner: inherited.carrier,
+        file,
+        recordedHash: inherited.fileHashes[file]
+      });
+    }
+  }
   for (const installed of componentsToUpdate) {
     let component;
     try {
@@ -4658,24 +4975,11 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     }
     for (const file of installed.files) {
       if (updatedFiles.includes(file)) continue;
-      const recordedHash = installed.fileHashes?.[file];
-      const status = await resolveOrphan(
-        targetDir,
+      orphanCandidates.push({
+        owner: installed.name,
         file,
-        recordedHash,
-        Boolean(options.prune) && !options.dryRun
-      );
-      orphanReport.push({ file, status });
-      if (status === "reported") {
-        try {
-          validateTargetPath(targetDir, file);
-          if (await fileExists(join9(targetDir, file))) {
-            updatedFiles.push(file);
-            if (recordedHash !== void 0) fileHashes[file] = recordedHash;
-          }
-        } catch {
-        }
-      }
+        recordedHash: installed.fileHashes?.[file]
+      });
     }
     updatedComponents.push({
       ...installed,
@@ -4684,6 +4988,26 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       fileHashes
     });
   }
+  const claimed = new Set(updatedComponents.flatMap((c) => c.files));
+  const resolvedOrphans = /* @__PURE__ */ new Set();
+  for (const { owner, file, recordedHash } of orphanCandidates) {
+    if (claimed.has(file) || resolvedOrphans.has(file)) continue;
+    resolvedOrphans.add(file);
+    const status = await resolveOrphan(
+      targetDir,
+      file,
+      recordedHash,
+      Boolean(options.prune) && !options.dryRun
+    );
+    orphanReport.push({ file, status });
+    if (status !== "reported") continue;
+    let into = updatedComponents.find((c) => c.name === owner);
+    if (!into) {
+      into = { name: owner, files: [], installedVersion: packageVersion, fileHashes: {} };
+      updatedComponents.push(into);
+    }
+    await retainReportedOrphan(targetDir, file, recordedHash, into);
+  }
   const orphansToReport = orphanReport.filter((o) => o.status !== "not-found");
   if (orphansToReport.length > 0) {
     const verb = options.dryRun ? "[dry-run] Found" : "Found";
@@ -4736,7 +5060,8 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
       `
 [dry-run] Would update ${fileCount} files.`
     );
-    const applicableRetrofits = scope === "repo" ? MANIFEST_RETROFITS.filter((r) => r.needsRetrofit(manifest)) : [];
+    if (Object.keys(flagPatch).length > 0) reportFlagPatch(flagPatch, manifest, answered, true);
+    const applicableRetrofits = scope === "repo" ? MANIFEST_RETROFITS.filter((r) => r.needsRetrofit(answered)) : [];
     if (applicableRetrofits.length > 0) {
       console.log(
         `[dry-run] Would ask ${applicableRetrofits.length} manifest retrofit question${applicableRetrofits.length === 1 ? "" : "s"}: ${applicableRetrofits.map((r) => r.field).join(", ")}.`
@@ -4745,19 +5070,21 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
     return;
   }
   const interactive = Boolean(process.stdin.isTTY) && scope === "repo";
-  const retrofitPatch = interactive ? await runManifestRetrofits(manifest) : {};
+  const retrofitPatch = interactive ? await runManifestRetrofits(answered, targetDir) : {};
   if (!interactive && scope === "repo") {
-    const pending = MANIFEST_RETROFITS.filter((r) => r.needsRetrofit(manifest));
+    const pending = MANIFEST_RETROFITS.filter((r) => r.needsRetrofit(answered));
     if (pending.length > 0) {
       console.log(
-        `  ! Skipped ${pending.length} manifest question${pending.length === 1 ? "" : "s"} (${pending.map((r) => r.field).join(", ")}) \u2014 no interactive terminal. Run \`spell update\` from a terminal to answer.`
+        `  ! Skipped ${pending.length} manifest question${pending.length === 1 ? "" : "s"} (${pending.map((r) => r.field).join(", ")}) \u2014 no interactive terminal. Run \`spell update\` from a terminal, or answer by flags:`
       );
+      for (const line of manifestFlagLine(answered) ?? []) console.log(`      ${line}`);
     }
   }
   const updated = {
     ...manifest,
     version: packageVersion,
     components: updatedComponents,
+    ...flagPatch,
     ...retrofitPatch,
     ...fanoutRecord !== void 0 ? { fanout: fanoutRecord } : {},
     ...defaultScopePatch(options, manifest)
@@ -4767,6 +5094,11 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
     `
 \u2713 Updated ${fileCount} files.`
   );
+  if (Object.keys(flagPatch).length > 0) {
+    reportFlagPatch(flagPatch, manifest, updated, false);
+  } else if (updated.push_policy !== manifest.push_policy) {
+    for (const line of pushPolicyNotice(updated.push_policy)) console.log(line);
+  }
   if (conflictedFiles.length > 0) {
     console.log(
       `
@@ -4776,7 +5108,13 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
     );
   }
   if (scope === "repo" && manifest.role !== "hub" && updated.role === "hub") {
-    await offerRegistryScaffold(targetDir, updated.business_root ?? "ventures");
+    if (process.stdin.isTTY) {
+      await offerRegistryScaffold(targetDir, updated.business_root ?? "ventures");
+    } else {
+      console.log(
+        `  This repository is now a hub. Run \`spell update\` from a terminal to scaffold ${updated.business_root ?? "ventures"}/registry.json from existing venture folders.`
+      );
+    }
   }
 }
 
@@ -5187,10 +5525,8 @@ async function uninstallUserTier(options, storeRoot, manifest) {
 }
 
 // src/commands/doctor.ts
-import { access as access4, readdir as readdir8, readFile as readFile10, mkdir as mkdir7, copyFile as fsCopyFile } from "fs/promises";
-import { join as join13, dirname as dirname9 } from "path";
-import { execFile as execFile3 } from "child_process";
-import { promisify as promisify2 } from "util";
+import { access as access4, readdir as readdir9, readFile as readFile11, mkdir as mkdir7, copyFile as fsCopyFile } from "fs/promises";
+import { join as join14, dirname as dirname9 } from "path";
 
 // src/config/incidents.ts
 var INCIDENT_QUEUE = [
@@ -5331,10 +5667,33 @@ async function scanRepository(repoRoot, rules, extensions, excludePrefixes = [])
   return findings;
 }
 
-// src/modules/platform-policy.ts
+// src/modules/exec.ts
 import { execFile as execFile2 } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile2);
+var EXTERNAL_CLI_TIMEOUT_MS = 1e4;
+function execFileWithTimeout(file, args, timeoutMs) {
+  return new Promise((resolve5, reject) => {
+    const child = execFile2(
+      file,
+      args,
+      {
+        timeout: timeoutMs,
+        killSignal: "SIGTERM",
+        windowsHide: true,
+        encoding: "utf8"
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve5({ stdout, stderr });
+      }
+    );
+    child.stdin?.end();
+  });
+}
+
+// src/modules/platform-policy.ts
 var SANCTIONED_MERGE_METHODS = ["merge", "rebase"];
 function compareToLadder(effective, declaredButBlocked, interactionNote) {
   const disallowedButPermitted = effective.filter(
@@ -5401,17 +5760,19 @@ function evaluateGitHubMergePolicy(rulesets) {
 }
 async function fetchGitHubRulesets(owner, repo) {
   try {
-    const { stdout: listOut } = await execFileAsync("gh", [
-      "api",
-      `repos/${owner}/${repo}/rulesets`
-    ]);
+    const { stdout: listOut } = await execFileWithTimeout(
+      "gh",
+      ["api", `repos/${owner}/${repo}/rulesets`],
+      EXTERNAL_CLI_TIMEOUT_MS
+    );
     const summaries = JSON.parse(listOut);
     const detailed = await Promise.all(
       summaries.map(async (s) => {
-        const { stdout } = await execFileAsync("gh", [
-          "api",
-          `repos/${owner}/${repo}/rulesets/${s.id}`
-        ]);
+        const { stdout } = await execFileWithTimeout(
+          "gh",
+          ["api", `repos/${owner}/${repo}/rulesets/${s.id}`],
+          EXTERNAL_CLI_TIMEOUT_MS
+        );
         return JSON.parse(stdout);
       })
     );
@@ -5443,7 +5804,7 @@ function evaluateAdoMergePolicy(policies) {
 async function fetchAdoMergeTypePolicies(org, project, repoName, branch) {
   try {
     const orgUrl = `https://dev.azure.com/${org}`;
-    const { stdout: repoOut } = await execFileAsync("az", [
+    const { stdout: repoOut } = await execFileWithTimeout("az", [
       "repos",
       "show",
       "--repository",
@@ -5456,10 +5817,10 @@ async function fetchAdoMergeTypePolicies(org, project, repoName, branch) {
       "id",
       "--output",
       "tsv"
-    ]);
+    ], EXTERNAL_CLI_TIMEOUT_MS);
     const repositoryId = repoOut.trim();
     if (!repositoryId) return null;
-    const { stdout } = await execFileAsync("az", [
+    const { stdout } = await execFileWithTimeout("az", [
       "repos",
       "policy",
       "list",
@@ -5473,7 +5834,7 @@ async function fetchAdoMergeTypePolicies(org, project, repoName, branch) {
       project,
       "--output",
       "json"
-    ]);
+    ], EXTERNAL_CLI_TIMEOUT_MS);
     return JSON.parse(stdout);
   } catch {
     return null;
@@ -5500,8 +5861,134 @@ function parseAdoRemote(url) {
   return null;
 }
 
+// src/modules/placeholders.ts
+import { readdir as readdir8, readFile as readFile10 } from "fs/promises";
+import { join as join13 } from "path";
+var PLACEHOLDER_STANDARD_FILE = "spell-authoring-standards.md";
+var RUNTIME_PLACEHOLDERS_START = "<!-- runtime-placeholders:start -->";
+var RUNTIME_PLACEHOLDERS_END = "<!-- runtime-placeholders:end -->";
+var PLACEHOLDER_PATTERN = /(?<!\$)\{([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*)\}/g;
+var FRONTMATTER_PATTERN2 = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+function parseFrontmatterStatus(content) {
+  const block = FRONTMATTER_PATTERN2.exec(content);
+  if (!block) return null;
+  const status = /^status:[ \t]*["']?([^"'\s#]+)/m.exec(block[1]);
+  return status ? status[1] : null;
+}
+function stripFrontmatter(content) {
+  const block = FRONTMATTER_PATTERN2.exec(content);
+  return block ? content.slice(block[0].length) : content;
+}
+function stripFencedCode(text) {
+  const kept = [];
+  let fence = null;
+  for (const line of text.split(/\r?\n/)) {
+    if (fence) {
+      const close = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line);
+      if (close && close[1][0] === fence.char && close[1].length >= fence.length) fence = null;
+      kept.push("");
+      continue;
+    }
+    const open = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    if (open && !(open[1][0] === "`" && line.slice(open[0].length).includes("`"))) {
+      fence = { char: open[1][0], length: open[1].length };
+      kept.push("");
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.join("\n");
+}
+function stripInlineCode(text) {
+  return text.split(/\n[ \t]*\n/).map((paragraph) => {
+    let out = "";
+    let i = 0;
+    while (i < paragraph.length) {
+      if (paragraph[i] !== "`") {
+        out += paragraph[i];
+        i += 1;
+        continue;
+      }
+      let runEnd = i;
+      while (paragraph[runEnd] === "`") runEnd += 1;
+      const run = runEnd - i;
+      let close = -1;
+      let j = runEnd;
+      while (j < paragraph.length) {
+        if (paragraph[j] !== "`") {
+          j += 1;
+          continue;
+        }
+        let k = j;
+        while (paragraph[k] === "`") k += 1;
+        if (k - j === run) {
+          close = j;
+          break;
+        }
+        j = k;
+      }
+      if (close === -1) {
+        out += paragraph.slice(i, runEnd);
+        i = runEnd;
+      } else {
+        out += " ";
+        i = close + run;
+      }
+    }
+    return out;
+  }).join("\n\n");
+}
+function findPlaceholderTokens(content) {
+  const prose = stripInlineCode(stripFencedCode(stripFrontmatter(content)));
+  const seen = /* @__PURE__ */ new Set();
+  for (const match of prose.matchAll(PLACEHOLDER_PATTERN)) seen.add(`{${match[1]}}`);
+  return [...seen];
+}
+function parseRuntimePlaceholders(standardContent) {
+  const start = standardContent.indexOf(RUNTIME_PLACEHOLDERS_START);
+  const end = standardContent.indexOf(RUNTIME_PLACEHOLDERS_END);
+  if (start === -1 || end === -1 || end < start) return null;
+  const region = standardContent.slice(start + RUNTIME_PLACEHOLDERS_START.length, end);
+  const tokens = /* @__PURE__ */ new Set();
+  for (const match of region.matchAll(/^[ \t]*[-*][ \t]+`(\{[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*\})`/gm)) {
+    tokens.add(match[1]);
+  }
+  return tokens;
+}
+async function scanGovernancePlaceholders(governanceDir) {
+  let standard;
+  try {
+    standard = await readFile10(join13(governanceDir, PLACEHOLDER_STANDARD_FILE), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { status: "skipped", reason: `${PLACEHOLDER_STANDARD_FILE} is not installed` };
+    }
+    throw err;
+  }
+  const runtimeTokens = parseRuntimePlaceholders(standard);
+  if (!runtimeTokens) {
+    return {
+      status: "skipped",
+      reason: `${PLACEHOLDER_STANDARD_FILE} has no runtime-placeholders list (an older version?)`
+    };
+  }
+  const files = (await readdir8(governanceDir, { withFileTypes: true })).filter((entry) => entry.isFile() && entry.name.endsWith(".md")).map((entry) => entry.name).sort();
+  const activeDocs = [];
+  const templateDocs = [];
+  const findings = [];
+  for (const file of files) {
+    const content = await readFile10(join13(governanceDir, file), "utf8");
+    const status = parseFrontmatterStatus(content);
+    if (status === "template") templateDocs.push(file);
+    if (status !== "active") continue;
+    activeDocs.push(file);
+    const unknown = findPlaceholderTokens(content).filter((token) => !runtimeTokens.has(token));
+    if (unknown.length > 0) findings.push({ file, tokens: unknown });
+  }
+  return { status: "scanned", runtimeTokens, activeDocs, templateDocs, findings };
+}
+
 // src/commands/doctor.ts
-var execFileAsync2 = promisify2(execFile3);
 function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -5518,52 +6005,45 @@ async function checkNodeVersion() {
     message: `${raw} \u2014 Node.js 18 or later is required`
   };
 }
-async function checkVSCodeExtension(id, label) {
+async function checkVSCodeExtension(id, label, homeDir = resolveHomeDir()) {
   const name = `VS Code extension: ${label}`;
-  const home = process.env["HOME"] ?? "";
-  const extDirs = [
-    join13(home, ".vscode", "extensions"),
-    join13(home, ".vscode-insiders", "extensions")
+  const flavours = [
+    { dir: join14(homeDir, ".vscode", "extensions"), bin: "code" },
+    { dir: join14(homeDir, ".vscode-insiders", "extensions"), bin: "code-insiders" }
   ];
-  for (const dir of extDirs) {
+  let installBin = null;
+  for (const flavour of flavours) {
+    let entries;
     try {
-      const { readdir: readdir11 } = await import("fs/promises");
-      const entries = await readdir11(dir);
-      const prefix = id.toLowerCase() + "-";
-      const found = entries.some(
-        (e) => e.toLowerCase() === id.toLowerCase() || e.toLowerCase().startsWith(prefix)
-      );
-      if (found) {
-        return { name, passed: true, message: `${id} is installed` };
-      }
+      entries = await readdir9(flavour.dir);
     } catch {
+      continue;
     }
-  }
-  let installBin = "code";
-  for (const bin of ["code", "code-insiders"]) {
-    try {
-      await execFileAsync2(bin, ["--version"]);
-      installBin = bin;
-      break;
-    } catch {
+    installBin ??= flavour.bin;
+    const prefix = id.toLowerCase() + "-";
+    const found = entries.some(
+      (e) => e.toLowerCase() === id.toLowerCase() || e.toLowerCase().startsWith(prefix)
+    );
+    if (found) {
+      return { name, passed: true, message: `${id} is installed` };
     }
   }
   return {
     name,
     passed: false,
-    message: `${id} not found. Install via: ${installBin} --install-extension ${id}`,
+    message: `${id} not found. Install via: ${installBin ?? "code"} --install-extension ${id}`,
     blocking: false
   };
 }
 async function checkArcaneManifest(targetDir) {
   const name = "Arcane manifest (.arcane.json)";
-  const manifestPath2 = join13(targetDir, ".arcane.json");
+  const manifestPath2 = join14(targetDir, ".arcane.json");
   try {
     await access4(manifestPath2);
   } catch {
-    const selfHostedManifestPath = join13(targetDir, "src", "assets", ".arcane.json");
+    const selfHostedManifestPath = join14(targetDir, "src", "assets", ".arcane.json");
     try {
-      const raw = await readFile10(selfHostedManifestPath, "utf8");
+      const raw = await readFile11(selfHostedManifestPath, "utf8");
       const manifest = JSON.parse(raw);
       if (isRecord3(manifest) && manifest["selfHosted"] === true && manifest["tracking_mode"] === "internal") {
         return {
@@ -5582,7 +6062,7 @@ async function checkArcaneManifest(targetDir) {
     };
   }
   try {
-    const raw = await readFile10(manifestPath2, "utf8");
+    const raw = await readFile11(manifestPath2, "utf8");
     const manifest = JSON.parse(raw);
     if (!isRecord3(manifest) || typeof manifest["version"] !== "string" || !manifest["version"] || !Array.isArray(manifest["components"])) {
       return {
@@ -5667,7 +6147,7 @@ async function checkSessionContinuity(targetDir) {
   const results = [];
   for (const file of SESSION_CONTINUITY_FILES) {
     const name = `Session file: ${file}`;
-    const filePath = join13(targetDir, file);
+    const filePath = join14(targetDir, file);
     try {
       await access4(filePath);
       results.push({ name, passed: true, message: "present" });
@@ -5685,11 +6165,11 @@ async function checkSessionContinuity(targetDir) {
 async function fixSessionContinuity(targetDir, assetsDir) {
   const created = [];
   for (const file of SESSION_CONTINUITY_FILES) {
-    const destPath = join13(targetDir, file);
+    const destPath = join14(targetDir, file);
     try {
       await access4(destPath);
     } catch {
-      const srcPath = join13(assetsDir, file);
+      const srcPath = join14(assetsDir, file);
       await mkdir7(dirname9(destPath), { recursive: true });
       await fsCopyFile(srcPath, destPath);
       created.push(file);
@@ -5809,15 +6289,48 @@ async function checkPushPolicy(targetDir) {
     name,
     passed: false,
     blocking: false,
-    message: `declared "blocked" but not enforced \u2014 ${missing.join("; ")}. The manifest claims a protection this repository does not have.`
+    // ARC-049 decision 3: name the command that closes the gap.
+    message: `declared "blocked" but not enforced \u2014 ${missing.join("; ")}. The manifest claims a protection this repository does not have. Run \`spell block-push\` to install the controls.`
+  };
+}
+async function checkGovernancePlaceholders(targetDir) {
+  const name = "Governance placeholders (ARC-051)";
+  let scan;
+  try {
+    scan = await scanGovernancePlaceholders(join14(targetDir, ".arcane", "governance"));
+  } catch (err) {
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: `could not scan .arcane/governance (${err instanceof Error ? err.message : String(err)})`
+    };
+  }
+  if (scan.status === "skipped") {
+    return { name, passed: true, blocking: false, skipped: true, message: `skipped \u2014 ${scan.reason}` };
+  }
+  if (scan.findings.length === 0) {
+    return {
+      name,
+      passed: true,
+      blocking: false,
+      message: `${scan.activeDocs.length} active doc(s) scanned, no unknown placeholders`
+    };
+  }
+  const listed = scan.findings.map(({ file, tokens }) => `.arcane/governance/${file}: ${tokens.join(", ")}`);
+  return {
+    name,
+    passed: false,
+    blocking: false,
+    message: `unknown placeholder(s) in status: active doc(s) \u2014 ${listed.join("; ")}. Fill each one in; or, if an agent resolves it at use time, add it to the runtime-placeholders list in .arcane/governance/${PLACEHOLDER_STANDARD_FILE}; or, if the document is meant to be filled in by hand, mark it \`status: template\`.`
   };
 }
 async function checkMcpConfig(targetDir) {
   const name = "MCP config (per-server timeout, I12)";
-  const filePath = join13(targetDir, ".mcp.json");
+  const filePath = join14(targetDir, ".mcp.json");
   let raw;
   try {
-    raw = await readFile10(filePath, "utf8");
+    raw = await readFile11(filePath, "utf8");
   } catch {
     return { name, passed: true, blocking: false, message: "no .mcp.json \u2014 nothing to check" };
   }
@@ -5870,10 +6383,10 @@ function isDelegationsFile(value) {
 }
 async function checkDelegations(targetDir) {
   const name = "Standing delegations (T13)";
-  const filePath = join13(targetDir, ".arcane", "delegations.json");
+  const filePath = join14(targetDir, ".arcane", "delegations.json");
   let raw;
   try {
-    raw = await readFile10(filePath, "utf8");
+    raw = await readFile11(filePath, "utf8");
   } catch {
     return { name, passed: true, blocking: false, message: "no delegations recorded" };
   }
@@ -5983,7 +6496,7 @@ async function checkSpellScope(targetDir, homeDir = resolveHomeDir()) {
   let probed = false;
   const probe = "spell-status.md";
   try {
-    const entries = await readdir8(join13(storeRoot, USER_TIER_SPELLS_DIR));
+    const entries = await readdir9(join14(storeRoot, USER_TIER_SPELLS_DIR));
     const spells = entries.filter((e) => e.startsWith("spell-") && e.endsWith(".md"));
     spellCount = spells.length;
     probed = spells.includes(probe);
@@ -6037,7 +6550,7 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
   }
   const results = await Promise.all([
     checkNodeVersion(),
-    checkVSCodeExtension("GitHub.copilot-chat", "GitHub Copilot (Chat)"),
+    checkVSCodeExtension("GitHub.copilot-chat", "GitHub Copilot (Chat)", resolveHomeDir()),
     checkArcaneManifest(targetDir),
     Promise.resolve(checkIncidentReleaseGate()),
     checkPullRebase(targetDir),
@@ -6046,16 +6559,18 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     checkDelegations(targetDir),
     checkMcpConfig(targetDir),
     checkUserTier(resolveHomeDir(), options.packageVersion),
-    checkSpellScope(targetDir)
+    checkSpellScope(targetDir),
+    checkGovernancePlaceholders(targetDir)
   ]);
   const sessionResults = await checkSessionContinuity(targetDir);
   results.push(...sessionResults);
   let allPassed = true;
   for (const result of results) {
-    const icon = result.passed ? "\u2713" : result.blocking === false ? "\u26A0" : "\u2717";
-    const label = result.passed ? "pass" : result.blocking === false ? "warn" : "FAIL";
+    const skipped = result.passed && result.skipped === true;
+    const icon = skipped ? "\u2013" : result.passed ? "\u2713" : result.blocking === false ? "\u26A0" : "\u2717";
+    const label = skipped ? "skip" : result.passed ? "pass" : result.blocking === false ? "warn" : "FAIL";
     console.log(`  ${icon} [${label}] ${result.name}`);
-    if (!result.passed) {
+    if (!result.passed || skipped) {
       console.log(`         ${result.message}`);
     }
     if (!result.passed && result.blocking !== false) {
@@ -6067,40 +6582,38 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     console.log("  All checks passed. Your environment is ready.\n");
   } else {
     console.log("  One or more checks failed. Fix the issues above before proceeding.\n");
-    const hasMissingSession = sessionResults.some((r) => !r.passed);
-    if (options.fix && hasMissingSession && assetsDir) {
-      console.log("  \u{1F527} Fixing missing session continuity files...\n");
-      const created = await fixSessionContinuity(targetDir, assetsDir);
-      if (created.length > 0) {
-        for (const file of created) {
-          console.log(`    \u2713 Created: ${file}`);
-        }
-        console.log(`
+    process.exitCode = 1;
+  }
+  const hasMissingSession = sessionResults.some((r) => !r.passed);
+  if (options.fix && hasMissingSession && assetsDir) {
+    console.log("  \u{1F527} Fixing missing session continuity files...\n");
+    const created = await fixSessionContinuity(targetDir, assetsDir);
+    if (created.length > 0) {
+      for (const file of created) {
+        console.log(`    \u2713 Created: ${file}`);
+      }
+      console.log(`
   ${created.length} file(s) created. Repo is now close-session-ready.
 `);
-      } else {
-        console.log("    No files needed creation (all present).\n");
-      }
-    } else if (hasMissingSession && !options.fix) {
-      console.log("  \u{1F4A1} Run `spell doctor --fix` to create missing session files.\n");
-    }
-    if (!allPassed) {
-      process.exitCode = 1;
+    } else {
+      console.log("    No files needed creation (all present).\n");
     }
+  } else if (hasMissingSession && !options.fix) {
+    console.log("  \u{1F4A1} Run `spell doctor --fix` to create missing session files.\n");
   }
 }
 
 // src/commands/ward.ts
-import { readFile as readFile12 } from "fs/promises";
+import { readFile as readFile13 } from "fs/promises";
 
 // src/modules/ward.ts
-import { readdir as readdir9, readFile as readFile11 } from "fs/promises";
-import { join as join14, relative as relative2 } from "path";
+import { readdir as readdir10, readFile as readFile12 } from "fs/promises";
+import { join as join15, relative as relative2 } from "path";
 async function scanFileAllRules(absolutePath, displayPath, rules) {
   const findings = [];
   let content;
   try {
-    content = await readFile11(absolutePath, "utf8");
+    content = await readFile12(absolutePath, "utf8");
   } catch {
     return findings;
   }
@@ -6153,12 +6666,12 @@ async function scanFilenames(root, rules, repoRoot = root) {
   const findings = [];
   let entries;
   try {
-    entries = await readdir9(root, { withFileTypes: true });
+    entries = await readdir10(root, { withFileTypes: true });
   } catch {
     return findings;
   }
   for (const entry of entries) {
-    const absolutePath = join14(root, entry.name);
+    const absolutePath = join15(root, entry.name);
     if (entry.isDirectory()) {
       if (SKIP_DIRECTORIES.has(entry.name)) continue;
       findings.push(...await scanFilenames(absolutePath, rules, repoRoot));
@@ -6195,7 +6708,7 @@ async function runWard(repoRoot, options = {}) {
     const findings2 = await scanFileAllRules(absolutePath, displayPath, allRules);
     if (findings2.length > 0) {
       try {
-        fileLines.set(displayPath, (await readFile11(absolutePath, "utf8")).split("\n"));
+        fileLines.set(displayPath, (await readFile12(absolutePath, "utf8")).split("\n"));
       } catch {
       }
     }
@@ -6223,7 +6736,7 @@ function parseTermsFileContent(raw) {
 }
 async function readTermsFile(filePath) {
   try {
-    return parseTermsFileContent(await readFile12(filePath, "utf8"));
+    return parseTermsFileContent(await readFile13(filePath, "utf8"));
   } catch (error) {
     console.warn(
       `\u26A0 arcane: could not read --terms-file "${filePath}": ${error.message}`
@@ -6370,17 +6883,80 @@ Name did not match ("${typed.trim()}" \u2260 "${repoName}"). Nothing changed.`);
   );
 }
 
+// src/commands/block-push.ts
+async function runBlockPush(targetDir) {
+  let manifest;
+  try {
+    manifest = await readManifest(targetDir);
+  } catch (err) {
+    if (err instanceof ManifestNotFoundError) {
+      console.error('Not initialized. Run "spell init" first.');
+      process.exit(1);
+      return;
+    }
+    throw err;
+  }
+  if (manifest.scope === "user") {
+    console.error(
+      "spell block-push applies to a repository, not the user tier: push_policy describes a repository."
+    );
+    process.exit(1);
+    return;
+  }
+  if ((await inspectGitRepository(targetDir)).status === "not-repository") {
+    console.error("spell block-push needs a Git repository: there is nothing here to block.");
+    process.exit(1);
+    return;
+  }
+  const recorded = manifest.push_policy ?? "open";
+  const alreadyEnforced = recorded === "blocked" && await isHookEnforced(targetDir) && (await undisabledRemotes(targetDir)).length === 0;
+  if (alreadyEnforced) {
+    printSuccess("Push is already blocked and enforced here. Nothing changed.");
+    if ((await listRemotes(targetDir)).length === 0) {
+      printWarning(
+        "No remote is configured, so only the pre-push hook is active. Re-run `spell block-push` after adding a remote to disable its push URL too."
+      );
+    }
+    printInfo("Run `spell unblock-push` from a terminal to undo this.");
+    return;
+  }
+  const outcome = await applyBlockedPushControls(targetDir, {
+    stopOnHookRefusal: true,
+    emit: (m) => m.level === "warning" ? printWarning(m.text) : printInfo(m.text)
+  });
+  const failedRemotes = outcome.urls.filter((u) => u.status === "failed");
+  if (!hookInForce(outcome.hook) || failedRemotes.length > 0) {
+    printWarning(
+      outcome.stoppedAtHook ? "Nothing was changed. Resolve the refusal above and re-run `spell block-push`." : "Push is NOT fully blocked: the remotes named above can still be pushed to. Fix them and re-run `spell block-push`."
+    );
+    if (recorded !== "blocked") {
+      printInfo(
+        `The manifest still records push_policy: "${recorded}" \u2014 it is not changed to "blocked" until both controls are in force.`
+      );
+    }
+    process.exit(1);
+    return;
+  }
+  if (recorded !== "blocked") {
+    await writeManifest(targetDir, { ...manifest, push_policy: "blocked" });
+    printSuccess(`Push blocked. Recorded push_policy: "blocked" (was "${recorded}") in .arcane.json.`);
+    printInfo("Commit that change so the repository's posture stays visible to everyone.");
+  } else {
+    printSuccess('Push blocked. The manifest already recorded push_policy: "blocked"; it is now enforced.');
+  }
+}
+
 // src/commands/report.ts
 import { access as access5 } from "fs/promises";
-import { join as join17 } from "path";
+import { join as join18 } from "path";
 
 // src/modules/show-report/generate.ts
-import { mkdir as mkdir8, readdir as readdir10, readFile as readFile14, writeFile as writeFile11 } from "fs/promises";
-import { basename as basename3, dirname as dirname10, isAbsolute, join as join16, relative as relative3, resolve as resolve4 } from "path";
+import { mkdir as mkdir8, readdir as readdir11, readFile as readFile15, writeFile as writeFile11 } from "fs/promises";
+import { basename as basename3, dirname as dirname10, isAbsolute, join as join17, relative as relative3, resolve as resolve4 } from "path";
 
 // src/modules/show-report/model.ts
-import { readFile as readFile13 } from "fs/promises";
-import { join as join15 } from "path";
+import { readFile as readFile14 } from "fs/promises";
+import { join as join16 } from "path";
 
 // src/modules/show-report/plan-parser.ts
 function parseFrontmatter(content) {
@@ -6650,7 +7226,7 @@ async function getCast(cwd, fromRef, toRef, generatedOutputs = []) {
 // src/modules/show-report/model.ts
 async function readOptional(path4) {
   try {
-    return await readFile13(path4, "utf8");
+    return await readFile14(path4, "utf8");
   } catch {
     return null;
   }
@@ -6746,13 +7322,13 @@ function buildCorrections(ledgerRows, programName) {
   };
 }
 async function buildShowReportModel(options) {
-  const planAbsPath = join15(options.rootDir, options.planRelPath);
-  const queueAbsPath = join15(options.rootDir, options.queueRelPath);
+  const planAbsPath = join16(options.rootDir, options.planRelPath);
+  const queueAbsPath = join16(options.rootDir, options.queueRelPath);
   const ledgerRelPath = "docs/verification-ledger.md";
-  const ledgerAbsPath = join15(options.rootDir, ledgerRelPath);
-  const decisionsAbsPath = join15(options.rootDir, "DECISIONS.md");
+  const ledgerAbsPath = join16(options.rootDir, ledgerRelPath);
+  const decisionsAbsPath = join16(options.rootDir, "DECISIONS.md");
   const [planContent, queueContent, ledgerContent, decisionsContent] = await Promise.all([
-    readFile13(planAbsPath, "utf8"),
+    readFile14(planAbsPath, "utf8"),
     readOptional(queueAbsPath),
     readOptional(ledgerAbsPath),
     readOptional(decisionsAbsPath)
@@ -6921,7 +7497,7 @@ function toPosix(path4) {
 async function programFromPlan(rootDir, slug, planRelPath) {
   let planContent;
   try {
-    planContent = await readFile14(join16(rootDir, planRelPath), "utf8");
+    planContent = await readFile15(join17(rootDir, planRelPath), "utf8");
   } catch {
     return { skipped: { slug, reason: `no PLAN.md at ${planRelPath}` } };
   }
@@ -6933,16 +7509,16 @@ async function programFromPlan(rootDir, slug, planRelPath) {
     program: {
       slug,
       planRelPath,
-      queueRelPath: toPosix(join16(dirname10(planRelPath), "OPERATOR-QUEUE.md")),
+      queueRelPath: toPosix(join17(dirname10(planRelPath), "OPERATOR-QUEUE.md")),
       ledgerProgramName: programNameFromTitle(frontmatter.title ?? slug)
     }
   };
 }
 async function discoverPrograms(rootDir) {
-  const plansDir = join16(rootDir, "docs", "plans");
+  const plansDir = join17(rootDir, "docs", "plans");
   let entries;
   try {
-    entries = (await readdir10(plansDir, { withFileTypes: true })).filter((e) => e.isDirectory());
+    entries = (await readdir11(plansDir, { withFileTypes: true })).filter((e) => e.isDirectory());
   } catch (error) {
     if (error.code === "ENOENT") return { programs: [], skipped: [] };
     throw error;
@@ -6966,14 +7542,14 @@ function normalizeLineEndings2(content) {
 }
 async function readOptionalFile(path4) {
   try {
-    return await readFile14(path4, "utf8");
+    return await readFile15(path4, "utf8");
   } catch (error) {
     if (error.code === "ENOENT") return null;
     throw error;
   }
 }
 async function generateReport(rootDir, program2, templateHtml) {
-  const planContent = await readFile14(join16(rootDir, program2.planRelPath), "utf8");
+  const planContent = await readFile15(join17(rootDir, program2.planRelPath), "utf8");
   const frontmatter = parseFrontmatter(planContent);
   const model = await buildShowReportModel({
     rootDir,
@@ -6991,7 +7567,7 @@ async function generateReport(rootDir, program2, templateHtml) {
   };
 }
 async function runReportGeneration(options) {
-  const templateHtml = await readFile14(options.templatePath, "utf8");
+  const templateHtml = await readFile15(options.templatePath, "utf8");
   const drifted = [];
   const repaired = [];
   const unwritten = [];
@@ -7006,12 +7582,12 @@ async function runReportGeneration(options) {
       [`${outRel}/show-report.html`, generated.html]
     ];
     for (const [relPath, expected] of outputs) {
-      const actual = await readOptionalFile(join16(options.rootDir, relPath));
+      const actual = await readOptionalFile(join17(options.rootDir, relPath));
       if (actual === null || normalizeLineEndings2(actual) !== normalizeLineEndings2(expected)) {
         drifted.push(`${relPath} does not match a regeneration from its sources.`);
         if (options.mode === "write") {
           await mkdir8(outAbs, { recursive: true });
-          await writeFile11(join16(options.rootDir, relPath), expected, "utf8");
+          await writeFile11(join17(options.rootDir, relPath), expected, "utf8");
           repaired.push(relPath);
         }
       }
@@ -7022,7 +7598,7 @@ async function runReportGeneration(options) {
 
 // src/commands/report.ts
 async function runReport(targetDir, options = {}, assetsDir) {
-  const templatePath = join17(assetsDir, "report", "show-report.template.html");
+  const templatePath = join18(assetsDir, "report", "show-report.template.html");
   try {
     await access5(templatePath);
   } catch {
@@ -7085,13 +7661,29 @@ async function runReport(targetDir, options = {}, assetsDir) {
 import { realpathSync } from "fs";
 var require3 = createRequire2(import.meta.url);
 var pkg = require3("../package.json");
-var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join18(dirname11(fileURLToPath(import.meta.url)), "assets");
+var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join19(dirname11(fileURLToPath(import.meta.url)), "assets");
 var program = new Command();
 var USER_FLAG_DESCRIPTION = "Operate on the per-user tier at ~/.arcane \u2014 spells shared by every repository on this machine, fanned out to ~/.agents/skills (Codex, Copilot) and ~/.claude/commands (Claude Code)";
 var USER_TIER_AGENTS_DESCRIPTION = "Operate on the per-user tier at ~/.arcane \u2014 one agent roster shared by every repository on this machine, rendered to ~/.copilot/agents (VS Code agent modes)";
 function targetDirFor(opts) {
   return opts.user ? userTierRoot() : process.cwd();
 }
+function withManifestFlags(command) {
+  return command.option("--role <role>", "Answer the hub question: hub | consumer").option("--tracking-mode <mode>", "Answer the tracking question: internal | external (external needs --external-provider)").option("--external-provider <provider>", "With --tracking-mode external: ado | github | jira | other").option("--content-sensitivity <level>", "Answer the content question: standard | sensitive").option(
+    "--push-policy <policy>",
+    "Answer the push question: open | guarded | blocked. Can tighten a recorded policy, never loosen it (use `spell unblock-push`)"
+  ).option("--subject-root <path>", "Answer the subject question with a directory (docs profile)");
+}
+function manifestFlagsFrom(opts) {
+  return {
+    role: opts.role,
+    trackingMode: opts.trackingMode,
+    externalProvider: opts.externalProvider,
+    contentSensitivity: opts.contentSensitivity,
+    pushPolicy: opts.pushPolicy,
+    subjectRoot: opts.subjectRoot
+  };
+}
 program.name("spell").description("Arcane framework CLI \u2014 scaffold and manage governance files").version(pkg.version).action(async () => {
   if (program.args.length > 0) {
     const [attempted] = program.args;
@@ -7111,14 +7703,17 @@ program.name("spell").description("Arcane framework CLI \u2014 scaffold and mana
   await printWelcome(pkg.version, process.cwd());
   program.outputHelp();
 });
-program.command("init").description("Scaffold Arcane framework files into the current repository").option("--profile <profile>", "Profile: full | lite | methodology | docs | governance-only").option("--force", "Overwrite existing files without error").option("--dry-run", "Preview what would be installed without making changes").option("--user", USER_FLAG_DESCRIPTION).action(
+withManifestFlags(
+  program.command("init").description("Scaffold Arcane framework files into the current repository").option("--profile <profile>", "Profile: full | lite | methodology | docs | governance-only").option("--force", "Overwrite existing files without error").option("--dry-run", "Preview what would be installed without making changes").option("--user", USER_FLAG_DESCRIPTION)
+).action(
   async (opts) => {
     await runInit(
       {
         profile: opts.profile,
         force: opts.force,
         dryRun: opts.dryRun,
-        user: opts.user
+        user: opts.user,
+        manifestFlags: manifestFlagsFrom(opts)
       },
       targetDirFor(opts),
       ASSETS_DIR,
@@ -7137,12 +7732,14 @@ program.command("add <component>").description("Add a component to an existing A
     );
   }
 );
-program.command("update").description("Update installed components to the current package version").option("--dry-run", "Preview what would be updated without making changes").option(
-  "--prune",
-  "Also delete orphaned managed files (tracked before this update, no longer part of any current component). Hash-checked: an edited file is reported, never silently deleted"
-).option("--user", USER_FLAG_DESCRIPTION).option(
-  "--default-scope <scope>",
-  "With --user: remember repo | user as the answer `spell init` pre-selects for NEW repositories on this machine. Never rewrites an existing repository, and the question is still asked"
+withManifestFlags(
+  program.command("update").description("Update installed components to the current package version").option("--dry-run", "Preview what would be updated without making changes").option(
+    "--prune",
+    "Also delete orphaned managed files (tracked before this update, no longer part of any current component). Hash-checked: an edited file is reported, never silently deleted"
+  ).option("--user", USER_FLAG_DESCRIPTION).option(
+    "--default-scope <scope>",
+    "With --user: remember repo | user as the answer `spell init` pre-selects for NEW repositories on this machine. Never rewrites an existing repository, and the question is still asked"
+  )
 ).action(async (opts) => {
   if (opts.defaultScope !== void 0) {
     if (!opts.user) {
@@ -7163,6 +7760,7 @@ program.command("update").description("Update installed components to the curren
       dryRun: opts.dryRun,
       prune: opts.prune,
       user: opts.user,
+      manifestFlags: manifestFlagsFrom(opts),
       ...opts.defaultScope === void 0 ? {} : { defaultScope: opts.defaultScope }
     },
     targetDirFor(opts),
@@ -7176,6 +7774,9 @@ program.command("status").description("Show installed components and check for u
 program.command("uninstall").description("Remove all installed Arcane framework files").option("--yes", "Skip confirmation prompt").option("--dry-run", "Preview what would be removed without deleting files").option("--user", USER_FLAG_DESCRIPTION).action(async (opts) => {
   await runUninstall({ yes: opts.yes, dryRun: opts.dryRun, user: opts.user }, targetDirFor(opts));
 });
+program.command("block-push").description("Enforce push_policy: blocked on this repository (pre-push hook + disabled push URLs); only ever tightens").action(async () => {
+  await runBlockPush(process.cwd());
+});
 program.command("unblock-push").description("Lift this repository's push block (interactive terminal only)").action(async () => {
   await runUnblockPush(process.cwd());
 });