arcane-cli 1.6.0 → 1.8.0

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

@@ -151,6 +151,23 @@ Workflow:
 
 7. **Present for review** — show the PRD to the user for approval before proceeding to `spell-architect`.
 
+   <!-- fragment:needs-you:start -->
+   **Needs you — required operator actions.** When this run leaves an action that only the operator can take, and the work is not correct or complete until it is taken, report it in one block at the very top of the final report, before every other section and before any optional next step:
+
+   ```markdown
+   ## ⚠ Needs you
+
+   - <exactly what to do: the command, the link, or the question> — <why the agent cannot do it itself>
+   ```
+
+   - **What belongs in it:** an action the work needs that only the operator can take — approving or merging a pull request, accepting a decision record, answering a question the work is waiting on, confirming a `guarded` push, running an interactive command such as `spell unblock-push`, or a step on an external platform the agent cannot reach. An optional suggestion, a next spell to run, or anything the agent could do itself is not a required action and stays out of the block.
+   - **One line per action.** Say exactly what to do, then, after the dash, why the agent cannot do it. Write the command, link or question out in full; never point elsewhere with "see above".
+   - **Never only among optional steps.** An action required for correctness is never listed only under next steps, suggestions, `Carry Forward` or `What's Next?`. It may be repeated there, but it always appears in this block.
+   - **Omit it when empty.** When nothing needs the operator, leave the block out entirely: no heading and no "None" line.
+   - **Every final report.** The block belongs in whatever report ends the run, including a report written when the spell stops early.
+   - Enforcement: explicitly advisory prose (ARC-023) — no check reads a spell's actual output for this block; it holds by these instructions alone.
+   <!-- fragment:needs-you:end -->
+
 8. **Provider TODO handling** — if `external_provider=jira` or `external_provider=other`, add a TODO note in PRD open questions that provider-specific automation/linking is pending. `github` does not need this — it has a real, working flow (Step 1 above).
 
 Rules:

package/dist/assets/.arcane/spells/spell-review-batch.md

@@ -104,6 +104,23 @@ collide, but a PR title inserted verbatim as a label could).
 2. If `--html` was passed, also emit a self-contained HTML file (inline CSS, no external assets) at the same base path so it can be shared by email/chat.
 3. Print a summary to the user: total reviewed / skipped, verdict counts, total findings by severity, the GO/NO-GO gate, and the output path(s).
 
+   <!-- fragment:needs-you:start -->
+   **Needs you — required operator actions.** When this run leaves an action that only the operator can take, and the work is not correct or complete until it is taken, report it in one block at the very top of the final report, before every other section and before any optional next step:
+
+   ```markdown
+   ## ⚠ Needs you
+
+   - <exactly what to do: the command, the link, or the question> — <why the agent cannot do it itself>
+   ```
+
+   - **What belongs in it:** an action the work needs that only the operator can take — approving or merging a pull request, accepting a decision record, answering a question the work is waiting on, confirming a `guarded` push, running an interactive command such as `spell unblock-push`, or a step on an external platform the agent cannot reach. An optional suggestion, a next spell to run, or anything the agent could do itself is not a required action and stays out of the block.
+   - **One line per action.** Say exactly what to do, then, after the dash, why the agent cannot do it. Write the command, link or question out in full; never point elsewhere with "see above".
+   - **Never only among optional steps.** An action required for correctness is never listed only under next steps, suggestions, `Carry Forward` or `What's Next?`. It may be repeated there, but it always appears in this block.
+   - **Omit it when empty.** When nothing needs the operator, leave the block out entirely: no heading and no "None" line.
+   - **Every final report.** The block belongs in whatever report ends the run, including a report written when the spell stops early.
+   - Enforcement: explicitly advisory prose (ARC-023) — no check reads a spell's actual output for this block; it holds by these instructions alone.
+   <!-- fragment:needs-you:end -->
+
 ## Rules
 
 - Reuse the `spell-review` engine per PR — do not invent a parallel, weaker rubric.

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

