@catalyst-cloud/cli 0.8.0

package/skills/what-needs-me/scripts/raise.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// raise.mjs — file one decision for the human as an ask ticket, through the cloud's own ask route.
+// Wraps `catalyst-skills ask raise`. You pass fields (question, options, default, what it blocks);
+// the cloud renders the body from the tenant's ask template, applies the ask labels, and creates the
+// blocking relations in one atomic write. Headings are never composed here.
+import { mustRun, parseFlags, parseJson, printHelp } from "./lib/cli.mjs";
+
+const SPEC = {
+  team: { value: true, help: "the team key the ask is filed on (required)" },
+  title: { value: true, help: "the question, one sentence (required)" },
+  context: { value: true, help: "a short paragraph of context the human needs to answer" },
+  option: { value: true, repeat: true, help: "one realistic option (repeat per option; the contract caps how many)" },
+  default: { value: true, help: "what proceeds if the human stays silent, and after how long" },
+  blocks: { value: true, repeat: true, help: "a ticket this decision holds (repeat per ticket)" },
+  "nothing-to-block": { value: false, help: "declare that no ticket is held (the ask then never shows in Waiting on me)" },
+  "ask-key": { value: true, help: "idempotency key so a re-run does not file a second ask" },
+  json: { value: false, help: "print the cloud's response as JSON" },
+};
+
+const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
+if (help) {
+  printHelp("node scripts/raise.mjs --team <key> --title <question> [--context <text>] [--option <text>]... [--default <text>] --blocks <ticket>... | --nothing-to-block [--ask-key <key>] [--json] [--help]", SPEC, [
+    "Search for an existing ask first (node scripts/inbox.mjs); one decision, one ask.",
+    "File BEFORE proceeding on the default. Cite the identifier only from this script's output.",
+  ]);
+  process.exit(0);
+}
+const missing = [];
+if (!flags.team) missing.push("--team");
+if (!flags.title) missing.push("--title");
+if (!flags.blocks && !flags["nothing-to-block"]) missing.push("--blocks <ticket> (or --nothing-to-block)");
+if (missing.length) {
+  process.stderr.write(`raise needs ${missing.join(", ")} (try --help)\n`);
+  process.exit(1);
+}
+
+const args = ["ask", "raise", "--team", flags.team, "--title", flags.title];
+if (flags.context) args.push("--context", flags.context);
+for (const o of flags.option ?? []) args.push("--option", o);
+if (flags.default) args.push("--default", flags.default);
+for (const b of flags.blocks ?? []) args.push("--blocks", b);
+if (flags["nothing-to-block"]) args.push("--nothing-to-block");
+if (flags["ask-key"]) args.push("--ask-key", flags["ask-key"]);
+args.push("--json");
+
+const result = parseJson(mustRun(args, { quiet: true }).stdout, "ask raise");
+const id = result.identifier ?? result.id ?? null;
+if (flags.json) process.stdout.write(JSON.stringify(result) + "\n");
+else {
+  process.stdout.write(`ask raised: ${id ?? "(no identifier returned)"}${flags.blocks ? ` — holds ${flags.blocks.join(", ")}` : " — holds nothing"}\n`);
+  if (flags.default) process.stdout.write(`default if silent: ${flags.default}\n`);
+}
+process.exit(0);

