arcane-cli 0.38.3 → 1.0.0

package/dist/assets/.arcane/spells/spell-security-review.md

@@ -0,0 +1,152 @@
+---
+name: Spell — Security Review
+description: OWASP Top 10 and AI/agent (LLM) security audit plus dependency vulnerability check for any project
+claude_description: Use PROACTIVELY before shipping any change that introduces new attack surface, handles sensitive data, or changes trust boundaries.
+argument-hint: Project path, PR, or specific security concern (e.g., "auth flow in the API")
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt runs a security-focused review against OWASP Top 10 and dependency vulnerabilities.
+- No dedicated security agent needed — any agent loads this spell for security context (ADR-049).
+- Covers code-level vulnerabilities, dependency audit, secrets detection, and infrastructure security.
+- Includes an AI/agent (LLM) security pass — prompt injection, excessive agency, and secrets-in-context — since Arcane drives AI agents.
+- See [[security/threat-model|Threat Model]] for the project's security baseline.
+
+---
+
+Perform a security review of the specified code, project, or PR.
+
+Use these files for context:
+
+- [security/threat-model.md](../../security/threat-model.md) — Project threat model and security controls. If absent, proceed against a generic OWASP Top 10 + AI/agent baseline rather than assuming the file exists.
+- [security/hardening-checklist.md](../../security/hardening-checklist.md) — Infrastructure hardening status
+- [DECISIONS.md](../../DECISIONS.md) — Security-related ADRs
+
+Workflow:
+
+1. **Scope the review** — determine what's being reviewed:
+   - Specific PR or branch diff
+   - Full project audit
+   - Particular area of concern (auth, payments, data handling)
+
+1a. **Map trust boundaries and data flow** — before running the checklists below, sketch how data crosses trust zones (external actors, the auth boundary, internal services, data stores). This is agent-authored analysis under rule 8 (`.arcane/governance/universal-agent-rules.md`), not the generated-state-diagrams sub-convention ARC-036 covers — there is no already-computed trust-boundary state to read back, only the agent's own reasoning about the code. Use a Mermaid flowchart with a subgraph per trust zone:
+
+   ```mermaid
+   flowchart LR
+       subgraph External [Untrusted]
+           User[User / Client]
+       end
+       subgraph Boundary [Trust Boundary: Auth]
+           API[API Layer]
+       end
+       subgraph Internal [Trusted]
+           DB[(Data Store)]
+       end
+       User -->|request| API
+       API -->|authenticated query| DB
+   ```
+
+   Skip this step when the review scope doesn't cross any trust boundary — a single internal utility with no new external interaction, no new data store, and no new auth flow has nothing to diagram.
+
+2. **OWASP Top 10 checklist** — check each category:
+
+   | #   | Category                  | Check                                                                                       |
+   | --- | ------------------------- | ------------------------------------------------------------------------------------------- |
+   | A01 | Broken Access Control     | Role checks, authorization on every endpoint, CORS config                                   |
+   | A02 | Cryptographic Failures    | TLS enforcement, password hashing (bcrypt/Argon2), no hardcoded keys                        |
+   | A03 | Injection                 | SQL parameterization, XSS output encoding, command injection prevention                     |
+   | A04 | Insecure Design           | Threat modeling, rate limiting, abuse case coverage                                         |
+   | A05 | Security Misconfiguration | Default credentials, debug mode off, error messages sanitized                               |
+   | A06 | Vulnerable Components     | Dependency audit (`npm audit`, `dotnet list package --vulnerable`)                          |
+   | A07 | Auth Failures             | MFA support, session management, credential storage                                         |
+   | A08 | Data Integrity Failures   | CI/CD pipeline integrity, deserialization safety, update verification                       |
+   | A09 | Logging Failures          | Security events logged, no sensitive data in logs, log injection prevention                 |
+   | A10 | SSRF                      | URL validation, allowlists for external calls, no user-controlled URLs to internal services |
+
+3. **AI / Agent security** (OWASP LLM-aligned — critical for agent-driven repos):
+
+   | Risk | Check |
+   | ---- | ----- |
+   | Prompt injection (direct & indirect) | Is untrusted content (files, web, tool output, PR/issue text, user data) ever treated as instructions rather than data? Flag anywhere fetched or user-supplied content is concatenated into agent instructions or tool arguments without delimiting or validation. |
+   | Insecure output handling | Is model/agent output used to build shell commands, SQL, file paths, or HTML without validation or escaping? Flag any execute-from-model-output path that isn't sandboxed or checked. |
+   | Excessive agency / over-broad tools | Do agents or tool profiles grant more capability or autonomy than the task needs? Check power levels and tool scopes against least privilege; verify destructive tools are gated behind approval (see `agents/agent-policies.md`). |
+   | Secrets in context | Are secrets, tokens, or credentials placed into prompts, agent memory, journals, or tool arguments? Verify SecretRef-style indirection is used and secrets are never echoed into logs or model context. |
+   | Sensitive-data exposure via tools | Could the agent exfiltrate PII or secrets by sending them to external tools, MCP servers, or web endpoints? Check what crosses the trust boundary. |
+   | Untrusted tools / MCP supply chain | Are connected tools, MCP servers, and model endpoints trusted and pinned? Flag unverified or arbitrary tool sources. |
+
+   Align findings with the project threat model and agent policies.
+
+4. **Dependency audit**:
+   - Run `npm audit` (Node.js) or `dotnet list package --vulnerable` (.NET).
+   - Check for known CVEs in direct and transitive dependencies.
+   - Flag any dependency more than 2 major versions behind.
+
+5. **Secrets detection**:
+   - Scan for API keys, tokens, passwords, connection strings in code.
+   - Check `.env` files are in `.gitignore`.
+   - Verify secrets management approach (environment variables, Key Vault, SecretRef).
+
+6. **Infrastructure security** (if applicable):
+   - Terraform security (Checkov scan).
+   - Network exposure (is anything public that shouldn't be?).
+   - IAM/RBAC configuration (least privilege).
+
+7. **Generate security report**:
+   ```markdown
+   ## Security Review — [Project/Feature]
+
+   **Reviewer:** [Agent name]
+   **Date:** [timestamp]
+   **Scope:** [What was reviewed]
+
+   ### Trust Boundary / Data Flow
+   [Mermaid flowchart from step 1a — omit this section entirely if step 1a was skipped]
+
+   ### OWASP Top 10 Results
+   | Category                  | Status    | Findings  |
+   | ------------------------- | --------- | --------- |
+   | A01 Broken Access Control | PASS/FAIL | [details] |
+   | ...                       | ...       | ...       |
+
+   ### AI/Agent Security Results
+   | Risk                     | Status    | Findings  |
+   | ------------------------ | --------- | --------- |
+   | Prompt injection         | PASS/FAIL | [details] |
+   | Insecure output handling | PASS/FAIL | [details] |
+   | Excessive agency         | PASS/FAIL | [details] |
+   | Secrets in context       | PASS/FAIL | [details] |
+
+   ### Dependency Audit
+   - Critical vulnerabilities: [N]
+   - High vulnerabilities: [N]
+   - Action required: [list]
+
+   ### Secrets Scan
+   - Hardcoded secrets found: [yes/no]
+   - Secrets management: [approach]
+
+   ### Findings (by severity)
+   #### CRITICAL
+   - [Finding with remediation]
+
+   #### HIGH
+   - [Finding with remediation]
+
+   #### MEDIUM
+   - [Finding with remediation]
+
+   ### Verdict
+   - [ ] PASS — no critical or high findings
+   - [ ] FAIL — remediation required before deploy
+   ```
+
+8. **Present findings** — show the report with clear remediation steps for each finding.
+
+Rules:
+- **Never skip a category.** Every OWASP item must be checked, even if marked N/A with justification.
+- **Provide remediation, not just findings.** Every finding must include how to fix it.
+- **Don't cry wolf.** Only flag real vulnerabilities, not theoretical risks with no attack vector.
+- **Check the threat model.** Findings should align with the project's actual threat landscape.
+- **Treat external content as untrusted.** In agent code, assume any file-, web-, or tool-sourced text could be hostile — flag anywhere it can steer the agent or reach a sink (shell, SQL, eval, file write, outbound HTTP) unchecked.

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

@@ -0,0 +1,106 @@
+---
+name: Spell — Ship
+description: Pre-deploy checklist, merge approval workflow, and deployment gate verification
+claude_description: Use PROACTIVELY before any deploy, even if the user just says 'ship it'.
+argument-hint: Branch name or PR number to ship
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt runs the pre-deploy checklist and manages the merge/deploy approval workflow.
+- It verifies all Spell Loop phases are complete before allowing a merge.
+- Enforces deployment gates from governance/cicd-standards.md.
+- Final gate is always human approval — agents cannot autonomously ship to production.
+
+---
+
+Run the ship workflow for the specified branch or PR.
+
+Use these files for context:
+
+- [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) — Spell Loop phases
+- [governance/cicd-standards.md](../../.arcane/governance/cicd-standards.md) — CI/CD pipeline requirements and deployment gates
+- [governance/testing-standards.md](../../.arcane/governance/testing-standards.md) — Coverage thresholds
+- [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) — Branch policies and merge strategy
+
+Workflow:
+
+1. **Verify Spell Loop completion** — check that all prior phases passed:
+   - [ ] PRD exists and was approved (or Quick Flow justified skipping it).
+   - [ ] Architecture doc exists (or Quick Flow justified skipping it).
+   - [ ] All stories in stories.json have `"passes": true`.
+   - [ ] Test evidence exists with passing thresholds.
+   - [ ] Code review completed with APPROVE verdict.
+
+2. **Sync with the target branch** — actually perform the sync, do not just assert it:
+   - Run `git fetch origin` to get the latest refs.
+   - Merge the target branch into the current branch (e.g. `git merge origin/<target>`).
+   - **On merge conflicts:** STOP and ask the user to resolve them, or run `spell-sync-pull-request` — it handles exactly this case, with a recoverable ref and an explicit mechanical-vs-ambiguous conflict boundary. Do not attempt to auto-resolve here.
+   - After a clean merge (or once the user has resolved conflicts), re-run the full test suite and confirm it passes.
+   - Push the synced branch (e.g. `git push`).
+
+3. **Run pre-deploy checklist**:
+   - [ ] All CI pipeline checks pass (build, test, lint, security scan).
+   - [ ] Branch synced with target (fetch + merge completed in step 2, no outstanding conflicts).
+   - [ ] No secrets or credentials in the diff.
+   - [ ] DECISIONS.md updated if new ADRs were created.
+   - [ ] Documentation updated for user-facing changes.
+   - [ ] **Package version bumped** (if `package.json` exists): run `npm view <package-name> version` to get the last published version, then confirm `package.json` `version` field is higher. BLOCK the ship if the version has not been incremented — the pipeline will skip publishing an already-published version, so a bump is required to actually release.
+
+4. **Ensure a PR exists** — before declaring the branch ready to ship, verify that a pull request exists for it. If none exists, STOP and direct the user to run `spell-create-pull-request` to open one. The ship checklist cannot complete without an open PR.
+
+5. **Deployment gate verification** — per cicd-standards.md:
+   - **Staging:** CI green + code review approved.
+   - **Production:** Staging validated + human approval + rollback plan documented.
+   - **Terraform:** Plan output reviewed + human approval for any destroy operations.
+
+6. **Generate ship report**:
+   ```markdown
+   ## Ship Report — [Feature/Branch]
+
+   **Date:** [timestamp]
+   **Target:** [main / release branch]
+
+   ### Spell Loop Status
+   | Phase     | Status    | Evidence                             |
+   | --------- | --------- | ------------------------------------ |
+   | Plan      | PASS/SKIP | [PRD link or justification]          |
+   | Architect | PASS/SKIP | [Architecture link or justification] |
+   | Implement | PASS      | [N stories complete]                 |
+   | Test      | PASS      | [Coverage %, test count]             |
+   | Review    | PASS      | [Review link, verdict]               |
+
+   ### Pre-Deploy Checklist
+   - [x/- for each item above]
+
+   ### Deployment Gate
+   - Target environment: [staging/production]
+   - Gate requirements met: [yes/no]
+   - Rollback plan: [documented/not needed]
+
+   ### Recommendation
+   - APPROVE for merge and deploy
+   - OR: BLOCK — [reason]
+   ```
+
+7. **Request human approval** — present the ship report and wait for explicit approval.
+
+8. **Execute merge** (after approval):
+   - Merge using the project's merge strategy as defined in [governance/git-conventions.md](../../.arcane/governance/git-conventions.md). **Do NOT squash** — squash merges are prohibited because they collapse per-commit attribution. Prefer rebase and fast-forward.
+   - Verify CI passes on the target branch post-merge.
+   - Tag release if applicable.
+
+9. **Post-merge branch cleanup** (after the PR merges) — the merge was the human gate, so cleanup is automatic:
+   - **First, which primitive are you in?** `git rev-parse --path-format=absolute --git-common-dir` vs `--git-dir` — equal means primary checkout, different means linked worktree. (`--path-format=absolute` is required; without it the two differ from any subdirectory and every primary checkout reads as a worktree.) **In a linked worktree, skip the two steps below** (ARC-028 R1/R8): `git checkout main` fails when another working tree holds `main`, and it fails *first*, so the rest of this cleanup block never runs and the remote branch deletion below is left half-done. Report the worktree path for removal from another vantage point instead, and go straight to the remote-branch and prune steps.
+   - Switch to the main branch (e.g. `git checkout main`).
+   - Pull the latest (e.g. `git pull`).
+   - Delete the merged topic branch locally (e.g. `git branch -d <branch>`) — if the repository or its linked worktrees might be reached through more than one filesystem view, run the same-vantage-point check first (EF-33 / ARC-028 R7, [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) Same-Vantage-Point Check section).
+   - Delete the merged topic branch on the remote (e.g. `git push origin --delete <branch>`); tolerate an already-deleted remote branch.
+   - Prune stale remote-tracking refs (e.g. `git fetch --prune` or `git remote prune origin`).
+
+Rules:
+- **Never merge without human approval.** This spell always ends with a human gate.
+- **Never skip the checklist.** Every item must be verified, not assumed.
+- **Block on failures.** If any checklist item fails, the ship is blocked until fixed.
+- **Document what shipped.** The ship report is the audit trail.

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

@@ -0,0 +1,86 @@
+---
+name: Spell — Status
+description: Show a fast, read-only snapshot of the current session — branch, git working state, open TODO count, decision count, and last journal date. Text or JSON.
+claude_description: Use PROACTIVELY when asked for a quick snapshot of session/repo state — branch, TODOs, decisions, last journal.
+argument-hint: Optional flags — e.g., --verbose --format json
+agent: agent
+---
+
+## Executive Summary
+
+- This spell prints a quick state snapshot for the current repo. It never modifies files.
+- It reads local git state plus arcane session files (`TODO.md`, `DECISIONS.md`, `journal/`).
+- Use it any time mid-session to re-orient without running the full `spell-open-session` pass.
+
+---
+
+Show the current session status for this repository. This is a read-only spell.
+
+## Inputs
+
+- Optional `--verbose` — include changed-file paths and the first few open TODOs.
+- Optional `--format text|json` — default is `text`.
+
+If no flags are given, use default text mode.
+
+## Steps
+
+0. Confirm this is a git repository (e.g., `git rev-parse --is-inside-work-tree`). If it is not, skip the git steps and set `branch`, `unpushedCommits`, `staged`, `unstaged`, and `untracked` to `unknown` (text) / `null` (JSON); still report the file-based counts in steps 4–6 if those files exist. Note `not a git repository` in the output.
+1. Run `git branch --show-current` and capture the branch name. If it returns empty, you are in **detached HEAD** — report the branch as `detached@{short-sha}` (use `git rev-parse --short HEAD`).
+2. Run `git rev-list --count @{upstream}..HEAD` for unpushed commit count. If there is no upstream (no tracking branch, or detached HEAD), set this to `unknown` (text) / `null` (JSON). Do not treat the absence of an upstream as `0`.
+3. Run `git status --short` and compute counts: staged, unstaged, untracked. A clean tree is `0`/`0`/`0`.
+4. Count open TODOs in `TODO.md` (unchecked `- [ ]` items). If the file is missing, count `0`.
+5. Count decision entries in `DECISIONS.md` — count one per decision-record heading (the `ADR-NNN` / `ARC-NNN` entry headings, e.g. `## ARC-012 ...`). Do not count cross-reference table rows or inline mentions, and de-duplicate repeated IDs. If the file is missing, count `0`.
+6. Determine the last session date from the most recent file in `journal/` (filenames follow `YYYY-MM-DD-topic-slug.md`; sort by the leading date, not file mtime). If `journal/` is missing or contains no dated entries, report `none` (text) / `null` (JSON).
+
+## Output
+
+### Text mode (default)
+
+One concise line:
+
+```
+[{branch}] ↑{unpushed} | {staged}● {unstaged}✎ {untracked}? | {openTodos} TODOs | {decisions} ADRs | last session: {date}
+```
+
+Glyph key: `↑` unpushed commits, `●` staged, `✎` unstaged, `?` untracked. Render `unknown` / `none` literally in the slot when a value cannot be determined (e.g. `↑unknown`, `last session: none`). When not a git repo, prefix the line with `not a git repository — ` and show `unknown` for all git-derived slots.
+
+If `--verbose`, also print:
+
+- a short bullet list of changed file paths from `git status --short`
+- the first 5 open TODO lines
+
+### JSON mode (`--format json`)
+
+```json
+{
+  "branch": "main",
+  "isGitRepo": true,
+  "detachedHead": false,
+  "unpushedCommits": 0,
+  "staged": 0,
+  "unstaged": 0,
+  "untracked": 0,
+  "openTodos": 0,
+  "decisions": 0,
+  "lastSessionDate": "YYYY-MM-DD",
+  "modifiedFiles": []
+}
+```
+
+Field conventions (keep JSON consistent with the text shape):
+
+- `branch` — string; `detached@{short-sha}` when in detached HEAD; `null` when not a git repo.
+- `isGitRepo` — boolean. When `false`, all git-derived fields (`unpushedCommits`, `staged`, `unstaged`, `untracked`, `branch`) are `null`.
+- `detachedHead` — boolean.
+- `unpushedCommits` — integer, or `null` when there is no upstream / detached HEAD (the JSON analogue of text `unknown`). Never silently `0`.
+- `lastSessionDate` — `YYYY-MM-DD` string, or `null` when no dated journal entry exists (the analogue of text `none`).
+- `modifiedFiles` — populated only when `--verbose` is set; otherwise `[]`.
+
+## Rules
+
+- Read-only — never edit, create, stage, or commit any file. Use only inspection commands (`git status`, `git rev-list`, `git branch`, file reads).
+- Prefer exact values from local git and files; do not estimate.
+- Never fail the whole snapshot because one source is unavailable. A missing count file is `0`; an undeterminable git value is `unknown` (text) / `null` (JSON); a non-git directory still reports file-based counts.
+- Counts vs. unknowns are distinct: a real `0` (clean tree, empty TODO) is not the same as `unknown`/`null` (could not determine). Do not collapse one into the other.
+- Keep text output to a single line unless `--verbose` is set.

package/dist/assets/.arcane/spells/spell-suggest-feature.md

@@ -0,0 +1,122 @@
+---
+name: Spell — Suggest Feature
+description: Capture a feature suggestion from smoke testing or usage — assesses impact, files a tracker item (provider-aware), and adds to backlog
+claude_description: Use PROACTIVELY when smoke testing or usage surfaces a feature gap worth tracking.
+argument-hint: Feature idea (e.g., "Settings page to change instance name and gateway URL")
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt captures feature suggestions discovered during smoke testing or regular use.
+- It creates a structured user story, assesses impact, and files a tracker item using whatever provider the repo is configured for (respects `tracking_mode`; ADO is one option, not an assumption).
+- Output is a tracked backlog item ready for future `spell-plan` invocation (or `spell-scope` for large, multi-feature suggestions).
+- See [[.arcane/governance/development-methodology|Development Methodology]] for the full Spell Loop reference and tracker-provider specifics.
+
+---
+
+Capture and document the described feature suggestion.
+
+Use these files for context:
+
+- [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) — Spell Loop methodology
+- [project.md](../../project.md) — Project goals and priorities
+- [DECISIONS.md](../../DECISIONS.md) — Existing ADRs to check for overlap
+- [TODO.md](../../TODO.md) — Current backlog items
+
+Workflow:
+
+1. **Capture the suggestion** — gather these details from the user (ask if missing):
+
+   | Field | Description |
+   |-------|-------------|
+   | **Title** | Short descriptive name for the feature |
+   | **User story** | "As a [role], I want [capability], so that [benefit]" |
+   | **Discovery context** | What were you doing when you noticed this gap? |
+   | **Affected area** | Page, component, workflow, or system |
+   | **Priority suggestion** | Must-have / Should-have / Nice-to-have |
+
+2. **Check for duplicates** — before creating a work item:
+   - Search `TODO.md` for related items.
+   - Search `DECISIONS.md` for ADRs that already cover this.
+   - Check the relevant PRD at `{PRD_PATH}` for existing must-haves (resolve from `.arcane.json` or the active feature/PRD frontmatter; if unset, ask the user — or skip this check if the repo has no PRD).
+   - If the feature is already planned, note which must-have (MH-XX) it maps to and skip to Step 6.
+
+3. **Assess impact** — quick evaluation:
+
+   | Dimension | Assessment |
+   |-----------|------------|
+   | **Who benefits?** | Which users/personas are affected |
+   | **Effort estimate** | S (< 1 day) / M (1-3 days) / L (3+ days) |
+   | **Dependencies** | What must exist first? Other features, infrastructure, ADRs? |
+   | **Risk** | Low / Medium / High — any security, UX, or architecture implications? |
+   | **Phase recommendation** | Which phase should this land in? (current, next, future) |
+
+4. **Resolve tracking mode** — before creating a tracker item:
+   - Read `tracking_mode` / `external_provider` from `.arcane.json` or the active PRD frontmatter if available.
+   - If missing, ask the user:
+     <!-- fragment:tracking-mode-declaration:start -->
+     - `tracking_mode: internal | external`
+     - `external_provider: ado | github | jira | other`
+     <!-- fragment:tracking-mode-declaration:end -->
+     - (`external_provider` is required only for external mode)
+   - If ADO context is already active and no explicit choice is provided, default to `external` + `ado` for backward compatibility.
+
+5. **Create tracker item (conditional)**:
+   - If `tracking_mode=external` and `external_provider=ado`, create a work item:
+     ```bash
+     az boards work-item create \
+       --type "User Story" \
+       --title "{title}" \
+       --description "{formatted user story + impact assessment}" \
+       --org https://dev.azure.com/{org} \
+       --project {project} \
+       --output json
+     ```
+     Extract the work item ID from the response.
+   - If `tracking_mode=external` and `external_provider=github`, create an issue:
+     ```bash
+     gh issue create \
+       --title "{title}" \
+       --body "{formatted user story + impact assessment}" \
+       --label enhancement
+     ```
+     `gh issue create` prints the created issue's URL; extract the trailing number as the issue ID. `--label` names must exist in the repo already (`gh label list`) — omit it rather than guessing a label that isn't there.
+   - If `tracking_mode=internal`, skip external item creation and track in `TODO.md` only.
+   - If `external_provider=jira` or `other`, add a TODO note for provider-specific automation and continue with `TODO.md` tracking.
+   - The ADO and GitHub commands above are illustrative; for the authoritative per-provider creation steps and field mappings, see [[.arcane/governance/development-methodology|Development Methodology]].
+
+6. **Update backlog** — add a line to `TODO.md`:
+   ```markdown
+   - [ ] {Title} — {one-line description} (tracking: {internal|provider#{id}|provider TODO}, {priority}, {effort})
+   ```
+   If the feature maps to an existing must-have, note the mapping instead of creating a duplicate entry.
+
+7. **Present summary** — show the user what was captured:
+   ```markdown
+   ## Feature Suggestion: {Title}
+
+   **User Story:** As a {role}, I want {capability}, so that {benefit}.
+   **Discovery:** {context}
+   **Impact:** {who benefits} | Effort: {S/M/L} | Phase: {recommendation}
+   **Tracking:** {internal-only | ado #{workItemId} | jira/other TODO + TODO.md}
+   **Dependencies:** {list or "None"}
+   **Duplicates/Overlaps:** {existing MH-XX or "None found"}
+   ```
+
+Rules:
+- Do not implement the feature — this spell only captures and tracks it.
+- If the suggestion overlaps with an existing planned feature, make the connection explicit rather than creating a duplicate.
+- The user decides priority — recommendations are just that.
+- Present the `TODO.md` edit for approval before saving.
+- If multiple related suggestions come in at once, capture each as a separate work item but note the relationship.
+
+## Related Spells
+
+This spell sits at the front of the Spell Loop — it captures and tracks; it does not plan or build. Hand off downstream:
+
+- **Feeds into [[spell-plan|spell-plan]]** — a captured suggestion is the input to planning. Once tracked here, invoke `spell-plan` to turn it into an implementation plan.
+- **Feeds into [[spell-scope|spell-scope]]** for large or multi-feature suggestions — if the impact assessment lands on **L** effort (or the idea spans several features), route it to `spell-scope` first to break it down before planning.
+- **Consumes from usage/testing** — there is no upstream spell; suggestions originate from smoke testing or regular use (e.g. while running `spell-test`).
+
+See [[.arcane/governance/development-methodology|Development Methodology]] for the canonical Spell Loop hand-off flow.

package/dist/assets/.arcane/spells/spell-summon-venture.md

@@ -0,0 +1,110 @@
+---
+name: Spell — Summon Venture
+description: Create a new venture in a hub repo — folder, overview/config/legal docs, idea and todo books, and a registry entry — in one hub-gated move.
+claude_description: Use PROACTIVELY in a hub repo when creating a new venture from scratch.
+argument-hint: Venture Name | Venture Type | One-line description
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt creates a new venture in a **hub** repo: the venture folder, its starter docs, its two idea/todo books, and its registry entry — one operation instead of several manual steps.
+- **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 ARC-008's precedent (cited as plain text, not linked — this file ships; see `agent-output.instructions.md` → Doc-ID Link Format).
+
+---
+
+## Step 0 — Hub Gate
+
+Read `.arcane.json`. If `role` is not `"hub"`, stop and report:
+
+> `spell-summon-venture` runs only in a hub repo (`role: "hub"` in `.arcane.json`). This repo is a consumer. If you're capturing an idea for a venture that should exist, save it in the hub instead — ask there for `spell-save-idea --venture <new-slug> "<idea>"`, which offers to scaffold the venture book if the slug doesn't exist yet.
+
+Do not create anything. Do not infer hub status from a `ventures/` directory existing — that directory can legitimately exist in a consumer repo too (this exact spell creates it there in non-hub contexts under the old model; the gate is what changed).
+
+If `role` is `"hub"`, resolve `{BUSINESS_ROOT}` from `.arcane.json`'s `business_root` field (default `ventures/`) and continue.
+
+## Step 1 — Gather Venture Details
+
+Parse the prompt argument as:
+`<Venture Name> | <Venture Type> | <One-line Description>`
+
+If any required value is missing, ask only for missing fields. Additionally ask for **ownership** if not stated or inferable from context: `llc` (company-owned), `co-venture` (shared with an external partner), or `personal` (non-commercial, no co-owner) — never guess this; it's load-bearing for the registry and for later idea-lifecycle disclosure decisions.
+
+Use these files first (each is optional — if missing, proceed as noted):
+
+- [playbooks/new-business-setup.md](../../playbooks/new-business-setup.md) — setup playbook. If `playbooks/` doesn't exist, skip and derive steps from the venture-type checklist below.
+- [naming-conventions.md](../../.arcane/governance/naming-conventions.md) — slug/file naming rules. If missing, default to lowercase-with-dashes slugs.
+- `{BUSINESS_ROOT}/_template/overview.md` — overview template. If missing, generate a minimal overview from the fields below.
+- [.arcane/templates/venture-template/IDEAS.md](../../.arcane/templates/venture-template/IDEAS.md) and [.arcane/templates/venture-template/TODO.md](../../.arcane/templates/venture-template/TODO.md) — book stubs. If missing, use the header format from [[spell-save-idea|spell-save-idea]] / [[spell-todo|spell-todo]].
+- [README.md](../../README.md) — repo navigation. If missing, skip cross-linking.
+- [project.md](../../project.md) — project context. If missing, skip.
+
+## Step 2 — Create the Venture
+
+1. Create `{BUSINESS_ROOT}/<slug>/` using existing repo style (lowercase with dashes). If `{BUSINESS_ROOT}` doesn't exist yet, create it.
+2. Create these files:
+   - `overview.md` from template, filled with provided venture details and current date.
+   - `config.md` with placeholders for `{PLATFORM_NAME}` configuration, data paths, and platform integrations. (`{PLATFORM_NAME}` is the org's operating platform — resolve from `.arcane.json`/frontmatter; ask if unset.)
+   - `legal.md` with baseline legal checklist and links to relevant repo docs.
+   - `IDEAS.md` from the venture-template stub, with the venture name filled in.
+   - `TODO.md` from the venture-template stub, with the venture name filled in.
+3. Add a startup checklist tailored to the venture type (`e-commerce`, `app`, `protocol`, `service`, or `personal`).
+
+## Step 3 — Register the Venture
+
+Open (or create, with the standard header — see `{BUSINESS_ROOT}/registry.json`'s own `_comment` field for the expected shape) `{BUSINESS_ROOT}/registry.json` and append an entry keyed by the slug:
+
+```json
+"<slug>": {
+  "name": "<Venture Name>",
+  "aliases": [],
+  "status": "idea",
+  "visibility": "private",
+  "ownership": "<llc|co-venture|personal>",
+  "tracking": "none",
+  "repos": []
+}
+```
+
+`status` starts `"idea"` and `tracking` starts `"none"` — this spell only creates the hub-side folder, it does not provision a code repo or tracker project. Update the `repos[]` array separately once a real repo exists. `visibility` defaults to `"private"`; only change it if the operator states the venture is public-facing at creation time.
+
+## Step 4 — Cross-Links and Summary
+
+Add cross-links only when appropriate:
+
+- Update [README.md](../../README.md) only if there is a clear place for venture navigation.
+- Update [TODO.md](../../TODO.md) (hub root) only with concrete, actionable next tasks — venture-specific tasks belong in the new venture's own `TODO.md`, not here.
+
+Return a ready-to-start summary.
+
+Output format:
+
+## Created
+
+- File and folder paths created, including the `{BUSINESS_ROOT}/registry.json` entry.
+
+## Defaults Applied
+
+- Slug, ownership, naming decisions, and template assumptions used.
+
+## Immediate Next Actions
+
+1. Action one.
+2. Action two.
+3. Action three.
+4. Action four.
+5. Action five.
+
+## Questions To Finalize
+
+- Up to 3 targeted questions, or `None`.
+
+Rules:
+
+- Follow repository frontmatter conventions.
+- Do not create Azure resources directly; document steps only.
+- Keep generated docs editable and operational, not verbose.
+- Never run outside a hub repo. Never infer hub status — only `role: "hub"` counts.