arcane-cli 1.6.0 → 1.7.0

package/dist/assets/.arcane/governance/decision-documentation-standard.md

@@ -36,7 +36,43 @@ Arcane separates framework-level decisions from org-specific ones using two pref
 - If the decision would apply to any organization using Arcane, it is `ARC-NNN`.
 - If the decision is specific to how your organization operates, it is `ADR-NNN`.
 - When uncertain, default to `ADR-NNN` in ops; promote to `ARC-NNN` later if the decision proves framework-generic. **Enforcement: explicitly advisory prose (ARC-023) — whether a decision is framework-generic enough for `ARC-NNN` (this rule and the two prefix-scoping rules above) is a judgment call; no script evaluates a decision's content to confirm the chosen prefix.**
-- Never renumber existing entries in either sequence. **Enforcement: explicitly advisory prose (ARC-023) — `scripts/check-distributed-adr-references.ts` only verifies that a bare `ADR-NNN` citation resolves to a heading declared in `framework-decisions.md` (and separately flags certain `ARC-NNN`/`EF-NNN` link forms as cross-repo hazards); it never checks that numbers are sequential, unique, or never reused.**
+- Never renumber existing entries in either sequence. **Enforcement: explicitly advisory prose (ARC-023) — `scripts/check-distributed-adr-references.ts` only verifies that a bare `ADR-NNN` citation resolves to a heading declared in `framework-decisions.md` (and separately flags certain `ARC-NNN`/`EF-NNN` link forms as cross-repo hazards); it never checks that numbers are sequential, unique, or never reused. Uniqueness alone has an executable check in Arcane's own repository only: `scripts/check-stale-claims.ts` (run in CI as `npm run check:stale-claims`) fails when two decision headings in its `DECISIONS.md` share an ID (ARC-050). That check does not ship to consuming repositories, and it cannot tell a renumbered entry from a new one.**
+
+## Allocating Decision Numbers
+
+Decision numbers are a shared sequence (ARC-028 R4). Two sessions on separate branches that each take
+"the next number" both take the same one. The collision surfaces at merge, or never, and
+cross-references then point at the wrong decision. ARC-050 sets how a number is allocated:
+
+1. **Fetch, then take the maximum.** Before allocating a decision number, fetch the trunk when a
+   usable remote exists. "Usable" is the classification `spell-open-session`'s Mutation Guard uses: a
+   supported provider with authenticated provider tooling, where a remote URL alone is not enough.
+   Then allocate `max(highest number on the local branch, highest number on the remote trunk) + 1`.
+2. **A local-only repository allocates from the local maximum and says so**, so the number is
+   visibly unchecked against any other branch.
+
+   **Enforcement (rules 1 and 2): structured spell gate (ARC-023) — `spell-close-session` step 3
+   requires the observed trunk maximum, or its stated local-only line, before it writes a new entry.
+   A decision written outside that spell, by hand or by another workflow, follows these rules as
+   explicitly advisory prose: nothing else fetches or compares for it.**
+3. **No reservation markers.** Never commit a placeholder or "reserved" entry to claim a number. A
+   marker is itself an edit to the same shared sequence, so it collides the same way. **Enforcement:
+   explicitly advisory prose (ARC-023) — no script recognizes a placeholder entry as a reservation.**
+4. **Several decisions at once are allocated once.** A program that drafts several decisions
+   allocates all of them at the start of the wave that needs them, from the fetched trunk. Its
+   parallel lanes use those numbers and never allocate their own. A single session that records
+   several decisions allocates them consecutively from one fetched maximum. **Enforcement:
+   explicitly advisory prose (ARC-023) — no spell gate or script tracks which numbers a program
+   pre-allocated.**
+5. **When a collision still happens, the unmerged branch renumbers.** Fetching narrows the race but
+   does not close it: two sessions can fetch before either pushes. "Never renumber existing entries"
+   applies to merged entries. When two branches hold the same number, the branch that has not merged
+   yet renumbers its own entry and every reference to it on that branch. **Enforcement: explicitly
+   advisory prose (ARC-023) for the renumbering — no script performs it or checks which branch did
+   it. Detecting the collision is an executable check in Arcane's own repository only:
+   `scripts/check-stale-claims.ts`, run in CI as `npm run check:stale-claims`, fails when two
+   decision headings share an ID. It matches any `## <PREFIX>-<number>` heading, not only `ARC`, so
+   a consuming repository can adopt it, but it is not installed there.**
 
 ## Problem Statement
 

