docs(slash): split /hew:auto (in-conversation) from /hew:loop (subprocess) (hew-6n0v)

CLAUDE.md

@@ -118,7 +118,7 @@ hew loop prune-worktrees [--apply]    # GC orphan worktrees from crashed paralle
 
 Each iter is a fresh `claude -p` (or `codex exec`) subprocess; the skill body + memory primer prefix is byte-stable across iters so the prompt cache hits (check `prompt_prefix_hash` in `.hew/loop/<run-id>/iter-NNN.json`). `--fallback-runtime` is primary-sticky with a configurable cooldown (`--fallback-cooldown-iters`, default 3) — see [docs/LOOP.md](./docs/LOOP.md#fallback-runtime) for the worked example. Parallel runs (`--jobs N`) lay down per-worker git worktrees under `~/.hew/wt/<run-id>/<n>/` and merge each `loop/<run-id>/w<n>` branch back at shutdown — see [docs/LOOP.md](./docs/LOOP.md#parallel-runs).
 
-`/hew:auto` now points at `hew loop run --until-empty`. The in-conversation walk is still reachable via `/hew:work`. Full guide: [docs/LOOP.md](./docs/LOOP.md).
+`/hew:loop` drives this subprocess loop. `/hew:auto` is the in-conversation, epic-scoped walk — one session, one epic, mid-loop steering. Full guide: [docs/LOOP.md](./docs/LOOP.md).
 
 ### Statusline
 

commands/auto.md

@@ -1,30 +1,58 @@
 ---
-description: Autonomously drain the queue via the process-level loop (`hew loop run --until-empty`).
+description: Drive the loop in-conversation, walking the children of one active epic.
 ---
 
-Run the autonomous outer loop until the ready queue drains:
+In-conversation, epic-scoped driver. `/hew:auto` stays inside the
+current Claude session and walks the children of one active epic in
+dependency order — one continuous transcript, full mid-loop steering.
+
+This is **not** the subprocess loop. For fresh-context-per-iter with
+prompt-cache hits, hard caps, and per-iter logs on disk, use
+[`/hew:loop`](./loop.md) (`hew loop run`).
+
+## Pick the active epic
+
+If the user named one in the prompt, use it. Otherwise:
 
 ```sh
-hew loop run --until-empty
+hew epic list                    # open epics
+hew epic tree <epic-id>          # children + dep order for the chosen epic
 ```
 
-`--until-empty` is on by default — stop signals fire when the queue
-hits zero, when a budget caps, when the operator touches the stop-file,
-or on a runtime error. Use `--max-iter N` to bound the run, `--strict`
-(default) to promote craft warnings to failures, `--budget-tokens N` /
-`--budget-wall <duration>` for hard caps.
+If exactly one open epic exists, pick it. If several, ask the user once
+which to drive. Never default to the full `bd ready` set — that's the
+subprocess loop's job.
+
+## The walk
+
+Until the active epic has no open children:
+
+1. From `hew epic tree <epic-id>`, pick the next unblocked child
+   (lowest-id ties break by creation order). Skip closed/in_progress
+   children belonging to another assignee.
+2. Tail-call `/hew:next` for that task. `/hew:next` claims, runs the
+   full `hew-execute` loop (read → code → tests → `hew-guard` → close
+   → commit → optional `hew remember`), and returns.
+3. Loop. The session stays focused on one epic at a time; cross-epic
+   work needs an explicit re-invocation.
+
+Stop when:
 
-Per-iter logs land in `.hew/loop/<run-id>/iter-NNN.json`. Inspect with
-`hew loop list`, `hew loop logs --tail 5`, `hew loop cancel`.
+- All children of the active epic are closed → run `/hew:verify`,
+  then offer to close the epic and report done.
+- A Rule-4 architectural change blocks progress → surface to the
+  user and wait.
+- The user interrupts.
 
-For the in-conversation walk through the workflow (older `/hew:auto`
-behavior — useful when you want to drive iters from inside one Claude
-session rather than spawning fresh subprocesses), call `/hew:work` and
-let it tail-call `/hew:next` until either:
+Honor every `hew-execute` rule along the way (guard before close,
+deviation tags in close reasons, atomic commits, branching contract).
 
-- `hew status` ready list is empty (call `/hew:verify`, then report done), or
-- a Rule-4 architectural change blocks you (stop, surface, wait).
+## When to reach for `/hew:loop` instead
 
-Honor all guard / deviation / convention rules; atomic commits per task.
+- You want each task in a fresh context window with a cache-warm
+  prefix.
+- You want hard caps (token / wall-clock / max-iter) and per-iter
+  logs to disk.
+- You're draining the global ready queue, not focusing one epic.
 
-See `docs/LOOP.md` for the full design.
+See [`docs/LOOP.md`](../docs/LOOP.md) for the full design.

docs/COMMANDS.md

@@ -40,11 +40,13 @@ Fast mode: one task, no plan/decompose overhead.
 
 ### `/hew:auto`
 
-Run plan → decompose → execute → verify autonomously. Now a thin
-pointer at `hew loop run --until-empty` — the in-conversation walk is
-still reachable via `/hew:work`.
+In-conversation, epic-scoped driver. Walks the children of one active
+epic in dependency order, tail-calling `/hew:next` per task, in a
+single Claude session. For the subprocess loop that drains the global
+ready queue with cache-warm prefixes and on-disk per-iter logs, use
+`/hew:loop`.
 
-- Use when: you trust the agent to drive end-to-end without pause
+- Use when: you want one session focused on one epic with mid-loop steering
 
 ### `/hew:loop`
 

docs/LOOP.md

@@ -423,8 +423,8 @@ Outstanding bugs discovered by the run:
 ## Related
 
 - `commands/loop.md` — the `/hew:loop` slash body.
-- `commands/auto.md` — the `/hew:auto` slash, now a thin pointer at
-  `hew loop run --until-empty`.
+- `commands/auto.md` — the `/hew:auto` slash: in-conversation,
+  epic-scoped walk (one session, one epic, mid-loop steering).
 - `hew_core::runner` — pure precedence logic for stop signals.
 - `hew_core::prompt` — cache-disciplined assembler.
 - `hew_core::runtime` — Claude Code spawner.

skills/core/hew-execute.md

@@ -457,9 +457,14 @@ it out. Future-you saves the lookup time.
 
 Run `hew prime execute` again. Pick the next ready task. Continue.
 
-If the user said "do this one task," stop after closing it. If "keep going"
-or `/hew:auto`, loop until `hew prime execute` shows no ready tasks (then call `hew-verify`) or
-a Rule-4 architectural decision blocks you (then surface and stop).
+If the user said "do this one task," stop after closing it. If "keep going,"
+loop until `hew prime execute` shows no ready tasks (then call `hew-verify`)
+or a Rule-4 architectural decision blocks you (then surface and stop).
+
+If invoked via `/hew:auto`, the walk is scoped to the children of one
+active epic (`hew epic tree <id>`), not the global `bd ready` set —
+finish the epic, run `/hew:verify`, then stop. For the subprocess loop
+that drains the global queue with cache-warm prefixes, see `/hew:loop`.
 
 ### Step 10a — review picker (optional, config-gated)