@catalyst-cloud/catalyst-skills 0.5.0 → 0.8.0

package/skills/what-needs-me/references/settling-an-answer.md

@@ -1,37 +0,0 @@
-# Settling an answer
-
-This reference restates invariants: where an answer is posted, how it is recorded, and how held work is released. The routes and the bookkeeping marker are the contract's; `node scripts/settle.mjs` reads them through the CLI.
-
-## The rule
-
-The answer lives on the ask. Wherever it arrived (a comment on the ask, a comment on a held ticket, a chat message, a call), it ends as a comment on the ask ticket, and that comment is recorded as the accepted answer. Question, options, default, answer and who answered are then one record.
-
-## The three steps
-
-**1. Post the answer where it should live.** If the human answered in the ask's thread, nothing to do. If they answered anywhere else, post a comment on the ask that states the answer, as the app actor, never as the human, and attribute it in the text ("the owner answered in chat: option B"). Use the `catalyst-linear` skill's comment script; it returns the comment id. Do not paraphrase into a different option; quote what they said.
-
-**2. Record it.** `node scripts/settle.mjs <ask> --answer <commentId> --role <role>` calls the cloud's ask-accept with the ask, the answering comment and the role doing the recording. The script first checks the comment is really on the ask (an id from a different ticket is refused before anything is written), then records, then reads the ask's blocking relations.
-
-**3. Release the held work.** For every open ticket the ask blocks, the script posts one bookkeeping comment naming the ask, the comment id and the first line of the answer, so the next phase or agent on that ticket reads the decision without opening the ask. The comment carries the contract's bookkeeping prefix, which means the cloud's comment-wake trigger ignores it: a record, not a turn in a conversation. Pass `--no-release-note` to skip this when the held tickets are about to be canceled anyway.
-
-With `--close`, the script also moves the ask to its team's done slot. The blocking relations stay on the record; a done ticket does not block anything, so the held tickets become dispatchable on the cloud's next pass. Close only when the answer is complete; an answer that raises a follow-up question keeps the ask open and the follow-up goes in the same thread.
-
-## Free-text replies
-
-A reply that names no option ("do whichever is cheaper", "ask me again Thursday") is recorded exactly as written. Nothing in the cloud or in this skill turns it into an option. Read it, decide whether it answers the question, and if it does not, reply in the thread with the one clarification needed and leave the ask open. If it does, settle with that comment as the answer and let the release note carry the quoted line.
-
-## Who settles
-
-The role that raised the ask, or the owner of the scope it belongs to. The desk settles asks that have no owner. The human never has to run anything; their part ends when they answer. Never settle another role's ask without saying so in the thread.
-
-## After settling
-
-- Tell the human, in one line, what was recorded and what it released.
-- The held tickets need no further action from you: their exclusion reason was the blocking relation, and the queue recomputes on the cloud's next pass. If one stays excluded, `whats-happening` explains why.
-- If the answer changes priorities or scope, that is a routing change for the project owner, not a second ask.
-
-## When it cannot be settled
-
-- The comment id is not on the ask: post the answer on the ask first, then settle with the new id.
-- The write budget for the day is spent: the CLI names the budget from the contract and exits 2. Say so; the record waits, the human's answer is not lost.
-- The ask is on a team the contract does not list: the tenant admin maps the team in settings; the `catalyst-setup` skill reads readiness.

package/skills/what-needs-me/scripts/inbox.mjs

