@catalyst-cloud/cli 0.9.5 → 0.13.0

package/skills/what-this-repo-needs/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: what-this-repo-needs
+description: >-
+  What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups — build/test, deploy-only, bindings — each with where it was found, what uses it, and where a local value would come from. Never reads or prints a value. Also validates a catalyst.env.json file the same way the cloud does. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing a repository's environment declaration.
+allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+---
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
+
+# What this repository needs
+
+Say this first, in your own words, before you scan: the fleet builds and tests this repository in a
+container that has only what is declared — nothing more, nothing guessed. The names below are what
+that container needs; none of them is a value, and this tool never reads or shows one.
+
+## Run first
+
+- `node scripts/inventory.mjs [path] --help` — scans the repository (default: here) and prints the
+  names in three groups: build/test, deploy-only, bindings. Each name shows where it was found
+  (file:line), what uses it, and where a local value would come from — a `.env` file, your shell, a
+  CI secret, or a Cloudflare binding. `--json` gives the same data in machine form.
+- `node scripts/check.mjs <file> --help` — validates an existing `catalyst.env.json` offline, with
+  the same rules the cloud applies, and never prints a value from it either.
+
+Then ask the person to review the grouped list: for each name, keep it, drop it, or move it to a
+different group. Keep your own reasoning short — the list is the point, not your commentary on it.
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| the person asks what a group means, or why a wrangler.toml entry is or is not a binding | `references/what-each-group-means.md` |
+
+## Rules
+
+- Report, never repair. This tool never writes `catalyst.env.json` and never proposes anything.
+- Never print a value. Not a `.env` value, not a secret, not a committed `wrangler.toml [vars]`
+  value — only the name, where it was found, and where a local value would come from.
+- A Cloudflare (or other platform) binding is not an environment value; keep the two apart.
+- This reads the repository only. It needs no login and makes no network call — unlike the
+  account-scope `catalyst-skills environment` verb, which reads your tenant's own declaration.

package/skills/what-this-repo-needs/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "What this repository needs"
+  short_description: "The environment variable names this repository needs, where each is used, and where its value comes from — never a value"
+  default_prompt: "Use $what-this-repo-needs to explain what environment variables this repository needs and where they come from."
+policy:
+  allow_implicit_invocation: true

package/skills/what-this-repo-needs/agents/portability.yaml

@@ -0,0 +1,4 @@
+identity: { pack: catalyst-cloud-skills, skill: what-this-repo-needs }
+effects: []
+invocation: implicit
+exposure: [catalog]

package/skills/what-this-repo-needs/references/what-each-group-means.md

@@ -0,0 +1,68 @@
+# What each group means
+
+`node scripts/inventory.mjs` sorts every environment variable name it finds into exactly one of
+three groups. This page explains what each one means and why a name lands where it does — it never
+restates a value, because the scan itself never reads one.
+
+## build/test
+
+Needed to install, build and run the tests in a container. This is the default group: a name lands
+here unless something specific pulls it into `deploy-only` or `bindings`. Examples: a name read by
+the repository's own source (`process.env.X`), a name documented in a `.env.example`-shaped file, a
+name a non-deploy workflow job uses.
+
+The scan does not read `package.json` scripts. A name that only a script's own shell line mentions
+and nothing else refers to is therefore not listed — add it by hand if the container needs it.
+
+A name referenced from **both** a deploy job and a non-deploy job (or build step) still lands here,
+not in `deploy-only` — a container that builds and tests the repository needs it too, so the
+stricter requirement wins.
+
+## deploy-only
+
+A CI secret used **only** by a job the scan classifies as deploying something: a workflow job that
+sets `environment:`, whose id looks like `deploy`, `publish`, `release` or `cd`, or that runs a
+recognised deploy command (`wrangler deploy`, `npm publish`, `gh release create`, and similar). If
+the same name is referenced anywhere outside a deploy job, it moves to `build/test` instead.
+
+Its local value comes from a CI secret — something a repository or organisation admin sets in the
+CI provider, not something a person types into a local `.env` file.
+
+## bindings
+
+A Cloudflare (or other platform) binding: a name bound to a resource — a KV namespace, a D1
+database, a Durable Object, an R2 bucket, a queue — declared in `wrangler.toml`. A binding is not an
+environment value a process reads from `process.env`; it is wired up by the platform at deploy
+time, which is why this scan keeps the two apart even though both are "names the container needs".
+
+A `wrangler.toml` binding table names the binding through one attribute's value — `binding = "NAME"`
+for most tables, `name = "NAME"` for `durable_objects.bindings` — never through the table's own key.
+
+## wrangler.toml `[vars]`: build/test, not a binding, and nothing to declare
+
+A `[vars]` (or `[env.<name>.vars]`) table is different from every other wrangler table: its keys ARE
+the names, and their values are committed in `wrangler.toml` itself — checked into the repository,
+not a secret and not something a person supplies locally. So a `[vars]` name lands in `build/test`
+(it is a plain value a build or test step could read, not a resource binding), and the scan marks it
+`needsDeclaration: false`: there is nothing for a customer to declare, because the value is already
+sitting in the file everyone can already read.
+
+## Where a local value comes from
+
+For every name, "where the local value comes from" is one of:
+
+- **a `.env` file or your shell** — the ordinary case for `build/test`.
+- **a CI secret** — for `deploy-only`, and for any `build/test` name whose only non-committed source
+  is a workflow's `secrets.X` reference.
+- **a Cloudflare binding** — for `bindings`; there is no local value to supply, the platform wires
+  it up.
+- **value committed in wrangler.toml — nothing to declare** — for a `[vars]` entry.
+
+None of these is the value itself — only where it would come from, so a person reviewing the list
+knows what to check without this tool ever showing them what is actually set.
+
+## A `wrangler.jsonc` or `wrangler.json` file
+
+Modern Wrangler configs are often JSONC. This scan does not read them yet — `wrangler.toml` is the
+only Cloudflare config format it understands — so a repository configured that way gets a note
+saying so, rather than a silent, confidently wrong "no bindings found".

