@catalyst-cloud/catalyst-skills 0.5.0 → 0.8.0

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

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

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

@@ -1,41 +0,0 @@
----
-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 — 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

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

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

package/skills/unstick/references/playbook.md

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

package/skills/unstick/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/unstick/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/unstick/scripts/unstick.mjs

@@ -1,57 +0,0 @@
-#!/usr/bin/env node
-// unstick.mjs — "why is this stuck, and can it be released?" in one JSON document. Runs
-// `catalyst-skills explain`, `explain --history` and a dry-run `release` for one ticket (or a dry-run
-// class release for one team), and only with --because runs the real release. Reaches the cloud only
-// by spawning the CLI.
-import { mustRun, parseFlags, parseJson, printHelp, runCli } from "./lib/cli.mjs";
-
-const SPEC = {
-  because: { value: true, help: "what changed since the ticket was held; runs the real release after the preview" },
-  "retry-unchanged": { value: false, help: "release even though nothing the cloud can see changed (say what did in --because)" },
-  class: { value: true, help: "release every ticket on --team parked under this failure class" },
-  team: { value: true, help: "with --class: the team key" },
-  limit: { value: true, help: "with --class: at most this many tickets (the cloud caps it at 25)" },
-};
-
-const { help, flags, positionals } = parseFlags(process.argv.slice(2), SPEC);
-const ticket = positionals[0];
-const byClass = typeof flags.class === "string";
-if (help || (!ticket && !byClass) || (byClass && (ticket || typeof flags.team !== "string"))) {
-  printHelp("node scripts/unstick.mjs <ticket> [--because <text>] [--retry-unchanged] [--help] | --class <c> --team <K> [--because <text>] [--retry-unchanged] [--limit N] [--help]", SPEC, [
-    "Without --because it changes nothing: it prints the explanation, the history (every governor holding the ticket",
-    "and past releases) and a dry-run release. With --because it then runs the real release. Read references/playbook.md",
-    "before passing --because. A refused release exits 1 with the refusals in the document.",
-  ]);
-  process.exit(help ? 0 : 1);
-}
-
-const releaseArgs = byClass ? ["release", "--class", flags.class, "--team", flags.team] : ["release", ticket];
-if (flags["retry-unchanged"]) releaseArgs.push("--retry-unchanged");
-if (byClass && typeof flags.limit === "string") releaseArgs.push("--limit", flags.limit);
-
-const out = {};
-if (!byClass) {
-  out.explain = parseJson(mustRun(["explain", ticket, "--json"]).stdout, "explain");
-  out.history = parseJson(mustRun(["explain", ticket, "--history", "--json"]).stdout, "history");
-}
-
-const preview = runCli([...releaseArgs, "--dry-run", "--json"]);
-if (preview.code !== 0 && preview.code !== 1) {
-  process.stderr.write(preview.stderr);
-  process.exit(preview.code);
-}
-out.preview = parseJson(preview.stdout, "the dry-run release");
-
-let exit = 0;
-if (typeof flags.because === "string") {
-  const real = runCli([...releaseArgs, "--because", flags.because, "--json"]);
-  if (real.code !== 0 && real.code !== 1) {
-    process.stderr.write(real.stderr);
-    process.exit(real.code);
-  }
-  out.release = parseJson(real.stdout, "the release");
-  exit = real.code;
-}
-
-process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
-process.exit(exit);

package/skills/what-needs-me/SKILL.md