@@ -1,56 +0,0 @@
-#!/usr/bin/env node
-// inbox.mjs — "what needs me?": the open asks on this tenant, ranked by what each answer releases.
-// A thin wrapper over `catalyst-skills ask list`, which reads the open tickets carrying the team's
-// ask label (from the contract), follows each one's blocking relations, and weights held work by
-// priority. By default the CLI keeps only the asks assigned to the connected person; --anyone widens
-// to the whole tenant. Prints the ranked list; --json prints the CLI's {scope, asks} unchanged.
-import { mustRun, parseFlags, parseJson, printHelp } from "./lib/cli.mjs";
-
-const SPEC = {
-  json: { value: false, help: "print the CLI's answer as JSON: {scope, asks: [{identifier, title, state, blocks[], score, assigneeId}]}" },
-  team: { value: true, help: "only asks whose identifier carries this team key" },
-  all: { value: false, help: "include asks that hold nothing (by default they are listed last, marked)" },
-  anyone: { value: false, help: "every open ask in the tenant, not only the ones assigned to you" },
-};
-
-const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
-if (help) {
-  printHelp("node scripts/inbox.mjs [--json] [--team K] [--all] [--anyone] [--help]", SPEC, [
-    "Rank: the sum over held open tickets of a priority weight (urgent 4 ... low 1, none 1), highest first.",
-    "An ask that holds nothing is real but will not appear in the tenant's Waiting-on-me view; it is",
-    "listed last with a marker so you can attach the work it should block (references/reading-the-inbox.md).",
-  ]);
-  process.exit(0);
-}
-
-const answer = parseJson(mustRun(["ask", "list", "--json", ...(flags.anyone ? ["--anyone"] : [])], { quiet: true }).stdout, "ask list");
-const rows = answer.asks;
-const scope = answer.scope;
-const wanted = flags.team ? rows.filter((r) => String(r.identifier).toUpperCase().startsWith(`${flags.team.toUpperCase()}-`)) : rows;
-if (flags.json) {
-  process.stdout.write(JSON.stringify({ scope, asks: wanted }) + "\n");
-  process.exit(0);
-}
-// Say whose list this is before the list, so an empty "mine" never reads as "nothing needs anyone".
-if (scope.kind === "mine") process.stdout.write(`asks assigned to ${scope.label}:\n`);
-else if (scope.kind === "anyone") process.stdout.write("every open ask in the tenant:\n");
-else if (scope.kind === "unmatched") process.stdout.write(`every open ask (your Linear identity is not matched yet — an admin matches it in Settings → Members):\n`);
-else process.stdout.write("every open ask (connected with the tenant's account key, which names no person — log in with your personal key to see only yours):\n");
-if (wanted.length === 0) {
-  process.stdout.write(scope.kind === "mine" ? "nothing needs you: no open asks assigned to you (--anyone lists the tenant's)\n" : "nothing needs anyone: no open asks\n");
-  process.exit(0);
-}
-const holding = wanted.filter((r) => r.blocks.length > 0);
-const idle = wanted.filter((r) => r.blocks.length === 0);
-let n = 0;
-for (const r of holding) {
-  n += 1;
-  process.stdout.write(`${n}. ${r.identifier}  holds ${r.blocks.length} (weight ${r.score}): ${r.blocks.join(", ")}\n   ${r.title}\n`);
-}
-if (idle.length && (flags.all || holding.length === 0)) {
-  process.stdout.write(`${holding.length ? "\n" : ""}asks that hold nothing (not shown in Waiting on me until they block something):\n`);
-  for (const r of idle) process.stdout.write(`   ${r.identifier}  ${r.title}\n`);
-} else if (idle.length) {
-  process.stdout.write(`\n(${idle.length} more ask${idle.length === 1 ? "" : "s"} hold nothing; --all lists them)\n`);
-}
-process.exit(0);

package/skills/what-needs-me/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/what-needs-me/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/what-needs-me/scripts/raise.mjs

