@gr8ful/spf 0.5.1 → 0.7.0

package/README.md

@@ -369,7 +369,7 @@ the Bitbucket identifier — finds no matching issues and looks exactly like
 nothing being configured at all.
 
 ```bash
-spf watch init                # idempotently seed tracker state (no-op for Jira — see below); run this first
+spf watch init                # idempotently seed tracker state (labels are a no-op report on Jira — see below); run this first
 spf watch                    # foreground daemon; Ctrl-C drains in-flight claims first
 spf watch --once             # one poll tick, then exit — good for cron
 spf watch --dry-run          # log intended claims/transitions, mutate nothing
@@ -377,19 +377,32 @@ spf watch --dry-run          # log intended claims/transitions, mutate nothing
 
 No GitHub App, no webhook, no Jira/Bitbucket app install — it's a plain REST poll against whichever combination is configured, same philosophy as the trace db's own polling contract. See [`assets/templates/`](assets/templates/) for full worked configs (also usable directly via `spf init --template <name>`), and `spf install-skill`'s installed skill (`roster.md`, `references/config.md`) for the field-by-field reference.
 
+### Priority, dependencies, and picking what's next
+
+Among every `<prefix>:ready` issue, `spf watch` claims in this order:
+
+1. **Priority** — the `<prefix>:priority:p0|p1|p2|p3` label (`p0` drop-everything, `p2` the default, `p3` someday). `spf watch init` seeds all four. A human relabeling an issue is the whole override mechanism — there's no separate priority command.
+2. **Sibling affinity** — among issues at the same priority, one whose parent feature already has a sibling in flight goes first. This is what tends to finish one feature before starting the next without giving up the one-PR-per-story design (see "Refining specs" below): each story is still its own claim, its own worktree, its own PR — affinity only orders which claim happens next.
+3. **Creation order** (oldest first) — the final tiebreaker.
+
+Before claiming anything, `spf watch` also checks the **frontier**: an issue's `blocked_by` dependencies (set by the refine lane, or by hand) must all carry `<prefix>:done` first. A leaf whose blockers aren't done yet is skipped, not blocked — it's simply reconsidered next tick, once the log line naming what it's waiting on stops applying.
+
+This is a **label**, not this repo's own GitHub Projects v2 "Priority" field (if your board has one — Urgent/High/Medium/Low, say). `spf watch` never reads or writes Projects v2: no GraphQL, no `project` token scope, no Jira equivalent. If you use both, they're independent — nothing reconciles them, and `spf watch` obeys only the label. Keep them aligned yourself, or don't use the board field for this repo's issues.
+
 ### Refining specs (`watch.refine`)
 
 A product spec isn't individually workable — it needs to become a feature,
 broken down into user stories and bugs, before the build lane above has
 anything to claim. `watch.refine` is a second lane over the same poll loop
 that does exactly that: it polls `<prefix>:spec-ready`, runs a decomposition
-chain (`refine` by default) against the spec in its own worktree, and
-publishes what it produces as real tracker issues — a feature/epic container
-plus story/bug/task leaves, linked via GitHub's native sub-issue hierarchy.
+chain (`refine` by default — `request → scout → refiner → publish`) against
+the spec in its own worktree, and publishes what it produces as real tracker
+issues — a feature/epic container plus story/bug/task leaves, linked into a
+real hierarchy: GitHub's native sub-issues API, or Jira's `parent` field.
 
 ```yaml
 watch:
-  issue_provider: github    # required — issue authoring isn't implemented for Jira yet
+  issue_provider: github    # or jira — both implement issue authoring
   repo: owner/name
   refine:
     enabled: true