package/dist/assets/.arcane/governance/development-methodology.md

@@ -161,6 +161,26 @@ GitHub Issues has no configurable work-item-type hierarchy the way Azure DevOps
 - **Jira (`external_provider=jira`)** — TODO: define issue-type mapping, parent-child/epic linkage strategy, and command examples.
 - **Other providers (`external_provider=other`)** — TODO: define required metadata contract and fallback behavior before enabling automation.
 
+### Tracker-ID Suffix on Captured Items
+
+When `tracking_mode=external` and a `TODO.md` item or an `IDEAS.md` entry corresponds to a tracker work item that already exists, the item carries that work item's id as a suffix, in the provider's own reference format. This is the one definition of the suffix; `spell-todo`, `spell-save-idea` and `spell-manifest` point here rather than restating it.
+
+| `external_provider` | Suffix | Example |
+| --- | --- | --- |
+| `github` | `[#<number>]` | `- [ ] Add export button [#123]` |
+| `ado` | `[AB#<id>]` | `- [ ] Add export button [AB#123]` |
+| `jira` | `[<issue key>]` — the key exactly as Jira prints it | `- [ ] Add export button [PROJ-123]` |
+| `other` | no suffix until that provider's metadata contract is defined (see External Provider TODOs) | — |
+
+- **Placement:** at the end of the item's text, after any file reference, and before a trailing `<!-- status: … -->` comment on an idea entry.
+- **Only a real id:** the suffix records an id that exists — one the operator supplied, or one a spell just got back from the tracker. Never guess an id, and never file a work item just to have a suffix.
+- **One suffix per item:** an item that already carries a suffix keeps it; it is not duplicated or rewritten.
+- **`tracking_mode=internal`:** no suffix. Items are written exactly as they are without this section.
+
+The suffix uses the same reference forms as the commit-link syntax `spell-bug` writes (`Fixes AB#{id}` for Azure DevOps, `Fixes #{id}` for GitHub Issues — the GitHub form is also under GitHub Issues Conventions above), so an item and the commit that closes it point at the work item the same way.
+
+**Enforcement: explicitly advisory prose (ARC-023) — no script checks that an externally tracked item carries its suffix or that a suffix matches the provider's format; the three spells apply it at write time and compliance depends on the executing agent.**
+
 ### Fresh Context Per Iteration
 
 Each implementation iteration starts with clean context. The only memory between iterations is:

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

@@ -70,6 +70,32 @@ If the npm registry is unreachable, report:
 ℹ Could not reach npm registry — update check skipped.
 ```
 
+### Setup questions from an AI harness (no interactive terminal, PRD D-02 / #282)
+
+This spell itself stays read-only. If the operator then asks you to run `spell update`, note that a
+harness shell is not an interactive terminal. The CLI then skips every unanswered manifest question
+and prints ``! Skipped N manifest question(s) (<fields>) — no interactive terminal. Run `spell update` from a terminal, or answer by flags:``,
+followed by the exact line to re-run, such as
+`spell update --tracking-mode <internal|external> --push-policy <open|guarded|blocked>`.
+`spell init --profile <profile>` prints the same kind of `spell update` line when it leaves
+questions unanswered. Do not send the operator off to find a terminal. Instead:
+
+1. Ask the operator each skipped question through the harness's own question UI (a plain chat
+   question if the harness has none): one question per flag the CLI printed, offering exactly the
+   values that flag lists. The flags are `--role`, `--tracking-mode`, `--external-provider`,
+   `--content-sensitivity`, `--push-policy` and `--subject-root`. `--tracking-mode external` also
+   needs `--external-provider <ado|github|jira|other>`, so ask that too when the answer is
+   `external`.
+2. Re-run `spell update` with the flags the CLI printed, filled with the operator's answers, for
+   example `spell update --tracking-mode internal --push-policy guarded`.
+3. Never pass a flag the operator did not answer. No guessed, default or "recommended" value stands
+   in for an answer. An unanswered question stays unset: the next interactive run asks it, and the
+   next harness run reports it skipped again.
+4. Never loosen `push_policy` by flag. `--push-policy` only answers an unset question or tightens a
+   recorded policy, and the CLI refuses a loosening. Moving a repository from `blocked` or `guarded`
+   toward `open` is only ever `spell unblock-push`, which the operator runs from an interactive
+   terminal (ARC-034 decision 6, ARC-049 decision 6). Tell them so; do not try to run it for them.
+
 ## Step 3 — Component Detail (optional)
 
 Only include this section when the user passed "components" as the prompt argument.

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

@@ -53,13 +53,39 @@ Workflow:
    - Journal entries must include:
      - `### Prompt Context` — original prompt text or a faithful paraphrase of the multi-turn request when the session began from a substantive user ask. Include follow-up scope inputs if they materially changed the direction of the work.
      - `### What Got Done` — numbered list of concrete outcomes with file/ADR references. Only list an outcome here if step 1b classified it `succeeded` (or it never involved async work at all, e.g. a local file edit). A `pending`/`dispatched`/`unverifiable` item belongs in Open Items Carried Forward, not here — do not let this section imply completion step 1b couldn't confirm.