@@ -1,53 +0,0 @@
-#!/usr/bin/env node
-// raise.mjs — file one decision for the human as an ask ticket, through the cloud's own ask route.
-// Wraps `catalyst-skills ask raise`. You pass fields (question, options, default, what it blocks);
-// the cloud renders the body from the tenant's ask template, applies the ask labels, and creates the
-// blocking relations in one atomic write. Headings are never composed here.
-import { mustRun, parseFlags, parseJson, printHelp } from "./lib/cli.mjs";
-
-const SPEC = {
-  team: { value: true, help: "the team key the ask is filed on (required)" },
-  title: { value: true, help: "the question, one sentence (required)" },
-  context: { value: true, help: "a short paragraph of context the human needs to answer" },
-  option: { value: true, repeat: true, help: "one realistic option (repeat per option; the contract caps how many)" },
-  default: { value: true, help: "what proceeds if the human stays silent, and after how long" },
-  blocks: { value: true, repeat: true, help: "a ticket this decision holds (repeat per ticket)" },
-  "nothing-to-block": { value: false, help: "declare that no ticket is held (the ask then never shows in Waiting on me)" },
-  "ask-key": { value: true, help: "idempotency key so a re-run does not file a second ask" },
-  json: { value: false, help: "print the cloud's response as JSON" },
-};
-
-const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
-if (help) {
-  printHelp("node scripts/raise.mjs --team <key> --title <question> [--context <text>] [--option <text>]... [--default <text>] --blocks <ticket>... | --nothing-to-block [--ask-key <key>] [--json] [--help]", SPEC, [
-    "Search for an existing ask first (node scripts/inbox.mjs); one decision, one ask.",
-    "File BEFORE proceeding on the default. Cite the identifier only from this script's output.",
-  ]);
-  process.exit(0);
-}
-const missing = [];
-if (!flags.team) missing.push("--team");
-if (!flags.title) missing.push("--title");
-if (!flags.blocks && !flags["nothing-to-block"]) missing.push("--blocks <ticket> (or --nothing-to-block)");
-if (missing.length) {
-  process.stderr.write(`raise needs ${missing.join(", ")} (try --help)\n`);
-  process.exit(1);
-}
-
-const args = ["ask", "raise", "--team", flags.team, "--title", flags.title];
-if (flags.context) args.push("--context", flags.context);
-for (const o of flags.option ?? []) args.push("--option", o);
-if (flags.default) args.push("--default", flags.default);
-for (const b of flags.blocks ?? []) args.push("--blocks", b);
-if (flags["nothing-to-block"]) args.push("--nothing-to-block");
-if (flags["ask-key"]) args.push("--ask-key", flags["ask-key"]);
-args.push("--json");
-
-const result = parseJson(mustRun(args, { quiet: true }).stdout, "ask raise");
-const id = result.identifier ?? result.id ?? null;
-if (flags.json) process.stdout.write(JSON.stringify(result) + "\n");
-else {
-  process.stdout.write(`ask raised: ${id ?? "(no identifier returned)"}${flags.blocks ? ` — holds ${flags.blocks.join(", ")}` : " — holds nothing"}\n`);
-  if (flags.default) process.stdout.write(`default if silent: ${flags.default}\n`);
-}
-process.exit(0);

package/skills/what-needs-me/scripts/settle.mjs

@@ -1,73 +0,0 @@
-#!/usr/bin/env node
-// settle.mjs — record the human's answer on an ask and release the work it held.
-// 1. `catalyst-skills ask accept <ask> --answer <commentId> --role <role>` records which comment is
-//    the accepted answer, as the app actor.
-// 2. Every open ticket the ask blocks gets one bookkeeping comment naming the ask and the answer,
-//    so the next agent on that ticket reads the decision without opening the ask.
-// 3. With --close, the ask moves to its team's done slot (the contract's mapping), since a settled
-//    ask is a closed record.
-import { mustRun, parseFlags, parseJson, printHelp, runCli } from "./lib/cli.mjs";
-
-const SPEC = {
-  answer: { value: true, help: "the id of the comment that holds the human's answer (required)" },
-  role: { value: true, help: "the role recording it, e.g. steward or concierge (required)" },
-  close: { value: false, help: "also move the ask to the done slot" },
-  "no-release-note": { value: false, help: "skip the bookkeeping comment on the held tickets" },
-  json: { value: false, help: "print what happened as JSON" },
-};
-
-const { help, flags, positionals } = parseFlags(process.argv.slice(2), SPEC);
-const askTicket = positionals[0];
-if (help || !askTicket || !flags.answer || !flags.role) {
-  printHelp("node scripts/settle.mjs <askTicket> --answer <commentId> --role <role> [--close] [--no-release-note] [--json] [--help]", SPEC, [
-    "The answer must already be a comment on the ask. When it arrived in chat, post it there first with",
-    "the catalyst-linear skill's comment script (as the app actor, never as the human), then settle with that",
-    "comment's id. A free-text reply that names no option is recorded exactly as written, never interpreted.",
-  ]);
-  process.exit(help ? 0 : 1);
-}
-
-const detail = parseJson(mustRun(["query", "issue", askTicket, "--json"], { quiet: true }).stdout, "issue");
-const comments = Array.isArray(detail.comments) ? detail.comments : [];
-const answer = comments.find((c) => String(c.id) === String(flags.answer));
-if (!answer) {
-  process.stderr.write(`comment ${flags.answer} is not on ${detail.identifier ?? askTicket} (${comments.length} comment${comments.length === 1 ? "" : "s"} read); post the answer there first\n`);
-  process.exit(1);
-}
-const answerLine = String(answer.body ?? "").trim().split("\n")[0].slice(0, 200) || "(empty comment)";
-
-const accepted = parseJson(mustRun(["ask", "accept", askTicket, "--answer", flags.answer, "--role", flags.role, "--json"], { quiet: true }).stdout, "ask accept");
-
-const relations = Array.isArray(detail.relations) ? detail.relations : [];
-const held = [...new Set(relations
-  .filter((r) => r.type === "blocks" && (r.issue_identifier === detail.identifier || r.issue_identifier === undefined))
-  .map((r) => r.related_identifier ?? r.related_issue_identifier)
-  .filter((id) => typeof id === "string"))];
-
-const released = [];
-const failed = [];
-if (!flags["no-release-note"]) {
-  for (const t of held) {
-    const body = `${detail.identifier ?? askTicket} was answered (comment ${flags.answer}, recorded by ${flags.role}): ${answerLine}`;
-    const r = runCli(["write", "comment", t, "--bookkeeping", "--body", body, "--json"]);
-    if (r.code === 0) released.push(t);
-    else failed.push({ ticket: t, error: (r.stderr || `exit ${r.code}`).trim().split("\n").at(-1) });
-  }
-}
-
-let closed = false;
-if (flags.close) {
-  const r = runCli(["write", "state", askTicket, "--slot", "done", "--json"]);
-  if (r.code === 0) closed = true;
-  else failed.push({ ticket: askTicket, error: (r.stderr || `exit ${r.code}`).trim().split("\n").at(-1) });
-}
-
-const out = { ask: detail.identifier ?? askTicket, answerComment: flags.answer, role: flags.role, answer: answerLine, accepted, held, released, closed, failed };
-if (flags.json) process.stdout.write(JSON.stringify(out) + "\n");
-else {
-  process.stdout.write(`${out.ask}: answer ${flags.answer} recorded by ${flags.role} — "${answerLine}"\n`);
-  process.stdout.write(held.length ? `held: ${held.join(", ")}; release note posted on: ${released.join(", ") || "none"}\n` : "held nothing\n");
-  if (closed) process.stdout.write(`${out.ask} moved to the done slot\n`);
-  for (const f of failed) process.stdout.write(`failed on ${f.ticket}: ${f.error}\n`);
-}
-process.exit(failed.length ? 1 : 0);

