@flavor-code/superharness 1.0.0

package/scripts/ralph-lib.sh

@@ -0,0 +1,366 @@
+#!/usr/bin/env bash
+# Ralph state mechanism — zero-dependency bash state library (macOS / Linux).
+# Counterpart of scripts/ralph-lib.ps1.
+#
+# Manages the four runtime files of a resumable autonomous-task loop, all under
+# <project>/<state-root>/superharness/ralph/ where <state-root> follows the host:
+#   .claude  (Claude Code install: .claude/superharness marketplace)
+#   .flavor  (flavor-code install: .flavor/plugins/superharness)
+#   .current-task      one-line pointer to the active task (switch = rewrite the line)
+#   task.json          task-list snapshot {status,phase,sprint,tasks[],updated_at}
+#   trace.jsonl        append-only ledger, one {ts,phase,event,detail} JSON per line
+#   .ralph-state.json  retry counter {retries,max,updated_at}, capped at 5
+#
+# Source this file to use the functions. The trace hooks (hooks/stop.sh,
+# hooks/user-prompt-submit.sh) source it for go task tracking. Conventions:
+# UTF-8 without BOM, atomic temp-then-move for JSON snapshots, ISO-8601 timestamps.
+#
+# JSON handling needs node (preferred) or python3 as a fallback.
+
+# ---------------------------------------------------------------- json helper
+
+ralph_json_escape() {
+    # $1 = raw string -> prints JSON-escaped content WITHOUT surrounding quotes.
+    local __raw="$1"
+    if command -v node >/dev/null 2>&1; then
+        RALPH_ESC="$__raw" node -e 'process.stdout.write(JSON.stringify(process.env.RALPH_ESC).slice(1,-1))'
+    elif command -v python3 >/dev/null 2>&1; then
+        RALPH_ESC="$__raw" python3 -c 'import json,os;print(json.dumps(os.environ["RALPH_ESC"])[1:-1],end="")'
+    else
+        # minimal fallback: backslash then double quote
+        printf '%s' "${__raw//\\/\\\\}" | sed 's/"/\\"/g' | awk '{if(NR>1)printf "\\n";printf "%s",$0}'
+    fi
+}
+
+ralph_json_get() {
+    # $1 = file  $2... = property path (top-level keys only, one per arg)
+    # Prints the value as text (objects/arrays as JSON), nothing when absent.
+    local __f="$1"; shift
+    [ -f "$__f" ] || return 0
+    if command -v node >/dev/null 2>&1; then
+        node -e '
+            const fs=require("fs");
+            let o; try{o=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));}catch{process.exit(0);}
+            let v=o;
+            for(let i=2;i<process.argv.length;i++){ if(v==null||typeof v!=="object"){process.exit(0);} v=v[process.argv[i]]; }
+            if(v===undefined||v===null) process.exit(0);
+            process.stdout.write(typeof v==="object"?JSON.stringify(v):String(v));
+        ' "$__f" "$@"
+    elif command -v python3 >/dev/null 2>&1; then
+        python3 - "$__f" "$@" <<'PY'
+import json,sys
+try:
+    o=json.load(open(sys.argv[1],encoding="utf-8"))
+except Exception:
+    sys.exit(0)
+v=o
+for k in sys.argv[2:]:
+    if not isinstance(v,dict) or k not in v: sys.exit(0)
+    v=v[k]
+if v is None: sys.exit(0)
+print(json.dumps(v) if isinstance(v,(dict,list)) else v,end="")
+PY
+    fi
+}
+
+# ---------------------------------------------------------------- paths & helpers
+
+ralph_parse_hook_stdin() {
+    # Parse hook input JSON from stdin. Writes the `cwd` and `prompt` fields to two
+    # temp files and sets RALPH_HOOK_CWD_FILE / RALPH_HOOK_PROMPT_FILE. Returns 1
+    # when stdin is empty or not valid JSON. Needs node or python3.
+    local raw
+    raw="$(cat || true)"
+    printf '%s' "$raw" | grep -q '[^[:space:]]' || return 1
+    local tmpdir="${TMPDIR:-/tmp}"
+    RALPH_HOOK_CWD_FILE="$tmpdir/ralph-hook-cwd.$$"
+    RALPH_HOOK_PROMPT_FILE="$tmpdir/ralph-hook-prompt.$$"
+    if command -v node >/dev/null 2>&1; then
+        printf '%s' "$raw" | RALPH_CWD_F="$RALPH_HOOK_CWD_FILE" RALPH_PROMPT_F="$RALPH_HOOK_PROMPT_FILE" node -e '
+            const fs = require("fs");
+            let s = "";
+            process.stdin.setEncoding("utf8");
+            process.stdin.on("data", d => { s += d; });
+            process.stdin.on("end", () => {
+                let o;
+                try { o = JSON.parse(s); } catch { process.exit(1); }
+                fs.writeFileSync(process.env.RALPH_CWD_F, typeof o.cwd === "string" ? o.cwd : "");
+                fs.writeFileSync(process.env.RALPH_PROMPT_F, typeof o.prompt === "string" ? o.prompt : "");
+            });
+        ' || return 1
+    elif command -v python3 >/dev/null 2>&1; then
+        printf '%s' "$raw" | RALPH_CWD_F="$RALPH_HOOK_CWD_FILE" RALPH_PROMPT_F="$RALPH_HOOK_PROMPT_FILE" python3 -c '
+import json, os, sys
+try:
+    o = json.load(sys.stdin)
+except Exception:
+    sys.exit(1)
+cwd = o.get("cwd") if isinstance(o.get("cwd"), str) else ""
+prompt = o.get("prompt") if isinstance(o.get("prompt"), str) else ""
+open(os.environ["RALPH_CWD_F"], "w", encoding="utf-8").write(cwd)
+open(os.environ["RALPH_PROMPT_F"], "w", encoding="utf-8").write(prompt)
+' || return 1
+    else
+        return 1
+    fi
+}
+
+ralph_cleanup_hook_stdin() {
+    rm -f "${RALPH_HOOK_CWD_FILE:-}" "${RALPH_HOOK_PROMPT_FILE:-}" 2>/dev/null || true
+}
+
+ralph_state_root() {
+    # Host detection: this library ships inside the host install, so its own path
+    # names the state root. SUPERHARNESS_STATE_ROOT ('.claude' | '.flavor') forces
+    # a choice for unusual layouts; Claude Code is the historical default.
+    case "${SUPERHARNESS_STATE_ROOT:-}" in
+        .flavor|flavor) printf '%s' '.flavor'; return ;;
+        .claude|claude) printf '%s' '.claude'; return ;;
+    esac
+    local self="${BASH_SOURCE[0]:-$0}" dir
+    dir="$(cd "$(dirname "$self")" 2>/dev/null && pwd)" || dir=""
+    case "$dir" in
+        */.flavor/plugins/superharness/scripts) printf '%s' '.flavor' ;;
+        *) printf '%s' '.claude' ;;
+    esac
+}
+
+ralph_dir() { printf '%s/%s/superharness/ralph' "$1" "$(ralph_state_root)"; }
+
+ralph_iso() { date -u '+%Y-%m-%dT%H:%M:%S+00:00'; }
+
+ralph_go_invocation() {
+    # Parse a UserPromptSubmit prompt. If it is a `/superharness:go <goal>` invocation
+    # (leading slash optional, must be at the start of the prompt), print two lines:
+    #   line 1: Goal
+    #   line 2: Slug='YYYY-MM-DD-<kebab|task-HHmmss>'
+    # Returns 1 when the prompt is not a go invocation. Pure.
+    # Portable across GNU sed and BSD sed (macOS).
+    local prompt="$1"
+    printf '%s' "$prompt" | grep -qE '^[[:space:]]*/?superharness:go([^A-Za-z0-9_]|$)' || return 1
+    # strip the invocation prefix (word boundary already verified above) and trim
+    local goal
+    goal="$(printf '%s' "$prompt" | sed -E 's/^[[:space:]]*\/?superharness:go[[:space:]]*//')"
+    goal="$(printf '%s' "$goal" | sed -E 's/^[[:space:]]+//;s/[[:space:]]+$//')"
+
+    local date_part kebab tokens
+    date_part="$(date '+%Y-%m-%d')"
+    tokens="$(printf '%s' "$goal" | tr '[:upper:]' '[:lower:]' | LC_ALL=C grep -oE '[a-z0-9]+' | head -n 6 | paste -sd '-' - 2>/dev/null || true)"
+    if [ -n "$tokens" ]; then
+        kebab="$tokens"
+    else
+        kebab="task-$(date '+%H%M%S')"
+    fi
+    printf '%s\n%s-%s\n' "$goal" "$date_part" "$kebab"
+}
+
+ralph_mkdir() {
+    local dir
+    dir="$(ralph_dir "$1")"
+    mkdir -p "$dir"
+    printf '%s' "$dir"
+}
+
+ralph_write_text() {
+    # Atomic write: temp file then move-replace. UTF-8 without BOM.
+    local path="$1" text="$2"
+    mkdir -p "$(dirname "$path")"
+    local tmp="$path.tmp.$$"
+    printf '%s' "$text" > "$tmp"
+    mv -f "$tmp" "$path"
+}
+
+ralph_write_json() {
+    # $1 = path, $2 = already-serialized JSON text
+    ralph_write_text "$1" "$2"
+}
+
+ralph_read_json() {
+    # Prints raw JSON content when the file exists and is non-empty.
+    local path="$1"
+    [ -f "$path" ] || return 1
+    [ -s "$path" ] || return 1
+    cat "$path"
+}
+
+# ---------------------------------------------------------------- .current-task
+
+ralph_current_task_path() { printf '%s/.current-task' "$(ralph_dir "$1")"; }
+
+ralph_set_current_task() {
+    # The pointer is a single line; switching a task rewrites only this line.
+    local root="$1" task_id="$2"
+    task_id="$(printf '%s' "$task_id" | sed -E 's/^[[:space:]]+//;s/[[:space:]]+$//')"
+    ralph_write_text "$(ralph_current_task_path "$root")" "$task_id"
+}
+
+ralph_get_current_task() {
+    local p line
+    p="$(ralph_current_task_path "$1")"
+    [ -f "$p" ] || return 0
+    line="$(sed -E 's/^[[:space:]]+//;s/[[:space:]]+$//' "$p" | head -n 1)"
+    [ -n "$line" ] && printf '%s' "$line"
+    return 0
+}
+
+# ---------------------------------------------------------------- task.json
+
+ralph_task_path() { printf '%s/task.json' "$(ralph_dir "$1")"; }
+
+ralph_init_tasks() {
+    # Write a fresh task-list snapshot with an empty task list (the agent enriches
+    # it later). $1=root  $2=status(planning)  $3=phase(plan)
+    local root="$1" status="${2:-planning}" phase="${3:-implement}"
+    local now
+    now="$(ralph_iso)"
+    local snapshot="{\"status\":\"$(ralph_json_escape "$status")\",\"phase\":\"$(ralph_json_escape "$phase")\",\"sprint\":{\"current\":0,\"total\":0},\"tasks\":[],\"updated_at\":\"$now\"}"
+    ralph_write_json "$(ralph_task_path "$root")" "$snapshot"
+}
+
+ralph_get_tasks() {
+    ralph_read_json "$(ralph_task_path "$1")"
+}
+
+ralph_get_phase() {
+    # Prints task.json's phase, or 'go' when absent.
+    local phase
+    phase="$(ralph_json_get "$(ralph_task_path "$1")" phase)"
+    if [ -n "$phase" ]; then printf '%s' "$phase"; else printf 'go'; fi
+}
+
+# ---------------------------------------------------------------- trace.jsonl
+
+ralph_trace_path() { printf '%s/trace.jsonl' "$(ralph_dir "$1")"; }
+
+ralph_add_trace() {
+    # Append a single minified {ts,phase,event,detail} line. Never rewrites earlier
+    # lines — the worst a crash can corrupt is the final line.
+    # $1=root  $2=phase  $3=event  $4=detail
+    local root="$1" phase="$2" event="$3" detail="${4:-}"
+    ralph_mkdir "$root" > /dev/null
+    local now line
+    now="$(ralph_iso)"
+    line="{\"ts\":\"$now\",\"phase\":\"$(ralph_json_escape "$phase")\",\"event\":\"$(ralph_json_escape "$event")\",\"detail\":\"$(ralph_json_escape "$detail")\"}"
+    printf '%s\n' "$line" >> "$(ralph_trace_path "$root")"
+}
+
+ralph_get_trace_tail() {
+    # Print the last N non-empty lines of the ledger (raw JSON lines).
+    local root="$1" count="${2:-1}"
+    local p
+    p="$(ralph_trace_path "$root")"
+    [ -f "$p" ] || return 0
+    tail -n "$count" "$p" | grep -v '^[[:space:]]*$' || true
+}
+
+# ---------------------------------------------------------------- .ralph-state.json (retry counter)
+
+ralph_retry_path() { printf '%s/.ralph-state.json' "$(ralph_dir "$1")"; }
+
+ralph_get_retry_state() {
+    # Prints two lines: retries, max. Defaults to 0, 5 when absent or malformed.
+    local root="$1" retries max
+    retries="$(ralph_json_get "$(ralph_retry_path "$root")" retries)"
+    max="$(ralph_json_get "$(ralph_retry_path "$root")" max)"
+    case "$retries" in ''|*[!0-9]*) retries=0 ;; esac
+    case "$max" in ''|*[!0-9]*) max=5 ;; esac
+    printf '%s\n%s\n' "$retries" "$max"
+}
+
+ralph_set_retry_state() {
+    # $1=root  $2=retries  $3=max
+    local root="$1" retries="$2" max="$3" now
+    now="$(ralph_iso)"
+    ralph_write_json "$(ralph_retry_path "$root")" "{\"retries\":$retries,\"max\":$max,\"updated_at\":\"$now\"}"
+}
+
+ralph_add_retry() {
+    # Increment the retry counter, clamped at max. Prints the new retry count.
+    local root="$1" state retries max
+    state="$(ralph_get_retry_state "$root")"
+    retries="$(printf '%s\n' "$state" | head -n 1)"
+    max="$(printf '%s\n' "$state" | tail -n 1)"
+    local n=$((retries + 1))
+    if [ "$n" -gt "$max" ]; then n=$max; fi
+    ralph_set_retry_state "$root" "$n" "$max"
+    printf '%s' "$n"
+}
+
+ralph_test_retry_exhausted() {
+    # Exit status 0 when retries >= max.
+    local state retries max
+    state="$(ralph_get_retry_state "$1")"
+    retries="$(printf '%s\n' "$state" | head -n 1)"
+    max="$(printf '%s\n' "$state" | tail -n 1)"
+    [ "$retries" -ge "$max" ]
+}
+
+ralph_reset_retry() {
+    local state max
+    state="$(ralph_get_retry_state "$1")"
+    max="$(printf '%s\n' "$state" | tail -n 1)"
+    ralph_set_retry_state "$1" 0 "$max"
+}
+
+# ---------------------------------------------------------------- task bootstrap
+
+ralph_start_task() {
+    # Auto-bootstrap a fresh go task: point .current-task, seed an empty task.json
+    # (planning/plan — the agent enriches the task list later), open the trace ledger
+    # with a task:started event, and reset the retry counter. Idempotent-ish: calling
+    # again repoints to a new TaskId and appends another task:started line.
+    # $1=root  $2=task_id  $3=goal
+    local root="$1" task_id="$2" goal="${3:-}"
+    ralph_set_current_task "$root" "$task_id"
+    ralph_init_tasks "$root" 'planning' 'plan'
+    ralph_add_trace "$root" 'plan' 'task:started' "$goal"
+    ralph_reset_retry "$root"
+}
+
+# ---------------------------------------------------------------- cold-start recovery
+
+ralph_get_resume_context() {
+    # Assemble the deterministic file-based facts a freshly-started agent needs to
+    # resume: the active pointer, the task snapshot, the last ledger event, and the
+    # retry state — as a single JSON object. The agent then reconciles these
+    # against `git diff` (code wins) and fixes task.json.
+    local root="$1"
+    local current tasks last_trace retries max all_done
+    current="$(ralph_get_current_task "$root")"
+    tasks="$(ralph_get_tasks "$root" || true)"
+    last_trace="$(ralph_get_trace_tail "$root" 1 | tail -n 1)"
+    local state
+    state="$(ralph_get_retry_state "$root")"
+    retries="$(printf '%s\n' "$state" | head -n 1)"
+    max="$(printf '%s\n' "$state" | tail -n 1)"
+
+    all_done=false
+    if [ -n "$tasks" ]; then
+        local remaining=""
+        if command -v node >/dev/null 2>&1; then
+            remaining="$(RALPH_TASKS="$tasks" node -e '
+                let o; try{o=JSON.parse(process.env.RALPH_TASKS||"");}catch{process.exit(0);}
+                const ts=Array.isArray(o.tasks)?o.tasks:[];
+                process.stdout.write(ts.some(t=>t.status!=="done")?"1":"");
+            ')"
+        elif command -v python3 >/dev/null 2>&1; then
+            remaining="$(RALPH_TASKS="$tasks" python3 -c '
+import json,os
+try:
+    o=json.loads(os.environ.get("RALPH_TASKS",""))
+except Exception:
+    raise SystemExit(0)
+ts=o.get("tasks") or []
+print("1" if any(t.get("status")!="done" for t in ts) else "",end="")')"
+        fi
+        [ -z "$remaining" ] && all_done=true
+    fi
+
+    local current_json="null" tasks_json="null" last_json="null"
+    [ -n "$current" ] && current_json="\"$(ralph_json_escape "$current")\""
+    [ -n "$tasks" ] && tasks_json="$tasks"
+    [ -n "$last_trace" ] && last_json="$last_trace"
+
+    printf '{"current_task":%s,"tasks":%s,"last_trace":%s,"all_done":%s,"retry":{"retries":%s,"max":%s}}' \
+        "$current_json" "$tasks_json" "$last_json" "$all_done" "$retries" "$max"
+}

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: brainstorm
+description: Manual-only brainstorming with a live browser mind map - explores requirements and design one question at a time while pushing the discussion structure to a draggable, zoomable mind map. ONLY invoke when the user explicitly runs /superharness:brainstorm; never self-invoke.
+disable-model-invocation: true
+argument-hint: [topic]
+---
+
+# Superharness Brainstorm — live mind-map requirement design
+
+**Topic:** $ARGUMENTS
+
+If the topic above is empty, ask your human partner what they want to brainstorm and stop.
+
+**Announce at start:** "Superharness brainstorm engaged. Topic: <topic>."
+
+Turn the idea into a validated design through collaborative dialogue, while mirroring
+the discussion structure to a live mind map in the user's browser.
+
+**State root:** the superharness state root follows the host — `.claude/superharness/`
+under Claude Code, `.flavor/superharness/` under flavor-code. Everywhere below,
+`.claude/superharness/` stands for whichever state root applies to your host
+(the scripts detect it automatically; use the actual paths they print).
+
+<HARD-GATE>
+Do NOT write implementation code or invoke implementation skills during this flow.
+The output of this skill is a design document, not code.
+</HARD-GATE>
+
+## Phase 1 — Start the mind map session
+
+1. Run (the script backgrounds node itself and prints server-info JSON before exiting):
+
+   ```
+   powershell -NoProfile -ExecutionPolicy Bypass -File "<this skill's base directory>/scripts/start-server.ps1" -ProjectDir "<project root>"
+   ```
+
+2. Parse the printed JSON: save `url`, `content_dir`, `state_dir`, and the session
+   directory (parent of `state_dir`). Tell the user to open `url` in a browser.
+3. Remind the user to add the brainstorm root — the parent of the session directory
+   the script printed (`<state-root>/superharness/brainstorm/`) — to `.gitignore` if missing.
+4. **Degrade gracefully:** if node is missing or the script fails, say so and continue
+   the whole flow in the terminal only. Never block brainstorming on the mind map.
+
+## Phase 2 — Explore context
+
+Read relevant project files, docs, and recent commits. Push the first snapshot:
+the root node is the topic. Then proceed.
+
+## Phase 3 — Clarify, one question at a time
+
+For each clarifying question:
+
+1. **Before asking in the terminal**, push a snapshot adding the question node
+   (`kind: "question"`, `state: "open"`) with its candidate options
+   (`kind: "option"`, `state: "open"`) as children.
+2. Ask in the terminal (multiple choice preferred). Mention that the user can also
+   click an option node in the browser.
+3. **After the user answers** (terminal text is primary): read `<state_dir>/events`
+   if it exists and merge with the terminal answer. Push a snapshot marking the
+   chosen option `state: "chosen"`, the others `state: "rejected"`, and the question
+   `state: "resolved"`.
+
+## Phase 4 — Propose approaches
+
+Push 2-3 approaches as branches (a `kind: "decision"` parent with `kind: "option"`
+children, trade-offs in `note`). Present them in the terminal with your
+recommendation. Mark the chosen approach as in Phase 3. Set top-level
+`status: "designing"`.
+
+## Phase 5 — Present the design
+
+Present the design in sections in the terminal, validating each. Fix agreed points
+into the map as `kind: "requirement"` / `kind: "decision"` nodes; record known risks
+as `kind: "risk"`.
+
+## Phase 6 — Wrap up
+
+After the user approves the design:
+
+1. Push a final snapshot with `status: "approved"`.
+2. Write the design to `<state-root>/superharness/specs/YYYY-MM-DD-<topic-slug>.md`
+   (`.claude/superharness/` under Claude Code, `.flavor/superharness/` under
+   flavor-code; create the folder if missing) and commit it.
+3. Stop the server:
+
+   ```
+   powershell -NoProfile -ExecutionPolicy Bypass -File "<this skill's base directory>/scripts/stop-server.ps1" -SessionDir "<session directory>"
+   ```
+
+4. Tell the user: the design is saved, and they can run
+   `/superharness:go <goal>` to implement it. Do NOT start implementation yourself.
+
+## Message protocol
+
+### Claude → browser: write the full snapshot to `<content_dir>/mindmap.json`
+
+Always rewrite the whole file with the Write tool. The server watches it and pushes
+it to the browser over WebSocket. Before each write, check that
+`<state_dir>/server-info` exists and `<state_dir>/server-stopped` does not;
+otherwise restart the server (Phase 1) or continue terminal-only.
+
+```json
+{
+  "type": "mindmap:snapshot",
+  "rev": 7,
+  "topic": "User Login",
+  "status": "exploring",
+  "root": {
+    "id": "root", "label": "User Login", "kind": "topic",
+    "children": [
+      { "id": "q1", "label": "Auth method?", "kind": "question", "state": "resolved",
+        "children": [
+          { "id": "q1-a", "label": "JWT", "kind": "option", "state": "chosen", "note": "Stateless, easy to scale" },
+          { "id": "q1-b", "label": "Session", "kind": "option", "state": "rejected" }
+        ] }
+    ]
+  }
+}
+```
+
+Rules:
+- `rev`: increment by 1 on every write (the browser discards stale revisions).
+- `status`: `exploring` → `designing` → `approved`.
+- Node `id`s are stable across snapshots; never reuse an id for a different node.
+- `kind`: `topic | question | option | decision | requirement | risk | note`.
+- `state`: `open | chosen | rejected | resolved` (default `open`).
+- `note`: optional hover tooltip text. Keep labels short; details go in `note`.
+
+### Browser → Claude: read `<state_dir>/events` (JSONL)
+
+The server clears this file each time you push a new snapshot, so pending lines
+always refer to the current screen. Missing file = no browser interaction.
+
+```json
+{"type":"node:click","id":"q1-a","label":"JWT","kind":"option","timestamp":1760000000}
+```
+
+The last click is usually the user's choice, but the terminal answer always wins
+on conflict.
+
+### Browser → Claude: read `<state_dir>/edits` (JSONL)
+
+Node `label`/`note` edits and the submit marker land here. Unlike `events`, this file
+is **NOT cleared on snapshot push** — it persists until you merge and clear it.
+
+```json
+{"type":"node:edit","id":"q1-a","label":"New label","note":"New note","timestamp":1760000000}
+{"type":"submit","timestamp":1760000005}
+```
+
+Only `label` and `note` are editable. Same `id` later in the file wins.
+
+### Edit round — pull browser edits into the design
+
+When you invite the user to edit node text:
+
+1. **Establish the baseline first.** Clear `<state_dir>/edits` (truncate it) so a stale
+   submit from an earlier round can't immediately satisfy the wait. Do this BEFORE
+   inviting the user, so the window where an eager submit lands un-watched is closed.
+2. Tell them: double-click a node in the browser to edit its label/note, save each one, then click "Submit" in the top bar when done.
+3. Do NOT end the turn. Block-wait for a `{"type":"submit"}` line in
+   `<state_dir>/edits` using `Monitor` (fall back to `ScheduleWakeup`, ≤60s, if
+   `Monitor` is unavailable). This only works while you are parked in this wait.
+4. On submit: read `<state_dir>/edits`, take all `node:edit` lines (same `id` later
+   wins), apply each `label`/`note` onto the current snapshot tree by `id`; ignore
+   ids no longer present.
+5. If a browser edit conflicts with what the terminal dialogue concluded for that
+   node, ask in the terminal which wins.
+6. Rewrite `<content_dir>/mindmap.json` (`rev` + 1), then clear `<state_dir>/edits`.
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "The server won't start, fix it first" | Degrade to terminal-only and keep going; brainstorming must not be blocked by the mind map. |
+| "Asking three questions at once is faster" | One question at a time. |
+| "The design is approved, start coding right away" | The endpoint is a design document + a prompt to run /superharness:go. |
+| "Snapshots push too often, batch them" | Push every question/decision; real-time-ness is this skill's value. |
+| "Take browser edits as final" | label/note edits wait for "Submit" and are confirmed in the terminal when they conflict with the dialogue. |

