@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

package/assets/skills/spec-init/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: spec-init
+description: Bootstrap the spec-driven-development workflow in the current project — create the specs/ lifecycle folders and .core, wire version-control so specs are tracked, verify the spec skills are installed, and add the spec workflow to CLAUDE.md and .claude/rules. Idempotent and safe to re-run. Use when setting up a new project for specs or repairing the setup, or when the user says "/spec-init", "set up specs here", "initialise the spec process".
+---
+
+# /spec-init — set up the spec-driven-development workflow
+
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
+Bootstrap (or repair) everything this project needs to run the spec lifecycle.
+**Idempotent:** detect what already exists, create only what's missing, and never
+clobber customised content. Finish with a summary of created vs already-present.
+
+> If `@skitterbyte/skitterspec` is installed, `npx @skitterbyte/skitterspec init` does
+> all of the below mechanically. This skill is the manual/repair path and is
+> useful when the package isn't available or you only need to fix part of the
+> setup.
+>
+> **Re-running on an already-set-up repo is safe.** `init` detects the existing
+> setup (via the committed `specs/.core/.skitterspec-manifest.json` of installed
+> file hashes) and, interactively, offers three paths — **Resync** (update managed
+> skills/rules to the latest but keep files you've edited), **Start again** (reset
+> the managed scaffolding fresh — never your specs or config, with a confirm), or
+> **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
+> `--reset` (reset needs `--yes`) drive the stronger actions.
+
+The system is **thirteen skills**: `spec` (feature), `spec-bug` (bug),
+`spec-hotfix` (a bug fixed on a released tag),
+`no-spec` (work that genuinely has none — off the base branch all the same),
+`spec-review`, `spec-start`,
+`spec-next`, `spec-diff` (read a spec's diff as a page),
+`spec-reviewed` (pick up a review you approved on that page), `spec-to-main`,
+`spec-complete`, `spec-cancel`, and this `spec-init`. The lifecycle is `backlog → in-progress → complete / cancelled`,
+with `.core` holding always-apply project rules.
+
+## 0. Workspace mode (only when adopting isolation)
+
+If this project is adopting per-spec isolation, ask which `mode` belongs in
+`specs/.core/env.config.json` — `worktree` (default; a checkout per spec, several
+at once, one terminal session each) or `checkout` (the branch is built in the
+checkout you are already in; one spec at a time, no hand-off). It is a question
+about how the operator works, not about what the repo contains, so ask rather
+than infer it from whether dev servers or Docker are configured.
+
+## 0b. Release gating (optional, and separate)
+
+Ask whether specs should record a **release-gating** decision — does this change
+ship behind a feature flag, or land live? Adopting it copies
+`specs/.core/gating.config.json.example` → `gating.config.json` and sets
+`guidance` to wherever this project documents its flags.
+
+It is **orthogonal to isolation**: a project can adopt either, both, or neither.
+Skitterspec never learns how the flags work — it asks the question, cites that
+path, and records the answer on each spec. Leave it off and nothing appears:
+no question, no header, no check. Off is a perfectly good answer for a project
+that does not use flags.
+
+## 1. Folders
+
+Create any that are missing; drop a `.gitkeep` into ones that would otherwise be
+empty so git keeps them:
+
+- `specs/.core/` — project rules (always apply; never moved)
+- `specs/backlog/` `specs/in-progress/` `specs/complete/` `specs/cancelled/`
+
+## 2. Version control — keep specs tracked
+
+The whole lifecycle lives in git — **everything under `specs/` is tracked**, so
+the default is simply *no ignore rule excluding it*. Ensure `.gitignore` has no
+`/specs/*` (or similar) entry that would hide spec folders; if one exists and the
+project wants everything tracked, remove it. Confirm with
+`git check-ignore -v specs/.core/<any-file>` — it should print nothing (tracked).
+
+- **`.core` dotfile caveat:** only relevant if a `/specs/*` ignore is
+  (re)introduced — `*` matches dotfiles, so `.core` would need an explicit
+  `!/specs/.core/` negation. With no ignore rule, it's tracked automatically.
+- If the project uses a formatter/linter ignore glob that excludes `specs/**`,
+  decide whether spec markdown should be formatted/linted and adjust accordingly.
+- If a project later wants to **stop** versioning work-in-progress specs, that's
+  a deliberate opt-out (e.g. `/specs/*` + `!/specs/.core/`) — ask first; the
+  default is track-everything.
+
+## 3. Verify the skills are installed
+
+Check each of the ten skills resolves — `.claude/skills/<name>/SKILL.md`
+(project) or `~/.claude/skills/<name>/` (global). List any missing. This skill
+scaffolds the project; it does **not** regenerate skill bodies — missing skills
+must be copied in (e.g. `npx @skitterbyte/skitterspec init`) from a global install
+or a sibling project. If most/all are global, just confirm availability.
+
+## 4. Governing rule (`.claude/rules/spec-planning.md`)
+
+Ensure it exists. If missing, create it documenting:
+
+- the lifecycle skills with their **status** and **folder** (table);
+- the **type** convention — header `> **Type:** Feature|Bug` + filename prefix
+  `feat-`/`bug-` (never `[BUG]` brackets — glob hazard);
+- the **Author** / **Developer** header fields;
+- the **State log** audit table (folder/status transitions), kept separate from
+  the **Changelog** (decisions);
+- the project's concrete typecheck/test commands, and the rule that
+  **every phase ends with creating + running tests**.
+
+Read a sibling spec skill (e.g. `spec`, `spec-next`) for the canonical shapes
+rather than inventing them. If the rule already exists, leave it unless stale.
+
+## 4a. The review-gate hook (`.claude/hooks/review-gate.cjs`)
+
+`skitterspec init` **and `skitterspec update`** install the hook script and
+register it in the project's **committed** `.claude/settings.json` as a
+`PreToolUse` hook on `Bash`. It runs one engine call per Bash tool call and
+refuses a `git commit` in a worktree whose phase is still awaiting a verdict.
+
+**Both commands, and that is not a detail.** Copying the script and registering
+it are one operation, and they were once split across two code paths — so
+`update` landed the file, reported `created:`, and wired nothing, on every
+project that upgraded. Landing the script is not installing the hook.
+
+**`.cjs`, and the extension is load-bearing.** The script lands inside the
+target project, where *that* project's `package.json` decides how node parses a
+`.js` — so CommonJS shipped as `.js` crashes in any `"type": "module"` project,
+on every Bash tool call. `.cjs` settles it at the file. A registration left over
+from the release that named `.js` is rewritten in place, keeping any wrapping
+the operator added, rather than gaining a second entry beside it.
+
+**Committed, not machine-local**, and the difference is the point: the trusted
+worktree root is one machine's absolute path, while *a phase that ended owes an
+answer* is the project's policy and should reach everyone who clones it. The
+command is written with `${CLAUDE_PROJECT_DIR}`, so it holds in worktrees too.
+
+**Say it is there, once.** A hook that blocks a commit with the operator not
+knowing a hook exists reads as a broken git, so name it in the report when it is
+newly registered — and say what turns it off (`review.required: false` in
+`env.config.json`, which the hook defers to entirely).
+
+**Never fatal, and never rewritten.** A settings file that is not parseable JSON
+is reported and left exactly as it is — it is the operator's config, and
+everything else in it would be lost. A settings file that already names this
+script, however it was wrapped, is left alone rather than gaining a second copy.
+
+## 5. CLAUDE.md
+
+Ensure a `## Spec workflow` section exists. If absent, add one with the
+skill table (`Skill | Action | Status | Folder`), the Feature/Bug type note,
+and a pointer to `.claude/rules/spec-planning.md`. Also update the `specs/` entry
+in any project-structure tree to show `.core/` + the four lifecycle folders. If
+the section exists, refresh only stale folder/skill names — don't rewrite it.
+
+## 6. Report
+
+Do **not** `git commit` unless the user asks.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — every area is in place.
+- `⚠️` — bootstrapped, with something worth knowing: a skill that could not be
+  installed, a CLAUDE.md that was left alone, a `.core` that is still ignored.
+- `❌` — it wrote some areas and failed on another. Name which, so the re-run is
+  informed; this skill is idempotent and re-running it is the fix.
+- `⏸` — not a git repo, or nothing it could safely write into.
+
+**Fields:** `Built` · `Follow-ups` · `Next`
+
+**`Built` is per area, one line each** — folders, `.gitignore` lines,
+tooling-ignore negations, skills (present/missing), rule files, CLAUDE.md
+section — as created / updated / already-present, plus the `git check-ignore`
+result for `.core`. This is the one skill whose `Built` is a list rather than a
+clause, because "what is now true of this project" is the entire answer it
+exists to give.
+
+**There is no spec to name**, so the verdict line drops that segment:
+`✅ /spec-init · every area in place`.

package/assets/skills/spec-jira-setup/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: spec-jira-setup
+description: Configure Jira sync for this repo by interview rather than by hand — asks for the site, the project and the workflow statuses, validates the answers against Jira, then writes specs/.core/jira.config.json. Safe to re-run; an existing config is reviewed, never overwritten without consent. Use when the user says "/spec-jira-setup", "set up Jira sync", "connect this repo to Jira", "configure jira.config.json", or "check my Jira setup".
+---
+
+# /spec-jira-setup — configure Jira sync by interview
+
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
+Writes `specs/.core/jira.config.json`, the file that switches one-way Jira
+sync on for this repo. You **interview**; the engine
+(`spec-sync init-config`) **validates and writes**. Keep that split: composing
+the JSON yourself is how a malformed config gets committed, and the engine
+already rejects everything the loader would later reject.
+
+The gap this closes is not "I can't remember my site URL" — it's that nothing
+ever asks which project this repo's work files into and which statuses its
+lifecycle maps to, so the config ends up describing a shape nobody confirmed.
+Ask about structure first; the values fall out of the answers.
+
+## 1. Check what already exists
+
+Read `specs/.core/jira.config.json`.
+
+- **Absent** — this is a first-time setup. Carry on.
+- **Present** — say so and default to **reviewing** it, not replacing it: run
+  the checks in steps 2 and 5 and report where the live config disagrees with
+  the site (a project key that no longer resolves, a status that was renamed).
+  That is the most useful thing a re-run can do. Only write when the user asks
+  for it, and then pass `--force`.
+
+## 2. Credentials first
+
+The interview validates its answers against Jira, so settle authentication
+before asking anything:
+
+```
+skitterspec spec-sync credentials status
+```
+
+If nothing is set, tell the user to run this **themselves**, in their own
+terminal:
+
+```
+skitterspec spec-sync credentials set
+```
+
+It prompts for **both halves** of the pair: the Atlassian account email
+(visible) and an API token (hidden), created at
+https://id.atlassian.com/manage-profile/security/api-tokens.
+
+**Do not ask the user to paste an email or token into this conversation, and do not offer to store one for them.**
+A credential pasted into a chat enters the transcript, is sent to the model,
+and may be logged — moving where it is stored is pointless if it travels
+through the conversation to get there. Your job is to confirm the setup is
+ready and name the command; the values are theirs alone.
+
+**Degrade, never block:** with no credentials and no MCP connection the answers
+cannot be validated. Say so in one line —
+*"Jira not reachable — can't validate the answers"* — point at the manual path
+(`jira.config.md`, the field reference beside the example config), and
+**stop without writing anything**. A half-written config is worse than none:
+every other command switches on the moment the file exists.
+
+## 3. Which site, and which project?
+
+- **Site URL** — `https://<site>.atlassian.net`. It also keys the
+  credentials-store entry, so it must be the same site `credentials set` was
+  given.
+- **Project key** — the identifier prefix (`PROJ` in `PROJ-123`).
+
+**This config pins exactly one project for the whole repo**, and every spec
+issue lands there **by construction** — there is no per-spec picker. Say that
+plainly, because it reframes the question: it isn't "which project do you
+like", it's *"which product's work does this repo hold"*. If the repo genuinely
+spans two projects, sync can't express that today: say so, and offer the two
+honest options — pick the project that owns most of the work, or split the
+repo's specs across two checkouts. Don't invent a workaround.
+
+## 4. Which issue types?
+
+- **`jira.issueType`** — the type a spec mints as. Default **Task**; take the
+  default unless the project files this kind of work as something else
+  (`Story`, say).
+- **`jira.subtaskType`** — the type a phase mints as. Default **Subtask**, and
+  it must be a subtask type in this project.
+
+Offer the defaults and take yes for an answer — this is a confirmation, not an
+interrogation.
+
+## 5. Check the status names
+
+```
+skitterspec spec-sync states --json
+```
+
+It prints the project's status names, exactly as Jira spells them — and
+reaching them is the setup's first real end-to-end check: a wrong site URL,
+project key or credential fails here, while the user is still in the setup
+conversation. Relay a failure with its fix rather than pressing on.
+
+Then settle the four bucket→status names against that list:
+
+- `backlog` → `To Do` · `in-progress` → `In Progress` · `complete` → `Done` by
+  default, and `cancelled` → `Done` too, because default Jira workflows carry
+  no Cancelled status.
+- **Validate every non-default answer against the `states` output** before
+  writing. A status moves by **workflow transition**: a name the project lacks
+  can never be reached, and the engine refuses loudly at push time rather than
+  path-finding — catching a renamed `Done` here is the whole reason this step
+  exists.
+- Where a configured or offered name is not in the list, show the real names
+  and ask which one means that bucket here — the mapping is the user's call,
+  never a guess.
+
+Each answer that differs from the defaults becomes a `--state <bucket>=<name>`
+flag in step 6.
+
+## 6. Write it
+
+```
+skitterspec spec-sync init-config \
+  --site-url https://<site>.atlassian.net --project-key PROJ \
+  [--issue-type Task] [--subtask-type Subtask] \
+  [--state <bucket>=<name> …] [--force] [--json]
+```
+
+The engine writes **only the keys that differ from the defaults**, so the file
+shows this repo's choices and keeps inheriting everything else. `--force` is
+required to replace an existing config — never pass it without the user having
+asked for a rewrite in step 1.
+
+**Relay the engine's report as printed.** It names the site, the project key,
+the issue types and the state mapping it wrote — that report is the evidence
+the setup is right, so don't paraphrase it into "done".
+
+## 6b. Let `/spec-start` commit the snapshot with its spec
+
+**Only when `specs/.core/env.config.json` exists** (per-spec isolation is on).
+If it is absent, skip this — there is nothing to configure.
+
+**Check before you write — a fresh install may already have this.** When this
+superset's `init --isolation` wrote the `env.config.json`, both keys below are
+seeded; this step is the **retrofit** for a project that adopted isolation
+before installing the Jira provider, or ran `/spec-jira-setup` before adopting
+it.
+
+`/spec-start` commits an uncommitted spec for you, but only the paths it can
+prove belong to that spec. Its own folder always does; this repo's per-spec
+Jira snapshot (`sync.baseDir`, `specs/.core/jira-base/<ID>.base.json`) does
+not, because the base engine is deliberately tracker-free and cannot know that
+path exists. Declare it once, in `env.config.json`:
+
+```json
+"spec": {
+  "companionPaths": ["specs/.core/jira-base/{identifier}.base.json"]
+}
+```
+
+`{identifier}` resolves through `branch.identifierField`, so **set that too** if
+it is still empty — `"jira_identifier"` is the field `/spec` stamps. Without
+it the pattern expands to nothing and the snapshot is treated as another spec's
+file: `/spec-start` then refuses the tree instead of committing it, which is the
+safe failure but a needless one.
+
+Leave both alone if the user has already set them.
+
+## 7. Report and hand off
+
+**Finish by checking, not by describing.** Run:
+
+```
+skitterspec spec-sync doctor
+```
+
+and relay its table. That is the difference between a summary of what setup
+*meant* to do and a check of what is actually true — including the layers this
+skill never touched (the scaffold, isolation). Every row that needs attention
+names its own fix, so there is nothing to paraphrase.
+
+It exits non-zero only when a layer is **broken** — configured but wrong. A
+`missing` row is an opt-in nobody took, which is fine; report it, don't treat
+it as a failure.
+
+Then name the next step:
+
+- `/spec` — write a spec; with Jira configured it creates the linked issue in
+  the configured project and stamps the key.
+- `/spec-status` — read-only report of what would push, the safe way to prove
+  the link works.
+- `/spec-push` — send a spec up.
+
+Mention what setup did **not** configure, so the defaults aren't mistaken for
+decisions: phase mapping (`mapping.phases` — subtask per phase by default) and
+field ownership. Point at `jira.config.md` for those. Assignment sync is not
+yet supported by the Jira provider, so there is no identity to settle here.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**The `doctor` table goes above the block, verbatim.** It is a check rather than
+a summary, and every row that needs attention names its own fix — paraphrasing
+it into fields would lose exactly that.
+
+**Verdicts**
+
+- `✅` — every layer `doctor` checked is configured and working.
+- `⚠️` — configured, with a `missing` row: an opt-in nobody took, which is fine.
+  Report it; do not treat it as a failure.
+- `❌` — a `broken` row: configured but wrong. Relay the row and its fix.
+- `⏸` — an existing config was reviewed and left alone, or Jira could not be
+  reached. Nothing was written.
+
+**Fields:** `Built` · `Follow-ups` · `Next`
+
+`Built` is the config written or reviewed, plus what was deliberately left
+unset. **The credentials are never a field** — `doctor` already reports whether
+they are set, masked, and the values are the user's alone.

package/assets/skills/spec-list/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: spec-list
+description: List every spec Jira holds — key, title, status, and the local spec folder name to paste into /spec-start. Read-only, and it starts nothing. Falls back to the repo's own listing when Jira is unreachable. Opt-in — needs specs/.core/jira.config.json. Use when the user says "/spec-list", "what specs are there", "what is in the backlog", or "list specs from Jira".
+disable-model-invocation: true
+---
+
+# /spec-list — every spec Jira holds
+
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
+Read-only. It answers a question and writes nothing — no branch, no folder move,
+no Jira write.
+
+Why ask Jira rather than `ls specs/`? Because `/spec-start` moves a spec to
+`specs/in-progress/` **on that spec's own branch**. On the base branch an
+in-flight spec still reads `backlog`, and a teammate's unlanded spec is not on
+disk at all. Jira knows what is actually in progress; the repo knows what each
+issue is **called on disk**. The listing joins the two.
+
+**Opt-in**: only runs when `specs/.core/jira.config.json` exists. If absent,
+tell the user how to enable Jira sync (`/spec-jira-setup`) and stop.
+
+## 1. Turn the question into flags
+
+The user asks in plain language; the engine takes flags. Map, then run:
+
+| They ask | Flags |
+|----------|-------|
+| "what specs are there", "/spec-list" | *(none — the live default)* |
+| "what's done", "everything" | `--all` |
+| "what's cancelled", a named status | `--state "<name>"` (repeatable) |
+
+The default scope is **live** — whatever `config.states` maps `backlog` and
+`in-progress` to. It is deliberately not everything: in a project with any
+history, Done dwarfs the rows anyone wanted.
+
+`--state` and `--all` are **alternatives**, and the engine refuses the pair
+rather than letting one win silently.
+
+The Linear provider's `--mine`, `--by` and `--next` filters are
+**not yet shipped for the Jira provider** — assignee filtering and backlog
+ordering wait on identity support. Say so when one is asked for, rather than approximating it.
+
+## 2. Run the engine
+
+```
+skitterspec spec-sync list [--state <name> …|--all] [--json]
+```
+
+- **`transport = api`** (credentials resolve) → it queried Jira and printed the
+  listing. **Relay its output verbatim** and stop. Do not re-format it and do not
+  make Jira calls of your own — the engine already joined the local spec
+  folders on.
+- **`transport = mcp`** → the engine made no call. Go to step 3.
+- Anything else it prints on one `spec-sync list:` line is a **degradation**, not
+  a crash — go to step 4.
+
+## 3. The MCP path
+
+Only when the engine said `transport = mcp`. Discover the issue **search** tool
+at runtime the way `/spec-push` describes (`searchJiraIssuesUsingJql`). If Jira
+isn't connected or the tool is missing, go to step 4 — do not stop with nothing.
+
+Then build one JQL query per run:
+
+- **Scope by status.** The live default is
+  `project = <jira.projectKey> AND status IN ("<backlog>", "<in-progress>")`
+  with the names from `config.states`; `--state` substitutes the named
+  status(es); `--all` drops the status clause entirely.
+- **Filter out phase subtasks in the query** — add
+  `AND issuetype NOT IN subtaskIssueTypes()`. A spec is a standard issue; a
+  phase is a subtask, and a listing that includes them buries the specs.
+- **Ask for the fields you print** — `summary` and `status`; the key rides on
+  every result, and the browse url is `<siteUrl>/browse/<key>`.
+- **Page, and never cap silently.** Follow the tool's pagination until it runs
+  out. If you stop early, say so on its own line and say what you stopped at.
+
+**The current phase, on in-progress rows only.** For each row whose status is
+the in-progress one, search again with `parent = <key>` and the same fields.
+Order the children by **key**, numerically — subtasks are minted in phase
+order, so the key carries it. Print the live one as `2/5 — <title>`. Three
+shapes, none of them guessed at:
+
+- **No child in progress** — print nothing extra. A spec sits between phases all
+  the time; that is not a missing phase.
+- **More than one** — print the lowest-numbered, then append
+  `(+N more in progress)`. Two people on one spec is real, not an error.
+- **`mapping.phases` is `inline` for this spec's bucket** — skip the call
+  entirely. Those phases live in the spec issue's own description, so there are
+  no subtasks, and asking would report "no phase in progress" for a spec that is
+  mid-build.
+
+Do **not** make this call for backlog, done or cancelled rows — one lookup per
+in-progress row is the budget, and there are rarely many.
+
+Then join locally — no second Jira call:
+
+```
+skitterspec spec-sync linked --json
+```
+
+That is `[{ spec, bucket, identifier }]`. Key it by `identifier` and attach each
+issue's local `spec` folder name. Format the rows exactly as the API path does
+(step 5), including the `showing N of M` count.
+
+## 4. Degrade — never leave them with nothing
+
+Jira unreachable, no credential, no MCP tool, a Jira error: **do not stop**.
+Print the local listing instead:
+
+```
+skitterspec spec-sync linked --json
+```
+
+Show `spec`, `bucket` and `identifier`, under a one-line banner naming what is
+missing and why it may be wrong:
+
+```
+Jira unreachable (<reason>) — this is the repo's own listing.
+Buckets are this branch's; a spec someone else has started still reads "backlog" here.
+```
+
+That caveat is the point of the banner. A local bucket is not evidence of a
+spec's real state — it is evidence of what this branch knows, which is exactly
+what the command exists to go beyond. A query command that fails closed is one
+people stop typing.
+
+## 5. Report
+
+Relay the listing. Whatever the path, three things must survive into what the
+user reads:
+
+- **The count, as `showing N of M`.** If they are not the same number, say what
+  was left out and how to see it.
+- **The phase, on in-progress rows** — `2/5 — <title>`, after the status.
+- **A row with no local match stays in**, marked `— (not linked here)`. It is not
+  noise: a teammate's unlanded spec, or one authored inside another spec's
+  worktree, is precisely what the repo could not have told them.
+
+Finish with the hand-off, because every row carries the folder name for it —
+as a sentence, not a fenced block: say that `/spec-start <name>` starts any of
+them, with the name copied from a row.
+
+**Never start it yourself.** `/spec-start` provisions a branch, moves a folder
+and commits, and it has dirty-tree refusals this skill does not reproduce.
+Offering the name is the whole job.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**The listing goes above the block, unflattened.** It is rows of other people's
+work; the block is the verdict on this run of the query. Do not fold the listing
+into fields, and do not repeat it there.
+
+**Verdicts**
+
+- `✅` — the listing is Jira's, joined to the local folder names.
+- `⚠️` — listed, with a caveat that changes how the rows read: a paging cap you
+  stopped at, or the local fallback listing under its banner.
+- `⏸` — refused before acting: no config, so there is nothing to list against.
+- `❌` — the query was wrong: `--state` and `--all` together, or a status name
+  Jira rejects.
+
+**Fields:** `Follow-ups` · `Next`
+
+**No `Tracker` row.** This skill names many specs and owns none, so an id row
+would have to pick one. The counts — `showing N of M` — belong to the listing
+above, where the engine already prints them.
+
+`Next` is the hand-off: `/spec-start <name>`, with a name copied from a row.