@@ -397,31 +410,151 @@ watch:
     concurrency: 1          # this lane's own budget, independent of watch.concurrency
 ```
 
+On Jira, every `RefinedIssue.kind` (`epic`/`feature`/`story`/`bug`/`task`) maps
+to a real Jira issue type through `watch.jira.issue_types` — defaults
+`epic`/`feature` → `Epic`, `story` → `Story`, `bug` → `Bug`, `task` → `Task`,
+overridable per kind since real projects rename or customize these:
+
+```yaml
+watch:
+  issue_provider: jira
+  jira:
+    base_url: https://your-domain.atlassian.net
+    project_key: PROJ
+    issue_types:        # optional — shown are the defaults
+      epic: Epic
+      feature: Epic
+      story: Story
+      bug: Bug
+      task: Task
+  refine:
+    enabled: true
+```
+
+Hierarchy uses Jira's modern `parent` field only (no legacy "Epic Link"
+custom-field support) — this works on team-managed projects and on
+company-managed projects with Jira's current issue-hierarchy setting; a
+project not configured for it surfaces Jira's own API error, unmodified.
+One accepted platform limitation: Jira doesn't support Epic-under-Epic
+nesting the way GitHub's sub-issues API supports up to 8 levels, so a
+`feature` node parented under another `epic`/`feature` (both `Epic` by
+default) will fail at publish time on Jira specifically — a real platform
+difference, not a bug. Both `spf watch init` and `spf watch`'s own startup
+check validate `watch.jira.issue_types` against the real project before
+anything unattended runs — see "Jira" below.
+
 Every generated issue carries a `<prefix>:type:epic|feature|story|bug|task`
-label. A container (a feature/epic — something else names it as `parent`)
-gets only that label; a leaf additionally gets `<prefix>:refined` — **never**
-`<prefix>:ready`. Promoting a leaf to `<prefix>:ready` is a deliberate human
-decision: the refine lane never auto-promotes anything, so a spec fanning out
-into twenty stories doesn't turn into twenty unattended chain runs and twenty
-PRs with nobody having looked at the breakdown first. Once you do promote a
-leaf, the existing build lane picks it up completely unchanged.
-
-The spec issue itself gets a `spec-ready → refining → done`/`blocked`
-lifecycle, same shape as the build lane, and a summary comment listing every
-issue it created. Try it by hand first, against a real spec, before turning
-on the daemon:
+label AND a `<prefix>:priority:p0|p1|p2|p3` label (see "Priority, dependencies,
+and picking what's next" above) — the refiner proposes the priority, a human
+can relabel it before promoting. A container (a feature/epic — something
+else names it as `parent`) gets only those two labels; a leaf additionally
+gets `<prefix>:refined` — **never** `<prefix>:ready`. Promoting a leaf to
+`<prefix>:ready` is a deliberate human decision: the refine lane never
+auto-promotes anything, so a spec fanning out into twenty stories doesn't
+turn into twenty unattended chain runs and twenty PRs with nobody having
+looked at the breakdown first. Once you do promote a leaf, the existing build
+lane picks it up completely unchanged — including the frontier check: a
+promoted leaf isn't claimed until every issue named in its `blocked_by` is
+`<prefix>:done`.
+
+A spec issue's own `<prefix>:priority:pN` label, if it has one, reaches the
+refiner as a **ceiling**: no generated node may be more urgent than the spec
+itself (enforced regardless of what the refiner emits — see
+`core/refine.ts`'s `publish()`). `spf refine ... --priority p1` sets the same
+ceiling for a bare manual run with no spec issue to read a label from.
+
+Grounding the decomposition in real code is structural, not just prose: a
+`scout` phase maps the subsystems the spec touches before the refiner ever
+runs, and its findings flow straight into the refiner as context. This makes
+`scout` a required agent for the `refine` chain — a roster that pruned it
+fails `spf watch` startup by name, the same as any other missing required
+agent.
+
+#### Human-in-the-loop escalation
+
+The refiner is instructed not to guess on anything material (scope, data
+model, an external dependency choice, a UX contract, a breaking change, or
+anything that would contradict an existing ADR — see
+`assets/prompts/refiner/system.md`'s "Ask, don't decide"). When it hits real
+ambiguity it raises questions instead of publishing a partial tree, and the
+spec moves through an extra loop before it's even fully published:
+
+```text
+spec-ready → refining ──┬─→ spec-in-progress → done / blocked   (published a tree, THEN tracked to completion)
+                         └─→ needs-feedback                      (raised questions)
+                                  │  a human answers in the issue's comments,
+                                  │  then adds continue-refinement
+                                  ▼
+                            refining (again, same adw_id) → ...
+```
+
+Answer the refiner's questions as comments on the spec issue, then add the
+`<prefix>:continue-refinement` label. `spf watch` resumes the **same**
+`adw_id` — the refiner's own coding-agent session continues, with the
+comment thread folded into its prompt — so it never re-derives context it
+already had, and it can loop through as many rounds as it takes; there's no
+cap. If channels are configured (see "Notifications" below), a
+`spec_needs_feedback` event fires every round.
+
+**Publishing a tree does not mean the spec is done.** A product manager
+watching a spec's status needs "done" to mean the work is actually finished,
+not merely that a decomposition happened — so once the refiner publishes,
+the spec moves to `<prefix>:spec-in-progress`, not `<prefix>:done`. It stays
+there — with a summary comment listing every issue it created, noting how
+many rounds of feedback it took, if any — until **every one of those
+issues** reaches `<prefix>:done` (a leaf that lands, or a feature/epic
+container once `rollUp` has already finished it — see "Container roll-up"
+below). Only then does `spf watch` transition the spec to `<prefix>:done`,
+post a closing comment, and close it on the tracker where the tracker
+supports closing at all — GitHub does (best-effort: a failed close never
+turns completed work back into `blocked`); Jira doesn't have this wired up,
+so a Jira spec still relabels and comments correctly, just stays open. A
+`spec_done` event fires either way, distinct from the earlier
+`spec_refined`. A spec whose
+generated leaf never gets promoted, or whose work stalls `blocked`, simply
+stays `spec-in-progress` — which is the truthful state, not a bug.
+
+The spec issue's full lifecycle: `spec-ready → refining → needs-feedback ⇄
+refining → spec-in-progress → done`/`blocked` (the `needs-feedback ⇄
+refining` loop only when the refiner actually escalates). Try it by hand
+first, against a real spec, before turning on the daemon:
 
 ```bash
