@catalyst-cloud/cli 0.8.0

package/skills/run-this-project/references/reacting-to-events.md

@@ -0,0 +1,76 @@
+# Reacting to events
+
+This reference restates invariants of the Catalyst Cloud stream and the `watch` verb. Nothing here varies per tenant; the tenant facts a reaction needs (stage ids, label ids, the ask team) come from `catalyst-skills contract` at the moment you need them.
+
+## The mechanism
+
+A steward never polls. It subscribes once to the tenant stream through the SDK's live client and reacts to each change as it arrives. The verb is `catalyst-skills watch`, and this skill's `scripts/watch-scope.mjs` is that verb with the scope checked up front:
+
+```sh
+node scripts/watch-scope.mjs --project <id>          # every ticket in the project
+node scripts/watch-scope.mjs --team <key>            # every ticket on the team
+node scripts/watch-scope.mjs --ticket ENG-41 --ticket ENG-42
+```
+
+The stream itself is tenant-wide; scope is filtered on this machine from each frame's entity and row, and a row that only carries a ticket reference (a comment, a session, a pull request) is resolved to its project through the ticket's own record, cached for the life of the watch. The cost of an ignored frame is one JSON parse, so a wide scope is fine.
+
+**In Claude Code**, arm a monitor on the command above. Each line it prints is one applied change inside the scope, delivered into your session as an event. React to it in the same turn: read what changed, decide, act, and only then let the turn end.
+
+**In Codex, OpenCode, or any harness without a monitor**, pass `--exec`:
+
+```sh
+node scripts/watch-scope.mjs --project <id> --exec 'node my-reaction.mjs'
+```
+
+The command runs once per frame with the frame on stdin. A non-zero exit is a failed reaction (see the cursor rule). Nothing polls in either shape.
+
+## The frame
+
+One JSON object per line, exactly what the SDK delivers:
+
+```json
+{"type":"change","accountId":"<tenant>","seq":4182,"entity":"comments","entityId":"<id>","op":"upsert","row":{...}}
+```
+
+`seq` is the tenant-wide position. `entity` is one of the mirror's feed tables. `op` is `upsert` or `delete`. `row` is the mirrored row when the op is an upsert; a delete carries the id only. A frame for another tenant is refused by the CLI and never printed.
+
+## Entities that matter to a scope
+
+| entity | what a change means | first reaction |
+| -- | -- | -- |
+| `issues` | a card moved, was retitled, re-prioritised, assigned, or created | if it moved into a stage the cloud owns, note the advance; if it moved out of the ladder by hand, ask why before touching it |
+| `comments` | someone or something wrote on a ticket | a human comment in your scope is answered in-thread by you, tagged; a cloud outcome card (phase complete, phase failed, remediate attempt, board health, merge wait) is your execution signal, read it |
+| `issue_labels`, `labels` | a label was added or removed | an ask label means a question, not work; a hold label means the cloud wants a human; the release label means a human cleared a false positive |
+| `relations` | a blocks relation appeared or went away | a new blocker on your ticket is a dependency to chase; a blocker closing may make a card dispatchable again |
+| `pull_requests`, `pr_events`, `pushes` | the branch and PR state changed | a PR going ready-for-review or merged is a milestone; a force-push after a resolved review thread is worth a look |
+| `check_runs`, `check_suites`, `commit_statuses` | CI moved | red on a required check after the queue label wakes an automatic remediation; you watch, you do not re-run it |
+| `reviews`, `pr_review_threads`, `pr_review_comments` | the reviewer spoke | unresolved threads block the merge; a clean pass is a reaction or a terse comment, not a review object |
+| `agent_sessions`, `agent_activities` | a phase started, wrote an artifact, opened a PR, reported | the plan on the session is the ladder itself; the current phase is the one in progress |
+| `fleet_activity`, `fleet_host_liveness` | a runner picked up or dropped a phase | a phase running is not a stall, whatever the clock says |
+| `fleet_anomalies` | the cloud raised a fleet-level alert | one alert covers every ticket it touches; never escalate it per ticket |
+| `workflow_states`, `team_workflow_mapping` | the tenant's stage map changed | refresh the contract (`catalyst-skills contract --refresh`) before the next state move |
+| `projects`, `cycles`, `initiatives` | your scope's container changed | update the status summary |
+
+Entities not listed still arrive when they are in scope; ignore what you do not need.
+
+## The same-turn rule
+
+A frame is reacted to in the turn it arrives, not batched for a later pass. The reaction is whatever the table above says plus anything the situation obviously needs, and it ends with the one status summary for the scope being current. If a reaction needs a human decision, file the ask through `what-needs-me` before proceeding on the default, in that same turn.
+
+## The cursor rule
+
+The cursor file (`~/.config/catalyst-cloud/watch-cursor.json`, stamped with the tenant) advances only after the reaction returns. A reaction that throws, or an `--exec` command that exits non-zero, leaves the cursor at the last good frame; the CLI closes the socket and the SDK's reconnect replays from that cursor, so the failed frame is offered again. Delivery is therefore at-least-once: make reactions safe to repeat (check before you write, prefer idempotent writes such as a label add over a fresh comment).
+
+Two consequences. First, a crash mid-reaction replays, never loses. Second, a reaction that keeps failing keeps the watch pinned on one frame; fix the reaction rather than skipping the frame, or restart with `--from head` and re-read the scope with `scripts/scope-status.mjs` to catch up on what you missed.
+
+## What to do on resync
+
+When the tenant tells the stream it can no longer replay from your cursor, the CLI prints one line on standard error, `[watch] resync: cursor moved to head <n>`, and continues from the head. No rows are copied. Anything that happened between your old cursor and the head is not replayed, so a resync is your cue to run `scripts/scope-status.mjs` once and reconcile the summary against the live state.
+
+## Starting a watch on an existing project
+
+Start with `--from head` when you are picking up a project that has been running without a steward; the backlog of old frames is not worth replaying, and `scope-status.mjs` gives you the present state in one call. Start from the saved cursor (the default) when you are resuming your own watch after a break, so nothing that happened in between is lost.
+
+## The honest limit
+
+The stream carries the mirror's entity changes. It does not carry the relay ledger's phase failures, parks, remediate rounds or backoff timers as first-class frames. Between frames you learn those from the outcome comments the cloud posts on the ticket, which do arrive as `comments` frames: a phase-failed card names the phase, the attempt and the failure class; a remediate-attempt card names the round; a board-health comment names a stall the cloud itself noticed. For the current verdict on any ticket, ask the explainer: `catalyst-skills explain <ticket>` turns the exclusion reason and the last failure into one paragraph. `catalyst-skills explain --history <ticket>` prints the per-phase attempt ledger, the remediation rounds against the cap, and any park with what releases it.