@@ -121,6 +121,23 @@ Workflow:
 
 8. **Present findings** — show the review to the user with a clear recommendation.
 
+   <!-- fragment:needs-you:start -->
+   **Needs you — required operator actions.** When this run leaves an action that only the operator can take, and the work is not correct or complete until it is taken, report it in one block at the very top of the final report, before every other section and before any optional next step:
+
+   ```markdown
+   ## ⚠ Needs you
+
+   - <exactly what to do: the command, the link, or the question> — <why the agent cannot do it itself>
+   ```
+
+   - **What belongs in it:** an action the work needs that only the operator can take — approving or merging a pull request, accepting a decision record, answering a question the work is waiting on, confirming a `guarded` push, running an interactive command such as `spell unblock-push`, or a step on an external platform the agent cannot reach. An optional suggestion, a next spell to run, or anything the agent could do itself is not a required action and stays out of the block.
+   - **One line per action.** Say exactly what to do, then, after the dash, why the agent cannot do it. Write the command, link or question out in full; never point elsewhere with "see above".
+   - **Never only among optional steps.** An action required for correctness is never listed only under next steps, suggestions, `Carry Forward` or `What's Next?`. It may be repeated there, but it always appears in this block.
+   - **Omit it when empty.** When nothing needs the operator, leave the block out entirely: no heading and no "None" line.
+   - **Every final report.** The block belongs in whatever report ends the run, including a report written when the spell stops early.
+   - Enforcement: explicitly advisory prose (ARC-023) — no check reads a spell's actual output for this block; it holds by these instructions alone.
+   <!-- fragment:needs-you:end -->
+
 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 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:
@@ -131,7 +148,7 @@ Workflow:
       - GitHub: find the blocking review's ID (`gh api repos/{owner}/{repo}/pulls/<n>/reviews --jq '.[] | select(.state=="CHANGES_REQUESTED") | .id'`), then dismiss it — `gh api -X PUT repos/{owner}/{repo}/pulls/<n>/reviews/<review_id>/dismissals -f event=DISMISS -f message="<why this is now resolved, referencing the fix commit>"`.
       - Azure DevOps: `az repos pr set-vote --id <n> --vote approve` (or reset to no-vote per team convention).
     - Degrade silently if the CLI is unauthenticated or the PR can't be resolved (e.g. no PR exists yet for a local-only review) — never let this step abort a review that otherwise completed; the findings, report, and step 9 write-back still stand on their own.
-    - **GitHub refuses a REQUEST CHANGES verdict from the PR's own author** (`GraphQL: Review Can not request changes on your own pull request`, verified live 2026-08-31 — the same restriction as self-approval, just previously untested). When you are reviewing your own authored PR under the same GitHub identity, this call will fail with exactly that error: treat it as expected, not a bug, and fall back to the step 9 write-back as the only signal available — a formal blocking review needs a genuinely distinct reviewer identity (a second collaborator, or a separate bot/service account).
+    - **GitHub refuses a REQUEST CHANGES verdict from the PR's own author** (`GraphQL: Review Can not request changes on your own pull request`, verified live 2026-08-31 — the same restriction as self-approval, just previously untested). When you are reviewing your own authored PR under the same GitHub identity, this call will fail with exactly that error: treat it as expected, not a bug, and fall back to the step 9 write-back as the only signal available — a formal blocking review needs a genuinely distinct reviewer identity (a second collaborator, or a separate bot/service account). Because this happens after step 8, finish by telling the operator in a short `## ⚠ Needs you` block (per step 8): have a distinct reviewer identity post the blocking review — this identity cannot block its own pull request.
 
 Rules:
 - **Cover every dimension, not a finding count.** You MUST explicitly address each lens — correctness, security, performance, tests, naming/clarity, architecture — and state "no issues" for any lens that is clean. There is no minimum number of findings: zero findings is a valid outcome on a clean or small diff. The mandate is coverage of effort, not a count of findings — never fabricate issues to hit a quota.

