arcane-cli 0.14.0

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

@@ -0,0 +1,263 @@
+---
+name: Spell — Scope
+description: Analyze a large PRD — scope it, split into epics, check architecture and security implications, estimate effort, and produce an execution plan with agent assignments
+argument-hint: "Path to PRD or paste PRD content (e.g., 'Analyze PRD.md for {BUSINESS_NAME} mobile app')"
+agent: agent
+---
+
+## Executive Summary
+
+- This spell takes a PRD of any size and produces an actionable execution plan.
+- It assesses scope, splits into sprint-sized epics, identifies architecture/security decisions needed, and maps agents to work.
+- Use this before `spell-architect` when the PRD is too large for a single Spell Loop cycle. (Formerly `spell-assess`.)
+- Output: `execution-plan.md` — ordered epics with dependency graph, risk flags, ADR candidates, and agent assignments.
+
+---
+
+Analyze the provided PRD and produce a scoped execution plan.
+
+Use these files for context. Each is optional — if a file is missing, proceed with the stated fallback and note the gap in the output's Open Questions:
+
+- [governance/development-methodology.md](../../governance/development-methodology.md) — Spell Loop methodology, story sizing rules, and the canonical **ADO Hierarchy Rules**. *Fallback: if missing, use the default sizing of 4–8 right-sized stories per cycle described below and skip external-tracker hierarchy mapping.*
+- [governance/testing-standards.md](../../governance/testing-standards.md) — Testing frameworks per stack. *Fallback: if missing, flag test strategy as an open question.*
+- [governance/cicd-standards.md](../../governance/cicd-standards.md) — Pipeline requirements. *Fallback: if missing, omit pipeline considerations.*
+- [DECISIONS.md](../../DECISIONS.md) — Existing ADRs to check against. *Fallback: if missing, treat all architecture decisions as new candidates.*
+- [security/threat-model.md](../../security/threat-model.md) — Active threat model. *Fallback: if missing, apply OWASP Top 10 as the baseline.*
+- [agents/agent-policies.md](../../agents/agent-policies.md) — Agent roster, power levels, capabilities. *Fallback: if missing, assign work by role label (architecture, backend, frontend, mobile, QA, DevOps, research) instead of named personas.*
+- [naming-conventions.md](../../naming-conventions.md) — Agent roster and role-to-persona mapping. *Fallback: if missing, refer to roles by their generic label.*
+- [project.md](../../project.md) — Project goals and business context. *Fallback: if missing, derive context from the PRD itself.*
+- [governance/product-excellence-standards.md](../../governance/product-excellence-standards.md) — PRD Quality Scorecard and scoring rubric. *Fallback: if missing, skip the Quality Quick-Check (section 1.5) and note that it was skipped.*
+
+> **Roster by reference.** This spell maps work to **roles** (architecture, backend, frontend, mobile, QA, DevOps, research, marketing). Resolve each role to a concrete agent persona via `agents/agent-policies.md` / `naming-conventions.md` at run time — do not assume a fixed set of persona names.
+
+> **Placeholder resolution.** `{ADO_ORG}`, `{ADO_PROJECT}`, `{BUSINESS_NAME}`, and any other `{UPPER_SNAKE}` token resolve from `.arcane.json` or the PRD frontmatter; if a value is unset, ask rather than assuming a default.
+
+---
+
+## Workflow
+
+### 1. PRD Intake
+
+Accept the PRD from one of these input sources:
+
+| Source | Format | How to fetch |
+|--------|--------|--------------|
+| **File path** | `PRD.md` or any markdown file | Read the file directly |
+| **Pasted content** | Inline text in the prompt | Use as-is |
+| **External tracker work item ID** (external mode) | `#507` or `507` with org name | Detect the provider (see tracking settings below) and fetch the item's title, description, and acceptance criteria via that provider's CLI/API. For ADO: `az boards work-item show --id {id} --org https://dev.azure.com/{ADO_ORG} --output json` and extract `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`, and `System.Title` |
+
+If the input is an external work item ID:
+1. Confirm the org/account: `{ADO_ORG}` — resolve from `.arcane.json` / PRD frontmatter; ask if unset.
+2. Fetch the item via the detected provider (for ADO: `az boards work-item show`).
+3. If the work item has child items, fetch those too — they may contain additional requirements.
+4. Combine all content into a single PRD view before proceeding.
+
+Resolve tracking settings from PRD frontmatter (preferred) or ask:
+- `tracking_mode: internal | external`
+- `external_provider: ado | jira | other`
+
+If unset and ADO context already exists, default to `external` + `ado` for backward compatibility.
+
+If `tracking_mode=external` and `external_provider=ado`, resolve template/type availability before splitting epics (resolve `{ADO_ORG}` / `{ADO_PROJECT}` from `.arcane.json` / PRD frontmatter; ask if unset):
+```bash
+az devops project show --org https://dev.azure.com/{ADO_ORG} --project {ADO_PROJECT} --query "capabilities.processTemplate.templateName" --output tsv
+az boards work-item-type list --org https://dev.azure.com/{ADO_ORG} --project {ADO_PROJECT} --output json --query "[].name"
+```
+For non-ADO providers, detect the provider from `external_provider` and resolve its equivalent item types instead.
+
+Read the full PRD. Extract:
+- **Feature name** and business context
+- **Target repo** and tech stack
+- **Total requirement count** (Must Have / Should Have / Won't Have)
+- **Total acceptance criteria count**
+- **Dependencies** on external services, APIs, or decisions
+
+### 1.5. Quality Quick-Check
+
+Before proceeding to scope assessment, run a quick quality audit against the PRD Quality Scorecard in `governance/product-excellence-standards.md`. Score each dimension (Requirements, UX, Accessibility, Performance, Security, Responsive, Competitive) as Bronze / Silver / Gold.
+
+If any dimension scores **Bronze**, recommend:
+> 💡 **Quality recommendation:** This PRD scores Bronze on [dimensions]. Consider running `spell-enchant` to enhance the PRD before continuing with assessment and architecture. `spell-enchant` will conduct competitive research (research role) and marketing review (marketing role), and proactively add missing quality requirements.
+
+This is a recommendation, not a gate — the user decides whether to enchant first or proceed directly. Include the scorecard results in the execution plan output regardless.
+
+### 2. Scope Assessment
+
+Evaluate the PRD against Spell Loop sizing rules:
+- Each Spell Loop cycle = **1-2 weeks of agent work** = **4-8 right-sized stories**
+- A right-sized story: one file change, one endpoint, one component, one migration
+- Flag anything that violates story sizing: "Build the entire dashboard", "Add authentication", "Refactor the API layer"
+
+Classify the PRD:
+
+| Classification | Criteria | Action |
+|---------------|----------|--------|
+| **Single cycle** | ≤ 8 stories, no cross-cutting concerns | Proceed directly to `spell-architect` |
+| **Multi-cycle** | 9-30 stories, clear epic boundaries | Split into epics, each gets its own Spell Loop run |
+| **Program-scale** | 30+ stories, multiple subsystems, cross-team concerns | Split into phases with milestone gates between them |
+
+### 3. Epic Splitting (if multi-cycle or program-scale)
+
+Break the PRD into epics. Each epic must be:
+- **Self-contained** — shippable independently (no half-built features)
+- **Sprint-sized** — 4-8 stories per epic
+- **Dependency-ordered** — infrastructure before API before UI before polish
+
+For each epic, define:
+```markdown
+### Epic N: [Name]
+**Stories (estimated):** [count]
+**Dependencies:** [prior epics or external]
+**Tech stack:** [frameworks, platforms]
+**Primary role:** [backend / frontend / mobile / full-stack — resolve to a persona via `agent-policies` / `naming-conventions`]
+**Risk level:** Low / Medium / High
+**Sprint estimate:** [1 or 2 cycles]
+```
+
+### 3.5. External Tracker Mapping (external mode)
+
+Only applies when `tracking_mode=external`. Skip entirely for internal mode.
+
+Do **not** inline the work-item-type fallback order or the parent/child linkage rules here — they are the single source of truth in [governance/development-methodology.md](../../governance/development-methodology.md) → **Process-Template-Aware ADO Hierarchy Rules**. Detect the provider from `external_provider`, then apply those rules. *Fallback: if that doc is missing, record the tracker mapping as an Open Question and proceed without item-type assignment.*
+
+Scope-specific delta (the only thing this spell adds on top of those rules): each split **epic** maps to the **Epic-level** logical level — use the `Epic` work item type whenever the resolved provider/template offers it, and record the selected type per epic in `execution-plan.md`. All lower-level and linkage decisions defer to the governance rules above.
+
+### 4. Architecture Decision Check
+
+Scan the PRD for decisions that need ADRs:
+- New frameworks or libraries not already in the stack
+- New external service integrations (APIs, databases, auth providers)
+- Data model changes that affect multiple subsystems
+- Deployment topology changes
+- New communication patterns (sync vs async, REST vs gRPC vs events)
+
+For each candidate:
+```markdown
+#### ADR Candidate: [Title]
+**Trigger:** [What in the PRD requires this decision]
+**Options:** [2-3 alternatives]
+**Recommendation:** [If obvious, state it; otherwise flag for the architecture role]
+**Blocking:** [Which epics are blocked until this is decided]
+```
+
+### 5. Security Review
+
+Check the PRD against the threat model:
+- Does this feature introduce new attack surface? (new endpoints, new auth flows, new data stores)
+- Does it handle PII, payment data, or secrets?
+- Does it change trust boundaries? (new external integrations, new user roles)
+- Are there OWASP Top 10 concerns? (injection points, auth gaps, data exposure)
+
+For each concern:
+```markdown
+#### Security Flag: [Title]
+**Threat:** [What could go wrong]
+**Mitigation required:** [What the implementation must include]
+**Blocking:** [yes/no — can the epic proceed without resolving this?]
+```
+
+### 6. Agent Assignment
+
+Map each epic to the right **role**, then resolve each role to a concrete agent persona via `agents/agent-policies.md` / `naming-conventions.md` (fallback: keep the generic role label if the roster files are absent):
+
+| Role | When |
+|------|------|
+| Architecture | ADR candidates, cross-epic design decisions |
+| Backend / Full-stack | APIs, databases, server-side logic |
+| Frontend / UI | Web UI, component frameworks |
+| Mobile | Native/cross-platform mobile apps |
+| QA | Test strategy, coverage validation |
+| DevOps | Pipeline creation, deployment config |
+| Research | Unknowns, technology evaluation, competitive analysis |
+| Marketing | User-facing copy, landing pages, SEO |
+
+Flag any epics that need **multiple roles** (e.g., a full-stack feature = backend + frontend + QA).
+
+### 7. Dependency Graph
+
+Produce a Mermaid diagram showing epic execution order:
+
+```mermaid
+flowchart LR
+    E1[Epic 1: Infrastructure] --> E2[Epic 2: API Layer]
+    E2 --> E3[Epic 3: Web UI]
+    E2 --> E4[Epic 4: Mobile App]
+    E3 --> E5[Epic 5: Integration Tests]
+    E4 --> E5
+```
+
+Identify:
+- **Critical path** — the longest dependency chain
+- **Parallelizable epics** — epics that can run simultaneously on different branches
+- **Milestone gates** — points where human review is needed before continuing
+
+### 8. Execution Plan Output
+
+Produce `execution-plan.md` with this structure:
+
+```markdown
+# Execution Plan: [Feature Name]
+
+## PRD Summary
+- **Source:** [PRD file or inline]
+- **Business:** [which business]
+- **Target repo:** [org/repo]
+- **Classification:** Single cycle / Multi-cycle / Program-scale
+- **Total epics:** [N]
+- **Total estimated stories:** [N]
+- **ADR candidates:** [N]
+- **Security flags:** [N]
+
+## Dependency Graph
+[Mermaid diagram]
+
+## Epics
+
+### Epic 1: [Name]
+- **Stories:** [estimated count]
+- **Agent:** [primary]
+- **Dependencies:** none
+- **Tracking item:** [internal-only OR external provider + type/id]
+- **Risk:** Low/Medium/High
+- **Notes:** [any special considerations]
+
+### Epic 2: [Name]
+...
+
+## Architecture Decisions Required
+[List of ADR candidates with recommendations]
+
+## Security Flags
+[List of security concerns with mitigations]
+
+## Recommended Execution Order
+1. Resolve ADR candidates (architecture role)
+2. Epic 1 — spell-full-cycle or spell-architect → spell-implement → spell-ship
+3. Run spell-commit-work to checkpoint major outputs before starting Epic 2
+4. Epic 2 — ...
+5. [milestone gate if needed]
+6. Epic N — ...
+
+## Open Questions
+[Anything that needs human decision before execution can start]
+```
+
+If `external_provider=jira` or `external_provider=other`, add explicit TODOs in Open Questions for provider-specific type mapping and linkage automation.
+
+### 9. Present and Confirm
+
+Present the execution plan to the user. Ask:
+1. Does the epic split make sense?
+2. Are the ADR candidates correct? Should any be decided now?
+3. Are there epics that should be deprioritized or cut?
+4. Ready to start with Epic 1?
+
+---
+
+## Rules
+
+- **Never start implementation from this spell.** This spell produces a plan, not code. The output feeds into `spell-architect` or `spell-full-cycle`.
+- **Be honest about unknowns.** If the PRD references technology or services you don't have context on, flag it as a research item for the research role.
+- **Respect existing ADRs.** If the PRD proposes something that contradicts an existing ADR, flag the conflict — don't silently override.
+- **Conservative estimates.** When in doubt, split smaller. Two small epics are better than one that's too big.
+- **Security is non-negotiable.** If a security flag is blocking, it blocks. No "we'll add auth later."

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

@@ -0,0 +1,129 @@
+---
+name: Spell — Security Review
+description: OWASP Top 10 and AI/agent (LLM) security audit plus dependency vulnerability check for any project
+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)
+
+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]
+
+   ### 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/.github/prompts/spell-ship.prompt.md

@@ -0,0 +1,104 @@
+---
+name: Spell — Ship
+description: Pre-deploy checklist, merge approval workflow, and deployment gate verification
+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](../../governance/development-methodology.md) — Spell Loop phases
+- [governance/cicd-standards.md](../../governance/cicd-standards.md) — CI/CD pipeline requirements and deployment gates
+- [governance/testing-standards.md](../../governance/testing-standards.md) — Coverage thresholds
+- [governance/git-conventions.md](../../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. Do not attempt to auto-resolve.
+   - 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](../../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:
+   - 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>`).
+   - 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/.github/prompts/spell-status.prompt.md

@@ -0,0 +1,85 @@
+---
+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.
+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.