@catalyst-cloud/cli 0.13.0 → 0.14.0

package/skills/how-catalyst-works/references/what-runs-next.md

@@ -1,95 +0,0 @@
-# What runs next: queue order, concurrency, routing, and every exclusion reason
-
-This reference restates invariants. The live queue is `node scripts/whats-running.mjs --queue [--team <key>]`; one ticket's verdict is `node scripts/explain-ticket.mjs <ticket>`. The reason phrases below match the CLI's own table, so a reason you see printed can be looked up here.
-
-## Queue order
-
-Each team's dispatch queue is derived by the tenant's own store, continuously, from the board:
-
-1. Queued tickets (cards in the dispatch slot) rank by **priority ascending, then created time ascending, then identifier ascending**.
-2. Mid-ladder tickets (any ticket with a phase already completed) join the candidate set and order **by completed-phase count descending**, so a ticket close to the end goes before one that just started. That count is an ordering surrogate only; it never decides membership or eligibility.
-
-The queue re-derives within seconds of any board change and at the top of every periodic pass as a backstop. `dispatch_queue.source` reads `self-derived` when the tenant store built it itself, which is the normal case.
-
-## Concurrency
-
-- Each repository has a concurrency cap (default 20 running phases). An operator can raise or lower it; a paused repository resolves to a cap of zero without touching the stored value, so resuming restores it.
-- Dispatch buckets by repository and splits slots across teams so no team starves another. A slot that is running, might be running, or is restarting is never free capacity.
-- Comment-wake work (an agent answering a human comment) shares the same cap as ladder work.
-
-## The WIP limit
-
-A Catalyst project (one Linear team, across every repository registered to it) starts no new ticket while its work in progress is at its limit. The limit is per project, never per repository and never workspace-wide: the project's own stored setting when there is one, else a tenant-wide value the operator set, else 12. `0` is a real limit and holds every new start. A workspace owner or admin sets it per project through the project-settings route; there is no page for it yet.
-
-It holds only new starts. A ticket in the dispatch column that has never run gets no first phase while the team is at its limit, and the explainer prints `wip_limit` with a detail such as "14 tickets in progress in <team key>, at or above its WIP limit of 12; this ticket starts once one finishes". A ticket that has already started keeps getting every later phase, whatever the count.
-
-What counts as in progress: every live ticket of the team that is past the dispatch column, or was granted a first phase even if its card still sits there, and is not in a terminal state (done, canceled, duplicate). Blocked, parked, waiting on the merge queue or waiting on a human all count: the count is tickets, not running containers. What does not count: triage and backlog states, a dispatch-column ticket that never started, a ticket fenced for a worker outside the cloud (the local-lane label), and a ticket whose PR merged and that only the runner-pin gate holds.
-
-How to read a fleet idle at the limit: nothing runs because the tickets in progress are all waiting, on the merge queue, on a hold, on a paused repository or on a person. Unstick those (`unstick`, `catalyst-github`, `what-needs-me`); the limit is doing its job. Raising the limit is the project owner's call, not a repair.
-
-## The routing decision, in five checks
-
-When a phase is about to start, a route is chosen per candidate, in order, and the first survivor wins:
-
-1. capability match (can this route run this phase);
-2. a model is configured;
-3. the provider is available;
-4. if the candidate needs a coding-account slot: an eligible slot exists and the headroom floor is met;
-5. degraded, equivalent or stage-default parameters resolve.
-
-No survivor is `no_eligible_account_slot` when any candidate was skipped on capacity, else `routing_unavailable` (a misconfiguration). See `references/coding-accounts.md` for what a slot is.
-
-## Every exclusion reason, one line each
-
-| Reason | Meaning |
-| -- | -- |
-| `ticket_terminal` | the ticket is in a done or canceled state |
-| `pipeline_complete` | every phase has already completed |
-| `not_at_dispatch_stage` | the card is not in the team's dispatch column; move it there to dispatch |
-| `not_at_pr_stage` | merge is next but the card is not in the PR column (waived when a tenant automation bounced it off PR and the bounce was recorded) |
-| `blocked` | a live blocking relation; the blocker closes first |
-| `cooling_down` | the offered phase is parked; an operator or a callback releases it, not a clock |
-| `lease_held` | a live container already holds this phase |
-| `intake_lease_held` | a later phase is offered while an intake container still holds the ticket |
-| `ask_ticket` | it carries an ask label; a question is never work |
-| `ask_shape_suspected` | its own text reads as a decision request; a human releases it with the release label from the contract's `vocabulary` |
-| `externally_claimed` | a worker outside the cloud claimed it |
-| `environment_check_required` | the repository's environment check has not run |
-| `environment_check_running` | the environment check is in flight |
-| `environment_check_failed` | the environment check failed |
-| `environment_check_expired` | the environment verdict aged out |
-| `environment_check_hash_mismatch` | the environment changed since the verdict |
-| `scope_overlap` | its declared file scope intersects a ticket in flight (implement only; enforced once a team activates a scope policy) |
-| `waiting_on` | a merge-gate failure with no remediable cause holds the card at PR |
-| `branch_missing` | the ticket branch has never been seen |
-| `branch_gone` | the ticket branch was deleted |
-| `pr_merged` | its PR merged and no other PR is open |
-| `no_change_hold` | a remediate round changed nothing; a human comment or a new push releases it |
-| `validate_class_spent` | this validate failure already spent its one repair round |
-| `stale_failure_episode` | the ladder advanced after the failure, so the round would repair a phase already passed |
-| `runner_image_breaker` | fleet-wide: the live runner image fails every phase at startup; clears when the pin moves |
-| `no_branch_to_remediate` | a remediate round is queued on a ticket with no branch |
-| `retry_backoff` | retrying in place, waiting out its 2/5/15-minute rung |
-| `routing_unavailable` | claimed then refused at kickoff: no route, no eligible slot, or the provider is unavailable; the detail names which |
-| `repo_paused` | an operator paused the repository |
-| `wip_limit` | the project is at its WIP limit (see above): its tickets in progress are waiting, and this new start waits until one of them finishes |
-| `remediate_parked` | the remediate phase is parked, so the failing phase has nowhere to be repaired; `catalyst-skills release <ticket>` releases the park once its cause is fixed |
-| `phase_parked` | the offered phase is parked after repeated failures or a spent repair-round cap; the person releases it once its cause is fixed |
-| `later_phase_lease_held` | an earlier phase is offered while a live container still holds a later phase of this ticket |
-| `human_owned_pr` | a person's own pull request holds this ticket; that person closes or merges the PR themselves, and no release command clears it |
-| `review_not_converging` | review and repair kept finding new problems without converging |
-| `round_threshold` | the ticket spent its lifetime repair budget |
-| `claim_storm` | claimed too many times in the last hour; it waits the hour out, and there is nothing to release |
-| `repo_at_capacity` | the repository's runner seats are all in use; it starts when one frees |
-
-## The unknowns (the evaluator fails closed)
-
-When the cloud cannot answer, it says so rather than guessing: `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`, `branch_snapshot_unknown`. An unknown is "I could not look", never "it is not there"; report it as inconclusive. The exception is a team with no saved stage mapping: `workflow_mapping_unknown` never clears on its own there, `explain` names the missing stages, and the fix is a tenant owner or admin mapping the team.
-
-One advisory gates nothing: `human_addressed_unlabeled_ask_suspect` (assigned to a human with no delegate; possibly an unlabelled ask).
-
-## The three levers a human has
-
-1. **Priority** on the ticket reorders the queue.
-2. **The dispatch column**: moving a card into the dispatch slot dispatches it; moving it to the team's backlog-type state parks it and stops rounds.
-3. **Holds**: the hold labels on the pull request (from the contract's `merge.prLabels`) keep a green PR out of the merge queue; a human comment on the ticket clears the validate hold and the no-change hold.

package/skills/how-catalyst-works/references/when-a-phase-fails.md

@@ -1,57 +0,0 @@
-# When a phase fails: four layers, in order
-
-This reference restates the mechanism, which does not vary per tenant. The numbers quoted are the fleet defaults; the live values are served on the contract under `thresholds` and `node scripts/show-my-map.mjs` prints them. Quote the printed values, not these.
-
-A failed phase writes no board state on its own: the ticket stays at its current stage, retryable. What happens next is decided by four stacked layers.
-
-## Layer 1: retry in place
-
-Some failures are not the ticket's fault, so the SAME phase is simply re-offered and no remediation round is minted:
-
-- the phase failed before any branch existed (research, plan or implement on a ticket whose own record shows no branch);
-- an infrastructure failure at any phase: a vendor 5xx, a dropped stream, a refused setup, an environment gap, a phase timeout, an unwritable workspace.
-
-Nothing is written for the retry; the ordinary dispatch path re-offers the phase. A remediation round on a branchless ticket could only fail to find the branch while spending a counted attempt, which is why this layer exists.
-
-## Layer 2: backoff
-
-Every retry-in-place, and a routing refusal at kickoff, waits out a rung of a backoff ladder before the phase is re-offered: 2 minutes, then 5, then 15, indexed by the consecutive-failure count and clamped at the last rung. While waiting, the eligibility explainer shows `retry_backoff` (or `routing_unavailable` with a kickoff detail). `node scripts/explain-ticket.mjs <ticket>` prints it. The live ladder is `thresholds.retryBackoffMs`.
-
-## Layer 3: move to Remediate
-
-Any failure that is not retry-in-place moves the card to the team's remediate stage and queues a remediation round. The round is an interrupt phase (`remediate`) that repairs what failed; when a round succeeds, the card restores to its exact pre-failure stage. A team with no remediate stage mapped gets the hold label from `teams[].labels.hold` instead of a state move.
-
-Rounds are capped: after `thresholds.remediateRoundCap` rounds (default 3) in one failure episode, no further round is queued. A remediation round that itself fails never queues another round. A round that changes nothing puts the ticket on a no-change hold, released by a human comment on the ticket or a new push, never by a clock. A validate failure with the same fingerprint spends only one repair round per episode.
-
-Two structural cases the round machinery refuses: a `remediate` round is never offered on a ticket with no recorded branch (`no_branch_to_remediate`), and one dispatched anyway is cancelled at the clone.
-
-## Layer 4: park
-
-After `thresholds.parkAfterConsecutiveFailures` consecutive failures (default 3) the phase is parked. A parked phase shows as `cooling_down` in the explainer; the ticket's `remediate` phase being parked shows as `remediate_parked`.
-
-Which parks release themselves:
-
-| Park | Releases by |
-| -- | -- |
-| repeated failure | a release from the person's own login once its cause is fixed (`catalyst-skills release`), not a clock |
-| remediate round cap reached | the same release, which buys one more round, not a clock |
-| missing branch | its own budgeted release loop |
-| rebase conflict | its own budgeted release loop |
-
-A person's own key releases a park, and every other hold that a retry can fix, in one step: `catalyst-skills release <ticket> --because <what changed>`. The cloud releases every governor holding the ticket or releases nothing and names what a person must do instead (a person's own pull request, a review that will not converge, the lifetime repair budget). It refuses a cause it cannot see change unless the caller says what changed. The `unstick` skill runs that loop. When a ticket is parked, name the failure class the explainer shows and whether its cause is fixed.
-
-## Two holds that are not failures
-
-- **Validate budget hold**: a validate failure that has spent its repair round holds the card; a human comment on the ticket clears it.
-- **Runner image breaker**: fleet-wide, not per ticket. When three distinct tickets fail the same startup class on the live runner image, dispatch pauses for the affected tickets, one anomaly alert is raised per tenant, and dispatch resumes automatically when the image pin moves. The explainer shows `runner_image_breaker`. Never escalate this one ticket at a time.
-
-## What a human sees on the ticket
-
-Each attempt posts a phase-outcome comment (complete or FAILED, with phase, attempt, artifact, a summary and any park or hold block) and each remediation round posts a remediate-attempt comment naming the failure class it is repairing. `catalyst-linear` describes the shapes. The attempt ledger, the round count against the cap and the park history are readable: `catalyst-skills explain --history <ticket>` prints them from the cloud's own relay ledger.
-
-## Rule of thumb for answering "why is it stuck?"
-
-1. Run `node scripts/explain-ticket.mjs <ticket>`; the reason names the layer.
-2. `retry_backoff` or `routing_unavailable`: wait; it retries itself. Say when.
-3. `cooling_down`, `remediate_parked`, `no_change_hold`, `validate_class_spent`: name what releases it (a release once the cause is fixed, a comment, a push) and who can do that.
-4. A system-level cause (provider down, runner image breaker, repo paused) is ONE alert, never a per-ticket escalation.