@@ -1,41 +0,0 @@
----
-name: what-needs-me
-description: >-
-  The human's decision inbox on a Catalyst Cloud tenant, and the one way an agent raises a decision on their behalf. Use when the person asks "what needs me?", "what am I blocking?", or when active work is gated on a choice only they can make. Lists open asks ranked by what each answer releases, files an ask through the cloud's ask route with the tenant's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
-disable-model-invocation: true
-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 needs me
-
-An ask is one decision only the human can make, filed as a ticket in their own Linear so that question, options, default, answer and who answered are one record. This skill reads that inbox ranked by blast radius, raises a new ask when work is gated, and settles the answer so the held work releases. The cloud renders the ask body from the tenant's template, applies the ask labels and creates the blocking relations; you pass fields, never headings.
-
-## 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 or an argument was missing.
-
-- `node scripts/inbox.mjs --help` — the open asks assigned to the connected person, ranked by the priority-weighted work each holds; `--anyone` for the whole tenant; `--json` for `{scope, asks}`.
-- `node scripts/raise.mjs --help` — file one decision: `--team`, `--title`, `--option` (repeated), `--default`, and `--blocks` (repeated) or `--nothing-to-block`.
-- `node scripts/settle.mjs --help` — record the answering comment on an ask and post a release note on every ticket it held; `--close` moves the ask to the done slot.
-
-## Load on demand
-
-| when | read |
-| -- | -- |
-| about to file an ask, or unsure whether something is one | `references/raising-a-decision.md` |
-| presenting the inbox, or the person asks what "waiting on me" means | `references/reading-the-inbox.md` |
-| an answer arrived, anywhere | `references/settling-an-answer.md` |
-
-The `catalyst-linear` skill posts the comment that carries an answer given in chat and reads an ask's thread; `whats-happening` explains a held ticket that stays excluded after the answer.
-
-## Rules
-
-- **File before proceeding on the default.** Work may run on a default only after the ask exists; a default with no ticket behind it is a guess, not a decision.
-- **One ask per decision.** Read the inbox first; attach new held tickets to an open ask rather than filing a twin. Duplicates split one decision's urgency across rows.
-- **Every ask names what it blocks.** The ranking the human sees is by held work weighted by priority, never by age; an ask that holds nothing does not reach Waiting on me unless you chose `--nothing-to-block` on purpose.
-- **Never answer as the human.** You do not pick an option, close an ask on their behalf, or post in their voice. Their answer is quoted into the ask as the app actor and recorded with its comment id.
-- **A free-text reply is recorded, never interpreted into an option.** If it does not answer the question, ask the one clarification in the thread and leave the ask open.
-- **Escalate inward.** A project owner raises asks for its scope; the desk raises what has no owner; a single stuck ticket or a provider outage is never an ask.
-- **Tenant facts come from the contract.** Team keys, label names, the option cap and the template are read live by the CLI; never restate them.
-- **Cite an identifier only after the create call returned it.**

package/skills/what-needs-me/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "What needs me"
-  short_description: "Your decision inbox on Catalyst Cloud, ranked by what each answer releases; raises and settles asks"
-  default_prompt: "Use $what-needs-me to show me what is waiting on my decision."
-policy:
-  allow_implicit_invocation: false

package/skills/what-needs-me/agents/portability.yaml

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

package/skills/what-needs-me/references/raising-a-decision.md

@@ -1,41 +0,0 @@
-# Raising a decision
-
-This reference restates invariants: what an ask is, when it is filed, and what it must carry. The body text, the headings, the option format and the cap on options are tenant facts served by the contract's `askTemplate` block and rendered by the cloud itself; `node scripts/raise.mjs` passes fields and never composes a heading.
-
-## What an ask is
-
-An ask is one decision only the human can make, filed as a ticket in the tenant's own Linear so that the question, the options, the default, the answer and who answered are one record the next agent can read. The cloud labels it as an ask, excludes it from dispatch (a question is never work), and holds every ticket it blocks until it is answered. It appears in the human's Waiting-on-me view when it is assigned to them and blocks open work.
-
-## When to file one
-
-File an ask when active work is gated on a product call, a priority call between two things that cannot both go first, an approval, or an action only the human can physically take (a click in settings, a credential, a payment). File it **before** proceeding on the default, never after, and never only as a TODO line, a board row, a handoff note or a chat question. Those may point at the ask's identifier; they never replace it.
-
-Do not file one for brainstorming, a design back-and-forth, a question the human asked first, a retry-or-abandon call a project owner can make, or a system-level failure (a provider down, out of capacity, rate-limited: that is one status line, and the affected tickets retry on their own).
-
-## What it carries
-
-1. **The question**, one sentence, as the title (`--title`).
-2. **Context** the human needs to answer without opening anything else (`--context`), short.
-3. **Options**, each one line, realistic, at most the number the contract allows (`--option`, repeated). The cloud letters and formats them.
-4. **The default if silent** (`--default`): what proceeds and after how long. It must be sane enough to actually run. Note that nothing in the cloud applies the default on a timer; the raising agent applies it, after the ask exists, and records that it did.
-5. **What it blocks** (`--blocks`, repeated): every ticket held until the answer lands. The cloud creates the blocking relations atomically with the ticket. An ask that holds nothing is refused unless you say `--nothing-to-block` on purpose, because an ask with no blocking relation never surfaces in Waiting on me and is indistinguishable from ordinary work.
-
-`--ask-key` is an idempotency key: a re-run with the same key does not file a second ask.
-
-## One ask per decision
-
-Run `node scripts/inbox.mjs` first and read the titles. When the same decision is already open, attach the new held tickets to it rather than filing again (the `catalyst-linear` skill adds the relation or a comment naming them). Duplicates split one decision's urgency across several rows and sink it below trivia in the ranking.
-
-## Who raises, and where
-
-- A decision inside a project scope is raised by that project's owner; the desk raises what has no owner.
-- The ask is filed on the team the held work belongs to (`--team`), from the contract's team list. An approvals team, when the contract names one, is where an approval with no natural team goes.
-- Never raise an ask on someone else's behalf about their own scope, and never answer one for the human.
-
-## After filing
-
-Cite the identifier the script printed, and only that. Proceed on the default if the work allows it, and say so in the ask's thread (a bookkeeping comment) so the record shows the default was taken. When the answer arrives, `references/settling-an-answer.md`.
-
-## Ranking
-
-The human sees asks ranked by how much open work each holds, weighted by that work's priority (urgent counts most), never by age. That is why `--blocks` must be complete: an ask that names one held ticket when it really holds a project sinks below a chore.

