arcane-cli 0.39.0 → 1.0.0

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

@@ -0,0 +1,82 @@
+---
+name: Spell — Bump Version
+description: Determine the correct semver bump type for the current change and apply it to package.json
+claude_description: Use PROACTIVELY before shipping any change that touches distributable content, to determine and apply the correct version bump.
+argument-hint: Optional context about the change (e.g., "new component", "bug fix", "breaking API change")
+agent: agent
+---
+
+## Executive Summary
+
+- This spell determines whether a version bump is required and applies the correct semver type.
+- Use it whenever you've changed `src/assets/`, `registry.ts`, or `profiles.ts` in the arcane repo.
+- It enforces the rule from `project.md` → Constraints → Self-hosting: "Anything touching
+  `src/assets/` requires a version bump." (Corrected 2026-08-31, BC-06 — this previously cited
+  CLAUDE.md, which now carries only the working protocol; the rule's live prose home moved to
+  `project.md ("requires a version bump"):56-58`.)
+
+---
+
+Determine the correct semver bump and apply it.
+
+## Step 1 — Check whether a bump is needed
+
+Run the version check gate in **staged mode** (LH-06a) — this spell runs before the commit that
+will actually contain the change, so the default `merge-base..HEAD` diff can't see it yet; staged
+mode unions that diff with `git diff --cached --name-only` so today's not-yet-committed work is
+checked too, not just history:
+
+```
+npm run check:version-bump -- --staged
+```
+
+- If it **passes** → no bump needed. Stop here and report "No version bump required."
+- If it **fails** → proceed to Step 2.
+- If the changed content isn't staged yet (working-tree edits only), use `-- --working-tree`
+  instead, which additionally unions plain `git diff --name-only`.
+
+## Step 2 — Determine semver type
+
+Inspect the changed files in `src/assets/`, `registry.ts`, and `profiles.ts`:
+
+| Change type | Bump |
+|---|---|
+| New component added to registry (new file in `src/assets/`) | `minor` |
+| Existing asset file updated (content change, no new component) | `patch` |
+| Component removed from registry | `minor` |
+| Breaking change to CLI API or registry schema | `major` |
+| Bug fix in CLI source (`src/modules/`, `src/commands/`) | `patch` |
+| New CLI command or flag | `minor` |
+
+When in doubt: new distributable content = `minor`, content update = `patch`.
+
+## Step 3 — Apply the bump
+
+Run the appropriate command (do **not** use `--git-tag-version` — tagging happens at publish time):
+
+```
+npm version patch --no-git-tag-version
+# or
+npm version minor --no-git-tag-version
+# or
+npm version major --no-git-tag-version
+```
+
+## Step 4 — Verify and stage
+
+```
+node -e "const p = require('./package.json'); console.log(p.version)"
+git add package.json package-lock.json
+```
+
+## Step 5 — Commit
+
+Use `spell-commit-work` to commit the version bump as a separate commit:
+
+```
+chore(release): bump version to X.Y.Z
+```
+
+Include in the commit body:
+- What distributable change triggered the bump
+- Which components were added/changed

package/dist/assets/.arcane/spells/spell-check-drift.md