package/skills/how-catalyst-works/scripts/explain-ticket.mjs

@@ -1,41 +0,0 @@
-#!/usr/bin/env node
-// explain-ticket.mjs — why one ticket is, or is not, about to run: the cloud's own eligibility row
-// for it, rendered as one paragraph, plus the raw row so the failure block is not lost.
-import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
-
-const HELP = `Usage: node scripts/explain-ticket.mjs <ticket> [--json]
-
-Asks Catalyst Cloud for the ticket's eligibility row (position, status, the exclusion reason in plain
-English, the last failure, advisories) and prints it as one paragraph. Wraps: catalyst-skills explain.
-
-  <ticket>   the Linear identifier, e.g. KEY-123
-  --json     print the CLI's JSON document instead of the paragraph
-
-Exit 0 explained (even when the ticket is excluded), 1 when the ticket is unknown to the mirror or
-a usage error, 2 when this machine is not connected to a tenant or the cloud refused the read
-(the line says which).`;
-
-const argv = process.argv.slice(2);
-if (wantsHelp(argv)) {
-  console.log(HELP);
-  process.exit(0);
-}
-const { flags, positionals } = parseFlags(argv, { bool: ["json"] });
-const ticket = positionals[0];
-if (!ticket) usage("explain-ticket needs a ticket identifier (see --help)");
-
-const r = runCli(["explain", ticket, "--json"]);
-exitOnFailure(r);
-relayStderr(r);
-const doc = parseJson(r.stdout);
-if (!doc || typeof doc.explanation !== "string") {
-  console.log(r.stdout.trimEnd());
-  process.exit(1);
-}
-if (flags.json) {
-  console.log(JSON.stringify(doc));
-} else {
-  console.log(doc.explanation);
-  if (doc.row) console.log(`row: ${JSON.stringify(doc.row)}`);
-}
-process.exit(doc.row ? 0 : 1);

