arcane-cli 0.22.3 → 0.22.5

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

@@ -567,13 +567,15 @@ See also: [Agent Workflow — Sync with main before opening a PR](#agent-workflo
 | **Description**    | Must include: summary of changes, rationale, verification steps, and a linked work item ID if applicable                                                                                                                                     |
 | **Pre-PR sync**    | **Mandatory rebase on latest `origin/<target>` before pushing.** See [🛑 Agent-mandatory pre-PR guard](#-agent-mandatory-pre-pr-guard) above — this applies even when opening PRs via raw `az repos pr create` / `gh pr create` / MCP tools. |
 | **Branch cleanup** | After merge, delete the source branch (local and remote).                                                                                                                                                                                    |
-| **PR link format** | All PR references in agent output should be clickable markdown links to the PR, not a bare `PR #NNN`.                                                                                                                                        |
+| **PR link format** | All PR references in agent output **must** be clickable markdown links to the PR, not a bare `PR #NNN`.                                                                                                                                     |
+| **Doc-ID link format** | The same rule extends to `ADR-NNN`/`ARC-NNN`/`EF-NN`/journal entries/named governance docs — never a bare ID. See `.github/instructions/agent-output.instructions.md` → Doc-ID Link Format for the full rule and required formats per context. |
 
 ### Agent PR Workflow
 
 1. **Create a work item** (if one doesn't exist) using `spell-suggest-feature` or `spell-bug`.
 2. **Open PR** with proper title, description, and work-item link.
-3. **Notify the human** through your configured channel with: `[PR #{number}] {repo} — {title} (#{workItemId})`.
+3. **Notify the human** through your configured channel with a clickable link, not a bare number:
+   `[PR #{number} — {title}]({url}) — {repo} (#{workItemId})`.
 4. **Address review feedback** if a reviewer requests changes.
 5. **After merge**, delete the branch (local + remote) and confirm cleanup.
 

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/.arcane/governance/new-business-setup.md

@@ -113,12 +113,12 @@ See [[agents/installation|Runtime Installation]].
 
 ### Step 3.3 — Agent Git Identity Setup
 
-Every agent that will produce commits for this business must have a registered Git identity **before making its first commit**. See [[governance/git-conventions#agent-attribution-model|Git Conventions — Agent Attribution]].
+Every agent that will produce commits for this business must have a registered Git identity **before making its first commit**. See [[git-conventions#agent-attribution-model|Git Conventions — Agent Attribution]].
 
 For each agent assigned to this business:
 
 1. **Confirm persona name** is registered in [[naming-conventions|Naming Conventions]] agent roster.
-2. **Confirm Git identity** exists in the registered identities table in [[governance/git-conventions#agent-email-convention|Git Conventions]].
+2. **Confirm Git identity** exists in the registered identities table in [[git-conventions#agent-email-convention|Git Conventions]].
 3. **Add agent to `.mailmap`** in every repo the agent will commit to:
    ```
    {AGENT_NAME} <{AGENT_EMAIL}>

package/dist/assets/.arcane/governance/spell-authoring-standards.md

@@ -15,7 +15,13 @@ against a consistent bar. This is the spell-prompt analogue of [[product-excelle
 grades PRDs, not prompts). It is an **authoring-time standard** — a checklist for contributors writing
 or reviewing spells. It is **not** meant to be read at runtime by the spells it grades.
 
-See [ARC-014](../../../DECISIONS.md#arc-014) for the decision that established this standard.
+See [ARC-014](https://github.com/codemagicianhq/arcane/blob/main/DECISIONS.md#arc-014--spell-authoring-standards-a-quality-rubric-for-spell-prompts)
+for the decision that established this standard. **Full canonical URL, not a same-repo
+wiki-link** (corrected 2026-08-31, BC-06) — this file ships to consumer repos, and
+`DECISIONS.md` does not: `src/assets/DECISIONS.md` (what consumers actually receive via
+`spell init`) is an empty starter template for the *consumer's own* decisions, so a
+same-repo wiki-link to a specific ARC id would resolve to the wrong document once
+installed, not simply fail to resolve.
 
 ## The Spell Quality Rubric
 

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/instructions/agent-output.instructions.md

@@ -4,7 +4,7 @@ applyTo: "**"
 
 # Agent Output Formatting Rules
 
-Source of truth: `.arcane/governance/git-conventions.md` → PR Standards section.
+Source of truth: `.arcane/governance/git-conventions.md` → PR Standards → PR Requirements.
 
 ## PR Link Format
 
@@ -20,9 +20,60 @@ All PR references in agent output **must** be clickable markdown links. Never wr
 [PR #270 — fix: remove Unix-only preinstall script and approve esbuild builds](https://dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/270)
 ```
 
+## Doc-ID Link Format
+
+The same rule extends to every other identifier class this framework uses to reference
+a decision or record: `ADR-NNN`, `ARC-NNN`, `EF-NN`, venture decision IDs, journal
+entries, and named governance docs. A bare decision ID in agent output is the same
+defect as a bare `PR #NNN` — the reader has to go find it themselves, and a typo or
+stale number is invisible until someone tries.
+
+**Required format, by context:**
+- **Inside a repo's own local markdown** (e.g. this repo's `journal/`, `PLAN.md`, or
+  `DECISIONS.md` cross-referencing itself): a wiki-link (`[[DECISIONS#ARC-NNN|ARC-NNN]]`)
+  or a relative markdown link that actually resolves from that file's own location.
+- **Chat or PR output:** a clickable markdown link to the canonical file/anchor.
+- **Governance docs this framework ships** (`.arcane/governance/*.md`): the full
+  canonical-repo URL. A file here lives in *this* repo today but ships into every
+  consumer repo's own tree, where a wiki-link or relative path to Arcane's own
+  `DECISIONS.md` either fails to resolve, or worse, silently resolves to the
+  *consumer's own* `DECISIONS.md` (an empty per-consumer starter template, not
+  Arcane's real decision record) — wrong content, not just a dead link.
+- **Spell prompts and instructions this framework ships**
+  (`.github/prompts/*.prompt.md`, `.github/instructions/*.md`): **plain text only —
+  cite the bare ID, no link at all** (`ARC-035`, not `[ARC-035](...)`). A full
+  canonical URL is *also* unsafe here, not just a same-repo link: it bakes
+  `github.com/codemagicianhq/arcane` — this project's own org and repo name — into
+  content the org-token portability gate (`scripts/org-token-lint.ts`, D2 in
+  `spell-authoring-standards.md`) exists specifically to keep out of distributed
+  spells. **Confirmed live 2026-08-31 (BC-06):** the build's `Org-token lint` failed
+  on exactly this pattern in three prompt files, including two this same correction
+  pass had introduced minutes earlier while fixing the *other* link defect. Known
+  gap: the portability scan today only walks `.github/prompts/`, so a full URL in a
+  `.github/instructions/*.md` file — like this one's own Merge Strategy section, two
+  paragraphs down — ships uncaught; tracked in `TODO.md`.
+- **Cross-repo references from anywhere else** (chat, PR output, another repo
+  entirely): the full canonical-repo URL.
+
+**Never fabricate an unresolvable link.** If you cannot confirm the ID exists and where
+it resolves to, say so and cite the ID as plain text rather than inventing a link that
+looks real but goes nowhere.
+
 ## Merge Strategy
 
-All PRs must use **Rebase and fast-forward**. Never squash. Never merge commit. See ADR-048.
+All PRs must use **Rebase and fast-forward**. Never squash. Never merge commit. See
+ARC-009 §7 (Arcane's own framework decision — cited as plain text, not linked, per
+Doc-ID Link Format above: this file ships). **Corrected 2026-08-31 (BC-06), three
+times over:** this file previously cited `ADR-048`, which does exist in the shipped
+`framework-decisions.md` reference — but its actual topic ("Code Versus Docs Branch
+Policy") has nothing to do with merge strategy, a topical miscitation rather than a
+missing one. The first fix replaced it with a same-repo wiki-link to this repo's own
+`DECISIONS.md` — itself the exact cross-repo defect this section warns about
+(`DECISIONS.md` doesn't ship). The second fix replaced that with a full canonical
+URL, which held up locally but failed the build's org-token portability gate: a
+`github.com/codemagicianhq/arcane` URL bakes this project's own org into a file the
+gate treats as distributed content (see Doc-ID Link Format above). Settled on the
+bare ID — the gate's own documented safe form.
 
 When completing a PR via `az repos pr update`, do **not** pass `--squash true`. The correct command:
 

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

@@ -9,7 +9,10 @@ agent: agent
 
 - This spell determines whether a version bump is required and applies the correct semver type.
 - Use it whenever you've changed `src/assets/`, `registry.ts`, or `profiles.ts` in the arcane repo.
-- It enforces the rule from CLAUDE.md: "Version bump required for any change to `src/assets/`."
+- It enforces the rule from `project.md` → Constraints → Self-hosting: "Anything touching
+  `src/assets/` requires a version bump." (Corrected 2026-08-31, BC-06 — this previously cited
+  CLAUDE.md, which now carries only the working protocol; the rule's live prose home moved to
+  `project.md:56-58`.)
 
 ---
 

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

@@ -51,7 +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.
+4. **Post the formal round state per PR** — apply `spell-review`'s step 10 (ARC-035 decision 3 — cited as plain text, not linked; see `agent-output.instructions.md` → Doc-ID Link Format) 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.
 
@@ -68,11 +68,11 @@ Build one report:
 
 | PR | Repo | Title | Verdict | High | Med | Low |
 | -- | ---- | ----- | ------- | ---- | --- | --- |
-| #n | repo | …     | approve / request-changes | 0 | 1 | 2 |
-| #n | repo | …     | SKIPPED — {reason}        | —  | —  | —  |
+| [#n]({url}) | repo | …     | approve / request-changes | 0 | 1 | 2 |
+| [#n]({url}) | repo | …     | SKIPPED — {reason}        | —  | —  | —  |
 
 ## Per-PR detail
-### PR #n — {title}
+### [PR #n]({url}) — {title}
 - Verdict: …
 - Coverage: {PASS/WARN/FAIL per lens}
 - Findings: {R1 …}

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

@@ -122,7 +122,7 @@ 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:
+10. **Post the formal round state** (ARC-035 decision 3 — Arcane's own framework decision, cited as plain text, not linked, since this file ships; see `agent-output.instructions.md` → Doc-ID Link Format) — 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.

package/dist/assets/.github/prompts/spell-summon-venture.prompt.md

@@ -11,7 +11,7 @@ agent: agent
 - **Hub-gated:** requires `role: "hub"` in `.arcane.json`. Refuses cleanly in a consumer repo, pointing at the right place to capture the idea instead.
 - Use this when starting a new venture (business, product, or personal project) that the hub should track.
 - Input format is: `Venture Name | Venture Type | Description` — prompt will ask for missing fields.
-- Renamed from `spell-bootstrap-business` — venture books and the registry didn't exist when that spell was named. Clean rename, no compatibility alias, per [[DECISIONS#ARC-008|ARC-008]]'s precedent.
+- Renamed from `spell-bootstrap-business` — venture books and the registry didn't exist when that spell was named. Clean rename, no compatibility alias, per ARC-008's precedent (cited as plain text, not linked — this file ships; see `agent-output.instructions.md` → Doc-ID Link Format).
 
 ---
 

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;