arcane-cli 0.26.0 → 0.26.2

package/README.md

@@ -30,7 +30,7 @@ npm install -g arcane-cli   #  then:  spell init
 
 <div align="center">
 
-**🔁 opinionated lifecycle** &nbsp;·&nbsp; **📜 36 spells** &nbsp;·&nbsp; **🤖 12 agents** &nbsp;·&nbsp; **⚖️ 23 governance standards** &nbsp;·&nbsp; **📝 markdown-native** &nbsp;·&nbsp; **🔌 any AI client / tracker**
+**🔁 opinionated lifecycle** &nbsp;·&nbsp; **📜 38 spells** &nbsp;·&nbsp; **🤖 12 agents** &nbsp;·&nbsp; **⚖️ 23 governance standards** &nbsp;·&nbsp; **📝 markdown-native** &nbsp;·&nbsp; **🔌 any AI client / tracker**
 
 </div>
 
@@ -113,22 +113,27 @@ Arcane isn't a prompt snippet — it's a full framework. Everything installs int
 
 | Layer | What you get |
 | --- | --- |
-| 📜 **Spells** | **34** prompt-driven workflows spanning the entire lifecycle — planning, architecture, implementation, testing, review, shipping, session management, and ops. |
-| ⚖️ **Governance** | **19** battle-tested standards as drop-in templates: git conventions, testing standards, CI/CD, threat model, ADR format, naming, security hardening, and more. |
+| 📜 **Spells** | **38** prompt-driven workflows spanning the entire lifecycle — planning, architecture, implementation, testing, review, shipping, session management, and ops. |
+| ⚖️ **Governance** | **23** battle-tested standards as drop-in templates: git conventions, testing standards, CI/CD, threat model, ADR format, naming, security hardening, and more. |
 | 🤖 **Agents** | **12** ready-made agent personas with roles, clusters, and a gamified autonomy model — assign work and power levels per repo. |
 | 🛠️ **CLI** | `spell init / add / update / status / uninstall` — install by profile or à la carte, and keep everything in sync as new versions ship. |
 
+<!-- arcane:start -->
 <details>
-<summary><b>📜 The full spell catalogue (34)</b></summary>
-
-**Core Spell Loop** — `plan` · `enchant` · `scope` · `architect` · `implement` · `test` · `review` · `ship`
-**Session** — `open-session` · `close-session` · `status`
-**Operational & Git** — `commit-work` · `todo` · `check-drift` · `bug` · `create-pull-request` · `address-review` · `bump`
-**Specialized** — `full-cycle` · `review-batch` · `security-review` · `dotnet-expert` · `product-review` · `suggest-feature`
-**Knowledge & Docs** — `document` · `explain-concept` · `feedback` · `save-idea` · `manifest`
-**Business & Admin** — `summon-venture` · `brainstorm` · `generate-bot-icons` · `present-arcane` · `arcane-version`
+<summary><b>📜 The full spell catalogue (38)</b></summary>
+
+**Session** — `open-session` · `close-session` · `commit-work` · `status` · `arcane-version`
+**Capture** — `save-idea` · `todo` · `feedback` · `suggest-feature` · `document` · `brainstorm` · `explain-concept`
+**Delivery** — `create-pull-request` · `sync-pull-request` · `address-review`
+**Review** — `review` · `review-batch`
+**Planning** — `plan` · `architect` · `scope` · `product-review`
+**Build** — `implement` · `test` · `full-cycle` · `bug` · `bump` · `dotnet-expert` · `security-review` · `ship` · `enchant` · `generate-bot-icons` · `make-discoverable` · `scry`
+**Docs** — `adopt-docs`
+**Venture** — `summon-venture` · `manifest`
+**Meta** — `present-arcane` · `check-drift`
 
 </details>
+<!-- arcane:end -->
 
 <details>
 <summary><b>⚖️ The governance standards (23)</b></summary>

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

