arcane-cli 0.14.0

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

@@ -0,0 +1,101 @@
+---
+title: Portable Bootstrap — Quick Context for Ad-Hoc AI Clients
+audience: ai
+status: active
+tags: [ai-context, bootstrap, multi-client, portable]
+---
+
+# Portable Bootstrap
+
+Paste this entire file into any AI client (Claude web, ChatGPT, etc.) to give it working context for this project. For full detail, read the linked files in the repo.
+
+---
+
+## Project
+
+**Arcane** — Operational documentation for running AI-automated businesses under {LLC_NAME} (owner: {OPERATOR_NAME}). Uses an agent runtime to automate operations across one or more ventures.
+
+**This is a documentation-only repository.** No build commands, test suites, or deployable code. Do not add automation without being asked.
+
+## Environment
+
+- **Primary machine:** the host where the agent runtime executes.
+- **Disk encryption:** full-disk encryption active on machines holding credentials or working copies.
+- **Agent runtime:** one or more agents configured. Runtime gateway bound to loopback, token auth via SecretRef, exposed remotely only through an authenticated tunnel if needed.
+- **User:** a dedicated non-root user.
+
+## Non-Negotiable Rules
+
+1. **Never access an encrypted or cross-OS volume you are not authorized to touch.** This rule stands as defense-in-depth regardless of encryption status.
+2. **No root commands** unless explicitly scoped and justified.
+3. **No secrets on the command line.** Use env vars and `read -s`.
+4. **Update `last_updated` frontmatter** when editing any document.
+5. **Log significant decisions** in DECISIONS.md as ADRs.
+6. **Production system** — no shortcuts, no "fix it later."
+7. **Conventional Commits** format: `type(scope): description`.
+8. **Never auto-commit** during interactive sessions — present for approval first.
+9. **Recommendation guardrails:** Flag actionable recommendations. Verify information. Present free alternatives. Confirm >$50 items.
+
+## Key Files
+
+| Need               | File                                  |
+| ------------------ | ------------------------------------- |
+| Full rules         | `governance/universal-agent-rules.md` |
+| Project overview   | `project.md`                          |
+| Decisions log      | `DECISIONS.md`                        |
+| Agent policies     | `agents/agent-policies.md`            |
+| Git conventions    | `governance/git-conventions.md`       |
+| AI context summary | `ai-context/system-prompt-context.md` |
+
+## 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.
+
+## Naming Tiers
+
+| Tier      | Style           | Examples                                  |
+| --------- | --------------- | ----------------------------------------- |
+| Machines  | Iconic names    | Atlas, Voyager                       |
+| AI Agents | Persona + role  | Merlin — CTO, {AGENT_NAME} — Product Ops |
+| Systems   | Functional slug | `inventory-api`, `orders-worker`          |
+
+## Version Control Host
+
+Use your chosen host's project organization ({ADO_ORG}). Apply a consistent project/repo naming convention. One project per business + one shared docs/ops project.
+
+## Spell Commands (Development Methodology)
+
+Development follows the **Spell Loop** — structured planning phases feeding an autonomous implementation loop, delivered through the spell system. All workflows go through this flow.
+
+**Available spells** (invoke by typing the command name in your message):
+
+### Core Loop: Plan → Architect → Implement → Test → Review → Ship
+
+- `spell-plan` — Plan a feature (output: PRD.md)
+- `spell-architect` — Design the solution (output: architecture.md + stories.json)
+- `spell-implement` — Write code per story
+- `spell-test` — Run QA and verify
+- `spell-review` — Adversarial code review
+- `spell-ship` — Merge and deploy
+
+### Session Management
+
+- `spell-open-session` — Rebuild context after reset; read core docs, identify unfinished work, prioritize
+- `spell-close-session` — End-of-session cleanup: stage changes, curate screenshots, propose commits, journal
+
+### Operational
+
+- `spell-commit-work` — Standard Git workflow: stage → message → approve → execute
+- `spell-todo` — Review TODO.md, prioritize, move resolved items to canonical docs
+- `spell-check-drift` — Find stale assumptions in docs vs. reality
+- `spell-bootstrap-business` — Initialize a new business: folder, template docs, project setup
+
+### Specialized
+
+- `spell-security-review` — Audit for security gaps, credential exposure, threat coverage
+- `spell-product-review` — Evaluate business readiness: market fit, automation scope, blockers
+- `spell-dotnet-expert` — .NET/Blazor deep-dive
+- `spell-explain-concept` — Break down complex architecture concepts
+- `spell-generate-bot-icons` — Create agent personas and icons
+
+Full reference: See `governance/development-methodology.md` in the repo.