-     - `### Decisions Made` — table of ADR number, decision, and rationale. If no decisions were made, omit this section.
+     - `### Decisions Made` — table of ADR number, decision, and rationale. If no decisions were made, omit this section. Take every number in this table from step 3's allocation rule (ARC-050). If step 3 has not allocated yet, run that allocation now and use the same numbers in both places. Never write a number from memory or from this branch's `DECISIONS.md` alone.
      - `### Lessons Learned` — one heading per lesson with enough context to prevent the mistake again. Use narrative, not bullet fragments.
      - `### Open Items Carried Forward` — items that remain undone from this session, including every `pending`/`dispatched`/`failed`/`unverifiable` item from step 1b.
 
+2b. **Lesson routing: send each lesson where it can be acted on.** A lesson left only in the journal never reaches the people who could fix its cause. Skip this step when step 2 wrote no `### Lessons Learned`, or when the invocation includes `--no-route`. With `--no-route`, the lessons stay in the journal only; say `Lesson routing skipped (--no-route)` in the closure report.
+   - **Classify each lesson** written in step 2 into exactly one class:
+     - **Framework-shaped:** the fix belongs in Arcane itself, meaning a spell prompt, template, governance doc, playbook, or CLI behavior this repository installed rather than authored. This is `spell-feedback` Step 3's definition. Destination: `FEEDBACK.md`, queued for upstream.
+     - **Product idea:** the lesson suggests something to build in this repository's own product. Destination: `spell-save-idea`.
+     - **Repo-local:** anything about this repository's own content, configuration, or way of working. Destination: the journal only. It is already there, so nothing more is written.
+   - **Show one batch proposal and ask once.** List every lesson with its class and destination, then ask a single question: `Route these lessons? (yes / edit / skip)`. `edit` lets the operator change a class or drop a lesson, then shows the proposal again. Route nothing before an explicit `yes`. A timeout, a cancellation, a delegated or host-generated response, or assent given to something else is not approval. Neither is an autonomous run with no operator to ask. In each of those cases route nothing, keep the lessons in the journal, and list the proposal in the closure report as not routed. `skip` is a complete, valid answer.
+   - **Framework-shaped, after `yes`:** append **one** block to `FEEDBACK.md` at the repository root, in `spell-feedback`'s Step 5 block format. Create the file with a `# Feedback Log` header first if it is missing. Fill the block this way:
+     - Heading: `## Feedback — <the spell or doc the lessons concern, or "Arcane workflow" when they span several> (<YYYY-MM-DD>)`.
+     - `**Session:**` names this session and adds `(routed by spell-close-session from Lessons Learned)`.
+     - `**Rating:**` and `**Would use again:**` are `N/A`, because nobody rated anything.
+     - Friction Points: one line per lesson saying what happened.
+     - Improvement Items: one imperative item per lesson, each line ending with `<!-- upstream: queued -->`.
+     - Raw Notes: cite the journal file and each lesson's heading.
+   - **Product idea, after `yes`:** hand each one to `spell-save-idea` as a one-sentence idea, citing the journal file. That spell appends it to the idea book.
+   - **No public write from this step.** Close-session never files an issue and never runs `gh issue create`. It also never runs `spell-feedback`'s Step 6 filing flow. Queuing is the whole outcome here. The `yes` above approves local appends only. Filing upstream still needs `spell-feedback`'s own literal `disclose` confirmation on each item, given in a later `spell-feedback` or `spell-feedback --flush` run, which re-offers every queued item through its genericize-and-`disclose` flow.
+   - **Append-only.** Add new entries to `FEEDBACK.md` and the idea book. Never edit, reorder, or remove an existing entry in either.
+   - Enforcement: structured spell gate (ARC-023) — nothing is routed without the one explicit batch `yes`, and it fails closed. The no-public-write and append-only rules are explicitly advisory prose: no hook stops this step from running `gh` or rewriting a book, so they hold by the step's own instructions. Classifying a lesson is a judgment call, and the operator checks it at the batch proposal.
+
 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.
