arcane-cli 1.10.1 → 1.11.0

package/README.md

@@ -221,7 +221,7 @@ spell add agent-policies   # or install any component à la carte
 spell add spells-build compliance-standards   # or several, in order
 ```
 
-`spell add` takes one or more names. It checks each component's files before writing any of them: if one already exists, it prints one line naming the file and `--force`, exits 1, and writes nothing from that component. With several names it stops at the first failure and says which were added and which were not attempted; a name that is already installed is skipped. A component that keeps your own file (`.mcp.json`) leaves an existing one alone and creates a missing one. `--dry-run` lists each file as identical, differing or missing, or as one that would be kept or refused, and writes nothing.
+`spell add` takes one or more names. It checks each component's files before writing any of them: if one already exists, it prints one line naming the file and `--force`, exits 1, and writes nothing from that component. With several names it stops at the first failure and says which were added and which were not attempted; a name that is already installed is skipped. A component that keeps your own file (`.gitattributes`, for example) leaves an existing one alone and creates a missing one. `--dry-run` lists each file as identical, differing or missing, or as one that would be kept or refused, and writes nothing.
 
 ### What `spell update` installs
 

package/dist/assets/.arcane/governance/git-conventions.md

@@ -486,8 +486,14 @@ reported in output so a human sees it happened. The known-issues rows below (`MC
 `MCP create_pull_request`) are concrete instances of this general rule, not special cases of their own.
 **Consumer hardening:** set a per-server `"timeout"` (milliseconds) in `.mcp.json` so a hang aborts on a
 predictable schedule instead of running to the client's own default idle limit (as long as 30 minutes).
+In Claude Code the value goes inside each server's entry under `mcpServers` — `"timeout": 30000` is 30
+seconds — and must be 1000 or more; a smaller value is ignored (Claude Code MCP docs, checked 2026-10-02;
+other clients have their own keys, so check theirs before copying this one). `spell doctor` warns on an
+entry without one and never edits the file: `.mcp.json` is yours. Arcane ships no example `.mcp.json` —
+the `mcp-config-template` scaffold was retired on 2026-10-02 because a root `.mcp.json` is live
+configuration that clients execute, not documentation, and its placeholder server failed on every session start.
 Origin: a real ops session lost roughly an hour to two consecutive 30-minute MCP hangs before the
-documented `az` fallback was used (2026-08-14). **Enforcement: explicitly advisory prose (ARC-023) — this fail-fast behavior and the `.mcp.json` timeout hardening both depend on the acting agent actually following them; no check in this repo verifies an agent stopped retrying a downed MCP server or that a given `.mcp.json` entry sets a timeout.**
+documented `az` fallback was used (2026-08-14). **Enforcement: explicitly advisory prose (ARC-023) for the fail-fast behavior — no check in this repo verifies an agent stopped retrying a downed MCP server. The timeout hardening has an advisory check: `spell doctor`'s "MCP config (per-server timeout, I12)" row warns on a `.mcp.json` entry without a `"timeout"` (exit code unchanged) and edits nothing.**
 
 **Known issues:**
 

package/dist/assets/.arcane/spells/spell-sync-pull-request.md

@@ -1,10 +1,10 @@
 ---
 name: Spell — Sync Pull Request
-description: Safely sync an open PR's branch with its target when it has fallen behind — recoverable pre-rebase ref, mechanical-vs-ambiguous conflict handling, force-with-lease push, provider-verified landing. Use when a PR needs rebasing onto a moved target, or was routed here from spell-create-pull-request/spell-ship's own conflict-stop points.
+description: Safely sync an open PR's branch with its target when it has fallen behind — recoverable pre-rebase ref, mechanical / regenerable / ambiguous conflict handling, force-with-lease push, provider-verified landing. Use when a PR needs rebasing onto a moved target, or was routed here from spell-create-pull-request/spell-ship's own conflict-stop points.
 claude_description: Use PROACTIVELY whenever an open PR has fallen behind its target branch and needs a safe rebase/sync, or when spell-create-pull-request/spell-ship stop on a conflict they route here.
 argument-hint: '[PR number or branch name]'
 agent: agent
-last_updated: 2026-08-31
+last_updated: 2026-10-01
 ---
 
 ## Executive Summary
@@ -13,7 +13,9 @@ last_updated: 2026-08-31
 - It is the recovery path `spell-create-pull-request` and `spell-ship` route to when they detect a
   conflict they deliberately don't try to resolve themselves.
 - It draws a hard line between conflicts safe to resolve mechanically (identical changes on both sides)