package/dist/assets/.arcane/governance/product-excellence-standards.md

@@ -0,0 +1,211 @@
+---
+title: Product Excellence Standards
+audience: both
+last_updated: YYYY-MM-DD
+status: active
+tags:
+  [quality, ux, accessibility, performance, security, spell-enchant, ADR-052]
+---
+
+# Product Excellence Standards
+
+## Purpose
+
+Define what "the best version of an app" means across every dimension — UX, accessibility, performance, security, and polish. This document provides the **PRD Quality Scorecard** that [[.github/prompts/spell-enchant.prompt|spell-enchant]] evaluates against when enchanting a PRD from functional to exceptional.
+
+## Quality Dimensions
+
+### 1. Requirements Completeness
+
+| Criterion                        | Description                                                                                                        |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **Testable acceptance criteria** | Every requirement has ≥1 acceptance criterion that can be verified by an automated test or a concrete manual check |
+| **Priority classification**      | All requirements classified as Must Have / Should Have / Won't Have                                                |
+| **Scope boundary**               | "Won't Have" section explicitly excludes items to prevent scope creep                                              |
+| **Dependency identification**    | External services, APIs, and decisions the feature depends on are listed                                           |
+| **Open questions documented**    | Unresolved items are captured — not ignored or assumed                                                             |
+
+### 2. User Experience (UX)
+
+| Criterion              | Description                                                                                         |
+| ---------------------- | --------------------------------------------------------------------------------------------------- |
+| **Full user journey**  | Every user-facing feature defines: happy path, error states, edge cases, empty states               |
+| **Loading states**     | Users see meaningful feedback during async operations (skeleton screens, spinners, progress bars)   |
+| **Error recovery**     | Errors include actionable messages — users know what went wrong and what to do next                 |
+| **Empty states**       | First-use and zero-data states guide users toward the next action rather than showing blank screens |
+| **Success feedback**   | Completions are acknowledged (toast, animation, redirect) — users know their action worked          |
+| **Onboarding flow**    | New users have a clear path from zero to first value delivered                                      |
+| **Consistency**        | UI patterns, terminology, and behavior are consistent across features                               |
+| **Micro-interactions** | Transitions, hover effects, and subtle animations provide polish without slowing users down         |
+
+### 3. Accessibility (WCAG 2.1 AA Baseline)
+
+| Criterion                 | Description                                                                        |
+| ------------------------- | ---------------------------------------------------------------------------------- |
+| **Keyboard navigation**   | All interactive elements reachable and operable via keyboard alone                 |
+| **Screen reader support** | Semantic HTML, ARIA labels, live regions for dynamic content                       |
+| **Color contrast**        | Text meets 4.5:1 ratio (normal text) or 3:1 (large text) against background        |
+| **Focus indicators**      | Visible focus ring on all interactive elements                                     |
+| **Alternative text**      | All images, icons, and media have descriptive alt text or are marked decorative    |
+| **Form labels**           | All form inputs have associated labels; error messages are programmatically linked |
+| **Motion sensitivity**    | Animations respect `prefers-reduced-motion`; no content-critical motion            |
+| **Text resizing**         | UI remains usable at 200% zoom                                                     |
+
+### 4. Performance
+
+| Criterion                                         | Description                                                                |
+| ------------------------------------------------- | -------------------------------------------------------------------------- |
+| **Largest Contentful Paint**                      | Web: < 2.5s; Mobile: < 3.5s                                                |
+| **First Input Delay / Interaction to Next Paint** | Web: < 100ms; Mobile: < 200ms                                              |
+| **Cumulative Layout Shift**                       | < 0.1 (no unexpected visual shifts during load)                            |
+| **API response time**                             | p95 < 500ms for user-facing endpoints; p95 < 2s for batch/report endpoints |
+| **Bundle size**                                   | Web: initial JS bundle < 200KB gzipped; lazy-load non-critical modules     |
+| **Offline / degraded**                            | Define behavior when network is slow or unavailable (if applicable)        |
+| **Concurrent users**                              | Target number documented; load testing plan defined for > 100 concurrent   |
+
+### 5. Security (Beyond OWASP Baseline)
+
+| Criterion                  | Description                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------- |
+| **Data classification**    | Each data field classified: Public / Internal / Confidential / Restricted       |
+| **Auth flows specified**   | Authentication and authorization model defined — no "we'll add auth later"      |
+| **Input validation depth** | Server-side validation for all user inputs; client-side validation for UX only  |
+| **Audit trail**            | State-changing actions produce audit log entries (who, what, when)              |
+| **Rate limiting**          | API endpoints have rate limits to prevent abuse                                 |
+| **Session management**     | Session timeout, renewal, and revocation policies defined                       |
+| **Secret handling**        | No hardcoded secrets; all credentials via environment variables or secret store |
+| **Dependency scanning**    | Third-party packages audited for known vulnerabilities                          |
+
+### 6. Responsive Design
+
+| Criterion                 | Description                                                           |
+| ------------------------- | --------------------------------------------------------------------- |
+| **Breakpoints defined**   | Mobile (< 768px), Tablet (768–1024px), Desktop (> 1024px)             |
+| **Touch targets**         | Interactive elements ≥ 44×44px on mobile                              |
+| **Layout adaptation**     | Content reflows appropriately — no horizontal scrolling on mobile     |
+| **Navigation adaptation** | Desktop nav collapses to mobile pattern (hamburger, bottom nav, etc.) |
+
+### 7. Competitive Differentiation
+
+| Criterion                 | Description                                                                |
+| ------------------------- | -------------------------------------------------------------------------- |
+| **Alternative analysis**  | Top 3 alternatives identified; what they do well and where they fall short |
+| **Unique value**          | At least one feature or quality that sets this app apart from alternatives |
+| **Table-stakes coverage** | Features that users expect as standard for this category are all present   |
+| **Experience premium**    | At least one UX element that makes users think "this is well-made"         |
+
+---
+
+## Quality Profiles
+
+Not every product needs Gold in every dimension. Quality profiles set the **target** per dimension based on the product type. The target determines what counts as Must-Add (current → target gap), Should-Add (one tier above target), and Could-Add (aspirational). Gold remains the ceiling shown in the scorecard for all profiles — profiles control what you're _aiming_ for.
+
+### Profile Definitions
+
+| Profile             | When to Use                                                           |
+| ------------------- | --------------------------------------------------------------------- |
+| **Internal Tool**   | Dashboards, CLIs, admin panels, single-user tools, dev utilities      |
+| **Public MVP**      | First public launch, market validation, early adopters, beta products |
+| **Production SaaS** | Revenue-generating, public-facing, scaled, established products       |
+| **Custom**          | User picks target tier per dimension manually                         |
+
+### Target Matrices
+
+#### Internal Tool
+
+| Dimension     | Target | Rationale                                                          |
+| ------------- | ------ | ------------------------------------------------------------------ |
+| Requirements  | Silver | Clear specs prevent rework even for internal tools                 |
+| UX            | Silver | Operator efficiency matters, but polish is secondary               |
+| Accessibility | Bronze | Single known user; invest only if the user has accessibility needs |
+| Performance   | Silver | Performance issues waste the operator's time                       |
+| Security      | Gold   | Internal tools often handle secrets, tokens, and admin access      |
+| Responsive    | Bronze | Desktop-only is usually correct for internal tools                 |
+| Competitive   | Bronze | No market competition — it's built for you                         |
+
+#### Public MVP
+
+| Dimension     | Target | Rationale                                                            |
+| ------------- | ------ | -------------------------------------------------------------------- |
+| Requirements  | Silver | Must be clear enough for a small team to ship confidently            |
+| UX            | Gold   | First impressions determine adoption; UX is the product at MVP stage |
+| Accessibility | Silver | Legal compliance + wider user reach from day one                     |
+| Performance   | Silver | Must feel fast; fine-tune later with real usage data                 |
+| Security      | Gold   | No second chances on security with real user data                    |
+| Responsive    | Silver | Users expect mobile access; at least don't break                     |
+| Competitive   | Silver | Must articulate why users should choose this over alternatives       |
+
+#### Production SaaS
+
+| Dimension     | Target | Rationale                                                |
+| ------------- | ------ | -------------------------------------------------------- |
+| Requirements  | Gold   | Revenue depends on reliability; every edge case matters  |
+| UX            | Gold   | Users paying money expect best-in-class experience       |
+| Accessibility | Gold   | Legal requirement (ADA/EAA); brand reputation; wider TAM |
+| Performance   | Gold   | Performance is a feature; slowness causes churn          |
+| Security      | Gold   | Breach = business-ending event at scale                  |
+| Responsive    | Gold   | Multi-device is table-stakes for SaaS                    |
+| Competitive   | Gold   | Must defend market position with clear differentiation   |
+
+### Default Profile
+
+If the user does not specify a profile, **Public MVP** is the default. Rationale: it provides the strongest quality-to-scope ratio — Gold where it matters most (UX, Security) without over-engineering internal or infrastructure dimensions.
+
+### How Profiles Drive Enhancement Tiers
+
+| Enhancement Tier | Rule                                                                       |
+| ---------------- | -------------------------------------------------------------------------- |
+| **Must-Add**     | Current score is below the profile's target for that dimension             |
+| **Should-Add**   | Current score matches the target; enhancement would lift to one tier above |
+| **Could-Add**    | Current score already meets or exceeds target; enhancement is aspirational |
+| **Won't-Add**    | Explicitly excluded regardless of profile                                  |
+
+**Override:** Security and Accessibility gaps are always at least Should-Add regardless of profile. A Bronze Security score is always Must-Add.
+
+---
+
+## PRD Quality Scorecard
+
+Score each dimension on a three-tier rubric:
+
+| Level      | Name        | Meaning                                                                                   |
+| ---------- | ----------- | ----------------------------------------------------------------------------------------- |
+| **Bronze** | Functional  | Meets minimum requirements — works but lacks polish, accessibility, and proactive quality |
+| **Silver** | Polished    | Good coverage across all dimensions — professional, accessible, performant                |
+| **Gold**   | Exceptional | Best-in-class for this app category — delightful UX, proactive security, competitive edge |
+
+### Scoring Criteria Per Dimension
+
+| Dimension         | Bronze                      | Silver                                          | Gold                                                                            |
+| ----------------- | --------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- |
+| **Requirements**  | Has acceptance criteria     | Priority classified, scope bounded, deps listed | Open questions documented, traceability matrix ready                            |
+| **UX**            | Happy path defined          | Error + empty states covered, loading feedback  | Full journey with micro-interactions, onboarding, consistency review            |
+| **Accessibility** | Basic semantic HTML         | WCAG 2.1 AA compliance stated                   | Keyboard nav, screen reader, color contrast, motion sensitivity all specified   |
+| **Performance**   | No targets stated           | Core Web Vitals targets defined                 | Load budgets, lazy loading strategy, offline behavior specified                 |
+| **Security**      | OWASP baseline              | Data classification + auth flows specified      | Audit trail, rate limiting, session management, dependency scanning all defined |
+| **Responsive**    | "Mobile friendly" mentioned | Breakpoints and layout adaptation defined       | Touch targets, nav adaptation, and responsive images specified                  |
+| **Competitive**   | No analysis                 | Top 3 alternatives listed                       | Unique value articulated, table-stakes confirmed, experience premium identified |
+
+### Overall Score
+
+- **Bronze overall**: Any dimension scores Bronze
+- **Silver overall**: All dimensions score Silver or above
+- **Gold overall**: All dimensions score Gold
+
+---
+
+## How This Is Used
+
+1. **`spell-enchant`** asks the user to select a quality profile, scores the incoming PRD against this scorecard, and produces enhancement suggestions to reach the profile's targets per dimension.
+2. **`spell-scope`** performs a quick scorecard check during PRD intake and recommends `spell-enchant` if any dimension scores below the profile's target.
+3. **`spell-plan`** outputs a PRD that starts at Bronze or Silver — `spell-enchant` is the path to the profile's targets.
+4. **`spell-review`** can reference these standards when evaluating whether shipped code meets the quality bar.
+5. **Quality Profiles** control what "good enough" means — Internal Tool, Public MVP (default), Production SaaS, or Custom.
+
+## Related
+
+- [[DECISIONS#ADR-052|ADR-052 — Product Excellence Standards and spell-enchant]]
+- [[governance/testing-standards|Testing Standards]] — Coverage thresholds and framework selection
+- [[governance/cicd-standards|CI/CD Standards]] — Pipeline quality gates
+- [[security/threat-model|Threat Model]] — Active security concerns
+- [[governance/development-methodology|Development Methodology]] — Spell Loop flow

package/dist/assets/.arcane/governance/rca-process-standard.md

@@ -0,0 +1,157 @@
+---
+title: Root Cause Analysis (RCA) Process Standard
+audience: both
+last_updated: YYYY-MM-DD
+status: active
+distributable: true
+tags: [governance, rca, process, incident, corrective-actions]
+---
+
+# Root Cause Analysis (RCA) Process Standard
+
+When a significant decision is reversed, a naming collision is discovered, or a multi-file correction is needed, something went wrong upstream. This document defines the process for tracing root causes and preventing recurrence.
+
+## Related ADRs
+
+- [[DECISIONS#ADR-068|ADR-068: Establish RCA Process Standard]]
+
+## When to Trigger an RCA
+
+An RCA is **required** when any of these occur:
+
+| Trigger | Example |
+|---------|---------|
+| **Decision reversed or superseded within 30 days** | ADR accepted, then rolled back because the premise was wrong |
+| **Naming collision discovered** | Two entities share a name, causing ambiguity in docs or code |
+| **Multi-file correction needed** | A change required updating >5 files to fix a single conceptual error |
+| **Implicit decision detected** | A drift check or session applied a change that had no governing ADR |
+| **Integration failure from doc mismatch** | A playbook or script failed because docs disagreed with reality |
+
+An RCA is **recommended** (but optional) for:
+- Repeated confusion in sessions about the same topic
+- A TODO item that was deferred and caused downstream problems
+- Any incident where the operator says "how did we end up here?"
+
+## RCA Template
+
+Every RCA follows this structure. Artifacts are stored in `governance/rcas/` with the filename `RCA-NNN-short-slug.md` (sequential numbering, matching the related ADR when applicable).
+
+```markdown
+---
+title: "RCA-NNN: Short Description"
+audience: both
+last_updated: YYYY-MM-DD
+status: active
+tags: [rca, relevant-tags]
+---
+
+# RCA-NNN: Short Description
+
+## Incident Summary
+
+One paragraph: what went wrong, when it was discovered, and what the impact was.
+
+## Timeline
+
+Chronological sequence of decisions and events that led to the incident.
+Include ADR numbers, journal dates, and session references.
+
+| Date | Event | Reference |
+|------|-------|-----------|
+| YYYY-MM-DD | Description | [[DECISIONS#ADR-NNN\|ADR-NNN]] |
+
+## Five Whys
+
+1. **Why [symptom]?** — Because [proximate cause].
+2. **Why [proximate cause]?** — Because [deeper cause].
+3. **Why [deeper cause]?** — Because [process gap].
+4. **Why [process gap]?** — Because [missing safeguard].
+5. **Why [missing safeguard]?** — Because [root cause].
+
+## Root Causes
+
+| # | Root Cause | Type |
+|---|-----------|------|
+| RC-1 | Description | Decision gap / Process gap / Review gap / Communication gap |
+
+## Corrective Actions
+
+Actions taken to fix the immediate problem.
+
+| # | Action | Status | Reference |
+|---|--------|--------|-----------|
+| CA-1 | Description | Done / Planned | Link to commit or doc |
+
+## Preventive Actions
+
+Process changes to prevent recurrence. These should modify governance docs, templates, or prompts.
+
+| # | Action | Target Doc | Status |
+|---|--------|-----------|--------|
+| PA-1 | Description | [[path/to/doc]] | Done / Planned |
+
+## Lessons Learned
+
+Bullet points — what the team now knows that it didn't before.
+```
+
+## Process Steps
+
+### 1. Initiate
+
+When a trigger condition is met:
+- Create the RCA artifact file in `governance/rcas/`
+- Fill in the Incident Summary and Timeline sections
+- Record the ADR that establishes the RCA (if applicable)
+
+### 2. Analyze
+
+- Walk the Five Whys from symptom to root cause
+- Categorize each root cause by type:
+  - **Decision gap** — a decision was needed but not made, or was made with incomplete scope
+  - **Process gap** — the process allowed an action that should have been guarded
+  - **Review gap** — a review step existed but missed the issue
+  - **Communication gap** — information existed but wasn't discoverable or linked
+
+### 3. Define Actions
+
+- **Corrective actions** fix the immediate problem (e.g., rename the files, revert the change)
+- **Preventive actions** change the process so the problem can't recur (e.g., add a checklist item, amend a template, update a prompt)
+- Every preventive action must reference the specific governance doc, template, or prompt it modifies
+
+### 4. Implement and Verify
+
+- Implement preventive actions in the same branch as the RCA artifact (when possible)
+- Verify: can the original root cause still produce the same problem? If yes, the preventive action is insufficient.
+
+### 5. Close
+
+- Set RCA status to `active` (RCAs remain active as reference — they are not "resolved" and deleted)
+- Link the RCA from the related ADR using a "Deep dive" wiki-link
+- Record a note in the session journal
+
+## Severity Levels
+
+RCAs do not have formal severity levels. The trigger conditions above determine whether an RCA is required or recommended. All RCAs follow the same template regardless of impact.
+
+## Ownership
+
+- In interactive sessions: the human operator and AI agent collaborate on the RCA
+- For autonomous agent work: the agent flags the trigger condition and drafts the RCA for human review
+- RCAs are never auto-committed — they require human approval (same rule as all interactive commits per [[governance/git-conventions|Git Conventions]])
+
+## Artifact Location
+
+```
+governance/
+  rcas/
+    RCA-001-naming-collision.md
+    RCA-002-...
+```
+
+**Why `governance/rcas/`?** RCAs are governance artifacts (process improvement), not journals (session logs) or decisions (ADRs). They complement ADRs by explaining *how a decision failed* rather than *what was decided*.
+
+## Maintenance
+
+- Review RCA preventive actions quarterly during `spell-check-drift` runs
+- If a preventive action proves ineffective (same class of problem recurs), update the RCA with a "Recurrence" section and strengthen the preventive action

package/dist/assets/.arcane/governance/spell-authoring-standards.md

@@ -0,0 +1,129 @@
+---
+title: Spell Authoring Standards
+audience: contributor
+last_updated: YYYY-MM-DD
+status: active
+tags: [spell, authoring, quality, governance, ARC-014]
+---
+
+# Spell Authoring Standards
+
+## Purpose
+
+Define what a **high-quality Arcane spell** looks like, so spell prompts can be authored and audited
+against a consistent bar. This is the spell-prompt analogue of [[product-excellence-standards]] (which
+grades PRDs, not prompts). It is an **authoring-time standard** — a checklist for contributors writing
+or reviewing spells. It is **not** meant to be read at runtime by the spells it grades.
+
+See [ARC-014](../../../DECISIONS.md#arc-014) for the decision that established this standard.
+
+## The Spell Quality Rubric
+
+Eight dimensions. Each is scored **Bronze (1) / Silver (2) / Gold (3)**. A spell's **overall score is
+its weakest dimension** (same weakest-link rule as the PRD scorecard) — a Gold workflow with a Bronze
+safety rail is a Bronze spell.
+
+Two dimensions are **hard gates**: **D2 Distributability** and **D7 Safety** must be **≥ Silver** for a
+spell to ship, regardless of overall target.
+
+### D1 — Front-matter & invocation contract
+
+| Tier | Bar |
+| --- | --- |
+| Bronze | Front-matter complete: `name`, `description`, `argument-hint`, `agent`. |
+| Silver | + an accurate **Executive Summary** stating purpose, when to use it, and what it produces. |
+| Gold | + explicitly disambiguates itself from sibling spells a user might confuse it with. |
+
+### D2 — Distributability / no org-coupling **(HARD GATE ≥ Silver)**
+
+| Tier | Bar |
+| --- | --- |
+| Bronze | No real organization, person, venture, or machine names. Org-specific values use `{UPPER_SNAKE}` placeholders. |
+| Silver | + every placeholder has an inline resolution note: *"resolve from `.arcane.json` / frontmatter; ask if unset."* |
+| Gold | + no hard assumption of a specific tracker, agent roster, or directory layout — the spell works in a vanilla consuming repo with no Arcane context files present. |
+
+> A **Bronze on D2 is OSS-blocking** and must be fixed before release. See **Distributability conventions** below.
+
+### D3 — Context-file robustness
+
+| Tier | Bar |
+| --- | --- |
+| Bronze | Context files the spell reads are listed. |
+| Silver | + each optional file has a fallback: *"if missing, proceed with X."* |
+| Gold | + the spell degrades gracefully end-to-end when **no** context files exist. |
+
+### D4 — Workflow completeness
+
+| Tier | Bar |
+| --- | --- |
+| Bronze | The happy path is fully specified with clear, ordered steps. |
+| Silver | + edge and failure cases handled: missing/invalid input, a required tool unavailable, an empty result. |
+| Gold | + re-run safety (idempotency) and recovery from partial failure. |
+
+### D5 — Output & acceptance spec
+
+| Tier | Bar |
+| --- | --- |
+| Bronze | The output is named. |
+| Silver | + the output's structure or a template is given. |
+| Gold | + a user-verifiable **acceptance checklist** — how to know the spell did its job. |
+
+### D6 — Cross-references
+
+| Tier | Bar |
+| --- | --- |
+| Bronze | Related spells are mentioned. |
+| Silver | + correct hand-off direction (consumes-from X, feeds-into Y). |
+| Gold | + bidirectional and consistent with the flow in [[development-methodology]]. |
+
+### D7 — Input validation & safety rails **(HARD GATE ≥ Silver)**
+
+| Tier | Bar |
+| --- | --- |
+| Bronze | A `Rules` section exists. |
+| Silver | + required arguments are validated or requested; the spell refuses to proceed on clearly invalid input. |
+| Gold | + every destructive or outward-facing action (delete, force-push, publish, external post) is explicitly gated behind confirmation. |
+
+### D8 — Conciseness & non-duplication
+
+| Tier | Bar |
+| --- | --- |
+| Bronze | No dead or contradictory text. |
+| Silver | + shared logic is **referenced**, not copy-pasted (e.g. point to a governance doc rather than inlining it). |
+| Gold | + tight and single-responsibility — the spell does one job well. |
+
+## Scoring & target
+
+- **Overall = lowest dimension score.**
+- **Hard gates:** D2 and D7 must each be **≥ Silver**.
+- **Authoring target:** every shipped spell reaches **Silver overall, Gold on D2.** Gold-everywhere is
+  aspirational, not required — chasing it on a mature spell usually adds bloat, not value. A short spell
+  that meets every gate at Silver is **done**; do not pad it.
+
+## Distributability conventions (D2)
+
+Arcane spells ship to other repositories and, eventually, open source. Keep them portable:
+
+- **Never hard-code** an org name, person, venture, product, or machine name. Use a documented
+  `{UPPER_SNAKE}` placeholder: `{ADO_ORG}`, `{ADO_PROJECT}`, `{BUSINESS_NAME}`, `{OPERATOR_NAME}`.
+- **Resolution rule:** a placeholder resolves from `.arcane.json` or the feature/PRD frontmatter; if it
+  is unset, the spell **asks** rather than assuming a default.
+- **Roster by reference, not by name:** when a spell needs the concept of an agent role, reference
+  [[agent-policies]] / [[naming-conventions]] as context (with a fallback) instead of naming personas
+  inline.
+- **Trackers are optional:** never assume Azure DevOps (or any single provider). Respect
+  `tracking_mode` (internal/external) and detect the provider; the shared rules live in
+  [[development-methodology]] — point to them rather than re-inlining ADO logic.
+
+> **Maintainer-internal exemption.** A few spells operate *on the Arcane framework itself*
+> (e.g. `spell-bump`, `spell-arcane-version`) and legitimately reference repo internals like
+> `registry.ts`, `src/assets/`, or the `arcane-cli` package name. Such
+> **framework-self-referential** references do **not** count as a D2 violation. The exemption covers
+> only the framework's own internals — never a consuming org's venture, person, machine, or tracker names.
+
+## How to audit a spell
+
+For each dimension, score Bronze/Silver/Gold with one line of evidence. Record the overall (weakest)
+score and flag any D2/D7 below Silver as **must-fix**. When elevating, prefer **additive** changes
+(add a fallback, an edge case, an acceptance line, a cross-reference); preserve the spell's intent and
+working prose, and treat any change to *behavior* (not just coverage) as requiring explicit sign-off.