+   - **Allocate that number against the trunk, not only this branch (ARC-050; ARC-028 R4 names decision numbers a shared sequence).** Another session on another branch may already have taken "the next number". Do this immediately before writing the first new entry:
+     - **Classify the remote first.** Use the classification from step 9's remote-capability check, which is the same one `spell-open-session`'s Mutation Guard uses. A usable remote is a supported provider (`github.com`, `dev.azure.com`, or `visualstudio.com`) with authenticated provider tooling; a remote URL alone is not enough. Resolve `<remote>` and `<trunk>` from observed state as step 10 does. Never assume `origin` or `main`.
+     - **Usable remote: fetch, then take the maximum.** Run `git fetch <remote> <trunk>`. Read the highest decision ID (the number in the log's `## <PREFIX>-NNN` headings) from this branch's `DECISIONS.md`, and from the trunk's copy with `git show <remote>/<trunk>:DECISIONS.md`. A trunk with no `DECISIONS.md` has no maximum. Allocate `max(highest ID on this branch, highest ID on <remote>/<trunk>) + 1`. In the Decision Updates output, name both maxima and the number allocated.
+     - **Local-only: allocate from the local maximum and say so.** When there is no usable remote, allocate `highest ID in the local DECISIONS.md + 1`. Say so in the Decision Updates output: `Allocated <PREFIX>-NNN from the local maximum only; not checked against any other branch.` Treat a usable remote whose fetch fails the same way, and name the failed fetch in that line.
+     - **Several decisions in one session:** allocate them consecutively from the one maximum you just computed, in a single pass.
+     - **No reservation markers.** Never commit a placeholder or "reserved" entry to claim a number before the real entry exists. A marker is itself an edit to the same shared sequence, so it collides the same way.
+     - **If a collision still surfaces later** (two sessions fetched before either pushed), the branch that has not merged yet renumbers its own entry and every reference to it on that branch. Merged entries are never renumbered (`decision-documentation-standard.md`).
+     - Enforcement: structured spell gate (ARC-023) — this step requires the observed trunk maximum, or the stated local-only line, before a new entry is written. The renumbering rule above is explicitly advisory prose: nothing in this spell detects a collision after the fact.
    - Follow the existing format: Date, Status, Context, Decision, Reasoning, Rejected alternatives.
 
 4. **Update [TODO.md](../../TODO.md).**
@@ -224,9 +250,15 @@ Output format:
 
 - Exact file updates made.
 
+## Lesson Routing
+
+- Each lesson from step 2b with its class and where it went: `FEEDBACK.md` (queued for upstream), `spell-save-idea`, or journal only.
+- Or one of: `Lesson routing skipped (--no-route)`, `No lessons recorded`, or `Not routed (no explicit yes)` followed by the proposal.
+
 ## Decision Updates
 
 - ADRs added or note that none were needed.
+- For each ADR added, how its number was allocated (step 3): `max(<this branch's highest>, <remote>/<trunk>'s highest) + 1`, or the local-only line.
 
 ## TODO Updates
 

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

@@ -127,6 +127,15 @@ For each framework-shaped item:
 
 Maintainer side is unchanged: GitHub issues are arcane's normal public intake; triage into arcane's own `IDEAS.md`/`DECISIONS.md` happens in arcane sessions like any other issue. This spell never writes to a hub's venture books and never reads `ventures/registry.json` — framework feedback and venture ideas are different channels on purpose (venture ideas → hub books → `spell-manifest`; framework lessons → here → arcane's GitHub).
 
