arcane-cli 1.18.0 → 1.20.0

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

@@ -252,22 +252,35 @@ 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:
+<!-- fragment:action-required:start -->
+**Action required — what only the operator can do.** When this run leaves an action that only the operator can take, report it in one block at the very top of the final report, before every other section and before any optional next step. The block exists because these are the operator's decisions to make, not because the agent is stuck: write it as a hand-off of authority, never as a plea for help. Frame it with a horizontal rule above and below, so it stands apart in a terminal as well as on a rendered page:
 
 ```markdown
-## ⚠ Needs you
+---
+
+## 🚧 Action required
+
+**Now**
+
+- <exactly what to do: the command, the link, or the question> — <why only the operator can do it>
 
-- <exactly what to do: the command, the link, or the question> — <why the agent cannot do it itself>
+**When you're at your desk**
+
+- <exactly what to do> — <why only the operator can do it>
+
+---
 ```
 
-- **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".
+- **What belongs in it:** 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. 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.
+- **Two tiers, one block.** **Now** holds what the work is not correct or complete without. **When you're at your desk** holds what only the operator can do but that can wait: a permission rule, a leftover remote branch, a credential to set up. Leave out a tier that has nothing in it; never split the tiers into two blocks.
+- **One line per action.** Say exactly what to do, then, after the dash, why only the operator can 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.
+- **Done items stay, struck through.** Within one session, once an item has been listed, keep it in every later report of the block; when the operator has done it, strike it through (`~~<the line>~~`) rather than dropping it, so progress shows and nothing disappears silently. The session's close carries only the open items forward.
+- **Omit it when empty.** When nothing is left for the operator and nothing was struck through this session, leave the block out entirely: no heading, no rules 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.
+- **Report the Now tier to the presence channel.** When the **Now** tier has open items, also run `spell presence report --status waiting --required-action "<line 1>" --required-action "<line 2>"`, one flag per open line of that tier; the other tier is not blocking and is not reported. With no presence channel configured on this machine the command prints nothing and exits 0, so the block itself and the rest of the run are unchanged.
 - 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 -->
+<!-- fragment:action-required:end -->
 
 Present the execution plan to the user. Ask:
 1. Does the epic split make sense?

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

@@ -97,22 +97,35 @@ 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:
+   <!-- fragment:action-required:start -->
+   **Action required — what only the operator can do.** When this run leaves an action that only the operator can take, report it in one block at the very top of the final report, before every other section and before any optional next step. The block exists because these are the operator's decisions to make, not because the agent is stuck: write it as a hand-off of authority, never as a plea for help. Frame it with a horizontal rule above and below, so it stands apart in a terminal as well as on a rendered page:
 
    ```markdown
-   ## ⚠ Needs you
+   ---
 
-   - <exactly what to do: the command, the link, or the question> — <why the agent cannot do it itself>
+   ## 🚧 Action required
+
+   **Now**
+
+   - <exactly what to do: the command, the link, or the question> — <why only the operator can do it>
+
+   **When you're at your desk**
+
+   - <exactly what to do> — <why only the operator can do it>
+
+   ---
    ```
 
-   - **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".
+   - **What belongs in it:** 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. 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.
+   - **Two tiers, one block.** **Now** holds what the work is not correct or complete without. **When you're at your desk** holds what only the operator can do but that can wait: a permission rule, a leftover remote branch, a credential to set up. Leave out a tier that has nothing in it; never split the tiers into two blocks.
+   - **One line per action.** Say exactly what to do, then, after the dash, why only the operator can 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.
+   - **Done items stay, struck through.** Within one session, once an item has been listed, keep it in every later report of the block; when the operator has done it, strike it through (`~~<the line>~~`) rather than dropping it, so progress shows and nothing disappears silently. The session's close carries only the open items forward.
+   - **Omit it when empty.** When nothing is left for the operator and nothing was struck through this session, leave the block out entirely: no heading, no rules 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.
+   - **Report the Now tier to the presence channel.** When the **Now** tier has open items, also run `spell presence report --status waiting --required-action "<line 1>" --required-action "<line 2>"`, one flag per open line of that tier; the other tier is not blocking and is not reported. With no presence channel configured on this machine the command prints nothing and exits 0, so the block itself and the rest of the run are unchanged.
    - 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 -->
+   <!-- fragment:action-required:end -->
 
 7. **Request human approval** — present the ship report and wait for explicit approval.
 

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

@@ -110,7 +110,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.
+  - First, the `## 🚧 Action required` 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.
@@ -172,22 +172,35 @@ 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:
+<!-- fragment:action-required:start -->
+**Action required — what only the operator can do.** When this run leaves an action that only the operator can take, report it in one block at the very top of the final report, before every other section and before any optional next step. The block exists because these are the operator's decisions to make, not because the agent is stuck: write it as a hand-off of authority, never as a plea for help. Frame it with a horizontal rule above and below, so it stands apart in a terminal as well as on a rendered page:
 
 ```markdown
-## ⚠ Needs you
+---
+
+## 🚧 Action required
+
+**Now**
+
+- <exactly what to do: the command, the link, or the question> — <why only the operator can do it>
 
-- <exactly what to do: the command, the link, or the question> — <why the agent cannot do it itself>
+**When you're at your desk**
+
+- <exactly what to do> — <why only the operator can do it>
+
+---
 ```
 