package/skills/what-needs-me/scripts/settle.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// settle.mjs — record the human's answer on an ask and release the work it held.
+// 1. `catalyst-skills ask accept <ask> --answer <commentId> --role <role>` records which comment is
+//    the accepted answer, as the app actor.
+// 2. Every open ticket the ask blocks gets one bookkeeping comment naming the ask and the answer,
+//    so the next agent on that ticket reads the decision without opening the ask.
+// 3. With --close, the ask moves to its team's done slot (the contract's mapping), since a settled
+//    ask is a closed record.
+import { mustRun, parseFlags, parseJson, printHelp, runCli } from "./lib/cli.mjs";
+
+const SPEC = {
+  answer: { value: true, help: "the id of the comment that holds the human's answer (required)" },
+  role: { value: true, help: "the role recording it, e.g. steward or concierge (required)" },
+  close: { value: false, help: "also move the ask to the done slot" },
+  "no-release-note": { value: false, help: "skip the bookkeeping comment on the held tickets" },
+  json: { value: false, help: "print what happened as JSON" },
+};
+
+const { help, flags, positionals } = parseFlags(process.argv.slice(2), SPEC);
+const askTicket = positionals[0];
+if (help || !askTicket || !flags.answer || !flags.role) {
+  printHelp("node scripts/settle.mjs <askTicket> --answer <commentId> --role <role> [--close] [--no-release-note] [--json] [--help]", SPEC, [
+    "The answer must already be a comment on the ask. When it arrived in chat, post it there first with",
+    "the catalyst-linear skill's comment script (as the app actor, never as the human), then settle with that",
+    "comment's id. A free-text reply that names no option is recorded exactly as written, never interpreted.",
+  ]);
+  process.exit(help ? 0 : 1);
+}
+
+const detail = parseJson(mustRun(["query", "issue", askTicket, "--json"], { quiet: true }).stdout, "issue");
+const comments = Array.isArray(detail.comments) ? detail.comments : [];
+const answer = comments.find((c) => String(c.id) === String(flags.answer));
+if (!answer) {
+  process.stderr.write(`comment ${flags.answer} is not on ${detail.identifier ?? askTicket} (${comments.length} comment${comments.length === 1 ? "" : "s"} read); post the answer there first\n`);
+  process.exit(1);
+}
+const answerLine = String(answer.body ?? "").trim().split("\n")[0].slice(0, 200) || "(empty comment)";
+
+const accepted = parseJson(mustRun(["ask", "accept", askTicket, "--answer", flags.answer, "--role", flags.role, "--json"], { quiet: true }).stdout, "ask accept");
+
+const relations = Array.isArray(detail.relations) ? detail.relations : [];
+const held = [...new Set(relations
+  .filter((r) => r.type === "blocks" && (r.issue_identifier === detail.identifier || r.issue_identifier === undefined))
+  .map((r) => r.related_identifier ?? r.related_issue_identifier)
+  .filter((id) => typeof id === "string"))];
+
+const released = [];
+const failed = [];
+if (!flags["no-release-note"]) {
+  for (const t of held) {
+    const body = `${detail.identifier ?? askTicket} was answered (comment ${flags.answer}, recorded by ${flags.role}): ${answerLine}`;
+    const r = runCli(["write", "comment", t, "--bookkeeping", "--body", body, "--json"]);
+    if (r.code === 0) released.push(t);
+    else failed.push({ ticket: t, error: (r.stderr || `exit ${r.code}`).trim().split("\n").at(-1) });
+  }
+}
+
+let closed = false;
+if (flags.close) {
+  const r = runCli(["write", "state", askTicket, "--slot", "done", "--json"]);
+  if (r.code === 0) closed = true;
+  else failed.push({ ticket: askTicket, error: (r.stderr || `exit ${r.code}`).trim().split("\n").at(-1) });
+}
+
+const out = { ask: detail.identifier ?? askTicket, answerComment: flags.answer, role: flags.role, answer: answerLine, accepted, held, released, closed, failed };
+if (flags.json) process.stdout.write(JSON.stringify(out) + "\n");
+else {
+  process.stdout.write(`${out.ask}: answer ${flags.answer} recorded by ${flags.role} — "${answerLine}"\n`);
+  process.stdout.write(held.length ? `held: ${held.join(", ")}; release note posted on: ${released.join(", ") || "none"}\n` : "held nothing\n");
+  if (closed) process.stdout.write(`${out.ask} moved to the done slot\n`);
+  for (const f of failed) process.stdout.write(`failed on ${f.ticket}: ${f.error}\n`);
+}
+process.exit(failed.length ? 1 : 0);

