@paleo/alcode 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paleo/alcode",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "Run a coding agent through AlignFirst protocols.",

package/templates/cli-reference.md

@@ -38,6 +38,8 @@ For large work, do not rush. Decompose it yourself only when the concerns are tr
 3. **Execute** — `alcode --new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"`. The agent implements and writes a summary file. When executing a main plan that spans several sub-plans and the working tree is clean, append to the message: *"Feel free to commit between each plan."*
 4. **Commit** — use the suggested commit message from the spec file.
 
+Run the chain end to end. The plan is a step of the implementation, not a checkpoint for your user to clear: the moment it's written, launch the execution.
+
 ## Light workflow (AAD)
 
 For one-shot changes or follow-up adjustments right after executing a plan. The agent investigates, discusses, then implements in one session.
@@ -48,11 +50,20 @@ alcode --new --protocol aad --ticket AB-123 --message "Task description"
 
 Answer questions as in the spec flow. The agent implements and writes a summary file, which carries a suggested commit message.
 
+## Review workflow
+
+Two fresh sessions: one reviews, one fixes.
+
+1. **Review** — `alcode --new --protocol review --ticket AB-123`. The agent reviews the current branch against the base branch and writes a review file; its path is in the run's result. The base defaults to the repository's default branch; override it via `--message "Base branch: \`develop\`"`.
+2. **Fix** (optional) — `alcode --new --protocol aad --ticket AB-123 --message "Here is a code review: \`.plans/AB-123/B1-review.md\`. What should we fix?"` (adapt the path). The agent proposes fixes; decide together what to fix, as in any AAD session, then it implements and writes a summary file.
+
+Skip the fix step when the review is informational.
+
 ## Other protocols
 
 - **description** — `alcode --new --protocol description --ticket AB-123`. Writes a PR/MR description for committed work. No discussion.
 - **read** — `alcode --new --protocol read --ticket AB-123 [--message "..."]`. Loads the ticket's spec and summary files into context; with a message, answers it against that context.
-- **review** — `alcode --new --protocol review --ticket AB-123`. Reviews the current branch against the base and writes a review file.
+- **review** — see the review workflow above.
 - **merge** — `alcode --new --protocol merge --ticket AB-123`. Resolves conflicts and summarizes tricky resolutions. Pass the incoming branch via `--message` to start the merge.
 
 ## Answering agent questions

package/templates/generic-guide.md

@@ -16,6 +16,8 @@ Read the run's session file (the path `alcode` prints on its first line, under `
 
 An `exitReason` of `auth_required` in the frontmatter (alcode also exits `2`) means the coding agent is not authenticated on the host: an administrator must re-login there before any run can succeed. Report that and do not retry.
 
-Do **not** re-verify the repo, re-run the agent, or inspect `git` — the session file is authoritative. Keep session files in place; they are the durable audit trail.
+Don't reconstruct what happened: no re-running the agent, no `git` archaeology to double-check its account — the session file is authoritative for that. Do verify that the result works, though. Run the project's checks (tests, lint, build) and exercise the change yourself before calling it done; a failing check reopens the work in a new session.
+
+Keep session files in place; they are the durable audit trail.
 
 {{CLI_REFERENCE}}

package/templates/openclaw-guide.md

@@ -21,7 +21,7 @@ Under OpenClaw, background it through the `exec` tool:
 - The session-file path comes from the run's first stdout line (`Session file: …`), available via `process log <id>`. The stamp in the file name is the run's start time; it cannot be derived from the clock.
 - `--meta` is for one case only: a **Discord** thread **you created yourself** this turn via `message` `action: "thread-create"`. There, the completion wake's plain reply would go to the channel, so add `--meta "<THREAD_ID>"` with that thread's `chat_id`; the wake then reports back into the thread via `message` `action: "thread-reply"`. In **every other case — always on Slack, and on Discord when the session is already thread-bound — omit `--meta`.** Slack auto-threads plain replies and exposes no `send`/`thread-reply` action, so a `--meta` there makes the wake attempt an unsupported `message` send that fails; a thread-bound session already replies in its own thread.
 
-As soon as the run is backgrounded, tell the user — in the user's language — that the coding agent is now working in the background and that you will report back when it finishes (e.g. *"The coding agent is running in the background — I'll let you know as soon as it's done."*). Deliver this "started" ack exactly like the completion report below: if you set `--meta` (a Discord thread you created this turn), the ack is a `message` `action: "thread-reply"` carrying that thread's `threadId` — your free-form text would stream to the parent channel. In every other case — always on Slack, and on a thread-bound Discord session — the ack is your plain text; do **not** also post it via `message`, that double-posts. Then go available. Do **not** poll.
+As soon as the run is backgrounded, tell the user — in the user's language — that the coding agent is now working in the background and that you will report back when it finishes (e.g. *"The coding agent is running in the background — I'll let you know as soon as it's done."*). Post it even when the user asked to be notified only at completion: this line is the promise of exactly that, not an interruption — a launch with no ack reads as a session gone silent. Deliver this "started" ack exactly like the completion report below: if you set `--meta` (a Discord thread you created this turn), the ack is a `message` `action: "thread-reply"` carrying that thread's `threadId` — your free-form text would stream to the parent channel. In every other case — always on Slack, and on a thread-bound Discord session — the ack is your plain text, and you **end the turn on it**: only your final message is guaranteed to post, so the ack must be the last thing you write, with no tool call after it. Do **not** also post it via `message` (that double-posts), and do **not** poll.
 
 Every run writes a session file under `.plans/`: `.plans/<ticket>/_alcode/<stamp>.md`, or `.plans/_alcode/<stamp>.md` without a ticket. This file is the durable record of the run. Its frontmatter carries `status` (`running` → `succeeded`/`failed`) and the `sessionId`, and the `---- Result ----` block holds the outcome.
 