-spf refine "<spec text or path/to/spec.md>" --issue 42   # --issue renders a "## Parent: #42" back-reference
+spf refine "<spec text or path/to/spec.md>" --issue 42               # --issue renders a "## Parent" section, "Decomposed from #42."
+spf refine "<spec text or path/to/spec.md>" --issue 42 --priority p1 # --priority clamps every generated node to p1 or less urgent
 ```
 
-`spf watch init` seeds the type labels alongside the state ones. This lane's
-prompt (`assets/prompts/refiner/`) is adapted from a "tracer-bullet ticket"
-decomposition skill — vertical slices, a `blocked_by` dependency graph, and
-an expand/migrate/contract sequence for wide mechanical refactors — with a
-gate (`gates.refinementWellFormed`) added on top to enforce the
+#### Container roll-up
+
+A feature or epic isn't itself a unit of work, so it's never claimed and
+never opens a PR — but it isn't abandoned once its children exist, either.
+Every time a leaf's PR merges, `spf watch` checks that leaf's parent: once
+**every** child under a container carries `<prefix>:done`, the container
+gets a summary comment (every child it rolled up, by id), transitions to
+`<prefix>:done`, and closes on the tracker if the tracker supports closing
+at all (GitHub does; Jira doesn't have this wired up, so a Jira container
+still relabels and comments, just stays open) — then the same check runs on
+*its* parent, so an epic of features rolls up once its last feature does.
+A container with even one unfinished child (including one still sitting at
+`<prefix>:refined`, never promoted) is left exactly as it is; nothing times
+out or force-closes it.
+
+Roll-up needs to read back the hierarchy `publish()` created — GitHub's
+native sub-issues API, or a Jira `parent = "<id>"` JQL search — so it works
+on both providers today, same as authoring itself. A tracker that isn't
+authoring-capable at all gets a logged no-op, not a startup failure, since
+the build lane still works fine without roll-up.
+
+`spf watch init` seeds the type labels alongside the state ones — **re-run
+it** after upgrading to this version, so it can create the new
+`<prefix>:needs-feedback` and `<prefix>:continue-refinement` labels. This
+lane's prompt (`assets/prompts/refiner/`) is adapted from a "tracer-bullet
+ticket" decomposition skill — vertical slices, a `blocked_by` dependency
+graph, and an expand/migrate/contract sequence for wide mechanical refactors
+— with a gate (`gates.refinementWellFormed`) added on top to enforce the
 container/leaf shape that skill left as prose convention rather than a
-checked rule.
+checked rule, now also enforcing that a refinement never publishes issues and
+raises questions in the same round.
 
 ### GitHub (`issue_provider: github` and/or `code_host: github`)
 
@@ -451,7 +584,7 @@ export JIRA_API_TOKEN=...   # id.atlassian.com -> Security -> API tokens
 
 State is modeled as Jira **labels** (`<prefix>:ready`, etc.), mirroring GitHub exactly, rather than native workflow status transitions — the latter would need per-project transition-id mapping, since workflows vary by project/scheme; labels work identically everywhere with zero per-project setup. One caveat: colons are a legal Jira label character and JQL matches on them fine, but they won't show up in Jira's own label autocomplete UI — cosmetic only.
 
-`spf watch init` is a no-op here (Jira labels are freeform strings with no color/description registry to seed, unlike GitHub's) — it just reports the labels this run will use.
+`spf watch init` still doesn't create any labels here (Jira labels are freeform strings with no color/description registry to seed, unlike GitHub's) — it reports the labels this run will use. But with `watch.refine.enabled`, it now also validates `watch.jira.issue_types` against the real project's issue types, read-only, and exits non-zero on a mismatch — see "Refining specs" above.
 
 ### Bitbucket (`code_host: bitbucket`)
 
@@ -482,10 +615,16 @@ notifications:
 ```
 
 `events` is the whole filter: `errors` sends only failed runs/phases, blocked