package/skills/whats-happening/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: whats-happening
+description: >-
+  The desk for a Catalyst Cloud tenant. Use when the person asks "what's happening?", "where are we?", "why is that stuck?", "what closed?", "what's next?", or asks for something to be done rather than known. Reads the tenant contract, what is running and queued, the eligibility explainer and the open asks through the catalyst-skills CLI, and answers in one reply with ticket ids. Routes work to a project owner and decisions to what-needs-me. Never composes a URL, never polls, never answers as the human.
+allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+---
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.8.0 — written in this repository for customer tenants -->
+
+# What's happening
+
+You are the one desk the person talks to about their Catalyst Cloud tenant. They ask four questions: where are we, why is that stuck, what closed, what is next. You answer each in one reply, from their tenant's data only, with a ticket identifier on every line. When they ask for something to be done, you route it to an owner; when only they can decide something, you raise it through `what-needs-me`.
+
+## Run first
+
+Scripts are run, never read. Each prints `--help`; exit 2 means this machine is not connected (run the `connect-me` skill), exit 1 means the check itself failed.
+
+- `node scripts/snapshot.mjs --help` — one JSON document: the trimmed contract (teams, stage names by slot, thresholds, ladder), what is running, the queue, the open asks ranked by what they hold, and the replica verdict. Add `--board` for open tickets grouped by stage in the contract's slot order, `--team K` to narrow.
+- `node scripts/explain.mjs --help` — why nothing is offered for one ticket, in one paragraph.
+
+For a single ticket's comments, relations and linked PRs use the `catalyst-linear` skill (`catalyst-skills query issue <id>`); for a pull request's checks and threads, `catalyst-github`.
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| writing any status answer | `references/status-reply.md` (schema: `assets/status-reply.json`) |
+| the board looks wrong, a column is long, or you must decide whether something is stuck | `references/reading-the-board.md` |
+| `explain` returned a reason and the person wants the next action | `references/why-is-it-stuck.md` |
+| "do this one first", "why is that not next", "stop that" | `references/reprioritising.md` |
+| the person asks for work to be done, or a decision surfaces | `references/routing-work.md` |
+
+For depth beyond these, load the fact skills: `how-catalyst-works` (the ladder, slots and mapping, failure layers, queue order, coding accounts), `catalyst-linear` (what a ticket accumulates, reading and writing), `catalyst-github` (what a PR accumulates, mergeability), `catalyst-setup` (readiness).
+
+## Rules
+
+- **Their tenant, as them.** Every read goes through the CLI, which holds the person's own key, the tenant and who they are. You never name, guess at, or try another tenant, and you never paste the key anywhere. "You" in your reply means the connected person: their assigned tickets, their asks.
+- **Tenant facts come from the contract, live.** Stage names, label names, team keys, thresholds and the ladder are in the snapshot's `tenant` block; read them there each time and never restate them from memory.
+- **One reply, ticket ids on every line, source named.** The reply opens with when the snapshot was taken and whether the replica or the API answered. A stale replica is stated, never hidden.
+- **Say what a key cannot see.** PR labels and reactions are not mirrored; the CLI prints the settings URL, and you repeat it instead of guessing. A park or hold is released from the person's own login once its cause is fixed: route that to the `unstick` skill (`catalyst-skills release`), never tell them it needs an operator. Coding-account status (`accounts`) and per-ticket execution history (`explain --history`) are readable — read them.
+- **No polling.** One snapshot per question. Waiting on a change is the project owner's job (`run-this-project` subscribes to the tenant stream); the desk never loops a read.
+- **You are not the owner.** You route work and make it visible; you do not dispatch, overrule a project owner, or run long work in this session.
+- **Never answer as the human.** A decision is an ask through `what-needs-me`, filed before anyone proceeds on its default; the answer is recorded there as the app actor.
+- **Cite an identifier only after a create call returned it.**

package/skills/whats-happening/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "What's happening"
+  short_description: "Where your Catalyst work stands: in flight, blocked and on whom, closed, and what runs next"
+  default_prompt: "Use $whats-happening to tell me where my work stands and why anything is stuck."
+policy:
+  allow_implicit_invocation: true

package/skills/whats-happening/agents/portability.yaml

@@ -0,0 +1,4 @@
+identity: { pack: catalyst-cloud-skills, skill: whats-happening }
+effects: []
+invocation: implicit
+exposure: [catalog]

package/skills/whats-happening/assets/status-reply.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Catalyst status reply",
+  "description": "The one-reply shape a status answer follows. Every line names a ticket identifier; nothing in it is a guess. Fill it from scripts/snapshot.mjs and scripts/explain.mjs, then render it as prose in this order.",
+  "type": "object",
+  "required": ["asOf", "source", "inFlight", "blocked", "closed", "next"],
+  "properties": {
+    "asOf": { "type": "string", "format": "date-time", "description": "When the snapshot was taken (snapshot.takenAt)." },
+    "source": {
+      "type": "string",
+      "description": "Where the facts came from, in one clause: the API, or the replica with its cursor and heartbeat age. Copy the snapshot's source line; never omit it when the replica was stale."
+    },
+    "scope": { "type": "string", "description": "The team key or project the reply covers, when the human asked about one." },
+    "inFlight": {
+      "type": "array",
+      "description": "Tickets a phase is running on right now, or that sit mid-ladder with a live lease. One entry per ticket.",
+      "items": { "$ref": "#/$defs/line" }
+    },
+    "blocked": {
+      "type": "array",
+      "description": "Tickets nothing is offered for, each with the reason in the human's words and who or what releases it.",
+      "items": {
+        "allOf": [
+          { "$ref": "#/$defs/line" },
+          {
+            "properties": {
+              "reason": { "type": "string", "description": "The explainer's reason, translated (references/why-is-it-stuck.md)." },
+              "onWhom": { "type": "string", "description": "The human, a named role, the cloud itself, or a clock — never blank." }
+            },
+            "required": ["reason", "onWhom"]
+          }
+        ]
+      }
+    },
+    "waitingOnHuman": {
+      "type": "array",
+      "description": "Open asks, ranked by what each holds. Taken from snapshot.waitingOnHuman; the what-needs-me skill owns the detail.",
+      "items": {
+        "type": "object",
+        "required": ["ticket", "question", "holds"],
+        "properties": {
+          "ticket": { "type": "string" },
+          "question": { "type": "string" },
+          "holds": { "type": "array", "items": { "type": "string" }, "description": "Ticket identifiers the answer releases." }
+        }
+      }
+    },
+    "closed": {
+      "type": "array",
+      "description": "Tickets that reached the done slot since the window the human asked about (or since the last reply).",
+      "items": { "$ref": "#/$defs/line" }
+    },
+    "next": {
+      "type": "array",
+      "description": "What the queue will pick up next, in queue order, with the phase each will run.",
+      "items": { "$ref": "#/$defs/line" }
+    },
+    "cannotSee": {
+      "type": "array",
+      "description": "Facts your key cannot read (PR labels and reactions; an operator-only park release), named, with where the human can read them (the CLI prints the URL).",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "line": {
+      "type": "object",
+      "required": ["ticket", "summary"],
+      "properties": {
+        "ticket": { "type": "string", "description": "The identifier, KEY-123 shape." },
+        "summary": { "type": "string", "description": "One clause: what it is and where it stands." },
+        "stage": { "type": "string", "description": "The stage name as the contract spells it for this team." },
+        "phase": { "type": "string", "description": "The ladder phase running or offered, when known." },
+        "age": { "type": "string", "description": "How long it has sat where it is, in human units." }
+      }
+    }
+  }
+}

