@iowarp/clio-coder 0.4.2 → 0.4.4

package/skills/workflow/design-council/SKILL.md

@@ -7,7 +7,7 @@ triggers:
   - get multiple expert perspectives
   - weigh the architecture options
   - what would experts say
-version: 0.4.0
+version: 0.6.0
 license: Apache-2.0
 allowed-tools:
   - dispatch
@@ -17,12 +17,13 @@ allowed-tools:
   - ls
   - context
   - code_nav
+  - ask_user
 clio-coder:
   registry-id: iowarp/clio-coder
   source-url: https://github.com/iowarp/clio-coder/tree/main/skills/workflow/design-council
   audit: pass
   provenance: designed
-  eval-status: scenarios-recorded
+  eval-status: smoke-checked
   model-size: large
   agents:
     - scout
@@ -36,22 +37,90 @@ Run a bounded multi-perspective debate on a real design decision. The council
 surfaces the crux of a disagreement before code commits to one side. It is not
 a ritual: if experts would agree, do not convene it.
 
+## Arguments
+
+```text
+convene a design council on <decision>
+```
+
+There is no flag syntax; the trigger is conversational — "convene a design
+council on X", "debate this design", "get multiple expert perspectives".
+Whatever the user names is the decision. A referenced file, doc, or repo path
+in the same request is Step 0/1's grounding to read first, not a separate
+argument.
+
+**Headless is the enforced default, not a suggestion.** A council is several
+worker runs; nobody is waiting between rounds in a headless run, and every
+round that actually runs costs real wall-clock time on top of the
+orchestrator's own turns. `ask_user` is not registered in a headless run,
+so the single question Step 1 asks is refused as an unregistered tool
+rather than answered. Treat that refusal (or
+skip the call and reason from this paragraph directly — one is not more valid
+than the other) as the fixed answer **quick mode: exactly three perspectives,
+exactly one round (Positions) plus synthesis.** Do not compose four or five
+perspectives headlessly and do not run a Responses or Convergence round
+headlessly, no matter how contested the topic looks — four/five perspectives
+and multi-round debate are for a live session with an operator who actually
+asked for the deeper pass. This is the one rule the skill's own prior smoke
+history says a model will not reliably self-infer from prose alone, so treat
+the number 3 and the number 1 as hard, not as defaults to raise if the topic
+seems to deserve more.
+
+**Dispatch call shape.** Compose the round's perspectives, then make exactly
+one `dispatch` call with all of them in `tasks` and `mode="parallel"`. If
+that call comes back admission-denied for endpoint or target capacity (a
+single local model instance commonly allows only one concurrent worker, so a
+3-task parallel wave can be denied outright rather than queued), retry the
+identical `tasks` batch in one dispatch call with `mode="sequential"` instead
+— the tool runs them one after another itself. Never split a round into
+several separate one-task `dispatch` calls made one at a time waiting on each
+result before deciding the next; that is the serial-perspectives pattern that
+produced the round-trip cost the skill's own timeout history is about, and it
+does not fix the capacity problem the parallel call already reported. Do not
+call `dispatch(list:true)` to probe capacity first — it answers nothing about
+concurrency and only spends a call.
+
+Declare `intent: {read_roots: [...], relevant_paths: [...]}` with paths
+relative to the repo root on every dispatch call instead of pasting an
+absolute path into `task`/`briefing` prose (a config value, a mount point).
+An absolute path token in briefing/task text with no declared `intent` is
+rejected as `legacy_scope_path_absolute`.
+
+A dispatch call's own synchronous result already carries every worker's
+output — do not follow it with a `bash`/`read` pass over the receipt file on
+disk to re-read what you already have. The steps below are the plan; do not
+open a `tasks` list for them. This skill's tool surface is exactly
+`dispatch`, `read`, `grep`, `find`, `ls`, `context`, `code_nav`, and
+`ask_user` (`context` and `ask_user` are always available regardless).
+`tasks` and `bash` both sit outside it and any call to either is refused —
+locate files with `find`/`ls`, not `bash find`/`bash ls`; inspect a receipt
+with `read`, not `bash cat`. This skill never writes: `write` and `artifact`
+are not on its surface, so the synthesis in Step 4 is chat output, never a
+file.
+
 ## Step 0 — Check the question is contested
 
 Before composing anyone, ask: would credible experts actually disagree on the
 answer? If every perspective you can imagine picks the same option and differs