-- **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".
+- **What belongs in it:** 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. 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.
+- **Two tiers, one block.** **Now** holds what the work is not correct or complete without. **When you're at your desk** holds what only the operator can do but that can wait: a permission rule, a leftover remote branch, a credential to set up. Leave out a tier that has nothing in it; never split the tiers into two blocks.
+- **One line per action.** Say exactly what to do, then, after the dash, why only the operator can 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.
+- **Done items stay, struck through.** Within one session, once an item has been listed, keep it in every later report of the block; when the operator has done it, strike it through (`~~<the line>~~`) rather than dropping it, so progress shows and nothing disappears silently. The session's close carries only the open items forward.
+- **Omit it when empty.** When nothing is left for the operator and nothing was struck through this session, leave the block out entirely: no heading, no rules 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.
+- **Report the Now tier to the presence channel.** When the **Now** tier has open items, also run `spell presence report --status waiting --required-action "<line 1>" --required-action "<line 2>"`, one flag per open line of that tier; the other tier is not blocking and is not reported. With no presence channel configured on this machine the command prints nothing and exits 0, so the block itself and the rest of the run are unchanged.
 - 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 -->
+<!-- fragment:action-required:end -->
 
 ```
 ✓ PR synced: <URL>

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

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

package/dist/assets/schemas/presence.schema.json

@@ -15,7 +15,7 @@
     "task",
     "message",
     "status",
-    "needs_you",
+    "required_actions",
     "started_at",
     "reported_at",
     "ended_at",
@@ -73,11 +73,11 @@
       ],
       "description": "working: a spell is running; waiting: the session asked the operator for something; blocked: cannot proceed for an external reason; idle: open, no spell running; done: ended (set by end only)."
     },
-    "needs_you": {
+    "required_actions": {
       "type": "array",
       "maxItems": 20,
       "items": {
-        "$ref": "#/$defs/needsYou"
+        "$ref": "#/$defs/requiredAction"
       }
     },
     "started_at": {
@@ -216,7 +216,7 @@
         }
       }
     },
-    "needsYou": {
+    "requiredAction": {
       "type": "object",
       "additionalProperties": false,
       "required": [
@@ -227,7 +227,7 @@
         "action": {
           "type": "string",
           "maxLength": 256,
-          "description": "Exactly what the operator must do: one line of a '## ⚠ Needs you' block.",
+          "description": "Exactly what the operator must do: one line of a '## 🚧 Action required' block.",
           "minLength": 1
         },
         "reason": {
@@ -390,14 +390,33 @@
           "maxLength": 256,
           "description": "Absent keeps the stored value; null clears it."
         },
-        "needs_you": {
+        "required_actions": {
           "type": "array",
           "maxItems": 20,
           "items": {
-            "$ref": "#/$defs/needsYou"
+            "$ref": "#/$defs/requiredAction"
           },
           "description": "Replaces the stored list on every report; absent means []. More than 20 entries is refused with 400, never cut."
+        },
+        "needs_you": {
+          "type": "array",
+          "maxItems": 20,
+          "items": {
+            "$ref": "#/$defs/requiredAction"
+          },
+          "deprecated": true,
+          "description": "The name of required_actions before 1.20 (ARC-060 decision 14), accepted as required_actions for the 1.20 series. Never sent together with required_actions: a body with both is refused with 400 naming needs_you."
         }
+      },
+      "not": {
+        "properties": {
+          "required_actions": true,
+          "needs_you": true
+        },
+        "required": [
+          "required_actions",
+          "needs_you"
+        ]
       }
     },
     "end": {
@@ -528,7 +547,7 @@
       }
     },
     "event": {
-      "description": "One change on GET /v0/events: the event name and the full record after the change. Exactly one event per accepted report, by the precedence started > resumed > needs_you > updated (architecture D5). The record is the truth and the event name is why it was sent: a consumer that alerts on 'needs you' reads the record's needs_you, because a first or a resumed report can carry lines under another event name.",
+      "description": "One change on GET /v0/events: the event name and the full record after the change. Exactly one event per accepted report, by the precedence started > resumed > action_required > updated (architecture D5). The record is the truth and the event name is why it was sent: a consumer that alerts on 'action required' reads the record's required_actions, because a first or a resumed report can carry lines under another event name.",
       "type": "object",
       "additionalProperties": false,
       "required": [
@@ -540,7 +559,7 @@
           "enum": [
             "session.started",
             "session.updated",
-            "session.needs_you",
+            "session.action_required",
             "session.stale",
             "session.resumed",
             "session.ended",