@catalyst-cloud/catalyst-skills 0.7.0 → 0.8.0

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

@@ -1,62 +0,0 @@
-# Why is it stuck
-
-This reference restates an invariant: the vocabulary the cloud's eligibility explainer uses when nothing is offered for a ticket, translated for a person, with what releases each. `node scripts/explain.mjs <ticket>` prints the reason for one ticket; this table turns it into the next action. The `how-catalyst-works` skill carries the mechanism behind each row.
-
-## How to read a reason
-
-`explain` prints one paragraph: the queue position (or none), the status, the reason, a detail or marker when the cloud gave one, the last failure, and any advisories. Match the reason to a row below. "Releases itself" means the cloud clears it with no human action; "needs" names who acts. When a reason is not in this table, `explain` prints it as the cloud spelled it; report it verbatim and say the bundle does not know it.
-
-## Reasons that release themselves
-
-| reason | what it means | how it clears |
-| -- | -- | -- |
-| `retry_backoff` | the failed phase is retrying in place and waiting out its rung | a clock; the rungs are the contract's `thresholds.retryBackoffMs` |
-| `lease_held` | a live container already holds this phase | the phase finishes |
-| `intake_lease_held` | a later phase is offered while an intake container still holds the ticket | intake finishes |
-| `environment_check_running` | the repository's environment check is in flight | the check finishes |
-| `runner_image_breaker` | fleet-wide: the live runner image fails every phase at startup, so dispatch is held rather than parking tickets | the cloud moves the pin; one alert per tenant, no per-ticket action |
-| `routing_unavailable` | claimed, then refused at kickoff: no route, no eligible coding-account slot, or the provider is unavailable | provider recovery or a slot freeing; if it persists, the tenant admin checks coding accounts in settings |
-| `cooling_down` (with a named callback) | the phase is parked on a condition the cloud watches | the callback fires; the `detail` names it |
-
-## Reasons that need a human
-
-| reason | what it means | who acts and how |
-| -- | -- | -- |
-| `ask_ticket` | it carries an ask label; a question is never work | the human answers the ask (`what-needs-me`) |
-| `ask_shape_suspected` | its own text reads as a decision request though it carries no ask label | the human either answers it as an ask or applies the release label the contract names |
-| `blocked` | a live blocking relation holds it | whoever owns the blocker closes it; if the blocker is an ask, that is the human |
-| `not_at_dispatch_stage` | the card is not in the team's dispatch column | someone moves the card to the dispatch slot (`references/reprioritising.md`) |
-| `not_at_pr_stage` | merge is next but the card is not in the PR column | the card returns to the pr slot; an automation that bounced it should be found |
-| `no_change_hold` | a repair round changed nothing | a human comment on the ticket, or a new push to the branch |
-| `waiting_on` | a merge-gate failure with no cause the cloud can repair | read the merge-wait comment on the ticket; usually a hold label or a review a person must give (`catalyst-github`) |
-| `externally_claimed` | a worker outside the cloud holds it | that worker, or the human removes the local-lane label |
-| `environment_check_required` / `_failed` / `_expired` / `_hash_mismatch` | the repository's environment gate has not passed | the tenant admin runs or fixes the environment check in settings |
-| `repo_paused` | an operator paused the repository | the operator resumes it |
-| `scope_overlap` | its declared file scope intersects a ticket already in flight | wait for the other ticket, or the human decides which goes first |
-
-## Reasons a release clears once the cause is fixed
-
-These do not release themselves, and nobody but the person needs to act: once the recorded cause is fixed, the person's own login releases them with `catalyst-skills release <ticket>`. The desk does not release; route the ticket to the `unstick` skill, which reads the history, previews the release and runs it, or names what a person must do first.
-
-| reason | what it means | note |
-| -- | -- | -- |
-| `phase_parked` / `cooling_down` (parked after repeated failures, or the round cap was spent) | the phase is parked and does not release itself | `unstick`; `explain --history` names the park and the failure class it recorded |
-| `remediate_parked` | the repair phase itself is parked, so the failing phase has nowhere to be repaired | as above |
-| `validate_class_spent` | this validate failure already spent its one repair round in this episode | a push or a comment saying what to change releases it on its own; otherwise `unstick` |
-| `human_owned_pr` | a person's own pull request holds the ticket | that person closes or merges it; no release clears it |
-| `review_not_converging` | review and repair kept finding new problems without converging | a person reads the findings and comments on the ticket to resume; raise an ask for that read |
-| `round_threshold` | the ticket spent its lifetime repair budget | a person answers the ask the cloud raised, or pushes a fix |
-| `no_branch_to_remediate` / `branch_missing` / `branch_gone` | a branch-dependent phase has no branch to clone | the cloud releases missing-branch parks on its own budget; a deleted branch needs a human to decide |
-| `stale_failure_episode` | the ladder advanced after the recorded failure | informational; the round is dropped |
-
-## Reasons that are not problems
-
-`ticket_terminal` (done or canceled), `pipeline_complete` (every phase ran), and `pr_merged` (the PR merged, nothing left to clone) describe finished work. Report them as closed, not blocked.
-
-## When the cloud could not judge
-
-A status of `unknown` with a reason such as `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` or `branch_snapshot_unknown` means the evaluator failed closed rather than guessing. Most clear on the cloud's next pass. `workflow_mapping_unknown`, and `ordering_never_published` beside it, does not clear by itself when the team has no saved stage mapping: `explain` then names the missing stages, and a tenant owner or admin maps the team in Settings → Linear teams. If any other one persists for a team, the readiness checks (`catalyst-setup`) are the next read.
-
-## The one advisory
-
-`human_addressed_unlabeled_ask_suspect` gates nothing: the ticket is assigned to a human with no delegate and may be an unlabelled ask. Mention it in the waiting-on-human block with a question mark.