package/skills/whats-happening/references/reading-the-board.md

@@ -0,0 +1,43 @@
+# Reading the board
+
+This reference restates invariants: what the stages are, what order they come in, and what "stuck" means. The names your team uses for each stage, and which state ids they map to, are tenant facts read live from the contract; `node scripts/snapshot.mjs --board` prints the board already grouped and ordered by them.
+
+## Stages are slots, names are display
+
+Catalyst thinks in eleven **slots** in pipeline order: dispatch, intake, research, plan, implement, remediate, verify, review, pr, done, canceled. Each of your teams maps some or all of those slots onto its own Linear workflow states. The contract carries, per team and per slot, the state id (the authority), the live state name and type (display), and whether the state still exists in Linear. A team may have adopted Catalyst's recommended states, mapped its existing ones, or mixed the two; the contract's `workflowMode` says which.
+
+Five slots are load-bearing and a missing one is a distinct silent failure: **dispatch** (where a card goes to be picked up), **intake** (an optional first pass for tickets that have never entered the ladder), **pr** (where a card sits while its pull request is reviewed and merged), **done** and **canceled**. The other six are informational: a wrong mapping there costs a warning, not a stall.
+
+Read a board by slot, never by name. Two teams can call the same slot different things, and a state renamed in Linear keeps its id and its slot.
+
+## Work in progress by stage
+
+The snapshot's `board` block groups open tickets by state name in slot order, drops terminal states, and lists any state name that maps to no slot at the end. Read it top to bottom:
+
+- **dispatch** holds what is ready and waiting for a container. A long dispatch column with nothing in flight is a capacity or eligibility question, not a work question: run `explain` on the first row.
+- **intake** through **pr** are the ladder. A card advances one slot when the matching phase completes; a failed phase writes no board state, so a card that has not moved is either still running, retrying in place, or moved sideways to remediate.
+- **remediate** is an interrupt, not a step. A card there was moved by a failure and returns to its exact previous stage when a repair round succeeds. Count remediate cards separately; they are not progress.
+- Backlog-type states are not slots. A ticket there is parked or not yet chosen; nothing is offered for it and nothing is wrong with it.
+
+## Aging
+
+Age is time since `updated_at`, or since the lease started for a ticket in flight. Report it in human units. Compare it to the phase, not to a fixed number: a research phase and a merge wait have different natural durations, and the cloud's own retry backoff (the contract's `thresholds.retryBackoffMs`) explains many short waits.
+
+## What counts as stuck
+
+A ticket is **stuck** only when all three hold:
+
+1. Nothing is offered for it: the queue lists it excluded, or `explain` gives a reason rather than a position.
+2. The reason does not release itself. Backoffs, cooldowns that name a callback, and fleet-wide holds that clear when the cloud repins are waits, not stalls. The table in `references/why-is-it-stuck.md` marks which is which.
+3. No one is acting on the release: no open ask names it, no human comment landed after the failure, no push arrived.
+
+Everything else is **waiting**, and the reply says what it is waiting on. Calling a wait "stuck" sends the human to fix something the cloud is already handling.
+
+## The signals the cloud posts on the ticket itself
+
+Before declaring anything, read the ticket's comments (`catalyst-skills query issue <id>`; the `catalyst-linear` skill explains each shape). The cloud posts a phase-outcome card on every completion and failure, a remediate-attempt card per repair round, a board-health note when it detects a stall itself, and a merge-wait note when a merge is held. Those comments are the narrative; the per-ticket ledger behind them — attempts, rounds against the cap, park state — is `catalyst-skills explain --history <ticket>`, and the two must agree.
+
+## Two things that look like work and are not
+
+- A ticket carrying the ask marker label, or whose text reads as a decision request, is a question. It is excluded from dispatch by design and belongs in the waiting-on-human block.
+- A ticket claimed by a worker outside the cloud (the local-lane label) is being worked, but not by Catalyst; report it as in flight elsewhere and do not chase the cloud for it.