-only in caveats, stop here. Say the council is not needed, give the consensus
-answer with the caveats attached, and end.
+only in caveats, stop here — do not dispatch anything. Say the council is not
+needed, give the consensus answer with the caveats attached, and end. Do not
+dispatch a round "just to confirm" a consensus call you already reached —
+that is the ritual this step exists to skip, and it still costs the same
+wall-clock time and worker slots as a real debate. Trust this self-check the
+same way you trust the rest of your own reasoning; a council you convened to
+double-check yourself is not more rigorous than the judgment behind it.
 
 ## Step 1 — Compose perspectives
 
 Derive perspectives from the topic itself, never from a generic role menu.
-Three is the default and the right number for almost every decision. Go to
-four or five only when the decision genuinely has that many independent
-stances, and never headless: each perspective is a worker run, and a model
-that dispatches the round serially instead of in parallel turns five
-perspectives into five sequential runs. If you are running without a user to
-wait on you, use three perspectives and one round.
+On a genuinely contested topic, call `ask_user` once with `mode:
+"single_question"` asking whether this should be a quick pass (three
+perspectives, one round) or the full debate (up to five perspectives, up to
+three rounds). See Arguments for what a headless run does with that call.
+In a live session where the user answers, honor the requested depth. Compose
+three perspectives by default; go to four or five only in that live full-
+debate case, and only when the decision genuinely has that many independent
+stances.
 
 Each perspective gets:
 
@@ -74,11 +143,13 @@ perspective from the read-only recipes in the live catalog:
 - `researcher`: stance leaning on external docs, standards, or papers.
 - `provenance`: stance arguing from runtime evidence and receipts.
 
-Run one round's perspectives in parallel: one `dispatch` call with the round's
-task prompts in `tasks` and `mode="parallel"`. Rounds are sequential. Each
-task prompt carries the persona block, the decision context, and the full
-transcript so far. Workers never edit files; the debate is analysis only.
-Dispatch receipts link every statement to a worker run.
+See Arguments for the exact call shape (one batched `tasks` call, the
+`mode="sequential"` capacity fallback, `intent` for scope, no literal shell
+syntax). Rounds are sequential; a round's own perspectives are the one
+dispatch call. Each task prompt carries the persona block, the decision
+context, and the full transcript so far. Workers never edit files; the
+debate is analysis only. Dispatch receipts link every statement to a worker
+run.
 
 ## Step 3 — Run the rounds
 
@@ -90,14 +161,15 @@ Dispatch receipts link every statement to a worker run.
    still disagrees and why that crux is the crux, and its final
    recommendation.
 
-**Quick mode** (user asked for a light pass): round 1 plus synthesis. No
-responses round.
+**Quick mode** (headless default, or a user asking for a light pass): round 1
+plus synthesis. No responses round, no convergence round.
 
-**Early termination.** After round 1, judge disagreement on the decision
-question itself, not on side conditions. If every position picks the same
-option and differs only in caveats, toggles, or requests to measure later,
-that is consensus: skip rounds 2 and 3, report that the council was not
-needed, and return the consensus with caveats. Never manufacture friction.
+**Early termination** (full-debate mode only). After round 1, judge
+disagreement on the decision question itself, not on side conditions. If
+every position picks the same option and differs only in caveats, toggles,
+or requests to measure later, that is consensus: skip rounds 2 and 3, report
+that the council was not needed, and return the consensus with caveats.
+Never manufacture friction.
 
 ## Step 4 — Synthesize
 
@@ -124,10 +196,11 @@ synthesis line has a citation and the recommendation names its crux.
 
 ## Degraded mode
 
-If dispatch is unavailable or admission-denied, run the same rounds inline:
-write each perspective's contribution yourself, sequentially, same round
-structure and synthesis format. Label the output as degraded (single-model
-debate, no receipts).
+If dispatch is unavailable or admission-denied for a reason other than the
+capacity retry in Arguments (the tool itself is missing from the surface, or
+every retry is denied), run the same rounds inline: write each perspective's
+contribution yourself, sequentially, same round structure and synthesis
+format. Label the output as degraded (single-model debate, no receipts).
 
 ## Boundaries
 
@@ -141,7 +214,19 @@ this skill when the debate needs the full round structure and receipts.
 ## Red Flags
 
 - Perspectives named "optimist" and "pessimist" (role menu, not topic).
