@catalyst-cloud/cli 0.9.5 → 0.13.1

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 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.