package/skills/whats-happening/SKILL.md

@@ -1,43 +0,0 @@
----
-name: whats-happening
-description: >-
-  The desk for a Catalyst Cloud tenant. Use when the person asks "what's happening?", "where are we?", "why is that stuck?", "what closed?", "what's next?", or asks for something to be done rather than known. Reads the tenant contract, what is running and queued, the eligibility explainer and the open asks through the catalyst-skills CLI, and answers in one reply with ticket ids. Routes work to a project owner and decisions to what-needs-me. Never composes a URL, never polls, never answers as the human.
-allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
----
-<!-- vendored-from: @catalyst-cloud/catalyst-skills — written in this repository for customer tenants -->
-
-# What's happening
-
-You are the one desk the person talks to about their Catalyst Cloud tenant. They ask four questions: where are we, why is that stuck, what closed, what is next. You answer each in one reply, from their tenant's data only, with a ticket identifier on every line. When they ask for something to be done, you route it to an owner; when only they can decide something, you raise it through `what-needs-me`.
-
-## Run first
-
-Scripts are run, never read. Each prints `--help`; exit 2 means this machine is not connected (run the `connect-me` skill), exit 1 means the check itself failed.
-
-- `node scripts/snapshot.mjs --help` — one JSON document: the trimmed contract (teams, stage names by slot, thresholds, ladder), what is running, the queue, the open asks ranked by what they hold, and the replica verdict. Add `--board` for open tickets grouped by stage in the contract's slot order, `--team K` to narrow.
-- `node scripts/explain.mjs --help` — why nothing is offered for one ticket, in one paragraph.
-
-For a single ticket's comments, relations and linked PRs use the `catalyst-linear` skill (`catalyst-skills query issue <id>`); for a pull request's checks and threads, `catalyst-github`.
-
-## Load on demand
-
-| when | read |
-| -- | -- |
-| writing any status answer | `references/status-reply.md` (schema: `assets/status-reply.json`) |
-| the board looks wrong, a column is long, or you must decide whether something is stuck | `references/reading-the-board.md` |
-| `explain` returned a reason and the person wants the next action | `references/why-is-it-stuck.md` |
-| "do this one first", "why is that not next", "stop that" | `references/reprioritising.md` |
-| the person asks for work to be done, or a decision surfaces | `references/routing-work.md` |
-
-For depth beyond these, load the fact skills: `how-catalyst-works` (the ladder, slots and mapping, failure layers, queue order, coding accounts), `catalyst-linear` (what a ticket accumulates, reading and writing), `catalyst-github` (what a PR accumulates, mergeability), `catalyst-setup` (readiness).
-
-## Rules
-
-- **Their tenant, as them.** Every read goes through the CLI, which holds the person's own key, the tenant and who they are. You never name, guess at, or try another tenant, and you never paste the key anywhere. "You" in your reply means the connected person: their assigned tickets, their asks.
-- **Tenant facts come from the contract, live.** Stage names, label names, team keys, thresholds and the ladder are in the snapshot's `tenant` block; read them there each time and never restate them from memory.
-- **One reply, ticket ids on every line, source named.** The reply opens with when the snapshot was taken and whether the replica or the API answered. A stale replica is stated, never hidden.
-- **Say what a key cannot see.** PR labels and reactions are not mirrored; the CLI prints the settings URL, and you repeat it instead of guessing. A park or hold is released from the person's own login once its cause is fixed: route that to the `unstick` skill (`catalyst-skills release`), never tell them it needs an operator. Coding-account status (`accounts`) and per-ticket execution history (`explain --history`) are readable — read them.
-- **No polling.** One snapshot per question. Waiting on a change is the project owner's job (`run-this-project` subscribes to the tenant stream); the desk never loops a read.
-- **You are not the owner.** You route work and make it visible; you do not dispatch, overrule a project owner, or run long work in this session.
-- **Never answer as the human.** A decision is an ask through `what-needs-me`, filed before anyone proceeds on its default; the answer is recorded there as the app actor.
-- **Cite an identifier only after a create call returned it.**