-issues, and watch errors; `all` adds every milestone — run started/finished,
-issue claimed, PR opened, issue done. A channel's own `events` overrides the
-top-level scope for just that channel. `spf doctor` reports whether each
-configured channel's env var is set.
+issues, watch errors, and a spec needing feedback (`spec_needs_feedback` —
+see "Human-in-the-loop escalation" above; it's `error`-level on purpose, the
+same class of event as a blocked issue, so an `errors`-scope channel sees it
+too); `all` adds every milestone — run started/finished, issue claimed, PR
+opened, issue done, a container's roll-up (`feature_done` — see "Container
+roll-up" above), and a spec reaching actual completion (`spec_done` —
+distinct from `spec_refined`, which fires the moment a tree is published;
+see "Human-in-the-loop escalation" above). A channel's own `events`
+overrides the top-level scope for just that channel. `spf doctor` reports
+whether each configured channel's env var is set.
 
 The webhook URL is a secret and lives only in `.env` — `webhook_url_env`
 names the key, never the URL itself, matching `GITHUB_TOKEN`/

package/assets/defaults/spf.config.yaml

@@ -52,6 +52,74 @@ observability:
 #       test: [test]
 #       all: [test, lint]
 
+# OFF by default, and absence/false is a TOTAL no-op: every agent dispatches
+# at exactly the model its roster entry names, byte-identically to before
+# this key existed. Same discipline as max_run_cost/max_run_tokens
+# (data_types.ts:463-491): a repo that upgrades must not silently start
+# routing its phases to different models.
+#
+# Turning it on is a deliberate edit, or `spf init --template ts-flue-ollama`
+# (the one packaged template whose two rungs are MEASURED). `spf init`'s
+# interview does NOT write this block — see config.md's "tiering" section
+# for why.
+tiering:
+  enabled: false
+
+  # The ladder, WEAKEST FIRST. A SEQUENCE, not a mapping: order is the whole
+  # semantics here (a risk level shifts every routed role UP or DOWN this
+  # list), and a YAML sequence states order unambiguously where a mapping
+  # would make it depend on the parser preserving key order.
+  #
+  # `coding_agent` (default "flue", the same default an agent's own field
+  # uses) declares WHICH BACKEND'S VOCABULARY this rung's `model` speaks. It
+  # is not optional in spirit: a tier changes an agent's `model` and NOTHING
+  # else — `coding_agent` is a per-agent field and always stays the agent's
+  # own — so a rung can only route roles whose backend matches. See
+  # config.md's "tiering" section for rule T, and note that this is what
+  # makes "validated by the same backend branch agents.validate() uses" an
+  # answerable question: the branch is the TIER's declared backend.
+  #
+  # `model` then speaks EXACTLY the same vocabulary as an agent's own `model:`
+  # for that backend — provider/model-id for flue, Claude Code's bare alias for
+  # claude_code. There is deliberately no per-provider table: for flue the
+  # provider is already the first segment of the value.
+  #
+  # WHEN tiering.enabled, `spf doctor` runs the SAME provider-key and
+  # model-shape checks over these rungs that it already runs over
+  # cfg.agents[].model — a rung naming a provider whose key is unset is a
+  # green doctor and a first-dispatch failure otherwise. When tiering is
+  # DISABLED (which is this file's shipped state) doctor does not look at
+  # `tiers` at all, so shipping this populated ladder cannot fail `spf
+  # doctor` in a repo that never opted in.
+  tiers:
+    - { name: scout,   coding_agent: flue, model: google/gemini-3.6-flash }
+    - { name: builder, coding_agent: flue, model: fireworks/accounts/fireworks/models/kimi-k3 }
+    - { name: deep,    coding_agent: flue, model: openai/gpt-5.6-terra }
+
+  # Baseline tier per ROLE (an agent name). Naming an agent here IS the
+  # operator's statement "route this one by tier" — so the resolved tier wins
+  # over that agent's own `model:`. An agent NOT named here is never retiered:
+  # its `model:` stands, untouched. That is the whole precedence rule.
+  #
+  # A key naming an agent this repo's roster does not define is NOT a global
+  # error — it is only reported for a chain that actually requires that
+  # agent. A pruned or renamed roster must not fail every chain.
+  #
+  # NOTE for the two packaged templates that set `defaults.coding_agent:
+  # claude_code` (ts, ts-cc): this `roles` map and the flue-shaped `tiers`
+  # above survive into their effective config through key-by-key merge. That
+  # is harmless while `enabled: false`. Flip `enabled: true` there without
+  # also declaring your own ladder and validate() fails LOUDLY by name on the
+  # backend mismatch (rule T) rather than dispatching a `fireworks/...` id
+  # through Claude Code.
+  roles:
+    scout:      scout
+    documenter: scout
+    planner:    builder
+    builder:    builder
+    refiner:    builder
+    reviewer:   deep
+
 agents:
   - name: planner
     model: fireworks/accounts/fireworks/models/kimi-k3

