@catalyst-cloud/cli 0.8.0

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

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

@@ -0,0 +1,41 @@
+#!/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

@@ -0,0 +1,164 @@
+#!/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

@@ -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/how-catalyst-works/scripts/show-my-map.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// show-my-map.mjs — this tenant's stage map, ladder and thresholds, straight from the contract:
+// per team, every slot with the Linear stage it maps to, its type, whether that state still exists
+// and how the mapping was chosen; then the ladder and the live failure thresholds.
+import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/show-my-map.mjs [--team <key>] [--json]
+
+Prints the tenant contract's stage map, ladder and thresholds. Nothing here is guessed: every value is
+read from the contract Catalyst Cloud serves for your tenant. Wraps: catalyst-skills contract --path.
+
+  --team <key>   only this team
+  --json         one JSON document: { slots, teams, ladder, thresholds }
+  --help         this text
+
+A slot marked * is load-bearing: dispatch, intake, pr, done and canceled must be mapped for the
+ladder to move at all; the others are informational. "(unmapped)" means the team has no stage for
+that slot; "(state gone)" means the mapped Linear state no longer exists and needs re-mapping in
+settings.
+
+Exit 0, 1 on a usage error or an unknown team, 2 when this machine is not connected to a tenant or
+the contract could not be read (the line says which).`;
+
+const LOAD_BEARING = new Set(["dispatch", "intake", "pr", "done", "canceled"]);
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags } = parseFlags(argv, { bool: ["json"], value: ["team"] });
+
+function contractPath(path) {
+  const r = runCli(["contract", "--path", path, "--json"]);
+  exitOnFailure(r);
+  const v = parseJson(r.stdout);
+  if (v === null || v === undefined) {
+    relayStderr(r);
+    console.error(`contract --path ${path} returned nothing readable`);
+    process.exit(1);
+  }
+  return { value: v, stderr: r.stderr };
+}
+
+const slotsRead = contractPath("slots");
+if (slotsRead.stderr.trim()) console.error(slotsRead.stderr.trimEnd());
+const slots = slotsRead.value;
+let teams = contractPath("teams").value;
+const ladder = contractPath("ladder").value;
+const thresholds = contractPath("thresholds").value;
+
+if (flags.team) {
+  const want = flags.team.toUpperCase();
+  teams = teams.filter((t) => String(t.key ?? "").toUpperCase() === want);
+  if (teams.length === 0) {
+    console.error(`no team with key ${flags.team} on this tenant's contract`);
+    process.exit(1);
+  }
+}
+
+if (flags.json) {
+  console.log(JSON.stringify({ slots, teams, ladder, thresholds }));
+  process.exit(0);
+}
+
+const pad = (s, n) => String(s).padEnd(n);
+for (const team of teams) {
+  console.log(`== team ${team.key ?? "(no key)"} — ${team.name ?? team.id} — workflow ${team.workflowMode}, git automation ${team.gitAutomation}, readiness ${team.readiness?.status ?? "unknown"}`);
+  console.log(`   ${pad("slot", 12)}${pad("stage", 22)}${pad("type", 12)}${pad("exists", 8)}source`);
+  for (const slot of slots) {
+    const s = team.stages?.[slot];
+    const mark = LOAD_BEARING.has(slot) ? "*" : " ";
+    if (!s) {
+      console.log(`  ${mark}${pad(slot, 12)}(unmapped)`);
+      continue;
+    }
+    const name = s.stateStillExists ? (s.name ?? "(unnamed)") : "(state gone)";
+    console.log(`  ${mark}${pad(slot, 12)}${pad(name, 22)}${pad(s.type ?? "-", 12)}${pad(s.stateStillExists ? "yes" : "NO", 8)}${s.source}`);
+  }
+  const labels = team.labels ?? {};
+  const describe = (list) => (list ?? []).map((l) => `${l.name}${l.preferredId ? "" : " (absent)"}`).join(", ") || "none";
+  console.log(`   labels: ask ${describe(labels.ask)}; hold ${describe(labels.hold)}; release ${describe(labels.release)}`);
+}
+
+console.log("== ladder");
+console.log(`   phases: ${(ladder.phases ?? []).join(" → ")}`);
+console.log(`   keying: ${ladder.keying} (${ladder.keyingScope}); intake ${ladder.intakeEnabled ? "enabled" : "off"}`);
+
+console.log("== thresholds (live, fleet-wide)");
+const minutes = (ms) => `${Math.round(ms / 60000)} min`;
+console.log(`   park after ${thresholds.parkAfterConsecutiveFailures} consecutive failures`);
+console.log(`   remediate round cap ${thresholds.remediateRoundCap} (escalated budget ${thresholds.remediateEscalatedRoundBudget}, rewind budget ${thresholds.remediateRewindBudget})`);
+console.log(`   retry backoff ${(thresholds.retryBackoffMs ?? []).map(minutes).join(", ")}`);
+console.log(`   write budget ${thresholds.hostDailyWriteBudget} per host per day`);

