From d573c14998b6ae5a4bd3cff9701f3364b45efa92 Mon Sep 17 00:00:00 2001
From: Rodin <rodin@forgedthought.ai>
Date: Fri, 15 May 2026 01:03:04 -0700
Subject: [PATCH] fix(docs): address review feedback on architecture clarity
 and path consistency

- Clarify SPAWN exits vs HANDOFF continues in architecture diagram (S1)
- Add 'read' to toolsAllow in architecture snippet to match cron config (G2)
- Rephrase safety invariant 6 to clarify workers may push/manage labels (G3)
- Add reserved Rule 1 placeholder to explain numbering gap (S2)
- Clarify Rule 10 skip behavior for already-assigned PRs (S3)
- Standardize invariants checker path to full workspace path (G4/G5)
- Add note explaining SKILL.md deployment to workspace path (G1)
---
 SKILL.md              | 10 ++++++----
 docs/dev-loop-spec.md |  6 +++---
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/SKILL.md b/SKILL.md
index e439774..815dfad 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -8,15 +8,15 @@ It lives in the repo so changes are version-controlled alongside the code.
 Dispatch is a **pure shell script** — no model reasoning.
 
 ```
-Cron (agentTurn, toolsAllow: [exec, sessions_spawn])
+Cron (agentTurn, toolsAllow: [exec, sessions_spawn, read])
   → runs dispatch script
   → reads output for SPAWN or HANDOFF lines
   → spawns worker if instructed
 
 Dispatch script  (~/.openclaw/workspace/scripts/dev-loop-dispatch.sh)
   → pure bash, all decisions are curl API calls + branches
-  → exits after one SPAWN action per pass
-  → may emit multiple HANDOFFs in one pass
+  → exits after emitting one SPAWN line (at most one worker per run)
+  → emits HANDOFF for each qualifying PR (does not exit after HANDOFF)
 
 Workers (Opus, spawned by cron model)
   → receive precise task description
@@ -34,7 +34,7 @@ The model **never** assesses project state or makes dispatch decisions.
 3. **WIP mutex** — one active worker per repo; WIP label gates new issue pickup
 4. **One SPAWN per run** — script emits at most one SPAWN line per execution
 5. **set -euo pipefail** — any curl failure aborts immediately, no partial actions
-6. **Workers reply NO_REPLY** — no announcements, no handoffs, no side effects
+6. **Workers reply NO_REPLY** — no dispatch-level side effects (workers may push changes and manage labels as part of their task)
 
 ## Dispatch Rules (in order)
 
@@ -42,6 +42,7 @@ The model **never** assesses project state or makes dispatch decisions.
 |------|-----------|--------|
 | 0 | WIP label > 1hr old | Remove stale WIP, continue |
 | 0b | WIP label ≤ 1hr old | Mark ACTIVE_WIP=1, continue (only gates Rule 10) |
+| _(1)_ | _(reserved — intentionally unused)_ | — |
 | 2 | Any reviewer has REQUEST_CHANGES | SPAWN:findings |
 | 3 | PR not mergeable | SPAWN:rebase |
 | 4 | CI failure, no fix plan | SPAWN:ci-fix |
@@ -99,6 +100,7 @@ Key fields:
     If no SPAWN line in output, reply NO_REPLY.
 
     See ~/.openclaw/workspace/skills/dev-loop/SKILL.md for full instructions.
+    (This repo's SKILL.md is deployed to that workspace path.)
   model: hai-anthropic/anthropic--claude-4.5-haiku
   toolsAllow: [exec, sessions_spawn, read]
 ```
diff --git a/docs/dev-loop-spec.md b/docs/dev-loop-spec.md
index 9e56435..226b511 100644
--- a/docs/dev-loop-spec.md
+++ b/docs/dev-loop-spec.md
@@ -204,7 +204,7 @@ If all current:
 - Emit `HANDOFF:<pr_num>`
 - Continue evaluating remaining PRs (do NOT exit)
 
-If already assigned to `aweiker`: skip.
+If already assigned to `aweiker`: skip (assume handoff was already performed; continue to next PR without emitting another HANDOFF).
 
 ### Rule 11: New Issue Pickup
 
@@ -219,7 +219,7 @@ Claim the issue (assign to bot user to prevent double-pick), then:
 
 ## 6. Safety Invariants
 
-These are statically checked by `test/check-invariants.sh` and enforced in all changes:
+These are statically checked by `~/.openclaw/workspace/scripts/test/check-invariants.sh` and enforced in all changes:
 
 | ID | Invariant |
 |----|-----------|
@@ -268,7 +268,7 @@ Workers **always** remove the WIP label on completion and reply `NO_REPLY`.
 ## 9. Fixes for Issues #144 and #145
 
 **Issue #144** (autonomous merge):
-The dispatch script contains no merge API calls anywhere. The `scripts/test/check-invariants.sh`
+The dispatch script contains no merge API calls anywhere. The `~/.openclaw/workspace/scripts/test/check-invariants.sh`
 invariant `S1` verifies this. Workers do not receive merge instructions.
 
 **Issue #145** (merged despite REQUEST_CHANGES):