package/skills/whats-happening/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "What's happening"
-  short_description: "Where your Catalyst work stands: in flight, blocked and on whom, closed, and what runs next"
-  default_prompt: "Use $whats-happening to tell me where my work stands and why anything is stuck."
-policy:
-  allow_implicit_invocation: true

package/skills/whats-happening/agents/portability.yaml

@@ -1,4 +0,0 @@
-identity: { pack: catalyst-cloud-skills, skill: whats-happening }
-effects: []
-invocation: implicit
-exposure: [catalog]

package/skills/whats-happening/assets/status-reply.json

@@ -1,77 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "Catalyst status reply",
-  "description": "The one-reply shape a status answer follows. Every line names a ticket identifier; nothing in it is a guess. Fill it from scripts/snapshot.mjs and scripts/explain.mjs, then render it as prose in this order.",
-  "type": "object",
-  "required": ["asOf", "source", "inFlight", "blocked", "closed", "next"],
-  "properties": {
-    "asOf": { "type": "string", "format": "date-time", "description": "When the snapshot was taken (snapshot.takenAt)." },
-    "source": {
-      "type": "string",
-      "description": "Where the facts came from, in one clause: the API, or the replica with its cursor and heartbeat age. Copy the snapshot's source line; never omit it when the replica was stale."
-    },
-    "scope": { "type": "string", "description": "The team key or project the reply covers, when the human asked about one." },
-    "inFlight": {
-      "type": "array",
-      "description": "Tickets a phase is running on right now, or that sit mid-ladder with a live lease. One entry per ticket.",
-      "items": { "$ref": "#/$defs/line" }
-    },
-    "blocked": {
-      "type": "array",
-      "description": "Tickets nothing is offered for, each with the reason in the human's words and who or what releases it.",
-      "items": {
-        "allOf": [
-          { "$ref": "#/$defs/line" },
-          {
-            "properties": {
-              "reason": { "type": "string", "description": "The explainer's reason, translated (references/why-is-it-stuck.md)." },
-              "onWhom": { "type": "string", "description": "The human, a named role, the cloud itself, or a clock — never blank." }
-            },
-            "required": ["reason", "onWhom"]
-          }
-        ]
-      }
-    },
-    "waitingOnHuman": {
-      "type": "array",
-      "description": "Open asks, ranked by what each holds. Taken from snapshot.waitingOnHuman; the what-needs-me skill owns the detail.",
-      "items": {
-        "type": "object",
-        "required": ["ticket", "question", "holds"],
-        "properties": {
-          "ticket": { "type": "string" },
-          "question": { "type": "string" },
-          "holds": { "type": "array", "items": { "type": "string" }, "description": "Ticket identifiers the answer releases." }
-        }
-      }
-    },
-    "closed": {
-      "type": "array",
-      "description": "Tickets that reached the done slot since the window the human asked about (or since the last reply).",
-      "items": { "$ref": "#/$defs/line" }
-    },
-    "next": {
-      "type": "array",
-      "description": "What the queue will pick up next, in queue order, with the phase each will run.",
-      "items": { "$ref": "#/$defs/line" }
-    },
-    "cannotSee": {
-      "type": "array",
-      "description": "Facts your key cannot read (PR labels and reactions; an operator-only park release), named, with where the human can read them (the CLI prints the URL).",
-      "items": { "type": "string" }
-    }
-  },
-  "$defs": {
-    "line": {
-      "type": "object",
-      "required": ["ticket", "summary"],
-      "properties": {
-        "ticket": { "type": "string", "description": "The identifier, KEY-123 shape." },
-        "summary": { "type": "string", "description": "One clause: what it is and where it stands." },
-        "stage": { "type": "string", "description": "The stage name as the contract spells it for this team." },
-        "phase": { "type": "string", "description": "The ladder phase running or offered, when known." },
-        "age": { "type": "string", "description": "How long it has sat where it is, in human units." }
-      }
-    }
-  }
-}

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

