arcane-cli 0.22.1 → 0.22.3

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

@@ -376,6 +376,8 @@ git branch -d type/old-topic            # delete local branch
 git push origin --delete type/old-topic  # delete remote branch (safety net; ignore 'does not exist' errors if already auto-deleted)
 ```
 
+**If `git branch -d` refuses with `error: the branch '<branch>' is not fully merged`, do not assume the branch is genuinely unmerged and do not reach for `-D` on that reading alone** — this repo's own sanctioned Rebase-and-fast-forward strategy (and any pre-ARC-009 squash merge) rewrites commit SHAs, so a fully-landed branch is permanently invisible to `-d`'s ancestry check. See **Content-Verified Branch Deletion** below for the actual procedure.
+
 **From a linked worktree, do not run the block above** (ARC-028 R8). `git checkout main` fails with
 `fatal: 'main' is already used by worktree at <path>` when the primary checkout holds it, and
 `git branch -d` fails with `error: cannot delete branch '<branch>' used by worktree at <path>` for
@@ -397,6 +399,19 @@ refusing to delete a worktree-attached one, are the enforcement ARC-028 R3/R7 re
 
 This applies to all actors — humans, interactive tools (Copilot, Claude), and autonomous agents. The `spell-commit-work` and `spell-close-session` prompts enforce this check.
 
+### Content-Verified Branch Deletion (TODO.md merged-branch-cleanup finding)
+
+Ancestry (`git branch --merged`, plain `git branch -d`) is not a reliable "is this landed?" test on this repo. Two of this repo's own sanctioned states defeat it identically: **Rebase-and-fast-forward** (ARC-009 §7) and any **pre-ARC-009 squash merge** both rewrite commit SHAs, so a fully-landed branch stays permanently invisible to `--merged` and refused by `-d` — not a rare edge case; every branch merged the sanctioned way hits this. Verify by content instead, for any local branch except `<trunk>` and any branch currently attached to another worktree (`git worktree list`):
+
+1. **Fetch first.** `git fetch <remote> --prune` — a stale local `<trunk>` under-counts and produces a false "unmerged" reading.
+2. **Prefer the provider's own record when a PR exists.** `gh pr list --head <branch> --state all` (or `az repos pr list --source-branch <branch> --status all`) — a confirmed `MERGED`/`completed` status is the fastest, most authoritative signal and needs no further check.
+3. **Otherwise, check patch-id equivalence:** `git cherry <remote>/<trunk> <branch>`. Every `-`-prefixed line is patch-id-identical to a commit already on `<trunk>` — safe. A `+`-prefixed line means "no identical patch found," not "definitely unmerged": a squash merge, or independent re-authoring of the same change, produces a *different* patch-id for *identical resulting content*. Before concluding a `+` commit is genuinely unmerged, check whether its actual content already exists on `<trunk>` (search for the added text, or diff the specific file). This is not hypothetical — confirmed live 2026-08-31 (BC-03): two docs-only commits on one branch both showed `+` via `git cherry`, and both were byte-identical to content that had already landed on `<trunk>` through separate, differently-authored commits.
+4. **Delete with `-D`, never plain `-d`**, only branches with **zero** real unmerged content (confirmed by step 2 or step 3) — `-d` will refuse on a rewritten SHA even when the branch is fully landed, which is the whole reason this section exists. Then `git push <remote> --delete <branch>` (ignore "does not exist" if already auto-deleted).
+5. **A branch that fails verification is a finding to surface, not an obstacle.** Report it with a one-line summary of what its unmerged commit(s) actually contain, so a human can decide land vs. abandon. Do not delete it, and do not silently drop it from the report either — in a 2026-08-21 field test, content verification cleared 17 of 18 candidate branches as landed and caught the 1 genuinely unmerged branch a naive `-D` sweep would have destroyed.
+6. **Idempotent by construction:** an already-deleted branch is simply absent from the next sweep's candidate list; a branch that failed verification is safely re-checked (and re-reported if still unresolved) on every run rather than being deleted or forgotten.
+
+Apply the Same-Vantage-Point Check below before any deletion if this repository or its linked worktrees might be reached through more than one filesystem view. `spell-close-session` runs this as an idempotent sweep every session; `spell-open-session`'s stale-branch check uses the same procedure for its read-only candidate list.
+
 ### Same-Vantage-Point Check (EF-33 / ARC-028 R7)
 
 `git worktree list` can **truthfully** report a live, healthy linked worktree as `prunable` when read through a cross-filesystem bridge — a Linux-side mount of a Windows host, a remote-mounted volume, a container bind-mount, any path-translation layer between the reading process and the repository's actual owning environment. The registered absolute path simply doesn't resolve from that vantage point, even though the directory exists and is valid from the machine that owns it. Nothing in Git's own output distinguishes "confirmed absent" from "not resolvable from this process's filesystem view" — both render identically as `prunable`. (A separate, unconditional hazard applies to `git branch --merged` regardless of vantage point — see the note at the end of this section; do not assume that one only matters when a bridge is in play.)
@@ -410,7 +425,7 @@ This applies to all actors — humans, interactive tools (Copilot, Claude), and
 
 This is documented as a standing operational caution, not a code-level gate: EF-33's own intake report frames the underlying defect as cross-machine/cross-mount filesystem visibility, which no single CI runner can reproduce — the confirmation step above must be followed manually by whichever human or agent is about to run the destructive command. Confirmed as a live near-miss on 2026-08-03: a Linux-side read reported eight healthy linked worktrees `prunable`; the same repository read from Windows (their actual owning environment) showed zero prunable entries, and `git worktree prune -v` there removed nothing.
 
-**Unconditional, vantage-point-independent note on branch deletion:** `git branch --merged` can also report a fully-landed branch as unmerged — or the reverse confusion, a branch never actually reviewed but ancestry-visible — because Git's rebase-and-fast-forward and squash merge strategies (both sanctioned by this repo's own merge-strategy table above) rewrite commit SHAs, defeating ancestry-based detection. This has nothing to do with filesystem bridges — it fires identically on a single machine with no mount involved. See the ancestry-vs-content-verification finding in `TODO.md`'s PR Workflow section for the full mechanism; verify branch content before deleting regardless of what vantage-point confidence steps 1-4 above establish.
+**Unconditional, vantage-point-independent note on branch deletion:** `git branch --merged` can also report a fully-landed branch as unmerged, because Git's rebase-and-fast-forward and squash merge strategies (both sanctioned by this repo's own merge-strategy table above) rewrite commit SHAs, defeating ancestry-based detection. This has nothing to do with filesystem bridges — it fires identically on a single machine with no mount involved. See **Content-Verified Branch Deletion** above for the actual procedure; verify branch content before deleting regardless of what vantage-point confidence steps 1-4 above establish.
 
 ### ADO PR Lifecycle — Complete Command Reference
 
@@ -476,7 +491,8 @@ git push origin --delete <branch>         # delete remote branch (safety net —
 | `gh pr create` not found                                                       | `gh` CLI not installed                | Use `az repos pr create`                                                        |
 | `creatorVoteCounts` is false on branch policy                                  | Vote registers but PR still blocked   | A second human must approve via ADO web UI                                      |
 | `az repos pr update --status completed` returns `status: active` without error | PR silently not merged                | Add `--squash false` to the command; the flag triggers the merge path correctly |
-| `git branch -d <branch>` fails after merge                                     | Branch is attached to a worktree      | Skip local delete; run remote delete + prune                                    |
+| `git branch -d <branch>` fails after merge, `error: cannot delete branch ... used by worktree` | Branch is attached to a worktree      | Skip local delete; run remote delete + prune                                    |
+| `git branch -d <branch>` fails after merge, `error: ... is not fully merged`   | Rebase/squash rewrote the branch's SHAs — see Content-Verified Branch Deletion above | Verify by content (`git cherry` or PR status), then `-D` only what passes        |
 | `git push origin --delete <branch>` fails with missing ref                     | Branch already deleted remotely       | Treat as non-fatal and continue                                                 |
 
 ### Branch Lifecycle

package/dist/assets/.github/prompts/spell-close-session.prompt.md

@@ -173,7 +173,7 @@ Rules:
    - If this worktree was created with `--detach` there is no branch to name; report the path and the detached HEAD sha instead.
    - Verify the merge landed with `git log --oneline -3 <remote>/<trunk>` (the remote-tracking ref), since local `<trunk>` is not checked out here to fast-forward.
 
-   - Common to both: if stale local branches exist (merged or older than 7 days), list them and suggest cleanup.
+   - **Common to both: run the idempotent, content-verified branch sweep** (TODO.md's merged-branch-cleanup finding) — not merely a list-and-suggest step. For every local branch except `<trunk>` and any branch attached to another worktree, apply [Content-Verified Branch Deletion](../../.arcane/governance/git-conventions.md#content-verified-branch-deletion-todomd-merged-branch-cleanup-finding) (git-conventions.md): fetch first, prefer a confirmed PR-merged status when one exists, otherwise verify by `git cherry` patch-id equivalence *and* a resulting-content check for `+`-flagged commits (a squash or independently re-authored commit can carry already-landed content under a different patch-id). Actually delete (`-D`, never `-d`) every branch that verifies as fully landed, local and remote. Report — do not delete — any branch with genuine unmerged content; a one-line summary of what it holds is enough for a human to decide land vs. abandon. Apply the Same-Vantage-Point Check (EF-33) before any deletion if the repository or its linked worktrees might be reached through more than one filesystem view. Safe to run every session: an already-clean branch list is simply a no-op.
    - See [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) Post-Merge Cleanup section.
 
 11. **Return a concise closure report.**

package/dist/assets/.github/prompts/spell-open-session.prompt.md

@@ -83,7 +83,7 @@ Before anything else, check:
   - Disallow random adjective-noun generator names (example: `ideal-disco`) as session defaults.
   - If current branch is non-compliant and no active PR depends on it, record the required rename for the Mutation Guard. Do not rename during a read-only session.
   - If an active PR uses the old branch name, do not force-delete the old remote branch; flag it and continue with a follow-up rename plan.
-- **Stale local branches:** Run `git branch --merged main` to list branches already merged that should be deleted. This lists candidates only — before deleting any, apply the same-vantage-point check (EF-33) and, separately, verify by content rather than trusting ancestry alone (rebase-and-fast-forward merges are invisible to `--merged`; see the merged-branch cleanup item in TODO.md).
+- **Stale local branches:** Run `git branch --merged main` to list branches already merged that should be deleted — this session's own read-only candidate list (`--merged` also misses every branch landed via this repo's sanctioned rebase-and-fast-forward, so treat a *clean* result as "no ancestry-visible candidates," not "nothing to check"). Open-session only lists; it does not delete. Apply the [Content-Verified Branch Deletion](../../.arcane/governance/git-conventions.md#content-verified-branch-deletion-todomd-merged-branch-cleanup-finding) procedure (git-conventions.md) to any candidate before flagging it as safe, and leave the actual idempotent prune to `spell-close-session`'s sweep.
 - **Tracker configuration check (early):** resolve active tracking settings before planning, in this order: root `.arcane.json` (if present) -> the committed self-hosted source manifest (`src/assets/.arcane.json`, read only when it declares `selfHosted: true` -- this is EF-14's recorded self-hosting resolution tier, distinct from treating the mere presence of a self-host marker as license to infer other, unrelated config) -> the current feature PRD frontmatter -> ask. Persisted once at `spell init`/`spell update` (EF-14); do not re-ask when any of the first three sources already sets it.
   - `tracking_mode: internal | external`
   - `external_provider: ado | jira | other`

package/dist/assets/.github/prompts/spell-review-batch.prompt.md

@@ -51,6 +51,7 @@ For each PR in the batch, independently:
 1. Fetch the PR diff and metadata (`gh pr diff <n>` / `az repos pr show --id <n>` + diff). If a PR can't be fetched (deleted, no access, network error), **skip it, record it as `SKIPPED` with the reason, and continue** — never abort the whole batch for one bad PR.
 2. Run the `spell-review` workflow against that diff — the full dimension-coverage sweep (correctness, security, performance, tests, naming/clarity, architecture), severity-ranked findings (`HIGH` / `MEDIUM` / `LOW`, matching the `spell-review` ladder) with stable IDs, and the PASS/WARN/FAIL coverage table.
 3. Record a per-PR result: verdict (**approve** / **request-changes**), finding counts by severity, and the coverage table.
+4. **Post the formal round state per PR** — apply `spell-review`'s step 10 ([ARC-035](../../DECISIONS.md#arc-035--auto-merge-requires-a-clear-review-round) decision 3) to *this* PR's number, not just this workflow's own single-run PR: a **request-changes** verdict posts `gh pr review <n> --request-changes` (or `az repos pr set-vote --id <n> --vote reject`); a re-review that clears a round this batch previously blocked dismisses/supersedes that prior review. An **approve** verdict posts nothing. Never let a posting failure (unauthenticated CLI, PR closed mid-batch) skip or abort the remaining PRs in the batch — record the result already computed and continue.
 
 Reviews are adversarial — actively look for problems, do not just confirm quality. Apply the same no-fabrication coverage mandate as `spell-review`: a clean lens is reported as "no issues," never padded.
 

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

@@ -122,6 +122,16 @@ Workflow:
 
 9. **Write back to the pull request** — when a PR exists for these changes, sync a short verdict plus a findings summary (verdict + finding counts/IDs + a pointer to the saved report) into the PR body/description. Use provider-agnostic phrasing that works for either GitHub or Azure DevOps. Mark it clearly as a snapshot at review time, and fall back to a top-level PR comment if the description can't be updated.
 
+10. **Post the formal round state** ([ARC-035](../../DECISIONS.md#arc-035--auto-merge-requires-a-clear-review-round) decision 3) — step 9's write-back is a human-readable summary; this is the separate, machine-readable signal the `Review round clear` required check actually reads. Only a confirmed blocker posts a formal review — an `APPROVE` or `DEFER` verdict posts nothing here, preserving the zero-friction path for PRs nobody formally blocks:
+    - **REQUEST CHANGES verdict:**
+      - GitHub: `gh pr review <n> --request-changes --body "<one-line blocker summary + pointer to the saved report>"`.
+      - Azure DevOps: `az repos pr set-vote --id <n> --vote reject` — the same primitive `spell-commit-work.prompt.md`'s author-side self-approval step already uses (`az repos pr set-vote --vote approve`), applied to the reviewer side.
+    - **Closing a round you previously blocked** (a later pass confirms the blocker is fixed) — do this explicitly; `dismiss_stale_reviews_on_push` is `false` on this repository's ruleset, so a later push never clears it automatically:
+      - GitHub: find the blocking review's ID (`gh api repos/{owner}/{repo}/pulls/<n>/reviews --jq '.[] | select(.state=="CHANGES_REQUESTED") | .id'`), then dismiss it — `gh api -X PUT repos/{owner}/{repo}/pulls/<n>/reviews/<review_id>/dismissals -f event=DISMISS -f message="<why this is now resolved, referencing the fix commit>"`.
+      - Azure DevOps: `az repos pr set-vote --id <n> --vote approve` (or reset to no-vote per team convention).
+    - Degrade silently if the CLI is unauthenticated or the PR can't be resolved (e.g. no PR exists yet for a local-only review) — never let this step abort a review that otherwise completed; the findings, report, and step 9 write-back still stand on their own.
+    - **GitHub refuses a REQUEST CHANGES verdict from the PR's own author** (`GraphQL: Review Can not request changes on your own pull request`, verified live 2026-08-31 — the same restriction as self-approval, just previously untested). When you are reviewing your own authored PR under the same GitHub identity, this call will fail with exactly that error: treat it as expected, not a bug, and fall back to the step 9 write-back as the only signal available — a formal blocking review needs a genuinely distinct reviewer identity (a second collaborator, or a separate bot/service account).
+
 Rules:
 - **Cover every dimension, not a finding count.** You MUST explicitly address each lens — correctness, security, performance, tests, naming/clarity, architecture — and state "no issues" for any lens that is clean. There is no minimum number of findings: zero findings is a valid outcome on a clean or small diff. The mandate is coverage of effort, not a count of findings — never fabricate issues to hit a quota.
 - **Never rubber-stamp.** Every review must include substantive analysis across all dimensions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-cli",
-  "version": "0.22.1",
+  "version": "0.22.3",
   "description": "Arcane framework CLI — scaffold and manage governance files in consuming repositories",
   "keywords": [
     "arcane",
@@ -44,6 +44,7 @@
     "fix:self-host-parity": "tsx scripts/self-host-parity.ts --fix",
     "check:adr-references": "tsx scripts/check-distributed-adr-references.ts",
     "check:version-bump": "tsx scripts/check-version-bump.ts",
+    "check:review-round": "tsx scripts/check-review-round.ts",
     "prepare": "husky"
   },
   "dependencies": {