-- More than five perspectives, or debate rounds beyond three.
+- Composing four or five perspectives, or running a Responses/Convergence
+  round, in a headless run — the enforced default is exactly three and
+  exactly one, not a ceiling to raise because the topic looks deep.
+- Splitting a round into several single-task `dispatch` calls issued one at a
+  time instead of one batched `tasks` call (retried as `mode="sequential"`
+  on a capacity denial).
+- Calling `dispatch(list:true)` before dispatching the round.
+- Pasting an absolute path into a dispatch `task`/`briefing` instead of a
+  declared `intent`, or quoting literal shell syntax inside a persona's
+  argument.
+- Reaching for `bash`/`read` on a receipt file the dispatch call's own result
+  already contains.
+- Opening a `tasks` list for the round structure; `tasks` is refused.
 - A synthesis that averages positions instead of naming the crux.
 - Manufactured disagreement on a settled question.
 - A worker asked to edit files as part of the debate.

package/skills/workflow/design-council/evals.md

@@ -95,3 +95,164 @@ default and tells a headless run to use three and one round, which is the
 blocker the timeout exposed. Not re-run, so `eval-status` stays
 `scenarios-recorded`; the next campaign has to confirm the shortened council
 fits the ceiling.
+
+## Battletest record (2026-09-03) — 0.4.0 -> 0.5.0
+
+Fixture: `/home/akougkas/eval-temp/harness/test_designcouncil.py`, a
+self-contained repo (`src/checkpoint.py` writing one raw `.npy` per rank per
+step to a shared parallel filesystem, `src/config.py`/`config.yaml` using
+`pyyaml`) adapted from this file's own worked examples. S1 = HDF5-vs-Zarr
+(genuinely contested), S2 = hand-roll-YAML-vs-keep-pyyaml (consensus), S4 =
+"poke holes in my plan" anti-trigger. `runner.py`'s `timeout=` was raised to
+1800s for this skill specifically — the 900s default is a `dispatch` fan-out
+ceiling, not a model-quality one, and the mission called for confirming the
+v0.3.0 "three perspectives, one round" headless fix on its own terms, not
+routing around it. Primary: `qwen3.8-27b`/`dynamo`. Cross-model confirm:
+`ornith1.5-35b-moe`/`mini`. Both runs shared the `dynamo` LM Studio endpoint
+with concurrently active sibling battletest sessions (`grill-me`,
+`workflow-distiller`) launched via `herdr` during this pass — real,
+externally-caused contention, not a fixture artifact; see below.
+
+| run | scenario | model | wall | turns | dispatch calls | safety blocks | score | outcome |
+|---|---|---|---|---|---|---|---|---|
+| baseline (no skill) | S1 | qwen3.8-27b | 121s | 5 | 0 | 0 | 3/11 | no skill invoked (ran under `--no-skills`); the model noticed the installed skill anyway and narrated "four positions, real cross-examination" as one inline monologue — a solid single-model analysis but no dispatch, no receipts, no named-recipe workers |
+| v1 (frozen 0.4.0) | S1 | qwen3.8-27b | 1740s, **killed at the 1800s ceiling** (exit -9) | 22 | 12 | 7 | 4/11 | composed **four** perspectives and ran into **round 2**, both violating the stated headless "three perspectives, one round" default; opened a `tasks` plan (refused); two `dispatch` calls rejected for an absolute path token in `briefing` (`legacy_scope_path_absolute`); one denied for endpoint capacity; one **hard-blocked as `rm-recursive-or-force`** because a perspective's own round-1 argument prose said "...you can `ls`, checksum, `rm -rf`, and publish..." — the admission layer's damage-control scan matched the quoted shell syntax inside the debate text itself, not an executed command; reached for `bash` to inspect a receipt file (refused). This is the same failure class the 2026-08-13 smoke record flagged, confirmed still present, worse: the v0.3.0 fix was never actually followed |
+| v2 (first hardened cut) | S1 | qwen3.8-27b | 416s | 11 | 3 | 4 | 8/11 | one batched `tasks`-array `dispatch` call, all 3 capacity/timeout-denied under real endpoint contention; correctly fell back to Degraded mode, cited the exact denial reasons, labeled the output degraded, produced a complete synthesis with agreements/crux/dissent — no `tasks` misuse, no shell-block trigger, no one-at-a-time call splitting |
+| v2 (post Step 0 strengthen) | S1 | qwen3.8-27b | 304s | 7 | 3 | 4 | 8/11 | same shape: parallel wave denied, sequential retry denied/timed out, correct Degraded fallback, well-formed synthesis citing the transcript |
+| v2 | S2 | qwen3.8-27b | 52.5s / 60.6s (before/after Step 0 edit) | 5 / 6 | **0** | 0 | **5/5** both | Step 0 stopped before any dispatch, stated the council was not needed, gave the consensus (keep `pyyaml`, `safe_load` only) with caveats, and named the repo's actually-contested question (the checkpoint format) as a pointer — no manufactured friction either run |
+| v2 | S4 | qwen3.8-27b | 69.4s | — | 0 | 0 | 3/3 | did not convene a council; ran a grill-me-shaped one-question-at-a-time interrogation instead and named `grill-me` |
+| v2 (cross-model) | S1 | ornith1.5-35b-moe/mini | 384s | 10 | 4 | 5 | 7/11 | 3 of 4 `dispatch` calls denied/timed out on the **same `dynamo` endpoint** (workers defaulted there even though the orchestrator itself ran on `mini`); one stray `monitor` call refused (outside the skill's surface); correctly diagnosed the capacity pattern in its own words ("times out at ~57s... despite reporting 0/4 slots in use... exhausted the capacity fallback") and ran Degraded mode with a clearly labeled warning banner |
+| v2 (cross-model) | S2 | ornith1.5-35b-moe/mini | 239.5s / 188.1s (before/after Step 0 edit) | 6 | 3 / 2 | 3 / 2 | 2/5 both | did **not** skip Step 0's dispatch the way qwen did — ran one capacity-retried round anyway, but stopped there (no round 2/3), reached the same correct consensus ("keep pyyaml", supply-chain caveat preserved as a contingent dissent, not manufactured), and stated the council-not-needed conclusion explicitly; the Step 0 wording strengthen did not change this model's behavior |
+
+**S3 (dispatch unavailable) — no clean forced trigger found, confirmed by
+reading the CLI, not assumed**: `clio-coder run --help`'s `--tool-profile`
+narrows a *dispatched sub-agent's own* tool set and requires `--agent`
+(`clio-coder run: fleet dispatch flags require --agent <recipe-id>`); there
+is no flag that strips `dispatch` from a top-level `--skill` orchestrator
+run's own surface in this harness. Editing the skill's own `allowed-tools`
+to omit `dispatch` would test a different skill, not this one. This is a
+real, documented harness gap, not faked around. In its place, S3's expected
+behavior was exercised **organically, repeatedly, for real**: every S1 run
+on both models hit genuine `dispatch` admission denial or timeout from
+endpoint capacity, and Degraded mode fired correctly every single time —
+labeled degraded, same round structure, synthesis format intact, no
+receipts claimed that did not exist.
+
+**The dispatch-viability and recipe-existence questions, resolved
+empirically:**
+
+- `scout`, `researcher`, and `provenance` all exist as builtin shadow-agent
+  recipes (`src/domains/agents/builtins/*.md`, `capabilityClass: read-only`)
+  and are dispatchable — every hardened run that got a `dispatch` call
+  admitted used one of them by name and got real worker output back.
+- Each recipe's own system prompt declares a rigid JSON-only result
+  contract (`{"findings":[...]}`, `{"source":...}`, `{"confirmedFacts":...}`)
+  that has nothing to do with a debate position. In practice this was
+  **not** a blocker: V1's successfully-admitted round 1 came back as full
+  argumentative prose (named claims, attacks, citations, mind-change
+  conditions) from `researcher`/`scout` workers, not the declared narrow
+  JSON shape — the persona in the task prompt won out over the recipe's
+  own stated output contract for the caller-facing transcript. Worth
+  knowing, not worth re-architecting around.
+- The actual, dominant blocker is **`dispatch` admission capacity on a
+  single-instance local LM Studio target**. `~/.local/state/clio-coder/
+  endpoint-slots.json` records the `dynamo` endpoint (`100.104.197.69:1234`)
+  at `"slots": 1`. A 3-task parallel wave is denied outright
+  (`capacity exceeded (3/1 slots)`), and the `mode="sequential"` retry this
+  pass added to the skill is followed correctly by both models but still
+  gets denied or times out (`admission timed out after ~57s... 0/4 worker
+  slots in use` — a scheduling state that never resolves within the wait
+  window), evidently because the orchestrator's own foreground session
+  already holds the endpoint's only slot. This reproduced independently on
+  `mini` too: workers dispatched from an orchestrator running on `mini`
+  still routed to `dynamo`'s endpoint by default, so the same 1-slot
+  contention applied there as well — confirming the brief's suspicion that
+  worker fan-out may silently default to an unexpected node/target. Some
+  of this pass's contention was real concurrent load, not just self-
+  contention: `ps` showed sibling `grill-me`/`workflow-distiller`
+  battletest sessions actively running via `herdr` against the same
+  endpoint during these runs.
+- The full-auto/`authorityBasis` auto-grant fact supplied going in
+  (`deps.getAutonomy?.() === "full-auto" ? "full-auto-policy" :
+  "operator-plan-approval"`) turned out to be **moot for this skill**:
+  that gate only applies to `agent:"auto"` dispatch requests
+  (`src/tools/dispatch-arguments.ts`, `agentSelection` is only populated
+  when `requestedAgent === "auto"`). Design-council always pins an explicit
+  recipe id (`scout`/`researcher`/`provenance`), so `agentSelection` stays
+  `undefined` and the operator-approval/full-auto-policy distinction never
+  engages — admission for this skill's calls is governed purely by the
+  capacity/reservation machinery above, independent of `--autonomy`.
+- `legacy_scope_path_absolute`: an absolute path token (e.g. a value read
+  from `config.yaml`) pasted into `task`/`briefing` prose without a
+  declared `intent` is rejected. Fixed by telling the skill to declare
+  `intent.read_roots`/`relevant_paths` (relative) on every call instead.
+
+**Changes (0.4.0 -> 0.5.0):**
+
+1. **`## Arguments` contract**, ported from `grill-me`/`cut-it`'s shape.
+   States headless is the *enforced* default (exactly three perspectives,
+   exactly one round), not a self-assessed suggestion — the v0.3.0 fix's
+   prose alone did not hold on either model (V1 composed four perspectives
+   and ran round 2 headlessly).
+2. **Dispatch call shape spelled out**: one batched `tasks`-array call per
+   round; on capacity denial, retry the *same* batch with
+   `mode="sequential"` in one call rather than splitting into several
+   single-task calls issued one at a time (V1's actual failure — 12
+   separate `dispatch` calls, a `list:true` probe, and manual receipt
+   reads via `bash`, all of which V2 stopped doing).
+3. **`intent.read_roots`/`relevant_paths` guidance** to avoid
+   `legacy_scope_path_absolute` rejections from paths quoted in prose.
+4. **No literal shell syntax in a persona's argument text** — added after
+   V1's `rm-recursive-or-force` hard block fired on debate prose, not a
+   real command.
+5. **`ask_user` added to `allowed-tools`** (already always-exempt, now
+   documented) with one call at Step 1 on a contested topic, asking
+   quick-vs-full-debate depth; headlessly it cancels, which *is* the
+   three-perspective/one-round confirmation, mirroring the auto-cancel
+   pattern the planning category established rather than relying on
+   unaided self-assessment.
+6. **Explicit `tasks`/`bash`/receipt-re-read refusal lines**, matching the
+   sibling skills' pattern (`tasks` opened a plan in V1; `bash` was reached
+   for twice across the runs above to re-inspect a receipt the dispatch
+   call's own result already contained).
+7. **Step 0 strengthened** against dispatching "just to confirm" a
+   consensus call already reached — tested on `ornith1.5-35b-moe`/`mini`
+   (still dispatches once) and `qwen3.8-27b`/`dynamo` (unaffected, already
+   correct); see Still weak.
+8. Five new Red flags entries naming the concrete failures observed above.
+
+**Still weak:**
+
+- **Step 0's short-circuit is model-family-dependent.** `qwen3.8-27b`
+  trusts its own contested-or-not judgment and skips `dispatch` entirely
+  for S2 (5/5, 0 dispatch calls, both before and after the Step 0 edit).
+  `ornith1.5-35b-moe` does not: it dispatches one (capacity-retried) round
+  "to confirm" even on the same consensus topic, both before and after the
+  strengthened wording — 2/5 unchanged. It still stops after that one
+  round, still reaches the correct consensus, still preserves the dissent
+  as a contingent caveat rather than manufacturing friction, so the
+  user-facing outcome is fine; the wasted dispatch cost is the actual gap,
+  and more prose did not move it, consistent with the planning category's
+  own finding that some model-family behaviors don't fully generalize no
+  matter how much repetition is added.
+- **S1 never completed as a genuine 3-perspective/1-round council with
+  real receipts** on this pass — every attempt on both models hit real
+  endpoint capacity contention and degraded. The Degraded path is now
+  proven solid, but the "happy path" (dispatch succeeds, synthesis cites
+  real worker receipts) is unverified under this specific pass's
+  conditions; V1's transcript shows it *can* succeed (four real worker
+  runs completed with citable output before the round-2/shell-block
+  failure), so this reads as an availability problem this pass's timing
+  ran into, not a structural block — but it means the exact scoring
+  bullets that depend on `dispatch_receipts_ok` (perspective count,
+  receipts-ok) were not exercised clean this round.
+  `perspectives_dispatched`/`used_named_recipes` in the grading script
+  count attempted, not completed, dispatch tasks for this reason.
+- **No purpose-built S3 fixture** — see above; a future pass with a
+  dedicated low-capacity or offline dispatch target would let this be
+  tested directly instead of relying on organic contention.
+- `code_nav` and `grep` were barely exercised (fixture is small enough
+  that `read`/`ls`/`find` covered grounding in most runs).
+- Only one fixture domain (HDF5-vs-Zarr / YAML-parser) ran this pass; the
+  richer four-perspective MPI-checkpoint example from "Observed live-smoke
+  results" above was not re-run against 0.5.0.