+## Entry Point — Lessons Routed by `spell-close-session`
+
+`FEEDBACK.md` has a second writer. `spell-close-session`'s lesson-routing step (step 2b) classifies each of the session's Lessons Learned. After one batch confirmation, it appends the framework-shaped ones as a single block in Step 5's format:
+- `**Session:**` carries `(routed by spell-close-session from Lessons Learned)`.
+- `**Rating:**` and `**Would use again:**` are `N/A`.
+- Each improvement item ends with `<!-- upstream: queued -->`.
+
+That step never files anything publicly. Its entries reach `{ARCANE_UPSTREAM_REPO}` only through this spell: `spell-feedback --flush` picks them up with every other queued item and runs Step 6 on each one (genericize, the literal `disclose` confirmation, then file or re-queue). A routed entry gets no shortcut, because close-session's batch confirmation approved a local append, not a public issue. An `N/A` rating is not a low rating, so it never triggers the `⚠️ LOW RATING` flag. **Enforcement: structured spell gate (ARC-023) — Step 6's literal `disclose` confirmation gates filing a routed item exactly as it gates any other; nothing in this spell distinguishes a routed item that could skip it.**
+
 ## Rules
 
 - Never overwrite existing feedback — always append.

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

@@ -30,6 +30,18 @@ Parse `status: new` entries from the hub root `IDEAS.md` and every `{BUSINESS_RO
 
 Tolerate operator YAML frontmatter above a book's header — entries always live below the `---` divider. Malformed entries (missing timestamp, unparseable status comment) are listed under a `Skipped` heading with `file:line`, never silently dropped.
 
+**Status-comment grammar.** A status comment is `<!-- status: <state>[; <key>: <value>]... -->`. The first field is the status itself, unchanged from before: `new`, `promoted → <dest> YYYY-MM-DD`, or `dropped YYYY-MM-DD` with an optional `(reason)`. Zero or more `; <key>: <value>` fields may follow it. `spell-todo --sweep --validate` writes three of them: `value` and `fit` (each `y`, `n` or `?`) and `dup` (`none`, or a short reference). Both forms parse:
+
+```
+<!-- status: new -->
+<!-- status: new; value: y; fit: y; dup: none -->
+```
+
+- **Splitting:** split the comment body on `; ` only where the next segment starts with a lowercase `key: `. A `; ` anywhere else — inside a drop reason, say — stays part of the field it is in.
+- **Deciding `new`:** only the first field does. An entry is collected when that field is exactly `status: new`, with or without fields after it.
+- **Unknown fields:** an unknown key, or a known key with an unexpected value, is ignored and shown as-is. It never moves the entry to `Skipped`.
+- **Unparseable:** a comment is unparseable, and the entry goes to `Skipped`, when it does not open with `status:`, is not closed with `-->`, or its first field is not exactly `new`, `promoted …` or `dropped …` (a typo such as `status: nwe` or `status: New` is reported, never silently left out of both lists).
+
 ## Step 2 — List
 
 Print one numbered list, grouped by book, oldest entry first within each group. Numbering is session-scoped — it does not persist across runs.
@@ -45,6 +57,8 @@ ventures/ordovica/TODO.md
   3. [ ] Confirm cart snapshot order (open item, no status comment — todo-book entries are listed as-is)
 ```
 