package/skills/what-this-repo-needs/scripts/check.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// check.mjs — validates a catalyst.env.json file offline, with the same rules this bundle vendors
+// from the cloud's own validator. Never reads or prints a value. Offline: no login, no network —
+// wraps `catalyst-skills env check`.
+import { runCliOffline } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/check.mjs <file> [--json]
+
+Validates a catalyst.env.json file against this bundle's offline copy of the cloud's rules. Prints
+"valid" or the refusal reasons — never a value. Exit 0 valid, 1 invalid or unreadable.
+
+--json prints {state, errors}. This is a local, offline check: no login, no network required.`;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(HELP);
+  process.exit(0);
+}
+const json = args.includes("--json");
+const file = args.find((a) => a !== "--json");
+if (!file) {
+  console.error("env check needs a file: node scripts/check.mjs <path to catalyst.env.json>");
+  console.log(HELP);
+  process.exit(1);
+}
+
+const res = runCliOffline(["env", "check", file, ...(json ? ["--json"] : [])]);
+if (res.stdout) process.stdout.write(res.stdout);
+if (res.stderr) process.stderr.write(res.stderr);
+await finish(res.code);
+
+/**
+ * ⛔ NEVER `process.exit(code)` STRAIGHT AFTER A WRITE — the same rule `bin/catalyst-skills.js`
+ * states in full, reintroduced here at validate attempt 29 (M-3). When this script's own stdout is a
+ * PIPE — which is how an agent harness runs it — writes are asynchronous, so `process.exit` severs
+ * whatever is still in flight AND STILL REPORTS THE ORIGINAL EXIT CODE. Measured: a `--json` body of
+ * 385,633 bytes arrived as 65,536 bytes of invalid JSON at exit 0. Writing to a FILE hides it,
+ * because a file gives stdout a synchronous write path.
+ *
+ * So: park the code on `process.exitCode`, wait for both streams to drain, and only then exit.
+ */
+function drained(stream) {
+  return new Promise((resolve) => {
+    if (!stream || stream.destroyed || stream.writableEnded) return resolve();
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    stream.once("error", done);
+    try {
+      stream.write("", done);
+    } catch {
+      done();
+    }
+  });
+}
+
+async function finish(code) {
+  process.exitCode = code;
+  await Promise.all([drained(process.stdout), drained(process.stderr)]);
+  process.exit(code);
+}

package/skills/what-this-repo-needs/scripts/inventory.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// inventory.mjs — lists the environment variable NAMES this repository needs, grouped build/test,
+// deploy-only and bindings, each with where it was found, what uses it, and where a local value
+// would come from. Never reads or prints a value. Offline: no login, no network — wraps
+// `catalyst-skills env inventory`.
+import { runCliOffline } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/inventory.mjs [path] [--json]
+
+Scans a repository (default: the current directory) for the environment variable names it needs and
+prints them in three groups: build/test, deploy-only, bindings. For each name: where it was found
+(file:line), what uses it, and where a local value would come from. Never reads or prints a value.
+
+--json prints the same data as JSON. This is a local, offline scan: no login, no network required.`;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(HELP);
+  process.exit(0);
+}
+const json = args.includes("--json");
+const path = args.find((a) => a !== "--json") ?? ".";
+
+const res = runCliOffline(["env", "inventory", path, ...(json ? ["--json"] : [])]);
+if (res.stdout) process.stdout.write(res.stdout);
+if (res.stderr) process.stderr.write(res.stderr);
+await finish(res.code);
+
+/**
+ * ⛔ NEVER `process.exit(code)` STRAIGHT AFTER A WRITE — the same rule `bin/catalyst-skills.js`
+ * states in full, reintroduced here at validate attempt 29 (M-3). When this script's own stdout is a
+ * PIPE — which is how an agent harness runs it — writes are asynchronous, so `process.exit` severs
+ * whatever is still in flight AND STILL REPORTS THE ORIGINAL EXIT CODE. Measured: a `--json` body of
+ * 385,633 bytes arrived as 65,536 bytes of invalid JSON at exit 0. Writing to a FILE hides it,
+ * because a file gives stdout a synchronous write path.
+ *
+ * So: park the code on `process.exitCode`, wait for both streams to drain, and only then exit.
+ */
+function drained(stream) {
+  return new Promise((resolve) => {
+    if (!stream || stream.destroyed || stream.writableEnded) return resolve();
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    stream.once("error", done);
+    try {
+      stream.write("", done);
+    } catch {
+      done();
+    }
+  });
+}
+
+async function finish(code) {
+  process.exitCode = code;
+  await Promise.all([drained(process.stdout), drained(process.stderr)]);
+  process.exit(code);
+}