package/skills/workflow/grill-me/SKILL.md

@@ -7,7 +7,7 @@ triggers:
   - stress-test this design
   - poke holes in this idea
   - clarify this plan one question at a time
-version: 0.4.0
+version: 0.5.1
 license: Apache-2.0
 allowed-tools:
   - read
@@ -33,9 +33,53 @@ Run a rigorous, repo-aware interview that turns a vague plan into explicit
 decisions. The point is not to interrogate for sport; it is to surface hidden
 branches before anyone writes code.
 
+## Arguments
+
+```text
+grill me on <plan, feature, or idea>
+```
+
+There is no flag syntax; the trigger is conversational — "grill me on X",
+"stress-test this design", "poke holes in this idea". Whatever the user
+names is the subject. A referenced file, doc, or repo path in the same
+request is Step 1's grounding to read first, not a separate argument.
+
+**This run has no back-and-forth.** There is no second turn in which a user
+reads your question and replies to it — whatever you ask, you must also
+answer yourself, in this same turn, before it ends. Do not write a question
+and stop to wait for a reply, in `ask_user` or in plain chat text; nothing
+is coming. Ending the turn on an open question — even one question, even a
+well-posed one — is this skill's single most common failure and worse than
+skipping the interview format entirely.
+
+There is no operator in a headless run: `ask_user` is not registered, so
+any call is refused as an unregistered tool rather than answered, every
+time, with no exceptions. Calling it again will not produce a different
+result, so one call is enough to confirm it (not required: reasoning from
+this paragraph alone is just as valid as calling it and observing the
+refusal). Whichever phase this lands in — even round
+1 — switch immediately to the assumed-confirm monologue for every phase
+from here on, in the same turn: state the question you would have asked,
+give your own best/recommended answer with the reasoning behind it, mark
+it `assumed — confirm`, and move to the next phase. Do not re-call
+`ask_user` hoping a later round behaves differently — that only burns the
+`max_rounds` budget without ever converging. Keep working the phase map,
+phase by phase, all the way through Step 5's decision log before ending
+the turn — never end on "Answer 1/2/3" or any other place a reply is
+expected.
+
+The phase map below is the plan; do not open a task list for it. This
+skill's tool surface is exactly `read`, `grep`, `ls`, `find`, `git`,
+`context`, `code_nav`, and `ask_user` (`context` and `ask_user` are always
+available regardless). `tasks` and `bash` both sit outside it and any call
+to either is refused — inspect a file with `read`, not `bash cat`/`bash
+head`/`bash wc`; locate files with `find` or `ls`, not `bash find`/`bash
+ls`; check repo state with the `git` tool, not shell `git`.
+
 ## Operating Contract
 