package/skills/whats-happening/references/reprioritising.md

@@ -0,0 +1,37 @@
+# Reprioritising
+
+This reference restates invariants: how Catalyst orders work and which levers a person actually has. The live queue is `catalyst-skills queue [--team K]` (inside `node scripts/snapshot.mjs`); the thresholds behind backoffs and parks are the contract's `thresholds` block, printed in the snapshot's `tenant` section.
+
+## How the cloud orders work
+
+Each team's queue is derived by the cloud itself from the team's own tickets, so there is nothing a session publishes and nothing that goes stale between sessions. The order is:
+
+1. **Priority** ascending, as set on the Linear ticket (urgent first).
+2. **Created time** ascending: older tickets first among equals.
+3. **Identifier** ascending, as the final tiebreak.
+
+Tickets that are already **mid-ladder** join the same candidate set and sort ahead by how many phases they have completed, so a ticket that is nearly done finishes before a fresh one starts. That is an ordering rule only; it never makes an ineligible ticket eligible.
+
+Within the order, dispatch is bounded per repository (a concurrency cap the tenant admin can set in settings, and a paused repository resolves to zero) and split across teams so one team cannot starve another. Comment-wake work, where the cloud answers a human comment on a ticket, shares the same cap as relay work.
+
+The queue is recomputed on every ingest that touches the team and on each alarm pass, so a change you make shows up within seconds, not on a schedule.
+
+## The three levers a person has
+
+**1. Priority on the ticket.** Change the Linear priority and the queue reorders itself. This is the lever for "do this one first". It does not jump a running phase; it changes what is picked up next.
+
+**2. The dispatch column.** A card is offered only when it sits in the team's dispatch slot (and, for a ticket that has never entered the ladder, the intake slot when intake is enabled). Moving a card into that slot is how work is started; moving it out to a backlog-type state is how work is stopped without cancelling it. The `run-this-project` skill has the script; through this skill you describe the move and let the person or the project owner make it.
+
+**3. Holds.** A PR label from the contract's `merge.prLabels` set keeps an otherwise-mergeable pull request out of the merge queue until a person removes it. A blocking relation from an ask holds every ticket the ask names. Applying the release label the contract names frees a ticket the ask-shape detector flagged by mistake.
+
+Everything else that looks like a lever is not one from a key: unparking a phase, clearing a repair hold, resetting a validate budget and re-pinning a base are operator actions today, and the reply says so and names the settings page rather than promising them.
+
+## What not to promise
+
+- **A running phase is not interrupted** by any of the three levers. It finishes or fails on its own; then the new order applies.
+- **A failed phase does not need re-queueing.** A pre-branch failure or an infrastructure failure retries in place after a backoff; a later failure moves the card to the remediate slot and queues a repair round, capped by the contract's `thresholds.remediateRoundCap`; repeated failures park it after `thresholds.parkAfterConsecutiveFailures`. Moving the card by hand during that sequence usually restarts the count rather than shortening it.
+- **Priority is not urgency to the human.** An urgent ticket that is blocked on an ask still waits for the ask. The what-needs-me ranking (by what an answer releases) is the right list for the human; the queue is the right list for the fleet.
+
+## Answering "why is that one not next?"
+
+Run `explain` on it. If the answer is a position, it is next in order and the cloud is bounded by capacity: say how many are ahead and whether any run at all (if nothing runs anywhere, the likely cause is coding-account capacity, which a key cannot read yet, so name the settings page). If the answer is a reason, use `references/why-is-it-stuck.md`. If the answer is that the ticket is not in the explainer, it is on another team, terminal, or unknown to the mirror: check the identifier before anything else.

package/skills/whats-happening/references/routing-work.md