package/skills/brainstorm/scripts/layout.js

@@ -0,0 +1,76 @@
+// Mind map tree layout. Pure and deterministic.
+// Loadable from Node (module.exports) and the browser (window.MindmapLayout).
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.MindmapLayout = factory();
+})(typeof self !== 'undefined' ? self : this, function () {
+  const LEVEL_X = 220; // horizontal distance per depth level
+  const NODE_H = 44;   // vertical slot per leaf
+
+  function leafCount(node) {
+    if (!node.children || node.children.length === 0) return 1;
+    return node.children.reduce((sum, c) => sum + leafCount(c), 0);
+  }
+
+  // Distribute root children left/right, balancing total leaf count.
+  function splitSides(children) {
+    const right = [];
+    const left = [];
+    let rightLeaves = 0;
+    let leftLeaves = 0;
+    for (const c of children) {
+      const n = leafCount(c);
+      if (rightLeaves <= leftLeaves) { right.push(c); rightLeaves += n; }
+      else { left.push(c); leftLeaves += n; }
+    }
+    return { right, left };
+  }
+
+  function visit(node, depth, side, top, parentId, nodes, links) {
+    const leaves = leafCount(node);
+    nodes.push({
+      id: node.id,
+      label: node.label,
+      kind: node.kind || 'note',
+      state: node.state || 'open',
+      note: node.note || '',
+      x: side * depth * LEVEL_X,
+      y: top + (leaves * NODE_H) / 2,
+      side,
+    });
+    links.push({ from: parentId, to: node.id });
+    let childTop = top;
+    for (const c of node.children || []) {
+      visit(c, depth + 1, side, childTop, node.id, nodes, links);
+      childTop += leafCount(c) * NODE_H;
+    }
+  }
+
+  function layout(rootNode) {
+    const nodes = [];
+    const links = [];
+    if (!rootNode) return { nodes, links };
+    nodes.push({
+      id: rootNode.id,
+      label: rootNode.label,
+      kind: rootNode.kind || 'topic',
+      state: rootNode.state || 'open',
+      note: rootNode.note || '',
+      x: 0,
+      y: 0,
+      side: 0,
+    });
+    const { right, left } = splitSides(rootNode.children || []);
+    for (const [side, group] of [[1, right], [-1, left]]) {
+      const total = group.reduce((sum, c) => sum + leafCount(c), 0);
+      let top = -(total * NODE_H) / 2;
+      for (const c of group) {
+        visit(c, 1, side, top, rootNode.id, nodes, links);
+        top += leafCount(c) * NODE_H;
+      }
+    }
+    return { nodes, links };
+  }
+
+  return { layout, leafCount, splitSides };
+});