-- Use `ask_user` for the interview whenever it is active.
+- In a live session, use `ask_user` for the interview and actually wait for
+  the user's answer between rounds. In a headless run, see Arguments above.
 - For every interview round, call `ask_user` with `mode: "single_question"` and
   exactly one question.
 - On the first ask for a normal grill-me run, set `max_rounds` to a bounded
@@ -45,8 +89,6 @@ branches before anyone writes code.
   alternatives with short tradeoff descriptions.
 - The user answers in natural language. You translate answers into compact
   decision keys and rationale when you call `ask_user` with `action: "complete"`.
-- If `ask_user` is unavailable, ask in plain text, still one question at a
-  time, and keep an internal decision log.
 
 ## Phase Map
 
@@ -69,7 +111,11 @@ or "fill" when the decision is genuinely missing.
 
 Read what the user already gave you. If the task references files, plans, code,
 tests, or project conventions, inspect them before asking. Prefer
-`context(scope="workspace")`, `grep`, `read`, and codewiki tools over guessing.
+`context(scope="workspace")`, `grep`, `read`, `code_nav` (symbol and call-graph
+lookups), and codewiki tools over guessing. Use the `git` tool (`status`,
+`log`, not shell `git`) when the plan references repo state — recent
+history, uncommitted changes, what "decided" actually means for this repo
+right now.
 
 Privately build a phase map:
 