@@ -0,0 +1,36 @@
+# Routing work
+
+This reference restates an invariant: what this skill does when the person asks for something to be done rather than known, and where a decision goes. Nothing here is tenant-specific.
+
+## Three kinds of request
+
+A message from the person is one of three things, and you decide which in the first sentence of your reply:
+
+1. **A question.** "Where is X? Why is Y stuck? What closed today?" Answer it in the one-reply shape (`references/status-reply.md`). No routing.
+2. **A request for work.** "Get X done. Ship the Y change. Own this until it closes." Turn it into a project with an owner, in one pass, as below.
+3. **A decision only they can make**, surfaced by you or by the cloud. That is never answered here; it goes to `what-needs-me`.
+
+A request that contains a decision is both: route the work and raise the decision, and say in the reply that you did both.
+
+## A request becomes a project with an owner, in one pass
+
+You hold no authority over project owners. Your job is to make the work visible and hand it to a single-threaded owner, then get out of the way.
+
+1. **Find the existing home first.** `catalyst-skills query projects` and `query search <terms>`. A request that fits an open project is a ticket in that project, not a new project. Duplicate projects split one goal's status across two places.
+2. **Scaffold when there is no home.** State the outcome in one sentence, the first ticket or two, and who owns it. Tickets are created through the `catalyst-linear` skill (the app actor, the team key from the contract); a project itself is created by the person in Linear, so name what you want it called and ask them to create it if none fits.
+3. **Name the owner.** The owner is a `run-this-project` session for that project, or a person. Say which, in the reply. Tell the person the one command that starts the owner session, and do not start long-running work inside this session: the desk answers questions; the owner reacts to events.
+4. **Say what you did.** The reply ends with the identifiers created, the owner named, and the next thing the person will see.
+
+Cite an identifier only after the create call returned it. A guessed number is usually a real, unrelated ticket.
+
+## What goes to what-needs-me
+
+Anything that gates active work on a choice only the human can make: a product call, a priority call between two things that cannot both go first, an approval, or an action only they can physically take (a click in settings, a credential). It is raised as an ask through the `what-needs-me` skill with the question, the options, the default that fires if they stay silent, and what it blocks, and it is raised **before** anyone proceeds on the default.
+
+Not an ask: brainstorming, a design back-and-forth, a question the person asked first, a retry-or-abandon call an owner can make, a provider outage (that is one status line, not a per-ticket question).
+
+## Three rules that bind this skill
+
+- **Never answer as the human.** You do not pick an option on an open ask, close one, or post in their voice. When their answer arrives in chat, it is recorded on the ask through `what-needs-me` so the record is complete, and it is recorded as the app actor, never as them.
+- **Escalate inward, never outward.** An instrument reports to the project owner; the owner asks the desk; the desk asks the human, as an ask. A single stuck ticket is never a page to the human. A system-level failure (provider down, out of capacity, rate-limited) is one line in the status reply, not a question per ticket.
+- **One door.** If the person needs a second place to look after your reply, add the missing block to the reply next time rather than pointing them at a dashboard.

package/skills/whats-happening/references/status-reply.md

