entropy-machines 0.1.4 → 0.1.7

package/README.md

@@ -11,6 +11,7 @@ the cycle repeats.
 
 **A PRD creates issues, not the other way round.** The questions in a PRD are
 the decisions only you can make. Everything downstream follows from your answers.
+The tracker backend is a six-operation contract and can be swapped — see [TRACKER-ADAPTER.md](docs/TRACKER-ADAPTER.md).
 
 ```
   YOU ANSWER A PRD

package/agents/designer.md

@@ -0,0 +1,41 @@
+---
+name: designer
+description: UX alignment agent for dialogue docs and PRD layout. Produces visual aids (mermaid diagrams, component mockups), pressure-tests UX decisions, and ensures docs are scannable with clear options and tight feedback loops. Read-only — no code changes, no commits.
+---
+
+You are reviewing UX alignment for dialogue docs in this repo.
+
+Your job is to make sure docs are **scannable**, options are **clear**, and
+feedback loops are **tight**. You produce visual aids and challenge UX
+decisions — you do not implement code.
+
+## What you do
+
+- **Visual aids**: mermaid sequence/flow diagrams, ASCII component mockups,
+  annotated screenshots. Anything that helps the owner see the system.
+- **Layout review**: page flow, response box placement, discuss block
+  clarity, navigation structure. Flag when a page buries its question or
+  makes the owner hunt for what needs attention.
+- **Option clarity**: every multi-option discuss block should have exactly
+  one marked as recommended, trade-offs stated as bullets not paragraphs,
+  and the question itself answerable without reading the whole page.
+- **Grill-me challenge**: when asked, pressure-test a UX decision. Ask the
+  hard questions: what happens when there are 20 of these? What does the
+  owner see after ignoring this for a week? Where does this break on
+  mobile / in a narrow terminal? The point is to find the weak spots
+  before the owner does.
+
+## What you never do
+
+- Implement code changes
+- Commit, push, or merge
+- Override owner UX rulings — you advise, the owner decides
+- Edit files outside docs (no lib/, no bin/, no tests/)
+
+## Output
+
+Your final message reports:
+
+- What you reviewed and what you found
+- Any diagrams or mockups you produced (as mermaid code blocks or inline)
+- Specific recommendations, each as one bullet with a clear action

package/bin/auto-verify

@@ -0,0 +1,123 @@
+#!/bin/sh
+# bin/auto-verify — zero-cost poller that emits a verifier Agent call.
+#
+#   bin/auto-verify <issue-id>
+#
+# Polls for HANDOFF.md in the worker's worktree (matched by .dispatch-issue
+# marker). Zero tokens while polling — pure shell. When found, outputs a
+# structured Agent JSON block with the worktree path baked in. The
+# orchestrator receives this via task notification and pastes it.
+#
+# Run via Bash(run_in_background: true) alongside the worker Agent call.
+
+set -e
+
+id="$1"
+if [ -z "$id" ]; then
+  echo "usage: bin/auto-verify <issue-id>" >&2
+  exit 1
+fi
+
+ENTROPY_MACHINES_ROOT=$(git rev-parse --show-toplevel)
+ctx="$ENTROPY_MACHINES_ROOT/.dispatch-context/$id.md"
+NOTES_PY="$ENTROPY_MACHINES_ROOT/lib/notes.py"
+
+# ---------------------------------------------------------------------------
+# POLL — zero tokens. Pure shell, 30-second intervals, 20-minute timeout.
+# ---------------------------------------------------------------------------
+main_wt="$ENTROPY_MACHINES_ROOT"
+worker_wt=""
+polls=0
+max_polls=40
+
+echo "auto-verify($id): polling for .dispatch-issue=$id + HANDOFF.md (30s intervals, max ${max_polls})"
+while [ -z "$worker_wt" ] && [ "$polls" -lt "$max_polls" ]; do
+  for wt in $(git worktree list --porcelain | grep '^worktree ' | sed 's/worktree //'); do
+    [ "$wt" = "$main_wt" ] && continue
+    if [ -f "$wt/.dispatch-issue" ] && [ "$(cat "$wt/.dispatch-issue" | tr -d '[:space:]')" = "$id" ]; then
+      if [ -f "$wt/HANDOFF.md" ]; then
+        worker_wt="$wt"
+        break
+      fi
+    fi
+  done
+  if [ -z "$worker_wt" ]; then
+    sleep 30
+    polls=$((polls + 1))
+  fi
+done
+
+if [ -z "$worker_wt" ]; then
+  echo "auto-verify($id): TIMEOUT — no HANDOFF.md after $max_polls polls" >&2
+  exit 1
+fi
+
+echo "auto-verify($id): HANDOFF.md found at $worker_wt"
+
+# ---------------------------------------------------------------------------
+# EMIT — a structured Agent call for the verifier. The orchestrator pastes
+# this to the Agent tool. The verifier runs in the SAME session, so it can
+# SendMessage to the worker for real interrogation.
+# ---------------------------------------------------------------------------
+prompt_file="$ENTROPY_MACHINES_ROOT/.dispatch-context/.verifier-prompt-$id.tmp"
+trap 'rm -f "$prompt_file"' EXIT
+
+cat > "$prompt_file" << VEOF
+VERIFIER for issue $id.
+
+A worker agent named "$id" completed implementation in worktree: $worker_wt
+Dispatch context (full issue detail): $ctx
+
+Read BOTH files before doing anything else.
+
+## STEP 1 — INTERROGATE THE WORKER
+
+Run: bin/handoff $id --interrogate
+This prints the questions. Use ListAgents to find the worker agent named
+"$id" and get its address. Send ALL questions via SendMessage:
+  SendMessage({to: "<agent-address>", message: "<the questions>"})
+Wait for the worker to respond (it resumes). Record the answers:
+  bin/handoff $id --record-interrogation --answer "<answers>"
+
+If the worker cannot be reached (no longer listed), answer from artifacts:
+  1. Read $worker_wt/HANDOFF.md (changed/found/assumed/next)
+  2. Read the changed files in the worktree
+At least one answer must be substantive.
+
+## STEP 2 — LIFT
+
+Run: bin/handoff $id --from $worker_wt --lift
+If any files are rejected (main drifted), merge manually: read the worker's
+version and main's current version, apply the semantic diff onto main.
+
+## STEP 3 — TEST
+
+Run: tests/run
+All tests must pass. Fix failures caused by the lift.
+
+## STEP 4 — VERIFY (do NOT commit)
+
+Run: bin/handoff $id --from $worker_wt --verified "auto-verified: tests passed"
+If HANDOFF.md had found: none AND next: none, add --clean.
+If it had real found: or next: values, pass --found "..." --next "..."
+
+DO NOT stage, commit, or push. Report what you verified and stop.
+The orchestrator is the last pass — they review your work and commit.
+VEOF
+
+echo
+echo "--- AGENT CALL ---"
+python3 -c '
+import json, sys
+prompt = open(sys.argv[1]).read()
+call = {
+    "subagent_type": "general-purpose",
+    "name": "verify-" + sys.argv[2],
+    "description": "Verify and land " + sys.argv[2],
+    "prompt": prompt
+}
+print(json.dumps(call, indent=2))
+' "$prompt_file" "$id"
+echo "--- END AGENT CALL ---"
+echo
+echo "Pass the JSON block above to the Agent tool to start verification."

package/bin/cycle

@@ -0,0 +1,29 @@
+#!/bin/sh
+# Review-cycle CLI — thin wrapper around lib/cycle.py.
+#
+#   bin/cycle list                       every handle + status + ball
+#   bin/cycle resolve "<phrase>"         handle → file (fuzzy)
+#   bin/cycle responses <handle>         read the user's saved answers
+#   bin/cycle start <handle>             mark 'in-review' (agent is on it)
+#   bin/cycle done  <handle> [label]     mark 'open' (ball back to user) + snapshot
+#   bin/cycle set   <handle> <status>    any status transition
+#   bin/cycle new   <handle> <file> <title> [status]   register a new doc
+#   bin/cycle history <handle>           list this doc's versions
+#   bin/cycle sync                       regenerate STATE.md + INDEX.html from manifest
+set -e
+
+. "$(dirname "$0")/../lib/roots.sh"
+ENTROPY_MACHINES_HOME=$(entropy_machines_home "$0")
+entropy_machines_require_root cycle
+
+CONFIG_PY="$ENTROPY_MACHINES_HOME/lib/config.py"
+
+docs_dir=$(python3 "$CONFIG_PY" get docs.dir 2>/dev/null) || docs_dir="entropy-machines-docs"
+case "$docs_dir" in
+  /*) docs_path="$docs_dir" ;;
+  *) docs_path="$ENTROPY_MACHINES_ROOT/$docs_dir" ;;
+esac
+
+export ENTROPY_MACHINES_DOCS="$docs_path"
+export PYTHONPATH="$ENTROPY_MACHINES_HOME/lib${PYTHONPATH:+:$PYTHONPATH}"
+exec python3 "$ENTROPY_MACHINES_HOME/lib/cycle.py" "$@"

package/bin/dispatch

@@ -3,9 +3,13 @@
 #
 #   bin/dispatch i-foo --files "src/x.ts tests/x.test.ts" --brief "one-line task"
 #
-# Exit 0 means SAFE TO DISPATCH; anything else names the hazard. It does not
-# spawn the agent — your agent runner does that — it refuses the mistakes
-# that have each burned a real run:
+# Exit 0 means SAFE TO DISPATCH; anything else names the hazard. It emits
+# TWO structured JSON blocks (--- AGENT CALL --- / --- END AGENT CALL ---)
+# with the exact Agent tool parameters — the WORKER (implements in a
+# worktree) and the VERIFIER (polls for HANDOFF.md, then runs the full
+# handoff pipeline and commits). The orchestrator pastes both blocks in one
+# message and walks away — nothing to remember, no manual landing. It refuses
+# the mistakes that have each burned a real run:
 #
 #   1. NON-ROOT CWD. A worktree is created in whatever repo the dispatching
 #      session's cwd belongs to. A session parked one directory off from the
@@ -21,7 +25,11 @@
 #      none of this agent's business.
 #   3. ALREADY-LANDED WORK. If git log already mentions the issue id, the
 #      task may be partly or fully done. The audit comes before the dispatch.
-#   4. UNRECORDED BRIEFS. The brief + file scope are appended to the tracker
+#   4. RECENTLY-TOUCHED FILES. If any declared file was touched in the last
+#      5 commits on any branch, that file is hot — another change may still
+#      be landing, or the agent's base commit may already contain the fix.
+#      The commits are printed and the dispatch requires --force to proceed.
+#   5. UNRECORDED BRIEFS. The brief + file scope are appended to the tracker
 #      notes log in the same act, so any session can see what was handed out
 #      and scopes can be checked for overlap before agents collide in a file.
 #
@@ -78,19 +86,21 @@
 # with no obvious symptom until the agent can't find its own files. Check 1
 # is what closes that.
 #
-# --anyway skips check 3 only (the git-log hits are still printed); checks 1
-# and 2 have no override — there is no correct dispatch from a wrong cwd or
-# over your own uncommitted edits.
+# --anyway skips check 3 only (the git-log hits are still printed); --force
+# skips check 4 only (the file-history hits are still printed); checks 1 and
+# 2 have no override — there is no correct dispatch from a wrong cwd or over
+# your own uncommitted edits.
 set -e
 
-usage() { echo "usage: bin/dispatch <issue-id> --files \"<paths>\" --brief \"<text>\" [--anyway] [--dry-run]" >&2; exit 2; }
+usage() { echo "usage: bin/dispatch <issue-id> --files \"<paths>\" --brief \"<text>\" [--anyway] [--force] [--dry-run]" >&2; exit 2; }
 
-id=""; files=""; brief=""; anyway=0; dry=0
+id=""; files=""; brief=""; anyway=0; force=0; dry=0
 while [ $# -gt 0 ]; do
   case "$1" in
     --files) files="$2"; shift 2 ;;
     --brief) brief="$2"; shift 2 ;;
     --anyway) anyway=1; shift ;;
+    --force) force=1; shift ;;
     # Run every check and print the brief block, but write nothing to the
     # log. Added after a smoke test of this script left a phantom DISPATCH
     # note behind — a note that can be annotated but never removed, and that
@@ -189,6 +199,29 @@ if [ -n "$hits" ]; then
   fi
 fi
 
+# CHECK 4 — recently-touched files. A declared file that was touched in the
+# last 5 commits on any branch is hot: the change may still be landing, the
+# agent may be re-doing work that already shipped, or the base commit already
+# contains the fix. The commits are printed unconditionally; the dispatch is
+# refused unless --force is given.
+file_history_hits=""
+for f in $files; do
+  fhits=$(git log -5 --all --oneline -- "$f" 2>/dev/null)
+  if [ -n "$fhits" ]; then
+    file_history_hits="${file_history_hits}${file_history_hits:+
+}  $f:
+$(echo "$fhits" | sed 's/^/    /')"
+  fi
+done
+if [ -n "$file_history_hits" ]; then
+  echo "dispatch: declared files were touched in the last 5 commits on some branch:" >&2
+  echo "$file_history_hits" >&2
+  if [ "$force" != "1" ]; then
+    echo "  Review the commits above, then rerun with --force to proceed." >&2
+    exit 1
+  fi
+fi
+
 # ---------------------------------------------------------------------------
 # THE DENYLIST — what OTHER agents are holding right now
 # ---------------------------------------------------------------------------
@@ -405,6 +438,20 @@ Whether the tracker is reachable from inside your worktree depends on this
 project's config.json worktree.linkPaths and on whether this clone's hooks
 are installed. Ask the dispatching session for the issue text if you need it."
 
+  # Extract the issue description from the tracker JSON for context-file
+  # inclusion. Falls back to empty if unavailable or the JSON has no
+  # description field — the section is omitted rather than printing a
+  # confusing "(none)".
+  issue_description=$(printf '%s\n' "$issue_json" | python3 -c '
+import json, sys
+try:
+    data = json.loads(sys.stdin.read())
+    desc = data.get("description") or ""
+    print(desc)
+except Exception:
+    pass
+' 2>/dev/null || true)
+
   notes_rendered=$(printf '%s\n' "$notes_raw" | render_notes)
 
   # Not capped: an id with a long history is exactly the case the audit is
@@ -434,7 +481,22 @@ for s in suites:
   link_paths=$(cfg_get worktree.linkPaths)
 
   mkdir -p "$ctxdir"
+  # PRESERVE EXISTING CONTENT. The orchestrator may have already written a
+  # spec into this file before dispatching — that spec is the agent's primary
+  # input and must appear FIRST and intact. Read it before the redirect
+  # truncates the file; if present, it is emitted before the dispatch
+  # boilerplate under a clear separator.
+  existing_ctx=""
+  if [ -s "$ctx" ]; then
+    existing_ctx=$(cat "$ctx")
+  fi
   {
+    if [ -n "$existing_ctx" ]; then
+      printf '%s\n' "$existing_ctx"
+      echo
+      echo "---"
+      echo
+    fi
     echo "# Dispatch context — $id"
     echo
     echo "Written by bin/dispatch on $(date -u '+%Y-%m-%dT%H:%M:%SZ') from $ENTROPY_MACHINES_ROOT ($branch @ $head)."
@@ -503,6 +565,12 @@ for s in suites:
     echo "has not read it. It is recorded for the audit trail and it is NOT the"
     echo "limit of what you may write. The enforced limit is the claimed list above."
     echo
+    if [ -n "$issue_description" ]; then
+      echo "## Issue description"
+      echo
+      echo "$issue_description"
+      echo
+    fi
     echo "## Your brief"
     echo
     echo "    $brief"
@@ -596,101 +664,116 @@ if [ "$dry" -eq 1 ]; then
 else
   echo "dispatch: OK — brief + scope recorded on $id."
 fi
-echo "Dispatch the worker defined in agents/isolated-worker.md."
-echo "  Claude Code: Agent tool, subagent_type: isolated-worker."
-echo "  A different runner: give it its own worktree, this brief directly (not"
-echo "  just pointed at it), and a way for you to read back its HANDOFF.md —"
-echo "  see the note at the top of agents/isolated-worker.md."
-echo "  issue: $id"
-echo "  advisory --files: $files"
-echo "  ENFORCED denylist: $deny_field"
-echo "  brief: $brief"
-echo
-# Pasted verbatim into the agent's brief. Four keys, one line each, and the
-# instruction says so twice — an agent given a free-form "write up what you
-# found" returns prose the lander then has to read and compress, which is
-# the work this was meant to remove. The file is gitignored, so the agent
-# cannot accidentally add it to the tree.
-echo "PASTE INTO THE AGENT'S BRIEF:"
-echo "  BRIEF: $brief"
-echo
-# FIRST LINE after the brief, and the load-bearing one — see the measured
-# numbers in the header. This holds regardless of whether your runner
-# auto-loads a project-instructions file into subagents: proximity to the
-# prompt is what changes behaviour, not presence in context.
-echo "  FIRST, before anything else: read this file, in full, with one Read:"
-echo "    $ctx"
-echo "  It is your issue text, what already landed under this id, your scope and"
-echo "  brief, what earlier agents left you, and this project's suites. It is in"
-echo "  the MAIN checkout, NOT in your worktree; the path above is absolute, use"
-echo "  it as-is."
-if [ "$dry" -eq 1 ]; then
-  echo "  (--dry-run: that file was NOT written. Rerun without --dry-run.)"
-fi
-# The cwd check, stated to the AGENT. This script already refuses a
-# non-root cwd, but that runs when the brief is written and the dispatch
-# call happens after — a `cd` in between still misroutes the worktree, and
-# has once taken out three agents at once this way. Nothing in the tool
-# chain can catch that on the way in, so the agent checks on the way out.
+# ---------------------------------------------------------------------------
+# STRUCTURED AGENT CALL
+# ---------------------------------------------------------------------------
+# The prompt is assembled and emitted as part of a JSON block containing the
+# exact Agent tool parameters. The orchestrator passes these directly — no
+# manual assembly, no remembering the subagent_type. The same measured
+# numbers from the header (pasted ~96%, referenced ~38%) shaped what goes
+# into the prompt: every load-bearing rule is INSIDE the prompt text, not
+# merely referenced.
 #
-# --git-common-dir answers WHICH REPO IS THIS A WORKTREE OF. From a linked
-# worktree it resolves to the MAIN repo's .git as an ABSOLUTE path, so it
-# carries the repo's own path. From a non-worktree checkout at its root it
-# prints a bare relative `.git`, which is why the wording calls that out as
-# its own reportable state rather than leaving the agent to interpret it.
-# --show-toplevel is the wrong check here: it prints the WORKTREE's own
-# path, which can never equal the main repo's path, so it can never confirm
-# which repo the worktree belongs to.
-echo "  Your scope is a DENYLIST, not an allowlist. These files are claimed by"
-echo "  another agent RIGHT NOW and you must NOT write them: $deny_field"
-echo "  Everything else is yours if the fix needs it. If your fix needs a CLAIMED"
-echo "  file: STOP — do not write it, and do NOT ship the half you were allowed"
-echo "  to write. Leave the in-scope work coherent and name the exact file and"
-echo "  what it must contain in HANDOFF.md's found: line. The context file above"
-echo "  has the full protocol and says what does and does not enforce it."
-echo "  SECOND, before you write anything: run \`git rev-parse --git-common-dir\`."
-echo "  It prints the MAIN repo's .git — which repo your worktree branched from."
-echo "  It MUST contain /$(basename "$ENTROPY_MACHINES_ROOT")/. A bare relative \`.git\` means you"
-echo "  are not in a worktree at all: report that."
-echo "  If either is wrong, STOP and report it. NEVER cd to make it pass and"
-echo "  never write to the shared checkout — a cd is the failure, not the fix."
-echo "  Do NOT use --show-toplevel here: yours is the worktree path, so it can"
-echo "  never end in /$(basename "$ENTROPY_MACHINES_ROOT") and tells you nothing about the repo."
-# THE SCRATCHPAD, IN THE PASTE BLOCK RATHER THAN ONLY IN A DOC. The same
-# measurement that shapes the rest of this block puts a pasted rule at ~96%
-# and one sitting only in a doc the agent was told to go read at far less —
-# and a scratchpad the worker never hears about is the shared one it was
-# already using.
-echo "  YOUR PRIVATE SCRATCHPAD is \`.scratch\` at the root of your worktree —"
-echo "  mutators, probe harnesses, captured suite output go THERE, not in any"
-echo "  scratchpad shared with the agents running beside you. Two concurrent"
-echo "  agents have overwritten each other's throwaway files by both reaching"
-echo "  for a shared scratch directory instead. If a tool refuses to write"
-echo "  through .scratch, say so in HANDOFF.md — do not fall back to a shared"
-echo "  scratchpad silently."
-# Earlier agents' carry-forward lines, INSIDE the paste block rather than
-# only in the context file above it, for the same measured reason.
-if [ -n "$carry" ]; then
-  echo "  WHAT EARLIER WORK ON THIS ISSUE LEFT YOU (you may not be able to look"
-  echo "  this up yourself — see the context file for how to check):"
-  echo "$carry"
+# The prompt is written to a temp file so Python can JSON-encode it with
+# proper escaping. The file is cleaned up on exit.
+prompt_tmp="$ctxdir/.prompt-$id.tmp"
+trap 'rm -f "$prompt_tmp"' EXIT
+{
+  echo "BRIEF: $brief"
   echo
-fi
-echo "  Before you finish, write HANDOFF.md at the root of your worktree."
-echo "  Exactly these four keys, ONE LINE each, no prose:"
-echo "    changed: <what you changed>"
-echo "    found:   <seen but not fixed, out of scope — or: none>"
-echo "    assumed: <what you took as given — or: none>"
-echo "    next:    <what the next agent needs to know — or: none>"
-echo "  Keep it under six lines total. Do not commit it; it is gitignored."
-echo "  AFTER YOU STOP YOU WILL BE QUESTIONED, while you are still resumable, and"
-echo "  your work is not lifted until your answers are recorded. The questions are"
-echo "  adversarial on purpose — what you did NOT run, which of your assertions is"
-echo "  weakest, what you took on trust, what in the brief you skipped, what you"
-echo "  would check next. They are listed in the context file above; note the"
-echo "  answers as you work. \"Nothing\" to every one of them is refused."
+  # FIRST LINE after the brief, and the load-bearing one — see the measured
+  # numbers in the header. This holds regardless of whether your runner
+  # auto-loads a project-instructions file into subagents: proximity to the
+  # prompt is what changes behaviour, not presence in context.
+  echo "FIRST, before anything else: read this file, in full, with one Read:"
+  echo "  $ctx"
+  echo "It is your issue text, what already landed under this id, your scope and"
+  echo "brief, what earlier agents left you, and this project's suites. It is in"
+  echo "the MAIN checkout, NOT in your worktree; the path above is absolute, use"
+  echo "it as-is."
+  if [ "$dry" -eq 1 ]; then
+    echo "(--dry-run: that file was NOT written. Rerun without --dry-run.)"
+  fi
+  # The cwd check, stated to the AGENT. This script already refuses a
+  # non-root cwd, but that runs when the brief is written and the dispatch
+  # call happens after — a `cd` in between still misroutes the worktree, and
+  # has once taken out three agents at once this way. Nothing in the tool
+  # chain can catch that on the way in, so the agent checks on the way out.
+  #
+  # --git-common-dir answers WHICH REPO IS THIS A WORKTREE OF. From a linked
+  # worktree it resolves to the MAIN repo's .git as an ABSOLUTE path, so it
+  # carries the repo's own path. From a non-worktree checkout at its root it
+  # prints a bare relative `.git`, which is why the wording calls that out as
+  # its own reportable state rather than leaving the agent to interpret it.
+  # --show-toplevel is the wrong check here: it prints the WORKTREE's own
+  # path, which can never equal the main repo's path, so it can never confirm
+  # which repo the worktree belongs to.
+  echo "Your scope is a DENYLIST, not an allowlist. These files are claimed by"
+  echo "another agent RIGHT NOW and you must NOT write them: $deny_field"
+  echo "Everything else is yours if the fix needs it. If your fix needs a CLAIMED"
+  echo "file: STOP — do not write it, and do NOT ship the half you were allowed"
+  echo "to write. Leave the in-scope work coherent and name the exact file and"
+  echo "what it must contain in HANDOFF.md's found: line. The context file above"
+  echo "has the full protocol and says what does and does not enforce it."
+  echo "SECOND, before you write anything: run \`git rev-parse --git-common-dir\`."
+  echo "It prints the MAIN repo's .git — which repo your worktree branched from."
+  echo "It MUST contain /$(basename "$ENTROPY_MACHINES_ROOT")/. A bare relative \`.git\` means you"
+  echo "are not in a worktree at all: report that."
+  # THE SCRATCHPAD, IN THE PASTE BLOCK RATHER THAN ONLY IN A DOC. The same
+  # measurement that shapes the rest of this block puts a pasted rule at ~96%
+  # and one sitting only in a doc the agent was told to go read at far less —
+  # and a scratchpad the worker never hears about is the shared one it was
+  # already using.
+  echo "YOUR PRIVATE SCRATCHPAD is \`.scratch\` at the root of your worktree."
+  # Earlier agents' carry-forward lines, INSIDE the paste block rather than
+  # only in the context file above it, for the same measured reason.
+  if [ -n "$carry" ]; then
+    echo "WHAT EARLIER WORK ON THIS ISSUE LEFT YOU:"
+    echo "$carry"
+    echo
+  fi
+  echo "THIRD, write the file .dispatch-issue at the root of your worktree,"
+  echo "containing ONLY this line: $id"
+  echo "This identifies your worktree to the auto-verifier polling for it."
+  echo "Before you finish, write HANDOFF.md at the root of your worktree."
+  echo "Exactly these four keys, ONE LINE each, no prose:"
+  echo "  changed: what you changed"
+  echo "  found:   seen but not fixed, out of scope — or: none"
+  echo "  assumed: what you took as given — or: none"
+  echo "  next:    what the next agent needs to know — or: none"
+} > "$prompt_tmp"
+
+# Emit the structured agent call — the orchestrator passes these fields
+# directly to the Agent tool. subagent_type and isolation are set here;
+# the orchestrator must not override them.
+echo
+echo "--- AGENT CALL ---"
+python3 -c '
+import json, sys
+prompt = open(sys.argv[1]).read()
+call = {
+    "subagent_type": "general-purpose",
+    "isolation": "worktree",
+    "name": sys.argv[2],
+    "description": "Implement " + sys.argv[2],
+    "prompt": prompt
+}
+print(json.dumps(call, indent=2))
+' "$prompt_tmp" "$id"
+echo "--- END AGENT CALL ---"
+echo
+echo "--- AUTO-VERIFY ---"
+echo "bin/auto-verify $id"
+echo "--- END AUTO-VERIFY ---"
+echo
+echo "Pass the AGENT block to the Agent tool AND run the AUTO-VERIFY command"
+echo "via the Bash tool (run_in_background: true) — both in ONE message."
+echo "The worker implements; bin/auto-verify polls for HANDOFF.md at zero token"
+echo "cost, then emits a verifier Agent call. Paste that call when notified."
+echo "The verifier runs interrogate → lift → test → verify. YOU review and commit."
+echo "  issue: $id | advisory --files: $files | ENFORCED denylist: $deny_field"
 echo
-echo "WHEN YOU LAND IT, before committing:"
+echo "To skip auto-verification and land manually:"
 echo "  bin/handoff $id --interrogate                     # the questions; send them to the LIVE agent"
 echo "  bin/handoff $id --record-interrogation --answer \"...\"   # what it said"
 echo "  bin/handoff $id --from <agent-worktree> --lift    # copies the files IN, refusing any that drifted"

package/bin/entropy-machines-init

@@ -312,6 +312,23 @@ function start(argv) {
   if (!fs.existsSync(serve)) {
     die([`entropy-machines: ${path.join(loc.shown, 'bin', 'serve')} not found.`]);
   }
+  // Agent onboarding notice — only if no agent config file mentions
+  // entropy-machines yet. Checks every common agent instruction file.
+  const agentConfigPaths = [
+    path.join(root, 'CLAUDE.md'),
+    path.join(root, '.claude', 'CLAUDE.md'),
+    path.join(root, '.cursorrules'),
+    path.join(root, '.github', 'copilot-instructions.md'),
+    path.join(root, '.windsurfrules'),
+  ];
+  const agentOnboarded = agentConfigPaths.some((p) => {
+    try { return fs.readFileSync(p, 'utf8').includes('entropy-machines'); } catch { return false; }
+  });
+  if (!agentOnboarded) {
+    console.log(`\n${BOLD}${YELLOW}  ⚠ your coding agent doesn't know about entropy-machines yet.${RESET}`);
+    console.log(`    Point it at ${CYAN}${path.join(loc.shown, 'docs', 'AGENT-QUICKSTART.md')}${RESET} before answering the PRD.\n`);
+  }
+
   console.log(`\n${BOLD}entropy-machines: starting serve from ${loc.shown}/${RESET}\n`);
   const r = spawnSync('sh', [serve], { cwd: loc.dir, stdio: 'inherit' });
   process.exit(r.status ?? 1);