package/skills/run-this-project/references/stalls-and-escalation.md

@@ -0,0 +1,63 @@
+# Stalls and escalation
+
+The stall thresholds here are **local policy**, set once by the human who owns the tenant and read by `scripts/scope-status.mjs`. They are not cloud values and the cloud does not enforce them; the cloud's own enforcement numbers (retry backoff, the park threshold, the remediate round cap, the write budget) are on the contract and printed by `how-catalyst-works`. The chase order and the escalation rule below are invariants.
+
+## The policy file
+
+`assets/stall-policy.json` ships the defaults: minutes a ticket may sit in each slot with no update and nothing running or leased on it before it counts as stalled. To change them, copy that file to `~/.config/catalyst-cloud/stall-policy.json` and edit it there; the script prefers the local copy and prints which file it used. Pass `--stall-policy <file>` to use another.
+
+Two slots deserve thought when tuning. The dispatch slot's threshold is how long a card may wait to be picked up before you ask why nothing took it; on a busy tenant with a full queue that is capacity, not a stall, and the answer is to wait or re-prioritise. The PR slot's threshold is how long a card may wait for merge evidence; reviews and CI take real time, so set it generously.
+
+## What counts as stuck
+
+A ticket is stuck when all of these hold at once: it is in an active slot (not done, not canceled), nothing is running or leased on it, its last update is older than the slot's threshold, and the eligibility explainer does not name a reason that is simply waiting out a clock. `scope-status.mjs` checks the first three and hands you the fourth as a command to run.
+
+A running phase is never a stall, however long it has run; the cloud's own timeout will fail it and the outcome card will say so. A ticket in retry backoff is waiting out a rung of two, five or fifteen minutes and is not a stall either.
+
+## The chase order
+
+Run `catalyst-skills explain <ticket>` first, and let its reason pick the row:
+
+| the explainer says | what it means | your move |
+| -- | -- | -- |
+| offered, with a position | the queue has it; a runner is the bottleneck | wait; if every ticket waits, it is capacity, see below |
+| lease held, intake lease held | a container has it | not a stall; wait for the outcome card |
+| retry backoff | a pre-branch or infrastructure failure is retrying in place | wait out the rung; three in a row parks it, and then it is a real stall |
+| blocked | a live blocks relation | chase the blocker: is it dispatchable, is it an ask nobody answered, is it done but still open |
+| ask ticket, ask shape suspected | the ticket is a question | route it to `what-needs-me`; if it is really work, a human applies the release label |
+| not at dispatch stage | somebody moved the card, or it never entered | read the card's history; re-dispatch with `make-ready.mjs` if it should run |
+| phase parked, cooling down, remediate parked | the cloud parked it after repeated failure or the round cap | read the last outcome card for the class; once its cause is fixed, the `unstick` skill releases it (`catalyst-skills release <ticket> --because <what changed>`); if the fix is a decision, file an ask |
+| no change hold | a remediate round changed nothing | a human comment on the ticket, or a new push to the branch, releases it; say what should change |
+| validate class spent, stale failure episode | the repair budget for this failure is used, or the ladder moved on | read the outcome cards; usually a decision about the approach, so an ask |
+| waiting on | a merge-gate failure with no automatic repair | read the merge-wait comment and the PR's three legs through `catalyst-github` |
+| branch missing, branch gone, no branch to remediate | the branch the phase needs does not exist | a hand-deleted branch is a human question; a never-created one means implement has not run, so check the earlier phases |
+| environment check required, running, failed, expired, hash mismatch | the repository's environment gate | a repository setting; the tenant admin resolves it in settings, one ask for the repository, not per ticket |
+| scope overlap | another in-flight ticket owns the files | wait for it, or re-order by priority |
+| routing unavailable, no eligible slot, runner image breaker, repo paused | a fleet or provider condition | one fleet note, never per ticket; see below |
+| pr merged, pipeline complete, ticket terminal | it is finished | close the loop in the summary; if the card is not Done a minute after the merge, that is a finding, not a chore |
+
+Where the explainer names a reason not in this table, it prints the raw reason; read it as spelled and consult `how-catalyst-works`.
+
+## Capacity and fleet conditions are one note, not many asks
+
+When several tickets in scope are offered and nothing picks them up, or the explainer names a routing, slot, provider or image condition, the cause is shared: coding-account headroom, a provider outage, a paused repository, a poisoned runner image. Write one line in the status summary naming the condition and the tickets it holds. Do not file an ask per ticket. `catalyst-skills accounts` reads coding-account status (state, usage windows, walls, quarantine); enrolling, pausing or removing an account is the settings page, not you.
+
+## Escalate inward, never outward
+
+The order is instrument, then you (the steward), then the desk (`whats-happening`), then the human, and the human only ever sees an ask. An instrument or a script that pages a human directly is a defect. So is a stall report that reaches the human as a bare label, a board row, or a chat aside with no ask behind it.
+
+Before anything reaches the human, answer three questions:
+
+1. **Can I decide this myself?** Which approach, retry or abandon, rebase or re-cut, re-order two tickets: yours. Decide, record the decision in a bookkeeping note on the ticket, and move on.
+2. **Does this need to block at all?** If a sane default exists, take it, record it, and file the ask anyway so the human can overrule; the work does not wait.
+3. **Who else can move this?** Another steward, the desk, a repository owner. Pulling in a peer is preferred over pulling in the human.
+
+Only a genuine product, priority or approval decision, or an action only a human can physically take (close a person's own pull request, read a review that will not converge, resolve a repository setting, apply the release label, answer a merge policy question), survives to become an ask.
+
+## When a stall becomes an ask
+
+File it through `what-needs-me`, never by hand and never as the human. The ask carries the question as its title, the options, the default that fires if silent, and what it blocks, with the stalled ticket named in the blocks list so the human's inbox ranks it by what it holds. Search for an existing ask about the same decision first and attach the new ticket to it rather than filing a second one; two asks for one decision split its urgency and sink both. Once filed, proceed on the default and say so in the ticket.
+
+## Reply where the message arrived
+
+A human comment inside your scope is answered by you, in that thread, tagged, as the app actor. A question only a human can decide becomes an ask; you do not answer it, and you never post as the human. A bookkeeping record (a state move, a decision you took, a chain summary) carries the contract's bookkeeping marker as a prefix so it wakes nothing; the `--bookkeeping` flag on `catalyst-skills write comment` adds it.

package/skills/run-this-project/scripts/lib/cli.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: by spawning the catalyst-skills
+// CLI. The CLI holds the SDK and the key; this file holds neither. It reads
+// ~/.config/catalyst-cloud/customer.json (under CATALYST_SKILLS_HOME when set, else HOME) for the
+// CLI path that login recorded and falls back to `npx @catalyst-cloud/catalyst-skills`.
+//
+// Exit codes every script built on this file shares: 2 = this machine is not connected, 1 = the
+// script's own check failed, 0 = fine.
+import { spawn } 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_NAME = "@catalyst-cloud/catalyst-skills";
+export const NOT_CONFIGURED_EXIT = 2;
+export const CHECK_FAILED_EXIT = 1;
+
+export function homeDir() {
+  return process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? process.env.USERPROFILE ?? "/";
+}
+
+export function configDir() {
+  return join(homeDir(), ".config", "catalyst-cloud");
+}
+
+export function configPath() {
+  return join(configDir(), "customer.json");
+}
+
+/** The stored config, or null when the file is absent or unreadable. Never throws. */
+export function loadCustomerConfig() {
+  const path = configPath();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!hasCredential(parsed) || typeof parsed.account !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Print the one not-connected line and exit 2. */
+export function requireConfigured() {
+  const cfg = loadCustomerConfig();
+  if (cfg) return cfg;
+  console.error(`not connected: ${configPath()} is missing or unreadable — run: ${CONNECT_COMMAND}`);
+  process.exit(NOT_CONFIGURED_EXIT);
+}
+
+/** The command and argument prefix that reaches the CLI on this machine. */
+export function cliCommand(cfg = loadCustomerConfig()) {
+  if (cfg && typeof cfg.cliPath === "string" && existsSync(cfg.cliPath)) {
+    return { command: process.execPath, prefix: [cfg.cliPath], via: `node ${cfg.cliPath}` };
+  }
+  const npx = process.platform === "win32" ? "npx.cmd" : "npx";
+  return { command: npx, prefix: [PACKAGE_NAME], via: `npx ${PACKAGE_NAME}` };
+}
+
+/**
+ * Run one CLI verb and capture its output. Resolves `{code, stdout, stderr, notConfigured}`;
+ * `notConfigured` is true when the CLI itself said the machine is not connected.
+ */
+export function runCli(args, { stdin } = {}) {
+  const { command, prefix } = cliCommand();
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, [...prefix, ...args], {
+      stdio: [stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+      env: process.env,
+      shell: process.platform === "win32",
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += String(d)));
+    child.stderr.on("data", (d) => (stderr += String(d)));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      resolve({ code: code ?? 1, stdout, stderr, notConfigured: /not (joined|connected)/i.test(stderr) || /not (joined|connected)/i.test(stdout) });
+    });
+    if (stdin !== undefined) child.stdin.end(stdin);
+  });
+}
+
+/**
+ * Run one CLI verb with the terminal attached, so a long-running verb such as `watch` streams
+ * straight through. Resolves with the exit code; SIGINT and SIGTERM are forwarded to the child.
+ */
+export function execCli(args) {
+  const { command, prefix } = cliCommand();
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, [...prefix, ...args], { stdio: "inherit", env: process.env, shell: process.platform === "win32" });
+    const forward = (sig) => () => {
+      try {
+        child.kill(sig);
+      } catch {
+        // already gone
+      }
+    };
+    const onInt = forward("SIGINT");
+    const onTerm = forward("SIGTERM");
+    process.on("SIGINT", onInt);
+    process.on("SIGTERM", onTerm);
+    child.on("error", reject);
+    child.on("close", (code) => {
+      process.off("SIGINT", onInt);
+      process.off("SIGTERM", onTerm);
+      resolve(code ?? 1);
+    });
+  });
+}
+
+/** Parse the CLI's --json output; a parse failure names the first line of what came back. */
+export function parseJson(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    throw new Error(`the CLI did not answer with JSON: ${stdout.split("\n")[0] ?? "(empty)"}`);
+  }
+}
+
+/** Exit 2 with the CLI's own not-connected line when a call reports it; otherwise return the result. */
+export function guard(result) {
+  if (result.notConfigured) {
+    process.stderr.write(result.stderr || result.stdout);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  return result;
+}
+
+/** A tiny flag parser: `--name value`, `--name=value`, `--flag`, repeatable names collected as arrays. */
+export function parseFlags(argv, { values = [], repeat = [], booleans = [] } = {}) {
+  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 value;
+    const eq = name.indexOf("=");
+    if (eq !== -1) {
+      value = name.slice(eq + 1);
+      name = name.slice(0, eq);
+    }
+    if (booleans.includes(name)) {
+      flags[name] = true;
+      continue;
+    }
+    if (!values.includes(name) && !repeat.includes(name)) {
+      console.error(`unknown option: --${name} (try --help)`);
+      process.exit(CHECK_FAILED_EXIT);
+    }
+    if (value === undefined) {
+      value = argv[++i];
+      if (value === undefined) {
+        console.error(`--${name} needs a value`);
+        process.exit(CHECK_FAILED_EXIT);
+      }
+    }
+    if (repeat.includes(name)) flags[name] = [...(flags[name] ?? []), value];
+    else flags[name] = value;
+  }
+  return { flags, positionals };
+}
+
+export function wantsHelp(argv) {
+  return argv.includes("--help") || argv.includes("-h");
+}
+
+const HELP = `lib/cli.mjs — shared helper; not a command.
+
+Resolves the catalyst-skills CLI (the path login recorded in ${configPath()}, else npx ${PACKAGE_NAME})
+and runs one verb for the script that imports it. Run any sibling script with --help instead.`;
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  console.log(HELP);
+  process.exit(0);
+}