package/assets/prompts/refiner/system.md

@@ -12,6 +12,38 @@ Decompose a product spec into a feature/story-or-bug tree of vertical slices the
 - Judge any command you run by its exit status, never by scanning its output for words. `error` or `not found` inside passing output is text, not a failure.
 - Write your working notes to `<context_handoff_dir>/refine_plan.md` before emitting your Report JSON.
 
+## Grounding: tie every slice to real code
+
+A scout has already mapped the subsystems this spec touches — its findings arrive as `previous_envelope`. Read them, then read the files they name yourself: a scout finding is a pointer, not a substitute for looking. Before writing a single slice, be able to name the concrete modules, functions, or types each slice will touch. Record what you read and what you concluded in `refine_plan.md`.
+
+A slice you cannot tie to code that actually exists is not a slice — it is a guess wearing a slice's shape. Turn it into a question instead (see below).
+
+## Ask, don't decide
+
+You will hit real ambiguity: places where the spec (or the codebase, or both) genuinely supports more than one answer, and picking wrong wastes real engineering time on the wrong tree. Escalate those to a human rather than deciding for them. You MUST escalate, rather than guess, anything touching:
+
+- **Scope boundaries** — is X in or out of this decomposition.
+- **Data model or schema shape** — a new field, table, or type whose shape isn't implied by what already exists.
+- **Choice of external service or dependency** — which library, API, or vendor.
+- **Auth or permission semantics** — who can do what.
+- **User-facing contract or UX behavior** — what the feature actually does from the outside, when the spec doesn't pin it down.
+- **Breaking changes and migration strategy** — whether existing behavior/data changes shape, and how the transition is sequenced.
+- **Non-functional targets** — performance, scale, availability numbers the spec doesn't state.
+- **Anything that would contradict an existing ADR.**
+
+You MAY decide these yourself, following whatever pattern the codebase already uses — that's ordinary judgment, not ambiguity: naming, file placement, test framework and layout, internal module structure, and the ordering of independent slices (defer to the `priority` you assign each one — see "Priority" below — rather than an arbitrary reading order).
+
+When you escalate, ask **everything you need in one batch** — don't trickle questions across rounds when you could have asked them all up front. Emit **no `issues`** in a round where you're asking questions; the two are mutually exclusive and a gate enforces it. For each question, give a human enough to answer in a word or two:
+
+- `why_it_matters` — what goes wrong if this gets guessed instead of decided.
+- `options` — the plausible answers you found, if there's a short list.
+- `recommendation` — your own best guess, so "go with your recommendation" is a valid answer.
+- `evidence` — the files/symbols that framed the question.
+
+## Resuming after a human answers
+
+A resumed run's prompt includes the issue's comment thread, split into "answers to your open questions" and "earlier discussion." Treat the answers as **authoritative** — never re-ask a question that's been answered. If an answer is itself ambiguous or incomplete, ask one narrower follow-up rather than repeating the original question.
+
 ## The tree
 
 Every node you produce is either a **container** (`epic` or `feature` — exists only to group other nodes; never itself a unit of work) or a **leaf** (`story`, `bug`, or `task` — the independently workable unit). A node is a container exactly when some other node names it as `parent`; everything else is a leaf. At least one leaf is required — a decomposition that is all containers has produced nothing to build.
