arcane-cli 0.14.0

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

@@ -0,0 +1,73 @@
+---
+name: Spell — Bump Version
+description: Determine the correct semver bump type for the current change and apply it to package.json
+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 CLAUDE.md: "Version bump required for any change to `src/assets/`."
+
+---
+
+Determine the correct semver bump and apply it.
+
+## Step 1 — Check whether a bump is needed
+
+Run the version check gate:
+
+```
+npm run check:version-bump
+```
+
+- If it **passes** → no bump needed. Stop here and report "No version bump required."
+- If it **fails** → proceed to Step 2.
+
+## 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/.github/prompts/spell-check-drift.prompt.md

@@ -0,0 +1,97 @@
+---
+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).
+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](../../agents/agent-policies.md)
+- Most recent journal file(s) in [journal/](../../journal/)
+- Relevant business overviews under [ventures/](../../ventures/)
+
+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).
+
+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 `file:line` — or the nearest locator such as a heading or section — wherever a specific location applies)
+- Affected file (cite `file:line` — or the nearest locator — wherever a specific location applies)
+- Exact recommended fix
+
+Every finding that points to a specific location MUST be pinpointable: cite `file:line` (or a line range, e.g. `TODO.md:42-45`). If no precise line 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.
+- **Findings:** total count, broken down per severity.
+
+## Drift Findings
+
+- One line per finding with `file:line` references (or nearest locator) and its severity rationale.
+
+## 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.
+- Keep changes minimal and traceable.

package/dist/assets/.github/prompts/spell-close-session.prompt.md

@@ -0,0 +1,189 @@
+---
+name: Spell — Close Session
+description: End a work session by logging outcomes in today's journal and pruning completed TODO items with verifiable evidence.
+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 reusable explanation), suggest running `spell-document` before closing so it lands in the right doc. For quick ideas worth keeping but not yet actionable, suggest `spell-save-idea`.
+
+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.
+     - `### 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.
+
+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 verifiably completed items as done with date.
+   - Keep unresolved items open.
+   - Remove completed checklist items only when completion is documented in the correct source-of-truth file.
+
+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.
+- **Last completed step:** The final concrete action taken — include file path or command text.
+- **Next concrete action:** The exact first thing to do at next session start. Be specific: file, command, or decision. Never write "continue work."
+- **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.
+- **Notes:** Anything time-sensitive, fragile, or contextual that would be lost if not stated explicitly.
+```
+
+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).
+   - 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.**
+
+   a. **Branch check — create a topic branch before any staging:**
+   Run `git branch --show-current`. If you are on `main`, create a topic branch **now** before any `git add`:
+
+   ```powershell
+   git checkout -b docs/session-close-YYYY-MM-DD
+   ```
+
+   Never commit directly to `main` — the branch policy rejects direct pushes. If a session branch already exists (created by `spell-open-session`), stay on it.
+
+   b. **Stage and commit immediately** — no approval wait (consistent with `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>`).
+   - Run `git commit` immediately once the message is determined. Do not pause for confirmation.
+
+   c. **Push and open a PR** — follow the full ADO PR lifecycle from `spell-commit-work` step 9:
+   `az repos pr create` → `Invoke-RestMethod` approval → `az repos pr update --status completed` → branch delete.
+   See [governance/git-conventions.md](../../governance/git-conventions.md) ADO PR Lifecycle section.
+
+10. **Return to main after the PR merges:**
+    - Run `git checkout main && git pull origin main`. Do not end the session on a topic branch.
+    - Delete the local topic branch: `git branch -d <branch>`.
+    - Verify `git log --oneline -3` shows the merge commit at HEAD.
+    - If stale local branches exist (merged or older than 7 days), list them and suggest cleanup.
+    - See [governance/git-conventions.md](../../governance/git-conventions.md) Post-Merge Cleanup section.
+
+11. **Return a concise closure report.**
+
+Output format:
+
+## Session Closure
+
+- Summary of what was completed.
+
+## 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 (added clarity on top of the ADO PR lifecycle steps above — not a replacement for them):
+
+| End state | Next action |
+| --- | --- |
+| 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 `main` | Create a `chore/docs` branch, then run `spell-create-pull-request --docs-only`. |
+| Nothing ahead of `origin/main` | 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 `main`** — 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.
+- 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.

package/dist/assets/.github/prompts/spell-commit-work.prompt.md

@@ -0,0 +1,211 @@
+---
+name: Spell — Commit Work
+description: Generate Conventional Commits message with agent attribution and commit current work during an active session
+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](../../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.
+   - **Protected-branch guard:** if the current branch is `main` or `master`, **STOP — do not stage or commit directly.** Tell the user that committing straight to the integration branch is not allowed, and instruct them to create a topic branch first (e.g., `sessions/YYYY-MM-DD-<slug>` per the session model). Once on a valid topic branch, continue the workflow normally (commit immediately as usual).
+
+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.
+
+   - **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. **Analyze changes** — 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:** if the staged 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 the 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.
+
+4. **Determine authorship** — who produced this content? See [governance/git-conventions.md](../../governance/git-conventions.md) Agent Attribution Model section and ADR-028.
+   - **Human wrote it:** no `--author` override needed (uses global Git config)
+   - **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 in doubt, ask the user who produced the content.
+
+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` — .github/prompts/ files
+   - `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` — ventures/ directory
+   - `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: [lowercase-persona or tool name]
+   Model: [model identifier, e.g., claude-opus-4-20250918]
+   Provider: [anthropic or openai]
+   Role: [agent role slug, if applicable]
+   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`, `Provider`
+   - Human-authored commits: trailers are optional
+
+8. **Execute commit immediately** once message and attribution are determined:
+   - Run `git add -A` (or selective `git add` if user specifies files)
+   - Run `git commit --author="..." --trailer="..." -m "message"` with all flags
+   - Confirm success and show the resulting commit hash
+
+9. **Push branch and run platform-specific PR flow:**
+
+   a. Run `git push origin <branch>`.
+
+   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 using **merge commit (no-fast-forward)** or **rebase+fast-forward** only. 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.
+   - 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.
+
+   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>`.
+- 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](../../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})
+
+**Next:** Continue work or run `spell-close-session` to finalize journal and session docs.