package/dist/assets/.arcane/spells/spell-save-idea.md

@@ -76,7 +76,9 @@ Entry format:
 
 - Get the real local date and time from the system (e.g., run `date`) rather than guessing — a wrong timestamp silently corrupts the append-only log.
 - The `status: new` HTML comment lets later triage mark entries as `promoted` / `dropped` without deleting history.
+- This spell always writes the plain `<!-- status: new -->`. Later, `spell-todo --sweep --validate` may add `; value: …; fit: …; dup: …` fields to the comment after an operator's batch confirmation. The grammar that reads both forms is in `spell-manifest` Step 1.
 - Include `[#tag]` only if a tag was inferred; otherwise omit it.
+- **Tracker-id suffix (`tracking_mode: external` only):** if `.arcane.json`'s tracking mode is `external` and the idea names a work item that already exists, end the idea text with that id's suffix in the provider's format, before the status comment — defined once in [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) under "Tracker-ID Suffix on Captured Items" (e.g. `[#123]` GitHub, `[AB#123]` Azure DevOps, the issue key for Jira). Never guess an id and never file a work item from here — this spell stays instant. In `tracking_mode: internal`, the entry format above is unchanged.
 
 If `IDEAS.md` does not exist yet, create it with this header first, then append:
 

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

@@ -249,6 +249,23 @@ If `external_provider=jira` or `external_provider=other`, add explicit TODOs in
 
 ### 9. Present and Confirm
 
+<!-- fragment:needs-you:start -->
+**Needs you — required operator actions.** When this run leaves an action that only the operator can take, and the work is not correct or complete until it is taken, report it in one block at the very top of the final report, before every other section and before any optional next step:
+
+```markdown
+## ⚠ Needs you
+
+- <exactly what to do: the command, the link, or the question> — <why the agent cannot do it itself>
+```
+
+- **What belongs in it:** an action the work needs that only the operator can take — approving or merging a pull request, accepting a decision record, answering a question the work is waiting on, confirming a `guarded` push, running an interactive command such as `spell unblock-push`, or a step on an external platform the agent cannot reach. An optional suggestion, a next spell to run, or anything the agent could do itself is not a required action and stays out of the block.
+- **One line per action.** Say exactly what to do, then, after the dash, why the agent cannot do it. Write the command, link or question out in full; never point elsewhere with "see above".
+- **Never only among optional steps.** An action required for correctness is never listed only under next steps, suggestions, `Carry Forward` or `What's Next?`. It may be repeated there, but it always appears in this block.
+- **Omit it when empty.** When nothing needs the operator, leave the block out entirely: no heading and no "None" line.
+- **Every final report.** The block belongs in whatever report ends the run, including a report written when the spell stops early.
+- Enforcement: explicitly advisory prose (ARC-023) — no check reads a spell's actual output for this block; it holds by these instructions alone.
+<!-- fragment:needs-you:end -->
+
 Present the execution plan to the user. Ask:
 1. Does the epic split make sense?
 2. Are the ADR candidates correct? Should any be decided now?

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

@@ -96,6 +96,23 @@ Workflow:
    - OR: BLOCK — [reason]
    ```
 
+   <!-- fragment:needs-you:start -->
+   **Needs you — required operator actions.** When this run leaves an action that only the operator can take, and the work is not correct or complete until it is taken, report it in one block at the very top of the final report, before every other section and before any optional next step:
+
+   ```markdown
+   ## ⚠ Needs you
+
+   - <exactly what to do: the command, the link, or the question> — <why the agent cannot do it itself>
+   ```
+
+   - **What belongs in it:** an action the work needs that only the operator can take — approving or merging a pull request, accepting a decision record, answering a question the work is waiting on, confirming a `guarded` push, running an interactive command such as `spell unblock-push`, or a step on an external platform the agent cannot reach. An optional suggestion, a next spell to run, or anything the agent could do itself is not a required action and stays out of the block.
+   - **One line per action.** Say exactly what to do, then, after the dash, why the agent cannot do it. Write the command, link or question out in full; never point elsewhere with "see above".
+   - **Never only among optional steps.** An action required for correctness is never listed only under next steps, suggestions, `Carry Forward` or `What's Next?`. It may be repeated there, but it always appears in this block.
+   - **Omit it when empty.** When nothing needs the operator, leave the block out entirely: no heading and no "None" line.
+   - **Every final report.** The block belongs in whatever report ends the run, including a report written when the spell stops early.
+   - Enforcement: explicitly advisory prose (ARC-023) — no check reads a spell's actual output for this block; it holds by these instructions alone.
+   <!-- fragment:needs-you:end -->
+
 7. **Request human approval** — present the ship report and wait for explicit approval.
 
 8. **Execute merge** (after approval):

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