package/skills/how-catalyst-works/scripts/lib/cli.mjs

@@ -1,164 +0,0 @@
-#!/usr/bin/env node
-// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: it spawns the catalyst-skills CLI
-// this machine connected with (the path recorded in customer.json, else npx) and hands back its
-// output. Scripts import it; a person runs it with --help to see what it does. No dependencies.
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
-import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
-
-export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = CONNECT_COMMAND;
-
-/** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME (used by tests) over 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 config, or a one-line reason it could not be read. Never throws. */
-export function loadConfig() {
-  const path = configPath();
-  if (!existsSync(path)) return { ok: false, reason: `no config at ${path}` };
-  try {
-    const cfg = JSON.parse(readFileSync(path, "utf8"));
-    if (!hasCredential(cfg) || typeof cfg.account !== "string") {
-      return { ok: false, reason: `${path} is missing a key or login, or the account` };
-    }
-    return { ok: true, cfg, path };
-  } catch (err) {
-    return { ok: false, reason: `${path} is unreadable: ${err instanceof Error ? err.message : String(err)}` };
-  }
-}
-
-/** Exit 2 with the one line every script prints when this machine is not connected to a tenant. */
-export function notConfigured(reason) {
-  console.error(`not connected to a Catalyst Cloud tenant (${reason}) — run: ${CONNECT_HINT}`);
-  process.exit(2);
-}
-
-/**
- * Run one catalyst-skills verb. Returns { code, stdout, stderr }. The CLI is `node <cliPath>` when
- * the config recorded one that still exists, else `npx @catalyst-cloud/catalyst-skills`.
- * Exits 2 (not configured) before spawning anything when the config is absent or unreadable.
- */
-export function runCli(args, { stdin } = {}) {
-  const loaded = loadConfig();
-  if (!loaded.ok) notConfigured(loaded.reason);
-  const { cfg } = loaded;
-  let cmd;
-  let argv;
-  let shell = false;
-  if (typeof cfg.cliPath === "string" && existsSync(cfg.cliPath)) {
-    cmd = process.execPath;
-    argv = [cfg.cliPath, ...args];
-  } else {
-    cmd = process.platform === "win32" ? "npx.cmd" : "npx";
-    argv = [PACKAGE, ...args];
-    shell = process.platform === "win32";
-  }
-  const r = spawnSync(cmd, argv, {
-    encoding: "utf8",
-    input: stdin,
-    env: process.env,
-    shell,
-    maxBuffer: 64 * 1024 * 1024,
-  });
-  if (r.error) {
-    console.error(`could not run ${cmd}: ${r.error.message} — re-run ${CONNECT_HINT} to record the CLI path`);
-    process.exit(2);
-  }
-  return { code: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
-}
-
-/** Print the CLI's stderr (the source line, the contract line, any refusal) on our stderr. */
-export function relayStderr(r) {
-  const text = r.stderr.trimEnd();
-  if (text) console.error(text);
-}
-
-/** A non-zero CLI result ends the script with the same code, its stdout shown so nothing is lost. */
-export function exitOnFailure(r) {
-  if (r.code === 0) return;
-  relayStderr(r);
-  const out = r.stdout.trimEnd();
-  if (out) console.log(out);
-  process.exit(r.code);
-}
-
-export function parseJson(text) {
-  try {
-    return JSON.parse(text.trim());
-  } catch {
-    return null;
-  }
-}
-
-/**
- * A small flag parser: `spec.value` names flags that take a value, `spec.bool` boolean flags,
- * `spec.repeat` value flags that may repeat (collected into arrays). Unknown flags are a usage error.
- */
-export function parseFlags(argv, spec = {}) {
-  const value = new Set(spec.value ?? []);
-  const bool = new Set(spec.bool ?? []);
-  const repeat = new Set(spec.repeat ?? []);
-  const flags = {};
-  const positionals = [];
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--") {
-      positionals.push(...argv.slice(i + 1));
-      break;
-    }
-    if (!a.startsWith("--")) {
-      positionals.push(a);
-      continue;
-    }
-    let name = a.slice(2);
-    let inline;
-    const eq = name.indexOf("=");
-    if (eq !== -1) {
-      inline = name.slice(eq + 1);
-      name = name.slice(0, eq);
-    }
-    if (bool.has(name)) {
-      flags[name] = true;
-    } else if (value.has(name) || repeat.has(name)) {
-      const v = inline ?? argv[++i];
-      if (v === undefined || v === "") usage(`--${name} needs a value`);
-      if (repeat.has(name)) (flags[name] ??= []).push(v);
-      else flags[name] = v;
-    } else {
-      usage(`unknown option --${name}`);
-    }
-  }
-  return { flags, positionals };
-}
-
-export function usage(message) {
-  console.error(message);
-  process.exit(1);
-}
-
-export function wantsHelp(argv) {
-  return argv.includes("--help") || argv.includes("-h");
-}
-
-const runDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (runDirectly) {
-  if (wantsHelp(process.argv.slice(2)) || process.argv.length <= 2) {
-    console.log(
-      [
-        "lib/cli.mjs — shared helper for this skill's scripts (not a command of its own)",
-        "",
-        "Reads ~/.config/catalyst-cloud/customer.json and runs the catalyst-skills CLI recorded there",
-        `(or npx ${PACKAGE} when no path is recorded). Exit 2 when the machine is not connected.`,
-        "",
-        `Connect first with: ${CONNECT_HINT}`,
-        `Config in use: ${configPath()}`,
-      ].join("\n"),
-    );
-    process.exit(0);
-  }
-}