+An entry whose status comment carries validation fields (Step 1's grammar) shows them after its text — for example `(value: y, fit: n, dup: none)` — so that the operator can leave out `fit: n` entries, or ones marked as duplicates, when selecting in Step 3. An entry without them is listed exactly as before.
+
 ## Step 3 — Select
 
 Ask: `Promote which? (numbers/ranges, e.g. 1,3,5-8, or "all")`. Accept a single answer covering the whole batch. `all` selects every listed entry, including ones in books outside `--venture` if no filter was given.
@@ -114,8 +128,12 @@ book:<other-slug>/IDEAS.md
 
 Any marker whose destination repository is public ends in ` (disclosed)` — whichever route landed it, because Step 5 gated it as a disclosure.
 
+**Tracker-id suffix.** When route (c) files a tracker item, append the new work item's id to the hub entry's text as a suffix — before its status comment — in the format [governance/development-methodology.md](../../.arcane/governance/development-methodology.md) defines once under "Tracker-ID Suffix on Captured Items" for that tracker's provider (`[AB#<id>]` Azure DevOps, `[#<id>]` GitHub, the issue key for Jira). Use only the id the create command returned. The promoted marker still names the repo (`github:<slug>#<id>`), which is what disambiguates a GitHub suffix inside a hub book. An entry that already carries a suffix keeps it unchanged wherever it lands. No tracker item filed means no suffix: entries routed without a tracker (and every internal-mode flow) are written exactly as before.
+
 Dropped entries get `<!-- status: dropped YYYY-MM-DD -->`, optionally with a trailing `(reason)`.
 
+Validation fields already in an entry's comment (Step 1's grammar) are kept after the new first field when it is marked, e.g. `<!-- status: dropped 2026-09-27; value: n; fit: y; dup: none -->`. An entry without them gets exactly the marker above.
+
 Before any downstream write, grep the target file for the entry's normalized first ~40 characters — if already present, treat this entry as already-landed, mark the hub entry promoted, and skip the write. This is what makes an interrupted or re-run batch safe.
 
 ## Step 7 — Leak Scan

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

@@ -99,6 +99,11 @@ Before anything else, check:
   - Run `npm view arcane-cli version` to get the latest published version.
   - **(a) Managed files behind the installed CLI** (installed CLI version is newer than the version recorded in `.arcane.json`): surface a warning: `⚠️ Managed files out of date: files at <installed> → CLI at <cli>. Run spell update to resync files.`
   - **(b) Installed CLI behind the latest published version** (latest published is newer than the installed CLI): surface a warning: `⚠️ Arcane CLI update available: CLI at <cli> → latest <latest>. Upgrade the CLI, then run spell update.`
+  - **Setup questions from an AI harness (no interactive terminal, PRD D-02 / #282):** if you run `spell update` yourself — a repository write, so apply the Mutation Guard first — note that a harness shell is not an interactive terminal. The CLI then skips every unanswered manifest question and prints ``! Skipped N manifest question(s) (<fields>) — no interactive terminal. Run `spell update` from a terminal, or answer by flags:``, followed by the exact line to re-run, such as `spell update --tracking-mode <internal|external> --push-policy <open|guarded|blocked>`. `spell init --profile <profile>` prints the same kind of `spell update` line when it leaves questions unanswered. Do not send the operator off to find a terminal. Instead:
+    1. Ask the operator each skipped question through the harness's own question UI (a plain chat question if the harness has none): one question per flag the CLI printed, offering exactly the values that flag lists. The flags are `--role`, `--tracking-mode`, `--external-provider`, `--content-sensitivity`, `--push-policy` and `--subject-root`. `--tracking-mode external` also needs `--external-provider <ado|github|jira|other>`, so ask that too when the answer is `external`.
+    2. Re-run `spell update` with the flags the CLI printed, filled with the operator's answers, for example `spell update --tracking-mode internal --push-policy guarded`.
+    3. Never pass a flag the operator did not answer. No guessed, default or "recommended" value stands in for an answer. An unanswered question stays unset: the next interactive run asks it, and the next harness run reports it skipped again.
+    4. Never loosen `push_policy` by flag. `--push-policy` only answers an unset question or tightens a recorded policy, and the CLI refuses a loosening. Moving a repository from `blocked` or `guarded` toward `open` is only ever `spell unblock-push`, which the operator runs from an interactive terminal (ARC-034 decision 6, ARC-049 decision 6). Tell them so; do not try to run it for them.
   - **If either axis shows drift, emit the canonical version-drift diagram beside the warning(s)** — per the generated state diagrams convention (rule 8, ARC-036). One commit per *distinct* version value among the three readings, in the order repo-files → installed-CLI → npm-latest; collapse consecutive identical values into a single shared commit rather than repeating it. Branch off immediately after the commit for each axis that drifts — `repo-files` after the repo-files-version commit if axis A drifts, `installed-cli` after the installed-CLI-version commit if axis B drifts. Tag the final commit `"latest"`. The dangling branch(es) *are* the drifting axis/axes — no legend needed:
     ```mermaid
     gitGraph

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-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`).