@catalyst-cloud/catalyst-skills 0.3.1 → 0.5.0

package/skills/connect-me/scripts/lib/cli.mjs

@@ -10,6 +10,7 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE_NAME = "@catalyst-cloud/catalyst-skills";
 export const NOT_CONFIGURED_EXIT = 2;
@@ -33,7 +34,7 @@ export function loadCustomerConfig() {
   if (!existsSync(path)) return null;
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (!parsed || typeof parsed !== "object" || typeof parsed.key !== "string" || typeof parsed.account !== "string") return null;
+    if (!hasCredential(parsed) || typeof parsed.account !== "string") return null;
     return parsed;
   } catch {
     return null;
@@ -44,7 +45,7 @@ export function loadCustomerConfig() {
 export function requireConfigured() {
   const cfg = loadCustomerConfig();
   if (cfg) return cfg;
-  console.error(`not connected: ${configPath()} is missing or unreadable — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE_NAME} login`);
+  console.error(`not connected: ${configPath()} is missing or unreadable — run: ${CONNECT_COMMAND}`);
   process.exit(NOT_CONFIGURED_EXIT);
 }
 

package/skills/connect-me/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
+// session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
+// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// itself. A new credential kind lands here, once.
+
+/** The command that connects this machine, as every not-connected line names it. */
+export const CONNECT_COMMAND =
+  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/how-catalyst-works/references/stages-and-mapping.md

@@ -28,7 +28,7 @@ The contract's `teams[].workflowMode` reports which one a team is in:
 - **mapped**: the team kept its existing stages and a human chose which stage fills each slot.
 - **mixed**: some slots adopted, some hand-chosen.
 
-`teams[].gitAutomation` is a separate switch, off by default, because enabling it can delete a team's own review automation in Linear; it is never bundled into "adopt recommended".
+`teams[].gitAutomation` is a stored consent for a feature that is not built yet (Catalyst managing a team's Linear git automations); nothing reads it, so `off` never stops work and turning it on would start none. What decides whether a team's tickets start is the mapping above: until dispatch, pr, done and canceled each point at a live stage, Catalyst starts nothing in that team, and `explain` says so by name.
 
 ## The state id is the authority; names are display
 

package/skills/how-catalyst-works/references/what-runs-next.md

@@ -66,7 +66,7 @@ No survivor is `no_eligible_account_slot` when any candidate was skipped on capa
 
 ## The unknowns (the evaluator fails closed)
 
-When the cloud cannot answer, it says so rather than guessing: `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`, `branch_snapshot_unknown`. An unknown is "I could not look", never "it is not there"; report it as inconclusive.
+When the cloud cannot answer, it says so rather than guessing: `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`, `branch_snapshot_unknown`. An unknown is "I could not look", never "it is not there"; report it as inconclusive. The exception is a team with no saved stage mapping: `workflow_mapping_unknown` never clears on its own there, `explain` names the missing stages, and the fix is a tenant owner or admin mapping the team.
 
 One advisory gates nothing: `human_addressed_unlabeled_ask_suspect` (assigned to a human with no delegate; possibly an unlabelled ask).
 

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

@@ -33,12 +33,12 @@ Which parks release themselves:
 
 | Park | Releases by |
 | -- | -- |
-| repeated failure | an operator, not a clock |
-| remediate round cap reached | an operator, not a clock |
+| repeated failure | a release from the person's own login once its cause is fixed (`catalyst-skills release`), not a clock |
+| remediate round cap reached | the same release, which buys one more round, not a clock |
 | missing branch | its own budgeted release loop |
 | rebase conflict | its own budgeted release loop |
 
-Your key cannot release a park; the repair verbs are operator-only. When a ticket is parked, say so, name the failure class the explainer shows, and hand the release to whoever administers the tenant.
+A person's own key releases a park, and every other hold that a retry can fix, in one step: `catalyst-skills release <ticket> --because <what changed>`. The cloud releases every governor holding the ticket or releases nothing and names what a person must do instead (a person's own pull request, a review that will not converge, the lifetime repair budget). It refuses a cause it cannot see change unless the caller says what changed. The `unstick` skill runs that loop. When a ticket is parked, name the failure class the explainer shows and whether its cause is fixed.
 
 ## Two holds that are not failures
 
@@ -53,5 +53,5 @@ Each attempt posts a phase-outcome comment (complete or FAILED, with phase, atte
 
 1. Run `node scripts/explain-ticket.mjs <ticket>`; the reason names the layer.
 2. `retry_backoff` or `routing_unavailable`: wait; it retries itself. Say when.
-3. `cooling_down`, `remediate_parked`, `no_change_hold`, `validate_class_spent`: name what releases it (an operator, a comment, a push) and who can do that.
+3. `cooling_down`, `remediate_parked`, `no_change_hold`, `validate_class_spent`: name what releases it (a release once the cause is fixed, a comment, a push) and who can do that.
 4. A system-level cause (provider down, runner image breaker, repo paused) is ONE alert, never a per-ticket escalation.

package/skills/how-catalyst-works/scripts/lib/cli.mjs

@@ -6,9 +6,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = CONNECT_COMMAND;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME (used by tests) over HOME. */
 export function configPath() {
@@ -22,8 +23,8 @@ export function loadConfig() {
   if (!existsSync(path)) return { ok: false, reason: `no config at ${path}` };
   try {
     const cfg = JSON.parse(readFileSync(path, "utf8"));
-    if (!cfg || typeof cfg.key !== "string" || typeof cfg.account !== "string") {
-      return { ok: false, reason: `${path} is missing the key or account` };
+    if (!hasCredential(cfg) || typeof cfg.account !== "string") {
+      return { ok: false, reason: `${path} is missing a key or login, or the account` };
     }
     return { ok: true, cfg, path };
   } catch (err) {

package/skills/how-catalyst-works/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
+// session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
+// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// itself. A new credential kind lands here, once.
+
+/** The command that connects this machine, as every not-connected line names it. */
+export const CONNECT_COMMAND =
+  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/run-this-project/SKILL.md

@@ -42,4 +42,4 @@ Every script exits 2 when this machine is not connected (run `catalyst-skills lo
 - **Escalate inward.** Instrument, then you, then the desk, then the human as an ask filed through `what-needs-me` with what it blocks. Decide the technical calls yourself; take the sane default and record it; a fleet or provider condition is one note, never one ask per ticket.
 - **Reply where the message arrived,** in-thread, tagged, as the app actor. Never post as the human, never answer someone else's ask. Bookkeeping records take the contract's marker (`catalyst-skills write comment --bookkeeping`).
 - **One status summary,** kept current after every reaction: in flight, blocked and on whom, closed, next, each line with a ticket id. Where a human decision is pending, the line carries the ask's id.
-- **Say what a key cannot see.** A park is released only by an operator, and PR labels and reactions are not mirrored; the CLI says so by name and points at settings. Execution history (`explain --history`) and coding-account status (`accounts`) ARE readable — read them rather than reconstructing them from comments.
+- **Say what a key cannot see.** PR labels and reactions are not mirrored; the CLI says so by name and points at settings. A park or hold is released from the person's own login once its cause is fixed, through the `unstick` skill (`catalyst-skills release`). Execution history (`explain --history`) and coding-account status (`accounts`) ARE readable — read them rather than reconstructing them from comments.

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

@@ -48,7 +48,7 @@ The card's stage is the fourth, weakest signal: a completed phase moves the card
 
 ## Parking, and what it does not do
 
-Parking is the lever that stops the cloud offering more rounds on a ticket: moved out of the dispatch column and the ladder's stages, the ticket is excluded at the next offer. It does not kill a phase that is already running under a lease; that container finishes its phase, posts its outcome, and the next offer finds the card parked. If you park a ticket the cloud has itself parked (three consecutive failures, or the remediate round cap), record why in a bookkeeping note; releasing a cloud park is an operator action, not a card move, so that is an ask for a human with the ticket named as what it blocks.
+Parking is the lever that stops the cloud offering more rounds on a ticket: moved out of the dispatch column and the ladder's stages, the ticket is excluded at the next offer. It does not kill a phase that is already running under a lease; that container finishes its phase, posts its outcome, and the next offer finds the card parked. If you park a ticket the cloud has itself parked (three consecutive failures, or the remediate round cap), record why in a bookkeeping note. Releasing a cloud park is not a card move: once its cause is fixed, the `unstick` skill releases it with `catalyst-skills release <ticket>`, and only a refusal that names a person's action becomes an ask.
 
 Un-parking is the same dispatch move again. The counted attempts and rounds do not reset when a card comes back; the contract's thresholds say how many remain.
 

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

@@ -26,7 +26,7 @@ Run `catalyst-skills explain <ticket>` first, and let its reason pick the row:
 | blocked | a live blocks relation | chase the blocker: is it dispatchable, is it an ask nobody answered, is it done but still open |
 | ask ticket, ask shape suspected | the ticket is a question | route it to `what-needs-me`; if it is really work, a human applies the release label |
 | not at dispatch stage | somebody moved the card, or it never entered | read the card's history; re-dispatch with `make-ready.mjs` if it should run |
-| cooling down, remediate parked | the cloud parked it after repeated failure or the round cap | read the last outcome card for the class; if the fix is a decision, file an ask; releasing the park is an operator action |
+| phase parked, cooling down, remediate parked | the cloud parked it after repeated failure or the round cap | read the last outcome card for the class; once its cause is fixed, the `unstick` skill releases it (`catalyst-skills release <ticket> --because <what changed>`); if the fix is a decision, file an ask |
 | no change hold | a remediate round changed nothing | a human comment on the ticket, or a new push to the branch, releases it; say what should change |
 | validate class spent, stale failure episode | the repair budget for this failure is used, or the ladder moved on | read the outcome cards; usually a decision about the approach, so an ask |
 | waiting on | a merge-gate failure with no automatic repair | read the merge-wait comment and the PR's three legs through `catalyst-github` |
@@ -52,7 +52,7 @@ Before anything reaches the human, answer three questions:
 2. **Does this need to block at all?** If a sane default exists, take it, record it, and file the ask anyway so the human can overrule; the work does not wait.
 3. **Who else can move this?** Another steward, the desk, a repository owner. Pulling in a peer is preferred over pulling in the human.
 
-Only a genuine product, priority or approval decision, or an action only a human can physically take (release a cloud park, resolve a repository setting, apply the release label, answer a merge policy question), survives to become an ask.
+Only a genuine product, priority or approval decision, or an action only a human can physically take (close a person's own pull request, read a review that will not converge, resolve a repository setting, apply the release label, answer a merge policy question), survives to become an ask.
 
 ## When a stall becomes an ask
 

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

@@ -10,6 +10,7 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE_NAME = "@catalyst-cloud/catalyst-skills";
 export const NOT_CONFIGURED_EXIT = 2;
@@ -33,7 +34,7 @@ export function loadCustomerConfig() {
   if (!existsSync(path)) return null;
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (!parsed || typeof parsed !== "object" || typeof parsed.key !== "string" || typeof parsed.account !== "string") return null;
+    if (!hasCredential(parsed) || typeof parsed.account !== "string") return null;
     return parsed;
   } catch {
     return null;
@@ -44,7 +45,7 @@ export function loadCustomerConfig() {
 export function requireConfigured() {
   const cfg = loadCustomerConfig();
   if (cfg) return cfg;
-  console.error(`not connected: ${configPath()} is missing or unreadable — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE_NAME} login`);
+  console.error(`not connected: ${configPath()} is missing or unreadable — run: ${CONNECT_COMMAND}`);
   process.exit(NOT_CONFIGURED_EXIT);
 }
 

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

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
+// session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
+// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// itself. A new credential kind lands here, once.
+
+/** The command that connects this machine, as every not-connected line names it. */
+export const CONNECT_COMMAND =
+  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/unstick/SKILL.md

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

package/skills/unstick/agents/openai.yaml

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

package/skills/unstick/agents/portability.yaml

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

package/skills/unstick/references/playbook.md

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

package/skills/unstick/scripts/lib/cli.mjs

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

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
+// session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
+// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// itself. A new credential kind lands here, once.
+
+/** The command that connects this machine, as every not-connected line names it. */
+export const CONNECT_COMMAND =
+  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/unstick/scripts/unstick.mjs

@@ -0,0 +1,57 @@
+#!/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/scripts/lib/cli.mjs

@@ -6,6 +6,7 @@
 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;
@@ -21,7 +22,7 @@ export function loadConfig() {
   if (!existsSync(path)) notConfigured(`no config at ${path}`);
   try {
     const cfg = JSON.parse(readFileSync(path, "utf8"));
-    if (typeof cfg !== "object" || cfg === null || typeof cfg.key !== "string") notConfigured(`config at ${path} has no key`);
+    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;
@@ -30,7 +31,7 @@ export function loadConfig() {
 }
 
 function notConfigured(why) {
-  process.stderr.write(`not connected (${why}) — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login\n`);
+  process.stderr.write(`not connected (${why}) — run: ${CONNECT_COMMAND}\n`);
   process.exit(NOT_CONFIGURED_EXIT);
 }