@@ -1,43 +0,0 @@
-# Reading the board
-
-This reference restates invariants: what the stages are, what order they come in, and what "stuck" means. The names your team uses for each stage, and which state ids they map to, are tenant facts read live from the contract; `node scripts/snapshot.mjs --board` prints the board already grouped and ordered by them.
-
-## Stages are slots, names are display
-
-Catalyst thinks in eleven **slots** in pipeline order: dispatch, intake, research, plan, implement, remediate, verify, review, pr, done, canceled. Each of your teams maps some or all of those slots onto its own Linear workflow states. The contract carries, per team and per slot, the state id (the authority), the live state name and type (display), and whether the state still exists in Linear. A team may have adopted Catalyst's recommended states, mapped its existing ones, or mixed the two; the contract's `workflowMode` says which.
-
-Five slots are load-bearing and a missing one is a distinct silent failure: **dispatch** (where a card goes to be picked up), **intake** (an optional first pass for tickets that have never entered the ladder), **pr** (where a card sits while its pull request is reviewed and merged), **done** and **canceled**. The other six are informational: a wrong mapping there costs a warning, not a stall.
-
-Read a board by slot, never by name. Two teams can call the same slot different things, and a state renamed in Linear keeps its id and its slot.
-
-## Work in progress by stage
-
-The snapshot's `board` block groups open tickets by state name in slot order, drops terminal states, and lists any state name that maps to no slot at the end. Read it top to bottom:
-
-- **dispatch** holds what is ready and waiting for a container. A long dispatch column with nothing in flight is a capacity or eligibility question, not a work question: run `explain` on the first row.
-- **intake** through **pr** are the ladder. A card advances one slot when the matching phase completes; a failed phase writes no board state, so a card that has not moved is either still running, retrying in place, or moved sideways to remediate.
-- **remediate** is an interrupt, not a step. A card there was moved by a failure and returns to its exact previous stage when a repair round succeeds. Count remediate cards separately; they are not progress.
-- Backlog-type states are not slots. A ticket there is parked or not yet chosen; nothing is offered for it and nothing is wrong with it.
-
-## Aging
-
-Age is time since `updated_at`, or since the lease started for a ticket in flight. Report it in human units. Compare it to the phase, not to a fixed number: a research phase and a merge wait have different natural durations, and the cloud's own retry backoff (the contract's `thresholds.retryBackoffMs`) explains many short waits.
-
-## What counts as stuck
-
-A ticket is **stuck** only when all three hold:
-
-1. Nothing is offered for it: the queue lists it excluded, or `explain` gives a reason rather than a position.
-2. The reason does not release itself. Backoffs, cooldowns that name a callback, and fleet-wide holds that clear when the cloud repins are waits, not stalls. The table in `references/why-is-it-stuck.md` marks which is which.
-3. No one is acting on the release: no open ask names it, no human comment landed after the failure, no push arrived.
-
-Everything else is **waiting**, and the reply says what it is waiting on. Calling a wait "stuck" sends the human to fix something the cloud is already handling.
-
-## The signals the cloud posts on the ticket itself
-
-Before declaring anything, read the ticket's comments (`catalyst-skills query issue <id>`; the `catalyst-linear` skill explains each shape). The cloud posts a phase-outcome card on every completion and failure, a remediate-attempt card per repair round, a board-health note when it detects a stall itself, and a merge-wait note when a merge is held. Those comments are the narrative; the per-ticket ledger behind them — attempts, rounds against the cap, park state — is `catalyst-skills explain --history <ticket>`, and the two must agree.
-
-## Two things that look like work and are not
-
-- A ticket carrying the ask marker label, or whose text reads as a decision request, is a question. It is excluded from dispatch by design and belongs in the waiting-on-human block.
-- A ticket claimed by a worker outside the cloud (the local-lane label) is being worked, but not by Catalyst; report it as in flight elsewhere and do not chase the cloud for it.