@@ -29,6 +61,16 @@ Emit a **flat list**, not nested JSON: each node names its `parent` by another n
 
 Give every node its `blocked_by`: the other nodes' `key`s that must land first. A node with no blockers can start immediately — leave `blocked_by` empty rather than inventing an order where none is required. The factory works the **frontier**: any leaf whose blockers are all done. For a purely linear chain that means top to bottom; for anything wider, only real dependencies belong in `blocked_by` — an artificial one just stalls the frontier.
 
+## Priority
+
+Give every node a `priority`: `p0` (drop everything — a broken promise to users, or blocking everything else), `p1` (the spec's core value — the slices without which it isn't shipped), `p2` (the default — real scope, can wait a cycle), or `p3` (worth writing down, not worth scheduling yet). This is independent of `blocked_by` — a `p0` slice still waits for its blockers, same as anything else; priority decides scheduling ORDER among leaves that are otherwise both ready to start, not which one is allowed to start.
+
+Three rules, all enforced, not just suggested:
+
+- **A container takes the urgency of its most urgent child.** Don't set a feature's priority independently of the stories under it — pick the highest urgency among its children.
+- **No node may be more urgent than its parent.** A `p0` story under a `p3` feature is a decomposition mistake, not a valid tree — a gate rejects it.
+- **When the prompt states the spec's own priority, it is a CEILING for every node you produce — never a floor.** Deviate downward freely (a `p1` spec can still have `p3` polish tucked inside it); nothing you produce may be more urgent than the spec itself. This is enforced by the harness at publish time regardless of what you emit, so state the priority you actually mean — a violation is silently clamped, not sent back as a correction.
+
 ## Wide refactors — the one exception to vertical slicing
 
 A **wide refactor** is one mechanical change (rename a column, retype a shared symbol) whose blast radius fans across the codebase, so a single edit breaks thousands of call sites and no vertical slice can land green on its own. Sequence it as **expand -> migrate -> contract**, each stage its own leaf(s):
