arcane-cli 0.38.3 → 1.0.0

package/dist/assets/.arcane/spells/spell-adopt-docs.md

@@ -0,0 +1,158 @@
+---
+name: Spell — Adopt Docs
+description: Bring an existing document tree under Arcane governance without moving anything first — inventory, propose a mapping, get approval, then apply in reversible steps. Dry-run by default.
+claude_description: Use PROACTIVELY when bringing an existing, ungoverned doc tree under Arcane governance.
+argument-hint: Optional path to the tree to adopt (defaults to the repository root). Add `--apply` only after reviewing a dry run.
+agent: agent
+---
+
+## Executive Summary
+
+- This spell adopts a folder of documents that already exists, rather than
+  scaffolding a new one.
+- It **never moves, renames, or deletes anything until you approve a specific
+  written mapping** — the default run is read-only.
+- It works with `subject_root: "."`, so a tree that already lives at the
+  repository root is adopted where it is. Restructuring is offered, never
+  required.
+- Every mutating phase states its rollback before it runs.
+- In a repository marked `content_sensitivity: sensitive`, the inventory records
+  paths and shapes, never document contents.
+
+---
+
+## Preconditions
+
+Stop and report, without changing anything, if any of these fail:
+
+1. **`.arcane.json` exists.** If not: "Run `spell init` first — adoption needs a
+   profile and a subject root to map into."
+2. **The working tree is clean** (`git status --porcelain` is empty). Adoption's
+   rollback story is "revert the commit"; that only works from a clean baseline.
+   Report the dirty paths and stop.
+3. **The target path exists and is inside the repository.** Reject absolute
+   paths and anything resolving outside the repo root.
+
+Read, in order: `.arcane.json` (for `subject_root`, `content_sensitivity`,
+`profile`), then `.arcane/governance/records-conventions.md`, then
+`.arcane/governance/naming-conventions.md` if installed.
+
+## Phase 1 — Inventory (always read-only)
+
+Walk the target tree and build a picture of what is actually there. Do not open
+a document to summarize its subject matter; classify from path, name, extension,
+and size.
+
+Report:
+
+- **Total counts** by extension, and total size.
+- **Depth and shape** — how deep the tree goes, which directories hold the bulk.
+- **Naming patterns observed** — dated (`2024-03-01-...`), numbered, free-form,
+  or mixed. Report what you see; do not judge it yet.
+- **Collisions with Arcane's own layout** — anything already at `TODO.md`,
+  `DECISIONS.md`, `IDEAS.md`, `README.md`, `journal/`, `.arcane/`, `.github/`,
+  `.claude/`. These are the only paths where adoption could overwrite something.
+- **Files Git will treat as binary** under the installed `.gitattributes`, and
+  any that are large enough to be worth an explicit LFS decision later.
+- **Anything unreadable** — permission errors, broken symlinks, zero-byte files.
+  Report them; never silently skip.
+
+**If `content_sensitivity` is `"sensitive"`:** the inventory is paths, counts,
+extensions and sizes only. Do not quote filenames that are themselves revealing
+in the session summary — say "12 files under `clients/`", not the list — and do
+not open documents to characterize their contents.
+
+## Phase 2 — Propose a mapping
+
+Produce a written proposal. This is the artifact the operator approves, and it
+must be specific enough that they can predict every effect.
+
+For each group of files, state one of:
+
+| Disposition | Meaning |
+|---|---|
+| **Leave in place** | No move. The default, and the right answer for most trees. |
+| **Move** | Old path → new path, explicitly, per file or per directory. |
+| **Rename** | Old name → new name, with the rule that produced it. |
+| **Ignore** | Added to `.gitignore` rather than governed. |
+| **Flag** | Needs an operator decision this spell will not make (see below). |
+
+Always also state:
+
+- **What `subject_root` will be** afterwards, and whether adoption changes it.
+  If the tree is already at the repository root, propose `"."` and say plainly
+  that this means no restructuring.
+- **Which collisions from Phase 1 you propose to resolve, and how.** Never
+  propose overwriting an existing `TODO.md`/`DECISIONS.md`/`README.md`; propose
+  merging or leaving the operator's file untouched.
+- **What will NOT be touched** — an explicit list is part of the proposal, not
+  an omission from it.
+
+Flag rather than decide:
+
+- Anything that looks like credentials, keys, or personal data.
+- Anything suggesting a retention obligation (contracts, filings, tax records)
+  — see `records-conventions.md`; deletion and relocation of those is an
+  operator decision.
+- Superseded-looking duplicates (`final-v2-FINAL.docx`). Propose the tombstone
+  convention from `records-conventions.md`; do not pick a winner.
+
+End with: **"Approve this mapping? (yes / edit / cancel)"** and stop. A dry run
+ends here, always.
+
+## Phase 3 — Apply (only after explicit approval, and only with `--apply`)
+
+Apply in the order below. Each step states its rollback *before* it runs, and
+each step is a separate commit. Revert them in reverse order — reverting an
+earlier phase while a later one still stands will conflict, because the later
+phase built on the paths the earlier one created.
+
+1. **Write `subject_root` to `.arcane.json`** (if it changes).
+   *Rollback: revert the commit; no files moved yet.*
+2. **Add ignore entries** for anything dispositioned "Ignore".
+   *Rollback: revert the commit; files are untouched on disk either way.*
+3. **Renames**, using `git mv` so history follows the file.
+   *Rollback: revert the commit. If a rename collides with an existing path,
+   stop the whole phase — do not overwrite, do not continue to step 4.*
+4. **Moves**, using `git mv`, deepest paths first so parent directories are
+   never removed out from under a pending move.
+   *Rollback: revert the commit.*
+5. **Tombstones** for anything the operator confirmed as superseded, per
+   `records-conventions.md`.
+   *Rollback: revert the commit; original content was never deleted.*
+
+Hard rules for this phase:
+
+- **Never delete a document.** Adoption moves, renames, and marks. Deletion is a
+  separate, explicit operator decision (`records-conventions.md`).
+- **Never overwrite an existing file.** On any collision, stop and report.
+- **Stop at the first failure.** Do not attempt partial recovery mid-phase —
+  report what completed, what did not, and the exact `git revert` command for
+  each commit already made.
+- If the repository is `content_sensitivity: sensitive`, commit messages name
+  paths and counts only, never contents.
+
+## Phase 4 — Report
+
+Output:
+
+```
+Adopted <N> files under {SUBJECT_ROOT}
+
+Moved      <n>   (commit <sha>)
+Renamed    <n>   (commit <sha>)
+Tombstoned <n>   (commit <sha>)
+Left as-is <n>
+Ignored    <n>
+Flagged    <n>   — needs your decision, listed below
+```
+
+Then list every flagged item with the decision it needs. Finish with the
+suggested next step: `spell-todo` to capture the flagged decisions, or
+`spell-commit-work` if anything remains uncommitted.
+
+## Related
+
+- [[.arcane/governance/records-conventions|Records Conventions]] — supersession and retention
+- [[.arcane/governance/git-conventions|Git Conventions]] — branch and merge discipline
+- [[.arcane/governance/universal-agent-rules|Universal Agent Rules]] — sensitive-repository behaviour