-  and conflicts that need a human — it never guesses on the ambiguous side of that line.
+  and conflicts that need a human — it never guesses on the ambiguous side of that line. A third class,
+  a script-regenerable artifact, is neither merged nor handed off: it is regenerated against the rebased
+  tree and verified by its own check.
 - Every history-rewriting step is preceded by a recoverable ref, and every push uses
   `--force-with-lease`, never bare `--force`.
 
@@ -72,7 +74,7 @@ Resolve the repository's actual merge-strategy ladder from `git-conventions.md`
 - **Never** produce a squash or semi-linear result as part of this sync — those are never sanctioned,
   regardless of which of the two above applies.
 
-## Step 3 — Classify any conflict: mechanical vs. ambiguous
+## Step 3 — Classify any conflict: mechanical, regenerable, or ambiguous
 
 If Step 2 completes with no conflicts, skip straight to Step 4 — **this is the common case and it must
 not be treated as a special case of conflict handling.**
@@ -84,6 +86,25 @@ then classify **each conflicted hunk independently** — a single file can conta
   same import added the same way), or one side's change is a strict superset of the other's with no
   semantic divergence. Resolve by keeping the superset/identical content, verify no line from either
   side's *unique* content was dropped, stage the file, and continue the rebase/merge.
+- **Regenerable** — the file is a committed artifact that a script owns: a known command regenerates it
+  from other files in the tree and overwrites it unconditionally, ignoring any conflict markers already
+  in it. Neither side's content is the right answer, because both were computed from trees that no
+  longer exist; the correct content is a fresh regeneration against the post-rebase tree. **Do not
+  hand-merge the diff and do not pick a side.** Leave the conflicted file as it is, run its regeneration
+  command, verify with the file's own `--check` command, then stage the file and continue the
+  rebase/merge. Known artifacts and their commands:
+  - `docs/plans/*/show-report.{json,html}` — `npm run fix:report` in Arcane's own repository (`spell
+    report` in a consumer), verified by `npm run check:report`. On a program's own `completed:` day the
+    regeneration must go in a **trailer-free, report-only commit** that touches nothing else, because
+    the close-commit logic counts any other commit made that day (recorded in
+    `docs/plans/upstream-intake-2026-09/PLAN.md`, "What this program taught").
+  - Self-hosted parity copies and client shims under `.arcane/`, `.github/`, `.claude/` and `.agents/`
+    in Arcane's own repository — `npm run fix:self-host-parity`, verified by
+    `npm run check:self-host-parity`. A compiled asset with its own `fix:*`/`check:*` pair in
+    `package.json` follows the same rule.
+  - `package-lock.json` — `npm install` against the rebased `package.json`, verified by `npm ci`.
+  A file you cannot name a regeneration command for is not regenerable: classify its hunks as mechanical
+  or ambiguous like any other, and never promote a hand-edited file to this class to avoid a STOP.
 - **Ambiguous** — the same lines changed with different intent, or you cannot establish with confidence
   that one side's content is a strict superset of the other's. **STOP.** Do not guess, do not pick a
   side, do not attempt a "reasonable-looking" merge of the two. Abort the in-progress rebase/merge
@@ -177,6 +198,8 @@ report the discrepancy rather than declaring the sync done.
 ```
 
 - If Step 3 resolved any mechanical conflicts, list exactly which files and what was kept from each side.
+- If Step 3 regenerated any artifact, name the file, the regeneration command that was run and the
+  `--check` command that verified the result.
 - If Step 3 aborted on an ambiguous conflict, this report never runs — Step 3's own STOP report is final.
 - Never delete the Step 1 recoverable ref as part of this report — that is the human's call.
 
@@ -185,6 +208,9 @@ report the discrepancy rather than declaring the sync done.
 - Never push with bare `--force` — only `--force-with-lease`, and never retry a rejected lease blindly.
 - Never guess on an ambiguous conflict — abort and hand off, every time, with no exception for
   "obviously trivial-looking" content on either side that this spell cannot independently verify.
+- Never hand-merge a script-regenerable artifact — regenerate it against the rebased tree and verify it
+  with its own check; and never classify a file as regenerable without naming the command that
+  regenerates it.
 - Never skip the recoverable ref (Step 1), even for a sync expected to be clean — the ref costs nothing
   and the alternative is an unrecoverable mistake on the case that turns out not to be clean.
 - Never report a sync as complete on a push success alone — provider verification (Step 5) is mandatory.

package/dist/assets/.github/prompts/spell-sync-pull-request.prompt.md