package/skills/what-needs-me/references/reading-the-inbox.md

@@ -1,38 +0,0 @@
-# Reading the inbox
-
-This reference restates invariants: what "waiting on me" means, how declared and inferred asks differ, and how to present the queue. The label that marks an ask, its prefix, and the release label are the contract's `vocabulary`; `node scripts/inbox.mjs` reads them from the CLI and never from prose.
-
-## What waiting-on-me means
-
-The tenant's own Waiting-on-me view lists a ticket for a person when all four hold:
-
-1. it is **assigned** to that person;
-2. it has **no delegate** (a ticket delegated to an agent is the agent's, not the human's);
-3. it is still **open**;
-4. what it **blocks** reaches open work: at least one ticket it holds is itself not done or canceled.
-
-A ticket that carries the ask marker label and is assigned to the person shows even with zero blocks. That is the **declared** ask. The four-part rule above is the **inferred** one, and the view offers both modes: asks only (the default) and everything the person is holding up, minus items an open unblock ask already covers.
-
-So an ask that holds nothing is real, but the person may never see it in their own view. `inbox.mjs` lists such asks last and marked, so you can attach the work they should block.
-
-## What the script reads
-
-`catalyst-skills ask list` reads the open tickets carrying the team's ask label (by the label ids and prefix the contract serves), follows each one's blocking relations to the tickets it holds, drops held tickets that are already terminal, and scores the rest by priority weight: urgent 4, high 3, medium 2, low 1, none 1. It filters to **the connected person** by default: `login` recorded who they are and their Linear user id, and the list keeps only asks assigned to that id. `--anyone` lists the whole tenant. The JSON answer carries a `scope` — `mine` (with the label and Linear id), `anyone`, `unmatched` (the person's Linear identity is not matched yet: an admin does that in Settings → Members, and until then the whole list is shown with a stderr line saying so), or `no-person` (the machine is connected with the tenant's account key, which names nobody: the whole list, with a line saying to log in with a personal key). Read the scope before presenting the list, and say which you got: "what needs me" is the `mine` list, "what needs anyone" is `--anyone`, and an empty `mine` list names the wider count so it never reads as "nothing needs anyone".
-
-## Presenting the queue
-
-- Ranked by score, highest first. Never by age, never by identifier. An ask that holds a project outranks one that holds a chore, whatever their dates.
-- One line per ask: rank, identifier, what it holds (identifiers), the question. The human decides from the question and the held work, so both must be on the line.
-- Asks that hold nothing come after a break, marked as not visible in Waiting on me until they block something.
-- When the list is empty, say "nothing needs you" and stop. Do not pad it with suspected asks.
-- A ticket `explain` flagged as `ask_shape_suspected` (its text reads as a decision but it carries no ask label) is mentioned separately with a question mark: it is either an ask the human should label, or a false positive they release with the release label the contract names.
-
-## What the inbox is not
-
-- It is not the dispatch queue. Held tickets are excluded from dispatch by their blocking relation; answering the ask releases them into the ordinary order.
-- It is not a place to answer. Nothing in this skill picks an option, closes an ask on the human's behalf, or posts in their voice. When they answer in chat, `references/settling-an-answer.md`.
-- It is not a stall detector. A ticket parked by repeated failures, a merge hold, or a coding-account wall is a status question for `whats-happening`, not a decision until someone makes it one by raising an ask.
-
-## Free-text and interpreted replies
-
-A human reply that names no option is recorded by the cloud and interpreted for display, but never auto-applied and never written back to Linear as a decision. Treat it the same way: read it, ask the human to confirm which option it means if that is unclear, and settle only once a comment on the ask states the answer.