package/dist/assets/.arcane/spells/spell-arcane-version.md

@@ -0,0 +1,87 @@
+---
+name: Spell — Arcane Version
+description: Report the version of Arcane installed in this repository, the active profile, installed components, and whether an update is available.
+claude_description: Use PROACTIVELY when asked about the installed Arcane version, profile, or whether an update is available.
+argument-hint: Optional flag — pass "components" to list all installed components in full detail
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt reads `.arcane.json` and reports the installed Arcane version for this repository.
+- It surfaces the install date, profile, and component count.
+- Optionally lists every installed component when the "components" argument is passed.
+- Use this any time you need to know which Arcane version a repo is running.
+
+---
+
+Report the Arcane installation state for this repository.
+
+## Step 1 — Read the Manifest
+
+Read [.arcane.json](../../.arcane.json) from the repository root.
+
+If the file does not exist, stop and output:
+
+```
+⚠ Arcane is not installed in this repository.
+Run `spell init` to install it.
+```
+
+## Step 2 — Output Installation Summary
+
+Produce output in this exact structure:
+
+### Arcane Installation
+
+| Field            | Value                         |
+| ---------------- | ----------------------------- |
+| **Version**      | `{version from .arcane.json}` |
+| **Profile**      | `{profile}`                   |
+| **Installed At** | `{installedAt}`               |
+| **Components**   | `{count}` installed           |
+
+### Update Check (two-axis)
+
+This repo's `.arcane.json` version is one of three readings — check both axes, the same two as
+`spell-open-session`'s own version check:
+
+- **Repo-files version** — already read in Step 1 (`.arcane.json`'s `version` field).
+- **Installed CLI version** — determine the version of the installed `arcane-cli` CLI (for example,
+  `npx arcane-cli --version`, or the locally installed package version).
+- **Npm-latest version** — fetch `https://registry.npmjs.org/arcane-cli/latest` and extract the
+  `version` field.
+
+- **(a) Repo-files behind the installed CLI:** `⚠ Managed files out of date: files at {version} → CLI at {cli}. Run spell update to resync files.`
+- **(b) Installed CLI behind npm-latest:** `⚠ Update available: CLI at {cli} → latest {latest}. Upgrade the CLI, then run spell update.`
+- **If either axis drifts, emit the canonical version-drift diagram** — same template, same collapsing/
+  branching rule, same `:::mermaid`-for-ADO-wikis fencing as `spell-open-session.md`'s own
+  "Arcane version check (two-axis)" step; that file holds the canonical shape, referenced here rather
+  than repeated.
+- If both axes are current:
+
+```
+✔ You are on the latest version ({version}).
+```
+
+If the npm registry is unreachable, report:
+
+```
+ℹ Could not reach npm registry — update check skipped.
+```
+
+## Step 3 — Component Detail (optional)
+
+Only include this section when the user passed "components" as the prompt argument.
+
+List each entry from the `components` array in `.arcane.json` as a table:
+
+| Component | Installed Version | Files |
+| --------- | ----------------- | ----- |
+| ...       | ...               | ...   |
+
+## Rules
+
+- Do not modify any files.
+- Keep output factual — read directly from `.arcane.json`, do not infer or assume values.
+- If `installedAt` is an ISO 8601 timestamp, display it as a human-readable date (e.g., "26 May 2026").

package/dist/assets/.arcane/spells/spell-architect.md

@@ -0,0 +1,117 @@
+---
+name: Spell — Architect
+description: Generate architecture decisions and story breakdown from a PRD, producing architecture.md and stories.json
+claude_description: Use PROACTIVELY once a PRD exists and needs architecture decisions and a story breakdown before implementation starts.
+argument-hint: Path to PRD.md or paste the PRD content
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt takes a PRD and produces architecture decisions plus an implementable story breakdown.
+- It follows a structured solutioning pattern — progressive context chain from requirements to implementation plan.
+- Outputs `architecture.md` and `stories.json` that feed into `spell-implement`.
+- See [[.arcane/governance/development-methodology|Development Methodology]] for full Spell Loop reference.
+
+---
+
+Generate architecture decisions and story breakdown from the provided PRD.
+
+Use these files for context:
+
+- [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) — Spell Loop methodology and stories.json format
+- [governance/testing-standards.md](../../.arcane/governance/testing-standards.md) — Testing frameworks and coverage requirements
+- [DECISIONS.md](../../DECISIONS.md) — Existing ADRs to respect and extend
+
+Workflow:
+
+1. **Read the PRD** — understand requirements, constraints, and acceptance criteria.
+   - If no PRD exists for the feature, do not architect against assumptions — recommend the user run `spell-plan` first to produce one, then return here.
+
+2. **Verify PRD coverage** — before designing the architecture, confirm the PRD covers the scope needed to design against. Never guess to fill holes. If there are gaps or ambiguities (missing requirements, undefined constraints, unresolved acceptance criteria), list them explicitly and ask the user to resolve them — or loop back to `spell-plan` — before proceeding. Only continue once the gaps are resolved.
+
+3. **Make architecture decisions** — for each significant technical choice:
+   - What are the options?
+   - What are the tradeoffs?
+   - What does the decision depend on?
+   - Propose a recommendation with rationale.
+   - Flag decisions that need a new ADR in DECISIONS.md.
+
+4. **Generate architecture.md**:
+   ```markdown
+   # Architecture: [Feature Name]
+
+   ## Overview
+   [High-level approach in 2-3 sentences]
+
+   ## Decisions
+   ### [Decision 1: e.g., API Design]
+   - **Options:** [A, B, C]
+   - **Decision:** [Chosen option]
+   - **Rationale:** [Why]
+   - **ADR:** [Existing ADR-NNN or "Needs new ADR"]
+
+   ## Component Diagram
+   [Mermaid diagram showing how components interact]
+
+   ## Data Flow
+   [Sequence diagram for key workflows]
+
+   ## Testing Strategy
+   - [Framework per governance/testing-standards.md]
+   - [Key test scenarios from acceptance criteria]
+   - [Coverage targets]
+
+   ## Security Considerations
+   - [Per threat model]
+
+   ## Implementation Notes
+   - [Tech stack specifics, package versions, patterns to follow]
+   ```
+
+5. **Break into stories** — generate `stories.json` per the format in development-methodology.md:
+   - Each story must be completable in one AI context window (one file change, one endpoint, one component).
+   - Order stories by dependency (infrastructure first, then API, then UI).
+   - Include acceptance criteria from the PRD mapped to specific stories.
+   - Mark all stories as `"passes": false`.
+
+5a. **Validate stories.json schema** — before outputting, self-check every field. Missing fields break `spell-implement`. Required top-level fields:
+   - `feature` (string)
+   - `branchName` (string, format: `agent/type/description`)
+   - `assignedAgent` (string, agent slug)
+   - `trackingMode` (`internal` or `external`)
+   - `externalProvider` (required when `trackingMode=external`)
+   - `adoWorkItemId` (required only when `trackingMode=external` and `externalProvider=ado`)
+
+   Required per-story fields:
+   - `id` (string, e.g. `FEAT-001`)
+   - `title` (string)
+   - `description` (string — detailed enough for implementation without additional context)
+   - `acceptanceCriteria` (array of strings)
+   - `priority` (number, 1 = highest)
+   - `passes` (boolean, always `false` on output)
+   - `assignedTo` (string, agent slug)
+   - `testEvidence` (null on output)
+
+   If any required field is missing, regenerate before outputting. Do not present incomplete stories.json.
+
+6. **Implementation readiness check** — verify:
+   - Every PRD requirement maps to at least one story.
+   - No story depends on an unresolved Open Question from the PRD.
+   - Testing strategy covers all acceptance criteria.
+   - No architecture decision contradicts existing ADRs.
+
+7. **Save to disk** — write both outputs to the feature folder:
+   - `features/{adoWorkItemId}-{slug}/architecture.md` and `features/{adoWorkItemId}-{slug}/stories.json` when `trackingMode=external` and `externalProvider=ado`
+   - `features/{slug}/architecture.md` and `features/{slug}/stories.json` when `trackingMode=internal` (or non-ADO external providers without an ADO ID)
+
+   Resolve `trackingMode`, `externalProvider`, optional `adoWorkItemId`, and slug from PRD frontmatter first. If the folder does not exist, create it with `mkdir -p`.
+   Confirm the paths to the user after writing.
+
+8. **Present for review** — show the architecture and story breakdown to the user.
+
+Rules:
+- Stories must be right-sized per the methodology doc (not "build the entire dashboard").
+- Architecture decisions must reference existing ADRs when relevant.
+- Use Mermaid for all diagrams, per rule 8 (`.arcane/governance/universal-agent-rules.md`) — this spell's component/data-flow diagrams are agent-authored design output, not the generated-state-diagrams sub-convention ARC-036 covers.
+- If PRD scope is too large, recommend splitting before proceeding.

package/dist/assets/.arcane/spells/spell-brainstorm.md

@@ -0,0 +1,125 @@
+---
+name: Spell — Brainstorm
+description: Divergent ideation — explore multiple solutions to a problem space before committing to a plan
+claude_description: Use PROACTIVELY when exploring multiple solutions to a problem before committing to one.
+argument-hint: "Problem space or opportunity (e.g., 'How should we handle multi-tenant billing?')"
+agent: agent
+---
+
+## Executive Summary
+
+- This spell generates multiple solution options for a problem space before narrowing to a plan.
+- It produces divergent ideas, evaluates trade-offs, and surfaces hidden constraints — without committing to implementation.
+- Use this BEFORE `spell-plan` when you're unsure which direction to take, or when the problem is ambiguous.
+- Output: structured options with trade-off matrix, recommended path, and open questions.
+
+---
+
+Explore the given problem space and generate solution options.
+
+Use these files for context. Each is **optional** — if a file is missing, proceed without it and note the gap in your output so the user knows what wasn't consulted:
+
+- [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) — Spell Loop methodology. _If missing:_ proceed with general SDLC reasoning.
+- [DECISIONS.md](../../DECISIONS.md) — Existing ADRs (to avoid contradicting decided patterns). _If missing:_ assume no decided patterns and state that ADR conflicts could not be checked.
+- [project.md](../../project.md) — Project goals and business context. _If missing:_ infer context from the problem statement and ask a clarifying question if goals are unclear.
+- [naming-conventions.md](../../.arcane/governance/naming-conventions.md) — Agent roster and roles. _If missing:_ proceed without role references.
+- [TODO.md](../../TODO.md) — In-progress work (referenced in step 4). _If missing:_ skip the in-progress-work cross-check and note it.
+
+---
+
+## Workflow
+
+### 1. Problem Framing
+
+Accept the problem from one of these sources:
+
+| Source | Format | How to fetch |
+|--------|--------|--------------|
+| **Description in prompt** | Inline text | Use as-is |
+| **ADO work item ID** | `#507` or `507` with org name | Run: `az boards work-item show --id {id} --org https://dev.azure.com/{org} --output json` |
+| **File path** | Path to existing doc | Read the file |
+
+Clarify the problem by identifying:
+- **What is the core tension?** — competing goals, missing capability, or scaling pain
+- **Who is affected?** — users, operators, downstream systems
+- **What constraints exist?** — budget, timeline, tech stack, ADRs already decided
+- **What does "good enough" look like?** — minimum viable outcome vs. ideal outcome
+
+If the problem is too vague, ask up to 3 clarifying questions before proceeding.
+
+### 2. Divergent Ideation
+
+Generate **3–5 distinct approaches** to the problem. Each must be meaningfully different — not just parameter variations of the same idea.
+
+For each option:
+
+```markdown
+### Option N: [Name]
+**One-liner:** [What this approach does in ≤15 words]
+**How it works:** [2-3 sentences on mechanism]
+**Strengths:** [What this gets right]
+**Weaknesses:** [What this sacrifices or risks]
+**Effort:** S (< 1 sprint) / M (1-2 sprints) / L (3+ sprints)
+**Prerequisite ADRs:** [Decisions that must be made first, or "none"]
+```
+
+Guidelines for generating options:
+- Include at least one **simple/minimal** option (the "just do the simplest thing" path)
+- Include at least one **ambitious** option (the ideal-world approach)
+- Include at least one **unconventional** option (reframe the problem, challenge assumptions)
+- Do NOT include options that violate existing ADRs unless you explicitly flag the conflict
+
+### 3. Trade-off Matrix
+
+Produce a comparison table:
+
+| Dimension | Option 1 | Option 2 | Option 3 | ... |
+|-----------|----------|----------|----------|-----|
+| **Complexity** | Low/Med/High | | | |
+| **Time to value** | Days/Weeks/Months | | | |
+| **Scalability** | Poor/Good/Excellent | | | |
+| **Reversibility** | Easy/Hard/Irreversible | | | |
+| **Risk** | Low/Med/High | | | |
+| **Alignment with goals** | Weak/Moderate/Strong | | | |
+
+### 4. Hidden Constraints & Risks
+
+Surface things the user might not have considered:
+- Dependencies on decisions not yet made
+- Interaction with other in-progress work (check `TODO.md`)
+- Security or compliance implications
+- Data migration or backwards-compatibility concerns
+- Skills or tooling gaps
+
+### 5. Recommendation
+
+State your recommended path clearly:
+
+```markdown
+## Recommended Path
+
+**Option [N]: [Name]**
+
+**Why:** [1-2 sentences on why this balances trade-offs best for the current context]
+
+**Immediate next step:** [One concrete action — likely "run `spell-plan` with this direction"]
+```
+
+If no single option is clearly best, say so and identify what additional information would break the tie.
+
+### 6. Open Questions
+
+List up to 5 questions that would refine the decision:
+- Questions whose answers would change the recommendation
+- Questions about constraints not visible in the docs
+- Questions about user preferences or business priorities
+
+---
+
+## Rules
+
+- **Never commit to implementation.** This spell produces options, not plans. The output **feeds into `spell-plan`** (run it with the recommended direction). For a large idea spanning multiple features or sprints, hand off to `spell-scope` first to break it into deliverables, then `spell-plan` each.
+- **Quantity over polish.** Brainstorming favors breadth. Options don't need to be fully fleshed out — just distinct enough to compare.
+- **Challenge assumptions.** If the user's framing seems to constrain solutions unnecessarily, say so explicitly.
+- **Respect decided ADRs.** Flag conflicts but don't silently ignore existing decisions.
+- **Stay grounded.** Options must be feasible given the tech stack and team size. No "hire 5 engineers" solutions for a solo operation.

package/dist/assets/.arcane/spells/spell-bug.md

@@ -0,0 +1,123 @@
+---
+name: Spell — Bug
+description: Document, diagnose, and fix a bug — files a tracker work item (per tracking_mode), traces root cause, implements fix, verifies, and commits
+claude_description: Use PROACTIVELY whenever diagnosing and fixing a bug, even if the user just describes broken behavior.
+argument-hint: Bug description (e.g., "Session detail dialog shows 404 when clicking a mock session")
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt handles the full bug lifecycle: document → track → diagnose → fix → verify → close.
+- It records the bug in your configured tracker (external provider) or `TODO.md` (internal mode) and links the fix commit to it.
+- Output is a working fix with tests, committed using Conventional Commits format.
+- **When to use:** you have a concrete defect — wrong/broken behavior versus expected. If the report is actually a request for *new* behavior, route to `spell-suggest-feature` instead. For small non-blocking cleanups discovered along the way, capture them with `spell-todo`.
+- See [[.arcane/governance/development-methodology|Development Methodology]] for full Spell Loop reference.
+
+---
+
+Document, diagnose, and fix the described bug.
+
+Use these files for context (each is optional — if a file is missing, proceed and note the assumption you fell back on):
+
+- [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) — Spell Loop methodology **and tracker-provider specifics** (which tracker, work-item types, commit-link syntax). If missing, default to `tracking_mode: internal` and track in `TODO.md`.
+- [DECISIONS.md](../../DECISIONS.md) — Existing ADRs to respect. If missing, proceed without ADR constraints.
+- [governance/testing-standards.md](../../.arcane/governance/testing-standards.md) — Coverage thresholds. If missing, match the test conventions already present in the repo.
+
+Workflow:
+
+1. **Capture the bug** — gather these details from the user (ask if missing):
+
+   | Field | Description |
+   |-------|-------------|
+   | **Summary** | One-line description of the bug |
+   | **Reproduction steps** | Numbered steps to reproduce |
+   | **Expected behavior** | What should happen |
+   | **Actual behavior** | What actually happens (include error messages, HTTP codes, screenshots) |
+   | **Severity** | Critical / High / Medium / Low |
+   | **Affected component** | File path, page, API route, or module |
+   | **Discovery context** | How was this found? (smoke test, user report, monitoring) |
+
+2. **Record the bug** — file it in whatever tracker this repo uses. Resolve `tracking_mode` from `.arcane.json` (or the repo's feature/PRD frontmatter); if unset, **ask** rather than assuming.
+
+   - **`tracking_mode: internal`** (or no tracker configured) — append the bug to `TODO.md` (create it if absent) using the captured fields from Step 1. Use the `TODO.md` entry's identifier as `{WORK_ITEM_ID}`. No external tooling required.
+   - **`tracking_mode: external`** — file a work item in the configured provider. Read [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) for the provider, work-item type, and required fields; do **not** assume Azure DevOps. Extract the returned id as `{WORK_ITEM_ID}`.
+
+     *Azure DevOps is one such provider — if and only if `.arcane.json` / methodology names it (and the `az` CLI is available), file it like so. Resolve `{ADO_ORG}` and `{ADO_PROJECT}` from `.arcane.json`; ask if unset:*
+     ```bash
+     az boards work-item create \
+       --type Bug \
+       --title "[Bug] {SUMMARY}" \
+       --description "{formatted description with repro steps}" \
+       --org https://dev.azure.com/{ADO_ORG} \
+       --project {ADO_PROJECT} \
+       --output json
+     ```
+
+     *GitHub is another — if and only if `.arcane.json` names `external_provider: github` (and the `gh` CLI is authenticated):*
+     ```bash
+     gh issue create \
+       --title "[Bug] {SUMMARY}" \
+       --body "{formatted description with repro steps}" \
+       --label bug
+     ```
+     `gh issue create` prints the created issue's URL on success; extract the trailing number as `{WORK_ITEM_ID}`. Omit `--label` if the repo has no `bug` label (`gh label list`) rather than guessing.
+
+   If the configured tooling is unavailable or the user prefers manual tracking, fall back to the `TODO.md` entry above and continue.
+
+3. **Diagnose** — trace the code path to find the root cause:
+   - Read the affected component and its dependencies.
+   - Identify the exact line(s) where the bug manifests.
+   - Determine *why* the bug exists (data mismatch, missing case, race condition, etc.).
+   - Document the root cause concisely.
+
+4. **Implement the fix** — write the minimal code change:
+   - Fix only the bug — no refactoring, no feature additions.
+   - Follow existing code patterns and conventions.
+   - If the fix touches a public interface, check all callers.
+
+5. **Add or update tests** — ensure the bug cannot regress:
+   - Write a test that reproduces the bug (fails without the fix).
+   - Verify existing tests still pass.
+   - Run the full test suite: `npx vitest run` (or project-specific command).
+
+6. **Verify the fix** — confirm the bug is resolved:
+   - Run the reproduction steps from Step 1 — they should now succeed.
+   - Check for side effects in related functionality.
+   - If applicable, rebuild and restart: `npm run build`.
+
+7. **Commit** — stage and propose a commit message for approval:
+   ```
+   fix({scope}): {SUMMARY}
+
+   {Root cause explanation}
+
+   {What was changed and why}
+
+   {WORK_ITEM_LINK}
+   ```
+   Follow Conventional Commits format. For `{WORK_ITEM_LINK}`, use the commit-link convention your tracker expects (per [governance/development-methodology.md](../../.arcane/governance/development-methodology.md)) — e.g. `Fixes AB#{WORK_ITEM_ID}` for Azure DevOps, `Fixes #{WORK_ITEM_ID}` for GitHub Issues, or a plain `Refs TODO.md` for internal mode. Wait for user approval before executing `git commit`.
+
+8. **Close out the tracker** — update the work item's state to reflect the fix:
+   - **`internal`** — mark the `TODO.md` entry as resolved (check it off / move to a Done section).
+   - **`external`** — transition the work item to its resolved/done state via the provider. For Azure DevOps specifically (resolve `{ADO_ORG}` from `.arcane.json`):
+     ```bash
+     az boards work-item update \
+       --id {WORK_ITEM_ID} \
+       --state Resolved \
+       --org https://dev.azure.com/{ADO_ORG} \
+       --output json
+     ```
+     For GitHub specifically:
+     ```bash
+     gh issue close {WORK_ITEM_ID} --reason completed --comment "Fixed by {commit SHA or PR URL}"
+     ```
+     For other providers, follow [governance/development-methodology.md](../../.arcane/governance/development-methodology.md).
+
+Rules:
+- Fix only the reported bug. Do not bundle unrelated improvements.
+- If the report turns out to describe *new* or *changed* behavior rather than a defect, stop and route the user to `spell-suggest-feature`. Capture any non-blocking follow-ups you notice via `spell-todo` rather than expanding this fix.
+- Every fix must have a test that would have caught the bug.
+- Present the commit message for human approval — never auto-commit.
+- If the root cause is unclear, present your diagnosis and ask for confirmation before implementing.
+- If the fix is risky (touches shared infrastructure, auth, or data), flag it explicitly.