@gr8ful/spf 0.6.0 → 0.8.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,6 +377,18 @@ 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,
@@ -385,12 +397,12 @@ 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 — `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 via
-GitHub's native sub-issue hierarchy.
+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
@@ -398,14 +410,58 @@ 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.
+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
@@ -421,11 +477,11 @@ 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 reaches `done`:
+spec moves through an extra loop before it's even fully published:
 
 ```text
-spec-ready → refining ──┬─→ done / blocked            (published a tree)
-                         └─→ needs-feedback            (raised questions)
+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
                                   ▼
@@ -440,19 +496,55 @@ 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.
 
-The spec issue itself moves through a `spec-ready → refining →
-needs-feedback ⇄ refining → done`/`blocked` lifecycle (the `needs-feedback ⇄
-refining` loop only when the refiner actually escalates), and a summary
-comment lists every issue it created — noting how many rounds of feedback it
-took, if any. Once a spec reaches `done`, `spf watch` also closes the issue
-on the tracker (best-effort: a tracker or a failed close never turns a
-successfully refined spec back to `blocked`). Try it by hand first, against
-a real spec, before turning on the daemon:
+**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
 ```
 
+#### 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
@@ -492,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`)
 
@@ -527,9 +619,12 @@ 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 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.
+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/prompts/refiner/system.md

@@ -31,7 +31,7 @@ You will hit real ambiguity: places where the spec (or the codebase, or both) ge
 - **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.
+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:
 
@@ -61,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):

package/assets/prompts/refiner/user.md

@@ -8,6 +8,8 @@
 
 `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}}
@@ -46,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",
@@ -54,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",
@@ -62,7 +66,8 @@ 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": []
@@ -99,4 +104,5 @@ Rules on the shape (enforced by a gate — a violation sends this back to you as
 - `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/references/config.md

@@ -155,7 +155,8 @@ Full mechanism: the main README's "`spf watch`" section. Field reference:
 | `concurrency` | int ≥1 | Max issues claimed and run at once, the build lane's own budget (independent of `refine.concurrency`). Default `2`. |
 | `chain_options` | map of string -> string | Options passed straight through to `chain` (and `refine.chain`) for every unattended dispatch — the same shape an interactive `spf <chain> --suite <name>` builds, e.g. `{suite: strict}` or `{agent: some-agent}`. Default `{}`. Only useful for a chain whose behavior actually reads the option (a step-derived chain's `--suite`; an imperative chain ignores an option it doesn't know about). |
 | `jira.base_url` / `jira.project_key` | string | Only consulted when `issue_provider: jira`. |