@@ -88,6 +88,7 @@ then classify **each conflicted hunk independently** — a single file can conta
   that one side's content is a strict superset of the other's. **STOP.** Do not guess, do not pick a
   side, do not attempt a "reasonable-looking" merge of the two. Abort the in-progress rebase/merge
   (`git rebase --abort` / `git merge --abort`) so the branch is left exactly as it was, then report:
+  - First, the `## ⚠ Needs you` block described in Step 6, naming the manual resolution as the action.
   - The exact conflicting file(s) and hunk(s).
   - Both sides' conflicting content, verbatim.
   - That the recoverable ref from Step 1 still points at the pre-sync state.
@@ -149,6 +150,23 @@ report the discrepancy rather than declaring the sync done.
 
 ## Step 6 — Report
 
+<!-- fragment:needs-you:start -->
+**Needs you — required operator actions.** When this run leaves an action that only the operator can take, and the work is not correct or complete until it is taken, report it in one block at the very top of the final report, before every other section and before any optional next step:
+
+```markdown
+## ⚠ Needs you
+
+- <exactly what to do: the command, the link, or the question> — <why the agent cannot do it itself>
+```
+
+- **What belongs in it:** an action the work needs that only the operator can take — approving or merging a pull request, accepting a decision record, answering a question the work is waiting on, confirming a `guarded` push, running an interactive command such as `spell unblock-push`, or a step on an external platform the agent cannot reach. An optional suggestion, a next spell to run, or anything the agent could do itself is not a required action and stays out of the block.
+- **One line per action.** Say exactly what to do, then, after the dash, why the agent cannot do it. Write the command, link or question out in full; never point elsewhere with "see above".
+- **Never only among optional steps.** An action required for correctness is never listed only under next steps, suggestions, `Carry Forward` or `What's Next?`. It may be repeated there, but it always appears in this block.
+- **Omit it when empty.** When nothing needs the operator, leave the block out entirely: no heading and no "None" line.
+- **Every final report.** The block belongs in whatever report ends the run, including a report written when the spell stops early.
+- Enforcement: explicitly advisory prose (ARC-023) — no check reads a spell's actual output for this block; it holds by these instructions alone.
+<!-- fragment:needs-you:end -->
+
 ```
 ✓ PR synced: <URL>
   Branch:          <branch> → <target>

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

@@ -12,18 +12,22 @@ agent: agent
 - It reads the current TODO landscape and repo structure to avoid duplicates and pick the right home.
 - Use this any time you have an idea mid-session and don't want to lose it or park it in the wrong place.
 - If the idea is ADR-worthy or journal-worthy, it flags that and routes accordingly.
+- `--prune` removes checked items from a TODO book — report first, outcome recorded or migrated before anything is deleted, one fingerprinted batch approval, and unchecked items are never touched.
 - **In a hub repo:** "add a todo for <venture>" targets that venture's own `TODO.md` book instead of the hub root. `--sweep` skips elaboration entirely and reports new/open counts across every book (hub root + every venture).
 
 ---
 
-Resolve `{BUSINESS_ROOT}` from `.arcane.json`'s `business_root` field (default `ventures/` if unset) before either mode below.
+Resolve `{BUSINESS_ROOT}` from `.arcane.json`'s `business_root` field (default `ventures/` if unset) before any mode below.
 
 ## Sweep Mode (`--sweep`)
 
 If the argument is (or starts with) `--sweep`, skip every other step in this spell entirely and run this instead:
 
-- **In a hub repo:** report `status: new` counts and oldest-entry age for the hub root `TODO.md` plus every `{BUSINESS_ROOT}/<slug>/TODO.md` that exists. Group by book, point at `spell-manifest` for entries ready to promote. Report-only — no edits.
+- **In a hub repo:** report `status: new` counts and oldest-entry age for the hub root `TODO.md` plus every `{BUSINESS_ROOT}/<slug>/TODO.md` that exists. Group by book, point at `spell-manifest` for entries ready to promote. Report-only — no edits (the one exception is the opt-in `--validate` below).
 - **In a consumer repo:** report the same, for the repo-root `TODO.md` only (no venture books exist there).
+- **Idea books too:** report the same `status: new` counts for the idea books that sit beside those TODO books — the hub root `IDEAS.md` and each venture's own `IDEAS.md` in a hub, the repo-root `IDEAS.md` in a consumer repo. Still report-only.
+
+**Sweep scope is hub-local (PRD D-08).** The sweep reads only books and journals inside this repository: in a hub, the hub's TODO books, the hub's IDEAS books, and the hub's own `journal/`. **It never reads a consumer repo's clone — not even a registered clone on this machine.** In a consumer repo it reads only that repo's own root books and `journal/`. Reaching into other repositories would widen what this spell touches, a privacy and scope change nobody asked for.
 
 Output format:
 
@@ -32,8 +36,84 @@ Todo sweep — N books, M open items
 
 hub TODO.md               12 open, oldest 2026-07-14
 ventures/ordovica/TODO.md  3 open, oldest 2026-08-10
+hub IDEAS.md               5 new, oldest 2026-08-02
+```
+
+### Unrouted lessons (part of every `--sweep`)
+
+The sweep also lists lessons from this repository's own journal that nothing has picked up yet. This pass is report-only, like the rest of the sweep: no writes, no moves, no filing, and no network calls.
+
+- **Where:** the hub's own `journal/` only — or, in a consumer repo, that repo's own `journal/` — within the hub-local scope above. Never a consumer clone's journal.
+- **Window:** journal entries dated on or after `--since YYYY-MM-DD`. Without `--since`, the last 30 days. The sweep is report-only, so it keeps no marker of when it last ran: to cover "since the last sweep", pass that sweep's date as `--since`. The output header states the window used.
+- **What counts as a lesson:** each heading directly under a `### Lessons Learned` section — one level deeper, e.g. `#### <lesson>` — because `spell-close-session` writes one heading per lesson. The pass reads headings only. **Bold sentences and bullet items are not read as lessons.** A `### Lessons Learned` section with no per-lesson headings (the older bullet style) is reported as one line — `<path>: Lessons Learned has no per-lesson headings — not harvested` — so it is never silently skipped.
+- **Routed or unrouted:** a lesson is routed when something references it:
+  - a `FEEDBACK.md` item;
+  - an idea-book entry or a TODO item within the sweep's scope — a reference is the lesson's heading text, or a link to its journal file with the lesson's heading anchor;
+  - an issue link in the lesson's own body (`#123`, `AB#123`, a Jira key, or an issue URL).
+
+  Everything else is unrouted. A lesson that `spell-close-session`'s Lessons Learned routing step (#274) already sent to `FEEDBACK.md` or an idea book is referenced there, so it drops out here.
+
+```
+Lessons since 2026-08-28 (hub journal) — 2 unrouted
+  journal/2026-09-11-cache-rollout.md
+    - The stated risk was work that did not exist
+    - Building the state first beat reading the plan
+  journal/2026-09-02-release-prep.md: Lessons Learned has no per-lesson headings — not harvested
+Promote with spell-feedback (framework), spell-save-idea (product idea), or spell-todo (task).
 ```
 