@@ -112,10 +158,26 @@ Good: "Which user should v1 optimize for first?"
 If an answer is vague, ask a follow-up on the same branch. Do not jump to a new
 branch while the current one is still unresolved.
 
+**Headless: there is no reply coming, whether `ask_user` comes back
+refused as unregistered or you never call it at all.** Neither is a vague answer to
+follow up on and neither is a signal to try again or to wait — both mean
+there is no operator this run, from round 1 on. Do not call `ask_user`
+again for this or any later phase, and do not phrase a question in plain
+text as if a reply is pending. From here, run every remaining phase
+(including this one) as the assumed-confirm monologue described in
+Arguments, in this same turn, through to the Step 5 decision log. See
+Arguments for the exact treatment.
+
 ### Step 4 - Respect Stop Signals
 
-Stop immediately when the user says "stop", "enough", "later", "done", "next
-time", or cancels the modal. Do not ask another question to confirm stopping.
+This step applies to a live session with a real operator. Stop immediately
+when the user says "stop", "enough", "later", "done", "next time", or cancels
+the modal. Do not ask another question to confirm stopping.
+
+A headless refusal of `ask_user` is not a stop signal from a user — it is the
+absence of an operator (see Step 3). Do not treat it as "the user cancelled
+this session"; treat it as the cue to switch to the assumed-confirm
+monologue and keep going to a complete decision log, not to stop early.
 
 If you have enough decisions to be useful, call:
 
