arcane-cli 0.22.2 → 0.22.4

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/.arcane/governance/naming-conventions.md

@@ -92,6 +92,19 @@ Arcane ships with twelve default agent personas, organized by functional cluster
 
 Twelve legendary agents — the Arcanos. Every namesake is public domain: golden-age stage magicians (Kellar, Lafayette, Adelaide, Alexander, Bess), myth and classic literature (Merlin, Circe, Iris, Prospero, Mercurio), and coinages from living vocabulary (Lince — *ojo de lince*; Custodio — *ángel custodio*). Lince is never anglicized.
 
+### Agent Definition Schema — Fields for Template/Renderer Authors
+
+The table above is the human-readable roster; agent definitions (`agents/*.yaml`) and the generated roster (`.arcane/agents.yaml`) carry the same data as structured fields. This is where they live, for anyone building a third-party renderer (DMC is renderer #1):
+
+| Field | Lives on | Populated by | Consumed by |
+| --- | --- | --- | --- |
+| `persona.description` / `behavioral_rules` | Agent definition (role-level, naming-strategy-agnostic) | Template author | Every client renderer (Copilot, Claude, Codex, OpenClaw) |
+| `persona.personality` / `persona.voice` / `persona.catchphrases` | Agent definition | Template author | Renderers that want tone/flavor beyond the bare role |
+| `persona.visual_description` | Agent definition | Template author | **Declared, not yet rendered by any client this repo ships.** Kept with the definition rather than a renderer, by design — data belongs with the thing it describes, not with any one consumer. A third-party image/avatar renderer reads this field directly from the YAML; no other wiring is required. |
+| `epithet` (e.g. "the Archmage") | **Roster entry**, not the agent definition — see below | Naming strategy (`arcanos` only; `generic`/`random`/`custom` are deliberately epithet-less) | `.arcane/generated/openclaw-roster.json`'s `identity.epithet`, when present |
+
+**Why `epithet` is schema v2's roster field, not a persona field:** an agent definition YAML (e.g. `architecture-lead.yaml`) is a role archetype reused across every naming strategy — "the Archmage" belongs to the persona *Merlin*, not to the "architecture-lead" role itself. Putting it in the definition would leak Arcanos-specific flavor into naming strategies designed to be epithet-neutral (`generic`'s plain role labels). It is populated during `spell agents init`'s naming step and flows through the roster entry (`.arcane/agents.yaml`) to `openclaw-roster.json` — never guessed or re-derived by a renderer.
+
 **Role consolidation (ADR-031):** Framework-specific dev roles (.NET, Blazor, React, Flutter, MAUI) are consolidated into generic roles (Full-Stack, Frontend, Mobile). The framework/stack is a prompt parameter, not an agent identity. This scales without needing a new agent for every technology.
 
 **Naming policy:** All agent names should be positive characters — beings, not objects — with a clear thematic connection to their role.

package/dist/assets/.github/agents/mercurio.agent.md

@@ -35,7 +35,7 @@ deliverables; every word in motion.
 - Follow platform guidelines (HIG for iOS, Material Design for Android)
 - App store submissions require a complete release checklist — no shortcuts
 - Performance profiling is required before marking any feature complete
-- [object Object]
+- Backward compatibility: support at least the two previous major OS versions
 
 ## Tools
 

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/index.js

@@ -946,6 +946,20 @@ var ARCANOS_NAME_MAP = {
   "collaborator": "Iris",
   "security-ops": "Custodio"
 };