package/skills/how-catalyst-works/scripts/lib/credential.mjs

@@ -1,29 +0,0 @@
-#!/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/how-catalyst-works/scripts/whats-running.mjs

@@ -1,65 +0,0 @@
-#!/usr/bin/env node
-// whats-running.mjs — what Catalyst is executing right now (fleet activity, the agent roster, lease
-// attributions), optionally the dispatch queue and the coding-account line.
-import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, wantsHelp } from "./lib/cli.mjs";
-
-const HELP = `Usage: node scripts/whats-running.mjs [--queue] [--accounts] [--team <key>] [--json]
-
-Prints what is executing on your tenant. Wraps: catalyst-skills running, queue, accounts.
-
-  --queue        also print the dispatch queue (what runs next, in order)
-  --team <key>   with --queue: one team's queue
-  --accounts     also print the coding-account line (provider, state, windows — never a credential)
-  --json         one JSON document: { running, queue?, accounts? }
-  --help         this text
-
-Exit 0, 1 on a usage error, 2 when this machine is not connected to a tenant or the cloud refused
-a read (the line says which).`;
-
-const argv = process.argv.slice(2);
-if (wantsHelp(argv)) {
-  console.log(HELP);
-  process.exit(0);
-}
-const { flags } = parseFlags(argv, { bool: ["queue", "accounts", "json"], value: ["team"] });
-
-const out = {};
-const running = runCli(["running", "--json"]);
-exitOnFailure(running);
-relayStderr(running);
-out.running = parseJson(running.stdout) ?? running.stdout.trimEnd();
-
-if (flags.queue) {
-  const args = ["queue", "--json"];
-  if (flags.team) args.push("--team", flags.team);
-  const queue = runCli(args);
-  exitOnFailure(queue);
-  relayStderr(queue);
-  out.queue = parseJson(queue.stdout) ?? queue.stdout.trimEnd();
-}
-
-if (flags.accounts) {
-  const accounts = runCli(["accounts"]);
-  exitOnFailure(accounts);
-  relayStderr(accounts);
-  out.accounts = accounts.stdout.trimEnd();
-}
-
-if (flags.json) {
-  console.log(JSON.stringify(out));
-  process.exit(0);
-}
-
-const section = (title, value) => {
-  console.log(`== ${title}`);
-  console.log(typeof value === "string" ? value : JSON.stringify(value, null, 2));
-};
-if (out.running && typeof out.running === "object") {
-  section("fleet activity", out.running.fleetActivity ?? out.running);
-  if (out.running.agentRoster !== undefined) section("agent roster", out.running.agentRoster);
-  if (out.running.leaseAttributions !== undefined) section("lease attributions", out.running.leaseAttributions);
-} else {
-  section("running", out.running);
-}
-if (out.queue !== undefined) section("dispatch queue", out.queue);
-if (out.accounts !== undefined) section("coding accounts", out.accounts);

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

@@ -1,43 +0,0 @@
-# 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. If it says `wip_limit`, the project is at its WIP limit (tickets in progress, counting blocked, parked and waiting ones, not containers): the work in progress is what is waiting, so read that column, not this one.
-- **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

@@ -1,37 +0,0 @@
-# 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 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.
-
-## 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.