fix(orchestrator): per-attempt human notes via suggestions/NNN.md (no cursor)

Rework the suggestions channel from the single-file mailbox of the previous
commit into a per-attempt convention, and move delivery out of the
orchestrator entirely.

suggestions/ is now a directory parallel to attempts/: the Runner of attempt
NNN reads suggestions/NNN.md as part of its Load-context step (alongside
goal.md and attempts/). The manager knows the current attempt from status, so
it writes a note targeting the round that will read it (suggestions/006.md
while 005 runs). The note file stays in place afterward as part of the audit
trail.

- No cursor, no offsets, no diffing — nothing to drift when notes are edited
  or deleted (the original bug this PR set out to fix).
- The orchestrator no longer injects or consumes anything: _consume_suggestions
  is gone and _build_brief is back to a static brief.
- Delivery is an exact attempt-number match; a note whose round the loop has
  already passed sits unread until re-pointed — an accepted, low-odds trade
  for the simplicity of "Runner reads its own NNN.md".

Runner prompt (agents/goal-runner.md) gains the read step; manager skill
(goal-run), goal-init/goal-flash skills, README, and design.md updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CHb1FkoMGfDfwmeJR5hBG6

Author: luohaha

README.md

@@ -165,9 +165,9 @@ the same session indefinitely.)
 
 You stay in control throughout: read what each attempt did via
 `/goal-run` or `goaloop status`; **edit `goal.md`** for a permanent
-change or **append to `suggestions.md`** for a transient per-attempt
-note — the next attempt picks it up. There's no live conversation into a
-running Runner.
+change or **drop a `suggestions/NNN.md`** note for a transient per-attempt
+nudge — the Runner of that attempt reads it. There's no live conversation into
+a running Runner.
 
 ### Configuration & modes
 
@@ -182,12 +182,12 @@ and waits for your approval before the next one; release it with
 `goaloop continue <name>`. (`pass`/`blocked`/`error` are terminal, and
 `in_progress` resumes automatically — only `advanced` waits.)
 
-`suggestions.md` is an optional async channel — a mailbox: append a one-off
-note and the next fresh attempt claims it (exactly once), archiving it to
-`.goaloop/suggestions.delivered.md` and clearing the file. Edit or delete
-freely before it's claimed; the claim is atomic, so nothing is lost or
-double-delivered. Use `goal.md` for permanent/structural changes,
-`suggestions.md` for transient nudges (e.g. left while AFK).
+`suggestions/` is an optional async channel — a directory parallel to
+`attempts/`: the Runner of attempt NNN reads `suggestions/NNN.md` at the start
+of that attempt, so the manager drops a note named for the round that will read
+it (e.g. `suggestions/006.md` while attempt 005 runs). The file stays in place
+afterward as part of the audit trail. Use `goal.md` for permanent/structural
+changes, `suggestions/` for transient nudges (e.g. left while AFK).
 
 ## Workspace contents
 
@@ -196,8 +196,8 @@ After running, the workspace looks like:
 ```
 <workspace>/
 ├── goal.md
-├── config.yaml           # optional: model / interval / mode
-├── suggestions.md        # optional: async per-attempt notes
+├── config.yaml           # optional: model / interval / mode / caps
+├── suggestions/          # optional: per-attempt human notes (NNN.md read by attempt NNN)
 ├── memory/
 │   └── learnings.md      # ~4KB cap; Runner curates this
 └── attempts/

agents/goal-runner.md

@@ -15,6 +15,11 @@ optional Initial Context), `memory/learnings.md` if present, and the last few
 on them rather than assumptions. Also read whatever `goal.md`'s Verification
 references (rubrics, scripts, baselines).
 
+Also read `suggestions/NNN.md` for THIS attempt's number (your brief states it),
+if it exists — a transient human note left for exactly this round. Treat it as
+guidance to address this attempt; `goal.md` still wins for the permanent spec.
+Leave the file in place (it's part of the audit trail, like `attempts/NNN.md`).
+
 ## 2. Verify
 Run the Verification procedure from `goal.md` — the **only authoritative check**,
 not your sense that it "looks done". It yields **pass** (objective met AND no hard

docs/design.md

@@ -235,8 +235,9 @@ tokens.
 ```
 <workspace>/
 ├── goal.md            # Objective + Hard Constraints + Verification spec