@@ -0,0 +1,118 @@
+---
+name: Spell — Check Doc Drift
+description: Detect contradictions and stale statements across core Arcane docs and report severity-graded findings (report-only by default; opt-in --fix applies safe mechanical fixes).
+claude_description: Use PROACTIVELY to detect contradictions and stale statements across core docs, periodically or after major changes.
+argument-hint: Optional scope selector --scope all|journal|todos|decisions|git (default all); free-text hints also accepted. Add --fix to apply safe mechanical fixes.
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt identifies documentation contradictions, stale dates, and inconsistencies across the repo.
+- It cross-references core docs to find drift between ADRs, journals, configuration files, and operational guides.
+- Use this periodically (weekly/monthly) or after major changes to maintain documentation accuracy.
+- **Report-only by default** (non-destructive): output is severity-graded findings with exact fix recommendations. Pass `--fix` to also apply safe, mechanical, unambiguous fixes.
+
+**Related spells:** `spell-open-session` consumes this as an early drift-check pre-step (feeds-into); this spell also runs standalone. Related to `spell-close-session`, which flags drift at session close.
+
+---
+
+Detect documentation drift in this repository.
+
+Use these files first:
+
+- [README.md](../../README.md)
+- [project.md](../../project.md)
+- [TODO.md](../../TODO.md)
+- [DECISIONS.md](../../DECISIONS.md)
+- [ai-context/system-prompt-context.md](../../ai-context/system-prompt-context.md)
+- [agents/agent-policies.md](../../.arcane/governance/agent-policies.md)
+- Most recent journal file(s) in [journal/](../../journal/)
+- Relevant business overviews under `{BUSINESS_ROOT}/` (resolve from `.arcane.json`'s `business_root` field, default `ventures/` if unset)
+- `{BUSINESS_ROOT}/registry.json`, if present (hub-role and registry-consistency detectors)
+
+Scope selection (`--scope <value>`, default `all`):
+
+- `all` — run every detector below (default).
+- `journal` — Journal chronology only.
+- `todos` — Done vs. carry-forward consistency only.
+- `decisions` — Decision-ID existence only.
+- `git` — Decision-ID existence plus the general contradiction/stale-date checks against tracked docs (git-tracked doc state); does not run journal-ordering or carry-forward detectors.
+
+A free-text scope hint (e.g., "security docs", "business docs") is still accepted and narrows the file set; `--scope` selects which detector catalog runs. When both are given, `--scope` governs the detector set and the free-text hint narrows the files.
+
+Concrete detectors to run (in addition to general contradiction/stale-date checks):
+
+- **Journal chronology** — journal entries and their dates must be in sane order. Flag out-of-order entries, duplicate session numbers, and any future or otherwise contradictory dates.
+- **Done vs. carry-forward consistency** — items marked done must not still appear as open or carry-forward items, and items listed as open/carry-forward must not also be marked done elsewhere.
+- **Decision-ID existence** — decision IDs referenced in TODO, journal, or other docs must exist in `DECISIONS.md`, and the IDs in the decisions log must be sequential and unique (no gaps that imply a missing entry, no duplicates).
+- **Shipped-state staleness** (LH-08; only when this repo has its own `scripts/check-stale-claims.ts` — Arcane's own repo, or one that adopted the same convention; skip gracefully otherwise) — run `npm run check:stale-claims -- --report` and triage its Class B output (occurrences of "not yet built"/"not yet supported"/"tracked as future work" and similar phrases in shipped or living content): each hit is a prompt to verify the claim against the real tree, not proof of staleness by itself. Class A (`ARC-NNN (Status)` claims vs. `DECISIONS.md`) is already a separate, mechanically-enforced CI gate — do not re-litigate its findings here, only Class B needs this judgment pass.
+- **Canonical vs. installed-copy parity** — for every managed root file that has a canonical counterpart under `src/assets/`, compare bytes first. If bytes differ, normalize `CRLF` and lone `CR` to `LF` in both files and compare again:
+  - If normalized content differs, report **real content drift** with normal severity grading.
+  - If normalized content matches, report **line-ending-only drift** separately. Do not count these paths as real content findings and do not include them in severity totals or the Go / No-Go decision.
+  - Report exact path counts for both classes. Never summarize all byte-different files as content drift.
+- **Hub-artifact leak (non-hub repos)** — if `.arcane.json` does not have `role: "hub"`, the existence of any `{BUSINESS_ROOT}/*/IDEAS.md`, `{BUSINESS_ROOT}/*/TODO.md`, or `{BUSINESS_ROOT}/registry.json` (resolve `{BUSINESS_ROOT}` the same way as above -- a consumer repo can still have a configured `business_root` left over from a prior role change, so this must not skip resolution just because the repo isn't currently a hub) is **Critical**: hub-only artifacts (potentially including sibling-venture and portfolio data) do not belong in a repo that isn't a declared hub. This check is deliberately structural (file existence only) — a non-hub repo cannot safely hold the sibling-name list a content-level check would need, so that asymmetry is by design, not a gap.
+- **Hub role/registry consistency (hub repos only)** — when `.arcane.json` has `role: "hub"`:
+  - `role: "hub"` with no `{BUSINESS_ROOT}` directory (default `ventures/`) present — **High**: the manifest claims a role the repo can't actually fulfill.
+  - `{BUSINESS_ROOT}/registry.json` slugs that don't match an existing `{BUSINESS_ROOT}/<slug>/` folder, or venture folders with no registry entry — **Medium**, both directions.
+  - Malformed `status: promoted → …` / `status: dropped …` markers in any book (unparseable destination, missing date) — **Low**.
+  - A `{BUSINESS_ROOT}/<slug>/` folder with a `role`-shaped `.arcane.json`-like marker of its own (i.e., it looks like it's trying to be a hub itself) — **Medium**: flag for operator review; nested hubs are unsupported.
+
+For each drift finding include:
+
+- Severity (`Critical`, `High`, `Medium`, or `Low`)
+- Severity rationale (one line: why this severity — e.g. work-integrity/duplicate-work risk → HIGH; confidence/correctness gap → MEDIUM; cosmetic → LOW)
+- Drift statement
+- Canonical source file (cite by stable locator — a heading anchor or a unique quoted phrase, e.g. `path#anchor` or `path ("unique phrase")` — never a bare line number, since findings routinely get promoted into TODO.md or another living doc afterward, where a line number drifts the moment the file is next edited)
+- Affected file (same stable-locator citation)
+- Exact recommended fix
+
+Every finding that points to a specific location MUST be pinpointable: cite by stable locator (a heading anchor or a unique quoted phrase, e.g. `path#anchor` or `path ("a unique phrase from the target")`). A bare line number may accompany a stable locator as a convenience (this report is read once, in the current tree), but never replace one — a citation promoted into a living doc later must survive on its own. If no precise anchor or phrase exists, cite the nearest available locator (heading, section, or list item) instead of omitting it.
+
+Behavior:
+
+- **Default mode is report-only and non-destructive — do not edit any files.** Only detect, grade, and report drift with recommended fixes.
+- **Only when invoked with `--fix`**: apply fixes that are mechanical and unambiguous, then report each edit applied. Still never apply ambiguous fixes — list those under Needs Confirmation instead.
+- If drift is ambiguous, do not edit (in either mode); ask a targeted clarification question.
+
+Output format:
+
+## Drift Report
+
+- **Scope:** the `--scope` value (`all`/`journal`/`todos`/`decisions`/`git`), any free-text hint, and mode (`report-only` or `--fix`).
+- **Date:** ISO date of this run.
+- **Real content findings:** total count, broken down per severity.
+- **Line-ending-only drift:** path count, reported separately and excluded from severity totals.
+
+## Real Content Drift Findings
+
+- One line per finding with stable-locator references (heading anchor or unique quoted phrase — nearest locator if neither applies) and its severity rationale.
+
+## Line-Ending-Only Drift
+
+- List byte-different paths whose contents match after line-ending normalization, or `None`.
+- Keep this list separate from real content findings even when it is long; a count plus path list is sufficient.
+
+## Fixes Applied
+
+- List edits applied (only possible in `--fix` mode), or `None`.
+
+## Needs Confirmation
+
+- Open questions that block safe edits, or `None`.
+
+## Suggested Next Updates
+
+- Short, prioritized follow-up edits.
+
+## Go / No-Go
+
+- A final roll-up verdict: **GO** if the workspace is clean enough to proceed (no unresolved Critical/High findings), or **NO-GO** if drift must be fixed first. State the single most important blocker and what must happen before proceeding.
+
+Rules:
+
+- Prefer ADR decisions and latest journal facts when conflicts exist.
+- Do not rewrite historical journal content.
+- Treat `src/assets/` as canonical when comparing a managed root dogfood copy with its distributable source counterpart.
+- A line-ending-only difference is review noise, not evidence of contradictory content; never let it create a Critical/High finding or a `NO-GO` verdict by itself.
+- Keep changes minimal and traceable.

package/dist/assets/.arcane/spells/spell-close-session.md

@@ -0,0 +1,266 @@
+---
+name: Spell — Close Session
+description: End a work session by logging outcomes in today's journal and pruning completed TODO items with verifiable evidence.
+claude_description: Use PROACTIVELY at the end of any significant work session, even if the user just says 'wrap up' or 'done for now'.
+argument-hint: Optional session focus (e.g., a config change, a fix, infrastructure setup)
+agent: agent
+---
+
+## Executive Summary
+
+- This prompt formally closes a session by capturing work done, decisions made, and lessons learned in the journal.
+- It updates TODO.md, DECISIONS.md, and ai-context/system-prompt-context.md to reflect current state.
+- Use this at the end of every significant work session to preserve continuity and maintain documentation hygiene.
+- The structured workflow ensures nothing is lost between sessions and handoff state is clean.
+
+---
+
+Close the current Arcane session and leave docs in a clean handoff state.
+
+Use these files first:
+
+- [TODO.md](../../TODO.md)
+- [DECISIONS.md](../../DECISIONS.md)
+- [ai-context/system-prompt-context.md](../../ai-context/system-prompt-context.md)
+- Most recent journal file(s) in [journal/](../../journal/)
+- Any files changed during this session
+
+Workflow:
+
+1. **Reconstruct the full session** from conversation context, terminal history, and changed files. Identify:
+   - Actions completed (config changes, installs, fixes).
+   - Decisions made (even implicit ones like naming choices, tool preferences, or workflow patterns).
+   - Problems encountered and how they were resolved (troubleshooting).
+   - Lessons learned (anything that cost time, surprised the user, or should prevent future mistakes).
+   - **Capture tie-in tip:** If this session produced durable analysis worth formalizing (a design, an investigation, a research finding, a reusable explanation), suggest running `spell-document` before closing so it lands in the right doc — a research finding defaults to `docs/research/<topic-slug>.md` per `portable-bootstrap.md`'s Research Reports convention. For quick ideas worth keeping but not yet actionable, suggest `spell-save-idea`. If this session had a real verification event worth a structured record — especially a confidently stated claim that a check later contradicted — suggest `spell-verification-ledger` separately; it is not part of this close-session flow itself.
+
+1b. **Verify in-flight async work before writing any output artifact (EF-21). Enforcement: structured spell gate (ARC-023) — this workflow requires the observable state of every dispatched item before proceeding to step 2.** "I started it" is not "it worked." Before the journal, TODO.md, or the handoff are written, enumerate every piece of asynchronous work dispatched during this session that could still be running or could have failed after being kicked off — CI/CD runs, deployments, package publishes, long-running background tasks, PR checks. For each, **actively check** its current status through whatever means is available (CI provider API/CLI, deployment dashboard, `gh run view`, `az pipelines runs show`, etc.) — attempt the check before reaching for `unverifiable`; that state exists for genuine access limits (no CLI/API access, no credentials, provider outage), not for skipping a check that was merely inconvenient to run. Then classify into exactly one state:
+
+    - **succeeded** — confirmed complete and correct. Only this state may be described as "done," "completed," or "shipped" anywhere in the journal, TODO.md, or the handoff.
+    - **failed** — confirmed to have failed. Record as a blocker or carry-forward item, never as done.
+    - **pending** — still running at last check. Record as in-flight; do not describe as complete.
+    - **dispatched** — kicked off, but no result has been observed at all (the letter was handed to the post office — you know it was sent, not whether it arrived).
+    - **unverifiable** — only after genuinely attempting the check above and finding this environment cannot query the target system. State the exact command, URL, or action the operator must run to check it themselves — a bare "unverifiable" with no next step is barely better than silence, and reaching for this state without attempting the check first defeats the purpose of this step as surely as skipping it entirely.
+
+    A commit succeeding, code being pushed, or a build being triggered are all **dispatched**, not **succeeded** — do not write any of them as complete until independently confirmed. Carry every non-succeeded item into the handoff's `Pending Verification` field (step 5b), and into `Last completed step` worded as not-yet-complete (also step 5b).
+
+    Step 10's existing PR-merge check ("Verify through the detected provider that the PR is merged before changing branches") is this same requirement applied to one specific, already-shipped case — the close-session's own PR. Running step 10 does not substitute for step 1b's sweep of everything else dispatched this session, and step 1b does not substitute for step 10's specific merge check; both apply.
+
+2. **Update today's journal file** at `journal/YYYY-MM-DD-topic-slug.md`.
+   - If it exists and already has a session section from this chat, **update that section in place** (do not create a duplicate).
+   - If it exists but has no section for this session, **append** a new `## Session: <title>` section.
+   - If it does not exist, **create** it using the existing journal frontmatter style.
+   - Journal entries must include:
+     - `### Prompt Context` — original prompt text or a faithful paraphrase of the multi-turn request when the session began from a substantive user ask. Include follow-up scope inputs if they materially changed the direction of the work.
+     - `### What Got Done` — numbered list of concrete outcomes with file/ADR references. Only list an outcome here if step 1b classified it `succeeded` (or it never involved async work at all, e.g. a local file edit). A `pending`/`dispatched`/`unverifiable` item belongs in Open Items Carried Forward, not here — do not let this section imply completion step 1b couldn't confirm.
+     - `### Decisions Made` — table of ADR number, decision, and rationale. If no decisions were made, omit this section.
+     - `### Lessons Learned` — one heading per lesson with enough context to prevent the mistake again. Use narrative, not bullet fragments.
+     - `### Open Items Carried Forward` — items that remain undone from this session, including every `pending`/`dispatched`/`failed`/`unverifiable` item from step 1b.
+
+3. **Update [DECISIONS.md](../../DECISIONS.md).**
+   - Add ADRs for any decisions made during the session (naming choices, tool preferences, workflow standards, security policies, etc.).
+   - Use the next sequential ADR number.
+   - Follow the existing format: Date, Status, Context, Decision, Reasoning, Rejected alternatives.
+
+4. **Update [TODO.md](../../TODO.md).**
+   - Mark an item done with date only if step 1b classified its outcome `succeeded` (or it required no async verification at all). A `pending`, `dispatched`, `failed`, or `unverifiable` item stays open, regardless of how confident the session felt about it.
+   - Keep unresolved items open.
+   - Remove completed checklist items only when completion is documented in the correct source-of-truth file.
+
+4b. **Register unfinished, task-bearing work on a durable surface (session handoff durability, ARC-040) before the handoff is written.** Enumerate: an incomplete `Active task`, the `Next concrete action`, and any content that would otherwise live only in `Notes` because it has no other durable home. For each, resolve the sink from `tracking_mode` (per ARC-032): `internal` → the appropriate `TODO.md` (root or venture book); `external` → a work item via the configured `external_provider`, falling back to `TODO.md` when tracker tooling is unavailable this session. Write or update the entry, then carry its location into step 5b so the handoff fields below can name it. Skip this step entirely when nothing is unfinished — a fully clean close has nothing to register.
+
+4c. **Follow-up promotion sweep (LH-09; only when this repo has its own `scripts/check-followups.ts` — Arcane's own repo, or one that adopted the same convention; skip gracefully otherwise).** Run `npm run check:followups` (or the closest journal-scoped equivalent) and check whether this session's own journal entry or closure notes contain a deferral phrase ("filed as a separate", "follow-up", "out of scope", "not fixed here", "left open", "deferred", "revisit", "future work") with no tracker token nearby (`TODO`, `IDEAS`, `Q-NNN`, `ARC-NNN`, `EF-NN`, `RCA-NNN`, a PR URL) and no explicit `(untracked: <reason>)` opt-out. Promote each real hit to `TODO.md`/`IDEAS.md` before writing the handoff, or add the opt-out inline. Report-only tool — a hit is a prompt to check, not proof of an untracked gap; skip anything that's already tracked elsewhere in the same document.
+
+4d. **Record the epic's reader-facing line (only when this session shipped an epic of a tracked program — one with a `docs/plans/<slug>/PLAN.md`; skip entirely otherwise).** Copy the `## For the record` sentence from the epic's own PR description verbatim into that epic's `PLAN.md` entry as its `**Report:**` line, in the format `**Report:** <sentence> · category: <spell|feature|governance|decision|fix|process|docs|platform>`, alongside the PR number the epic ticked with. Authored at PR time (see `spell-create-pull-request` Step 4) and copied here — never re-invented at close, and never substituted with the commit subject, which describes the change to an engineer rather than to the program's reader. **If the PR carried no such section**, leave the line absent rather than writing one from memory: the generator renders a missing description visibly as `unwritten`, and a visible gap someone can fill later is worth more than a plausible sentence nobody verified. Where a completion report is generated (`npm run check:report` / `spell report`), regenerate it after this edit so the committed artifact matches its sources.
+
+5. **Update [ai-context/system-prompt-context.md](../../ai-context/system-prompt-context.md).**
+   - If priorities, environment state, or agent rules changed during the session, update the file to reflect current reality.
+   - If no changes are needed, skip this step.
+
+5b. **Write the Next Session Handoff block.**
+
+In `ai-context/system-prompt-context.md`, replace the existing `## Next Session Handoff` section (or append it if the section is absent) with a freshly generated block. Populate every field from conversation context and current git state:
+
+```markdown
+## Next Session Handoff
+
+> Auto-generated by spell-close-session. Consumed by spell-open-session. Do not edit manually.
+> Generated: YYYY-MM-DD
+
+- **Active task:** One-line description of the task that was in progress when this session closed. If incomplete, name where step 4b registered it (e.g. `path ("the item's own quoted title")` — a stable locator naming the actual file and its bold title, never a bare line number that drifts the moment that file is next edited).
+- **Last completed step:** The final concrete action taken — include file path or command text. If that action was async work step 1b classified as anything other than `succeeded`, do not describe it as done here — name the action in `dispatched`/in-progress terms (e.g. "Pushed the fix and opened PR #NN" is fine; "Merged PR #NN" is not, unless step 1b confirmed the merge) and let `Pending Verification` carry the actual state.
+- **Next concrete action:** The exact first thing to do at next session start. Be specific: file, command, or decision. Never write "continue work." Name where step 4b registered it (e.g. `path ("the item's own quoted title")` — a stable locator naming the actual file and its bold title, never a bare line number that drifts the moment that file is next edited).
+- **Active files:** Files with uncommitted changes or the focus of the last edit (comma-separated).
+- **Branch:** Output of `git branch --show-current`.
+- **Blockers:** Known unresolved blockers or dependencies. Write "None" if clear.
+- **Pending Verification:** One line per non-`succeeded` item from step 1b: `<what> — <state> — <verification action>`. States: `dispatched`, `pending`, `failed`, `unverifiable` (never list a `succeeded` item here — it belongs in `Last completed step` / TODO.md / the journal instead, worded per the gating above). The verification action is required for `dispatched`, `pending`, and `unverifiable` — "N/A" is only valid for `failed`, where the state is already resolved and there is nothing left to check. Write "None" only if step 1b found every dispatched item resolved to `succeeded` or `failed` before this handoff was written.
+- **Notes:** Anything time-sensitive, fragile, or contextual that would be lost if not stated explicitly. Never the sole carrier of durable content (session handoff durability) — if it names unfinished work, that work must also be registered per step 4b; name its location here.
+```
+
+Rules:
+
+- Do not omit any field. Write "N/A" if not applicable.
+- The block header must include the generation date.
+- This section is ephemeral — it will be overwritten by the next close-session and consumed by the next open-session.
+
+6. **Update troubleshooting sections** in affected operational docs.
+   - If problems were encountered and resolved during the session, add troubleshooting entries to the relevant runbook (e.g., `agents/installation.md`, `security/hardening-checklist.md`).
+   - Use the standard format: **Symptom**, **Cause**, **Fix**, **Verify**, **Prevention**.
+   - If screenshots were provided during the session, reference them in troubleshooting or journal entries.
+
+7. **Process screenshots** (if provided during the session).
+   - **First check `content_sensitivity` in `.arcane.json`.** If it is
+     `"sensitive"`, retain no screenshots of repository contents and transcribe
+     nothing from them into the journal — record the document path instead. See
+     universal-agent-rules.md, "Sensitive Repositories".
+   - Screenshots should already be saved to `assets/screenshots/YYYY-MM-DD/` — agents must save them immediately when the user pastes them (see global screenshot rule in `copilot-instructions.md`).
+   - At close-session time, review all screenshots saved during the session.
+   - Keep only screenshots that provide durable evidence for journal/runbook documentation.
+   - Delete duplicates, low-signal images, and any screenshot containing sensitive data (secrets, tokens, PII).
+   - Ensure every kept screenshot is referenced in at least one doc (journal entry or troubleshooting section).
+   - For journal files under `journal/`, reference via: `![description](../assets/screenshots/YYYY-MM-DD/filename.png)`.
+   - Reference in troubleshooting docs with context captions.
+
+8. **Flag documentation drift** discovered while closing the session — stale dates, outdated priorities, contradictions between docs.
+
+9. **Stage and commit session-close docs.**
+
+   **Remote-capability check:** classify the state created by `spell-open-session` before branching, staging, push, or PR operations. Check for **not a repository at all** first — every other classification assumes a `.git` directory exists.
+   - **Not a Git repository (EF-05):** `git rev-parse --is-inside-work-tree` fails. Do not attempt any git operation (branch, add, commit, push). Fail closed with: `No Git repository detected. Run \`git init -b main\` first (explicit -b avoids landing on "master" on systems where that's the init.defaultBranch default), then re-run spell-close-session.` This mirrors `spell init`'s own next-steps guidance for the same state.
+   - **Usable supported remote/merge path:** requires an authenticated supported provider (`github.com`, `dev.azure.com`, or `visualstudio.com`). Keep the current compliant session/PR/worktree branch, resolve the actual remote name and integration branch, and use the provider-neutral PR path below.
+   - **No usable remote/merge path:** remain on the current trunk. Do not create a dead session branch, push, pull, or open a PR. Apply the EF-28 interactive commit approval gate, commit locally on trunk after approval, report `Local-only close: committed on <trunk>; no remote PR/pull performed`, and skip steps 9a, 9c, and 10's remote operations.
+   - **Read-only session:** if no repository mutation occurred, do not create a branch or commit.
+
+   a. **Branch check — create a topic branch before any staging:**
+   This remote branch path applies only when the remote-capability check found a usable merge path.
+   Run `git branch --show-current`. If you are on the resolved integration branch `<trunk>`, create a topic branch **now** before any `git add`:
+
+   ```powershell
+   git checkout -b docs/session-close-YYYY-MM-DD
+   ```
+
+   Never commit directly to a remotely protected integration branch — the branch policy rejects direct pushes. If a session branch already exists (created by `spell-open-session`), stay on it.
+
+   b. **Stage and apply the interactive commit gate from `spell-commit-work`:**
+   - Run `git add -A && git diff --stat --cached` to show what changed.
+   - Auto-generate a conventional commit message summarizing the session closure (e.g., `docs(journal): close session — <topic>`).
+   - Treat session close as `interaction_context: interactive` unless independently dispatched with validated autonomous authority.
+   - Bind structured operator approval to the exact staged diff and proposed message fingerprint. Recompute before commit; any change invalidates approval.
+   - Timeout, cancellation, fallback, or delegated response is not approval. Print the visible authorization downgrade and halt without committing.
+
+   c. **Push and open a PR through `spell-commit-work` step 9, including its separate merge gate:**
+   - Commit approval is not merge approval.
+   - Never invoke merge, auto-complete, or `--status completed` below loader-validated Magus authority.
+   - Missing/invalid authority visibly downgrades to PR creation only and requires human completion.
+   - Interactive Magus+ completion still requires separate authenticated approval tied to the exact PR ID and head SHA.
+
+10. **Synchronize the configured integration branch after the PR merges (remote path only):**
+   - Skip this entire step for local-only and read-only sessions.
+   - Resolve `<remote>` and `<trunk>` from observed Git/provider state: use the usable authenticated remote selected in step 9 and the merged PR's target branch (falling back to that remote's default branch). Never assume `origin` or `main`.
+   - Verify through the detected provider that the PR is merged before changing branches.
+   - **Determine the isolation primitive first (ARC-028 R8).** Run both of these and compare:
+     ```bash
+     git rev-parse --path-format=absolute --git-common-dir
+     git rev-parse --path-format=absolute --git-dir
+     ```
+     Equal → **primary checkout**. Different → **linked worktree**, and the two paths below diverge. `spell-open-session` should already have named the primitive; re-derive it here rather than trusting the handoff, because the session may have moved.
+
+     **`--path-format=absolute` is required, not decorative.** Without it, `--git-dir` returns an absolute path while `--git-common-dir` stays relative whenever the current directory is *below* the repository root — so a plain comparison reports the primary checkout as a linked worktree from any subdirectory, which is most of the time. If your git predates `--path-format` (2.31), use `git rev-parse --git-dir` and test whether the result contains `/worktrees/` instead.
+
+   **Primary checkout (the default path):**
+   - Run `git switch <trunk>` followed by `git pull --ff-only <remote> <trunk>`. Do not end a remote-backed session on a topic branch.
+   - Delete the local topic branch: `git branch -d <branch>` — if the repository or its linked worktrees might be reached through more than one filesystem view, run the same-vantage-point check first (EF-33 / ARC-028 R7, [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) Same-Vantage-Point Check section).
+   - Verify `git log --oneline -3` shows the merged change at HEAD.
+
+   **Linked worktree:**
+   - First establish whether any working tree currently holds `<trunk>`: run `git worktree list` and look for `[<trunk>]`. That, not the mere fact of being in a worktree, is what determines the two rules below — a **bare** repository with worktrees attached (a common agent-fleet layout: one bare clone, one worktree per agent) usually has no checkout holding `<trunk>` at all, and there `git switch <trunk>` and `git branch -d` both succeed normally. Verified: they do.
+   - **If a working tree holds `<trunk>`, do not run `git switch <trunk>`.** It will fail — Git refuses to check out one branch in two worktrees (`fatal: '<trunk>' is already used by worktree at '<path>'`). Ending on the session branch is correct here, not a lapse; the branch is already merged and the worktree is about to be removed.
+   - **Do not run `git branch -d <branch>` while this worktree is attached to it.** It will fail (`error: cannot delete branch '<branch>' used by worktree at '<path>'`), from inside the worktree and from the primary alike. Both refusals are the guardrail ARC-028 R3/R7 leans on, not an obstacle to work around — never reach for `-D`, `--force`, or manual deletion of `.git/worktrees/<name>` to get past them. (`-D` does not bypass this either; the refusal is about attachment, not about merge state.)
+   - Report the worktree path and the branch name, and name **where** removal must happen: `git worktree remove <path>` then `git fetch --prune <remote>`, run after the same-vantage-point check from a checkout that is not this one. A worktree cannot safely remove itself. If `git worktree list` shows a working tree holding `<trunk>`, that is the vantage point; if the repository is **bare**, run it from the bare repository itself (`git -C <bare> worktree remove <path>`) — do not report the work as belonging to a "primary checkout" that does not exist.
+   - If this worktree was created with `--detach` there is no branch to name; report the path and the detached HEAD sha instead.
+   - Verify the merge landed with `git log --oneline -3 <remote>/<trunk>` (the remote-tracking ref), since local `<trunk>` is not checked out here to fast-forward.
+
+   - **Common to both: run the idempotent, content-verified branch sweep** (TODO.md's merged-branch-cleanup finding) — not merely a list-and-suggest step. For every local branch except `<trunk>` and any branch attached to another worktree, apply [Content-Verified Branch Deletion](../../.arcane/governance/git-conventions.md#content-verified-branch-deletion-todomd-merged-branch-cleanup-finding) (git-conventions.md): fetch first, prefer a confirmed PR-merged status when one exists, otherwise verify by `git cherry` patch-id equivalence *and* a resulting-content check for `+`-flagged commits (a squash or independently re-authored commit can carry already-landed content under a different patch-id). Actually delete (`-D`, never `-d`) every branch that verifies as fully landed, local and remote. Report — do not delete — any branch with genuine unmerged content; a one-line summary of what it holds is enough for a human to decide land vs. abandon. Apply the Same-Vantage-Point Check (EF-33) before any deletion if the repository or its linked worktrees might be reached through more than one filesystem view. Safe to run every session: an already-clean branch list is simply a no-op.
+   - See [governance/git-conventions.md](../../.arcane/governance/git-conventions.md) Post-Merge Cleanup section.
+
+11. **Return a concise closure report.**
+
+Output format:
+
+## Session Closure
+
+- Summary of what was completed.
+- **Session commit graph** — per the generated state diagrams convention (rule 8, ARC-036), built only
+  from commits this session actually made (`git log <trunk>..HEAD --format="%h %s" --reverse`, or
+  `<remote>/<trunk>..HEAD` once pushed) plus step 1b's succeeded/pending/failed classification per
+  commit. Skip entirely (the applicability guard) for a read-only session or a single-commit session —
+  one point has nothing to sequence. Deliberately `gitGraph`, the same already-verified diagram type
+  R1–R9 use, not Mermaid's `timeline` diagram — that type is marked experimental in Mermaid's own docs,
+  a real compatibility risk across GitHub/VS Code/Obsidian this convention explicitly commits to
+  supporting; a session's own commit sequence is exactly what `gitGraph` already represents:
+
+  ```mermaid
+  gitGraph
+     commit id: "<short-sha 1> succeeded"
+     commit id: "<short-sha 2> pending"
+  ```
+
+  One commit per session commit, in order, `id` carrying its short SHA and step 1b's classification —
+  never claim `succeeded` for anything step 1b did not confirm as such.
+
+## Journal Updates
+
+- Exact file updates made.
+
+## Decision Updates
+
+- ADRs added or note that none were needed.
+
+## TODO Updates
+
+- Exact checklist changes made.
+
+## Drift and Fixes
+
+- Documentation drift found and corrected, or "None."
+
+## Screenshots
+
+- Screenshots saved to `assets/screenshots/YYYY-MM-DD/` with references added to journal/docs, or "None provided."
+
+## PR Readiness
+
+Enumerate the current end state and the prescribed next action. Use this table to classify where the session landed within the provider-neutral lifecycle above:
+
+| End state | Next action |
+| --- | --- |
+| Local-only trunk, changes committed | Session is integrated locally; no branch or PR cleanup required. |
+| Read-only session, no changes | No branch or commit required. |
+| Open PR exists | Docs/changes reach `main` when it merges — show the PR URL. |
+| No PR + docs-only on a branch | Run `spell-create-pull-request --docs-only`. |
+| No PR + mixed code+docs on a branch | Run `spell-create-pull-request` once the feature is complete. |
+| Docs-only commit on remote-backed `<trunk>` | Create a `chore/docs` branch, then run `spell-create-pull-request --docs-only`. |
+| Nothing ahead of `<remote>/<trunk>` | Branch is fully merged — clean up local/remote branches. |
+
+## Carry Forward
+
+- 3 to 5 concrete next actions.
+
+## What's Next?
+
+Route the user to the right next spell based on the end state:
+
+- **Docs-only commit on remote-backed `<trunk>`** — create a docs branch, then run `spell-create-pull-request --docs-only`.
+- **On a feature branch, ready for review** — run `spell-create-pull-request`.
+- **On a feature branch, still in progress** — next session, run `spell-open-session` to resume.
+- **PR already open** — run `spell-address-review` after reviewers comment.
+
+Rules:
+
+- Do not invent completions — only mark items done if verifiable from context. "Verifiable" means classified `succeeded` under step 1b's five-state vocabulary (`dispatched`/`pending`/`succeeded`/`failed`/`unverifiable`), not merely "I can see it was started" (EF-21).
+- `Notes` is a pointer, never the sole carrier of durable content (session handoff durability) — if something needs to survive to next session, it must also live wherever step 4b registers it, not only in prose here.
+- Keep frontmatter date values in `YYYY-MM-DD`.
+- Preserve existing checklist and journal style.
+- Keep edits minimal and factual.
+- Never include secrets, API keys, or tokens in any document.
+- If a journal entry for this session already exists (same date, same topic), update it rather than creating a duplicate.