+### Idea validation (`--sweep --validate`, opt-in)
+
+Without `--validate`, the sweep never edits anything. With it, the sweep also asks two or three quick yes/no questions per idea entry, so that `spell-manifest` can later see which ideas are worth promoting. Capture itself (`spell-save-idea`) stays unchanged.
+
+1. **Candidates:** idea-book entries, within the hub-local scope above, whose status comment is `status: new` and does not yet carry a `value:` field. TODO-book items have no status comment and are not validated.
+2. **Ask, per entry** — show the entry's text and book, then ask:
+   - `value` — Is this valuable to the people who use what this repo builds? (`y` / `n` / `?`)
+   - `fit` — Does it belong here, rather than in another venture, another repo, or a consumer's own product? (`y` / `n` / `?`)
+   - `dup` — Does it duplicate an existing idea entry, TODO item or tracker issue? (`none`, or a short reference such as `#123` or `IDEAS.md 2026-08-02 14:10`; never containing `;` or `--`)
+
+   `skip` leaves the entry unanswered; `stop` ends the questions and goes on to the confirmation with what has been answered so far. **Nothing is written while the questions are being asked** — the answers are held until step 3.
+3. **One batch confirmation.** Print every change as `file:line`, the old comment, and the new one. Then ask once: `Write N status comments? (write / cancel)`. Only the operator's own literal `write` writes. A timeout, a cancellation, a host-generated fallback or ordinary conversational assent is not confirmation, and nothing is written. If a book changed since it was read, re-read it and confirm again. **Enforcement: structured spell gate (ARC-023) — answers are written only after the operator's single batch `write`; the check is agent-administered, not tool-verified.**
+4. **Write only the status comment.** The entry text, timestamp and tag stay untouched, and the books stay append-only. The answers are added as fields after the status. The grammar is `spell-manifest`'s Step 1 "Status-comment grammar", which reads both forms:
+
+   ```
+   <!-- status: new -->                                  before
+   <!-- status: new; value: y; fit: y; dup: none -->     after
+   ```
+
+   Update `last_updated` in the frontmatter of every touched book. Do not commit; hand off to `spell-commit-work`.
+
+## Prune Mode (`--prune`)
+
+If the argument is (or starts with) `--prune`, skip every other step in this spell entirely and run this instead. It removes resolved items from a TODO book only after proving each one's outcome is recorded somewhere durable. (Not to be confused with `spell update --prune`, which removes orphaned managed files.)
+
+**Target book:** this repo's root `TODO.md`. In a hub, `--prune --venture <slug>` targets that venture's own `TODO.md` instead, resolved through the registry's aliases exactly as Step 0 below does. One book per run.
+
+1. **Collect checked items only.** A candidate is a checked item — `- [x]` or `- [X]` — together with its indented continuation lines, and only when every item it is nested under is checked too: a checked sub-item under an unchecked parent belongs to that open item and is never a candidate. **An unchecked item (`- [ ]`) is never a candidate: it is never deleted, moved or edited by this mode.** A checked item with any unchecked sub-item is kept whole and reported as `has open sub-items — kept`.
+2. **Check each outcome is recorded durably.** For each candidate, look for the record of what happened, in this order:
+   - the item's own reference — a file link, a PR or issue link, an ADR id, a tracker-id suffix — followed and confirmed to exist and to describe the outcome;
+   - otherwise, a search of `journal/`, `DECISIONS.md`, `CHANGELOG.md`, and the repo's audit log and playbooks where they exist, for the item's key terms.
+
+   Classify each candidate as `recorded → <where>` (path, plus heading or line) or `unrecorded`. A merged PR or closed issue counts as durable only when the item links it; an unlinked guess ("probably PR #40") is `unrecorded`.
+3. **Report first — no edits yet.** Print every candidate with its classification. For each `unrecorded` one, print the outcome migration you propose: a short outcome note (what was done, when, where it can be seen) appended to today's journal entry, `journal/YYYY-MM-DD-<topic-slug>.md`, under a `### Pruned TODO outcomes` heading. If you cannot tell what the outcome was, say so and leave that item out of the batch — never invent an outcome.
+
+   ```
+   Todo prune — TODO.md, 5 checked items
+
+     1. [x] Add export button              recorded → CHANGELOG.md (1.4.0)
+     2. [x] Decide on ADR numbering         recorded → DECISIONS.md (numbering entry)
+     3. [x] Document the retrofit path      unrecorded → migrate to journal/2026-09-27-todo-prune.md
+     4. [x] Wire the push hook              has open sub-items — kept
+     5. [x] Try the new cache               outcome unknown — kept (tell me what happened, or leave it)
+
+   Delete 3 items (1 after migration). Fingerprint: 3f9c1a…
+   ```
+4. **One batch approval, fingerprinted.** This is the same gate `spell-commit-work` step 8 uses for a commit. Compute an approval fingerprint from the exact deletion list (book path, line, full item text for every item to delete) plus the exact migration text. Present the list, the migration text and the fingerprint through a structured approval control, and wait for an authenticated operator response tied to that fingerprint. One approval covers the whole batch; there are no per-item prompts. A timeout, a cancellation, a host-generated fallback, a delegated response, or ordinary conversational assent is not approval: halt with nothing written. Recompute the fingerprint immediately before writing. If the book or the migration text changed, the approval is void; ask again. **Enforcement: structured spell gate (ARC-023) — nothing is written until the operator approves the fingerprinted batch; the fingerprint comparison is agent-administered, not tool-verified.**
+5. **Migrate, then delete.** Write every migration first and confirm each one landed. Then delete exactly the approved lines, and nothing else. An item whose migration failed stays in the book. Update `last_updated` in the frontmatter of every touched file.
+6. **Record the deletion; do not commit.** `governance/records-conventions.md` ("Retention and deletion") requires an approved deletion to be recorded. Propose a commit message whose body lists each deleted item and where its outcome is recorded, and hand off to `spell-commit-work`. No separate completed-items ledger is written: `records-conventions.md` defines no home for one, and the commit body plus the migrated journal notes are the record.
+
+**Speed rule:** a book with no checked items reports `Nothing to prune — 0 checked items` and stops.
+
 ## Step 0 — Venture Targeting (Hub Only)
 
 If the input names a venture ("add a todo for ordo", `--venture <slug>`), resolve it through `{BUSINESS_ROOT}/registry.json`'s aliases first (exact slug → alias → closest match offered — never guessed). Unknown slug:
@@ -104,6 +184,8 @@ Expand the idea into one or more concrete TODO items. Each item must:
 - Include a file reference if a canonical home doc already exists (e.g., `— see [[DECISIONS]]`)
 - Be specific enough to act on without further clarification
 
+**Tracker-id suffix (`tracking_mode: external` only):** when `.arcane.json`'s tracking mode is `external` and an item corresponds to a work item that already exists (the operator gave its id, or the idea names it), end the item with that id's suffix in the provider's format — defined once in [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) under "Tracker-ID Suffix on Captured Items" (e.g. `[#123]` GitHub, `[AB#123]` Azure DevOps, the issue key for Jira). Never guess an id or file a work item just to get one. In `tracking_mode: internal`, items are written without a suffix, exactly as before.
+
 If the idea naturally decomposes into multiple sub-items (e.g., "build dashboard" → design, implement, deploy, document), list them individually — do not bundle vague compound items.
 
 If the idea is an `adr-candidate`, also draft a one-sentence ADR title suggestion (e.g., `ADR-NNN: Use GitHub Actions for CI instead of Azure Pipelines`).

package/dist/assets/ai-context/system-prompt-context.md

@@ -33,6 +33,7 @@
 - **Branch:** main
 - **Blockers:** None.
 - **Pending Verification:** None.
+- **Needs you:** None.
 - **Notes:** —
 
 > ✓ Consumed: YYYY-MM-DD — scaffold placeholder, not a real session; ships pre-consumed so the first