-├── config.yaml        # Optional: model / interval / mode (see below)
-├── suggestions.md     # Optional: async per-attempt human notes (see below)
+├── config.yaml        # Optional: model / interval / mode / caps (see below)
+├── suggestions/       # Optional: per-attempt human notes (see below)
+│   └── 006.md         # suggestions/NNN.md is read by the Runner of attempt NNN
 ├── memory/
 │   └── learnings.md   # Run-level curated knowledge; Runner self-maintains, ~4KB cap
 ├── attempts/
@@ -247,14 +248,13 @@ tokens.
     ├── state.json     # Checkpoint: active session id + cumulative counters/cost for resume
     ├── status.txt     # Current one-line orchestrator status (read by /goal-run)
     ├── attempt_complete.json  # Last completed attempt's {attempt, status, cost_usd, total_cost_usd}
-    ├── suggestions.delivered.md  # Archive of consumed suggestions.md notes, stamped per attempt
     ├── continue.json  # copilot-mode approval token (written by `goaloop continue`)
     ├── orchestrator.log       # Per-attempt log: Runner messages, tool calls, results
     └── pipeline.pid   # PID of the running orchestrator (for status/stop)
 ```
 
 The `goal.md` + `memory/` + `attempts/` triple is the goal record GoaLoop
-requires; `config.yaml` and `suggestions.md` are optional human inputs, and
+requires; `config.yaml` and `suggestions/` are optional human inputs, and
 `.goaloop/` is the orchestrator's own bookkeeping and can be deleted
 between runs without losing the audit trail. Anything else (scripts the
 verification uses, source code being modified, datasets, etc.) lives wherever
@@ -443,8 +443,8 @@ The orchestrator, not the Manager, performs the per-attempt mechanics:
 3. **Spawn the Runner.** `claude -p <brief> --append-system-prompt
    goal-runner.md --output-format stream-json --session-id <uuid>
    --dangerously-skip-permissions`. The brief carries the workspace path,
-   the attempt number, the read-context + terminator instructions, and —
-   on a fresh attempt — any NEW `suggestions.md` text since the cursor.
+   the attempt number, and the read-context + terminator instructions; the
+   Runner itself reads `suggestions/NNN.md` for that attempt as context.
 4. **Parse the terminator** (`{"status": pass|advanced|in_progress|blocked}`)
    and branch: `pass`/`blocked` → exit; `advanced` (and `attempts/NNN.md`
    exists) → pace (or, in copilot mode, wait for approval), then next
@@ -531,27 +531,28 @@ on the user's confirmation** — not to carry the guidance itself.
 This is also why `goal.md` is mutable mid-run: it is the steering wheel, not
 just the starting configuration.
 
-**`suggestions.md` — transient / per-attempt.**
+**`suggestions/` — transient / per-attempt.**
 
 For a one-off note that does not belong in the goal spec (e.g. something left
-while AFK — "try lock granularity next"), the human appends to
-`<workspace>/suggestions.md`. The file is a **mailbox, not a log**: whatever it
-holds is undelivered. On each FRESH attempt the orchestrator atomically
-*claims* its contents (renaming it aside), injects them into the Runner's brief
-as a "Human guidance (NEW)" section, archives them to
-`.goaloop/suggestions.delivered.md`, and clears the file — so each note reaches
-exactly one attempt. The atomic rename is what makes this race-free: a note
-appended while a claim is in flight lands in either that batch or a fresh file
-the next attempt picks up — never lost, never delivered twice, with no byte
-cursor to drift when the human edits or deletes earlier notes. Use `goal.md`
-for changes that should persist; use `suggestions.md` for transient nudges.
+while AFK — "try lock granularity next"), the manager drops a note file into
+`<workspace>/suggestions/` — a directory parallel to `attempts/`. Delivery is
+**Runner-side, by attempt number**: the Runner of attempt NNN reads
+`suggestions/NNN.md` as part of its Load-context step (just like it reads
+`goal.md` and `attempts/`), so the manager — which knows the current attempt
+from status — names the note for the round that will read it (`suggestions/006.md`
+while 005 runs). The orchestrator never touches it; there is no injection, no
+consumption, no cursor. The file stays in place afterward as part of the audit
+trail. Because delivery is an exact number match, a note whose round the loop
+has already passed simply sits unread until re-pointed — an accepted, low-odds
+trade for the simplicity of "Runner reads its own `suggestions/NNN.md`". Use
+`goal.md` for changes that should persist; `suggestions/` for transient nudges.
 
 **The Manager distinguishes messages for itself vs. goal edits.**
 
 | User message | Manager's response |
 |---|---|
 | "How is it going?" | Answer directly by reading `.goaloop/status.txt` + latest `attempts/NNN.md` |
-| "Try lock granularity instead next time" | A transient nudge → append to `suggestions.md` (next attempt sees it once); a permanent change → propose editing `goal.md`'s Initial Context |
+| "Try lock granularity instead next time" | A transient nudge → write `suggestions/<next-attempt>.md` (that Runner reads it); a permanent change → propose editing `goal.md`'s Initial Context |
 | "Stop the orchestrator" | `goaloop stop <name>`; confirm it stopped |
 | "Change the target to P99 < 3s" | Propose editing `goal.md`'s Objective; edit on confirmation |
 | "Hmm" / "OK" / chit-chat | Ignore |
@@ -633,8 +634,8 @@ Human pacing during a run is achieved by:
 - **Reading status** via `/goal-run` (or `goaloop status`, or
   `tail -f .goaloop/orchestrator.log`) — the orchestrator writes `status.txt` and
   `attempt_complete.json` each attempt.
-- **Editing `goal.md`** (permanent) or **appending to `suggestions.md`**
-  (transient, per-attempt) to steer — the next attempt's Runner picks it up
+- **Editing `goal.md`** (permanent) or **dropping a `suggestions/NNN.md`**
+  (transient, per-attempt) to steer — the Runner of that attempt picks it up
   (see Human guidance protocol).
 - **`goaloop continue`** to release the next attempt in copilot mode.
 - **`goaloop stop`** to halt earlier than `pass`.
@@ -683,9 +684,9 @@ The following were considered and deliberately not built. Each appears here
 with the reason so future contributors don't reintroduce them by reflex.
 
 > **Implemented after v0.1 (now included).** Two features once listed here as
-> excluded have since been built: `suggestions.md` (a transient per-attempt
-> human → agent channel, NEW-since-cursor injection — see Human guidance
-> protocol) and copilot mode (the `--mode copilot` human-review pause,
+> excluded have since been built: `suggestions/` (a transient per-attempt
+> human → agent channel — the Runner of attempt NNN reads `suggestions/NNN.md`;
+> see Human guidance protocol) and copilot mode (the `--mode copilot` human-review pause,
 > released with `goaloop continue` — see How to run). They are documented
 > above and are no longer exclusions.
 

goaloop/orchestrator.py

@@ -87,15 +87,10 @@ def __init__(
         self.status_path = self.state_dir / "status.txt"
         self.complete_path = self.state_dir / "attempt_complete.json"
         self.continue_path = self.state_dir / "continue.json"
-        # Async human feedback channel (optional). suggestions.md is a MAILBOX,
-        # not a log: whatever it holds is undelivered guidance. Each fresh
-        # attempt atomically CLAIMS its contents (rename aside), injects them as
-        # NEW into the brief, archives them, and clears the file — so there is
-        # no byte cursor to drift when the human edits/deletes (the old model).
-        self.suggestions_path = self.ws / "suggestions.md"
-        # Atomic-claim staging + permanent archive of delivered notes.
-        self.suggestions_inflight = self.state_dir / "suggestions.inflight"
-        self.suggestions_archive = self.state_dir / "suggestions.delivered.md"
+        # Human feedback is delivered Runner-side, not here: the manager writes
+        # a note to suggestions/NNN.md and the Runner of attempt NNN reads it as
+        # context for that round (see agents/goal-runner.md, "Load context").
+        # The orchestrator stays out of it — no injection, no consumption.
 
         self.adapter = ClaudeAdapter(
             cwd=str(self.ws),
@@ -193,40 +188,6 @@ def _end_error(self, attempt: int, reason: str) -> None:
         self._mark_complete(attempt, "error", None)
         self._clear_active()
 
-    def _consume_suggestions(self, n: int) -> str:
-        """Claim any pending human notes from suggestions.md (the mailbox) and
-        return them as a brief section, or "" if none.
-
-        suggestions.md holds undelivered guidance; we CLAIM it by atomically
-        renaming it aside. That rename is the whole trick: a human append that
-        races the claim lands either in the batch we just took or in a fresh
-        file the next attempt picks up — never lost, never delivered twice, and
-        with no byte cursor to drift when the human edits or deletes earlier
-        notes. The claimed text is appended to suggestions.delivered.md
-        (stamped with the attempt) so history survives the cleared live file.
-        goal.md stays the channel for permanent/structural guidance.
-
-        Crash-safety: the inflight file persists until the archive write
-        succeeds, so a crash mid-claim leaves it for the next call to recover
-        (at worst delivered twice — harmless — never dropped).
-        """
-        self.state_dir.mkdir(parents=True, exist_ok=True)
-        if not self.suggestions_inflight.exists():
-            if not self.suggestions_path.exists():
-                return ""
-            try:
-                self.suggestions_path.rename(self.suggestions_inflight)
-            except OSError:
-                return ""
-        text = self.suggestions_inflight.read_text().strip()
-        if not text:
-            self.suggestions_inflight.unlink(missing_ok=True)
-            return ""
-        with self.suggestions_archive.open("a") as fh:
-            fh.write(f"\n## Delivered to attempt {n:03d}\n\n{text}\n")
-        self.suggestions_inflight.unlink(missing_ok=True)
-        return f"\n## Human guidance (NEW — address this attempt)\n\n{text}\n"
-
     def _wait_for_continue(self, n: int) -> None:
         """Copilot mode: block until the human approves the next attempt.
 
@@ -244,10 +205,8 @@ def _wait_for_continue(self, n: int) -> None:
         self.log("[orchestrator] approval received — continuing")
 
     def _build_brief(self, n: int) -> str:
-        guidance = self._consume_suggestions(n)
         return f"""Workspace: {self.ws}
 This is attempt {n:03d}; write your attempt record to attempts/{n:03d}.md.
-{guidance}
 Run one attempt per your system-prompt workflow, then end your final message
 with a single line that is exactly one of these JSON objects:
   {{"status": "pass", "verification": "<one-line summary>"}}

skills/goal-flash/SKILL.md

@@ -115,8 +115,9 @@ rather than interviewing for it:
   `goaloop status <name>` or `tail -f <workspace>/.goaloop/orchestrator.log`.
 - **The inferred goal.md is the steering wheel and is mutable mid-run.** If
   the inference was off, edit `<workspace>/goal.md` (esp. Verification) — the
-  next attempt picks it up. Drop a transient nudge in `suggestions.md`. Halt
-  with `goaloop stop <name>`.
+  next attempt picks it up. Drop a transient nudge as a note file in
+  `suggestions/` (e.g. `suggestions/<next-attempt>.md`). Halt with
+  `goaloop stop <name>`.
 
 From here, progress relay is identical to `/goal-run` — read
 `.goaloop/status.txt`, `.goaloop/attempt_complete.json`, and the latest

skills/goal-init/SKILL.md

@@ -131,9 +131,9 @@ After writing, tell the user:
   mid-run, edit `goal.md` — the next attempt picks it up.
 - (Optional, no action needed at init) the workspace may also hold a
   `config.yaml` (flat keys `model` / `interval` / `mode: auto|copilot`)
-  to set run defaults, and a `suggestions.md` where they can drop async
-  per-attempt notes mid-run (each note is shown to one fresh attempt);
-  `goal.md` remains the place for permanent changes.
+  to set run defaults, and a `suggestions/` directory where the manager can
+  drop async per-attempt note files mid-run (the Runner of attempt NNN reads
+  `suggestions/NNN.md`); `goal.md` remains the place for permanent changes.
 
 Encourage them to read and tweak `goal.md` before kicking off — it's
 the load-bearing artifact of the whole framework.

skills/goal-run/SKILL.md

@@ -152,12 +152,15 @@ durable guidance channels, by intent serving different purposes.
   (or a file it references, like a rubric). The next attempt's Runner
   reads the updated spec naturally — no relay needed. Propose the edit,
   make it on the user's confirmation; no restart required.
-- **Transient per-attempt note**: append a line to
-  `~/.goaloop/<name>/suggestions.md` (a mailbox). The next fresh attempt
-  claims it exactly once — injected into the brief, archived to
-  `.goaloop/suggestions.delivered.md`, and the file cleared. Use this for
-  one-off nudges (e.g. dropped while AFK) rather than changes that should
-  persist — those belong in `goal.md`.
+- **Transient per-attempt note**: the Runner of attempt NNN reads
+  `~/.goaloop/<name>/suggestions/NNN.md` at the start of that attempt. So
+  write the note there, targeting the round that will read it: check
+  `goaloop status` for the current attempt and write the NEXT number — if
+  attempt 005 is running, write `suggestions/006.md`. The file stays in place
+  afterward as an audit trail (parallel to `attempts/NNN.md`). Use this for
+  one-off nudges (e.g. dropped while AFK); `goal.md` is for changes that
+  should persist. (If the loop has already moved past the round you targeted,
+  the note just sits unread — re-point it at the new next attempt.)
 - **Stop the orchestrator**: `goaloop stop <name>` (sends SIGTERM; it
   exits after the in-flight attempt's process settles).