arcane-cli 0.22.4 → 0.22.5

package/dist/assets/.arcane/governance/git-conventions.md

@@ -567,13 +567,15 @@ See also: [Agent Workflow — Sync with main before opening a PR](#agent-workflo
 | **Description**    | Must include: summary of changes, rationale, verification steps, and a linked work item ID if applicable                                                                                                                                     |
 | **Pre-PR sync**    | **Mandatory rebase on latest `origin/<target>` before pushing.** See [🛑 Agent-mandatory pre-PR guard](#-agent-mandatory-pre-pr-guard) above — this applies even when opening PRs via raw `az repos pr create` / `gh pr create` / MCP tools. |
 | **Branch cleanup** | After merge, delete the source branch (local and remote).                                                                                                                                                                                    |
-| **PR link format** | All PR references in agent output should be clickable markdown links to the PR, not a bare `PR #NNN`.                                                                                                                                        |
+| **PR link format** | All PR references in agent output **must** be clickable markdown links to the PR, not a bare `PR #NNN`.                                                                                                                                     |
+| **Doc-ID link format** | The same rule extends to `ADR-NNN`/`ARC-NNN`/`EF-NN`/journal entries/named governance docs — never a bare ID. See `.github/instructions/agent-output.instructions.md` → Doc-ID Link Format for the full rule and required formats per context. |
 
 ### Agent PR Workflow
 
 1. **Create a work item** (if one doesn't exist) using `spell-suggest-feature` or `spell-bug`.
 2. **Open PR** with proper title, description, and work-item link.
-3. **Notify the human** through your configured channel with: `[PR #{number}] {repo} — {title} (#{workItemId})`.
+3. **Notify the human** through your configured channel with a clickable link, not a bare number:
+   `[PR #{number} — {title}]({url}) — {repo} (#{workItemId})`.
 4. **Address review feedback** if a reviewer requests changes.
 5. **After merge**, delete the branch (local + remote) and confirm cleanup.
 

package/dist/assets/.arcane/governance/new-business-setup.md

@@ -113,12 +113,12 @@ See [[agents/installation|Runtime Installation]].
 
 ### Step 3.3 — Agent Git Identity Setup
 
-Every agent that will produce commits for this business must have a registered Git identity **before making its first commit**. See [[governance/git-conventions#agent-attribution-model|Git Conventions — Agent Attribution]].
+Every agent that will produce commits for this business must have a registered Git identity **before making its first commit**. See [[git-conventions#agent-attribution-model|Git Conventions — Agent Attribution]].
 
 For each agent assigned to this business:
 
 1. **Confirm persona name** is registered in [[naming-conventions|Naming Conventions]] agent roster.
-2. **Confirm Git identity** exists in the registered identities table in [[governance/git-conventions#agent-email-convention|Git Conventions]].
+2. **Confirm Git identity** exists in the registered identities table in [[git-conventions#agent-email-convention|Git Conventions]].
 3. **Add agent to `.mailmap`** in every repo the agent will commit to:
    ```
    {AGENT_NAME} <{AGENT_EMAIL}>

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

@@ -15,7 +15,13 @@ against a consistent bar. This is the spell-prompt analogue of [[product-excelle
 grades PRDs, not prompts). It is an **authoring-time standard** — a checklist for contributors writing
 or reviewing spells. It is **not** meant to be read at runtime by the spells it grades.
 
-See [ARC-014](../../../DECISIONS.md#arc-014) for the decision that established this standard.
+See [ARC-014](https://github.com/codemagicianhq/arcane/blob/main/DECISIONS.md#arc-014--spell-authoring-standards-a-quality-rubric-for-spell-prompts)
+for the decision that established this standard. **Full canonical URL, not a same-repo
+wiki-link** (corrected 2026-08-31, BC-06) — this file ships to consumer repos, and
+`DECISIONS.md` does not: `src/assets/DECISIONS.md` (what consumers actually receive via
+`spell init`) is an empty starter template for the *consumer's own* decisions, so a
+same-repo wiki-link to a specific ARC id would resolve to the wrong document once
+installed, not simply fail to resolve.
 
 ## The Spell Quality Rubric
 

package/dist/assets/.github/instructions/agent-output.instructions.md

@@ -4,7 +4,7 @@ applyTo: "**"
 
 # Agent Output Formatting Rules
 
-Source of truth: `.arcane/governance/git-conventions.md` → PR Standards section.
+Source of truth: `.arcane/governance/git-conventions.md` → PR Standards → PR Requirements.
 
 ## PR Link Format
 
@@ -20,9 +20,60 @@ All PR references in agent output **must** be clickable markdown links. Never wr
 [PR #270 — fix: remove Unix-only preinstall script and approve esbuild builds](https://dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/270)
 ```
 
+## Doc-ID Link Format
+
+The same rule extends to every other identifier class this framework uses to reference
+a decision or record: `ADR-NNN`, `ARC-NNN`, `EF-NN`, venture decision IDs, journal
+entries, and named governance docs. A bare decision ID in agent output is the same
+defect as a bare `PR #NNN` — the reader has to go find it themselves, and a typo or
+stale number is invisible until someone tries.
+
+**Required format, by context:**
+- **Inside a repo's own local markdown** (e.g. this repo's `journal/`, `PLAN.md`, or
+  `DECISIONS.md` cross-referencing itself): a wiki-link (`[[DECISIONS#ARC-NNN|ARC-NNN]]`)
+  or a relative markdown link that actually resolves from that file's own location.
+- **Chat or PR output:** a clickable markdown link to the canonical file/anchor.
+- **Governance docs this framework ships** (`.arcane/governance/*.md`): the full
+  canonical-repo URL. A file here lives in *this* repo today but ships into every
+  consumer repo's own tree, where a wiki-link or relative path to Arcane's own
+  `DECISIONS.md` either fails to resolve, or worse, silently resolves to the
+  *consumer's own* `DECISIONS.md` (an empty per-consumer starter template, not
+  Arcane's real decision record) — wrong content, not just a dead link.
+- **Spell prompts and instructions this framework ships**
+  (`.github/prompts/*.prompt.md`, `.github/instructions/*.md`): **plain text only —
+  cite the bare ID, no link at all** (`ARC-035`, not `[ARC-035](...)`). A full
+  canonical URL is *also* unsafe here, not just a same-repo link: it bakes
+  `github.com/codemagicianhq/arcane` — this project's own org and repo name — into
+  content the org-token portability gate (`scripts/org-token-lint.ts`, D2 in
+  `spell-authoring-standards.md`) exists specifically to keep out of distributed
+  spells. **Confirmed live 2026-08-31 (BC-06):** the build's `Org-token lint` failed
+  on exactly this pattern in three prompt files, including two this same correction
+  pass had introduced minutes earlier while fixing the *other* link defect. Known
+  gap: the portability scan today only walks `.github/prompts/`, so a full URL in a
+  `.github/instructions/*.md` file — like this one's own Merge Strategy section, two
+  paragraphs down — ships uncaught; tracked in `TODO.md`.
+- **Cross-repo references from anywhere else** (chat, PR output, another repo
+  entirely): the full canonical-repo URL.
+
+**Never fabricate an unresolvable link.** If you cannot confirm the ID exists and where
+it resolves to, say so and cite the ID as plain text rather than inventing a link that
+looks real but goes nowhere.
+
 ## Merge Strategy
 
-All PRs must use **Rebase and fast-forward**. Never squash. Never merge commit. See ADR-048.
+All PRs must use **Rebase and fast-forward**. Never squash. Never merge commit. See
+ARC-009 §7 (Arcane's own framework decision — cited as plain text, not linked, per
+Doc-ID Link Format above: this file ships). **Corrected 2026-08-31 (BC-06), three
+times over:** this file previously cited `ADR-048`, which does exist in the shipped
+`framework-decisions.md` reference — but its actual topic ("Code Versus Docs Branch
+Policy") has nothing to do with merge strategy, a topical miscitation rather than a
+missing one. The first fix replaced it with a same-repo wiki-link to this repo's own
+`DECISIONS.md` — itself the exact cross-repo defect this section warns about
+(`DECISIONS.md` doesn't ship). The second fix replaced that with a full canonical
+URL, which held up locally but failed the build's org-token portability gate: a
+`github.com/codemagicianhq/arcane` URL bakes this project's own org into a file the
+gate treats as distributed content (see Doc-ID Link Format above). Settled on the
+bare ID — the gate's own documented safe form.
 
 When completing a PR via `az repos pr update`, do **not** pass `--squash true`. The correct command:
 

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

@@ -9,7 +9,10 @@ agent: agent
 
 - 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/`."
+- 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:56-58`.)
 
 ---
 

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

@@ -51,7 +51,7 @@ For each PR in the batch, independently:
 1. Fetch the PR diff and metadata (`gh pr diff <n>` / `az repos pr show --id <n>` + diff). If a PR can't be fetched (deleted, no access, network error), **skip it, record it as `SKIPPED` with the reason, and continue** — never abort the whole batch for one bad PR.
 2. Run the `spell-review` workflow against that diff — the full dimension-coverage sweep (correctness, security, performance, tests, naming/clarity, architecture), severity-ranked findings (`HIGH` / `MEDIUM` / `LOW`, matching the `spell-review` ladder) with stable IDs, and the PASS/WARN/FAIL coverage table.
 3. Record a per-PR result: verdict (**approve** / **request-changes**), finding counts by severity, and the coverage table.
-4. **Post the formal round state per PR** — apply `spell-review`'s step 10 ([ARC-035](../../DECISIONS.md#arc-035--auto-merge-requires-a-clear-review-round) decision 3) to *this* PR's number, not just this workflow's own single-run PR: a **request-changes** verdict posts `gh pr review <n> --request-changes` (or `az repos pr set-vote --id <n> --vote reject`); a re-review that clears a round this batch previously blocked dismisses/supersedes that prior review. An **approve** verdict posts nothing. Never let a posting failure (unauthenticated CLI, PR closed mid-batch) skip or abort the remaining PRs in the batch — record the result already computed and continue.
+4. **Post the formal round state per PR** — apply `spell-review`'s step 10 (ARC-035 decision 3 — cited as plain text, not linked; see `agent-output.instructions.md` → Doc-ID Link Format) to *this* PR's number, not just this workflow's own single-run PR: a **request-changes** verdict posts `gh pr review <n> --request-changes` (or `az repos pr set-vote --id <n> --vote reject`); a re-review that clears a round this batch previously blocked dismisses/supersedes that prior review. An **approve** verdict posts nothing. Never let a posting failure (unauthenticated CLI, PR closed mid-batch) skip or abort the remaining PRs in the batch — record the result already computed and continue.
 
 Reviews are adversarial — actively look for problems, do not just confirm quality. Apply the same no-fabrication coverage mandate as `spell-review`: a clean lens is reported as "no issues," never padded.
 
@@ -68,11 +68,11 @@ Build one report:
 
 | PR | Repo | Title | Verdict | High | Med | Low |
 | -- | ---- | ----- | ------- | ---- | --- | --- |
-| #n | repo | …     | approve / request-changes | 0 | 1 | 2 |
-| #n | repo | …     | SKIPPED — {reason}        | —  | —  | —  |
+| [#n]({url}) | repo | …     | approve / request-changes | 0 | 1 | 2 |
+| [#n]({url}) | repo | …     | SKIPPED — {reason}        | —  | —  | —  |
 
 ## Per-PR detail
-### PR #n — {title}
+### [PR #n]({url}) — {title}
 - Verdict: …
 - Coverage: {PASS/WARN/FAIL per lens}
 - Findings: {R1 …}

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

@@ -122,7 +122,7 @@ Workflow:
 
 9. **Write back to the pull request** — when a PR exists for these changes, sync a short verdict plus a findings summary (verdict + finding counts/IDs + a pointer to the saved report) into the PR body/description. Use provider-agnostic phrasing that works for either GitHub or Azure DevOps. Mark it clearly as a snapshot at review time, and fall back to a top-level PR comment if the description can't be updated.
 
-10. **Post the formal round state** ([ARC-035](../../DECISIONS.md#arc-035--auto-merge-requires-a-clear-review-round) decision 3) — step 9's write-back is a human-readable summary; this is the separate, machine-readable signal the `Review round clear` required check actually reads. Only a confirmed blocker posts a formal review — an `APPROVE` or `DEFER` verdict posts nothing here, preserving the zero-friction path for PRs nobody formally blocks:
+10. **Post the formal round state** (ARC-035 decision 3 — Arcane's own framework decision, cited as plain text, not linked, since this file ships; see `agent-output.instructions.md` → Doc-ID Link Format) — step 9's write-back is a human-readable summary; this is the separate, machine-readable signal the `Review round clear` required check actually reads. Only a confirmed blocker posts a formal review — an `APPROVE` or `DEFER` verdict posts nothing here, preserving the zero-friction path for PRs nobody formally blocks:
     - **REQUEST CHANGES verdict:**
       - GitHub: `gh pr review <n> --request-changes --body "<one-line blocker summary + pointer to the saved report>"`.
       - Azure DevOps: `az repos pr set-vote --id <n> --vote reject` — the same primitive `spell-commit-work.prompt.md`'s author-side self-approval step already uses (`az repos pr set-vote --vote approve`), applied to the reviewer side.

package/dist/assets/.github/prompts/spell-summon-venture.prompt.md

@@ -11,7 +11,7 @@ agent: agent
 - **Hub-gated:** requires `role: "hub"` in `.arcane.json`. Refuses cleanly in a consumer repo, pointing at the right place to capture the idea instead.
 - Use this when starting a new venture (business, product, or personal project) that the hub should track.
 - Input format is: `Venture Name | Venture Type | Description` — prompt will ask for missing fields.
-- Renamed from `spell-bootstrap-business` — venture books and the registry didn't exist when that spell was named. Clean rename, no compatibility alias, per [[DECISIONS#ARC-008|ARC-008]]'s precedent.
+- Renamed from `spell-bootstrap-business` — venture books and the registry didn't exist when that spell was named. Clean rename, no compatibility alias, per ARC-008's precedent (cited as plain text, not linked — this file ships; see `agent-output.instructions.md` → Doc-ID Link Format).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-cli",
-  "version": "0.22.4",
+  "version": "0.22.5",
   "description": "Arcane framework CLI — scaffold and manage governance files in consuming repositories",
   "keywords": [
     "arcane",