arcane-cli 0.19.0 → 0.20.1

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 dirname3, join as join11 } from "path";
+import { dirname as dirname3, join as join12 } from "path";
 
 // src/commands/init.ts
 import { select as select2, confirm, input as input2 } from "@inquirer/prompts";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import chalk2 from "chalk";
 
 // src/modules/copier.ts
@@ -99,6 +99,7 @@ var MANIFEST_FILE = ".arcane.json";
 var VALID_TRACKING_MODES = ["internal", "external"];
 var VALID_EXTERNAL_PROVIDERS = ["ado", "jira", "other"];
 var VALID_CONTENT_SENSITIVITY = ["standard", "sensitive"];
+var VALID_PUSH_POLICIES = ["open", "guarded", "blocked"];
 function isValidSubjectRoot(value) {
   const invalid = value.trim() === "" || path2.isAbsolute(value) || // Windows drive-relative ("C:docs") and UNC-ish values also escape.
   /^[a-zA-Z]:/.test(value) || value.startsWith("\\\\") || value.startsWith("\\") || value.split(/[\\/]/).includes("..") || // A stored subject_root is interpolated into agent prompts downstream, so
@@ -128,6 +129,9 @@ function validateTrackingFields(manifest, filePath) {
       manifest.content_sensitivity
     );
   }