package/skills/how-catalyst-works/scripts/whats-running.mjs

@@ -0,0 +1,65 @@
+#!/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/run-this-project/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: run-this-project
+description: >-
+  Own one Catalyst Cloud project end to end until it closes. Use when the person says "run this project for me", "own this until it ships", "keep this moving", or hands you a project id or a set of tickets to drive. Subscribes to the tenant stream for the scope through the catalyst-skills CLI, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Writes to Linear as the app actor; never polls.
+disable-model-invocation: true
+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 -->
+
+# Run this project
+
+You are the steward: the single-threaded owner of ONE project or ticket set, from now until it closes. The person says "run this project for me" and hands you a scope. Catalyst does the phases; you make work ready and visible, react to what happens, unblock, and keep one status summary the person can read. You hold no authority over other stewards and you are not the desk; `whats-happening` is the desk.
+
+## Run first
+
+Scripts are run, never read. Each prints its own `--help`.
+
+1. `node scripts/scope-status.mjs --project <id>` (or `--team <key>`): tickets by stage in the contract's order, what is running and queued in scope, and stalls against the local policy. Run it once to take the scope, and again after any resync.
+2. `node scripts/watch-scope.mjs --project <id>`: the subscription. In Claude Code, arm a monitor on it and react to each printed line in the same turn. In a harness with no monitor, add `--exec <command>` so a reaction still runs per frame.
+3. `node scripts/make-ready.mjs <ticket>` to dispatch; `--park` to stop; `--note <why>` to record it.
+4. `catalyst-skills explain <ticket>` whenever a ticket is not moving: one paragraph naming the reason and what releases it.
+
+Every script exits 2 when this machine is not connected (run `catalyst-skills login`), 1 when its own check fails.
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| arming the watch, deciding what a frame means, a reaction failed, a resync line printed | `references/reacting-to-events.md` |
+| dispatching or parking a ticket, judging whether a phase actually ran, writing a ticket for Catalyst | `references/making-work-ready.md` |
+| something is not moving, tuning the stall policy, deciding whether a human needs to hear about it | `references/stalls-and-escalation.md` |
+| the exclusion vocabulary in depth, the ladder, this team's stage map | the `how-catalyst-works` skill |
+| raising or settling a decision | the `what-needs-me` skill |
+| a PR's checks, review and merge legs | the `catalyst-github` skill |
+
+## Rules
+
+- **React, never poll.** A loop that re-reads the API or the replica is a defect. The stream and the cursor file are the mechanism; a reaction that throws leaves the cursor so the frame is offered again.
+- **Dispatch is a card move.** The cloud takes work from the dispatch column and writes every later stage itself. Your two moves are into dispatch and into the backlog; never hand-move a card into a ladder stage.
+- **Evidence a phase ran is the outcome comment, the attached document and the agent session,** not the clock and not the card's column.
+- **Tenant facts come from the contract, live.** Never restate a stage name, label id, team id, threshold or template in prose; run `catalyst-skills contract --path <a.b.c>` when you need one.
+- **Escalate inward.** Instrument, then you, then the desk, then the human as an ask filed through `what-needs-me` with what it blocks. Decide the technical calls yourself; take the sane default and record it; a fleet or provider condition is one note, never one ask per ticket.
+- **Reply where the message arrived,** in-thread, tagged, as the app actor. Never post as the human, never answer someone else's ask. Bookkeeping records take the contract's marker (`catalyst-skills write comment --bookkeeping`).
+- **One status summary,** kept current after every reaction: in flight, blocked and on whom, closed, next, each line with a ticket id. Where a human decision is pending, the line carries the ask's id.
+- **Say what a key cannot see.** PR labels and reactions are not mirrored; the CLI says so by name and points at settings. A park or hold is released from the person's own login once its cause is fixed, through the `unstick` skill (`catalyst-skills release`). Execution history (`explain --history`) and coding-account status (`accounts`) ARE readable — read them rather than reconstructing them from comments.