@@ -1,10 +1,10 @@
 ---
 name: Spell — Sync Pull Request
-description: Safely sync an open PR's branch with its target when it has fallen behind — recoverable pre-rebase ref, mechanical-vs-ambiguous conflict handling, force-with-lease push, provider-verified landing. Use when a PR needs rebasing onto a moved target, or was routed here from spell-create-pull-request/spell-ship's own conflict-stop points.
+description: Safely sync an open PR's branch with its target when it has fallen behind — recoverable pre-rebase ref, mechanical / regenerable / ambiguous conflict handling, force-with-lease push, provider-verified landing. Use when a PR needs rebasing onto a moved target, or was routed here from spell-create-pull-request/spell-ship's own conflict-stop points.
 claude_description: Use PROACTIVELY whenever an open PR has fallen behind its target branch and needs a safe rebase/sync, or when spell-create-pull-request/spell-ship stop on a conflict they route here.
 argument-hint: '[PR number or branch name]'
 agent: agent
-last_updated: 2026-08-31
+last_updated: 2026-10-01
 ---
 
 This prompt is the Arcane `spell-sync-pull-request` spell. Read [`.arcane/spells/spell-sync-pull-request.md`](../../.arcane/spells/spell-sync-pull-request.md) and follow it as the complete workflow.

package/dist/index.js

@@ -579,15 +579,10 @@ var COMPONENTS = [
     skipExisting: true,
     initOnly: true
   },