+  if (manifest.push_policy !== void 0 && !VALID_PUSH_POLICIES.includes(manifest.push_policy)) {
+    throw new ManifestInvalidFieldError(filePath, "push_policy", manifest.push_policy);
+  }
   if (manifest.subject_root !== void 0 && manifest.subject_root !== null) {
     if (typeof manifest.subject_root !== "string") {
       throw new ManifestInvalidFieldError(filePath, "subject_root", manifest.subject_root);
@@ -668,7 +672,7 @@ var WORDMARK = [
 var INDENT = "  ";
 var LOCKUP_WIDTH = INDENT.length + Math.max(...WORDMARK.map((l) => l.length));
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 function isAnimatable() {
   return !!process.stdout.isTTY && process.env["TERM"] !== "dumb" && process.env["CI"] !== "true" && process.env["ARCANE_DISABLE_ANIMATION"] !== "true" && (process.stdout.columns ?? 80) >= LOCKUP_WIDTH;
@@ -1790,6 +1794,11 @@ async function runAgentsList(targetDir) {
   console.log();
 }
 
+// src/modules/push-safety.ts
+import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile5, chmod, access as access3, rm as rm2 } from "fs/promises";
+import { constants } from "fs";
+import { join as join4, resolve } from "path";
+
 // src/modules/git.ts
 import { execFile } from "child_process";
 var GitTimeoutError = class extends Error {
@@ -1885,7 +1894,7 @@ function buildGitEnv() {
 function runGit(cwd, args, options = {}) {
   const commandClass = options.commandClass ?? classifyGitCommand(args);
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUTS_MS[commandClass] ?? DEFAULT_TIMEOUTS_MS.write;
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve3, reject) => {
     const child = execFile(
       "git",
       args,
@@ -1919,7 +1928,7 @@ function runGit(cwd, args, options = {}) {
           reject(error);
           return;
         }
-        resolve({ stdout, stderr });
+        resolve3({ stdout, stderr });
       }
     );
     child.stdin?.end();
@@ -2008,6 +2017,317 @@ async function ensureLocalPullRebase(cwd) {
   }
 }
 
+// src/modules/push-safety.ts
+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";
+async function readHooksPath(cwd) {
+  let raw;
+  try {
+    const { stdout } = await runGit(cwd, ["config", "--show-scope", "--get", "core.hooksPath"]);
+    raw = stdout.trim();
+  } catch (error) {
+    if (error.code !== 1) {
+      return { value: "", scope: "unknown", unreadable: true };
+    }
+    return void 0;
+  }
+  if (raw === "") return void 0;
+  const separator = raw.indexOf("	");
+  if (separator === -1) return { value: raw, scope: "unknown" };
+  const scope = raw.slice(0, separator).trim();
+  const value = raw.slice(separator + 1).trim();
+  if (value === "") return void 0;
+  const known = ["local", "worktree", "global", "system", "command"];
+  const matched = known.find((candidate) => candidate === scope);
+  return { value, scope: matched ?? "unknown" };
+}
+function isArcaneHooksPath(cwd, value) {
+  const windows = process.platform === "win32";
+  const normalize = (p) => {
+    const separated = windows ? p.replace(/\\/g, "/") : p;
+    const absolute = resolve(cwd, separated).replace(/\\/g, "/").replace(/\/+$/, "");
+    return windows ? absolute.toLowerCase() : absolute;
+  };
+  return normalize(value) === normalize(ARCANE_HOOKS_DIR);
+}
+var HOOK_BODY = `#!/bin/sh
+# Installed by Arcane because this repository's .arcane.json sets
+# push_policy: "blocked".
+#
+# This is deliberately not tamper-proof. It guards against an accidental push
+# -- the wrong remote, muscle memory, an unsupervised agent -- not against a
+# determined operator, who can always bypass it.
+#
+# To push legitimately, undo the policy first:
+#
+#     spell unblock-push
+#
+# That command is interactive-only and asks you to confirm the repository by
+# name. Do not work around this hook by other means: the manifest would then
+# claim a protection this repository no longer has.
+echo "arcane: push blocked (push_policy: blocked). Run 'spell unblock-push' to undo." >&2
+exit 1
+`;
+function describeConfigScope(scope) {
+  switch (scope) {
+    case "local":
+      return "set for this repository";
+    case "worktree":
+      return "set for this worktree";
+    case "global":
+      return "set globally, for your user";
+    case "system":
+      return "set system-wide";
+    case "command":
+      return "set on the command line";
+    default:
+      return "scope unknown";
+  }
+}
+function hookFilePath(cwd) {
+  return join4(cwd, ARCANE_HOOKS_DIR, "pre-push");
+}
+async function installPrePushHook(cwd) {
+  const existing = await readHooksPath(cwd);
+  if (existing?.unreadable === true) return { status: "refused-unreadable-config" };
+  if (existing !== void 0 && !isArcaneHooksPath(cwd, existing.value)) {
+    return {
+      status: "refused-foreign-hooks-path",
+      existing: existing.value,
+      scope: existing.scope
+    };
+  }
+  const hookPath = hookFilePath(cwd);
+  if (existing !== void 0 && await hookBodyMatches(cwd)) return { status: "already-ours" };
+  await mkdir4(join4(cwd, ARCANE_HOOKS_DIR), { recursive: true });
+  await writeFile5(hookPath, HOOK_BODY, "utf-8");
+  await chmod(hookPath, 493);
+  await runGit(cwd, ["config", "--local", "core.hooksPath", ARCANE_HOOKS_DIR]);
+  return { status: "installed", path: hookPath };
+}
+async function isHookEnforced(cwd) {
+  const hooksPath = await readHooksPath(cwd);
+  if (hooksPath === void 0 || !isArcaneHooksPath(cwd, hooksPath.value)) return false;
+  return hookBodyMatches(cwd);
+}
+async function hookBodyMatches(cwd) {
+  const hookPath = hookFilePath(cwd);
+  if (!await fileExists(hookPath)) return false;
+  try {
+    if (await readFile4(hookPath, "utf-8") !== HOOK_BODY) return false;
+  } catch {
+    return false;
+  }
+  if (process.platform === "win32") return true;
+  try {
+    await access3(hookPath, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function removePrePushHook(cwd) {
+  const existing = await readHooksPath(cwd);
+  if (existing === void 0 || existing.unreadable === true) return;
+  if (!isArcaneHooksPath(cwd, existing.value)) return;
+  if (existing.scope !== "local" && existing.scope !== "worktree") return;
+  const scopeFlag = existing.scope === "worktree" ? "--worktree" : "--local";
+  try {
+    await runGit(cwd, ["config", scopeFlag, "--unset", "core.hooksPath"]);
+  } catch {
+  }
+  try {
+    await rm2(hookFilePath(cwd), { force: true });
+  } catch {
+  }
+}
+async function listRemotes(cwd) {
+  try {
+    const { stdout } = await runGit(cwd, ["remote"]);
+    return stdout.split("\n").map((r) => r.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+async function pushTargets(cwd) {
+  const targets = [];
+  for (const remote of await listRemotes(cwd)) {
+    try {
+      const { stdout } = await runGit(cwd, ["remote", "get-url", "--push", "--all", remote]);
+      targets.push({
+        remote,
+        urls: stdout.split("\n").map((line) => line.trim()).filter(Boolean)
+      });
+    } catch {
+      targets.push({ remote, urls: [] });
+    }
+  }
+  return targets;
+}
+function originalPushUrlKey(remote) {
+  return `remote.${remote}.arcaneOriginalPushUrl`;
+}
+async function readLocalAll(cwd, key) {
+  try {
+    const { stdout } = await runGit(cwd, ["config", "--local", "--get-all", key]);
+    return stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+async function readScopedAll(cwd, key) {
+  let stdout;
+  try {
+    ({ stdout } = await runGit(cwd, ["config", "--show-scope", "--get-all", key]));
+  } catch {
+    return [];
+  }
+  return stdout.split("\n").map((line) => line.trimEnd()).filter(Boolean).map((line) => {
+    const separator = line.indexOf("	");
+    if (separator === -1) return { scope: "unknown", value: line.trim() };
+    return { scope: line.slice(0, separator).trim(), value: line.slice(separator + 1).trim() };
+  }).filter((entry) => entry.value !== "");
+}
+async function effectivePushUrls(cwd, remote) {
+  const scoped = await readScopedAll(cwd, `remote.${remote}.pushurl`);
+  return scoped.map((entry) => entry.value);
+}
+async function disablePushUrls(cwd) {
+  const results = [];
+  for (const remote of await listRemotes(cwd)) {
+    try {
+      results.push(await disableOneRemote(cwd, remote));
+    } catch (error) {
+      results.push({ remote, status: "failed", reason: describeError(error) });
+    }
+  }
+  return results;
+}
+async function disableOneRemote(cwd, remote) {
+  const scoped = await readScopedAll(cwd, `remote.${remote}.pushurl`);
+  const foreign = scoped.filter((entry) => entry.scope !== "local" && entry.value !== DISABLED_PUSH_URL);
+  if (foreign.length > 0) {
+    const where = [...new Set(foreign.map((entry) => entry.scope))].join(", ");
+    return {
+      remote,
+      status: "failed",
+      reason: `a push URL for this remote is configured at ${where} scope, which this repository cannot override \u2014 git would still deliver the push there. Remove it with \`git config --${where.split(", ")[0]} --unset-all remote.${remote}.pushurl\` and re-apply.`
+    };
+  }
+  const currentPushUrls = scoped.map((entry) => entry.value);
+  if (currentPushUrls.length === 1 && currentPushUrls[0] === DISABLED_PUSH_URL) {
+    return { remote, status: "already-disabled" };
+  }
+  const key = originalPushUrlKey(remote);
+  if ((await readLocalAll(cwd, key)).length === 0 && !await hadNoPushUrl(cwd, remote)) {
+    if (currentPushUrls.length > 0) {
+      await runGit(cwd, ["config", "--local", "--replace-all", key, currentPushUrls[0]]);
+      for (const extra of currentPushUrls.slice(1)) {
+        await runGit(cwd, ["config", "--local", "--add", key, extra]);
+      }
+    } else {
+      await runGit(cwd, ["config", "--local", NO_PUSH_URL_MARKER(remote), "true"]);
+    }
+  }
+  await runGit(cwd, [
+    "config",
+    "--local",
+    "--replace-all",
+    `remote.${remote}.pushurl`,
+    DISABLED_PUSH_URL
+  ]);
+  return { remote, status: "disabled" };
+}
+async function undisabledRemotes(cwd) {
+  const open = [];
+  for (const remote of await listRemotes(cwd)) {
+    const urls = await effectivePushUrls(cwd, remote);
+    if (urls.length === 0 || urls.some((url) => url !== DISABLED_PUSH_URL)) open.push(remote);
+  }
+  return open;
+}
+async function blockedRemotes(cwd) {
+  const blocked = [];
+  for (const remote of await listRemotes(cwd)) {
+    const urls = await effectivePushUrls(cwd, remote);
+    if (urls.some((url) => url === DISABLED_PUSH_URL)) blocked.push(remote);
+  }
+  return blocked;
+}
+async function restorePushUrls(cwd) {
+  const results = [];
+  for (const remote of await listRemotes(cwd)) {
+    try {
+      results.push(await restoreOneRemote(cwd, remote));
+    } catch (error) {
+      results.push({ remote, status: "failed", reason: describeError(error) });
+    }
+  }
+  return results;
+}
+async function restoreOneRemote(cwd, remote) {
+  const key = originalPushUrlKey(remote);
+  let recorded = await readLocalAll(cwd, key);
+  let hadNone = await hadNoPushUrl(cwd, remote);
+  if (recorded.length === 0 && !hadNone) {
+    const legacy = await readLegacyRecord(cwd, remote);
+    if (legacy.status !== "usable") return { remote, status: legacy.status, reason: legacy.reason };
+    recorded = legacy.values;
+    hadNone = false;
+  }
+  if (hadNone) {
+    await runGit(cwd, ["config", "--local", "--unset-all", `remote.${remote}.pushurl`]);
+  } else {
+    await runGit(cwd, [
+      "config",
+      "--local",
+      "--replace-all",
+      `remote.${remote}.pushurl`,
+      recorded[0]
+    ]);
+    for (const extra of recorded.slice(1)) {
+      await runGit(cwd, ["config", "--local", "--add", `remote.${remote}.pushurl`, extra]);
+    }
+  }
+  for (const staleKey of [key, NO_PUSH_URL_MARKER(remote), `arcane.originalPushUrl.${remote}`]) {
+    try {
+      await runGit(cwd, ["config", "--local", "--unset-all", staleKey]);
+    } catch {
+    }
+  }
+  return { remote, status: "restored" };
+}
+async function hadNoPushUrl(cwd, remote) {
+  return (await readLocalAll(cwd, NO_PUSH_URL_MARKER(remote)))[0] === "true";
+}
+async function readLegacyRecord(cwd, remote) {
+  const values = await readLocalAll(cwd, `arcane.originalPushUrl.${remote}`);
+  if (values.length === 0) return { status: "nothing-recorded" };
+  const current = await effectivePushUrls(cwd, remote);
+  if (!current.includes(DISABLED_PUSH_URL)) {
+    return {
+      status: "failed",
+      reason: `found a push URL recorded by 0.20.0 ("${values.join(", ")}") but this remote is not currently blocked by Arcane, so the record may belong to a different remote of the same name. Not applying it \u2014 set the URL yourself if it is correct.`
+    };
+  }
+  const names = await listRemotes(cwd);
+  const collides = names.some(
+    (other) => other !== remote && other.toLowerCase() === remote.toLowerCase()
+  );
+  if (collides) {
+    return {
+      status: "failed",
+      reason: `this repository has remotes whose names differ only by case, and 0.20.0 stored their original push URLs under one shared key, so the recorded value ("${values.join(", ")}") cannot be attributed to a specific remote. Not applying it \u2014 set the URLs yourself.`
+    };
+  }
+  return { status: "usable", values };
+}
+function describeError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.split("\n")[0].trim();
+}
+
 // src/commands/init.ts
 var VALID_PROFILES = ["full", "lite", "governance-only", "methodology", "docs"];
 var PROFILE_ICONS = {
@@ -2170,7 +2490,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   for (const component of components) {
     const installedFiles = [];
     for (const file of component.files) {
-      const srcPath = join4(assetsDir, component.sourceOverrides?.[file] ?? file);
+      const srcPath = join5(assetsDir, component.sourceOverrides?.[file] ?? file);
       if (options.dryRun) {
         printDryRun(`Would copy: ${file}`);
       } else {
@@ -2187,7 +2507,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       fileCount++;
     }
     for (const dir of component.directories ?? []) {
-      const srcDirPath = join4(assetsDir, dir);
+      const srcDirPath = join5(assetsDir, dir);
       if (options.dryRun) {
         printDryRun(`Would copy directory: ${dir}/`);
       } else {
@@ -2212,7 +2532,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   if (options.dryRun) {
     if (hasAgents) {
       const agentFiles = await import("fs").then(
-        (fsModule) => fsModule.promises.readdir(join4(assetsDir, "agents"))
+        (fsModule) => fsModule.promises.readdir(join5(assetsDir, "agents"))
       );
       const yamlFiles = agentFiles.filter((f) => f.endsWith(".yaml")).sort();
       printDryRun("Would run agent setup (interactive):");
@@ -2302,6 +2622,22 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       default: "standard"
     });
   }
+  let push_policy;
+  if (!options.profile) {
+    console.log();
+    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 (a pre-push hook plus a disabled push URL)"
+        }
+      ],
+      default: "open"
+    });
+  }
   const manifest = {
     version: packageVersion,
     profile,
@@ -2310,10 +2646,55 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
     ...role ? { role } : {},
     ...tracking_mode ? { tracking_mode, external_provider } : {},
     ...subject_root !== void 0 ? { subject_root } : {},
-    ...content_sensitivity ? { content_sensitivity } : {}
+    ...content_sensitivity ? { content_sensitivity } : {},
+    ...push_policy ? { push_policy } : {}
   };
   await writeManifest(targetDir, manifest);
   printSuccess(`Initialized with profile "${profile}" \u2014 ${fileCount} files installed`);
+  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-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) {
+          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."
+          );
+        } 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).`);
+          }
+        }
+        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."
+        );
+      }
+    } catch (err) {
+      printWarning(
+        `Could not fully apply push-safety controls: ${err instanceof Error ? err.message : String(err)}. The manifest records push_policy: "${push_policy}", but this repository may not actually be protected. Run \`spell doctor\` to see exactly what is and isn't in place.`
+      );
+    }
+  }
   let agentsConfigured = false;
   if (hasAgents && !options.profile) {
     console.log();
@@ -2359,7 +2740,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
 }
 
 // src/commands/add.ts
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
   let manifest;
   try {
@@ -2394,7 +2775,7 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
   let fileCount = 0;
   const installedFiles = [];
   for (const file of component.files) {
-    const srcPath = join5(assetsDir, component.sourceOverrides?.[file] ?? file);
+    const srcPath = join6(assetsDir, component.sourceOverrides?.[file] ?? file);
     if (options.dryRun) {
       console.log(`  [dry-run] Would copy: ${file}`);
     } else {
@@ -2404,7 +2785,7 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
     fileCount++;
   }
   for (const dir of component.directories ?? []) {
-    const srcDirPath = join5(assetsDir, dir);
+    const srcDirPath = join6(assetsDir, dir);
     if (options.dryRun) {
       console.log(`  [dry-run] Would copy directory: ${dir}/`);
     } else {
@@ -2434,12 +2815,12 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
 }
 
 // src/commands/update.ts
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 
 // src/modules/hub.ts
 import { confirm as confirm2, select as select3, input as input3 } from "@inquirer/prompts";
-import { readdir as readdir3, writeFile as writeFile5 } from "fs/promises";
-import { join as join6 } from "path";
+import { readdir as readdir3, writeFile as writeFile6 } from "fs/promises";
+import { join as join7 } from "path";
 var MANIFEST_RETROFITS = [
   {
     field: "role",
@@ -2539,6 +2920,27 @@ var MANIFEST_RETROFITS = [
       }
       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) {
@@ -2556,9 +2958,9 @@ async function runManifestRetrofits(manifest) {
   return patch;
 }
 async function offerRegistryScaffold(targetDir, businessRoot) {
-  const registryPath = join6(targetDir, businessRoot, "registry.json");
+  const registryPath = join7(targetDir, businessRoot, "registry.json");
   if (await fileExists(registryPath)) return;
-  const businessRootPath = join6(targetDir, businessRoot);
+  const businessRootPath = join7(targetDir, businessRoot);
   let ventureDirs;
   try {
     const entries = await readdir3(businessRootPath, { withFileTypes: true });
@@ -2596,7 +2998,7 @@ async function offerRegistryScaffold(targetDir, businessRoot) {
     updated: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
     ventures
   };
-  await writeFile5(registryPath, JSON.stringify(registry, null, 2) + "\n", "utf-8");
+  await writeFile6(registryPath, JSON.stringify(registry, null, 2) + "\n", "utf-8");
   console.log(
     `  \u2713 Scaffolded ${businessRoot}/registry.json with ${Object.keys(ventures).length} venture(s).`
   );
@@ -2689,8 +3091,8 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     }
     const updatedFiles = [];
     for (const file of component.files) {
-      const srcPath = join7(assetsDir, component.sourceOverrides?.[file] ?? file);
-      const targetExists = await fileExists(join7(targetDir, file));
+      const srcPath = join8(assetsDir, component.sourceOverrides?.[file] ?? file);
+      const targetExists = await fileExists(join8(targetDir, file));
       const preserveExisting = Boolean(component.skipExisting) && targetExists;
       if (component.initOnly && !targetExists) {
         console.log(
@@ -2712,7 +3114,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       }
     }
     for (const dir of component.directories ?? []) {
-      const srcDirPath = join7(assetsDir, dir);
+      const srcDirPath = join8(assetsDir, dir);
       if (options.dryRun) {
         console.log(`  [dry-run] Would update directory: ${dir}/`);
       } else {
@@ -2767,8 +3169,8 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
 }
 
 // src/modules/version-check.ts
-import { readFile as readFile4, writeFile as writeFile6, mkdir as mkdir4 } from "fs/promises";
-import { dirname, join as join8 } from "path";
+import { readFile as readFile5, writeFile as writeFile7, mkdir as mkdir5 } from "fs/promises";
+import { dirname, join as join9 } from "path";
 import { homedir as homedir2 } from "os";
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
@@ -2782,11 +3184,11 @@ function getFeedUrl() {
   }
   return url;
 }
-var DEFAULT_CACHE_PATH = join8(homedir2(), ".arcane", "version-cache.json");
+var DEFAULT_CACHE_PATH = join9(homedir2(), ".arcane", "version-cache.json");
 var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 async function readCache(cachePath) {
   try {
-    const content = await readFile4(cachePath, "utf-8");
+    const content = await readFile5(cachePath, "utf-8");
     const parsed = JSON.parse(content);
     if (typeof parsed.latest !== "string" || typeof parsed.checkedAt !== "string") {
       return null;
@@ -2797,9 +3199,9 @@ async function readCache(cachePath) {
   }
 }
 async function writeCache(cachePath, latest) {
-  await mkdir4(dirname(cachePath), { recursive: true });
+  await mkdir5(dirname(cachePath), { recursive: true });
   const entry = { latest, checkedAt: (/* @__PURE__ */ new Date()).toISOString() };
-  await writeFile6(cachePath, JSON.stringify(entry, null, 2), "utf-8");
+  await writeFile7(cachePath, JSON.stringify(entry, null, 2), "utf-8");
 }
 async function getLatestVersion(feedUrl) {
   const normalizedBase = feedUrl.endsWith("/") ? feedUrl : feedUrl + "/";
@@ -2911,8 +3313,8 @@ async function runStatus(targetDir, packageVersion) {
 }
 
 // src/commands/uninstall.ts
-import { rm as rm2 } from "fs/promises";
-import { join as join9 } from "path";
+import { rm as rm3 } from "fs/promises";
+import { join as join10 } from "path";
 import { confirm as confirm3 } from "@inquirer/prompts";
 async function runUninstall(options, targetDir) {
   let manifest;
@@ -2926,6 +3328,21 @@ async function runUninstall(options, targetDir) {
     }
     throw err;
   }
+  const policy = manifest.push_policy ?? "open";
+  const controlsInForce = await isHookEnforced(targetDir) || (await blockedRemotes(targetDir)).length > 0;
+  if ((policy === "blocked" || controlsInForce) && !options.dryRun) {
+    const why = policy === "blocked" ? `this repository's push_policy is "blocked"` : `this repository still has Arcane's push block in force (the manifest says "${policy}", but the controls are actually installed)`;
+    console.error(
+      `Refusing to uninstall: ${why}.
+Uninstalling now would delete .arcane.json while leaving the pre-push hook and the
+disabled push URLs in place \u2014 the repository could not push, and \`spell unblock-push\`
+would no longer recognise it.
+
+Run \`spell unblock-push\` first (interactive), then uninstall.`
+    );
+    process.exit(1);
+    return;
+  }
   const allFiles = manifest.components.flatMap((c) => c.files);
   const totalFiles = allFiles.length;
   if (options.dryRun) {
@@ -2940,6 +3357,11 @@ async function runUninstall(options, targetDir) {
     console.log(`[dry-run] Would strip arcane sections from: CLAUDE.md, AGENTS.md, copilot-instructions.md`);
     console.log(`
 [dry-run] ${totalFiles} file(s) + manifest + agent outputs would be removed.`);
+    if (policy === "blocked" || controlsInForce) {
+      console.log(
+        `[dry-run] BUT the real run would refuse: Arcane's push block is in force. Run \`spell unblock-push\` first.`
+      );
+    }
     return;
   }
   if (!options.yes) {
@@ -2955,24 +3377,24 @@ async function runUninstall(options, targetDir) {
   let removed = 0;
   for (const component of manifest.components) {
     for (const file of component.files) {
-      const filePath = join9(targetDir, file);
+      const filePath = join10(targetDir, file);
       try {
-        await rm2(filePath, { force: true });
+        await rm3(filePath, { force: true });
         removed++;
       } catch {
       }
     }
   }
-  await rm2(join9(targetDir, ".arcane.json"), { force: true });
+  await rm3(join10(targetDir, ".arcane.json"), { force: true });
   const agentDirs = [
     ".github/agents",
     ".arcane/agents",
     ".arcane/generated"
   ];
   for (const dir of agentDirs) {
-    await rm2(join9(targetDir, dir), { recursive: true, force: true });
+    await rm3(join10(targetDir, dir), { recursive: true, force: true });
   }
-  await rm2(join9(targetDir, ".arcane/agents.yaml"), { force: true });
+  await rm3(join10(targetDir, ".arcane/agents.yaml"), { force: true });
   const markerFiles = [
     "CLAUDE.md",
     "AGENTS.md",
@@ -2986,8 +3408,8 @@ async function runUninstall(options, targetDir) {
 }
 
 // src/commands/doctor.ts
-import { access as access3, readFile as readFile5, mkdir as mkdir5, copyFile as fsCopyFile2 } from "fs/promises";
-import { join as join10, dirname as dirname2 } from "path";
+import { access as access4, readFile as readFile6, mkdir as mkdir6, copyFile as fsCopyFile2 } from "fs/promises";
+import { join as join11, dirname as dirname2 } from "path";
 import { execFile as execFile2 } from "child_process";
 import { promisify } from "util";
 
@@ -3075,8 +3497,8 @@ async function checkVSCodeExtension(id, label) {
   const name = `VS Code extension: ${label}`;
   const home = process.env["HOME"] ?? "";
   const extDirs = [
-    join10(home, ".vscode", "extensions"),
-    join10(home, ".vscode-insiders", "extensions")
+    join11(home, ".vscode", "extensions"),
+    join11(home, ".vscode-insiders", "extensions")
   ];
   for (const dir of extDirs) {
     try {
@@ -3110,13 +3532,13 @@ async function checkVSCodeExtension(id, label) {
 }
 async function checkArcaneManifest(targetDir) {
   const name = "Arcane manifest (.arcane.json)";
-  const manifestPath2 = join10(targetDir, ".arcane.json");
+  const manifestPath2 = join11(targetDir, ".arcane.json");
   try {
-    await access3(manifestPath2);
+    await access4(manifestPath2);
   } catch {
-    const selfHostedManifestPath = join10(targetDir, "src", "assets", ".arcane.json");
+    const selfHostedManifestPath = join11(targetDir, "src", "assets", ".arcane.json");
     try {
-      const raw = await readFile5(selfHostedManifestPath, "utf8");
+      const raw = await readFile6(selfHostedManifestPath, "utf8");
       const manifest = JSON.parse(raw);
       if (manifest.selfHosted === true && manifest.tracking_mode === "internal") {
         return {
@@ -3135,7 +3557,7 @@ async function checkArcaneManifest(targetDir) {
     };
   }
   try {
-    const raw = await readFile5(manifestPath2, "utf8");
+    const raw = await readFile6(manifestPath2, "utf8");
     const manifest = JSON.parse(raw);
     if (!manifest.version || !Array.isArray(manifest.components)) {
       return {
@@ -3206,9 +3628,9 @@ async function checkSessionContinuity(targetDir) {
   const results = [];
   for (const file of SESSION_CONTINUITY_FILES) {
     const name = `Session file: ${file}`;
-    const filePath = join10(targetDir, file);
+    const filePath = join11(targetDir, file);
     try {
-      await access3(filePath);
+      await access4(filePath);
       results.push({ name, passed: true, message: "present" });
     } catch {
       results.push({
@@ -3224,18 +3646,69 @@ async function checkSessionContinuity(targetDir) {
 async function fixSessionContinuity(targetDir, assetsDir) {
   const created = [];
   for (const file of SESSION_CONTINUITY_FILES) {
-    const destPath = join10(targetDir, file);
+    const destPath = join11(targetDir, file);
     try {
-      await access3(destPath);
+      await access4(destPath);
     } catch {
-      const srcPath = join10(assetsDir, file);
-      await mkdir5(dirname2(destPath), { recursive: true });
+      const srcPath = join11(assetsDir, file);
+      await mkdir6(dirname2(destPath), { recursive: true });
       await fsCopyFile2(srcPath, destPath);
       created.push(file);
     }
   }
   return created;
 }
+async function checkPushPolicy(targetDir) {
+  const name = "Push policy (EF-09)";
+  let manifest;
+  try {
+    manifest = await readManifest(targetDir);
+  } catch {
+    return { name, passed: true, message: "not initialized \u2014 nothing to check" };
+  }
+  const policy = manifest.push_policy ?? "open";
+  if (policy === "open") {
+    return { name, passed: true, message: "open \u2014 pushes allowed" };
+  }
+  if (policy === "guarded") {
+    const targets = await pushTargets(targetDir);
+    const where = targets.length === 0 ? "none configured" : targets.map(({ remote, urls }) => `${remote} \u2192 ${urls.length > 0 ? urls.join(", ") : "unknown"}`).join("; ");
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: `guarded \u2014 no technical control installed. Push targets: ${where}. Confirm those are the remotes you intend before pushing.`
+    };
+  }
+  const hookActive = await isHookEnforced(targetDir);
+  const remotes = await listRemotes(targetDir);
+  const open = await undisabledRemotes(targetDir);
+  if (hookActive && open.length === 0) {
+    if (remotes.length === 0) {
+      return {
+        name,
+        passed: false,
+        blocking: false,
+        message: "blocked \u2014 pre-push hook in place, but no remote is configured, so no push URL is disabled. If a remote is added later, run `spell doctor` again: a --no-verify push to it would succeed until the URL is disabled too."
+      };
+    }
+    return {
+      name,
+      passed: true,
+      message: `blocked \u2014 pre-push hook in place and push URL disabled for ${remotes.join(", ")}`
+    };
+  }
+  const missing = [
+    hookActive ? null : "pre-push hook (config or hook file absent)",
+    open.length > 0 ? `push URL still live for: ${open.join(", ")}` : null
+  ].filter(Boolean);
+  return {
+    name,
+    passed: false,
+    blocking: false,
+    message: `declared "blocked" but not enforced \u2014 ${missing.join("; ")}. The manifest claims a protection this repository does not have.`
+  };
+}
 async function runDoctor(targetDir, options = {}, assetsDir) {
   console.log("\nspell doctor \u2014 checking your Arcane environment\n");
   const results = await Promise.all([
@@ -3243,7 +3716,8 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     checkVSCodeExtension("GitHub.copilot-chat", "GitHub Copilot (Chat)"),
     checkArcaneManifest(targetDir),
     Promise.resolve(checkIncidentReleaseGate()),
-    checkPullRebase(targetDir)
+    checkPullRebase(targetDir),
+    checkPushPolicy(targetDir)
   ]);
   const sessionResults = await checkSessionContinuity(targetDir);
   results.push(...sessionResults);
@@ -3287,11 +3761,103 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
   }
 }
 
+// src/commands/unblock-push.ts
+import { basename, resolve as resolve2 } from "path";
+import { input as input4 } from "@inquirer/prompts";
+async function runUnblockPush(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;
+  }
+  const policy = manifest.push_policy ?? "open";
+  if (policy === "open") {
+    printInfo("This repository is not push-blocked \u2014 nothing to undo.");
+    return;
+  }
+  if (!process.stdin.isTTY) {
+    console.error(
+      "spell unblock-push must be run from an interactive terminal.\nLifting a push block is a deliberate decision, so it cannot be scripted, piped, or run in CI."
+    );
+    process.exit(1);
+    return;
+  }
+  const repoName = basename(resolve2(targetDir));
+  if (repoName === "") {
+    console.error(
+      "Could not determine a repository name to confirm against (is this repository at a filesystem root?). Refusing to unblock."
+    );
+    process.exit(1);
+    return;
+  }
+  printWarning(`This repository's push_policy is "${policy}".`);
+  printInfo(
+    "Unblocking restores the ability to push this repository's full history to its remote. Deleting a file later does not undo a push: the content stays in history, in any clone already made, and in the remote's own backups."
+  );
+  console.log();
+  const typed = await input4({
+    message: `Type the repository name to confirm (${repoName}):`
+  });
+  if (typed.trim() !== repoName) {
+    console.error(`
+Name did not match ("${typed.trim()}" \u2260 "${repoName}"). Nothing changed.`);
+    process.exit(1);
+    return;
+  }
+  await removePrePushHook(targetDir);
+  const results = await restorePushUrls(targetDir);
+  const restored = results.filter((r) => r.status === "restored").map((r) => r.remote);
+  const failed = results.filter((r) => r.status === "failed");
+  const stillBlocked = await blockedRemotes(targetDir);
+  const updated = {
+    ...manifest,
+    push_policy: "open",
+    push_policy_unblocked_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await writeManifest(targetDir, updated);
+  const hookStillOn = await isHookEnforced(targetDir);
+  const fullyLifted = failed.length === 0 && stillBlocked.length === 0 && !hookStillOn;
+  if (fullyLifted) {
+    printSuccess(`Push unblocked for "${repoName}".`);
+  } else {
+    printWarning(
+      `Push only PARTIALLY unblocked for "${repoName}". The manifest now says open; the repository is not fully open yet. Details below.`
+    );
+  }
+  if (restored.length > 0) {
+    printInfo(`Restored push URL for: ${restored.join(", ")}.`);
+  }
+  if (hookStillOn) {
+    printWarning(
+      "The pre-push hook is still in force. Arcane did not remove it because `core.hooksPath` is not one it owns, or could not be read. Check `git config --show-scope --get core.hooksPath`."
+    );
+  }
+  if (failed.length > 0) {
+    printWarning(
+      `Could not restore the push URL for: ${failed.map((r) => `${r.remote} (${r.reason ?? "unknown error"})`).join("; ")}.`
+    );
+  }
+  if (stillBlocked.length > 0) {
+    printWarning(
+      `These remotes still have a blocked push URL and no recorded original: ${stillBlocked.join(", ")}. Set them yourself with \`git remote set-url --push <name> <url>\` \u2014 until then, pushing to them will fail even though the manifest now says open.`
+    );
+  }
+  printInfo(
+    "Recorded in .arcane.json as push_policy: open, with the time it was lifted. Commit that change so the repository's actual posture stays visible to everyone."
+  );
+}
+
 // src/index.ts
 import { realpathSync } from "fs";
 var require3 = createRequire2(import.meta.url);
 var pkg = require3("../package.json");
-var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join11(dirname3(fileURLToPath(import.meta.url)), "assets");
+var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join12(dirname3(fileURLToPath(import.meta.url)), "assets");
 var program = new Command();
 program.name("spell").description("Arcane framework CLI \u2014 scaffold and manage governance files").version(pkg.version).action(async () => {
   await printWelcome(pkg.version, process.cwd());
@@ -3336,6 +3902,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").action(async (opts) => {
   await runUninstall({ yes: opts.yes, dryRun: opts.dryRun }, process.cwd());
 });
+program.command("unblock-push").description("Lift this repository's push block (interactive terminal only)").action(async () => {
+  await runUnblockPush(process.cwd());
+});
 program.command("doctor").description("Check your environment for Arcane prerequisites").option("--fix", "Automatically create missing session continuity files").action(async (opts) => {
   await runDoctor(process.cwd(), { fix: opts.fix }, ASSETS_DIR);
 });