arcane-cli 1.7.0 → 1.8.0

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

@@ -213,6 +213,38 @@ Arcane's own repository, a test (`test/up02-d-runtime-placeholders.test.ts`) fai
 `status: active` governance document uses a token that is not in this list. Whether an agent actually
 resolves a listed token from the named source is explicitly advisory prose: no check exercises it.**
 
+## Required operator actions: the `Needs you` block
+
+Some runs end with an action 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. Listed among optional next steps, such an action gets skimmed past. A spell
+whose output can carry one reports it in one fixed block instead:
+
+- **One fixed heading,** `## ⚠ Needs you`, at the very top of the final report, before every other
+  section and before any optional next step.
+- **One line per action:** exactly what to do, then why the agent cannot do it itself.
+- **Never only among optional steps:** an action required for correctness may be repeated under next
+  steps or suggestions, but it always appears in the block.
+- **Omitted when empty:** when nothing needs the operator, the block is left out entirely, never
+  printed as an empty heading or a "None" line.
+
+The block's wording lives in one shared prose fragment (ARC-039), `needs-you`, kept in Arcane's
+source under `.arcane/spells/_fragments/` and never shipped on its own. A spell carries it as a
+`<!-- fragment:needs-you:start -->` / `<!-- fragment:needs-you:end -->` marker pair placed where the
+spell describes its final output or report, and `npm run fix:self-host-parity` expands the fragment
+between the markers. Edit the fragment, never an expanded copy, and never restate its rules by hand
+in a spell body. Required actions also survive the end of a session: `spell-close-session` writes
+the open items into the handoff's `Needs you` field, and `spell-open-session` surfaces that field
+first, above the rest of the handoff, and does not mark the handoff consumed until it has.
+
+**Enforcement: executable check (ARC-023) for the wording — in Arcane's own repository,
+`npm run check:self-host-parity` fails CI when a spell's expanded span differs from the fragment, and
+a test (`test/up04-b-needs-you.test.ts`) fails when the fragment loses its heading, placement or
+omit-when-empty rule, or when a spell in the chosen set loses its span. Which spells carry the span
+is decided by an author's judgment, and whether an agent actually emits the block is explicitly
+advisory prose: no check reads a spell's output.**
+
 ## How to audit a spell
 
 For each dimension, score Bronze/Silver/Gold with one line of evidence. Record the overall (weakest)

package/dist/assets/.arcane/spells/_fragments/needs-you.md

@@ -0,0 +1,14 @@
+**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.

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

@@ -114,6 +114,24 @@ Resolve threads via the provider:
 
 3. `git push` all commits.
 4. Print a summary table of actions taken (category, file, action, commit), thread status (resolved / deferred-with-TODO / needs manual resolution), commits pushed, and next steps (CI, notify reviewer, ready for re-review).
+
+   <!-- 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 -->
+
 5. Optionally post the summary back to the PR as a top-level comment for a durable record.
 
 ## Rules

package/dist/assets/.arcane/spells/spell-adopt-docs.md

@@ -134,6 +134,23 @@ Hard rules for this phase:
 
 ## Phase 4 — 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 -->
+
 Output:
 
 ```

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

@@ -110,6 +110,23 @@ Workflow:
 
 8. **Present for review** — show the architecture and story breakdown to the user.
 
+   <!-- 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:
 - Stories must be right-sized per the methodology doc (not "build the entire dashboard").
 - Architecture decisions must reference existing ADRs when relevant.

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

@@ -120,6 +120,7 @@ In `ai-context/system-prompt-context.md`, replace the existing `## Next Session
 - **Branch:** Output of `git branch --show-current`.
 - **Blockers:** Known unresolved blockers or dependencies. Write "None" if clear.
 - **Pending Verification:** One line per non-`succeeded` item from step 1b: `<what> — <state> — <verification action>`. States: `dispatched`, `pending`, `failed`, `unverifiable` (never list a `succeeded` item here — it belongs in `Last completed step` / TODO.md / the journal instead, worded per the gating above). The verification action is required for `dispatched`, `pending`, and `unverifiable` — "N/A" is only valid for `failed`, where the state is already resolved and there is nothing left to check. Write "None" only if step 1b found every dispatched item resolved to `succeeded` or `failed` before this handoff was written.