package/skills/run-this-project/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/run-this-project/scripts/make-ready.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// make-ready.mjs — the two card moves a steward makes. Dispatch is a move into the team's dispatch
+// slot; parking is a move into the team's backlog-type state, which is not a slot, so the CLI
+// resolves it from the team's live workflow states. Every id comes from the contract or the live
+// state list; nothing here names a stage.
+import { CHECK_FAILED_EXIT, guard, parseFlags, parseJson, requireConfigured, runCli, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/make-ready.mjs <ticket> [--park] [--note <text>] [--json]
+
+Without --park: moves the card into the team's dispatch column, so the cloud offers its next phase.
+With --park:    moves the card into the team's backlog-type state, so nothing further is offered.
+
+Options:
+  --note <text>   also post a bookkeeping comment saying why (prefixed with the contract's marker,
+                  so it wakes nothing)
+  --json          print the CLI's JSON answers instead of the summary lines
+  --help          this text
+
+After a dispatch move the script asks the eligibility explainer about the ticket and prints its
+verdict. A verdict about a stale or unpublished ordering right after a move is normal: the cloud
+re-derives the queue within a pass; ask again in a minute.
+
+Exit codes: 2 not connected; 1 the move was refused (the CLI's reason is printed); 0 moved.`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags, positionals } = parseFlags(argv, { values: ["note"], booleans: ["park", "json"] });
+const ticket = positionals[0];
+if (!ticket || positionals.length !== 1) {
+  console.error("make-ready needs exactly one ticket identifier (see --help)");
+  process.exit(CHECK_FAILED_EXIT);
+}
+requireConfigured();
+
+const moveArgs = flags.park ? ["write", "state", ticket, "--state-type", "backlog"] : ["write", "state", ticket, "--slot", "dispatch"];
+const moved = guard(await runCli([...moveArgs, "--json"]));
+if (moved.code !== 0) {
+  process.stderr.write(moved.stderr || moved.stdout);
+  process.exit(CHECK_FAILED_EXIT);
+}
+const out = { ticket, action: flags.park ? "parked" : "dispatched", move: parseJson(moved.stdout) };
+
+if (flags.note) {
+  const body = `${flags.park ? "parked" : "dispatched"} by run-this-project: ${flags.note}`;
+  const noted = guard(await runCli(["write", "comment", ticket, "--bookkeeping", "--body", body, "--json"]));
+  out.note = noted.code === 0 ? parseJson(noted.stdout) : { failed: (noted.stderr || noted.stdout).trim() };
+}
+
+if (!flags.park) {
+  const explained = guard(await runCli(["explain", ticket, "--json"]));
+  out.eligibility = explained.code === 0 ? parseJson(explained.stdout) : { failed: (explained.stderr || explained.stdout).trim() };
+}
+
+if (flags.json) {
+  console.log(JSON.stringify(out));
+} else {
+  console.log(`${ticket}: ${out.action}`);
+  if (out.note) console.log(out.note.failed ? `note: not posted (${out.note.failed})` : "note: posted as a bookkeeping comment");
+  if (out.eligibility) console.log(out.eligibility.failed ? `eligibility: unknown (${out.eligibility.failed})` : `eligibility: ${out.eligibility.explanation}`);
+}
+process.exit(0);

package/skills/run-this-project/scripts/watch-scope.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// watch-scope.mjs — subscribe to the tenant stream filtered to one scope and pass every in-scope
+// frame through, one JSON line each. This is `catalyst-skills watch` with the scope flags checked
+// up front; the CLI owns the socket, the cursor file, the replay and the reconnects.
+import { CHECK_FAILED_EXIT, execCli, parseFlags, requireConfigured, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/watch-scope.mjs (--project <id> | --team <key> | --ticket <id>...) [options]
+
+Streams one JSON line per change inside the scope: a ticket, a comment, a pull request, a check, a
+review thread, an agent session or a fleet anomaly. Runs until the session ends (Ctrl-C).
+
+Scope (at least one; they combine):
+  --project <id>      every ticket in this Linear project, resolved through the ticket's own record
+  --team <key>        every ticket whose identifier carries this team key
+  --ticket <id>       one ticket (repeatable)
+
+Options:
+  --exec <command>    run this shell command once per frame with the frame on stdin; a non-zero exit
+                      is a failed reaction, so the cursor holds and the frame is offered again
+  --from cursor|head  start from the saved cursor (default) or skip straight to the tenant head
+  --cursor-file <p>   where the cursor lives (default ~/.config/catalyst-cloud/watch-cursor.json)
+  --help              this text
+
+Exit codes: 2 not connected; 1 no scope given; otherwise the CLI's own exit code.
+
+In Claude Code, arm a monitor on this command and react to each line in the same turn. In a harness
+with no monitor, pass --exec so the reaction still happens per frame and nothing polls.`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags, positionals } = parseFlags(argv, {
+  values: ["project", "team", "exec", "from", "cursor-file"],
+  repeat: ["ticket"],
+});
+if (positionals.length > 0) {
+  console.error(`unexpected argument: ${positionals[0]} (scope is given with --project, --team or --ticket)`);
+  process.exit(CHECK_FAILED_EXIT);
+}
+if (!flags.project && !flags.team && !(flags.ticket && flags.ticket.length)) {
+  console.error("watch-scope needs a scope: --project <id>, --team <key> or --ticket <id> (see --help)");
+  process.exit(CHECK_FAILED_EXIT);
+}
+if (flags.from && flags.from !== "cursor" && flags.from !== "head") {
+  console.error("--from must be cursor or head");
+  process.exit(CHECK_FAILED_EXIT);
+}
+requireConfigured();
+
+const args = ["watch"];
+if (flags.project) args.push("--project", flags.project);
+if (flags.team) args.push("--team", flags.team);
+for (const t of flags.ticket ?? []) args.push("--ticket", t);
+if (flags.exec) args.push("--exec", flags.exec);
+if (flags.from) args.push("--from", flags.from);
+if (flags["cursor-file"]) args.push("--cursor-file", flags["cursor-file"]);
+
+const code = await execCli(args);
+process.exit(code);

package/skills/unstick/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: unstick
+description: >-
+  Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst-skills CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
+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 -->
+
+# Unstick
+
+You get one stuck ticket, or one set of tickets stuck for the same reason, moving again. The cloud parks or holds a ticket when retrying would only repeat a failure: after repeated failures, when the repair-round cap is spent, when a repair changed nothing, when the same validate failure recurred. Each of those is a governor. Once its cause is fixed, the person's own key releases it; nothing here needs an operator.
+
+## Run first
+
+Scripts are run, never read. Each prints `--help`; exit 2 means this machine is not connected (run `catalyst-skills login`).
+
+- `node scripts/unstick.mjs <ticket>` — one JSON document: the eligibility explanation, the execution history (every governor holding the ticket with what releases it, and past releases), and a dry-run release showing what a release would clear and refuse. Changes nothing.
+- `node scripts/unstick.mjs <ticket> --because "<what changed>"` — the same, then the real release. Add `--retry-unchanged` only when you can say what changed outside what the cloud can see.
+- `node scripts/unstick.mjs --class <failure-class> --team <key> [--because "<what changed>"]` — the same for every ticket on one team parked under one failure class (at most 25 per call).
+
+The verbs underneath are `catalyst-skills explain <ticket>`, `catalyst-skills explain <ticket> --history` and `catalyst-skills release <ticket> --because <text> [--retry-unchanged] [--dry-run]`.
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| deciding whether to release, what a refusal means, when to ask a person | `references/playbook.md` |
+| what a reason in the explanation means | the `whats-happening` skill's why-is-it-stuck reference, or `how-catalyst-works` |
+| a refusal needs a decision or a person's action | the `what-needs-me` skill |
+| a refusal names a person's pull request or its review | the `catalyst-github` skill |
+
+## Rules
+
+- **Read before you release.** Explain, then history, then a dry run. A release is never the first call.
+- **The cause decides, not the wish to move.** Release when you can name what changed since the ticket was held: a push, a comment that says what to change, an outage that ended, a secret that was rotated, an account that was re-enrolled. Put that sentence in `--because`; it is recorded against your name.
+- **Unchanged means say so.** The cloud refuses a release whose cause it cannot see change. Pass `--retry-unchanged` only with a `--because` that names the change it cannot see. If nothing changed, do not release; say so.
+- **One release per cause.** If the history shows a release for the same failure and nothing has changed since, a second release buys the same failure. Raise an ask instead.
+- **A refusal names its fix.** Do the fix when it is yours to do; everything else is one ask through `what-needs-me`, attached to an existing ask for the same decision. Never close or merge a person's pull request, and never answer an ask as the person.
+- **A shared cause is one note.** Several tickets parked by one outage or one bad image are one class release and one line in your reply, never one ask per ticket.
+- **Their tenant, as them.** Every read and write goes through the CLI and the person's own login. You never name another tenant.

package/skills/unstick/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Unstick"
+  short_description: "Find out why a Catalyst ticket is parked or held and release it once its cause is fixed; asks only for what needs a person"
+  default_prompt: "Use $unstick to find out why <ticket> is stuck and get it moving again."
+policy:
+  allow_implicit_invocation: false

package/skills/unstick/agents/portability.yaml

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

package/skills/unstick/references/playbook.md

@@ -0,0 +1,51 @@
+# The unstick playbook
+
+This reference restates how a person's release of a stuck ticket works and the order you follow. The cloud does the deciding: it reads every governor holding the ticket and either releases all of them or releases nothing and names, for each one it refuses, the action that does fix it. Your job is to read, judge whether the cause is fixed, and say so honestly.
+
+## The order
+
+1. **Why is nothing running?** `catalyst-skills explain <ticket>`. If the reason is not a park or a hold (for example `blocked`, `not_at_dispatch_stage`, an ask, a missing environment check, `scope_overlap`), there is nothing to release: follow the `whats-happening` skill's why-is-it-stuck reference instead and stop here.
+2. **What holds it, and has it been released before?** `catalyst-skills explain <ticket> --history`. Read three things: the "Held by" lines (each governor and what releases it), the last failure (its class and summary), and the "Releases" lines (who released it before, why, and what happened).
+3. **Is the cause fixed?** Decide from evidence, in this order:
+   - a push to the ticket's branch, a comment on the ticket that says what to change, or main moving on since the park: the cloud can see these, and a release goes through;
+   - a change the cloud cannot see (a provider outage that ended, a rotated secret, a re-enrolled coding account, a fixed tenant setting): release with `--retry-unchanged`, and the reason you give names that change;
+   - nothing changed: do not release. Tell the person what failed and what would have to change.
+   If a previous release in the history named the same failure and nothing has changed since, the next release will fail the same way. Do not release again; raise an ask.
+4. **Preview.** `catalyst-skills release <ticket> --dry-run`. It prints what a release would clear and what it would refuse, and changes nothing.
+5. **Release.** `catalyst-skills release <ticket> --because "<the change>"`. Report what it released, verbatim, with the ticket id. A warning line (for example, that a released repair round runs again at the escalated tier and a second cap parks it again) goes in your reply too.
+6. **Act on each refusal.** A refusal is terminal for that attempt: nothing was released. Each names its fix; the table below says who does it.
+
+## What a refusal means and who fixes it
+
+| refusal | what it means | who acts |
+| -- | -- | -- |
+| `cause_unchanged` | nothing the cloud can see changed since it was held | you, if you can name a change it cannot see (`--retry-unchanged` with that `--because`); otherwise nobody should release it yet |
+| `lease_held` | a phase is running on the ticket right now | nobody; wait for the phase's outcome comment, then look again |
+| `branch_still_missing` | the ticket's branch was never pushed | it releases itself when the branch appears; check the earlier phases through `catalyst-linear` |
+| `human_owned_pr` | a person opened the pull request this ticket would work on | that person closes or merges it, or hands it to Catalyst; never close a person's pull request yourself |
+| `review_not_converging` | review and repair kept finding new problems | a person reads the findings (`catalyst-github`) 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 already raised, or pushes a fix; point at that ask, do not raise a second one |
+| `base_revision_lost` | the ticket's base commit is gone | whoever administers the tenant re-pins it; raise one ask |
+| `remediate_cap` | this tenant keeps the repair-round cap for an administrator | whoever administers the tenant; raise one ask |
+| `unknown_park` | a park this bundle does not know | raise one ask with the ticket id and the park name, verbatim |
+| `held_beyond_class` | a class release reached a ticket held by more than that class | release that ticket on its own, from step 1 |
+| `team_changed` (the ticket moved teams during the check) | the release was checked for one team and the ticket is now on another | run the release again |
+
+Raise an ask only through `what-needs-me`, with the stuck ticket in what it blocks, and attach to an existing ask for the same decision rather than filing a second one.
+
+## Several tickets, one cause
+
+When several tickets on one team are parked for the same failure class (the explanation and the history show the same class, typically an outage or a runner problem that has since ended):
+
+1. `catalyst-skills release --class <failure-class> --team <key> --dry-run` to see which tickets it reaches.
+2. `catalyst-skills release --class <failure-class> --team <key> --because "<the change>" --retry-unchanged` when the change is one the cloud cannot see.
+3. Report one line: how many released, which were refused and why, and whether more remain (run it again for the next batch).
+
+A ticket the class release refuses is listed and left alone; take it through the single-ticket order above.
+
+## What a release does not do
+
+- It does not skip a phase or accept work as done; a released phase runs again.
+- It does not reset a lifetime budget. A released repair round still counts toward the ticket's lifetime threshold, and the cloud stops a loop that claims the same unit too often in an hour.
+- It does not move the card. The ticket stays where it is and runs when the cloud next offers it.
+- It is recorded: who released, with which login, why, what it cleared and what it refused. `explain --history` shows it to everyone who reads the ticket.