package/skills/whats-happening/scripts/explain.mjs

@@ -1,28 +0,0 @@
-#!/usr/bin/env node
-// explain.mjs — "why is this ticket stuck?" in one paragraph. A thin wrapper over
-// `catalyst-skills explain <ticket>`, which reads the cloud's eligibility explainer for the ticket's
-// team and translates the exclusion reason, the failure block and any advisories into plain English.
-import { mustRun, parseFlags, printHelp } from "./lib/cli.mjs";
-
-const SPEC = {
-  json: { value: false, help: "print the raw eligibility row and the explanation as JSON" },
-  history: { value: false, help: "ask for the per-ticket execution history (the CLI says when a key cannot see it yet)" },
-};
-
-const { help, flags, positionals } = parseFlags(process.argv.slice(2), SPEC);
-const ticket = positionals[0];
-if (help || !ticket) {
-  printHelp("node scripts/explain.mjs <ticket> [--json] [--history] [--help]", SPEC, [
-    "The ticket is its identifier (the KEY-123 shape). The explanation names the queue position, the status,",
-    "the reason nothing is offered, the last failure, and what releases it; an unknown reason is printed as the",
-    "cloud spelled it. Read references/why-is-it-stuck.md to turn the reason into the next action.",
-  ]);
-  process.exit(help ? 0 : 1);
-}
-
-const args = ["explain", ticket];
-if (flags.history) args.push("--history");
-if (flags.json) args.push("--json");
-const r = mustRun(args);
-process.stdout.write(r.stdout.endsWith("\n") ? r.stdout : `${r.stdout}\n`);
-process.exit(0);

package/skills/whats-happening/scripts/lib/cli.mjs