@@ -31,17 +31,21 @@ Every run writes a session file under `.plans/`: `.plans/<ticket>/_alcode/<stamp
 
 The chained wake fires when the backgrounded `alcode` exits: this session receives a heartbeat, usually as a plain heartbeat poll with no message text (the wake text is often dropped in transit). A run counts as pending while it is running **and until its outcome is reported**.
 
-**First, decide whether this heartbeat needs a report.** A heartbeat is the completion wake only while a run is pending. Once you have already reported a run's outcome, later heartbeats for it — a single run can wake you more than once, since the platform's own exec-exit notice may fire on top of the chained wake — need nothing: end the turn with a final answer of exactly `NO_REPLY`. Never `HEARTBEAT_OK`: it is not swallowed, it posts as literal text where the user reads. Whenever a heartbeat turn has nothing new to say, the answer is `NO_REPLY`, never `HEARTBEAT_OK`.
+**First, decide whether this heartbeat needs a report.** A heartbeat is the completion wake only while a run is pending. Once you have already reported a run's outcome, later heartbeats for it — a single run can wake you more than once, since the platform's own exec-exit notice may fire on top of the chained wake — need nothing: end the turn with a final answer of exactly `NO_REPLY`. The token suppresses delivery only when it is the entire answer; any prose around it ("nothing new to add. NO_REPLY") posts verbatim where the user reads. Never `HEARTBEAT_OK`: it is not swallowed either. Whenever a heartbeat turn has nothing new to say, the answer is `NO_REPLY`, alone.
 
 Any heartbeat received while an `alcode` run is **still pending** (running, or finished but not yet reported) is the completion wake — do exactly this:
 
 1. **Read the run's session file** (the path `alcode` printed on its first line, under `_alcode/`). Its frontmatter holds `status` (`succeeded` / `failed`) and the session id; the `---- Result ----` block holds the outcome. If you set `meta` at launch, it is there too.
-2. **Report the outcome to the user** where the work was requested. Send one concise message: succeeded or failed, plus a one-line summary of the result for the audience. Two cases:
-   - The frontmatter `meta` carries a destination (a Discord thread target): send the report there with `message` `action: "thread-reply"` (never `action: "send"`), then end the wake turn with a final answer of exactly `NO_REPLY` — any other final text streams to the channel as a stray duplicate.
-   - No `meta` destination (always the case on Slack, and on a thread-bound Discord session): the work was requested on this session's own surface, so **the report itself is your plain-text final reply** — just write it, no `message` tool. On Slack it auto-threads back to the right thread. Never end such a wake turn silently.
+2. **Verify, then report — one message that ends the turn.** Run the verification your platform's instructions prescribe (keep it quick), then report, in the user's language, where the work was requested:
 
-   A wake turn ends with the report or with exactly `NO_REPLY` — nothing else, ever, and never `HEARTBEAT_OK`. `NO_REPLY` is the ending after a `message`-tool report (the report is already delivered) and for any wake with nothing new to report.
-3. Do **not** re-verify the repo, re-run the coding agent, fetch/merge branches, or inspect `git`. The coding agent already did the work and the session file is authoritative. Relay its outcome, nothing more.
+   `Coding run {succeeded | failed} — the agent reports: {one-line summary of the Result block}. {What you verified.}`
+
+   The report must be the turn's **final message**: text written between tool calls may never post, and ending the turn on `NO_REPLY` after a completed run reports nothing at all. Two delivery cases:
+   - The frontmatter `meta` carries a destination (a Discord thread target): post it with `message` `action: "thread-reply"` (never `action: "send"`), then end the turn with a final answer of exactly `NO_REPLY`. Free-form text would stream to the channel as a stray duplicate.
+   - No `meta` destination (always the case on Slack, and on a thread-bound Discord session): the work was requested on this session's own surface, so **your plain text is the report** — write it as the turn's ending, no `message` tool, no tool call after it. On Slack it auto-threads back to the right thread. Never end such a wake turn silently.
+3. **Don't reconstruct what happened.** Verifying the result is the platform's prescribed step; re-deriving the run's story is not: no re-running the coding agent, no fetch/merge, no `git` archaeology to double-check its account — the session file is authoritative for that.
+
+Reporting the run is not calling the work done: the report relays the agent's claim plus what you verified. When your verification finds a failing check, the report says so, and the fix is new work — a fresh run with its own completion wake; the wake you were answering is discharged by your report.
 
 If the session file says the run failed, report that plainly and propose the next step; don't silently retry. When a session turns bad, keep everything in place — session files, directories, and records are the durable audit trail; never delete them; just start a new session.