@@ -45,9 +87,3 @@ If even a batch can't stay green alone, keep the same three-stage sequence but l
 - Avoid specific file paths or code snippets; they go stale fast. Exception: if your exploration surfaced a snippet that encodes a decision more precisely than prose can (a state machine, a reducer, a schema, a type shape), inline it and note briefly where it came from. Trim to the decision-rich part, not a working demo.
 - Do **not** write a "Blocked by" or "Parent" section into `body` yourself — the harness renders both from `blocked_by`/the source issue automatically, with real issue numbers once everything is created. Writing your own would go stale or duplicate the real one.
 - `body` should read as `## What to build` followed by `## Acceptance criteria` (a checklist).
-
-## Subagents
-
-`subagent_create` / `_continue` / `_list` / `_remove` fan out exploration — one per subsystem or open question — when the spec spans more than you can read cheaply. Give each a self-contained task, hold it to read-only work, and omit `model`.
-
-They run in the background. **Wait for every one you spawned to report before writing `refine_plan.md` or your Report JSON.** Skip them when a few reads would do.

package/assets/prompts/refiner/user.md

@@ -6,25 +6,34 @@
 
 {{prompt}}
 
+`prompt` may include a `## Discussion on the spec issue` section — the spec issue's own comment thread, if it has one. On a first pass this is whatever discussion already existed before the spec was labeled ready; on a resumed pass (after you raised questions and a human answered) it's split into "Answers to your open questions (round N)" and "Earlier discussion." Treat the answers section as authoritative — see your system instructions on resuming.
+
+`prompt` may also include a `## Priority` section, when the spec issue itself carries a priority label. Treat that as a **ceiling** for every node you produce — see your system instructions on priority. Its absence means no ceiling, not "assume p2."
+
 ### previous_envelope
 
 {{previous_envelope}}
 
+A scout's findings — the subsystems this spec touches, one entry per file with a note on what's there. Read them, then read the files yourself; a scout finding is a pointer, not a substitute for grounding your own decomposition in the actual code.
+
 ### context_handoff_dir
 
 {{context_handoff_dir}}
 
 ## Task
 