@@ -1,135 +0,0 @@
-#!/usr/bin/env node
-// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills CLI.
-// The CLI holds the SDK and the key; this file holds neither. It reads customer.json only
-// to learn where the CLI lives, and it exits 2 with one line when the machine is not connected.
-// Run any script beside this one with --help; this file is a library and is never run directly.
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
-
-export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const NOT_CONFIGURED_EXIT = 2;
-
-export function configPath() {
-  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/";
-  return join(home, ".config", "catalyst-cloud", "customer.json");
-}
-
-/** The connected-machine config, or exit 2 with the one line that says how to connect. */
-export function loadConfig() {
-  const path = configPath();
-  if (!existsSync(path)) notConfigured(`no config at ${path}`);
-  try {
-    const cfg = JSON.parse(readFileSync(path, "utf8"));
-    if (!hasCredential(cfg)) notConfigured(`config at ${path} has no key or login`);
-    return cfg;
-  } catch (err) {
-    if (err && err.exitCode === NOT_CONFIGURED_EXIT) throw err;
-    notConfigured(`config at ${path} is unreadable`);
-  }
-}
-
-function notConfigured(why) {
-  process.stderr.write(`not connected (${why}) — run: ${CONNECT_COMMAND}\n`);
-  process.exit(NOT_CONFIGURED_EXIT);
-}
-
-/**
- * Run one catalyst-skills verb and return {code, stdout, stderr}. Uses the CLI path the login
- * recorded when it still exists, else `npx <package>`. A CLI exit of 2 with a "not joined" or
- * "not connected" line is turned into this script's own exit 2, so every caller sees one contract.
- */
-export function runCli(args, opts = {}) {
-  const cfg = loadConfig();
-  const useRecorded = typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
-  const cmd = useRecorded ? process.execPath : "npx";
-  const argv = useRecorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
-  const res = spawnSync(cmd, argv, {
-    input: opts.stdin,
-    encoding: "utf8",
-    maxBuffer: 64 * 1024 * 1024,
-    shell: !useRecorded && process.platform === "win32",
-    env: process.env,
-  });
-  if (res.error) {
-    process.stderr.write(`could not run ${cmd}: ${res.error.message}\n`);
-    process.exit(NOT_CONFIGURED_EXIT);
-  }
-  const stdout = res.stdout ?? "";
-  const stderr = res.stderr ?? "";
-  if (res.status === NOT_CONFIGURED_EXIT && /not (joined|connected|configured)/i.test(stderr)) {
-    process.stderr.write(stderr);
-    process.exit(NOT_CONFIGURED_EXIT);
-  }
-  return { code: res.status ?? 1, stdout, stderr };
-}
-
-/** Run a verb and require success; on failure print the CLI's own stderr and exit with its code (or 1). */
-export function mustRun(args, opts = {}) {
-  const r = runCli(args, opts);
-  if (r.code !== 0) {
-    if (r.stderr) process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
-    if (r.stdout && !opts.quiet) process.stdout.write(r.stdout.endsWith("\n") ? r.stdout : `${r.stdout}\n`);
-    process.exit(r.code === 0 ? 1 : r.code);
-  }
-  return r;
-}
-
-/** Parse the CLI's --json stdout; a non-JSON answer is a failed check, exit 1. */
-export function parseJson(stdout, what = "output") {
-  try {
-    return JSON.parse(stdout.trim());
-  } catch {
-    process.stderr.write(`could not parse ${what} as JSON: ${stdout.trim().slice(0, 200)}\n`);
-    process.exit(1);
-  }
-}
-
-/** Minimal flag parsing for the scripts: --name value, --name=value, --flag, repeated flags collect. */
-export function parseFlags(argv, spec) {
-  const flags = {};
-  const positionals = [];
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--help" || a === "-h") return { help: true, flags, positionals };
-    if (a.startsWith("--")) {
-      let name = a.slice(2);
-      let value;
-      const eq = name.indexOf("=");
-      if (eq !== -1) {
-        value = name.slice(eq + 1);
-        name = name.slice(0, eq);
-      }
-      const s = spec[name];
-      if (!s) {
-        process.stderr.write(`unknown option --${name} (try --help)\n`);
-        process.exit(1);
-      }
-      if (s.value) {
-        if (value === undefined) value = argv[++i];
-        if (value === undefined || value === "") {
-          process.stderr.write(`--${name} needs a value\n`);
-          process.exit(1);
-        }
-        if (s.repeat) (flags[name] ??= []).push(value);
-        else flags[name] = value;
-      } else flags[name] = true;
-      continue;
-    }
-    positionals.push(a);
-  }
-  return { help: false, flags, positionals };
-}
-
-export function printHelp(usage, spec, notes = []) {
-  const lines = [`Usage: ${usage}`, ""];
-  const names = Object.keys(spec);
-  if (names.length) {
-    lines.push("Options:");
-    for (const n of names) lines.push(`  --${n}${spec[n].value ? " <value>" : ""}  ${spec[n].help}`);
-    lines.push("");
-  }
-  lines.push(...notes, "", "Exit codes: 0 ok · 1 the check failed or the arguments were wrong · 2 this machine is not connected to a tenant");
-  process.stdout.write(lines.join("\n") + "\n");
-}