-| `refine.enabled` | bool | Turns on the second lane: decompose a `<prefix>:spec-ready` product spec into a feature/story-or-bug tree of real issues, instead of running `chain` against it directly (a spec isn't individually workable). Default `false` — off by default, so an existing `watch:` config is unaffected by upgrading. Needs `issue_provider: github` — `spf watch` fails loudly at startup otherwise, since issue authoring (create + link a hierarchy) isn't implemented for Jira yet. |
+| `jira.issue_types` | map: `epic`/`feature`/`story`/`bug`/`task` -> string | Only consulted when `issue_provider: jira` AND `refine.enabled`. What each `RefinedIssue.kind` creates as on Jira — defaults `epic`/`feature` → `Epic`, `story` → `Story`, `bug` → `Bug`, `task` → `Task`, overridable per kind. Validated against the real project by both `spf watch init` and `spf watch`'s own startup check. |
+| `refine.enabled` | bool | Turns on the second lane: decompose a `<prefix>:spec-ready` product spec into a feature/story-or-bug tree of real issues, instead of running `chain` against it directly (a spec isn't individually workable). Default `false` — off by default, so an existing `watch:` config is unaffected by upgrading. Needs `issue_provider: github` or `"jira"` — both implement issue authoring (create + link a hierarchy); any other value fails loudly at startup. |
 | `refine.chain` | string | Which registered chain runs per claimed spec. Default `refine`. |
 | `refine.concurrency` | int ≥1 | The refine lane's own budget, separate from `concurrency`. Default `1`. |
 
@@ -180,23 +181,60 @@ additionally gets `<prefix>:refined`, so a human can review and promote it to
 `<prefix>:ready` when it's worth building — the refine lane never
 auto-promotes anything.
 
+A third label vocabulary — `<prefix>:priority:p0|p1|p2|p3` — is what
+`claimNewWork` actually schedules `<prefix>:ready` issues by: priority first,
+then sibling affinity (a leaf whose parent already has a sibling in flight
+goes first), then creation order. The refiner proposes a priority per node
+(clamped to the spec's own priority, when the spec issue has one, as a
+ceiling — never a floor); a human can relabel before promoting, which is the
+entire override mechanism. Independently, a `<prefix>:ready` leaf whose
+`blocked_by` isn't fully `<prefix>:done` is skipped until it is — the
+frontier check. This label is separate from any GitHub Projects v2
+"Priority" field a repo's board might have; `spf watch` never touches
+Projects v2, so the two are unreconciled if you use both.
+
 The `refine` chain grounds its decomposition with a `scout` phase before the
 refiner runs, so `scout` is a required agent for it — a roster that pruned
 it fails `spf watch` startup by name.
 
 The refine lane's own state machine has an extra loop beyond
-`spec-ready → refining → done`/`blocked`: when the refiner raises material
-ambiguity instead of a tree (see `assets/prompts/refiner/system.md`'s "Ask,
-don't decide"), the spec moves to `<prefix>:needs-feedback` with a comment
-naming its questions, instead of publishing anything. A human answers in the
-issue's comments and adds `<prefix>:continue-refinement`; `spf watch` claims
-that label back into `refining` and resumes the **same** `adw_id` — the
-comment thread (split into "answers to your open questions" and "earlier
-discussion") is folded into the resumed prompt, and the refiner's own
-coding-agent session continues rather than starting cold. This can loop any
-number of rounds. `spf watch init` must be re-run after upgrading to this
-version to seed the two new labels. Once a spec is fully published it's also
-closed on the tracker (GitHub only, best-effort), not just labeled `done`.
+`spec-ready → refining → spec-in-progress → done`/`blocked`: when the
+refiner raises material ambiguity instead of a tree (see
+`assets/prompts/refiner/system.md`'s "Ask, don't decide"), the spec moves to
+`<prefix>:needs-feedback` with a comment naming its questions, instead of
+publishing anything. A human answers in the issue's comments and adds
+`<prefix>:continue-refinement`; `spf watch` claims that label back into
+`refining` and resumes the **same** `adw_id` — the comment thread (split
+into "answers to your open questions" and "earlier discussion") is folded
+into the resumed prompt, and the refiner's own coding-agent session
+continues rather than starting cold. This can loop any number of rounds.
+
+Publishing a tree does NOT mean the spec is done: `<prefix>:spec-in-progress`
+is where a spec lands right after publish, and it stays there — with a
+summary comment listing every issue created — until **every one of those
+issues** is itself `<prefix>:done` (`finishTrackedSpecs`, polled every tick,
+reads `WatchMarker.refined` back to check). Only then does it move to
+`<prefix>:done`, get a closing comment, and close on the tracker (GitHub
+only, best-effort) — firing `spec_done`, distinct from the earlier
+`spec_refined`. This exists so a spec's tracker status means what a product
+manager expects it to mean: "done" is the work being finished, not merely
+having been decomposed. `spf watch init` must be re-run after upgrading to
+this version to seed the new labels.
+
+Container roll-up mirrors that same "close, don't just label" behavior for a
+generated feature/epic: once every child under it carries `<prefix>:done`
+(checked reactively, each time a leaf's PR merges), the container gets a
+summary comment and transitions to `<prefix>:done` — then the check repeats
+on ITS OWN parent, so an epic rolls up once its last feature does. A
+container with one unfinished child (including a leaf still sitting at
+`<prefix>:refined`, never promoted) is left alone; nothing forces it. This
+needs a native hierarchy read-back — GitHub's sub-issues API, or a Jira
+`parent = "<id>"` JQL search — so it works on both today; a tracker that
+implements neither gets a logged no-op, not a startup failure, since the
+build lane still works fine without roll-up. Whether the container actually
+CLOSES on the tracker (not just relabels) depends on `closeIssue` being
+implemented at all — GitHub yes, Jira no (its own resolution workflow isn't
+wired up), same asymmetry as leaf and spec completion already have on Jira.
 
 ### `notifications`
 

package/assets/templates/ts.spf.config.yaml

@@ -77,8 +77,12 @@ agents:
 #   #   suite: strict
 #   # Optional second lane: decompose a spf:spec-ready product spec into a
 #   # feature/story-or-bug tree of real issues instead of building it
-#   # directly. Off by default; needs issue_provider: github (the default
-#   # above) — issue authoring isn't implemented for Jira yet.
+#   # directly. Off by default; needs issue_provider: github OR jira — both
+#   # support issue authoring (create + link a hierarchy). On Jira, each
+#   # RefinedIssue.kind maps to a real Jira issue type via
+#   # watch.jira.issue_types (defaults: epic/feature -> Epic, story -> Story,
+#   # bug -> Bug, task -> Task) — spf watch init validates this against the
+#   # real project when refine is enabled.
 #   refine:
 #     enabled: true
 #     chain: refine

package/dist/chains/context.d.ts

@@ -1,3 +1,4 @@
+import type { RunObserver } from "../core/console.ts";
 /**
  * What every chain's `main()` receives. The CLI (or, later, the chain
  * registry) resolves every path here — a chain never has its own opinion
@@ -57,4 +58,29 @@ export interface ChainContext {
      * edited by the time anyone reads the run back).
      */
     chain_source?: string;
+    /**
+     * A live TTY view's hook into this run's `Console` — see `RunObserver`'s
+     * doc comment (`core/console.ts`). Optional and omitted by every
+     * construction site except an interactive `cli/commands/run.ts`
+     * dispatch: `spf watch`'s per-issue runs, `spf fanout`'s per-attempt
+     * runs, the `refine` chain, and every test all continue to build a
+     * plain, unobserved `Console` exactly as before this field existed.
+     */
+    render_hooks?: {
+        sink?: (line: string) => void;
+        observer?: RunObserver | null;
+        /**
+         * The live dashboard's own handoff pair — call `pause()` before a
+         * chain shows its own competing prompt (today, only `simple_sdlc.ts`'s
+         * human sign-off gate) and `resume()` once it's done, symmetrically,
+         * in a `finally`. Ink refuses a second `render()` on the same stdout
+         * while a prior instance is still live, so this isn't optional
+         * politeness — skipping `pause()` before mounting another Ink surface
+         * (or even a plain `readline` prompt sharing the same stdin/stdout,
+         * given the dashboard's own live-updating timer keeps writing to it)
+         * corrupts both.
+         */
+        pause?: () => void | Promise<void>;
+        resume?: () => void;
+    };
 }

package/dist/chains/simple_sdlc.js

@@ -217,6 +217,13 @@ export async function main(ctx) {
         const canPrompt = isInteractive() && !ctx.unattended; // amendment: never infer this from TTY state alone
         identity = committerIdentity(run.repo_root);
         const asker = canPrompt ? createAsker() : null;
+        // A live run dashboard (cli/ui/run_dashboard.tsx) keeps writing to the
+        // same stdout/stdin on its own timer even though it never reads input
+        // itself — that alone is enough to corrupt this prompt's rendering if
+        // both are live at once. `pause()`/`resume()` are no-ops when no
+        // dashboard is mounted (every non-interactive dispatch, and any test).
+        if (canPrompt)
+            await ctx.render_hooks?.pause?.();
         try {
             const outcome = await run.phase(makePhaseParams({
                 name: "signoff",
@@ -238,6 +245,8 @@ export async function main(ctx) {
         }
         finally {
             asker?.close();
+            if (canPrompt)
+                ctx.render_hooks?.resume?.();
         }
     }
     if (verified) {

package/dist/chains/steps.d.ts

@@ -316,33 +316,6 @@ export declare function refine(opts?: {
     retries?: number;
     extraGates?: string[];
 }): Step;
-/**
- * Create the tree `refine()` produced on the tracker, in dependency order,
- * and link each node to its parent. A `code` phase, not an agent one — the
- * decision-making (topological order, label assignment, `## Blocked by`
- * rendering) is `core/refine.ts`'s job; this step is sequencing only, per
- * SKILL.md's "chains stay thin" rule. Requires a preceding refine() step.
- *
- * When the refiner raised material ambiguity instead of a tree
- * (`envelope.questions` non-empty — `gates.refinementWellFormed` already
- * guarantees `issues` is empty whenever that's true), this publishes
- * nothing: it writes those questions to
- * `<context_handoff_dir>/refine_questions.json` instead of
- * `refine_publish.json` and returns. That is a successful phase outcome, not
- * a failure — escalating to a human is a legitimate way for this chain to
- * end, same as publishing a tree is.
- *
- * Writes what it created (or asked) to `<context_handoff_dir>/`, one of
- * `refine_publish.json` or `refine_questions.json` — the side channel
- * `cli/commands/watch.ts`'s `runRefine` reads after the chain returns, since
- * a chain's own return value is just an exit code. `spf watch`'s own
- * marker/comment/transition bookkeeping for the spec issue (including
- * posting the questions and moving it to `needs-feedback`) lives entirely in
- * `core/watch.ts`'s `runSpec`/`escalateSpec`, never here — a bare `spf
- * refine` run (no daemon, no spec issue in play) still needs this step to
- * work standalone, and just leaves the questions on disk for a human to
- * read.
- */
 export declare function publishIssues(opts?: {
     description?: string;
 }): Step;

package/dist/chains/steps.js

@@ -73,7 +73,7 @@ function makeStep(fn, meta = {}) {
 export async function startRun(ctx, requiredAgents, requiredSuites) {
     const cfg = agentsCfg.loadConfig(ctx.config_paths);
     agentsCfg.validate(cfg, requiredAgents, requiredSuites, ctx.cwd);
-    const run = session.ensure(cfg, ctx.adw_id, ctx.cwd, ctx.chain_name);
+    const run = session.ensure(cfg, ctx.adw_id, ctx.cwd, ctx.chain_name, ctx.render_hooks);
     // Provenance, once per run, before any phase opens: a repo-local chain
     // (.spf/chains/*.yaml) records the file it came from. `chain_name` alone
     // stops being enough to reconstruct a run the moment a target repo can
@@ -706,6 +706,23 @@ export function refine(opts = {}) {
  * work standalone, and just leaves the questions on disk for a human to
  * read.
  */
+/**
+ * `state.options["priority"]` -> a `RefinedPriority` ceiling, or `null` when
+ * unset — the generic chain-options path (`cli/commands/run.ts`'s
+ * `--priority`, or `core/watch.ts`'s `runSpec` threading a spec's own
+ * `<prefix>:priority:pN` label) is the ONLY place this string enters the
+ * system, so it's validated here rather than trusted: a typo'd or stale
+ * `--priority urgent` fails the phase with a clear message instead of
+ * silently publishing every node at its own, un-clamped priority.
+ */
+function parsePriorityOption(raw) {
+    if (raw === undefined)
+        return null;
+    if (raw !== "p0" && raw !== "p1" && raw !== "p2" && raw !== "p3") {
+        throw new Error(`publishIssues(): --priority ${JSON.stringify(raw)} is not one of p0|p1|p2|p3`);
+    }
+    return raw;
+}
 export function publishIssues(opts = {}) {
     preflightDescription("publish", opts.description);
     const fn = async (run, state) => {
@@ -714,6 +731,7 @@ export function publishIssues(opts = {}) {
             throw new Error("publishIssues() requires a preceding refine() step in the chain's step list");
         }
         const questions = envelope.questions ?? [];
+        const priorityCeiling = parsePriorityOption(state.options["priority"]);
         await run.phase(makePhaseParams({
             name: "publish",
             kind: "code",
@@ -729,9 +747,10 @@ export function publishIssues(opts = {}) {
             const created = await refineLib.publish(tracker, envelope.issues, {
                 labelPrefix: run.cfg.watch.label_prefix,
                 specIssueId: state.issue_id,
+                priorityCeiling,
             });
             writeFileSync(path.join(run.context_handoff_dir, "refine_publish.json"), JSON.stringify(created.map((c) => ({ id: c.issue.id, title: c.issue.title, kind: c.kind, isLeaf: c.isLeaf })), null, 2));
-            ph.log({ created: created.length, leaves: created.filter((c) => c.isLeaf).length });
+            ph.log({ created: created.length, leaves: created.filter((c) => c.isLeaf).length, priority_ceiling: priorityCeiling });
         });
     };
     return makeStep(fn, { label: "code(publish)" });

package/dist/cli/ask.d.ts

@@ -33,8 +33,21 @@ export interface Asker {
 }
 /** `stdin.isTTY` is what actually matters (the interview reads it) — `stdout.isTTY` alone, this repo's only prior TTY check (`src/ui/server/serve.ts:88`), would let a piped-in `spf init` hang waiting on input that will never arrive. */
 export declare function isInteractive(): boolean;
+/**
+ * Whether `cli/ui/ink_asker.tsx`'s Ink-backed `Asker` can run instead of this
+ * file's plain readline one. Ink hard-requires raw-mode stdin — confirmed by
+ * testing: rendering an Ink app against a non-raw-mode-capable stdin throws
+ * before anything is drawn. `isInteractive()` already implies raw mode is
+ * available in every real case (a TTY stdin always exposes `setRawMode`);
+ * the extra `typeof` check is cheap insurance against whatever exotic
+ * terminal doesn't, so a caller falls back to `createAsker()` instead of
+ * crashing.
+ */
+export declare function inkAvailable(): boolean;
 /** Thrown when the user interrupts (Ctrl-C) or stdin closes (EOF) mid-interview. `initCommand` catches this and exits 130, writing nothing. */
 export declare class InterviewAborted extends Error {
     constructor();
 }
 export declare function createAsker(): Asker;
+/** Exported for `cli/ui/ink_asker.tsx`'s secret prompt, which renders the same "keep current" line and must mask it identically. */
+export declare function maskForPrompt(value: string): string;

package/dist/cli/ask.js

@@ -16,6 +16,19 @@ import { paint } from "../core/console.js";
 export function isInteractive() {
     return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY) && !process.env["CI"];
 }
+/**
+ * Whether `cli/ui/ink_asker.tsx`'s Ink-backed `Asker` can run instead of this
+ * file's plain readline one. Ink hard-requires raw-mode stdin — confirmed by
+ * testing: rendering an Ink app against a non-raw-mode-capable stdin throws
+ * before anything is drawn. `isInteractive()` already implies raw mode is
+ * available in every real case (a TTY stdin always exposes `setRawMode`);
+ * the extra `typeof` check is cheap insurance against whatever exotic
+ * terminal doesn't, so a caller falls back to `createAsker()` instead of
+ * crashing.
+ */
+export function inkAvailable() {
+    return isInteractive() && typeof process.stdin.setRawMode === "function";
+}
 /** Thrown when the user interrupts (Ctrl-C) or stdin closes (EOF) mid-interview. `initCommand` catches this and exits 130, writing nothing. */
 export class InterviewAborted extends Error {
     constructor() {
@@ -148,7 +161,8 @@ export function createAsker() {
         },
     };
 }
-function maskForPrompt(value) {
+/** Exported for `cli/ui/ink_asker.tsx`'s secret prompt, which renders the same "keep current" line and must mask it identically. */
+export function maskForPrompt(value) {
     if (value.length <= 4)
         return "•".repeat(value.length);
     return `${"•".repeat(Math.max(0, value.length - 4))}${value.slice(-4)}`;