-Decompose the product spec in `prompt` into a feature/story-or-bug tree, following every rule in your system instructions (vertical slices, the `blocked_by` DAG, expand/migrate/contract for wide refactors, no "Blocked by"/"Parent" text of your own).
+Decompose the product spec in `prompt` into a feature/story-or-bug tree, following every rule in your system instructions (grounding, ask-don't-decide, vertical slices, the `blocked_by` DAG, expand/migrate/contract for wide refactors, no "Blocked by"/"Parent" text of your own).
 
-1. Explore the codebase only as far as you need to ground the decomposition in what actually exists.
-2. Write your working notes to `<context_handoff_dir>/refine_plan.md`.
-3. Emit your `Report` JSON, declaring that one file in `artifacts`.
+1. Read the scout's findings in `previous_envelope`, then explore the codebase yourself as far as you need to ground the decomposition in what actually exists.
+2. Decide whether you can decompose the whole spec now, or whether something in it is genuinely ambiguous (see "Ask, don't decide"). These are mutually exclusive outcomes for this round — see the two Report shapes below.
+3. Write your working notes to `<context_handoff_dir>/refine_plan.md`.
+4. Emit your `Report` JSON, declaring that one file in `artifacts`.
 
 ## Report
 
-Respond with ONLY valid JSON matching `RefineOutput` — no prose before or after:
+Respond with ONLY valid JSON matching `RefineOutput` — no prose before or after. Exactly one of `issues` / `questions` is non-empty; the gate rejects a Report that populates both.
+
+**Shape 1 — the decomposition is unambiguous: emit `issues`, leave `questions` empty.**
 
 ```json
 {
@@ -39,7 +48,8 @@ Respond with ONLY valid JSON matching `RefineOutput` — no prose before or afte
       "title": "<feature title>",
       "body": "## What to build\n\n<end-to-end behavior this feature covers>\n\n## Acceptance criteria\n\n- [ ] <criterion>",
       "parent": "",
-      "blocked_by": []
+      "blocked_by": [],
+      "priority": "p1"
     },
     {
       "key": "S1",
@@ -47,7 +57,8 @@ Respond with ONLY valid JSON matching `RefineOutput` — no prose before or afte
       "title": "<leaf title>",
       "body": "## What to build\n\n<end-to-end behavior from the user's perspective>\n\n## Acceptance criteria\n\n- [ ] <criterion>\n- [ ] <criterion>",
       "parent": "F1",
-      "blocked_by": []
+      "blocked_by": [],
+      "priority": "p1"
     },
     {
       "key": "S2",
@@ -55,7 +66,31 @@ Respond with ONLY valid JSON matching `RefineOutput` — no prose before or afte
       "title": "<leaf title>",
       "body": "## What to build\n\n<the fix, described end-to-end>\n\n## Acceptance criteria\n\n- [ ] <criterion>",
       "parent": "F1",
-      "blocked_by": ["S1"]
+      "blocked_by": ["S1"],
+      "priority": "p2"
+    }
+  ],
+  "questions": []
+}
+```
+
+**Shape 2 — something material is ambiguous: emit `questions`, leave `issues` empty.**
+
+```json
+{
+  "status": "success",
+  "summary": "<one sentence: how many questions, and what they're about>",
+  "artifacts": ["<context_handoff_dir>/refine_plan.md"],
+  "notes_for_next_agent": "<anything a human answering these should know>",
+  "issues": [],
+  "questions": [
+    {
+      "id": "Q1",
+      "question": "<the question, precise enough to answer in a word or two>",
+      "why_it_matters": "<what goes wrong if this is guessed instead of decided>",
+      "options": ["<plausible answer>", "<another plausible answer>"],
+      "recommendation": "<your own best guess, if you have one>",
+      "evidence": ["<file or symbol that framed this question>"]
     }
   ]
 }
@@ -63,8 +98,11 @@ Respond with ONLY valid JSON matching `RefineOutput` — no prose before or afte
 
 Rules on the shape (enforced by a gate — a violation sends this back to you as a correction, not a silent acceptance):
 
+- `issues` and `questions` are mutually exclusive: a non-empty `questions` requires an empty `issues`, and vice versa. Escalating means publishing nothing this round.
 - `key` is your own local id for this run, unique within `issues` — never a real tracker id.
 - A node is a **container** (`kind: "epic"` or `"feature"`) exactly when some other node names it in `parent`; every other node is a **leaf** (`kind: "story"`, `"bug"`, or `"task"`) and must not be a container. At least one leaf is required.
 - `parent` is another node's `key`, or `""` for a top-level feature/epic.
 - `blocked_by` is a list of other nodes' `key`s — real dependencies only, and no cycles (through `parent` or `blocked_by`, or both together).
 - `body` is `## What to build` then `## Acceptance criteria` only — no "Blocked by" or "Parent" section; those are rendered for you once every node has a real issue number.
+- `priority` is one of `p0`|`p1`|`p2`|`p3`, defaulting to `p2` if you omit it. No node may be more urgent than its parent, and no node may exceed the spec's priority where the `## Priority` section states one — a violation is clamped, not sent back as a correction, so state the priority you actually mean.
+- `questions[].id` is your own local id for this round, unique within `questions` — stable enough that, on a resumed run, an answer in the thread can be matched back to the question it answers.

package/assets/skill/SKILL.md

@@ -46,6 +46,7 @@ phases`/`spf events` exist so nobody has to guess the schema again).
 | "add a chain / a phase / an output type / a gate" | `authoring_chains.md` |
 | "what is SPF" | `spf_overview.md` |
 | "fold a third-party review tool's findings into the reviewer" | `cookbooks/ocr_reviewer.md` |
+| "try N attempts and pick the best one / best-of-N" | `spf fanout` — see `references/config.md`'s `spf fanout` section |
 | envelope/gate/session contract | `references/handoff.md` |
 | trace schema, spend vs. context | `references/observability.md` |
 | config field reference | `references/config.md` |