package/skills/whats-happening/references/reprioritising.md

@@ -1,37 +0,0 @@
-# Reprioritising
-
-This reference restates invariants: how Catalyst orders work and which levers a person actually has. The live queue is `catalyst-skills queue [--team K]` (inside `node scripts/snapshot.mjs`); the thresholds behind backoffs and parks are the contract's `thresholds` block, printed in the snapshot's `tenant` section.
-
-## How the cloud orders work
-
-Each team's queue is derived by the cloud itself from the team's own tickets, so there is nothing a session publishes and nothing that goes stale between sessions. The order is:
-
-1. **Priority** ascending, as set on the Linear ticket (urgent first).
-2. **Created time** ascending: older tickets first among equals.
-3. **Identifier** ascending, as the final tiebreak.
-
-Tickets that are already **mid-ladder** join the same candidate set and sort ahead by how many phases they have completed, so a ticket that is nearly done finishes before a fresh one starts. That is an ordering rule only; it never makes an ineligible ticket eligible.
-
-Within the order, dispatch is bounded per repository (a concurrency cap the tenant admin can set in settings, and a paused repository resolves to zero) and split across teams so one team cannot starve another. Comment-wake work, where the cloud answers a human comment on a ticket, shares the same cap as relay work.
-
-The queue is recomputed on every ingest that touches the team and on each alarm pass, so a change you make shows up within seconds, not on a schedule.
-
-## The three levers a person has
-
-**1. Priority on the ticket.** Change the Linear priority and the queue reorders itself. This is the lever for "do this one first". It does not jump a running phase; it changes what is picked up next.
-
-**2. The dispatch column.** A card is offered only when it sits in the team's dispatch slot (and, for a ticket that has never entered the ladder, the intake slot when intake is enabled). Moving a card into that slot is how work is started; moving it out to a backlog-type state is how work is stopped without cancelling it. The `run-this-project` skill has the script; through this skill you describe the move and let the person or the project owner make it.
-
-**3. Holds.** A PR label from the contract's `merge.prLabels` set keeps an otherwise-mergeable pull request out of the merge queue until a person removes it. A blocking relation from an ask holds every ticket the ask names. Applying the release label the contract names frees a ticket the ask-shape detector flagged by mistake.
-
-Everything else that looks like a lever is not one from a key: unparking a phase, clearing a repair hold, resetting a validate budget and re-pinning a base are operator actions today, and the reply says so and names the settings page rather than promising them.
-
-## What not to promise
-
-- **A running phase is not interrupted** by any of the three levers. It finishes or fails on its own; then the new order applies.
-- **A failed phase does not need re-queueing.** A pre-branch failure or an infrastructure failure retries in place after a backoff; a later failure moves the card to the remediate slot and queues a repair round, capped by the contract's `thresholds.remediateRoundCap`; repeated failures park it after `thresholds.parkAfterConsecutiveFailures`. Moving the card by hand during that sequence usually restarts the count rather than shortening it.
-- **Priority is not urgency to the human.** An urgent ticket that is blocked on an ask still waits for the ask. The what-needs-me ranking (by what an answer releases) is the right list for the human; the queue is the right list for the fleet.
-
-## Answering "why is that one not next?"
-
-Run `explain` on it. If the answer is a position, it is next in order and the cloud is bounded by capacity: say how many are ahead and whether any run at all (if nothing runs anywhere, the likely cause is coding-account capacity, which a key cannot read yet, so name the settings page). If the answer is a reason, use `references/why-is-it-stuck.md`. If the answer is that the ticket is not in the explainer, it is on another team, terminal, or unknown to the mirror: check the identifier before anything else.