-  // Optional MCP config scaffold (BC-22/I12). skipExisting: a repo's own
-  // .mcp.json is user-owned server config Arcane must never overwrite.
-  // Not initOnly -- useful to retrofit via `spell add` on an existing repo too.
-  {
-    name: "mcp-config-template",
-    description: "Example .mcp.json with a per-server timeout, companion to the MCP fail-fast rule",
-    files: [".mcp.json"],
-    skipExisting: true
-  },
+  // NOTE: the `mcp-config-template` component (`.mcp.json`, BC-22/I12) was
+  // retired on 2026-10-02 -- see REGISTRY_RETIREMENTS. A root .mcp.json is
+  // live MCP config that clients execute, and the `full` profile's "*" put
+  // its example server in every full-profile repo (#328).
   {
     name: "records-conventions",
     description: "Supersession, tombstone, and retention conventions for records repositories",
@@ -937,6 +932,13 @@ var REGISTRY_RETIREMENTS = [
     successors: [],
     reason: "`.github/agents/*.agent.md` files are rendered per roster by `spell agents init` / `spell agents sync` (ARC-047), which a fixed-path component cannot do"
   },
+  {
+    name: "mcp-config-template",
+    kind: "component",
+    successors: [],
+    userOwned: true,
+    reason: "retired 2026-10-02 (#328): a root .mcp.json is live MCP config that clients execute, and the `full` profile installed its example server everywhere; set per-server timeouts in your own .mcp.json, which `spell doctor` checks"
+  },
   {
     name: "spell-prompts",
     kind: "component",
@@ -4803,7 +4805,8 @@ function formatRegistryChanges(changes) {
     lines.push("  Renamed or retired, still tracked here:");
     for (const entry of changes.retired) {
       const successor = entry.successors.length > 0 ? entry.successors.join(", ") : "no successor";
-      lines.push(`    ${entry.name} (${entry.kind}) \u2192 ${successor}: ${entry.reason}`);
+      const ownership = entry.userOwned ? " (user-owned: a copy you edited is released from tracking, never deleted)" : "";
+      lines.push(`    ${entry.name} (${entry.kind}) \u2192 ${successor}: ${entry.reason}${ownership}`);
     }
     lines.push(
       "    Nothing is deleted because of this list: their files go through the orphan handling above, which removes an untouched one only under `spell update --prune`."
@@ -5058,6 +5061,17 @@ async function resolveOrphan(targetDir, file, recordedHash, prune) {
   console.log(`  Pruned orphaned file: ${file}`);
   return "pruned";
 }
+async function isReleasableUserOwnedFile(targetDir, file, recordedHash) {
+  try {
+    validateTargetPath(targetDir, file);
+  } catch {
+    return false;
+  }
+  const filePath = join10(targetDir, file);
+  if (!await fileExists(filePath)) return false;
+  if (recordedHash === void 0) return true;
+  return !await fileMatchesHash(filePath, recordedHash);
+}
 async function retainReportedOrphan(targetDir, file, recordedHash, into) {
   try {
     validateTargetPath(targetDir, file);
@@ -5332,14 +5346,36 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     } catch (err) {
       if (err instanceof ComponentNotFoundError) {
         console.log(`  ! ${installed.name} not in registry \u2014 skipping.`);
+        const userOwned = REGISTRY_RETIREMENTS.some(
+          (r) => r.kind === "component" && r.name === installed.name && r.userOwned === true
+        );
+        const stillTracked = [];
         for (const file of installed.files) {
+          const recordedHash = installed.fileHashes?.[file];
+          if (userOwned && await isReleasableUserOwnedFile(targetDir, file, recordedHash)) {
+            console.log(
+              `  ${options.dryRun ? "[dry-run] Would release" : "Released"}: ${file} \u2014 yours (edited since Arcane wrote it, or never written by Arcane), no longer tracked. Delete it yourself if you do not want it.`
+            );
+            continue;
+          }
           const status = await resolveOrphan(
             targetDir,
             file,
-            installed.fileHashes?.[file],
+            recordedHash,
             Boolean(options.prune) && !options.dryRun
           );
           orphanReport.push({ file, status });
+          if (status === "reported") stillTracked.push(file);
+        }
+        if (userOwned && !options.dryRun) {
+          if (stillTracked.length === 0) continue;
+          const fileHashes2 = {};
+          for (const file of stillTracked) {
+            const hash = installed.fileHashes?.[file];
+            if (hash !== void 0) fileHashes2[file] = hash;
+          }
+          updatedComponents.push({ ...installed, files: stillTracked, fileHashes: fileHashes2 });
+          continue;
         }
         if (options.prune && !options.dryRun && installed.files.every((f) => orphanReport.find((o) => o.file === f)?.status !== "reported")) {
           continue;
@@ -6837,6 +6873,7 @@ async function checkGovernancePlaceholders(targetDir) {
   };
 }
 var UNOWNED_EXAMPLE_SCOPE = "@example/";
+var RETIRED_SCAFFOLD_PLACEHOLDER = "<your-mcp-server-package>";
 async function checkComponentRequires(targetDir) {
   const name = "Component prerequisites";
   let manifest;
@@ -6927,11 +6964,14 @@ async function checkMcpConfig(targetDir) {
     return { name, passed: true, blocking: false, message: "no MCP servers configured" };
   }
   const exampleHits = [];
+  const placeholderHits = [];
   for (const n of serverNames) {
     const args = servers[n]?.args;
     if (!Array.isArray(args)) continue;
     for (const a of args) {
-      if (typeof a === "string" && a.startsWith(UNOWNED_EXAMPLE_SCOPE)) exampleHits.push(`${n} (${a})`);
+      if (typeof a !== "string") continue;
+      if (a.startsWith(UNOWNED_EXAMPLE_SCOPE)) exampleHits.push(`${n} (${a})`);
+      if (a === RETIRED_SCAFFOLD_PLACEHOLDER) placeholderHits.push(n);
     }
   }
   if (exampleHits.length > 0) {
@@ -6942,13 +6982,21 @@ async function checkMcpConfig(targetDir) {
       message: `.mcp.json runs a package under the ${UNOWNED_EXAMPLE_SCOPE} scope nobody here owns: ${exampleHits.join(", ")}. The old \`spell init\` scaffold shipped it as a placeholder, and \`npx -y\` would run whoever publishes it. Replace the entry with your own MCP server package, or remove it; the file is yours, so doctor does not edit it`
     };
   }
+  if (placeholderHits.length > 0) {
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: `.mcp.json still holds the placeholder server from the retired mcp-config-template scaffold: ${placeholderHits.join(", ")} (${RETIRED_SCAFFOLD_PLACEHOLDER}). Clients load this file as live MCP config, so the placeholder fails on every session start. Delete the file if you run no MCP servers, or replace the entry with a real server package; the file is yours, so doctor does not edit it. An untouched scaffold is removed by \`spell update --prune\``
+    };
+  }
   const missingTimeout = serverNames.filter((n) => typeof servers[n]?.timeout !== "number");
   if (missingTimeout.length > 0) {
     return {
       name,
       passed: false,
       blocking: false,
-      message: `server(s) missing a "timeout": ${missingTimeout.join(", ")} \u2014 a hang runs to the client's own default idle limit (up to 30 min) instead of a predictable one`
+      message: `server(s) missing a "timeout": ${missingTimeout.join(", ")} \u2014 add "timeout": 30000 (milliseconds; Claude Code ignores a value below 1000) to each entry under mcpServers, so a stuck tool call ends after 30 s instead of running to the client's own idle limit (as long as 30 minutes)`
     };
   }
   return {