@@ -140,8 +202,11 @@ state the partial decisions and the next unresolved root question.
 
 ### Step 5 - Complete
 
-Before final prose, call `ask_user` with `action: "complete"` and a compact
-`decisions` array. Then write the final decision log:
+In a live session, close with `ask_user` `action: "complete"` and a compact
+`decisions` array before final prose. In a headless run where `ask_user`
+already came back refused, skip straight to the decision log below — do
+not attempt another `ask_user` call just to close out; it will be refused
+too and adds nothing. Write the final decision log:
 
 ```markdown
 ## Decision Log - <topic>
@@ -189,4 +254,14 @@ Use this ordering when several questions are possible:
 - Asking about facts discoverable from the repo.
 - Letting `ask_user` hit the round limit without completing the interview.
 - Ending with a summary paragraph instead of the decision log.
-- Treating cancellation as permission to keep asking.
+- Re-calling `ask_user` for a later phase after an earlier round already came
+  back refused — the answer will not be different; that budget is wasted.
+- Ending a turn on "Answer 1/2/3", "let me know which you prefer", or any
+  other wording that expects a reply in a headless run — there is no next
+  turn for a reply to land in. This is the single most common failure mode
+  of this skill and the one to watch hardest for: asking one question, then
+  stopping, instead of running the assumed-confirm monologue through every
+  remaining phase to the decision log in the same turn.
+- Opening a `tasks` list for the phase map; `tasks` is refused.
+- Treating a headless `ask_user` refusal as the user's stop signal (Step 4)
+  instead of the absence-of-operator cue it actually is.