arcane-cli 0.22.13 → 0.23.0

package/dist/assets/.claude/commands/spell-sync-pull-request.md

@@ -0,0 +1,13 @@
+---
+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.
+---
+
+# Sync Pull Request
+
+Invoke the Arcane `spell-sync-pull-request` spell workflow.
+
+See the full prompt at `.github/prompts/spell-sync-pull-request.prompt.md` for the complete workflow definition.
+
+---
+
+@.github/prompts/spell-sync-pull-request.prompt.md

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

@@ -27,6 +27,7 @@ Related spells:
 - `spell-commit-work` — land your work as Conventional-Commits commits before opening the PR.
 - `spell-ship` — the broader release flow that records the PR URL after this spell creates it.
 - `spell-address-review` — resolve reviewer feedback once the PR is open.
+- `spell-sync-pull-request` — the recovery path when Step 0.6's rebase guard hits a conflict.
 
 ## Arguments
 
@@ -60,7 +61,7 @@ Before enabling auto-complete/auto-merge or completing an existing PR, resolve `
 3. **Ensure the branch is on origin (upstream):** if `git rev-parse --abbrev-ref --symbolic-full-name @{u}` fails, the branch was never pushed — run `git push -u origin <branch>`. The provider CLIs can only open a PR for a branch that exists on the remote.
 4. **STOP** if the branch has no commits ahead of the target: `git log origin/<target>..HEAD --oneline` is empty → nothing to PR.
 5. Check for an existing **open** PR for this branch (provider-specific, Step 2). If one exists, print its URL and stop — never create duplicates.
-6. **Mandatory rebase on target (governance guard):** `git fetch origin` then `git rebase origin/<target>`. On clean rebase, `git push --force-with-lease` (only if the branch existed remotely before the rebase). On conflicts: **STOP**, list conflicting files, ask the user to resolve; never push a branch that will produce a merge conflict on the target (see git-conventions "🛑 Agent-mandatory pre-PR guard"). This step is not optional and is not skippable by calling a different PR-creation tool.
+6. **Mandatory rebase on target (governance guard):** `git fetch origin` then `git rebase origin/<target>`. On clean rebase, `git push --force-with-lease` (only if the branch existed remotely before the rebase). On conflicts: **STOP**, list conflicting files, ask the user to resolve **or run `spell-sync-pull-request`** — it draws the same mechanical-vs-ambiguous conflict line this guard doesn't attempt to, with a recoverable ref before it touches anything; never push a branch that will produce a merge conflict on the target (see git-conventions "🛑 Agent-mandatory pre-PR guard"). This step is not optional and is not skippable by calling a different PR-creation tool.
 7. **Auto-suggest `--docs-only`** (only if not already passed): if every changed file vs target is documentation/session files (`*.md`, `TODO.md`, `DECISIONS.md`, `journal/**`, `IDEAS.md`, `FEEDBACK.md`), print a one-line hint suggesting `--docs-only` and proceed with the standard path.
 
 ## Step 1 — Gather context

package/dist/assets/.github/prompts/spell-ship.prompt.md

@@ -35,7 +35,7 @@ Workflow:
 2. **Sync with the target branch** — actually perform the sync, do not just assert it:
    - Run `git fetch origin` to get the latest refs.
    - Merge the target branch into the current branch (e.g. `git merge origin/<target>`).
-   - **On merge conflicts:** STOP and ask the user to resolve them. Do not attempt to auto-resolve.
+   - **On merge conflicts:** STOP and ask the user to resolve them, or run `spell-sync-pull-request` — it handles exactly this case, with a recoverable ref and an explicit mechanical-vs-ambiguous conflict boundary. Do not attempt to auto-resolve here.
    - After a clean merge (or once the user has resolved conflicts), re-run the full test suite and confirm it passes.
    - Push the synced branch (e.g. `git push`).
 

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

@@ -0,0 +1,160 @@
+---
+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.
+argument-hint: '[PR number or branch name]'
+agent: agent
+last_updated: 2026-08-31
+---
+
+## Executive Summary
+
+- This spell safely syncs an open PR's branch with its target branch once the target has moved ahead.
+- 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.
+- Every history-rewriting step is preceded by a recoverable ref, and every push uses
+  `--force-with-lease`, never bare `--force`.
+
+---
+
+Sync the specified PR's branch (or the current branch's own open PR) with its target branch.
+
+Context to consult:
+
+- `.arcane/governance/git-conventions.md` — the declared merge-strategy ladder (Merge no-fast-forward or
+  Rebase-and-fast-forward sanctioned; Squash and Semi-linear merge never sanctioned) and branch policy.
+- `.arcane/governance/testing-standards.md` — coverage thresholds for the post-replay gate re-run.
+
+Related spells:
+
+- `spell-create-pull-request` — routes here from its Step 0.6 conflict-stop; reuses its Step 2
+  provider-detection table rather than re-deriving it (D8).
+- `spell-ship` — routes here from its Step 2 conflict-stop.
+
+## Step 0 — Guard checks
+
+1. **Require a clean worktree.** Run `git status --porcelain`. Any output — staged, unstaged, or
+   untracked — **STOPS** this spell before it touches anything. Sync is not the place to also carry
+   uncommitted work through a rebase.
+2. **Resolve the active PR, source branch, base branch, and expected head SHA.** If a PR number or
+   branch name was given as an argument, resolve from that; otherwise resolve from
+   `git branch --show-current` and the open PR for it (reuse `spell-create-pull-request`'s Step 2
+   provider-detection and open-PR-lookup calls — same commands, not restated here). Record the
+   branch's current HEAD SHA now, before anything else runs — this is what "expected head SHA" means
+   for Step 5's post-push verification once rebase/replay changes it to a new value.
+3. **STOP** if no open PR is found for the resolved branch — this spell syncs an *existing* PR; if none
+   exists yet, direct the user to `spell-create-pull-request` first.
+
+## Step 1 — Create the recoverable ref
+
+Before any history-rewriting operation, tag the current HEAD so this sync is never a one-way door:
+
+```bash
+git tag "sync-backup/<branch>/$(date +%Y%m%d-%H%M%S)" HEAD
+```
+
+Report the tag name in the final output (Step 6). **Never delete this tag automatically** — leave it for
+the human to remove once they've confirmed the sync landed correctly; this spell only ever adds it.
+
+## Step 2 — Fetch and apply the declared merge policy
+
+```bash
+git fetch origin
+```
+
+Resolve the repository's actual merge-strategy ladder from `git-conventions.md` rather than assuming:
+
+- **Rebase-and-fast-forward** (the common case for a PR that's simply fallen behind): `git rebase origin/<target>`.
+- **Merge no-fast-forward** (when the repo's declared policy or the PR's own history indicates merge
+  commits are the norm here): `git merge origin/<target>`.
+- **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
+
+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.**
+
+If Step 2 reports conflicts, read every conflicted file's conflict markers before doing anything else,
+then classify **each conflicted hunk independently** — a single file can contain both kinds:
+
+- **Mechanically resolvable** — both sides made the identical change (e.g. the same formatting fix, the
+  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.
+- **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
+  (`git rebase --abort` / `git merge --abort`) so the branch is left exactly as it was, then report:
+  - The exact conflicting file(s) and hunk(s).
+  - Both sides' conflicting content, verbatim.
+  - That the recoverable ref from Step 1 still points at the pre-sync state.
+  - A direct instruction to resolve manually and re-run this spell, or to resolve and push directly.
+
+Never proceed past an ambiguous hunk on the theory that "the rest of the file is fine" — abort the whole
+operation and hand off, per the line above.
+
+## Step 4 — Re-run project gates before pushing
+
+A clean replay is not the same as a working tree. Before pushing:
+
+```bash
+npm run typecheck && npm run lint && npm run test
+```
+
+If this repository has `check:version-bump` and the sync touched any distributable path, run it too. **A
+gate failure here is the same class of stop as an ambiguous conflict** — do not push a tree that fails
+its own gates just because the git-level replay succeeded. Report which gate failed and stop; the
+recoverable ref from Step 1 is still available.
+
+## Step 5 — Push and verify
+
+```bash
+git push --force-with-lease
+```
+
+- **On success:** proceed to provider verification below.
+- **On lease rejection** (the remote moved again since this sync's own Step 2 fetch — someone else
+  pushed to the branch in the meantime): **do not retry with `--force`, and do not retry
+  `--force-with-lease` blindly.** Re-fetch and re-evaluate from Step 2 as if starting over — the branch
+  state this sync was built against no longer exists. This is a genuinely new sync, not a retry of the
+  same one.
+
+**Provider verification (never assume a successful push means the PR reflects it):**
+
+| Provider | Verify |
+| --- | --- |
+| GitHub | `gh pr view <PR#> --json headRefOid,mergeable` — `headRefOid` must equal the new HEAD SHA from Step 5; `mergeable` should not report a conflict state. |
+| Azure DevOps | `az repos pr show --id <PR_ID> --output json --query "{sha:lastMergeSourceCommit.commitId, status:mergeStatus}"` — the SHA must equal the new HEAD; `status` should not report `conflicts`. |
+
+If the reported SHA does not match, or the mergeable/status field reports a conflict despite a clean
+local push, **do not report success** — this is the exact "dispatched is not succeeded" gap EF-21
+already established for `spell-close-session`; a push completing without error is dispatched, not
+verified. Re-check once after a short wait (provider APIs can lag); if it still doesn't match, stop and
+report the discrepancy rather than declaring the sync done.
+
+## Step 6 — Report
+
+```
+✓ PR synced: <URL>
+  Branch:          <branch> → <target>
+  Method:          rebase-and-fast-forward | merge-no-fast-forward
+  Conflicts:       none | resolved (mechanical) | none — no rebase needed
+  Recoverable ref: sync-backup/<branch>/<timestamp>
+  New head SHA:    <sha> (provider-confirmed)
+```
+
+- If Step 3 resolved any mechanical conflicts, list exactly which files and what was kept from each side.
+- 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.
+
+## Rules
+
+- 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 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.
+- Never delete the recoverable ref automatically.

package/dist/index.js

@@ -492,10 +492,12 @@ var COMPONENTS = [
   },
   {
     name: "spells-delivery",
-    description: "Pull-request lifecycle \u2014 open a PR, respond to review feedback",
+    description: "Pull-request lifecycle \u2014 open a PR, sync a stale one, respond to review feedback",
     files: [
       ".github/prompts/spell-create-pull-request.prompt.md",
       ".claude/commands/spell-create-pull-request.md",
+      ".github/prompts/spell-sync-pull-request.prompt.md",
+      ".claude/commands/spell-sync-pull-request.md",
       ".github/prompts/spell-address-review.prompt.md",
       ".claude/commands/spell-address-review.md"
     ]
@@ -3595,8 +3597,8 @@ Run \`spell unblock-push\` first (interactive), then uninstall.`
 // src/commands/doctor.ts
 import { access as access4, readFile as readFile6, mkdir as mkdir6, copyFile as fsCopyFile2 } from "fs/promises";
 import { join as join11, dirname as dirname3 } from "path";
-import { execFile as execFile2 } from "child_process";
-import { promisify } from "util";
+import { execFile as execFile3 } from "child_process";
+import { promisify as promisify2 } from "util";
 
 // src/config/incidents.ts
 var INCIDENT_QUEUE = [
@@ -3663,8 +3665,177 @@ function evaluateIncidentGate(records) {
   };
 }
 
-// src/commands/doctor.ts
+// src/modules/platform-policy.ts
+import { execFile as execFile2 } from "child_process";
+import { promisify } from "util";
 var execFileAsync = promisify(execFile2);
+var SANCTIONED_MERGE_METHODS = ["merge", "rebase"];
+function compareToLadder(effective, declaredButBlocked, interactionNote) {
+  const disallowedButPermitted = effective.filter(
+    (m) => !SANCTIONED_MERGE_METHODS.includes(m)
+  );
+  const missingSanctioned = SANCTIONED_MERGE_METHODS.filter(
+    (m) => !effective.includes(m)
+  );
+  const passed = disallowedButPermitted.length === 0 && missingSanctioned.length === 0;
+  const messages = [];
+  if (interactionNote) messages.push(interactionNote);
+  if (disallowedButPermitted.length > 0) {
+    messages.push(
+      `disallowed method(s) effectively permitted: ${disallowedButPermitted.join(", ")} (never sanctioned per git-conventions.md)`
+    );
+  }
+  if (missingSanctioned.length > 0) {
+    messages.push(
+      `sanctioned method(s) not effectively available: ${missingSanctioned.join(", ")}`
+    );
+  }
+  return {
+    passed,
+    effectiveMergeMethods: effective,
+    declaredButBlocked,
+    disallowedButPermitted,
+    message: passed ? `effective merge methods [${effective.join(", ")}] match the declared ladder` : messages.join("; ")
+  };
+}
+function evaluateGitHubMergePolicy(rulesets) {
+  const active = rulesets.filter(
+    (r) => r.enforcement === "active" && r.target === "branch"
+  );
+  if (active.length === 0) {
+    return {
+      passed: false,
+      effectiveMergeMethods: null,
+      declaredButBlocked: [],
+      disallowedButPermitted: [],
+      message: "No active branch ruleset covers the target branch (checked via Rulesets, not the classic protection endpoint, which false-negatives on Rulesets-only repos)."
+    };
+  }
+  let allowedMergeMethods = null;
+  let hasRequiredLinearHistory = false;
+  for (const ruleset of active) {
+    for (const rule of ruleset.rules) {
+      if (rule.type === "required_linear_history") {
+        hasRequiredLinearHistory = true;
+      }
+      if (rule.type === "pull_request") {
+        const methods = rule.parameters?.["allowed_merge_methods"];
+        if (Array.isArray(methods)) {
+          const typed = methods;
+          allowedMergeMethods = allowedMergeMethods === null ? typed : allowedMergeMethods.filter((m) => typed.includes(m));
+        }
+      }
+    }
+  }
+  const nominal = allowedMergeMethods ?? ["merge", "squash", "rebase"];
+  const effective = hasRequiredLinearHistory ? nominal.filter((m) => m !== "merge") : nominal;
+  const declaredButBlocked = hasRequiredLinearHistory && nominal.includes("merge") ? ["merge"] : [];
+  const interactionNote = declaredButBlocked.length > 0 ? `allowed_merge_methods declares [${nominal.join(", ")}] but a required_linear_history rule silently blocks merge commits regardless -- effective methods are [${effective.join(", ")}]` : void 0;
+  return compareToLadder(effective, declaredButBlocked, interactionNote);
+}
+async function fetchGitHubRulesets(owner, repo) {
+  try {
+    const { stdout: listOut } = await execFileAsync("gh", [
+      "api",
+      `repos/${owner}/${repo}/rulesets`
+    ]);
+    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}`
+        ]);
+        return JSON.parse(stdout);
+      })
+    );
+    return detailed;
+  } catch {
+    return null;
+  }
+}
+function evaluateAdoMergePolicy(policies) {
+  const enabled = policies.filter((p) => p.isEnabled);
+  if (enabled.length === 0) {
+    return {
+      passed: false,
+      effectiveMergeMethods: null,
+      declaredButBlocked: [],
+      disallowedButPermitted: [],
+      message: 'No enabled "Limit merge types" branch policy found for the target branch.'
+    };
+  }
+  const effective = /* @__PURE__ */ new Set();
+  for (const policy of enabled) {
+    const s = policy.settings ?? {};
+    if (s.allowNoFastForward) effective.add("merge");
+    if (s.allowRebase || s.allowRebaseMerge) effective.add("rebase");
+    if (s.useSquashMerge) effective.add("squash");
+  }
+  return compareToLadder([...effective], []);
+}
+async function fetchAdoMergeTypePolicies(org, project, repoName, branch) {
+  try {
+    const orgUrl = `https://dev.azure.com/${org}`;
+    const { stdout: repoOut } = await execFileAsync("az", [
+      "repos",
+      "show",
+      "--repository",
+      repoName,
+      "--org",
+      orgUrl,
+      "--project",
+      project,
+      "--query",
+      "id",
+      "--output",
+      "tsv"
+    ]);
+    const repositoryId = repoOut.trim();
+    if (!repositoryId) return null;
+    const { stdout } = await execFileAsync("az", [
+      "repos",
+      "policy",
+      "list",
+      "--repository-id",
+      repositoryId,
+      "--branch",
+      branch,
+      "--org",
+      orgUrl,
+      "--project",
+      project,
+      "--output",
+      "json"
+    ]);
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}
+function parseGitHubRemote(url) {
+  const match = /github\.com[/:]([^/]+)\/([^/.]+?)(?:\.git)?\/?$/.exec(url);
+  if (!match) return null;
+  const [, owner, repo] = match;
+  if (!owner || !repo) return null;
+  return { owner, repo };
+}
+function parseAdoRemote(url) {
+  const modern = /dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/([^/?]+)/.exec(url);
+  if (modern) {
+    const [, org, project, repo] = modern;
+    if (org && project && repo) return { org, project, repo };
+  }
+  const legacy = /([^./]+)\.visualstudio\.com\/([^/]+)\/_git\/([^/?]+)/.exec(url);
+  if (legacy) {
+    const [, org, project, repo] = legacy;
+    if (org && project && repo) return { org, project, repo };
+  }
+  return null;
+}
+
+// src/commands/doctor.ts
+var execFileAsync2 = promisify2(execFile3);
 async function checkNodeVersion() {
   const name = "Node.js version";
   const raw = process.version;
@@ -3702,7 +3873,7 @@ async function checkVSCodeExtension(id, label) {
   let installBin = "code";
   for (const bin of ["code", "code-insiders"]) {
     try {
-      await execFileAsync(bin, ["--version"]);
+      await execFileAsync2(bin, ["--version"]);
       installBin = bin;
       break;
     } catch {
@@ -3894,6 +4065,49 @@ async function checkPushPolicy(targetDir) {
     message: `declared "blocked" but not enforced \u2014 ${missing.join("; ")}. The manifest claims a protection this repository does not have.`
   };
 }
+async function checkPlatformBranchPolicy(targetDir) {
+  const name = "Platform branch/merge policy (T11)";
+  const targets = await pushTargets(targetDir);
+  const origin = targets.find((t) => t.remote === "origin") ?? targets[0];
+  const url = origin?.urls[0];
+  if (!url) {
+    return { name, passed: true, message: "no remote configured \u2014 nothing to check", blocking: false };
+  }
+  const github = parseGitHubRemote(url);
+  if (github) {
+    const rulesets = await fetchGitHubRulesets(github.owner, github.repo);
+    if (rulesets === null) {
+      return {
+        name,
+        passed: false,
+        blocking: false,
+        message: `could not query GitHub Rulesets for ${github.owner}/${github.repo} \u2014 is \`gh\` installed and authenticated? Verify manually: gh api repos/${github.owner}/${github.repo}/rulesets`
+      };
+    }
+    const result = evaluateGitHubMergePolicy(rulesets);
+    return { name, passed: result.passed, blocking: false, message: result.message };
+  }
+  const ado = parseAdoRemote(url);
+  if (ado) {
+    const policies = await fetchAdoMergeTypePolicies(ado.org, ado.project, ado.repo, "main");
+    if (policies === null) {
+      return {
+        name,
+        passed: false,
+        blocking: false,
+        message: `could not query the Azure DevOps "Limit merge types" branch policy for ${ado.org}/${ado.project}/${ado.repo} \u2014 is \`az\` installed and authenticated? Verify manually in the ADO web UI under Branch Policies.`
+      };
+    }
+    const result = evaluateAdoMergePolicy(policies);
+    return { name, passed: result.passed, blocking: false, message: result.message };
+  }
+  return {
+    name,
+    passed: true,
+    blocking: false,
+    message: "remote is neither GitHub nor Azure DevOps \u2014 platform policy verification not available for this provider"
+  };
+}
 async function runDoctor(targetDir, options = {}, assetsDir) {
   console.log("\nspell doctor \u2014 checking your Arcane environment\n");
   const results = await Promise.all([
@@ -3902,7 +4116,8 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     checkArcaneManifest(targetDir),
     Promise.resolve(checkIncidentReleaseGate()),
     checkPullRebase(targetDir),
-    checkPushPolicy(targetDir)
+    checkPushPolicy(targetDir),
+    checkPlatformBranchPolicy(targetDir)
   ]);
   const sessionResults = await checkSessionContinuity(targetDir);
   results.push(...sessionResults);