package/skills/whats-happening/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/whats-happening/scripts/snapshot.mjs

@@ -1,149 +0,0 @@
-#!/usr/bin/env node
-// snapshot.mjs — one call that answers "where are we?": the tenant contract (trimmed to what a
-// status reply needs), what is running, what is queued, what is waiting on a human, and whether the
-// local replica is fresh. Prints ONE JSON document on stdout and the source line on stderr.
-import { mustRun, parseFlags, parseJson, printHelp, runCli } from "./lib/cli.mjs";
-
-const SPEC = {
-  team: { value: true, help: "limit the queue and the board to this team key" },
-  board: { value: false, help: "also include open tickets grouped by stage, in the contract's slot order" },
-  limit: { value: true, help: "board: max tickets to read (default 200)" },
-  "full-contract": { value: false, help: "include the whole contract instead of the trimmed tenant block" },
-};
-
-const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
-if (help) {
-  printHelp("node scripts/snapshot.mjs [--team K] [--board] [--limit N] [--full-contract] [--help]", SPEC, [
-    "Runs, in order: catalyst-skills contract, running, queue, ask list, replica status (and query issues with --board).",
-    "Output: one JSON document {takenAt, source, tenant, running, queue, waitingOnHuman, board?, errors?}.",
-    "A section the cloud refused is reported under errors and the rest still prints; exit 1 in that case.",
-    "Every tenant fact (stage names, thresholds, teams) comes from the contract in this output, never from prose.",
-  ]);
-  process.exit(0);
-}
-
-const errors = {};
-const section = (name, args) => {
-  const r = runCli(args);
-  if (r.code !== 0) {
-    errors[name] = (r.stderr || r.stdout || `exit ${r.code}`).trim().split("\n").at(-1);
-    return null;
-  }
-  return parseJson(r.stdout, name);
-};
-
-const contract = parseJson(mustRun(["contract", "--json"], { quiet: true }).stdout, "contract");
-// `replica status` exits 0 fresh, 1 stale, 3 absent — all three are verdicts with JSON on stdout,
-// not failures; only a non-JSON answer is an error.
-const replica = (() => {
-  const r = runCli(["replica", "status", "--json"]);
-  try {
-    return JSON.parse(r.stdout.trim());
-  } catch {
-    errors.replica = (r.stderr || r.stdout || `exit ${r.code}`).trim().split("\n").at(-1);
-    return { verdict: "unknown", cursor: null, heartbeatAgeMs: null };
-  }
-})();
-const running = section("running", ["running", "--json"]);
-const queue = section("queue", flags.team ? ["queue", "--team", flags.team, "--json"] : ["queue", "--json"]);
-const asks = section("waitingOnHuman", ["ask", "list", "--json"]);
-
-const out = {
-  takenAt: new Date().toISOString(),
-  source: {
-    reads: "api",
-    replica: replica.verdict,
-    replicaCursor: replica.cursor ?? null,
-    replicaHeartbeatAgeMs: replica.heartbeatAgeMs ?? null,
-  },
-  tenant: flags["full-contract"] ? contract : trimContract(contract, flags.team),
-  running,
-  queue,
-  waitingOnHuman: asks,
-};
-
-if (flags.board) {
-  const args = ["query", "issues", "--limit", String(flags.limit ?? 200), "--json"];
-  if (flags.team) args.push("--team", flags.team);
-  const r = runCli(args);
-  const sourceLine = (r.stderr.match(/^source: .*$/m) ?? [null])[0];
-  // A board read is a window (`--limit` stays the default), and a window the cloud cut short must
-  // say so rather than reading as the whole team.
-  const truncatedLine = (r.stderr.match(/^truncated at .*$/m) ?? [null])[0];
-  if (r.code !== 0) errors.board = (r.stderr || `exit ${r.code}`).trim().split("\n").at(-1);
-  else {
-    const rows = parseJson(r.stdout, "issues");
-    out.board = groupByStage(rows, contract, flags.team);
-    if (sourceLine) out.source.board = sourceLine.replace(/^source: /, "");
-    if (truncatedLine) out.source.boardTruncated = truncatedLine;
-  }
-}
-
-if (Object.keys(errors).length) out.errors = errors;
-process.stderr.write(`source: api for running/queue/asks; replica ${replica.verdict}${replica.cursor != null ? ` (cursor ${replica.cursor})` : ""}${out.source.board ? `; board from ${out.source.board}` : ""}\n`);
-process.stdout.write(JSON.stringify(out, null, 2) + "\n");
-process.exit(Object.keys(errors).length ? 1 : 0);
-
-/** The contract facts a status reply needs, and nothing a reply should not paste. */
-function trimContract(doc, teamKey) {
-  const teams = (doc.teams ?? []).filter((t) => !teamKey || String(t.key ?? "").toUpperCase() === teamKey.toUpperCase());
-  return {
-    contractVersion: doc.contractVersion,
-    account: { slug: doc.account?.slug, name: doc.account?.name },
-    slots: doc.slots,
-    ladder: { phases: doc.ladder?.phases, intakeEnabled: doc.ladder?.intakeEnabled, keying: doc.ladder?.keying },
-    thresholds: doc.thresholds,
-    mergeDefaultPolicy: doc.merge?.defaultPolicy,
-    teams: teams.map((t) => ({
-      key: t.key,
-      name: t.name,
-      workflowMode: t.workflowMode,
-      readiness: t.readiness?.status,
-      stages: Object.fromEntries(
-        (doc.slots ?? Object.keys(t.stages ?? {}))
-          .filter((slot) => t.stages?.[slot])
-          .map((slot) => [slot, { name: t.stages[slot].name, type: t.stages[slot].type, stateStillExists: t.stages[slot].stateStillExists }]),
-      ),
-      labels: {
-        ask: (t.labels?.ask ?? []).map((l) => l.name),
-        hold: (t.labels?.hold ?? []).map((l) => l.name),
-        release: (t.labels?.release ?? []).map((l) => l.name),
-      },
-    })),
-  };
-}
-
-/** Open tickets by stage name, ordered by the contract's slot order for the ticket's team; unmapped
- *  state names follow, alphabetically. Terminal-typed states are dropped so the board is work only. */
-function groupByStage(rows, doc, teamKey) {
-  const order = [];
-  const seen = new Set();
-  const terminal = new Set();
-  for (const t of doc.teams ?? []) {
-    if (teamKey && String(t.key ?? "").toUpperCase() !== teamKey.toUpperCase()) continue;
-    for (const slot of doc.slots ?? []) {
-      const s = t.stages?.[slot];
-      if (!s?.name) continue;
-      if (slot === "done" || slot === "canceled" || ["completed", "canceled", "cancelled"].includes(String(s.type ?? "").toLowerCase())) terminal.add(s.name);
-      else if (!seen.has(s.name)) {
-        seen.add(s.name);
-        order.push(s.name);
-      }
-    }
-  }
-  const byStage = {};
-  for (const r of rows) {
-    const state = String(r.state ?? "unknown");
-    if (terminal.has(state)) continue;
-    (byStage[state] ??= []).push({
-      identifier: r.identifier,
-      title: r.title,
-      priority: r.priority ?? null,
-      assignee: r.assignee_name ?? r.assignee ?? null,
-      updatedAt: r.updated_at ?? null,
-      projectId: r.project_id ?? null,
-    });
-  }
-  const extra = Object.keys(byStage).filter((s) => !seen.has(s)).sort();
-  return { stageOrder: [...order, ...extra], byStage, terminalStagesDropped: [...terminal] };
-}