@@ -0,0 +1,34 @@
+# The one-reply shape
+
+This reference restates an invariant of this skill: how a status answer is shaped. The facts inside it come live from `node scripts/snapshot.mjs` and `node scripts/explain.mjs`; the machine-readable schema is `assets/status-reply.json`.
+
+## The rule
+
+The person asked one question and gets one reply. If they would need a second surface, a second message, or a follow-up question from you to know where things stand, the reply is wrong. Every line names a ticket identifier. Nothing in the reply is a guess: a fact you could not read is named as unreadable, with where it lives.
+
+## The five blocks, in this order
+
+1. **In flight.** Tickets a phase is running on right now, or that hold a live lease mid-ladder. Source: the snapshot's `running` block (fleet activity, the agent roster, lease attributions). One line per ticket: identifier, the phase running, how long it has run.
+2. **Blocked, and on whom.** Tickets nothing is offered for. Source: the queue's excluded rows, then `explain` on each one the person cares about. Every line carries the reason in the person's words and who releases it: the human (an ask), a role, the cloud itself (a backoff, a park that self-releases), or a clock. "On whom" is never blank; if you cannot tell, say the reason the cloud gave and that the release is unknown to a key.
+3. **Waiting on the human.** The open asks, ranked by what each one holds. Source: `waitingOnHuman` in the snapshot. Keep this to identifier, the question, and what it releases; the `what-needs-me` skill owns the detail and the settling.
+4. **Closed.** What reached the done slot in the window the person asked about (or since your last reply). Source: `query issues` filtered by the team's done-slot stage name from the contract, or the change feed for a time window. When you did not read a window, say "since my last reply" and mean it.
+5. **Next.** What the queue picks up next, in the cloud's order, with the phase each will run. Source: the snapshot's `queue` block. Do not reorder it to what you think should be next; the levers are in `references/reprioritising.md`.
+
+A sixth block, **cannot see**, appears only when it is non-empty: the facts your key cannot read (PR labels and reactions, which are not mirrored; an operator-only park release), each with the URL the CLI printed.
+
+## The header line
+
+The reply opens with one clause that says when and from where: the snapshot's `takenAt` and its source line. When the replica was stale or absent, the reply says the numbers came from the API; when it was fresh, it says the cursor. This is not decoration. A stale source that goes unmentioned is the way a wrong status reply happens.
+
+## Writing the lines
+
+- Identifier first, then the stage as the contract spells it for that team, then one clause. `KEY-123 · <stage name> · implement running 14 min`.
+- Age in human units (minutes, hours, days), from `updated_at` or the lease's start, never a raw timestamp.
+- A reason is the translation from `references/why-is-it-stuck.md`, not the cloud's snake_case token, unless the token is one the table does not know, in which case quote it as the cloud spelled it.
+- No adjectives about health. "Stuck" has a definition (`references/reading-the-board.md`); use it only when it applies.
+
+## What the reply never does
+
+- It never restates a stage name, threshold or label from memory. The snapshot's `tenant` block carries the live values; read them there each time.
+- It never answers an ask, proposes a default on the human's behalf inside the status reply, or moves anything. Routing a request is `references/routing-work.md`; a decision is the `what-needs-me` skill.
+- It never pads a short answer. When one ticket is in flight and nothing is blocked, the reply is three lines.

package/skills/whats-happening/references/why-is-it-stuck.md