package/skills/what-this-repo-needs/scripts/lib/cli.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches the Catalyst Cloud SDK and API: by spawning the
+// catalyst-skills CLI this bundle installed. It reads customer.json to find that CLI and nothing
+// else; it never holds the key itself. This file is a library — run a sibling script with
+// --help for usage. Per-skill (skills install one directory at a time, so nothing shared outside the
+// skill would ever be installed) — see runCliOffline below for the one way this skill's copy differs.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
+
+export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: ${CONNECT_COMMAND}`;
+
+/** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
+export function configPath() {
+  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? process.env.USERPROFILE ?? "";
+  return join(home, ".config", "catalyst-cloud", "customer.json");
+}
+
+/** The customer config, or exit 2 with one line naming the connect command. Never throws. */
+export function requireCustomerConfig() {
+  const path = configPath();
+  if (!existsSync(path)) {
+    console.error(CONNECT_HINT);
+    process.exit(2);
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    console.error(`${path} could not be read (${err instanceof Error ? err.message : String(err)}) — ${CONNECT_HINT}`);
+    process.exit(2);
+  }
+  if (!hasCredential(cfg) || typeof cfg.baseUrl !== "string") {
+    console.error(`${path} is missing required fields — ${CONNECT_HINT}`);
+    process.exit(2);
+  }
+  return cfg;
+}
+
+/**
+ * Run one catalyst-skills verb and return {code, stdout, stderr}. Spawns the CLI whose path the
+ * connect step recorded in customer.json; falls back to `npx @catalyst-cloud/catalyst-skills` when
+ * no path is recorded or it no longer exists. Exits 2 when the machine is not connected.
+ */
+export function runCli(args, opts = {}) {
+  const cfg = requireCustomerConfig();
+  return spawnCli(cfg, args, opts);
+}
+
+/**
+ * Run `catalyst-skills env inventory` / `env check` without requiring a credential at all. Unlike
+ * every other verb this launcher can reach, `env inventory` and `env check` are LOCAL and OFFLINE —
+ * they never call the cloud — so gating them on `requireCustomerConfig` would break the feature they
+ * exist to provide. Still resolves the recorded `cliPath` when a customer.json happens to exist (so
+ * an already-connected machine reuses the same installed CLI), and still falls back to
+ * `npx @catalyst-cloud/catalyst-skills` otherwise.
+ */
+export function runCliOffline(args, opts = {}) {
+  let cfg = null;
+  try {
+    const path = configPath();
+    if (existsSync(path)) cfg = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    cfg = null;
+  }
+  return spawnCli(cfg, args, opts);
+}
+
+function spawnCli(cfg, args, opts) {
+  const recorded = Boolean(cfg) && typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
+  const command = recorded ? process.execPath : process.platform === "win32" ? "npx.cmd" : "npx";
+  const argv = recorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
+  const res = spawnSync(command, argv, {
+    encoding: "utf8",
+    input: opts.stdin,
+    env: process.env,
+    maxBuffer: 64 * 1024 * 1024,
+    shell: !recorded && process.platform === "win32",
+  });
+  if (res.error) {
+    console.error(`could not run ${recorded ? cfg.cliPath : `npx ${PACKAGE}`}: ${res.error.message}`);
+    process.exit(2);
+  }
+  return { code: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+
+/**
+ * Run a verb that must succeed. On exit 2 (the CLI's "not configured / refused" class) the script
+ * exits 2; on any other non-zero exit it exits 1. The CLI's own stderr is forwarded either way so the
+ * reason is never lost.
+ */
+export function runCliOrExit(args, opts = {}) {
+  const res = runCli(args, opts);
+  if (res.code === 0) return res;
+  const why = res.stderr.trim() || res.stdout.trim() || `catalyst-skills ${args.join(" ")} exited ${res.code}`;
+  console.error(why);
+  process.exit(res.code === 2 ? 2 : 1);
+}
+
+/** Parse the CLI's --json stdout; null when it is not JSON (the caller decides what that means). */
+export function parseJson(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  console.log("lib/cli.mjs is a library used by the scripts beside it; run any of those with --help for usage.");
+}

package/skills/what-this-repo-needs/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
+// session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
+// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// itself. A new credential kind lands here, once.
+
+/** The command that connects this machine, as every not-connected line names it. */
+export const CONNECT_COMMAND =
+  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/whats-happening/SKILL.md

@@ -4,7 +4,7 @@ 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.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # What's happening
 

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

@@ -12,7 +12,7 @@ Each team's queue is derived by the cloud itself from the team's own tickets, so
 
 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.
+Within the order, dispatch is bounded per repository (a concurrency cap of 20 running phases by default that an operator raises or lowers — the tenant's own settings page displays it and does not change it — and a paused repository resolves to zero without losing the stored value) 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.
 

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

@@ -16,6 +16,8 @@ The person asked one question and gets one reply. If they would need a second su
 
 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.
 
+A flow number is named in that block by name, not left out: cycle time, throughput, or how long pull requests have been open are not computed by anything a key reads today. Say they are not computed rather than counting ticket dates or open pull requests and calling it that.
+
 ## 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.

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

@@ -4,55 +4,62 @@ This reference restates an invariant: the vocabulary the cloud's eligibility exp
 
 ## 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.
+`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; "who acts" names who does — the person, with their own login; a tenant owner or admin, in settings; an operator; or "no one acts", which is a fourth honest answer, not a gap. 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 |
-| `wip_limit` | the project (one Linear team, all its repositories) is at its WIP limit, default 12, so this ticket gets no first phase; tickets already in progress are unaffected | a ticket in progress finishes. If the fleet is idle at the limit, the in-progress tickets are the ones waiting (merge queue, holds, paused repositories, asks): unstick those, never the queue. Raising the limit is the project owner's call |
+| reason | what it means | how it clears | who acts |
+| -- | -- | -- | -- |
+| `retry_backoff` | the failed phase is retrying in place and waiting out its rung | a clock; the rungs are the contract's `thresholds.retryBackoffMs` | no one acts |
+| `lease_held` | a live container already holds this phase | the phase finishes | no one acts |
+| `intake_lease_held` | a later phase is offered while an intake container still holds the ticket | intake finishes | no one acts |
+| `later_phase_lease_held` | an earlier phase is offered while a live container still holds a later phase of this ticket | the later phase finishes | no one acts |
+| `environment_check_running` | the repository's environment check is in flight | the check finishes | no one acts |
+| `claim_storm` | this unit was claimed too many times in the last hour | it waits the hour out; there is nothing to release | no one acts |
+| `repo_at_capacity` | the repository's runner seats are all in use | it starts when a seat frees | no one acts |
+| `runner_image_breaker` | fleet-wide: the live runner image fails every phase at startup, so dispatch is held rather than parking tickets | an operator moves the pin; one alert per tenant, no per-ticket action | an operator |
+| `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 | usually no one acts; if it persists, a tenant owner or admin, in settings, checks coding accounts |
+| `cooling_down` (with a named callback) | the phase is parked on a condition the cloud watches | the callback fires; the `detail` names it | no one acts; an operator can release it directly if the callback stalls |
+| `no_branch_to_remediate` / `branch_missing` | a branch-dependent phase has no branch yet | the cloud releases these parks on its own budget | no one acts |
+| `stale_failure_episode` | the ladder advanced after the recorded failure, so the round would repair a phase already passed | the round is dropped automatically; the reason is informational | no one acts |
+| `wip_limit` | the project (one Linear team, all its repositories) is at its WIP limit, default 12, so this ticket gets no first phase; tickets already in progress are unaffected | a ticket in progress finishes. If the fleet is idle at the limit, the in-progress tickets are the ones waiting (merge queue, holds, paused repositories, asks): unstick those, never the queue. Raising the limit is the project owner's call | no one acts on this ticket; the in-progress tickets it waits on each have their own row |
 
 ## 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 |
+| `ask_ticket` | it carries an ask label; a question is never work | the person, with their own login, answers the ask (`what-needs-me`) |
+| `ask_shape_suspected` | its own text reads as a decision request though it carries no ask label | the person, with their own login, 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; when the blocker is an ask, that is the person, with their own login |
+| `not_at_dispatch_stage` | the card is not in the team's dispatch column | the person, with their own login, 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 person, with their own login, returns the card to the pr slot; an automation that bounced it should be found |
+| `no_change_hold` | a repair round changed nothing | the person, with their own login, comments on the ticket or pushes to the branch |
+| `waiting_on` | a merge-gate failure with no cause the cloud can repair | the person, with their own login, reads the merge-wait comment on the ticket; usually a hold label or a review they must give (`catalyst-github`) |
+| `externally_claimed` | a worker outside the cloud holds it | that worker releases it, or the person, with their own login, removes the local-lane label |
+| `environment_check_required` | the repository's environment check has not run | a tenant owner or admin, in settings, runs the environment check |
+| `environment_check_failed` | the repository's environment check failed | a tenant owner or admin, in settings, fixes and reruns the environment check |
+| `environment_check_expired` | the environment check's verdict aged out | a tenant owner or admin, in settings, reruns the environment check |
+| `environment_check_hash_mismatch` | the environment changed since its recorded verdict | a tenant owner or admin, in settings, reruns the environment check |
+| `repo_paused` | an operator paused the repository | an operator resumes it |
+| `scope_overlap` | its declared file scope intersects a ticket already in flight | the person, with their own login, decides which goes first, or waits for the other ticket |
+| `human_owned_pr` | a person's own pull request holds the ticket | the person, with their own login, closes or merges that pull request, or hands it to Catalyst; never close someone's pull request for them. No release clears this one — the release command refuses it terminally — so do not route it to `unstick` expecting one |
+| `review_not_converging` | review and repair kept finding new problems without converging | the person, with their own login, reads the findings (`catalyst-github`) and comments on the ticket to resume; raise an ask for that read. No release clears this one — the release command refuses it terminally — so do not route it to `unstick` expecting one |
+| `round_threshold` | the ticket spent its lifetime repair budget | the person, with their own login, answers the ask the cloud already raised, or pushes a fix; point at that ask rather than raising a second one. No release clears this one — the release command refuses it terminally — so do not route it to `unstick` expecting one |
 
 ## 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.
+These do not release themselves: 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 |
+| reason | what it means | note | who acts |
+| -- | -- | -- | -- |
+| `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 | the person, with their own login |
+| `remediate_parked` | the repair phase itself is parked, so the failing phase has nowhere to be repaired | as above | the person, with their own login |
+| `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` | the person, with their own login |
+| `branch_gone` | a branch that existed was deleted | the person, with their own login, decides whether to recreate it or drop the ticket | the person, with their own login |
 
 ## 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.
+`ticket_terminal` (done or canceled), `pipeline_complete` (every phase ran), and `pr_merged` (the PR merged, nothing left to clone) describe finished work; no one acts. Report them as closed, not blocked.
 
 ## When the cloud could not judge