Complete RALPH-WP-0002 plugin hardening and adoption docs

README.md

@@ -93,6 +93,39 @@ When every task is `done`, Claude also updates the workplan frontmatter to
 
 No state hub, no HTTP calls, no external coordination needed.
 
+## Adoption across coulomb repos
+
+Use ralph-workplan in any repo that already follows ADR-001 workplan files:
+
+```bash
+git clone forgejo-remote:coulomb/ralph-workplan.git ~/ralph-workplan
+cd ~/ralph-workplan && ./install.sh
+# restart Claude Code
+```
+
+Then from a target repo checkout:
+
+```bash
+/ralph-workplan workplans/CUST-WP-0056-daily-todo-md-stale-review.md
+/ralph-workplan workplans/MY-WP-0003-feature.md --max-iterations 15
+```
+
+**Workplan requirements** — see [workplan-spec.md](workplan-spec.md):
+
+- YAML frontmatter with `id`, `title`, `status` (`active` while in progress; `done`/`finished` when complete)
+- One or more fenced ` ```task ` blocks with `id`, `status`, optional `priority`
+- For State Hub–integrated repos: include `state_hub_workstream_id` and per-task `state_hub_task_id`; mark tasks `done` in the file **and** call `update_task_status` in the hub
+
+**`check-done.sh` behavior** — pre-start guard exits 0 only when frontmatter status is `done`/`finished` **and** every task is `done` or `cancel`. Otherwise the skill refuses to start (or continues the loop).
+
+**`--max-iterations`** — default 20. Use 10–15 for small workplans; raise only when tasks are large and file-driven progress is slow. The loop always sets completion promise `HEUREKA`.
+
+Manual check without starting a loop:
+
+```bash
+~/ralph-workplan/plugin/scripts/check-done.sh workplans/MY-WP-0001.md && echo complete || echo incomplete
+```
+
 ## Why not just use `/ralph-loop` directly?
 
 `/ralph-loop` with a static prompt has no awareness of completion state — it

plugin/scripts/check-done.sh

@@ -1,33 +1,26 @@
 #!/bin/bash
-# check-done.sh
-# Exit 0 if the workplan is done, 1 if not.
-# Used as the pre-start guard in the ralph-workplan skill.
-#
-# Usage: check-done.sh <workplan_file>
-
+# check-done.sh — exit 0 when workplan is complete, 1 when work remains, 2 if missing.
 set -euo pipefail
-
 WORKPLAN_FILE="${1:?workplan_file required}"
+[[ -f "$WORKPLAN_FILE" ]] || { echo "❌ Workplan file not found: $WORKPLAN_FILE" >&2; exit 2; }
+python3 - "$WORKPLAN_FILE" <<'PY'
+import re, sys
+from pathlib import Path
 
-if [[ ! -f "$WORKPLAN_FILE" ]]; then
-  echo "❌ Workplan file not found: $WORKPLAN_FILE" >&2
-  exit 2
-fi
-
-# Extract status from YAML frontmatter (first occurrence between --- markers)
-STATUS=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$WORKPLAN_FILE" \
-  | grep '^status:' \
-  | head -1 \
-  | sed 's/status:[[:space:]]*//' \
-  | tr -d '"'"'" )
-
-if [[ -z "$STATUS" ]]; then
-  echo "⚠️  No status field found in frontmatter of: $WORKPLAN_FILE" >&2
-  exit 1
-fi
-
-if [[ "$STATUS" == "done" ]]; then
-  exit 0
-else
-  exit 1
-fi
+path = Path(sys.argv[1])
+text = path.read_text(encoding="utf-8")
+fm = re.search(r"^---\n(.*?)\n---", text, re.S)
+if not fm:
+    print(f"⚠️  No frontmatter in {path}", file=sys.stderr)
+    raise SystemExit(1)
+status_match = re.search(r"^status:\s*(\S+)", fm.group(1), re.M)
+status = (status_match.group(1) if status_match else "").strip('"')
+tasks = re.findall(r"```task\n(.*?)```", text, re.S)
+open_tasks = [
+    t for t in tasks
+    if not re.search(r"^status:\s*(done|cancel)\s*$", t, re.M)
+]
+if status in {"done", "finished"} and not open_tasks:
+    raise SystemExit(0)
+raise SystemExit(1)
+PY

workplans/RALPH-WP-0002-plugin-hardening.md

@@ -4,11 +4,12 @@ type: workplan
 title: "Plugin hardening and adoption docs"
 domain: agents
 repo: ralph-workplan
-status: ready
+status: finished
 owner: codex
 topic_slug: foerster-capabilities
 created: "2026-07-08"
 updated: "2026-07-08"
+state_hub_workstream_id: "97a09113-a439-42d0-a66f-a4d3e7e4bf72"
 ---
 
 # Plugin hardening and adoption docs
@@ -19,8 +20,11 @@ Harden install/check scripts and document adoption path for workplan-driven Ralp
 
 ```task
 id: RALPH-WP-0002-T01
-status: todo
+status: done
 priority: high
+state_hub_task_id: "d6ced27c-d1c5-4d80-bf42-ea61b003f823"
 ```
 
+Result 2026-07-08: Hardened check-done.sh (status + all tasks); README adoption section for coulomb repos and max-iterations guidance.
+
 Document workplan-spec.md requirements, check-done behavior, max-iterations guidance, and cross-repo install notes in README.