@@ -0,0 +1,62 @@
+# Why is it stuck
+
+This reference restates an invariant: the vocabulary the cloud's eligibility explainer uses when nothing is offered for a ticket, translated for a person, with what releases each. `node scripts/explain.mjs <ticket>` prints the reason for one ticket; this table turns it into the next action. The `how-catalyst-works` skill carries the mechanism behind each row.
+
+## How to read a reason
+
+`explain` prints one paragraph: the queue position (or none), the status, the reason, a detail or marker when the cloud gave one, the last failure, and any advisories. Match the reason to a row below. "Releases itself" means the cloud clears it with no human action; "needs" names who acts. When a reason is not in this table, `explain` prints it as the cloud spelled it; report it verbatim and say the bundle does not know it.
+
+## Reasons that release themselves
+
+| reason | what it means | how it clears |
+| -- | -- | -- |
+| `retry_backoff` | the failed phase is retrying in place and waiting out its rung | a clock; the rungs are the contract's `thresholds.retryBackoffMs` |
+| `lease_held` | a live container already holds this phase | the phase finishes |
+| `intake_lease_held` | a later phase is offered while an intake container still holds the ticket | intake finishes |
+| `environment_check_running` | the repository's environment check is in flight | the check finishes |
+| `runner_image_breaker` | fleet-wide: the live runner image fails every phase at startup, so dispatch is held rather than parking tickets | the cloud moves the pin; one alert per tenant, no per-ticket action |
+| `routing_unavailable` | claimed, then refused at kickoff: no route, no eligible coding-account slot, or the provider is unavailable | provider recovery or a slot freeing; if it persists, the tenant admin checks coding accounts in settings |
+| `cooling_down` (with a named callback) | the phase is parked on a condition the cloud watches | the callback fires; the `detail` names it |
+
+## Reasons that need a human
+
+| reason | what it means | who acts and how |
+| -- | -- | -- |
+| `ask_ticket` | it carries an ask label; a question is never work | the human answers the ask (`what-needs-me`) |
+| `ask_shape_suspected` | its own text reads as a decision request though it carries no ask label | the human either answers it as an ask or applies the release label the contract names |
+| `blocked` | a live blocking relation holds it | whoever owns the blocker closes it; if the blocker is an ask, that is the human |
+| `not_at_dispatch_stage` | the card is not in the team's dispatch column | someone moves the card to the dispatch slot (`references/reprioritising.md`) |
+| `not_at_pr_stage` | merge is next but the card is not in the PR column | the card returns to the pr slot; an automation that bounced it should be found |
+| `no_change_hold` | a repair round changed nothing | a human comment on the ticket, or a new push to the branch |
+| `waiting_on` | a merge-gate failure with no cause the cloud can repair | read the merge-wait comment on the ticket; usually a hold label or a review a person must give (`catalyst-github`) |
+| `externally_claimed` | a worker outside the cloud holds it | that worker, or the human removes the local-lane label |
+| `environment_check_required` / `_failed` / `_expired` / `_hash_mismatch` | the repository's environment gate has not passed | the tenant admin runs or fixes the environment check in settings |
+| `repo_paused` | an operator paused the repository | the operator resumes it |
+| `scope_overlap` | its declared file scope intersects a ticket already in flight | wait for the other ticket, or the human decides which goes first |
+
+## Reasons a release clears once the cause is fixed
+
+These do not release themselves, and nobody but the person needs to act: once the recorded cause is fixed, the person's own login releases them with `catalyst-skills release <ticket>`. The desk does not release; route the ticket to the `unstick` skill, which reads the history, previews the release and runs it, or names what a person must do first.
+
+| reason | what it means | note |
+| -- | -- | -- |
+| `phase_parked` / `cooling_down` (parked after repeated failures, or the round cap was spent) | the phase is parked and does not release itself | `unstick`; `explain --history` names the park and the failure class it recorded |
+| `remediate_parked` | the repair phase itself is parked, so the failing phase has nowhere to be repaired | as above |
+| `validate_class_spent` | this validate failure already spent its one repair round in this episode | a push or a comment saying what to change releases it on its own; otherwise `unstick` |
+| `human_owned_pr` | a person's own pull request holds the ticket | that person closes or merges it; no release clears it |
+| `review_not_converging` | review and repair kept finding new problems without converging | a person reads the findings and comments on the ticket to resume; raise an ask for that read |
+| `round_threshold` | the ticket spent its lifetime repair budget | a person answers the ask the cloud raised, or pushes a fix |
+| `no_branch_to_remediate` / `branch_missing` / `branch_gone` | a branch-dependent phase has no branch to clone | the cloud releases missing-branch parks on its own budget; a deleted branch needs a human to decide |
+| `stale_failure_episode` | the ladder advanced after the recorded failure | informational; the round is dropped |
+
+## Reasons that are not problems
+
+`ticket_terminal` (done or canceled), `pipeline_complete` (every phase ran), and `pr_merged` (the PR merged, nothing left to clone) describe finished work. Report them as closed, not blocked.
+
+## When the cloud could not judge
+
+A status of `unknown` with a reason such as `ordering_never_published`, `ordering_stale`, `workflow_mapping_unknown`, `ticket_unknown`, `dependency_snapshot_unknown`, `blocker_unknown`, `label_snapshot_unknown`, `prior_artifact_unknown`, `scope_unknown`, `scope_occupancy_unknown` or `branch_snapshot_unknown` means the evaluator failed closed rather than guessing. Most clear on the cloud's next pass. `workflow_mapping_unknown`, and `ordering_never_published` beside it, does not clear by itself when the team has no saved stage mapping: `explain` then names the missing stages, and a tenant owner or admin maps the team in Settings → Linear teams. If any other one persists for a team, the readiness checks (`catalyst-setup`) are the next read.
+
+## The one advisory
+
+`human_addressed_unlabeled_ask_suspect` gates nothing: the ticket is assigned to a human with no delegate and may be an unlabelled ask. Mention it in the waiting-on-human block with a question mark.

package/skills/whats-happening/scripts/explain.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// explain.mjs — "why is this ticket stuck?" in one paragraph. A thin wrapper over
+// `catalyst-skills explain <ticket>`, which reads the cloud's eligibility explainer for the ticket's
+// team and translates the exclusion reason, the failure block and any advisories into plain English.
+import { mustRun, parseFlags, printHelp } from "./lib/cli.mjs";
+
+const SPEC = {
+  json: { value: false, help: "print the raw eligibility row and the explanation as JSON" },
+  history: { value: false, help: "ask for the per-ticket execution history (the CLI says when a key cannot see it yet)" },
+};
+
+const { help, flags, positionals } = parseFlags(process.argv.slice(2), SPEC);
+const ticket = positionals[0];
+if (help || !ticket) {
+  printHelp("node scripts/explain.mjs <ticket> [--json] [--history] [--help]", SPEC, [
+    "The ticket is its identifier (the KEY-123 shape). The explanation names the queue position, the status,",
+    "the reason nothing is offered, the last failure, and what releases it; an unknown reason is printed as the",
+    "cloud spelled it. Read references/why-is-it-stuck.md to turn the reason into the next action.",
+  ]);
+  process.exit(help ? 0 : 1);
+}
+
+const args = ["explain", ticket];
+if (flags.history) args.push("--history");
+if (flags.json) args.push("--json");
+const r = mustRun(args);
+process.stdout.write(r.stdout.endsWith("\n") ? r.stdout : `${r.stdout}\n`);
+process.exit(0);