arcane-cli 0.22.11 → 0.22.13

package/dist/assets/.arcane/governance/universal-agent-rules.md

@@ -53,6 +53,12 @@ See also: [[README]], [[DECISIONS]], [[governance/git-conventions|Git Convention
 
 ---
 
+## Spell Lifecycle
+
+22. **Lifecycle operations run through their spell when one is installed.** Committing, opening a PR, opening or closing a session, reviewing code, and shipping each have a dedicated spell (`spell-commit-work`, `spell-create-pull-request`, `spell-open-session`/`spell-close-session`, `spell-review`, `spell-ship`). When the installed component set includes the matching spell, invoke it for that operation rather than improvising the workflow from general knowledge — even when the user does not name the spell explicitly. The intent→spell routing table injected into each client's L1 instruction file (`CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`) is normative for this mapping, not illustrative.
+
+---
+
 ## Recommendation Guardrails (ADR-034)
 
 15. **Flag actionable recommendations.** Any recommendation that could lead to a purchase, subscription, account creation, or irreversible action must: (a) be flagged explicitly, (b) use verified current information — never assume or fabricate, (c) present free/no-cost alternatives when they exist, (d) state confidence level if based on general knowledge. For >$50 or contracts, require explicit confirmation. See [[agents/agent-policies#actionable-recommendation-policy-adr-034|Full Policy]].

package/dist/assets/.claude/commands/spell-address-review.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY whenever responding to PR review comments — fetch threads, triage, fix or reply, resolve.
+---
+
 # Address Review
 
 Invoke the Arcane `spell-address-review` spell workflow.

package/dist/assets/.claude/commands/spell-adopt-docs.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when bringing an existing, ungoverned doc tree under Arcane governance.
+---
+
 # Adopt Docs
 
 Invoke the Arcane `spell-adopt-docs` spell workflow.

package/dist/assets/.claude/commands/spell-arcane-version.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when asked about the installed Arcane version, profile, or whether an update is available.
+---
+
 # Arcane Version
 
 Invoke the Arcane `spell-arcane-version` spell workflow.

package/dist/assets/.claude/commands/spell-architect.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY once a PRD exists and needs architecture decisions and a story breakdown before implementation starts.
+---
+
 # Architect
 
 Invoke the Arcane `spell-architect` spell workflow.

package/dist/assets/.claude/commands/spell-brainstorm.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when exploring multiple solutions to a problem before committing to one.
+---
+
 # Brainstorm
 
 Invoke the Arcane `spell-brainstorm` spell workflow.

package/dist/assets/.claude/commands/spell-bug.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY whenever diagnosing and fixing a bug, even if the user just describes broken behavior.
+---
+
 # Bug
 
 Invoke the Arcane `spell-bug` spell workflow.

package/dist/assets/.claude/commands/spell-bump.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY before shipping any change that touches distributable content, to determine and apply the correct version bump.
+---
+
 # Bump Version
 
 Invoke the Arcane `spell-bump` spell workflow.

package/dist/assets/.claude/commands/spell-check-drift.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY to detect contradictions and stale statements across core docs, periodically or after major changes.
+---
+
 # Check Drift
 
 Invoke the Arcane `spell-check-drift` spell workflow.

package/dist/assets/.claude/commands/spell-close-session.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY at the end of any significant work session, even if the user just says 'wrap up' or 'done for now'.
+---
+
 # Close Session
 
 Invoke the Arcane `spell-close-session` spell workflow.

package/dist/assets/.claude/commands/spell-commit-work.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY whenever committing work during a session, even if the user just says 'commit this'.
+---
+
 # Commit Work
 
 Invoke the Arcane `spell-commit-work` spell workflow.

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

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY whenever opening a pull request for the current branch, even if the user just says 'open a PR'.
+---
+
 # Create Pull Request
 
 Invoke the Arcane `spell-create-pull-request` spell workflow.

package/dist/assets/.claude/commands/spell-document.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when conversation content (an analysis, a decision, an investigation) should become a permanent reference doc.
+---
+
 # Document
 
 Invoke the Arcane `spell-document` spell workflow.

package/dist/assets/.claude/commands/spell-dotnet-expert.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when working on a .NET project and best-practice guidance is needed.
+---
+
 # Dotnet Expert
 
 Invoke the Arcane `spell-dotnet-expert` spell workflow.

package/dist/assets/.claude/commands/spell-enchant.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when a PRD should be enhanced — UX, accessibility, security, performance — before implementation.
+---
+
 # Enchant
 
 Invoke the Arcane `spell-enchant` spell workflow.

package/dist/assets/.claude/commands/spell-explain-concept.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when the user needs a concept, architecture, or system behavior explained before deciding or building.
+---
+
 # Explain Concept
 
 Invoke the Arcane `spell-explain-concept` spell workflow.

package/dist/assets/.claude/commands/spell-feedback.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when the user reports friction with AI assistance or the workflow itself, not the product being built.
+---
+
 # Feedback
 
 Invoke the Arcane `spell-feedback` spell workflow.

package/dist/assets/.claude/commands/spell-full-cycle.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY for an end-to-end feature request that should chain plan, architect, implement, test, review, and ship.
+---
+
 # Full Cycle
 
 Invoke the Arcane `spell-full-cycle` spell workflow.

package/dist/assets/.claude/commands/spell-generate-bot-icons.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when a bot/agent needs a Teams-ready avatar and icon set generated.
+---
+
 # Generate Bot Icons
 
 Invoke the Arcane `spell-generate-bot-icons` spell workflow.

package/dist/assets/.claude/commands/spell-implement.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY to work through stories.json autonomously once architecture and stories exist.
+---
+
 # Implement
 
 Invoke the Arcane `spell-implement` spell workflow.

package/dist/assets/.claude/commands/spell-make-discoverable.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when auditing a web property's search/AI-assistant discoverability (metadata, robots, sitemap, indexing).
+---
+
 # Make Discoverable
 
 Invoke the Arcane `spell-make-discoverable` spell workflow.

package/dist/assets/.claude/commands/spell-manifest.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY in a hub repo to triage idea-book/todo-book entries downstream.
+---
+
 # Manifest
 
 Invoke the Arcane `spell-manifest` spell workflow.

package/dist/assets/.claude/commands/spell-open-session.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY at the start of any new session, even if the user just says 'let's start' or asks 'what's next'.
+---
+
 # Open Session
 
 Invoke the Arcane `spell-open-session` spell workflow.

package/dist/assets/.claude/commands/spell-plan.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when a feature description needs to become a PRD before architecture or implementation.
+---
+
 # Plan
 
 Invoke the Arcane `spell-plan` spell workflow.

package/dist/assets/.claude/commands/spell-present-arcane.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when asked to present, demo, or explain Arcane itself to an audience.
+---
+
 # Present Arcane
 
 Invoke the Arcane `spell-present-arcane` spell workflow.

package/dist/assets/.claude/commands/spell-product-review.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when evaluating a shipped feature's real-world performance and deciding next actions.
+---
+
 # Product Review
 
 Invoke the Arcane `spell-product-review` spell workflow.

package/dist/assets/.claude/commands/spell-review-batch.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when multiple open PRs need an adversarial review pass and a consolidated go/no-go verdict.
+---
+
 # Review Batch
 
 Invoke the Arcane `spell-review-batch` spell workflow.

package/dist/assets/.claude/commands/spell-review.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY before merging any nontrivial change, even if the user doesn't explicitly ask for review.
+---
+
 # Review
 
 Invoke the Arcane `spell-review` spell workflow.

package/dist/assets/.claude/commands/spell-save-idea.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY to capture a fleeting idea immediately, even if the user just says 'note that' or 'don't forget'.
+---
+
 # Save Idea
 
 Invoke the Arcane `spell-save-idea` spell workflow.

package/dist/assets/.claude/commands/spell-scope.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when a PRD is too large for one Spell Loop cycle and needs epic-splitting before architecture.
+---
+
 # Scope
 
 Invoke the Arcane `spell-scope` spell workflow.

package/dist/assets/.claude/commands/spell-security-review.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY before shipping any change that introduces new attack surface, handles sensitive data, or changes trust boundaries.
+---
+
 # Security Review
 
 Invoke the Arcane `spell-security-review` spell workflow.

package/dist/assets/.claude/commands/spell-ship.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY before any deploy, even if the user just says 'ship it'.
+---
+
 # Ship
 
 Invoke the Arcane `spell-ship` spell workflow.

package/dist/assets/.claude/commands/spell-status.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when asked for a quick snapshot of session/repo state — branch, TODOs, decisions, last journal.
+---
+
 # Status
 
 Invoke the Arcane `spell-status` spell workflow.

package/dist/assets/.claude/commands/spell-suggest-feature.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY when smoke testing or usage surfaces a feature gap worth tracking.
+---
+
 # Suggest Feature
 
 Invoke the Arcane `spell-suggest-feature` spell workflow.

package/dist/assets/.claude/commands/spell-summon-venture.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY in a hub repo when creating a new venture from scratch.
+---
+
 # Summon Venture
 
 Invoke the Arcane `spell-summon-venture` spell workflow.

package/dist/assets/.claude/commands/spell-test.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY to validate a completed story or feature against coverage thresholds before marking it done.
+---
+
 # Test
 
 Invoke the Arcane `spell-test` spell workflow.

package/dist/assets/.claude/commands/spell-todo.md

@@ -1,3 +1,7 @@
+---
+description: Use PROACTIVELY whenever a raw idea needs to become one or more well-scoped TODO items, even if the user just says 'add a todo'.
+---
+
 # Todo
 
 Invoke the Arcane `spell-todo` spell workflow.

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

@@ -66,6 +66,8 @@ Workflow:
    - Keep unresolved items open.
    - Remove completed checklist items only when completion is documented in the correct source-of-truth file.
 
+4b. **Register unfinished, task-bearing work on a durable surface (session handoff durability, ARC-040) before the handoff is written.** Enumerate: an incomplete `Active task`, the `Next concrete action`, and any content that would otherwise live only in `Notes` because it has no other durable home. For each, resolve the sink from `tracking_mode` (per ARC-032): `internal` → the appropriate `TODO.md` (root or venture book); `external` → a work item via the configured `external_provider`, falling back to `TODO.md` when tracker tooling is unavailable this session. Write or update the entry, then carry its location into step 5b so the handoff fields below can name it. Skip this step entirely when nothing is unfinished — a fully clean close has nothing to register.
+
 5. **Update [ai-context/system-prompt-context.md](../../ai-context/system-prompt-context.md).**
    - If priorities, environment state, or agent rules changed during the session, update the file to reflect current reality.
    - If no changes are needed, skip this step.
@@ -80,14 +82,14 @@ In `ai-context/system-prompt-context.md`, replace the existing `## Next Session
 > Auto-generated by spell-close-session. Consumed by spell-open-session. Do not edit manually.
 > Generated: YYYY-MM-DD
 
-- **Active task:** One-line description of the task that was in progress when this session closed.
+- **Active task:** One-line description of the task that was in progress when this session closed. If incomplete, name where step 4b registered it (e.g. `TODO.md:NNN`).
 - **Last completed step:** The final concrete action taken — include file path or command text. If that action was async work step 1b classified as anything other than `succeeded`, do not describe it as done here — name the action in `dispatched`/in-progress terms (e.g. "Pushed the fix and opened PR #NN" is fine; "Merged PR #NN" is not, unless step 1b confirmed the merge) and let `Pending Verification` carry the actual state.
-- **Next concrete action:** The exact first thing to do at next session start. Be specific: file, command, or decision. Never write "continue work."
+- **Next concrete action:** The exact first thing to do at next session start. Be specific: file, command, or decision. Never write "continue work." Name where step 4b registered it (e.g. `TODO.md:NNN`).
 - **Active files:** Files with uncommitted changes or the focus of the last edit (comma-separated).
 - **Branch:** Output of `git branch --show-current`.
 - **Blockers:** Known unresolved blockers or dependencies. Write "None" if clear.
 - **Pending Verification:** One line per non-`succeeded` item from step 1b: `<what> — <state> — <verification action>`. States: `dispatched`, `pending`, `failed`, `unverifiable` (never list a `succeeded` item here — it belongs in `Last completed step` / TODO.md / the journal instead, worded per the gating above). The verification action is required for `dispatched`, `pending`, and `unverifiable` — "N/A" is only valid for `failed`, where the state is already resolved and there is nothing left to check. Write "None" only if step 1b found every dispatched item resolved to `succeeded` or `failed` before this handoff was written.
-- **Notes:** Anything time-sensitive, fragile, or contextual that would be lost if not stated explicitly.
+- **Notes:** Anything time-sensitive, fragile, or contextual that would be lost if not stated explicitly. Never the sole carrier of durable content (session handoff durability) — if it names unfinished work, that work must also be registered per step 4b; name its location here.
 ```
 
 Rules:
@@ -251,6 +253,7 @@ Route the user to the right next spell based on the end state:
 Rules:
 
 - Do not invent completions — only mark items done if verifiable from context. "Verifiable" means classified `succeeded` under step 1b's five-state vocabulary (`dispatched`/`pending`/`succeeded`/`failed`/`unverifiable`), not merely "I can see it was started" (EF-21).
+- `Notes` is a pointer, never the sole carrier of durable content (session handoff durability) — if something needs to survive to next session, it must also live wherever step 4b registers it, not only in prose here.
 - Keep frontmatter date values in `YYYY-MM-DD`.
 - Preserve existing checklist and journal style.
 - Keep edits minimal and factual.

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

@@ -34,9 +34,9 @@ Use these files first:
 
 Check `ai-context/system-prompt-context.md` for a `## Next Session Handoff` section.
 
-- If present and **not yet marked consumed** (no `> ✓ Consumed:` line): surface it immediately as `## Picking Up From Last Session` at the very top of your output, before all other sections. Use the `Next concrete action` field as the first item in `## Next Session Plan`. Use the `Active task`, `Active files`, and `Branch` fields to pre-populate the State Snapshot.
+- If present and **not yet marked consumed** (no `> ✓ Consumed:` line): surface it immediately as `## Picking Up From Last Session` at the very top of your output, before all other sections — include `Last completed step`, `Blockers`, and `Notes` verbatim alongside the rest (session handoff durability: these three are written by close-session but were previously never read back). Use the `Next concrete action` field as the first item in `## Next Session Plan`. Use the `Active task`, `Active files`, and `Branch` fields to pre-populate the State Snapshot.
 - **If the handoff's `Pending Verification` field lists anything other than "None" (EF-21):** surface each listed item explicitly, then actively re-check its current status (per the item's stated verification action) rather than treating the state recorded at close-session time as still current — a `dispatched`/`pending` item may have since succeeded, failed, or still be running, and carrying it forward as inert text would repeat the exact failure mode this field exists to prevent. Report what you found (resolved succeeded / resolved failed / still pending / still unverifiable) before relying on anything downstream that depended on it.
-- After surfacing it, apply the Mutation Guard below before appending `> ✓ Consumed: YYYY-MM-DD` (today's date). The marker write is a repository mutation.
+- After surfacing it, apply the Mutation Guard below, then run the **Durability check** (session handoff durability, ARC-040): confirm that an incomplete `Active task`, the `Next concrete action`, and any task-bearing `Notes` content each name a durable location that genuinely exists (the cited `TODO.md` line, or tracker work item). If a named location is missing, or close-session's own step 4b was skipped when it shouldn't have been, register the missing content now — on this session's own branch — before proceeding. Only then append `> ✓ Consumed: YYYY-MM-DD` (today's date); the marker write is a repository mutation. If the Durability check cannot complete, leave the handoff unconsumed so the next open-session retries the same check idempotently, rather than silently losing the gap.
 - If the section is absent or already marked consumed: skip this step and proceed with the normal workspace scan.
 
 ## Mutation Guard (run lazily before the first repository write)

package/dist/assets/ai-context/system-prompt-context.md

@@ -23,11 +23,17 @@
 
 ## Next Session Handoff
 
-**Active task:** None yet.
-**Last completed step:** Initial scaffold via `spell init`.
-**Next concrete action:** Begin work.
-**Active files:** —
-**Branch:** main
-**Blockers:** None.
-**Pending Verification:** None.
-**Notes:** —
+> Auto-generated by spell-close-session. Consumed by spell-open-session. Do not edit manually.
+> Generated: YYYY-MM-DD
+
+- **Active task:** None yet.
+- **Last completed step:** Initial scaffold via `spell init`.
+- **Next concrete action:** Begin work.
+- **Active files:** —
+- **Branch:** main
+- **Blockers:** None.
+- **Pending Verification:** None.
+- **Notes:** —
+
+> ✓ Consumed: YYYY-MM-DD — scaffold placeholder, not a real session; ships pre-consumed so the first
+> real spell-open-session run does not mistake this for live handoff content.

package/dist/index.js

@@ -1444,6 +1444,22 @@ ${rules}
 **Denied:** ${def.tools.denied.join(", ")}
 `;
 }
+function renderSpellRoutingSection() {
+  return `## Spell Routing
+
+| When you're about to... | Invoke |
+|---|---|
+| Commit work | \`spell-commit-work\` |
+| Open a session | \`spell-open-session\` |
+| Close a session | \`spell-close-session\` |
+| Open a pull request | \`spell-create-pull-request\` |
+| Ship a feature end-to-end | \`spell-full-cycle\` |
+| Fix a bug | \`spell-bug\` |
+| Review code or a PR | \`spell-review\` |
+
+If a spell exists for the workflow you are about to perform, invoke it \u2014 do not improvise the workflow from general knowledge, even when the user doesn't name the spell.
+`;
+}
 function renderAgentRosterSection(entries) {
   const rows = entries.map(
     ({ def, displayName }) => `| **${displayName}** | ${def.role} | ${def.category} |`
@@ -1564,32 +1580,35 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
       }
       synced.push(`.github/agents/${fileName}`);
     }
-    const rosterSection = renderAgentRosterSection(resolved);
+    const copilotSection = `${renderSpellRoutingSection()}
+${renderAgentRosterSection(resolved)}`;
     const copilotMerged = await mergeIntoFile(
       targetDir,
       ".github/copilot-instructions.md",
-      rosterSection,
+      copilotSection,
       { force: true, dryRun: options.dryRun }
     );
     if (copilotMerged)
       synced.push(".github/copilot-instructions.md (agents section)");
   }
   if (options.claude !== false) {
-    const rosterSection = renderAgentRosterSection(resolved);
+    const claudeSection = `${renderSpellRoutingSection()}
+${renderAgentRosterSection(resolved)}`;
     const claudeMerged = await mergeIntoFile(
       targetDir,
       "CLAUDE.md",
-      rosterSection,
+      claudeSection,
       { force: true, dryRun: options.dryRun }
     );
     if (claudeMerged) synced.push("CLAUDE.md (agents section)");
   }
   if (options.codex !== false) {
-    const rosterSection = renderAgentRosterSection(resolved);
+    const codexSection = `${renderSpellRoutingSection()}
+${renderAgentRosterSection(resolved)}`;
     const codexMerged = await mergeIntoFile(
       targetDir,
       "AGENTS.md",
-      rosterSection,
+      codexSection,
       { force: true, dryRun: options.dryRun }
     );
     if (codexMerged) synced.push("AGENTS.md (agents section)");