+- **Needs you:** One line per action only the operator can take that this session leaves open: `<what to do> — <why the agent cannot do it>`. This block is committed before steps 9–10 run, so write it with them in view and name now the actions they will leave open: the pull request step 9c opens needs a human merge, and when `push_policy` (read it now, per step 9c's push-policy check) is `blocked`, or `guarded` in an autonomous run, the push itself waits on the operator. The closure report's `## ⚠ Needs you` block (step 11) lists the same items, plus any that arose after this handoff was committed. Write "None" when nothing needs the operator. Never leave such an action only in `Blockers`, `Notes` or `Carry Forward`; it may be repeated there, but it always appears here.
 - **Notes:** Anything time-sensitive, fragile, or contextual that would be lost if not stated explicitly. Never the sole carrier of durable content (session handoff durability) — if it names unfinished work, that work must also be registered per step 4b; name its location here.
 ```
 
@@ -175,7 +176,7 @@ Rules:
    - Timeout, cancellation, fallback, or delegated response is not approval. Print the visible authorization downgrade and halt without committing.
 
    c. **Push and open a PR through `spell-commit-work` step 9, including its separate merge gate:**
-   - Run the push-policy check before the push. `spell-commit-work` step 9a runs the same check; run it once per push, not twice. It also governs step 10's remote branch deletions. If it stops the push, end the session with the commits local and report them in the PR Readiness section as not pushed.
+   - Run the push-policy check before the push. `spell-commit-work` step 9a runs the same check; run it once per push, not twice. It also governs step 10's remote branch deletions. If it stops the push, end the session with the commits local and report them in the PR Readiness section as not pushed, and in the step 11 report's `## ⚠ Needs you` block.
 
      <!-- fragment:push-policy-check:start -->
      **Push-policy check (ARC-049) — before any push.** Read `push_policy` from the repository's `.arcane.json` at the repository root (a self-hosted source repository with no root manifest keeps it in `src/assets/.arcane.json` when that file declares `selfHosted: true`). An absent file or an absent field means `open`. The check covers every push this spell makes: a branch push, a `--force-with-lease` push, and a remote branch deletion (`git push <remote> --delete <branch>`).
@@ -225,6 +226,23 @@ Rules:
 
 Output format:
 
+<!-- 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 -->
+
 ## Session Closure
 
 - Summary of what was completed.

package/dist/assets/.arcane/spells/spell-commit-work.md

@@ -256,6 +256,23 @@ Workflow:
 
 Output format after execution:
 
+<!-- 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 -->
+
 ## Commit Complete
 
 ```

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

@@ -200,6 +200,23 @@ so they need no edit.
 
 ## 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 created: <URL>
   Title:     <title>

package/dist/assets/.arcane/spells/spell-eas-store-deploy.md

@@ -234,6 +234,29 @@ console error stating otherwise (`EV-06`).
 - **Locale lists differ between the stores.** Release notes are per-language; resolve locale coverage
   against each store's own catalogue rather than copying the other store's list (`MR-06`).
 
+### Reporting the release
+
+End every release run with a short report. The store-console steps the agent cannot reach — sending
+staged Google Play changes for review, answering an App Store review question, confirming a manual
+release — are required operator actions:
+
+<!-- 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

package/dist/assets/.arcane/spells/spell-full-cycle.md

@@ -184,6 +184,24 @@ Execute the `spell-ship` workflow:
    applies (state "Nothing withheld" in that case). Fold it into the consumer repo's own QA checklist
    so a human reviewer sees exactly what still needs a human look, not just what passed (2026-07-22
    dogfooding finding: honest disclosure of sandbox limits, not just of failures).
+
+   <!-- 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 -->
+
 4. Create the PR:
    - `external/ado` mode: `az repos pr create --repository {repo} --source-branch {branch} --target-branch main --title "{feature}" --work-items {adoWorkItemId}`
    - `internal` mode (or provider TODO mode): create PR without `--work-items`.

package/dist/assets/.arcane/spells/spell-make-discoverable.md

@@ -250,6 +250,23 @@ just because nothing threw an error.
 
 ## Phase 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 -->
+
 Summarize what changed, what's still open, and close with a plain-language,
 user-verifiable acceptance checklist:
 

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

@@ -36,6 +36,7 @@ Use these files first:
 Check `ai-context/system-prompt-context.md` for a `## Next Session Handoff` section.
 
 - If present and **not yet marked consumed** (no `> ✓ Consumed:` line): surface it immediately as `## Picking Up From Last Session` at the very top of your output, before all other sections — include `Last completed step`, `Blockers`, and `Notes` verbatim alongside the rest (session handoff durability: these three are written by close-session but were previously never read back). Use the `Next concrete action` field as the first item in `## Next Session Plan`. Use the `Active task`, `Active files`, and `Branch` fields to pre-populate the State Snapshot.
+- **The handoff's `Needs you` field comes first.** If it lists anything other than "None", surface every item in the `## ⚠ Needs you` block (see the output structure below) **above** `## Picking Up From Last Session`, the one exception to "before all other sections" in the bullet above. Where you can check an item (a pull request's merge state, whether a branch was pushed), check it: an item the operator has already done leaves the block and is noted as done under `## Picking Up From Last Session` (that counts as surfaced); keep every item you cannot check. A handoff written before this field existed has no `Needs you` line; treat it as "None". Do not mark the handoff consumed until every listed item has been surfaced: a handoff whose `Needs you` items were not surfaced stays unconsumed, so the next open-session surfaces them again.
 - **If the handoff's `Pending Verification` field lists anything other than "None" (EF-21):** surface each listed item explicitly, then actively re-check its current status (per the item's stated verification action) rather than treating the state recorded at close-session time as still current — a `dispatched`/`pending` item may have since succeeded, failed, or still be running, and carrying it forward as inert text would repeat the exact failure mode this field exists to prevent. Report what you found (resolved succeeded / resolved failed / still pending / still unverifiable) before relying on anything downstream that depended on it.
 - After surfacing it, apply the Mutation Guard below, then run the **Durability check** (session handoff durability, ARC-040): confirm that an incomplete `Active task`, the `Next concrete action`, and any task-bearing `Notes` content each name a durable location that genuinely exists (the cited `TODO.md` item — by stable locator, not a line number that may have already drifted — or tracker work item). If a named location is missing, or close-session's own step 4b was skipped when it shouldn't have been, register the missing content now — on this session's own branch — before proceeding. Only then append `> ✓ Consumed: YYYY-MM-DD` (today's date); the marker write is a repository mutation. If the Durability check cannot complete, leave the handoff unconsumed so the next open-session retries the same check idempotently, rather than silently losing the gap.
 - If the section is absent or already marked consumed: skip this step and proceed with the normal workspace scan.
@@ -67,6 +68,23 @@ Run the `spell-check-drift` spell first, before building the state snapshot or g
 
 Then produce output in this exact structure:
 
+<!-- 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 -->
+
 ## Workspace Health Check
 
 Before anything else, check:

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-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/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

package/package.json

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