arcane-cli 0.28.1 → 0.29.1

package/README.md

@@ -120,10 +120,10 @@ Arcane isn't a prompt snippet — it's a full framework. Everything installs int
 
 <!-- arcane:start -->
 <details>
-<summary><b>📜 The full spell catalogue (40)</b></summary>
+<summary><b>📜 The full spell catalogue (41)</b></summary>
 
 **Session** — `open-session` · `close-session` · `commit-work` · `status` · `arcane-version`
-**Capture** — `save-idea` · `todo` · `feedback` · `suggest-feature` · `document` · `brainstorm` · `explain-concept`
+**Capture** — `save-idea` · `todo` · `feedback` · `suggest-feature` · `document` · `verification-ledger` · `brainstorm` · `explain-concept`
 **Delivery** — `create-pull-request` · `sync-pull-request` · `address-review`
 **Review** — `review` · `review-batch`
 **Planning** — `plan` · `architect` · `scope` · `product-review`

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

@@ -638,19 +638,25 @@ New agents are registered during onboarding.
 
 Agent-authored commits MUST include trailers in the commit message footer. Human commits MAY include them.
 
-| Trailer        | Required    | Example                                |
-| -------------- | ----------- | -------------------------------------- |
-| `Agent`        | Yes         | `kellar`, `copilot`, `claude`          |
-| `Model`        | Yes         | `claude-opus-4-20250918`, `gpt-4o`     |
-| `Provider`     | Yes         | `anthropic`, `openai`                  |
-| `Role`         | Recommended | `product-ops`, `developer`, `cto`      |
-| `Task-Type`    | Optional    | `docs`, `code`, `review`, `marketing`  |
-| `Approval`     | Optional    | `interactive`, `batch`, `post-review`  |
-| `Channel`      | Optional    | `chat`, `cli`, `editor`                |
-| `Risk-Class`   | Optional    | `low`, `medium`, `high`                |
-| `Request-ID`   | Optional    | `req-001`                              |
-| `Session`      | Optional    | `session-01`                           |
-| `Rollback-Ref` | Optional    | path or commit to the pre-change state |
+**`Agent` is the runtime/tool only — never a persona name.** The prior single-field model let `kellar` (a persona) and `copilot`/`claude` (runtimes) sit in the same field's example list, which is exactly the conflation this split removes. `Persona` and `Role` are conditional on a roster (`.arcane/agents.yaml`) existing and one having been assigned — omit both, do not guess, when no roster exists or none was assigned this session (this repo's own root has no roster today; the "Solo-Operator Delegation Records (No Roster)" pattern in [[agent-policies#solo-operator-delegation-records-no-roster|agent-policies.md]] is the same "mechanism doesn't apply, degrade gracefully" shape applied to delegation instead of attribution).
+
+| Trailer        | Required    | Example                               | Notes |
+| -------------- | ----------- | -------------------------------------- | ----- |
+| `Agent`        | Yes         | `claude`, `copilot`, `codex`          | The runtime that executed — always resolvable from the tool itself. |
+| `Persona`      | Conditional | `kellar`, `merlin`                    | The roster identity operated as. Present only when a roster exists and one was assigned; omit entirely otherwise — never guess. |
+| `Role`         | Conditional | `CTO / Architecture Lead`             | Derived **only** from `Persona`'s roster entry (`AgentDefinition.role`, reached via the roster entry's `definition` pointer — see `agent-loader.ts`), never typed by hand. Present only when `Persona` is present; a `Role` value not sourced from the actual roster file is a defect, not a stylistic choice — see the grading-probe example below. |
+| `Model`        | Yes         | `claude-opus-4-20250918`, `gpt-4o`    | Self-reported by the runtime. |
+| `Model-Source` | Yes         | `self-reported`                       | Marks that `Model` (and `Agent`) is self-reported, not independently verified — currently the only defined value. Exists because a fabricated `Model`/author trailer once survived eight PRs and human review undetected; the field makes that limitation visible instead of silently trusted. |
+| `Provider`     | Yes         | `anthropic`, `openai`                 | |
+| `Task-Type`    | Optional    | `docs`, `code`, `review`, `marketing`  | |
+| `Approval`     | Optional    | `interactive`, `batch`, `post-review`  | |
+| `Channel`      | Optional    | `chat`, `cli`, `editor`                | |
+| `Risk-Class`   | Optional    | `low`, `medium`, `high`                | |
+| `Request-ID`   | Optional    | `req-001`                              | |
+| `Session`      | Optional    | `session-01`                           | |
+| `Rollback-Ref` | Optional    | path or commit to the pre-change state | |
+
+**Grading probe for whether a session actually inherited this rule** (not a hypothetical — this exact question surfaced a real gap before this split existed): *"What does `Role: developer` in a commit trailer resolve from?"* The wrong answer is "the agent roster" stated with confidence. The correct behavior is to check — read `.arcane/agents.yaml` if it exists, resolve the acting persona's `AgentDefinition.role` — and if no roster exists or the value can't be traced to a real entry, omit the `Role` trailer rather than typing a plausible-sounding guess.
 
 ### Vendored Framework Trailers
 
@@ -665,14 +671,30 @@ Never type or infer `Vendor-Version`. If the installed CLI cannot be resolved pr
 
 ### Complete Examples
 
-**Agent-authored commit ({AGENT_NAME}):**
+**Agent-authored commit, with an assigned roster persona ({AGENT_NAME}):**
 
 ```bash
 git commit --author="{AGENT_NAME} <{AGENT_EMAIL}>" \
-  --trailer="Agent=kellar" \
+  --trailer="Agent=claude" \
+  --trailer="Persona=kellar" \
+  --trailer="Role=Product Operations Manager" \
   --trailer="Model=<model-id>" \
+  --trailer="Model-Source=self-reported" \
+  --trailer="Provider=<provider>" \
+  --trailer="Channel=chat" \
+  -m "feat(inventory): generate initial product catalog
+
+Created 47 SKUs from the inventory spreadsheet."
+```
+
+**Agent-authored commit, no roster installed (this repo's own current state):**
+
+```bash
+git commit --author="{AGENT_NAME} <{AGENT_EMAIL}>" \
+  --trailer="Agent=claude" \
+  --trailer="Model=<model-id>" \
+  --trailer="Model-Source=self-reported" \
   --trailer="Provider=<provider>" \
-  --trailer="Role=product-ops" \
   --trailer="Channel=chat" \
   -m "feat(inventory): generate initial product catalog
 
@@ -685,6 +707,7 @@ Created 47 SKUs from the inventory spreadsheet."
 git commit --author="Copilot <copilot@{OPERATOR_DOMAIN}>" \
   --trailer="Agent=copilot" \
   --trailer="Model=<model-id>" \
+  --trailer="Model-Source=self-reported" \
   --trailer="Provider=<provider>" \
   --trailer="Channel=editor" \
   -m "docs(governance): add attribution model to git conventions"
@@ -709,10 +732,14 @@ git log --author="@{OPERATOR_DOMAIN}" --oneline
 git log --author="{OPERATOR_EMAIL}" --oneline
 
 # Extract trailers
-git log -10 --format='%H %s%n%(trailers:key=Agent,key=Model,key=Provider)%n'
+git log -10 --format='%H %s%n%(trailers:key=Agent,key=Persona,key=Model,key=Provider)%n'
 
-# Count commits per agent
+# Count commits per runtime/tool (Agent) -- coarse, always populated
 git log --all --format='%(trailers:key=Agent,valueonly)' | sort | uniq -c | sort -rn
+
+# Count commits per persona -- the finer-grained count the old single-Agent-field
+# query used to produce; empty where no roster was ever assigned
+git log --all --format='%(trailers:key=Persona,valueonly)' | sort | uniq -c | sort -rn
 ```
 
 ---

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

@@ -126,7 +126,8 @@ For each agent assigned to this business:
 4. **Verify** you can commit with the agent's author:
    ```bash
    git commit --allow-empty --author="{AGENT_NAME} <{AGENT_EMAIL}>" \
-     --trailer="Agent=kellar" --trailer="Model=test" --trailer="Provider=test" \
+     --trailer="Agent=claude" --trailer="Persona={AGENT_NAME}" --trailer="Model=test" \
+     --trailer="Model-Source=test" --trailer="Provider=test" \
      -m "test: verify agent git identity for {AGENT_NAME}"
    git log -1  # confirm author shows {AGENT_NAME}
    git reset HEAD~1  # clean up test commit

package/dist/assets/.arcane/governance/universal-agent-rules.md

@@ -45,7 +45,7 @@ See also: [[README]], [[DECISIONS]], [[governance/git-conventions|Git Convention
 
 11. **Use Conventional Commits format** for all commit messages: `type(scope): description`. See [[governance/git-conventions|Git Conventions]] for types, scopes, and examples.
 
-12. **Agent attribution trailers** are required on agent-authored commits (`Agent`, `Model`, `Provider`). See [[governance/git-conventions#agent-attribution-model|Attribution Model]].
+12. **Agent attribution trailers** are required on agent-authored commits (`Agent`, `Model`, `Model-Source`, `Provider`). `Persona`/`Role` are conditional — present only when a roster exists and one was assigned, never guessed. See [[governance/git-conventions#agent-attribution-model|Attribution Model]].
 
 13. **For runtime config changes** (anything touching the agent runtime's config files or service restarts): do NOT commit supporting docs until the user has confirmed the change is working. Stage and present — but wait for explicit approval after testing.
 

package/dist/assets/.claude/commands/spell-verification-ledger.md

@@ -0,0 +1,13 @@
+---
+description: Use PROACTIVELY when a session had real verification events worth a structured record — especially a claim that didn't survive a check.
+---
+
+# Verification Ledger
+
+Invoke the Arcane `spell-verification-ledger` spell workflow.
+
+See the full prompt at `.github/prompts/spell-verification-ledger.prompt.md` for the complete workflow definition.
+
+---
+
+@.github/prompts/spell-verification-ledger.prompt.md

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

@@ -81,7 +81,7 @@ Show a table (`# | category | disposition | author | file:line | summary | plann
 
 ## Step 5 — Execute
 
-Commits in this spell follow `.arcane/governance/git-conventions.md`: Conventional Commits format, agent attribution (`--author` + required `Agent`/`Model`/`Provider` trailers) when an agent authors the change, and — because this is an **interactive session** — present each proposed commit message and **wait for the human's approval before committing** (the Step 4 plan approval covers *what* to do, not the commit itself). Never squash.
+Commits in this spell follow `.arcane/governance/git-conventions.md`: Conventional Commits format, agent attribution (`--author` + required `Agent`/`Model`/`Model-Source`/`Provider` trailers, plus `Persona`/`Role` when a roster exists and one was assigned) when an agent authors the change, and — because this is an **interactive session** — present each proposed commit message and **wait for the human's approval before committing** (the Step 4 plan approval covers *what* to do, not the commit itself). Never squash.
 
 For **must-fix** (one thread at a time): read the code → implement → run the relevant tests.
 - **If tests pass:** commit (e.g. `fix(scope): address review — <desc>`) → reply `Fixed in <hash>. <what changed>` (cite the `R#` finding ID if one exists) → resolve the thread immediately.

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

@@ -31,7 +31,7 @@ Workflow:
    - 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`.
+   - **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:
 

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

@@ -116,12 +116,14 @@ Workflow:
    - References to ADRs or files
    - Context for why]
 
-   Agent: [lowercase-persona or tool name]
+   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]
-   Role: [agent role slug, if applicable]
    Task-Type: [docs, code, review, marketing, infra]
    Channel: [vscode, cli, chat]
    ```
@@ -132,7 +134,7 @@ Workflow:
    - 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`
+   - 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
 

package/dist/assets/.github/prompts/spell-full-cycle.prompt.md

@@ -122,7 +122,7 @@ Execute the `spell-implement` workflow:
    b1. **DB migration guard.** If `architecture.md`/the PRD did not name a database migration as part of this feature's scope, but implementing this story is about to produce one anyway, **halt and flag it** — do not write the migration file silently (2026-07-22 dogfooding finding: this is a scoped hard guard, not a blanket ban). If a migration genuinely is in scope, **re-derive its sequence number from a fresh `git pull --ff-only` of the target branch immediately before writing the file** — not once at branch-creation time in step 0 — so a concurrent epic that landed a migration in the meantime is reflected. This is the concrete fix for a real incident: two epics run in parallel worktrees each independently claimed the same migration sequence number, invisible until human merge review.
    c. Write tests per `governance/testing-standards.md`.
    d. Run tests. If passing:
-      - In `external/ado` mode, commit with `#{adoWorkItemId} type(scope): description` and agent attribution trailers (`Agent`, `Model`, `Provider`).
+      - In `external/ado` mode, commit with `#{adoWorkItemId} type(scope): description` and agent attribution trailers (`Agent`, `Model`, `Model-Source`, `Provider`).
       - In `internal` mode, commit with standard Conventional Commits format (no ADO prefix) plus attribution trailers.
    e. Update `stories.json`: set `passes: true`, fill `testEvidence`.
    f. Append learnings to `progress.txt`.
@@ -240,7 +240,7 @@ exactly one phase carries it at a time, matching the status line's own `[Phase N
 - **One human gate only.** Everything before Phase 6 step 5 is autonomous. Do not ask for intermediate approvals unless a gate fails.
 - **No scope creep.** Only build what the feature description specifies.
 - **Fail fast.** If a phase cannot succeed, halt immediately rather than producing garbage for downstream phases.
-- **Attribution required.** Every commit must carry `Agent`, `Model`, and `Provider` trailers per ADR-028/ADR-029.
+- **Attribution required.** Every commit must carry `Agent`, `Model`, `Model-Source`, and `Provider` trailers per ADR-028/ADR-029, plus `Persona`/`Role` when a roster exists and one was assigned.
 - **Branch discipline.** All work on topic branches, never on main — see `.arcane/governance/git-conventions.md`'s Trunk-based development rule. (Corrected 2026-08-31, BC-14: previously cited "ADR-048," which does exist in the shipped `framework-decisions.md` reference but is actually about the Code-Versus-Docs Branch Policy's local-only-repo fallback, unrelated to this general rule — a topical miscitation, the same class BC-06 found and fixed elsewhere. `git-conventions.md` states this rule directly with no ADR/ARC number attached, so there is nothing to cite beyond the file itself.)
 - **Fresh context per story.** Do not carry assumptions between stories during Phase 3.
 - **Epic checkpointing.** When this spell is run as one epic in a multi-epic plan, recommend running `spell-commit-work` before starting the next epic.

package/dist/assets/.github/prompts/spell-verification-ledger.prompt.md

@@ -0,0 +1,101 @@
+---
+name: Spell — Verification Ledger
+description: Extract a structured record of claims that were checked this session and what the check showed — especially the ones that didn't survive. Separate from spell-close-session; run on demand, not every session.
+argument-hint: Optional focus (e.g., "just the corrections", "since the last commit")
+agent: agent
+---
+
+## Executive Summary
+
+- The highest-value output of a working session is often the corrections — claims that were checked and
+  did not survive. `spell-close-session` captures what happened and sanitized lessons learned; it does
+  not capture what was asserted, what was checked, what the check showed, or what changed as a result.
+  This spell extracts exactly that, separately.
+- **Run on demand, not every session.** Most sessions have nothing worth a ledger entry; this spell says
+  so plainly and stops rather than manufacturing content to fill one (same discipline as
+  `spell-document`).
+- **A `corrected` result is the point, not a failure to hide.** A ledger showing three confirmed claims
+  and one correction is more valuable than one showing four confirmed claims and nothing else — the
+  correction is evidence the verification step actually did something, not theater.
+- Appends to a single running file, [`docs/verification-ledger.md`](../../docs/verification-ledger.md),
+  so a calibration rate (how often a checked claim survives) is computable across sessions without
+  reading scattered journal entries.
+
+---
+
+## What counts as a ledger-worthy event
+
+Only an assertion that was actually **checked against an independent source** counts — not every
+statement made during the session. The check has to have been capable of coming back either way:
+
+- A confident claim, followed by a real verification step (a tool call, a live read, re-running
+  something, checking a second source), whose result **confirmed** the claim.
+- A confident claim, followed by the same kind of check, whose result **contradicted** it —
+  a **correction**.
+- A check that was attempted but couldn't produce a definitive answer (no access, an ambiguous result)
+  — **unverifiable**. Distinct from never having been checked at all, which isn't ledger-worthy at all.
+
+Not ledger-worthy: a claim nobody checked, a preference or judgment call with no verifiable fact behind
+it, or a check whose outcome was never in doubt (confirming something already directly observed moments
+earlier is not a verification event).
+
+## Workflow
+
+1. **Scan the session for ledger-worthy events**, per the definition above. Look specifically for
+   moments where a check contradicted an initial assertion — a count that was off, a file path that
+   didn't exist, a "should be done" that direct inspection showed wasn't, a citation that pointed at the
+   wrong content. These are usually more memorable than confirmations; do not let them get lost among
+   routine, expected-to-pass checks.
+
+2. **Stop here if nothing qualifies.** If the session had no real verification events — no claim was
+   both asserted with confidence and independently checked — say so plainly and do not proceed. A quiet,
+   uneventful session with nothing to report is a valid outcome, not a gap to paper over.
+
+3. **Classify each event:**
+
+   | Field | What it captures |
+   | --- | --- |
+   | Claim | The assertion as originally stated, in the speaker's own words at the time — not softened in hindsight. |
+   | Verification method | What was actually done to check it (a specific command, a specific file read, a specific re-fetch) — not "verified," which asserts nothing checkable itself. |
+   | Result | `confirmed` / `corrected` / `unverifiable`. |
+   | Correction | For `corrected` only: what the check actually showed, and what changed as a result (a claim retracted, a decision reversed, a fix applied). |
+
+4. **Present the extracted ledger for approval** before writing — the same approval gate
+   `spell-document` uses, since this is also durable content leaving the conversation:
+
+   ```text
+   ## Verification Ledger Proposal — [session topic]
+
+   | Claim | Verification method | Result | Correction |
+   | --- | --- | --- | --- |
+   | ... | ... | confirmed | — |
+   | ... | ... | corrected | ... |
+
+   Approve? (yes / edit / skip)
+   ```
+
+5. **Append, don't rewrite.** After approval, append a new `## YYYY-MM-DD — <session topic>` section
+   with the approved table to `docs/verification-ledger.md`. Get the real date from the system rather
+   than guessing. If the file doesn't exist yet, create it with a short header explaining its purpose
+   and schema, then the first section — never insert a section anywhere but the end.
+
+## Rules
+
+- Never fabricate a ledger-worthy event to fill a report — an empty result from step 2 is a complete,
+  valid run of this spell.
+- Quote the claim as it was actually stated, not a cleaned-up paraphrase that makes the miss look
+  smaller (or larger) than it was.
+- Do not editorialize about fault or blame in the ledger itself — the value is the calibration signal
+  (how often checks confirm vs. correct), not a record of who was wrong.
+- Do not commit the changes — that is `spell-commit-work`'s job.
+
+## Related
+
+- **Complements, does not replace:** `spell-close-session`'s narrative record and sanitized lessons
+  learned. Run this spell separately when a session had real verification events worth a structured
+  record, not as a mandatory step of every close.
+- `spell-document` — the general-purpose formalization spell this one borrows its
+  extract-then-approve-then-write shape from, narrowed to one specific, structured record type.
+
+> **Tip:** Run `spell-close-session` afterward to log the session, or `spell-commit-work` to commit the
+> ledger update.

package/dist/index.js

@@ -505,6 +505,8 @@ var COMPONENTS = [
       ".claude/commands/spell-suggest-feature.md",
       ".github/prompts/spell-document.prompt.md",
       ".claude/commands/spell-document.md",
+      ".github/prompts/spell-verification-ledger.prompt.md",
+      ".claude/commands/spell-verification-ledger.md",
       ".github/prompts/spell-brainstorm.prompt.md",
       ".claude/commands/spell-brainstorm.md",
       ".github/prompts/spell-explain-concept.prompt.md",
@@ -4640,7 +4642,10 @@ program.command("unblock-push").description("Lift this repository's push block (
 program.command("doctor").description("Check your environment for Arcane prerequisites").option("--fix", "Automatically create missing session continuity files").action(async (opts) => {
   await runDoctor(process.cwd(), { fix: opts.fix }, ASSETS_DIR);
 });
-program.command("ward").description("Scan the repo for leaked third-party identifiers and trademarks (T18)").option("--terms <terms>", "Comma-separated denylist terms, in addition to the built-in vendor-identifier list").option("--gate", "Exit non-zero if any leak is found (for CI)").action(async (opts) => {
+program.command("ward").description("Scan the repo for leaked identifiers -- third-party trademarks and the operator's own personal identifiers alike (T18)").option(
+  "--terms <terms>",
+  "Comma-separated denylist terms, in addition to the built-in vendor-identifier list. Seed this from your OWN identity too, not just org/venture names -- usernames, machine names, and personal handles leak the same way a private venture name does (I1)"
+).option("--gate", "Exit non-zero if any leak is found (for CI)").action(async (opts) => {
   await runWardCli(process.cwd(), opts);
 });
 var agentsCommand = program.command("agents").description("Manage the portable agent system (init, sync, list)");