package/skills/run-this-project/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Run this project"
+  short_description: "Own one Catalyst project end to end: react to its events, make tickets ready, chase stalls, escalate inward"
+  default_prompt: "Use $run-this-project to run project <id> for me until it closes."
+policy:
+  allow_implicit_invocation: false

package/skills/run-this-project/agents/portability.yaml

@@ -0,0 +1,5 @@
+identity: { pack: catalyst-cloud-skills, skill: run-this-project }
+effects: [external-write]
+mutating: true
+invocation: explicit
+exposure: [catalog]

package/skills/run-this-project/assets/stall-policy.json

@@ -0,0 +1,15 @@
+{
+  "$comment": "Stall thresholds in minutes, per workflow slot, for scope-status.mjs. This is local policy a human sets once, not a cloud value: copy this file to ~/.config/catalyst-cloud/stall-policy.json and edit it there. A ticket counts as stalled when it has sat in a slot longer than the threshold with no update and nothing running or leased on it. 'dispatch' is how long a card may wait in the dispatch column before you ask why nothing picked it up; 'pr' is how long a card may wait for merge evidence; 'default' covers any slot not named.",
+  "minutes": {
+    "dispatch": 60,
+    "intake": 60,
+    "research": 90,
+    "plan": 90,
+    "implement": 120,
+    "remediate": 120,
+    "verify": 90,
+    "review": 90,
+    "pr": 240,
+    "default": 120
+  }
+}

package/skills/run-this-project/references/making-work-ready.md