+var ARCANOS_EPITHET_MAP = {
+  "orchestrator": "the Maestro",
+  "architecture-lead": "the Archmage",
+  "fullstack-dev": "the Conjuror",
+  "qa-lead": "the Unmasker",
+  "devops": "the Stormcaller",
+  "frontend-dev": "the Illusionist",
+  "mobile-dev": "the Swift",
+  "research-analyst": "the Man Who Knows",
+  "marketing-strategist": "the Charmweaver",
+  "operations-comms": "the Herald",
+  "collaborator": "the Emissary",
+  "security-ops": "the Warden"
+};
 var RANDOM_NAME_POOL = [
   "Aiden",
   "Blake",
@@ -985,10 +999,11 @@ function applyGenericNames(roleIds) {
   }));
 }
 function applyArcanosNames(roleIds) {
-  return roleIds.map((id) => ({
-    definition: id,
-    name: ARCANOS_NAME_MAP[id] ?? GENERIC_NAME_MAP[id] ?? id
-  }));
+  return roleIds.map((id) => {
+    const name = ARCANOS_NAME_MAP[id] ?? GENERIC_NAME_MAP[id] ?? id;
+    const epithet = ARCANOS_NAME_MAP[id] ? ARCANOS_EPITHET_MAP[id] : void 0;
+    return epithet ? { definition: id, name, epithet } : { definition: id, name };
+  });
 }
 function applyRandomNames(roleIds) {
   const shuffled = [...RANDOM_NAME_POOL].sort(() => Math.random() - 0.5);
@@ -1182,6 +1197,7 @@ function validateAgentRoster(value, source) {
       requireString(item.definition, `roster[${index}].definition`, issues);
       if (item.name !== null) requireString(item.name, `roster[${index}].name`, issues);
       requireString(item.id, `roster[${index}].id`, issues);
+      if (item.epithet !== void 0) requireString(item.epithet, `roster[${index}].epithet`, issues);
     });
   }
   if (issues.length > 0) throw new AgentConfigValidationError(source, issues);
@@ -1442,6 +1458,7 @@ ${rows}
 async function syncAgents(targetDir, assetsDir, roster, options = {}) {
   const synced = [];
   const skipped = [];
+  let hasUnresolvedRoles = false;
   const projectDefs = projectAgentsDir(targetDir);
   const bundledDefs = join2(assetsDir, "agents");
   const resolved = [];
@@ -1454,6 +1471,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
         def = await loadAgentDefinition(bundledDefs, entry.definition);
       } catch {
         skipped.push(`${entry.definition} (definition not found)`);
+        hasUnresolvedRoles = true;
         continue;
       }
     }
@@ -1506,6 +1524,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
         id: entry.id,
         identity: {
           name: entry.name ?? entry.definition,
+          ...entry.epithet ? { epithet: entry.epithet } : {},
           role: def.role
         }
       }))
@@ -1575,7 +1594,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
     );
     if (codexMerged) synced.push("AGENTS.md (agents section)");
   }
-  return { synced, skipped };
+  return { synced, skipped, hasUnresolvedRoles };
 }
 
 // src/modules/agents.ts
@@ -1660,9 +1679,9 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
   }
   printStep("Assigning names...");
   const named = await applyNamingStrategy(namingStrategy, selectedRoleIds);
-  const rosterEntries = named.map(({ definition, name }) => {
+  const rosterEntries = named.map(({ definition, name, epithet }) => {
     const id = definition === "orchestrator" ? "main" : name.toLowerCase().replace(/\s+/g, "-");
-    return { definition, name, id };
+    return epithet ? { definition, name, id, epithet } : { definition, name, id };
   });
   const roster = {
     schema_version: 2,
@@ -1706,7 +1725,7 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
     return;
   }
   printStep("Syncing agent definitions to all clients...");
-  const { synced, skipped } = await syncAgents(
+  const { synced, skipped, hasUnresolvedRoles } = await syncAgents(
     targetDir,
     assetsDir,
     roster,
@@ -1721,6 +1740,12 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
   console.log();
   console.log(`    \u{1F4A1} Customize: edit .arcane/agents.yaml \u2192 spell agents sync`);
   console.log();
+  if (hasUnresolvedRoles) {
+    console.error(
+      '  \u2717 One or more rostered roles could not be resolved (see "Skipped" above) \u2014 a malformed or missing agent template must not pass silently.'
+    );
+    process.exitCode = 1;
+  }
 }
 async function runAgentsSync(options, targetDir, assetsDir) {
   let roster;
@@ -1739,7 +1764,7 @@ async function runAgentsSync(options, targetDir, assetsDir) {
   } else {
     console.log("\n  Syncing agents...\n");
   }
-  const { synced, skipped } = await syncAgents(
+  const { synced, skipped, hasUnresolvedRoles } = await syncAgents(
     targetDir,
     assetsDir,
     roster,
@@ -1763,6 +1788,12 @@ async function runAgentsSync(options, targetDir, assetsDir) {
     }
   }
   console.log();
+  if (hasUnresolvedRoles) {
+    console.error(
+      '  \u2717 One or more rostered roles could not be resolved (see "Skipped" above) \u2014 a malformed or missing agent template must not pass silently.'
+    );
+    process.exitCode = 1;
+  }
 }
 async function runAgentsList(targetDir) {
   let roster;