@@ -478,6 +478,17 @@ git branch -d <branch>                    # delete local branch (skip if branch
 git push origin --delete <branch>         # delete remote branch (safety net — --delete-source-branch true usually handles this; ignore 'does not exist' errors)
 ```
 
+**MCP fail-fast / fallback rule:** one abnormal MCP tool failure — a hang, an idle-timeout abort, a
+transport error, or an empty response where data is clearly expected — marks that MCP server **down
+for the rest of the session**. Do not retry it blindly. All subsequent operations that would have used
+it fall back to the documented CLI (`az repos pr` / `gh` / a direct REST call), and the downgrade is
+reported in output so a human sees it happened. The known-issues rows below (`MCP vote_pull_request`,
+`MCP create_pull_request`) are concrete instances of this general rule, not special cases of their own.
+**Consumer hardening:** set a per-server `"timeout"` (milliseconds) in `.mcp.json` so a hang aborts on a
+predictable schedule instead of running to the client's own default idle limit (as long as 30 minutes).
+Origin: a real ops session lost roughly an hour to two consecutive 30-minute MCP hangs before the
+documented `az` fallback was used (2026-08-14).
+
 **Known issues:**
 
 | Issue                                                                          | Symptom                               | Fix                                                                             |

package/dist/assets/.arcane/governance/portable-bootstrap.md

@@ -54,6 +54,12 @@ Paste this entire file into any AI client (Claude web, ChatGPT, etc.) to give it
 - **Project/domain documents:** use explicit descriptive paths such as `docs/`, `security/`, `infrastructure/`, or a configured business root. These add project context alongside framework standards.
 - **Overrides are not yet supported:** editing a managed `.arcane/governance/` standard can be replaced by `arcane update`. Additive project documents are safe; overriding a shipped standard requires the open customization/override model.
 
+## Research Reports
+
+Research findings (competitive analysis, technical spikes, feasibility studies — the output of the Research & Backlog Analyst role) live at `docs/research/<topic-slug>.md`, one file per report. No dedicated spell produces these: `spell-document` already proposes a target path from project structure and matches its destination directory's existing conventions — point it at `docs/research/` for investigative content, the same way it already proposes `docs/` or `.arcane/governance/` for other document types. The directory is created on first real report, not pre-seeded on `spell init`.
+
+Use this repo's standard frontmatter (below) plus one addition: `sources` — a list of what was consulted. Every claim in the body traces back to one of these or is explicitly marked speculative. Structure the body summary-first: a short **Summary** with the key findings, then **Findings** with full detail and inline citations, then an optional **Follow-ups** for anything that should become a TODO item — route those via `spell-todo`, which cross-references the report path. Throughout, distinguish **verified facts**, **reasonable inferences**, and **speculation** explicitly; don't let an inference read as a checked fact.
+
 ## Documentation Format
 
 Every doc uses YAML frontmatter: `title`, `audience` (human/ai/both), `last_updated`, `status` (draft/active/deprecated), `tags`. Use wiki-links (`[[filename]]`) for cross-references.

package/dist/assets/.github/instructions/agent-output.instructions.md

@@ -81,6 +81,13 @@ When completing a PR via `az repos pr update`, do **not** pass `--squash true`.
 az repos pr update --id <PR_ID> --org https://dev.azure.com/<org> --status completed --delete-source-branch true
 ```
 
+## MCP Fail-Fast / Fallback
+
+One abnormal MCP tool failure (hang, idle-timeout abort, transport error, empty response where data is
+expected) marks that server down for the rest of the session — fall back to the documented CLI (`az
+repos pr` / `gh` / REST), no blind retries, and report the downgrade in output. Full rule and origin
+incident: `.arcane/governance/git-conventions.md` → Known issues.
+
 ## Branch Naming (Interactive Sessions)
 
 Interactive tool session branches use:

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

@@ -31,7 +31,7 @@ Workflow:
    - Decisions made (even implicit ones like naming choices, tool preferences, or workflow patterns).
    - Problems encountered and how they were resolved (troubleshooting).
    - Lessons learned (anything that cost time, surprised the user, or should prevent future mistakes).
-   - **Capture tie-in tip:** If this session produced durable analysis worth formalizing (a design, an investigation, a reusable explanation), suggest running `spell-document` before closing so it lands in the right doc. For quick ideas worth keeping but not yet actionable, suggest `spell-save-idea`.
+   - **Capture tie-in tip:** If this session produced durable analysis worth formalizing (a design, an investigation, a research finding, a reusable explanation), suggest running `spell-document` before closing so it lands in the right doc — a research finding defaults to `docs/research/<topic-slug>.md` per `portable-bootstrap.md`'s Research Reports convention. For quick ideas worth keeping but not yet actionable, suggest `spell-save-idea`.
 
 1b. **Verify in-flight async work before writing any output artifact (EF-21). Enforcement: structured spell gate (ARC-023) — this workflow requires the observable state of every dispatched item before proceeding to step 2.** "I started it" is not "it worked." Before the journal, TODO.md, or the handoff are written, enumerate every piece of asynchronous work dispatched during this session that could still be running or could have failed after being kicked off — CI/CD runs, deployments, package publishes, long-running background tasks, PR checks. For each, **actively check** its current status through whatever means is available (CI provider API/CLI, deployment dashboard, `gh run view`, `az pipelines runs show`, etc.) — attempt the check before reaching for `unverifiable`; that state exists for genuine access limits (no CLI/API access, no credentials, provider outage), not for skipping a check that was merely inconvenient to run. Then classify into exactly one state:
 

package/dist/assets/.github/prompts/spell-commit-work.prompt.md

@@ -152,6 +152,8 @@ Workflow:
 
    a. Run `git push origin <branch>`.
 
