arcane-cli 0.39.0 → 1.0.0

package/dist/assets/.arcane/spells/spell-commit-work.md

@@ -0,0 +1,279 @@
+---
+name: Spell — Commit Work
+description: Generate Conventional Commits message with agent attribution and commit current work during an active session
+claude_description: Use PROACTIVELY whenever committing work during a session, even if the user just says 'commit this'.
+argument-hint: Optional focus (e.g., security, prompts, agents, infrastructure)
+agent: agent
+last_updated: 2026-07-05
+---
+
+## Executive Summary
+
+- This prompt commits work-in-progress during an active session before moving to the next task.
+- It generates Conventional Commits format messages with proper type, scope, and agent attribution trailers.
+- Use this when you've completed a discrete chunk of work and want to checkpoint before continuing.
+- Enables clean commits without waiting for session-close (which handles journal/session docs separately).
+
+---
+
+Commit the current work in progress using Conventional Commits format.
+
+Use these files first:
+
+- [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) — Conventional Commits reference and agent attribution model
+- [DECISIONS.md](../../DECISIONS.md) — for ADR context if relevant
+
+Workflow:
+
+1. **Check git status and guard the branch** — run `git status` to see what changed, and confirm the current branch.
+   - Classify the Git/remote state before enforcing the protected-branch guard. A usable merge path requires a configured remote on a supported provider (`github.com`, `dev.azure.com`, or `visualstudio.com`) and authenticated provider tooling. A remote URL alone is insufficient.
+   - Apply exactly one path:
+     - **Supported, authenticated GitHub/ADO remote + `main` or `master` checked out:** **STOP — do not stage or commit directly.** Create and switch the current worktree to a compliant topic branch (for example, `sessions/YYYY-MM-DD-<slug>`), then continue.
+     - **Supported, authenticated GitHub/ADO remote + valid topic/PR branch checked out:** stay on that branch and continue.
+     - **No remote, unsupported remote, or provider authentication unavailable:** remain on the current trunk. Print `Local-only checkpoint: no usable remote merge path; commit remains on <trunk> and no remote push/PR will run.` Continue through the local commit gate, then skip Steps 9 and 10 entirely.
+   - If the current worktree, branch, provider, or authentication state cannot be determined, fail closed before staging and ask the operator. Never strand a local-only commit on a topic branch with no usable merge path.
+
+2. **Run tests and verify coverage** _(skip only if zero source files changed — e.g., pure docs/config commit)_:
+   - Detect the project stack from the root of the changed repo:
+     - `package.json` present → `npm run test:coverage` (or `npm test` if no `test:coverage` script exists)
+     - `*.csproj` / `*.sln` present → `dotnet test --collect:"Code Coverage"`
+     - `pubspec.yaml` present → `flutter test --coverage`
+   - **HALT if tests fail or coverage thresholds are not met.** Do not proceed to commit. Report the exact failure output and instruct the operator to fix it first (run the failing tests, add missing coverage, or document an intentional threshold exception with a code comment and a note in the commit body).
+   - If coverage passes, record the coverage summary for use in the commit body or PR description.
+   - **Never commit code that fails CI locally.** The pipeline is not the first gate — this step is.
+
+   - **Distributable-change halt** (LH-06a; only when this repo has its own `scripts/check-version-bump.ts` — Arcane's own repo, or one that adopted the same convention; skip gracefully otherwise, this is not a general-purpose check every consumer repo can run):
+     - Run `npm run check:version-bump -- --staged` before committing. This is the staged-diff mode, not the default CI mode — it can see today's not-yet-committed change, which the default `merge-base..HEAD` diff cannot.
+     - **HALT if it fails.** Distributable content (`src/assets/`, `registry.ts`, `profiles.ts`) changed without a version bump. Run `spell-bump` first, then return here.
+
+   - **Format before committing** _(stack-aware; runs alongside the test gate above)_:
+     - Detect the configured formatter from the project's own config — do not assume one. Look for the toolchain's standard markers, for example:
+       - JS/TS: `.prettierrc*` / `prettier` in `package.json` → `npx prettier --write .`
+       - .NET: `*.csproj` / `*.sln` (optionally an `.editorconfig`) → `dotnet format`
+       - Python: `pyproject.toml` / `setup.cfg` declaring Black or Ruff → `black .` or `ruff format .`
+       - Go: any `*.go` files → `gofmt -w .` (or `go fmt ./...`)
+     - Run the detected formatter, then `git add` the resulting changes so they are part of this commit.
+     - **If no formatter is configured, skip this step gracefully** — do not install one and do not block the commit.
+
+3. **Determine authorship and partition the batch** — who produced each changed file or inseparable change set? See [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) Agent Attribution Model section and ADR-028.
+   - **Invariant: one commit has exactly one author.** Changes spanning authors must be split into separate commits.
+   - Partition changed files by author first. Step 4 then groups by concern within each author partition; concern grouping must never recombine authors.
+   - **Human wrote it:** no `--author` override needed (uses global Git config)
+    - **Arcane vendored scaffold/update:** no `--author` override; the operator's Git identity records the repository action. Add `Vendor: arcane-cli` and, when derivable, `Vendor-Version: <version>` trailers.
+       - Derive the version at commit time by running `arcane --version` (or the resolved `spell --version` alias). The CLI reads its installed package's `package.json`; never type the version, copy it from memory, or infer it from the repository manifest.
+       - If the installed CLI version cannot be read programmatically, omit `Vendor-Version` and report that provenance is incomplete. Never guess.
+       - A batch mixing vendored files with human- or agent-authored changes spans provenance authors and must be split before concern grouping.
+   - **AI agent/tool produced it:** use `--author` with the agent's registered identity:
+     - Roster agent: `--author="{AGENT_NAME} <{AGENT_EMAIL}>"` — resolve `{AGENT_NAME}` / `{AGENT_EMAIL}` from the active agent config (see [[agent-policies]] / [[naming-conventions]]); ask if unset.
+     - Generic CLI/IDE tool: `--author="{TOOL_NAME} <{TOOL_NAME_LOWER}@{OPERATOR_DOMAIN}>"` — resolve `{TOOL_NAME}` from the channel in use and `{OPERATOR_DOMAIN}` from `.arcane.json`; ask if unset.
+   - When authorship is unknown or disputed, stop and ask. Never select one identity for a mixed-author batch.
+
+4. **Analyze and group changes within each author partition** — categorize the work:
+   - What was the intent? (new feature, bug fix, docs, refactor, etc.)
+   - What scope/area was affected? (prompts, agents, security, infrastructure, journal, etc.)
+   - Is this part of a larger initiative or a standalone change?
+   - **Commit-splitting heuristic:** within one author partition, if the changes span clearly unrelated concerns (e.g., a feature change + an unrelated refactor + a dependency bump), recommend splitting them into multiple focused commits, each with its own message, rather than a single mixed commit. A single commit is fine when one author's changes serve one purpose. When splitting, stage and commit each concern separately.
+   - **Wiki-link check:** For any new `.md` files being committed, verify each has at least one outbound `[[...]]` wiki-link connecting it to the knowledge graph. Orphaned docs (no outbound links) break Obsidian's graph view. If missing, add a `Related:` or `See also:` line before committing. See the CLAUDE.md wiki-link conventions for the correct format.
+   - **TODO linkage assist (LH-09; only when this repo has its own `TODO.md` convention with backticked paths):** run `git diff --cached --name-only` and check whether any staged path also appears backticked in an open (`- [ ]`) `TODO.md` item. If so, print a one-line reminder naming the matching item so the author can close or update it in the same commit — advisory only, never blocks the commit.
+
+4.5. **Resolve execution authority before any commit or merge command:**
+
+- Declare `interaction_context: interactive | autonomous`. VS Code chat, editor chat, Claude Code, and any live operator session are `interactive`; never infer `autonomous` from tool access.
+- Resolve the acting agent's effective power level and `exec_allowed` only through the EF-27 loader-validated roster and definition. Do not parse YAML directly or trust an unvalidated value.
+- If interaction context, consent provenance, roster identity, power level, or `exec_allowed` is missing/invalid/unavailable, fail closed to the least-authorized path. Print: `Authorization downgraded: <input> is <missing/invalid>. Human execution is required for <commit/merge>.`
+- `exec_allowed: false` always requires human execution, regardless of power level.
+
+| Context / validated authority | Commit                                         | Merge / auto-complete                                    |
+| ----------------------------- | ---------------------------------------------- | -------------------------------------------------------- |
+| Interactive, any power        | Exact operator approval required               | Separate exact operator approval **and** Magus+ required |
+| Autonomous, below Magus       | May commit to topic branch when `exec_allowed` | Prohibited; queue PR for human completion                |
+| Autonomous, Magus+            | May commit when `exec_allowed`                 | May self-merge within approved scope                     |
+| Missing or invalid authority  | Human execution required                       | Human execution required                                 |
+
+5. **Determine commit type** using Conventional Commits standard:
+   - `feat` — new feature or capability
+   - `fix` — bug fix
+   - `docs` — documentation only changes
+   - `refactor` — code/structure changes without behavior change
+   - `chore` — maintenance, deps, tooling, cleanup
+   - `test` — adding or fixing tests
+   - `perf` — performance improvements
+   - `ci` — CI/CD pipeline changes
+
+6. **Determine scope** — what part of the repo changed:
+   - `prompts` — .arcane/spells/ canonical spell files (their .github/prompts, .claude/commands and .agents/skills shims are generated, never hand-edited)
+   - `agents` — agents/ directory or config
+   - `security` — security/ directory, hardening, threat model
+   - `infrastructure` — infrastructure/ directory, hardware, OS setup
+   - `decisions` — DECISIONS.md updates
+   - `journal` — journal/ entries
+   - `business` — `{BUSINESS_ROOT}` directory (resolve from `.arcane.json`'s `business_root` field, default `ventures/` if unset)
+   - `playbooks` — playbooks/ directory
+   - `governance` — governance/ directory
+   - Multiple scopes? Pick the primary one or use a broader scope like `docs` or `repo`.
+
+7. **Generate commit message with trailers** (ADR-029). For agent-authored commits, include required trailers. Format:
+
+   ```
+   type(scope): short description (72 chars max)
+
+   [Optional body with details if needed:
+   - Bullet list of key changes
+   - References to ADRs or files
+   - Context for why]
+
+   Agent: [runtime/tool name only -- claude, copilot, codex -- never a persona name]
+   Persona: [roster identity operated as, ONLY if a roster exists (.arcane/agents.yaml) and one was assigned this session -- omit entirely otherwise, never guess]
+   Role: [Persona's own AgentDefinition.role value, resolved from the roster -- never typed by hand. Present only if Persona is present]
+   Model: [model identifier, e.g., claude-opus-4-20250918]
+   Model-Source: [self-reported -- currently the only defined value; marks Model/Agent as self-reported, not independently verified]
+   Provider: [anthropic or openai]
+   Vendor: [arcane-cli, for vendored scaffold/update commits]
+   Vendor-Version: [programmatically derived installed package version, when available]
+   Task-Type: [docs, code, review, marketing, infra]
+   Channel: [vscode, cli, chat]
+   ```
+
+   **Rules:**
+   - Short description: imperative mood ("add", "fix", "update"), lowercase, no period
+   - Keep first line under 72 characters for git log readability
+   - Body is optional but useful for complex changes
+   - Reference ADRs if applicable (e.g., "Implements ADR-028")
+   - Trailers go after a blank line following the body (standard Git footer position)
+   - Required trailers for agent commits: `Agent`, `Model`, `Model-Source`, `Provider`. `Persona`/`Role` are conditional -- see `.arcane/governance/git-conventions.md`'s Agent Attribution Model for the full rule and the grading-probe example of what happens when `Role` is guessed instead of sourced.
+   - Required trailer for Arcane-vendored commits: `Vendor: arcane-cli`; include `Vendor-Version` only when derived from the installed CLI at commit time
+   - Human-authored commits: trailers are optional
+
+8. **Gate and execute the commit:**
+   - Run `git add -A` (or selective `git add` if user specifies files), show `git diff --stat --cached`, and compute an approval fingerprint from the exact staged diff plus proposed commit message.
+   - In an interactive context, present the staged diff summary, full proposed message, and fingerprint through a structured approval control. Wait for an authenticated operator response tied to that fingerprint.
+   - Timeout, cancellation, host-generated fallback, delegated response, or ordinary conversational assent is not approval. Halt without committing.
+   - Recompute the fingerprint immediately before `git commit`. If the staged diff or message changed, invalidate approval and ask again.
+   - In autonomous context, execute only when loader-validated `exec_allowed` is true. Below-Magus authority may commit to the topic branch but may not complete its PR.
+   - Run `git commit --author="..." --trailer="..." -m "message"` only after the applicable gate passes, then confirm the commit hash.
+
+9. **Push branch and run platform-specific PR flow:**
+
+   **Local-only exit:** if Step 1 classified the repository as having no usable remote merge path, skip this entire step and Step 10. Print `Local-only checkpoint: committed on <trunk>; no remote push/PR performed.` The local commit is the completed checkpoint.
+
+   **Separate merge authorization gate:** commit approval never authorizes merge. Bind any interactive merge approval to the exact PR ID and current head SHA, and re-check both immediately before completion. Missing/changed approval invalidates the gate. Never invoke merge, auto-merge, auto-complete, or `--status completed` below loader-validated Magus authority; create/update the PR, print the visible downgrade, and leave completion to a human.
+
+   a. Run `git push origin <branch>`.
+
+   a1. **MCP fail-fast / fallback.** If an MCP tool used anywhere in this step (e.g. `create_pull_request`) fails abnormally once — a hang, an idle-timeout abort, a transport error, or an empty response where data is clearly expected — treat that server as down for the rest of this session. Do not retry it blindly; fall back to the raw CLI paths below (`gh pr create` / `az repos pr create`) and report the downgrade. Full rule: `.arcane/governance/git-conventions.md` → Known issues.
+
+   b. **🛑 Mandatory pre-PR rebase (governance guard, applies to every path below).** Before invoking any PR-creation command — whether via `spell-create-pull-request`, raw `gh pr create`, raw `az repos pr create`, or an MCP `create_pull_request` tool — you MUST:
+
+   ```bash
+   git fetch origin
+   git rebase origin/<target-branch>   # default: main
+   # resolve conflicts locally; never open a PR on a branch that will conflict with target
+   git push --force-with-lease         # only if the branch already existed on origin
+   ```
+
+   This is not optional. Skipping the rebase (for example by shelling out to `az repos pr create` directly and hoping reviewers will merge over the conflict) is a governance violation. See `.arcane/governance/git-conventions.md` → **🛑 Agent-mandatory pre-PR guard**. If a rebase produces conflicts you cannot confidently resolve, **STOP** and hand off to the human — do not open the PR.
+
+   Prefer delegating to `spell-create-pull-request`, which encodes this check as its Step 0.6. The steps below are the raw-CLI fallback and still require the rebase above to have already been performed.
+
+   c. Detect remote platform from `git remote get-url origin`:
+   - `github.com` → GitHub flow
+   - `dev.azure.com` / `visualstudio.com` → Azure DevOps flow
+
+   d. **GitHub flow (when remote is GitHub):**
+   - Create PR with `gh pr create --title "<Conventional Commits title>" --body-file <pr-body-file.md>`.
+   - Use `--body-file` (not inline `--body`) to preserve multi-line markdown reliably.
+   - Assign reviewer by default (operator/reviewer identity) if available.
+   - Self-approve only when platform/policy allows. If blocked by policy, report and continue with human approval required.
+   - Complete only after the separate merge authorization gate passes, using **merge commit (no-fast-forward)** or **rebase+fast-forward**. Do not use squash.
+
+   e. **Azure DevOps flow (when remote is ADO):**
+   - Check if an active PR already exists for the source branch:
+     - `az repos pr list --source-branch <branch> --status active --output json`
+     - If one exists, reuse it; otherwise create via `az repos pr create`.
+   - For multi-line markdown descriptions:
+     - Bash: `--description "$(cat <pr-body-file.md>)"`
+     - PowerShell: `--description (Get-Content -Raw .\<pr-body-file.md>)`
+   - Assign reviewer by default to the operator/reviewer identity (for example from `git config user.email`), idempotently (skip if already assigned).
+   - Approve via CLI first: `az repos pr set-vote --id <PR_ID> --vote approve`.
+   - If self-approval is blocked by policy, report that a second human approval is required and continue without forcing approval.
+   - Only after the separate merge authorization gate passes, complete idempotently with source-branch deletion enabled and squash disabled: `az repos pr update --id <PR_ID> --status completed --delete-source-branch true --squash false`.
+   - Use only **merge (no-fast-forward)** or **rebase+fast-forward** merge strategy; never squash.
+   - REST fallback only when CLI commands fail or are unavailable. Ensure the request URI is fully qualified and includes exactly one `?api-version=7.1`.
+
+   f. **PR description quality rules** (both platforms):
+   - `## Summary` with why the PR exists.
+   - Structured `###` sections for each logical change area.
+   - A `### Testing` checklist (`- [x]` / `- [ ]`).
+   - Tables/code blocks where they improve clarity.
+   - `## For the record` — **only when this PR is one epic of a tracked program** (one with a
+     `docs/plans/<slug>/PLAN.md`); omit the heading entirely otherwise. One plain sentence a
+     non-engineer reading the finished program would understand, plus `· category: <…>`.
+     It is copied verbatim into the epic's `PLAN.md` entry as its `**Report:**` line when the epic
+     is recorded. See `spell-create-pull-request`'s Step 4 for the full convention — defined there,
+     referenced here.
+
+   g. Capture PR ID/URL from command output.
+   - Always render PRs as clickable markdown links with the full URL.
+   - Never write a bare `PR #NNN`.
+
+10. **Post-merge cleanup (worktree-safe):**
+
+- Ensure remote cleanup:
+  - `git push origin --delete <branch>` (if already deleted, treat as non-fatal)
+  - `git fetch --prune origin`
+- If `<branch>` is attached to an active worktree, skip local branch deletion.
+- If branch is not attached to any active worktree, run `git branch -d <branch>` — but 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) before trusting a "safe to delete" read.
+- Return to `main` only when appropriate for the active session/worktree context.
+- If other stale local branches exist (merged or older than 7 days), list them and suggest cleanup.
+- See [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) Post-Merge Cleanup section.
+
+## Troubleshooting
+
+- **Wrong platform commands:** Always detect platform from `git remote get-url origin` before running PR commands.
+- **ADO `api-version` errors:** Prefer `az repos pr set-vote` and `az repos pr update` first. If REST fallback is needed, verify URI path and single `?api-version=7.1`.
+- **Reviewer already assigned:** Treat as non-fatal; continue without re-adding reviewer.
+- **Vote API quirks / policy blocks:** If `set-vote` succeeds but approval does not satisfy policy, confirm reviewer vote state and require a second human approval.
+- **Worktree branch delete failure:** If branch is attached to a worktree, skip local delete and continue with remote delete + prune.
+- **Remote branch already deleted:** Continue and run `git fetch --prune origin`.
+
+Output format after execution:
+
+## Commit Complete
+
+```
+[commit hash] type(scope): description
+Author: Display Name <email>
+```
+
+**Files committed:**
+
+- File 1
+- File 2
+- ...
+
+**Commit metadata used:**
+
+- Author override: `yes/no`
+- Agent trailers: `included/skipped`
+- Provider trailer: `included/skipped`
+
+**Pull Request:** [full PR URL](https://github.com/{org}/{repo}/pull/{id} or https://dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/{id})
+
+**Branch topology** — per the generated state diagrams convention (rule 8, ARC-036), built only from
+data Step 1/9 already gathered (current branch name, commits ahead of target via
+`git log origin/<target>..HEAD --format="%h %s" --reverse`). Skip entirely — this is the applicability
+guard — when there is no separate topic branch (the local-only-checkpoint path, committing directly on
+trunk) or no usable remote (nothing to compare against):
+
+```mermaid
+gitGraph
+   commit id: "<target HEAD short-sha>"
+   branch <branch-name>
+   commit id: "<short-sha 1>"
+   commit id: "<short-sha 2>"
+```
+
+One commit per entry in the gathered commit list, in the same order; omit the diagram (not just the
+commits) if that list is empty. Use `<target>`'s short SHA as the fork-point commit id.
+
+**Next:** Continue work or run `spell-close-session` to finalize journal and session docs.

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

@@ -0,0 +1,130 @@
+---
+name: Spell — Compliance
+description: Run a regulatory compliance self-assessment against this repo (GDPR, CCPA, SOC 2, HIPAA) and produce a prioritized remediation checklist. Read-only — never drafts policies or fixes gaps automatically.
+claude_description: Use PROACTIVELY before a launch, an enterprise sales cycle, or a security questionnaire that raises GDPR/CCPA/SOC 2/HIPAA questions.
+argument-hint: Optional focus (e.g., "GDPR only", "pre-launch check", "SOC 2 readiness")
+agent: agent
+---
+
+## Executive Summary
+
+- This spell self-assesses a repo's compliance posture against GDPR, CCPA, SOC 2, and HIPAA, and
+  produces a prioritized remediation checklist.
+- **It is read-only.** It never drafts a privacy policy, invents a retention period, or fixes a gap on
+  its own — every finding is a checklist item for a human (often with legal input) to act on.
+- **This is not legal advice**, and the report says so explicitly. It is a starting self-assessment
+  against established, uncontroversial obligations — not a substitute for a qualified lawyer's analysis
+  of this specific business's specific facts.
+- Findings cite `CS-nn` rule IDs from
+  [`compliance-standards.md`](../../.arcane/governance/compliance-standards.md) — the rationale for each
+  obligation lives there, not restated here.
+
+---
+
+## Context files
+
+- [governance/compliance-standards.md](../../.arcane/governance/compliance-standards.md) — every
+  `CS-nn` rule this spell checks against. Rules are **cited by ID only** in this spell, never restated.
+  **If the file is not installed**, this spell still runs in full — findings just cite each check as
+  `CS-nn (rationale unavailable — install the standards doc)` instead of linking to it.
+- `threat-model.md` and `hardening-checklist.md`, if present — the security-control evidence for `CS-10`
+  (access control, audit logging) frequently already exists in these docs rather than needing to be
+  assessed fresh.
+- `project.md` / `.arcane.json` — for the business context (target users, whether the product could
+  plausibly reach EU or California residents, whether it handles health data) that Phase 1 needs.
+
+## Phase 1 — Determine applicability (ask, don't assume)
+
+Applicability determinations have real consequences, so resolve each of the following by checking the
+repo's own context first (`project.md`, `.arcane.json`, existing docs); **ask the operator directly**
+for anything not resolvable from those sources — never assume:
+
+- Could the product realistically reach EU residents (any public-internet-reachable consumer product
+  defaults to yes) — GDPR relevance (`CS-01`).
+- Does the business meet, or plausibly approach, CCPA/CPRA's revenue or data-volume thresholds, and
+  could it reach California residents — CCPA relevance (`CS-04`). State plainly that exact thresholds
+  should be verified against current statute, not assumed from this spell's own knowledge.
+- Is a customer, prospect, or procurement process currently asking for a SOC 2 report, or is one
+  expected within a near-term sales cycle — SOC 2 relevance (`CS-09`).
+- Does the product create, receive, maintain, or transmit protected health information as a covered
+  entity or business associate — HIPAA relevance (`CS-11`). State plainly that this is a narrow trigger,
+  not a default.
+
+Record which frameworks are in scope for this run and why, before proceeding — a framework judged
+out of scope is reported as such in Phase 4, not silently skipped without explanation.
+
+## Phase 2 — Inventory (read-only)
+
+Enumerate what compliance-relevant artifacts already exist, without judging sufficiency yet:
+
+- A privacy policy — does one exist, and where.
+- A data inventory / Records of Processing Activities doc — does one exist and does it name what
+  personal data is collected, where it's stored, and why.
+- A retention/deletion policy — does one exist, and does it define a period per data category.
+- Consent mechanism indicators — a cookie/consent banner, a consent-management SDK, an opt-in flow in
+  the signup path; and separately, a "Do Not Sell or Share" link or equivalent opt-out mechanism.
+- Existing security documentation this repo may already ship (`threat-model.md`,
+  `hardening-checklist.md`, `authentication-strategy.md`) — relevant evidence for `CS-10` without
+  needing to reassess it from scratch.
+- Breach-notification process — is there a documented incident-response process with a named owner and
+  a notification path.
+
+Report anything not found as absent, not as failed — Phase 3 is where absence becomes a finding against
+a specific applicable rule.
+
+## Phase 3 — Audit
+
+For each framework marked in-scope in Phase 1, check its rules from `compliance-standards.md` against
+what Phase 2 found. Mark each `PASS` / `FAIL` / `PARTIAL`, citing the rule ID only:
+
+```text
+CS-07 FAIL — no data inventory found; a data inventory is the prerequisite artifact CS-02/CS-04's
+  rights-request obligations depend on.
+CS-06 PARTIAL — a consent banner exists, but the "accept all" and "reject non-essential" options are
+  not visually equivalent, which is a common consent-validity gap.
+```
+
+Do not restate why a rule matters — that reasoning lives in `compliance-standards.md`; cite the ID and
+state the evidence.
+
+## Phase 4 — Report
+
+Produce a prioritized remediation checklist: mandatory-baseline gaps (GDPR/CCPA, if in scope) before
+optional-tier gaps (SOC 2, HIPAA), and structural prerequisites (a missing data inventory) before the
+rights-request/consent mechanisms that depend on them.
+
+```markdown
+## Compliance Self-Assessment — [repo name]
+
+**Frameworks assessed:** [list, with in-scope/out-of-scope reasoning from Phase 1]
+**Date:** [timestamp]
+
+> This is a self-assessment against established compliance obligations, not legal advice. Confirm any
+> finding below with qualified counsel before treating it as a compliance determination.
+
+### Findings, by priority
+
+#### Mandatory baseline (GDPR / CCPA)
+- [ ] CS-07 — [gap + what artifact would close it]
+
+#### Optional tier (SOC 2 / HIPAA), if in scope
+- [ ] CS-10 — [gap + what artifact would close it]
+
+### Out of scope this run
+- [Framework] — [why, per Phase 1's determination]
+```
+
+## Rules
+
+This spell defers entirely to
+[governance/compliance-standards.md](../../.arcane/governance/compliance-standards.md) for what each
+obligation means and why. Findings in this spell cite rule IDs; they do not re-explain them. This spell
+never drafts a policy document, never invents a retention period or lawful basis on the operator's
+behalf, and never claims to produce a legal compliance determination — every output is a checklist item
+for a human to act on, with legal input where the finding calls for it.
+
+## Related
+
+- [Compliance Standards](../../.arcane/governance/compliance-standards.md)
+- **Feeds into:** the operator's own remediation work — this spell does not fix gaps, it enumerates
+  them.

package/dist/assets/.arcane/spells/spell-create-pull-request.md

@@ -0,0 +1,224 @@
+---
+name: Spell — Create Pull Request
+description: Open a pull request for the current branch with an auto-generated title and description from commit history. Provider-agnostic (GitHub or Azure DevOps).
+claude_description: Use PROACTIVELY whenever opening a pull request for the current branch, even if the user just says 'open a PR'.
+argument-hint: '[--draft] [--reviewers <name,...>] [--target <branch>] [--docs-only]'
+agent: agent
+last_updated: 2026-07-05
+---
+
+## Executive Summary
+
+- This spell creates a pull request for the current feature branch — no manual title/description writing.
+- It auto-generates a Conventional-Commits title and a structured description from the commit log.
+- It is provider-agnostic: it detects GitHub vs Azure DevOps from the git remote and uses the right CLI.
+- The PR is the only path to `main` (direct pushes are blocked by policy). See `.arcane/governance/git-conventions.md`.
+
+---
+
+Create a pull request for the current branch.
+
+Context to consult:
+
+- `.arcane/governance/git-conventions.md` — PR requirements, branch policy, merge strategy (the no-squash rule).
+- `.arcane/governance/testing-standards.md` — coverage thresholds to cite in the description.
+
+Related spells:
+
+- `spell-commit-work` — land your work as Conventional-Commits commits before opening the PR.
+- `spell-ship` — the broader release flow that records the PR URL after this spell creates it.
+- `spell-address-review` — resolve reviewer feedback once the PR is open.
+- `spell-sync-pull-request` — the recovery path when Step 0.6's rebase guard hits a conflict.
+
+## Arguments
+
+- `--draft` — create the PR as a draft (work-in-progress / early feedback).
+- `--reviewers <name,...>` — comma-separated reviewers. Optional.
+- `--target <branch>` — target branch (default `main`).
+- `--docs-only` — lightweight mode for documentation-only changes: prefixes `[docs]` in the title and skips test-evidence/review sections. It does not bypass merge authorization.
+
+## Authorization Gate
+
+Before enabling auto-complete/auto-merge or completing an existing PR, resolve `interaction_context`, effective power level, and `exec_allowed` through the EF-27 loader-validated roster/definition. Missing or invalid authority visibly downgrades to PR creation only. Print the invalid/missing input and state that human completion is required.
+
+- Below Magus: create the PR and stop; never request auto-complete or invoke merge.
+- Autonomous Magus+: auto-complete/self-merge is allowed within approved scope when `exec_allowed` is true.
+- Interactive Magus+: require separate authenticated operator approval bound to the exact PR ID and head SHA. Commit approval is not merge approval.
+- Re-check authority, PR ID, and head SHA immediately before completion; any change invalidates approval.
+
+## Step 0 — Guard checks
+
+> **🛑 AGENT-MANDATORY PRE-PR CHECKLIST — READ FIRST.** Before *any* PR-creation call (this spell, raw `az repos pr create`, raw `gh pr create`, the `create_pull_request` MCP tool, REST, web hook, or anything else):
+>
+> 1. `git fetch origin`
+> 2. `git rebase origin/<target-branch>` (default `main`) and resolve conflicts locally
+> 3. `git push --force-with-lease` if the branch was already on origin
+> 4. *Then* run the PR-creation call
+>
+> This rule is on the **agent**, not on the spell. Calling `az repos pr create` / `gh pr create` directly is **not** an escape hatch — it is a governance violation. See `.arcane/governance/git-conventions.md` → **🛑 Agent-mandatory pre-PR guard**.
+
+1. Run `git branch --show-current`. **STOP** if on `main`/`master` — you cannot PR the integration branch into itself. Also **STOP** if detached HEAD (empty output) — check out a named branch first.
+2. **Verify the target exists:** `git rev-parse --verify origin/<target>`. If it fails, `git fetch origin <target>`; if still missing, **STOP** and ask the user for the correct `--target`.
+3. **Ensure the branch is on origin (upstream):** if `git rev-parse --abbrev-ref --symbolic-full-name @{u}` fails, the branch was never pushed — run `git push -u origin <branch>`. The provider CLIs can only open a PR for a branch that exists on the remote.
+4. **STOP** if the branch has no commits ahead of the target: `git log origin/<target>..HEAD --oneline` is empty → nothing to PR.
+5. Check for an existing **open** PR for this branch (provider-specific, Step 2). If one exists, print its URL and stop — never create duplicates.
+6. **Mandatory rebase on target (governance guard):** `git fetch origin` then `git rebase origin/<target>`. On clean rebase, `git push --force-with-lease` (only if the branch existed remotely before the rebase). On conflicts: **STOP**, list conflicting files, ask the user to resolve **or run `spell-sync-pull-request`** — it draws the same mechanical-vs-ambiguous conflict line this guard doesn't attempt to, with a recoverable ref before it touches anything; never push a branch that will produce a merge conflict on the target (see git-conventions "🛑 Agent-mandatory pre-PR guard"). This step is not optional and is not skippable by calling a different PR-creation tool.
+7. **Auto-suggest `--docs-only`** (only if not already passed): if every changed file vs target is documentation/session files (`*.md`, `TODO.md`, `DECISIONS.md`, `journal/**`, `IDEAS.md`, `FEEDBACK.md`), print a one-line hint suggesting `--docs-only` and proceed with the standard path.
+
+## Step 1 — Gather context
+
+```bash
+git branch --show-current
+git log origin/<target>..HEAD --format="%h %s" --reverse   # commit list
+git diff origin/<target>..HEAD --stat | tail -1            # files / insertions / deletions
+git remote get-url origin                                  # provider detection
+```
+
+## Step 2 — Detect provider
+
+| Remote URL contains | Provider |
+| --- | --- |
+| `github.com` | GitHub (`gh`) |
+| `dev.azure.com` / `visualstudio.com` | Azure DevOps (`az repos`) |
+| anything else | unknown — **STOP** and ask the user which provider/CLI to use |
+
+If the detected provider's CLI is missing or unauthenticated (`gh auth status` / `az account show` fails), **STOP** with a clear message — do not silently fall back to the other provider.
+
+Check for an existing **open** PR before creating (filter by state so a previously merged/closed PR for the same branch does not falsely block):
+
+- **GitHub:** `gh pr list --head <branch> --base <target> --state open --json url --jq '.[0].url'`
+- **Azure DevOps:** `az repos pr list --source-branch <branch> --target-branch <target> --status active --output json`
+
+If an open PR is found, print its URL and stop.
+
+## Step 3 — Build the title
+
+Format: `type(scope): summary`
+
+1. `type` = the majority commit type in the log (e.g. `feat`, `fix`, `chore`).
+2. `scope` = optional; derive from the dominant changed area if obvious, else omit the parens.
+3. `summary` = a concise one-line synthesis of the commits (≤ 72 chars per git-conventions), lowercase, imperative, no trailing period.
+4. With `--docs-only`, prepend `[docs] `.
+
+## Step 4 — Build the description
+
+Write the body to a **temp file** and pass it to the provider CLI by file reference — never pass multiline content as a shell argument (this avoids shell/PowerShell truncation, quoting, and newline-mangling). Resolve the scratch path with `git rev-parse --git-dir` (handles worktrees and non-default `.git` locations) and write to `<git-dir>/arcane-pr-body.md`. The `.git` directory is never committed, so the body file is safe and ignored. Delete it after a successful create (Step 6).
+
+Standard template:
+
+```markdown
+## Summary
+
+<1–3 sentences synthesized from the commits — not copied verbatim.>
+
+## Changes
+
+### Features
+- <feat summaries>
+### Fixes
+- <fix summaries>
+### Infrastructure / Chores
+- <chore/docs/ci/refactor summaries>
+
+> Omit empty sections.
+
+## Testing
+
+- <coverage / test status if known, else "See CI pipeline results.">
+
+## For the record
+
+<One plain sentence a non-engineer reviewing the finished program would read — what changed for
+them, not how it was built. Omit this section entirely when the PR is not one epic of a tracked
+program.> · category: <spell|feature|governance|decision|fix|process|docs|platform>
+```
+
+`--docs-only` template (skip Testing):
+
+```markdown
+## Summary
+<1–2 sentences on the doc changes.>
+
+## Changes
+- <changed files or sections>
+
+## Notes
+Documentation-only PR. No functional code changed.
+
+## For the record
+
+<Same as above — include only when this PR is one epic of a tracked program.> · category: docs
+```
+
+**About `## For the record`** — include it **only when this PR is one epic of a tracked program**
+(one with a `docs/plans/<slug>/PLAN.md`); omit the heading entirely otherwise, since an empty
+section is worse than none. Write the sentence that program's completion report will show for this
+epic, in the reader's language rather than the implementation's — what changed for someone reading
+the finished program, not how it was built. Authoring it here, while the work is fresh, is the
+point: it is copied verbatim into the epic's `PLAN.md` entry as its `**Report:**` line when the
+epic is recorded (`spell-close-session` step 4d). An epic that never gets one renders visibly as
+**unwritten** in the report — never as a pasted commit subject — so a missing line stays a visible
+gap rather than a silently fabricated one.
+
+The line ends at `category:`. It carried a trailing `· glyph: <emoji>` until ARC-043, which
+dropped it: `category` is a closed set of eight and already selects the mark the report draws, so a
+per-epic emoji was a second, redundant decision on every line — and an emoji renders differently on
+every platform, prints badly, and cannot take the report's own colour. Do **not** author one.
+Lines written before ARC-043 still carry theirs; the parser reads past it and the report ignores it,
+so they need no edit.
+
+## Step 5 — Create the PR
+
+- **GitHub:**
+  ```bash
+  gh pr create --title "<title>" --body-file <temp> --base <target> --head <branch> [--draft] [--reviewer <r1,r2>]
+  ```
+  With `--docs-only`, `gh pr merge --auto <PR#>` is permitted only after the authorization gate above passes (use the repo's configured merge method; do **not** force squash — see git-conventions).
+- **Azure DevOps:**
+  ```bash
+  az repos pr create --title "<title>" --description "@<temp>" --source-branch <branch> --target-branch <target> [--draft] [--reviewers "<r1> <r2>"]
+  ```
+  With `--docs-only`, add `--auto-complete` only after the authorization gate above passes. Respect the repo merge strategy — never enable squash (see git-conventions).
+
+**Reviewers:** pass `--reviewers`/`--reviewer` values through as given. If a reviewer cannot be resolved by the provider, do **not** abort the create — let the PR be created and surface the unresolved name(s) in the Step 6 report so the user can add them manually.
+
+**Post-create verification (both providers):** read the PR back (`gh pr view <PR#> --json url,title,body` / `az repos pr show --id <PR#>`). If the title or description is empty or does not match the temp file, patch it (`gh pr edit` / `az repos pr update`) from the temp file, then re-verify once. This guards against silent body truncation/drop on either CLI.
+
+## Step 6 — Report
+
+```
+✓ PR created: <URL>
+  Title:     <title>
+  PR #:      <number>
+  Source → Target: <branch> → <target>
+  Reviewers: <list or "none assigned">
+```
+
+- If no reviewers were resolved (none passed, or names the provider could not match): `⚠ No reviewers assigned — add them in the PR or re-run with --reviewers`.
+- If `--draft`: note it was created as a draft.
+- Delete the body temp file (`<git-dir>/arcane-pr-body.md`) once the PR is confirmed created and verified.
+- **Branch topology** — per the generated state diagrams convention (rule 8, ARC-036), built only from
+  Step 1's already-gathered branch name and commit list (`git log origin/<target>..HEAD --format="%h %s" --reverse`).
+  Skip entirely (the applicability guard) if that commit list is empty — Step 0.4 already stops before
+  reaching here in that case, so this only re-states the same guard for anyone reading this step in
+  isolation:
+
+  ```mermaid
+  gitGraph
+     commit id: "<target HEAD short-sha>"
+     branch <branch-name>
+     commit id: "<short-sha 1>"
+     commit id: "<short-sha 2>"
+  ```
+
+  Same shape `spell-commit-work` uses for the identical concept — reference it rather than re-deriving
+  the rule (D8): one commit per gathered log entry, target's short SHA as the fork point.
+
+## Rules
+
+- Never create duplicate PRs — always check first (Step 2).
+- Never push directly to `main` — the PR is the only path.
+- Always write the description to a file before passing it to the provider CLI.
+- Respect the repo merge strategy in `.arcane/governance/git-conventions.md` — **do not squash** (it breaks per-commit attribution).
+- Print the PR URL clearly so it can be recorded by `spell-ship` / `spell-close-session`.
+- Never include secrets or tokens in the title or description.