@@ -0,0 +1,60 @@
+# Making work ready
+
+This reference restates invariants of how Catalyst takes work. The tenant's own values (which Linear state is the dispatch column, which state is the backlog, the ask and release label ids, the round cap and the park threshold) are read live from `catalyst-skills contract`; the scripts here never name a stage.
+
+## The steward's two moves
+
+Catalyst does not take work by being asked. It takes work by finding a card in the team's dispatch column and offering that card's next phase to a runner. So the steward's dispatch verb is a card move, and its stop verb is a card move:
+
+```sh
+node scripts/make-ready.mjs ENG-41            # move into the dispatch column; the cloud offers the next phase
+node scripts/make-ready.mjs ENG-41 --park     # move into the team's backlog-type state; nothing further is offered
+node scripts/make-ready.mjs ENG-41 --park --note "waiting on the vendor's API change"
+```
+
+Dispatch resolves the dispatch slot on the ticket's team from the contract. Parking resolves the team's first backlog-type state from its live workflow states, because the backlog is deliberately not one of the eleven slots. Those are the only two state moves you make. Every other stage move on a ticket in the ladder is the cloud's, written when a phase completes; moving a card forward by hand does not run a phase, it only confuses the advance table, and moving it backwards by hand does not undo one.
+
+## What a dispatchable ticket carries
+
+Before the move, the ticket needs, in the record itself:
+
+- A title that states the outcome. A phase agent reads the ticket, not your chat.
+- A description that says what done looks like: the behaviour, the constraints, the files or surfaces if you know them, acceptance criteria a validate phase can check.
+- The right team. The team key is the ticket prefix, and the team's stage map and labels are what the cloud will use.
+- A priority. Queue order inside a team is priority first, then creation time, then identifier, so an unset priority sorts last.
+- No live blocking relation. A ticket with an open blocker is excluded as `blocked` until the blocker closes.
+- No ask on it. A ticket that carries the ask label, or whose own text reads as a decision request (an ask-shaped title, lettered options, a "default if silent" line), is excluded as a question rather than work. If a real ticket trips the shape detector, a human applies the release label named in the contract's vocabulary; you can also rewrite the text so it reads as work.
+- Declared scope when the team enforces it: a ticket whose declared files overlap a ticket already in flight is held as `scope_overlap` for the implement phase.
+
+A ticket does not need a branch, a PR, or any artifact to be dispatched: the ladder creates those. A ticket that has never entered the ladder starts at intake when the tenant enables it, otherwise at research.
+
+## After the move
+
+`make-ready.mjs` asks the eligibility explainer as soon as the move lands and prints the verdict. Read it as follows:
+
+- `offered` or `eligible` with a queue position: done; a runner will pick it up in the next dispatch pass, ordered by priority, then age, then identifier, with tickets already mid-ladder ahead of fresh ones.
+- An ordering that is stale or never published: the cloud re-derives the team's queue within a pass of the move; ask again in a minute with `catalyst-skills explain <ticket>`.
+- Any other exclusion reason: the paragraph names it and what releases it. The reasons and what unblocks each are in `how-catalyst-works` and in `whats-happening`'s "why is it stuck" reference.
+
+## Evidence a phase ran
+
+Do not infer progress from time passing. A phase leaves three kinds of evidence on the ticket, and a card move alone is not one of them:
+
+1. **The outcome comment.** The cloud posts a card per phase: a completed phase names the phase, the attempt, and its artifact; a failed phase names the phase, the attempt, and the failure class, and may carry a park or hold block. A remediate round posts its own attempt card with the round number and the class it is repairing. These arrive as comment frames on the watch.
+2. **The attachment and document.** Each artifact-bearing phase (research, plan, implement, validate, pr, remediate) is projected to a Linear document titled with the ticket, the phase, the attempt and the date, attached to the ticket, with a short link comment. Research and plan on a ticket with a project also appear as a project link.
+3. **The agent session.** The ticket's agent session carries the ladder as its plan, with the phases before the current one completed, the current one in progress, and the rest pending; its activities are the phase start, the gate, artifacts written, the PR opened, and the report.
+
+The card's stage is the fourth, weakest signal: a completed phase moves the card to the stage the advance table names, a failed phase writes no stage at all, and Done is written only when the pull request actually merges, by the merge webhook, never by a phase. A card sitting in a stage tells you which phase last finished, not whether the next one is running; `scripts/scope-status.mjs` shows running and leased phases beside the stage for exactly that reason.
+
+## Parking, and what it does not do
+
+Parking is the lever that stops the cloud offering more rounds on a ticket: moved out of the dispatch column and the ladder's stages, the ticket is excluded at the next offer. It does not kill a phase that is already running under a lease; that container finishes its phase, posts its outcome, and the next offer finds the card parked. If you park a ticket the cloud has itself parked (three consecutive failures, or the remediate round cap), record why in a bookkeeping note. Releasing a cloud park is not a card move: once its cause is fixed, the `unstick` skill releases it with `catalyst-skills release <ticket>`, and only a refusal that names a person's action becomes an ask.
+
+Un-parking is the same dispatch move again. The counted attempts and rounds do not reset when a card comes back; the contract's thresholds say how many remain.
+
+## What you never do to make work ready
+
+- Never move a card into a research, plan, implement, validate, PR, done or canceled stage by hand to "skip ahead". The cloud reads those stages as the record of what ran.
+- Never remove an ask label or apply the release label yourself; a human decides whether a ticket is a question.
+- Never dispatch two tickets that touch the same files at once; serialise them or let the second one wait as `scope_overlap`.
+- Never dispatch a ticket you have not read in full.