+   a1. **MCP fail-fast / fallback.** If an MCP tool used anywhere in this step (e.g. `create_pull_request`) fails abnormally once — a hang, an idle-timeout abort, a transport error, or an empty response where data is clearly expected — treat that server as down for the rest of this session. Do not retry it blindly; fall back to the raw CLI paths below (`gh pr create` / `az repos pr create`) and report the downgrade. Full rule: `.arcane/governance/git-conventions.md` → Known issues.
+
    b. **🛑 Mandatory pre-PR rebase (governance guard, applies to every path below).** Before invoking any PR-creation command — whether via `spell-create-pull-request`, raw `gh pr create`, raw `az repos pr create`, or an MCP `create_pull_request` tool — you MUST:
 
    ```bash

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

@@ -25,8 +25,8 @@ The user's input describes what to capture and where. If no argument was provide
 Identify:
 
 - **Topics** — what conversation insights to extract (e.g., "naming analysis", "architecture comparison").
-- **Target paths** — where to write (e.g., `docs/...`, `.arcane/governance/...`). If the user gives only topics, propose sensible paths from the project structure.
-- **Document type** — reference doc, decision record, analysis report, inventory, or guide.
+- **Target paths** — where to write (e.g., `docs/...`, `.arcane/governance/...`). If the user gives only topics, propose sensible paths from the project structure. For a research report specifically (cited investigation, competitive analysis, feasibility study), default to `docs/research/<topic-slug>.md` per `portable-bootstrap.md`'s Research Reports convention.
+- **Document type** — reference doc, decision record, analysis report, research report, inventory, or guide.
 
 ## Step 2 — Extract from Conversation
 

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

@@ -118,6 +118,7 @@ Determine the target file(s) for each item:
 | Speculative idea or future-facing concept             | `TODO.md` under `## Product Ideas` or the best matching section                    |
 | ADR candidate                                         | `DECISIONS.md` — flag it as pending, do not write the full ADR yet                 |
 | Journal-worthy context                                | `journal/` — propose a filename with today's date slug, do not create the file yet |
+| Finding sourced from a research report                | `TODO.md` under the matching section — cross-reference the report path (e.g., `— see docs/research/<slug>.md`) |
 | Business-specific execution item                      | Both `TODO.md` AND the relevant `{BUSINESS_ROOT}/<name>/overview.md` reference section  |
 
 ## Step 4 — Show Proposal

package/dist/assets/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "$comment": "Example MCP server config. Replace or remove the example server below with your own. Set a per-server \"timeout\" (milliseconds) so a hung server aborts on a predictable schedule instead of running to the client's own default idle limit (as long as 30 minutes) -- see .arcane/governance/git-conventions.md's MCP fail-fast / fallback rule.",
+  "mcpServers": {
+    "example-server": {
+      "command": "npx",
+      "args": ["-y", "@example/mcp-server"],
+      "timeout": 30000
+    }
+  }
+}

package/dist/index.js

@@ -428,6 +428,15 @@ var COMPONENTS = [
     skipExisting: true,
     initOnly: true
   },
+  // Optional MCP config scaffold (BC-22/I12). skipExisting: a repo's own
+  // .mcp.json is user-owned server config Arcane must never overwrite.
+  // Not initOnly -- useful to retrofit via `spell add` on an existing repo too.
+  {
+    name: "mcp-config-template",
+    description: "Example .mcp.json with a per-server timeout, companion to the MCP fail-fast rule",
+    files: [".mcp.json"],
+    skipExisting: true
+  },
   {
     name: "records-conventions",
     description: "Supersession, tombstone, and retention conventions for records repositories",
@@ -4067,6 +4076,47 @@ async function checkPushPolicy(targetDir) {
     message: `declared "blocked" but not enforced \u2014 ${missing.join("; ")}. The manifest claims a protection this repository does not have.`
   };
 }
+async function checkMcpConfig(targetDir) {
+  const name = "MCP config (per-server timeout, I12)";
+  const filePath = join11(targetDir, ".mcp.json");
+  let raw;
+  try {
+    raw = await readFile6(filePath, "utf8");
+  } catch {
+    return { name, passed: true, blocking: false, message: "no .mcp.json \u2014 nothing to check" };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: ".mcp.json exists but contains invalid JSON"
+    };
+  }
+  const servers = parsed.mcpServers ?? {};
+  const serverNames = Object.keys(servers);
+  if (serverNames.length === 0) {
+    return { name, passed: true, blocking: false, message: "no MCP servers configured" };
+  }
+  const missingTimeout = serverNames.filter((n) => typeof servers[n]?.timeout !== "number");
+  if (missingTimeout.length > 0) {
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: `server(s) missing a "timeout": ${missingTimeout.join(", ")} \u2014 a hang runs to the client's own default idle limit (up to 30 min) instead of a predictable one`
+    };
+  }
+  return {
+    name,
+    passed: true,
+    blocking: false,
+    message: `${serverNames.length} server(s) configured, all with a timeout set`
+  };
+}
 async function checkDelegations(targetDir) {
   const name = "Standing delegations (T13)";
   const filePath = join11(targetDir, ".arcane", "delegations.json");
@@ -4152,7 +4202,8 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     checkPullRebase(targetDir),
     checkPushPolicy(targetDir),
     checkPlatformBranchPolicy(targetDir),
-    checkDelegations(targetDir)
+    checkDelegations(targetDir),
+    checkMcpConfig(targetDir)
   ]);
   const sessionResults = await checkSessionContinuity(targetDir);
   results.push(...sessionResults);