@catalyst-cloud/cli 0.8.0

package/skills/catalyst-github/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: catalyst-github
+description: >-
+  Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
+allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+---
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.8.0 — written in this repository for customer tenants -->
+
+# Catalyst's GitHub
+
+You answer for the pull requests Catalyst opens and moves. The person asking wants to see one PR, know what is red, and know whether it will merge. Everything tenant-specific (the reviewer's login, the merge policy per repository, the four PR label names, the required checks) comes from the contract at run time and is printed by the scripts; you never restate it from memory.
+
+## Run first
+
+- `node scripts/read-pr.mjs --help` — a ticket's PR (or a PR by node id): state, branch, head, linked ticket, GitHub's mergeable state, every check, status and review. `--all` lists every PR for a ticket.
+- `node scripts/is-it-mergeable.mjs --help` — the three legs (checks, reviewer signal, unresolved threads) judged under the repository's policy, plus the prerequisites; exit 1 when a leg is red.
+
+Both read through `catalyst-skills query`, `contract` and, when fresh, `replica`; the first stderr line names the source, and your answer repeats it.
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| the person asks what Catalyst did to the branch or PR, why the title changed, why history was rewritten, what a label means, or what happens on merge | `references/what-a-pr-accumulates.md` |
+| the person asks why a PR has not merged, what the queue needs, what a clean review pass looks like, or what a policy requires | `references/is-it-mergeable.md` |
+
+## Rules
+
+- Never compose a URL or call the API yourself. Every read is a `catalyst-skills` verb behind a script; run the script, do not read it.
+- A queue-ready label is the cloud's attestation, never a lever you apply; "merged by the queue" is the terminal signal.
+- Hold labels are the human's lever. Describe them; do not apply or remove them.
+- Say what a key cannot see by name (PR labels, the reviewer's reaction, the queue's own state); never guess it.
+- An inconclusive leg is not a red one. Report "not proven from this read" and name what would settle it.
+- Never poll. To wait on a merge, subscribe through the project-running skill's watch; do not re-run a script in a loop.
+- Cite the PR as `<owner/name>#<number>` and the ticket by its identifier.

package/skills/catalyst-github/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Catalyst's GitHub"
+  short_description: "Show a ticket's pull request with its checks, reviews and threads, and say whether it is mergeable under this repository's policy"
+  default_prompt: "Use $catalyst-github to show me the PR for this ticket and whether it can merge."
+policy:
+  allow_implicit_invocation: true

package/skills/catalyst-github/agents/portability.yaml

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

package/skills/catalyst-github/references/is-it-mergeable.md

@@ -0,0 +1,57 @@
+# Is it mergeable?
+
+The rule is invariant; the policy that applies to a repository is not. The policy names, the default, each repository's resolved policy and its source (repository setting, tenant setting, or the default), the reviewer login and the required check names all come from the contract's `merge` block at run time. `node scripts/is-it-mergeable.mjs <ticket>` reads them and prints one line per leg; the text below explains what those lines mean.
+
+## Prerequisites before any leg counts
+
+A merge queue never takes a PR that is closed, still a draft, or in conflict with its base branch, and neither does the cloud's evaluator. The script reports these first: the pr phase is what marks a draft ready for review; a conflict (GitHub reports the mergeable state as dirty) is repaired by a remediate round that rebases the branch.
+
+## The three legs
+
+Merge evidence has three independent legs. Two are unconditional under every policy; the third is what the policy decides.
+
+| leg | passes when | always required? |
+| -- | -- | -- |
+| checks | every gating check at the current head completed with a non-failing conclusion (success, neutral or skipped count as non-failing). A pending check, or an empty set, is unknown, never green. The queue's own status check is not evidence about the PR and is excluded. | yes |
+| reviewer | the reviewer signal the policy accepts (below) | only under a reviewer-attestation policy |
+| threads | zero unresolved review threads, and no resolved thread whose resolving commit has left the head | yes |
+
+Which checks are gating: the names the queue configuration itself requires, plus any extra gating check the cloud names. The contract serves the checks the cloud's own remediation waits on as `cloudRemediateRequiredChecks`; a check that cannot block a merge is informational and never a reason to withhold the label.
+
+## The policies
+
+Three policy names are served on `merge.policies`; the default is `merge.defaultPolicy`; a repository's own is `merge.repositories[].policy` with `policySource` saying where it came from. Read them from the contract; do not assume a repository is on the default.
+
+| policy as served today | reviewer leg passes when |
+| -- | -- |
+| the default (an attestation policy) | a clean pass at the current head, or findings raised on an earlier head together with green checks and zero unresolved threads. In plain terms: the reviewer found something, the fix landed, every thread it raised is resolved, and the checks are green at the current head. That PR re-earns eligibility on its own; nobody has to ask the reviewer again. |
+| the strict variant | a clean pass at the current head, always. Findings on an earlier head keep blocking until the reviewer looks again. |
+| checks and threads only | the reviewer requirement is dropped entirely; the two unconditional legs decide. |
+
+A clean pass is a reaction: a thumbs-up from the reviewer login posted at or after the head commit's own timestamp. The comment-shaped clean pass ("no major issues" in place of threads) is honoured only if `cleanPassShapes[]` says so for that kind; the script does not judge it either way.
+
+## What the script can and cannot see
+
+The mirrored PR detail carries checks, legacy commit statuses, review objects with their state, GitHub's mergeable state and the auto-merge flag. It does not carry reactions, PR labels, or the commit each review was submitted against. So:
+
+- checks: judged fully from the detail.
+- reviewer: reported as inconclusive unless the policy waives it. The script says whether the reviewer left review objects, but whether a clean-pass reaction followed, and whether those reviews stand at the current head or an earlier one, is not mirrored.
+- threads: read from the local replica's review-thread rows when the replica is fresh (resolved flag per thread); inconclusive otherwise, with the command that starts the replica. Thread ancestry against force-pushes is judged by the cloud, not here.
+
+The exit code is 1 only for a proven-red leg or prerequisite. An inconclusive leg leaves exit 0 and a verdict that says "not proven mergeable from this read". The cloud's own evaluator, which holds the reaction and the ancestry, is the authority; a queue-ready label on the PR means it already said yes.
+
+## What happens after the label
+
+Once the cloud's merge phase applies the queue-ready label, four events each wake one bounded remediate round with no operator in the loop: a required check turning red, a fresh conflict with the base branch, a non-clean review, and a dequeue by the queue. The round repairs what it can, pushes, and the PR re-enters the queue itself. A scheduled sweep is the independent backstop for a labelled PR that is not moving. A hand-posted review request is never the required unblock for the ordinary shape.
+
+## The levers a human has
+
+- The hold label keeps an eligible PR out of the queue; removing it lets the PR enter on its own.
+- The preview label requests a preview and holds the merge; removing it is the approval.
+- Replying on a review thread and re-resolving it re-attests that thread against the current head.
+- A comment on the ticket releases a remediate round that changed nothing, and a validate hold.
+- A path the queue excludes is merged by hand; the cloud marks such a PR with the hand-steps hold automatically.
+
+## Reading the answer
+
+Lead with the verdict line, then the red legs with what unblocks each, then the inconclusive ones with what would settle them. Name the policy and where it came from. Say which source the read used (the first stderr line). If the person wants to wait for the merge, subscribe through the project-running skill's watch rather than re-running this script in a loop.

package/skills/catalyst-github/references/what-a-pr-accumulates.md

@@ -0,0 +1,61 @@
+# What a pull request accumulates as Catalyst moves a ticket
+
+Most of this page restates invariants: how Catalyst names branches, opens and rewrites pull requests, and what it pushes when. The parts that vary per tenant are read live from the contract's `merge` block and never restated here: the reviewer's login (`merge.reviewerLogin`), which clean-pass shapes are honoured (`merge.cleanPassShapes[]`), the four PR label names (`merge.prLabels`), the checks the cloud waits on (`merge.cloudRemediateRequiredChecks`), and the policy per repository (`merge.repositories[]`, else `merge.defaultPolicy`). `catalyst-skills contract --path merge` prints them.
+
+## The branch
+
+The branch is named exactly the ticket identifier, with no prefix: ticket `ABC-123` works on branch `ABC-123`. It is created by the implement phase once that phase has changes to push. A ticket that has never reached implement has no branch, which is why an eligibility explanation can say a branch is missing: nothing is wrong, nothing has run yet.
+
+A separate work-in-progress namespace exists for runner scratch pushes; a pull request is never opened from it.
+
+## The pull request, phase by phase
+
+| phase | what it does to the PR |
+| -- | -- |
+| implement | pushes the branch and opens a draft PR with a placeholder. The title is Conventional-Commit shaped: `feat(<scopes>): <ticket> — <ticket title>`, scopes derived from the changed top-level app or package directories (at most three), the whole title capped at 110 characters. The body says the description is pending from the pr phase. |
+| validate | runs the gate and writes its report; touches the PR only through the checks the push triggers. |
+| pr | writes the real title and body from its own artifact (first line the title, then the body), rebases the branch onto the current base, force-pushes, updates the PR, and marks it ready for review. |
+| remediate | repairs one failure class (a red check, a conflict, review findings, a dequeue) and pushes with a compare-and-swap force push, so a push that raced it is never overwritten. |
+| merge | evaluates the evidence below and, when it is sufficient, applies the queue-ready label. It performs no merge itself. |
+
+No `Closes <ticket>` trailer is inserted. The ticket reaches Done through the merge webhook, not through any phase (see the last section).
+
+## Force-pushes are routine
+
+Three phases rewrite history on the ticket branch: implement pushes fresh with force, pr rebases and force-pushes, remediate force-pushes with a lease. Two consequences a reader must hold:
+
+- A review thread resolved against one commit may stop being evidence once the head moves. Catalyst walks the PR's own force-push timeline: a rebase that carries the same fix forward still counts; a force-push that dropped the fix does not, and the refusal names the thread and both commits. Replying on the thread and re-resolving it re-attests against the current head.
+- A check result belongs to a head. After any push, the checks at the new head start from nothing; "no check has reported yet" is unknown, never green.
+
+## The reviewer signal
+
+An automated reviewer (login from the contract) reviews every PR. Its signal is one of four: clean, findings at the current head, findings at an earlier head, no review. A clean pass is a reaction, not a review object: a thumbs-up from the reviewer posted at or after the head commit's own timestamp. A second shape, a terse "no major issues" comment in place of review threads, exists as a documented convention; whether it is honoured is served on `cleanPassShapes[].honoured` and must be read there, never assumed. What counts under each policy is on `references/is-it-mergeable.md`.
+
+## Labels on the PR
+
+Four labels matter, all named on `merge.prLabels`, all matched exactly (a queue's label conditions are exact matches, which is why every hold has its own name):
+
+| contract field | who applies it | meaning |
+| -- | -- | -- |
+| `queueReady` | the cloud's merge phase, once its own evidence gate passes | an attestation that the evidence was sufficient. It is not a lever: applying it by hand makes nothing merge that would not have merged, and removing it is not a hold. |
+| `hold` | a human | the one manual escape hatch. An eligible PR stays out of the queue while it carries this. |
+| `handStepsHold` | the cloud, automatically | the PR touches a path the queue configuration excludes (schema or migration paths, typically), so a person has to merge it by hand. |
+| `preview` | a human | "deploy me a preview and hold the merge until I have looked". Removing the label is the approval. |
+
+The mirror does not carry PR labels or reactions, so your key cannot read which holds a PR carries or whether the reviewer reacted; the scripts say so by name. GitHub's own page, or the tenant's settings, is where those live.
+
+## The queue is optional and opt-out
+
+When a repository runs a merge queue, entry is opt-out: a PR against the base branch that is green on its required checks, not a draft, has zero unresolved review threads, carries no hold label, and touches no excluded path enters the queue on its own. Nobody applies a label to make that happen. The terminal signal is the queue's own merge ("merged by" the queue bot), not any return value from a merge command. Without a queue, the queue-ready label is still the cloud's attestation and the merge itself is whatever the repository's own setup does with it.
+
+## After the label
+
+A problem after the attestation does not wait on a person noticing. A red required check, a fresh conflict with the base branch, a non-clean review, or a dequeue by the queue each wakes one bounded remediate round automatically, which repairs what it can, re-pushes, and re-enters the queue itself. An independent scheduled sweep remains as a backstop for a PR that carries the label and is going nowhere. Hand-posting a review request to the reviewer is never the required unblock for the ordinary remediation shape.
+
+## What happens on merge
+
+The ticket moves to Done when the real merge webhook arrives, keyed to the pull request's merged event, with a bounded sweep as the backstop for a dropped webhook. Measured latency is a few seconds. A phase never writes Done; a ticket still not Done a minute after its PR merged is a finding, not a chore. Done is not the same as live: a change to a service deploys on its own pipeline after the merge.
+
+## Reading a PR through this skill
+
+`node scripts/read-pr.mjs <ticket>` follows the ticket's own record to the pull requests that name it, picks the open one (else the merged one, else the newest), and prints the mirrored detail: state, draft and merged flags, branch and base, head commit, the linked ticket and its stage, GitHub's own mergeable state and auto-merge flag, every check with status and conclusion, legacy commit statuses, and every mirrored review with its state. `--all` lists every PR for the ticket; `--json` prints the raw document. The first stderr line names the source, a fresh replica or the API, and the answer should repeat it.

package/skills/catalyst-github/scripts/is-it-mergeable.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// is-it-mergeable.mjs — the three legs of merge evidence for one PR (checks, reviewer signal,
+// unresolved threads) judged under the policy the tenant contract resolves for its repository, plus
+// the prerequisites a queue applies before any leg counts (open, not a draft, no conflict). Every
+// input comes from `catalyst-skills query`, `contract` and, when fresh, `replica sql`.
+// Exit 0 no leg is red, 1 a leg or prerequisite is red, 2 this machine is not connected.
+import { parseJson, runCli, runCliOrExit } from "./lib/cli.mjs";
+import { resolvePull, truthy } from "./lib/pull.mjs";
+
+const HELP = `Usage: node scripts/is-it-mergeable.mjs <ticket | pr-node-id> [--json]
+
+Judges one pull request against the merge policy the tenant contract resolves for its repository:
+  checks     every gating check at the head completed without failing (pending or absent is not green)
+  reviewer   the reviewer signal the policy requires; the clean-pass reaction itself is not mirrored,
+             so this leg is reported as inconclusive rather than guessed, unless the policy waives it
+  threads    zero unresolved review threads, read from the local replica when it is fresh
+
+A red prerequisite (closed, draft, merge conflict) is also exit 1. Inconclusive legs never fail the
+exit code; the cloud's own evaluator, which holds the reaction and the thread ancestry, is authoritative.
+--json prints {pr, policy, legs[], verdict} instead of lines.`;
+
+const args = process.argv.slice(2);
+if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+  console.log(HELP);
+  process.exit(0);
+}
+const json = args.includes("--json");
+const target = args.find((a) => !a.startsWith("--"));
+if (!target) {
+  console.error("is-it-mergeable needs a ticket or a PR node id");
+  process.exit(1);
+}
+
+const { ticket, detail } = resolvePull(target);
+const merge = parseJson(runCliOrExit(["contract", "--path", "merge", "--json"]).stdout);
+if (!merge || !Array.isArray(merge.policies)) {
+  console.error("the contract's merge block did not parse; run: catalyst-skills contract --refresh");
+  process.exit(1);
+}
+
+const repoId = String(detail.repo_id ?? "");
+const repoRow = (merge.repositories ?? []).find((r) => `${r.owner}/${r.name}`.toLowerCase() === repoId.toLowerCase());
+const policy = repoRow?.policy ?? merge.defaultPolicy;
+const policySource = repoRow ? repoRow.policySource : "default";
+const requiresReviewer = policy !== "checks-and-threads";
+const acceptsEarlierHead = policy === "codex-attestation";
+
+const legs = [];
+const add = (leg, state, line) => legs.push({ leg, state, line });
+
+// ── prerequisites the queue applies before any leg counts ──────────────────────────────────────
+if (truthy(detail.merged)) {
+  add("state", "pass", `already merged${detail.merged_at ? ` at ${new Date(Number(detail.merged_at)).toISOString()}` : ""}; nothing left to judge`);
+} else {
+  const state = String(detail.state ?? "").toLowerCase();
+  if (state && state !== "open") add("state", "fail", `the PR is ${state}, not open`);
+  else if (truthy(detail.draft)) add("state", "fail", "the PR is still a draft; the pr phase marks it ready for review, a queue never takes a draft");
+  else add("state", "pass", "open and ready for review");
+  const ms = String(detail.mergeable_state ?? "").toLowerCase();
+  if (ms === "dirty" || detail.mergeable === false || detail.mergeable === 0) add("conflict", "fail", `GitHub reports a merge conflict with the base branch (mergeable_state=${ms || "unknown"}); a remediate round rebases it`);
+  else if (ms) add("conflict", "pass", `GitHub reports mergeable_state=${ms}`);
+  else add("conflict", "inconclusive", "GitHub has not reported a mergeable state for this head yet");
+}
+
+// ── leg 1: checks ───────────────────────────────────────────────────────────────────────────────
+const checks = Array.isArray(detail.checks) ? detail.checks : [];
+const required = Array.isArray(merge.cloudRemediateRequiredChecks) ? merge.cloudRemediateRequiredChecks : [];
+const notQueue = checks.filter((c) => !/mergify|^queue:|^summary$/i.test(String(c.name ?? "")));
+const gating = notQueue.filter((c) => required.includes(String(c.name)));
+const judged = gating.length > 0 ? gating : notQueue;
+const ok = new Set(["success", "neutral", "skipped"]);
+const red = judged.filter((c) => String(c.status).toLowerCase() === "completed" && !ok.has(String(c.conclusion).toLowerCase()));
+const pending = judged.filter((c) => String(c.status).toLowerCase() !== "completed");
+const statuses = Array.isArray(detail.commit_statuses) ? detail.commit_statuses : [];
+const redStatuses = statuses.filter((s) => ["failure", "error"].includes(String(s.state).toLowerCase()));
+const scope = gating.length > 0 ? `the ${gating.length} required check(s) the contract names` : `every mirrored check (none of the contract's required names is present at this head)`;
+if (judged.length === 0 && redStatuses.length === 0) add("checks", "inconclusive", "no check has reported at this head; an unrun set is unknown, never green");
+else if (red.length > 0 || redStatuses.length > 0) add("checks", "fail", `red: ${[...red.map((c) => `${c.name} (${c.conclusion})`), ...redStatuses.map((s) => `${s.context} (${s.state})`)].join(", ")}`);
+else if (pending.length > 0) add("checks", "inconclusive", `still running: ${pending.map((c) => c.name).join(", ")} — judged over ${scope}`);
+else add("checks", "pass", `green over ${scope}`);
+
+// ── leg 2: the reviewer signal ─────────────────────────────────────────────────────────────────
+const reviews = Array.isArray(detail.reviews) ? detail.reviews : [];
+const login = String(merge.reviewerLogin ?? "");
+const byReviewer = reviews.filter((r) => String(r.reviewer_name ?? "") === login || String(r.reviewer_id ?? "") === `github:${login}`);
+if (!requiresReviewer) add("reviewer", "pass", `policy ${policy} needs no reviewer signal`);
+else if (byReviewer.length > 0) {
+  const states = [...new Set(byReviewer.map((r) => String(r.state ?? "?")))].join(", ");
+  add("reviewer", "inconclusive", `${login} left ${byReviewer.length} review object(s) (${states}); whether they stand at the current head or an earlier one, and whether a clean-pass reaction followed, is not mirrored${acceptsEarlierHead ? " — under this policy, findings on an earlier head plus green checks and zero unresolved threads are accepted" : " — this policy requires a clean pass at the current head"}`);
+} else add("reviewer", "inconclusive", `no review object from ${login} is mirrored; a clean pass is a reaction, which this read cannot see`);
+
+// ── leg 3: unresolved threads, from the replica when it is fresh ───────────────────────────────
+const replica = parseJson(runCli(["replica", "status", "--json"]).stdout);
+if (replica && replica.verdict === "fresh") {
+  const num = Number(detail.number);
+  const esc = repoId.replace(/'/g, "''");
+  const sql = `select resolved, count(*) as n from pr_review_threads where repo_id = '${esc}' and pr_number = ${Number.isInteger(num) ? num : -1} group by resolved`;
+  const rows = parseJson(runCli(["replica", "sql", sql, "--json"]).stdout) ?? [];
+  const count = (want) => rows.filter((r) => (want === null ? r.resolved === null || r.resolved === undefined : Number(r.resolved) === want)).reduce((a, r) => a + Number(r.n ?? 0), 0);
+  const unresolved = count(0);
+  const unknown = count(null);
+  if (unresolved > 0) add("threads", "fail", `${unresolved} unresolved review thread(s)`);
+  else if (unknown > 0) add("threads", "inconclusive", `${unknown} thread(s) with no resolved flag mirrored`);
+  else add("threads", "pass", `${count(1)} thread(s), all resolved (ancestry against force-pushes is judged by the cloud, not here)`);
+} else {
+  add("threads", "inconclusive", `the PR detail carries no thread count and the replica is ${replica?.verdict ?? "unavailable"}; start it (catalyst-skills replica start --detach) for a local read`);
+}
+
+const failed = legs.filter((l) => l.state === "fail");
+const open = legs.filter((l) => l.state === "inconclusive");
+let verdict;
+if (failed.length > 0) verdict = `NOT MERGEABLE: ${failed.map((l) => l.leg).join(", ")}`;
+else if (open.length > 0) verdict = `NOT PROVEN MERGEABLE from this read (${open.map((l) => l.leg).join(", ")} inconclusive); the cloud's evaluator decides`;
+else verdict = "MERGEABLE as far as this read can see";
+
+const header = `${repoId}#${detail.number ?? "?"}${ticket ? ` (${ticket})` : ""} head ${String(detail.head_sha ?? "").slice(0, 12)} — policy ${policy} (${policySource})`;
+if (json) {
+  console.log(JSON.stringify({ pr: { repo_id: repoId, number: detail.number, node_id: detail.node_id, ticket, head_sha: detail.head_sha }, policy: { name: policy, source: policySource }, legs, verdict }));
+} else {
+  console.log(header);
+  for (const l of legs) console.log(`${l.state === "pass" ? "ok  " : l.state === "fail" ? "FAIL" : "?   "}  ${l.leg}: ${l.line}`);
+  console.log(verdict);
+}
+process.exit(failed.length > 0 ? 1 : 0);

package/skills/catalyst-github/scripts/lib/cli.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches the Catalyst Cloud SDK and API: by spawning the
+// catalyst-skills CLI this bundle installed. It reads customer.json to find that CLI and nothing
+// else; it never holds the key itself. This file is a library — run a sibling script with
+// --help for usage. Identical in every skill of this bundle on purpose (skills install one directory
+// at a time, so nothing shared outside the skill would ever be installed).
+import { spawnSync } 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 = "@catalyst-cloud/catalyst-skills";
+export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: ${CONNECT_COMMAND}`;
+
+/** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
+export function configPath() {
+  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? process.env.USERPROFILE ?? "";
+  return join(home, ".config", "catalyst-cloud", "customer.json");
+}
+
+/** The customer config, or exit 2 with one line naming the connect command. Never throws. */
+export function requireCustomerConfig() {
+  const path = configPath();
+  if (!existsSync(path)) {
+    console.error(CONNECT_HINT);
+    process.exit(2);
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    console.error(`${path} could not be read (${err instanceof Error ? err.message : String(err)}) — ${CONNECT_HINT}`);
+    process.exit(2);
+  }
+  if (!hasCredential(cfg) || typeof cfg.baseUrl !== "string") {
+    console.error(`${path} is missing required fields — ${CONNECT_HINT}`);
+    process.exit(2);
+  }
+  return cfg;
+}
+
+/**
+ * Run one catalyst-skills verb and return {code, stdout, stderr}. Spawns the CLI whose path the
+ * connect step recorded in customer.json; falls back to `npx @catalyst-cloud/catalyst-skills` when
+ * no path is recorded or it no longer exists. Exits 2 when the machine is not connected.
+ */
+export function runCli(args, opts = {}) {
+  const cfg = requireCustomerConfig();
+  const recorded = typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
+  const command = recorded ? process.execPath : process.platform === "win32" ? "npx.cmd" : "npx";
+  const argv = recorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
+  const res = spawnSync(command, argv, {
+    encoding: "utf8",
+    input: opts.stdin,
+    env: process.env,
+    maxBuffer: 64 * 1024 * 1024,
+    shell: !recorded && process.platform === "win32",
+  });
+  if (res.error) {
+    console.error(`could not run ${recorded ? cfg.cliPath : `npx ${PACKAGE}`}: ${res.error.message}`);
+    process.exit(2);
+  }
+  return { code: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+
+/**
+ * Run a verb that must succeed. On exit 2 (the CLI's "not configured / refused" class) the script
+ * exits 2; on any other non-zero exit it exits 1. The CLI's own stderr is forwarded either way so the
+ * reason is never lost.
+ */
+export function runCliOrExit(args, opts = {}) {
+  const res = runCli(args, opts);
+  if (res.code === 0) return res;
+  const why = res.stderr.trim() || res.stdout.trim() || `catalyst-skills ${args.join(" ")} exited ${res.code}`;
+  console.error(why);
+  process.exit(res.code === 2 ? 2 : 1);
+}
+
+/** Parse the CLI's --json stdout; null when it is not JSON (the caller decides what that means). */
+export function parseJson(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}
+
+/** Forward the `source: replica|api (...)` line a query verb prints, so the answer names its source. */
+export function forwardSourceLine(res) {
+  for (const line of res.stderr.split("\n")) {
+    if (line.startsWith("source:")) console.error(line);
+  }
+}
+
+/** True for a ticket identifier such as ABC-123; false for a GitHub node id or anything else. */
+export function looksLikeTicket(s) {
+  return /^[A-Za-z][A-Za-z0-9]*-\d+$/.test(s);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  console.log("lib/cli.mjs is a library used by the scripts beside it; run any of those with --help for usage.");
+}

package/skills/catalyst-github/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/catalyst-github/scripts/lib/pull.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// lib/pull.mjs — resolve "a ticket or a PR id" to one mirrored pull-request detail, the way both
+// scripts in this skill need it. A ticket resolves through its own record's linked pull requests
+// (the mirror links a PR to the ticket its text names), then the chosen PR's detail is read by node
+// id. A library: run read-pr.mjs or is-it-mergeable.mjs with --help for usage.
+import { fileURLToPath } from "node:url";
+import { forwardSourceLine, looksLikeTicket, parseJson, runCli, runCliOrExit } from "./cli.mjs";
+
+export function truthy(v) {
+  return v === true || v === 1 || v === "1" || v === "true";
+}
+
+function readIssue(ticket, extra = []) {
+  const res = runCli(["query", "issue", ticket, ...extra, "--json"]);
+  forwardSourceLine(res);
+  if (res.code !== 0) {
+    console.error(res.stderr.trim() || `${ticket}: not found`);
+    process.exit(res.code === 2 ? 2 : 1);
+  }
+  const issue = parseJson(res.stdout);
+  if (!issue || typeof issue !== "object") {
+    console.error(`${ticket}: the ticket read did not return JSON`);
+    process.exit(1);
+  }
+  return issue;
+}
+
+/**
+ * Every PR that names the ticket, newest number first. Exits 1 when the ticket is unknown. A source
+ * whose ticket detail carries no `linked_pulls` field at all (a replica built by an SDK that predates
+ * the ticket-to-PR link) is not evidence of "no PR": the ticket is re-read from the API, which is
+ * origin-fresh and carries the field, and the second source line says so. An empty list from a source
+ * that has the field is a real "no PR yet".
+ */
+export function linkedPulls(ticket) {
+  let issue = readIssue(ticket);
+  if (issue.linked_pulls === undefined) {
+    console.error("note: this source carries no linked pull requests on a ticket; re-reading the ticket from the API");
+    issue = readIssue(ticket, ["--source", "api"]);
+  }
+  const pulls = Array.isArray(issue.linked_pulls) ? issue.linked_pulls : [];
+  return { issue, pulls: [...pulls].sort((a, b) => Number(b.number ?? 0) - Number(a.number ?? 0)) };
+}
+
+/** The PR that matters for a ticket: an open one first, else the merged one, else the newest. */
+export function pickPull(pulls) {
+  const open = pulls.find((p) => String(p.state ?? "").toLowerCase() === "open" && !truthy(p.merged));
+  if (open) return open;
+  const merged = pulls.find((p) => truthy(p.merged));
+  return merged ?? pulls[0] ?? null;
+}
+
+/** One PR's detail by node id: checks, reviews, commit statuses, mergeable state, linked ticket. */
+export function pullDetail(nodeId) {
+  const res = runCliOrExit(["query", "pull", nodeId, "--json"]);
+  forwardSourceLine(res);
+  const detail = parseJson(res.stdout);
+  if (!detail || typeof detail !== "object") {
+    console.error(`${nodeId}: the pull read did not return JSON`);
+    process.exit(1);
+  }
+  return detail;
+}
+
+/** Ticket or node id → {ticket, detail, linked}. Exits 1 when a ticket has no PR yet. */
+export function resolvePull(arg) {
+  if (looksLikeTicket(arg)) {
+    const { pulls } = linkedPulls(arg);
+    const chosen = pickPull(pulls);
+    if (!chosen) {
+      console.error(`${arg}: no pull request names this ticket yet — the implement phase opens one when it has a branch`);
+      process.exit(1);
+    }
+    return { ticket: arg, detail: pullDetail(String(chosen.node_id)), linked: pulls };
+  }
+  const detail = pullDetail(arg);
+  return { ticket: detail.linear_issue_identifier ? String(detail.linear_issue_identifier) : null, detail, linked: [] };
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  console.log("lib/pull.mjs is a library used by read-pr.mjs and is-it-mergeable.mjs; run those with --help for usage.");
+}

package/skills/catalyst-github/scripts/read-pr.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// read-pr.mjs — one ticket's pull request (or one PR by node id) as the mirror holds it: state,
+// branch, head, base, linked ticket and its stage, GitHub's own mergeable verdict, every check,
+// review and commit status. Reads through `catalyst-skills query`; composes no URL.
+import { linkedPulls, resolvePull, truthy } from "./lib/pull.mjs";
+
+const HELP = `Usage: node scripts/read-pr.mjs <ticket | pr-node-id> [--all] [--json]
+
+  <ticket>       a ticket identifier such as ABC-123: its open PR is shown (else the merged one, else the newest)
+  <pr-node-id>   a GitHub pull-request node id, as printed by "catalyst-skills query pulls"
+  --all          for a ticket: list every PR that names it instead of one detail
+  --json         print the raw detail document instead of the summary
+
+Exit 0 shown, 1 not found or no PR yet, 2 this machine is not connected to a tenant.
+The first stderr line names the source the CLI read from (a fresh replica, or the API).`;
+
+const args = process.argv.slice(2);
+if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+  console.log(HELP);
+  process.exit(0);
+}
+const json = args.includes("--json");
+const all = args.includes("--all");
+const target = args.find((a) => !a.startsWith("--"));
+if (!target) {
+  console.error("read-pr needs a ticket or a PR node id");
+  console.log(HELP);
+  process.exit(1);
+}
+
+function fmt(v, fallback = "?") {
+  return v === null || v === undefined || v === "" ? fallback : String(v);
+}
+
+function when(ms) {
+  const n = Number(ms);
+  return Number.isFinite(n) && n > 0 ? new Date(n).toISOString() : fmt(ms, "");
+}
+
+if (all) {
+  if (!/^[A-Za-z][A-Za-z0-9]*-\d+$/.test(target)) {
+    console.error("--all takes a ticket identifier");
+    process.exit(1);
+  }
+  const { pulls } = linkedPulls(target);
+  if (json) {
+    console.log(JSON.stringify(pulls));
+    process.exit(0);
+  }
+  if (pulls.length === 0) {
+    console.log(`${target}: no pull request names this ticket yet`);
+    process.exit(1);
+  }
+  for (const p of pulls) {
+    const flags = [truthy(p.draft) ? "draft" : null, truthy(p.merged) ? "merged" : null].filter(Boolean).join(" ");
+    console.log(`${fmt(p.repo_id)}#${fmt(p.number)}  ${fmt(p.state)}${flags ? ` ${flags}` : ""}  ${fmt(p.title, "")}  [${fmt(p.node_id, "")}]`);
+  }
+  process.exit(0);
+}
+
+const { ticket, detail } = resolvePull(target);
+if (json) {
+  console.log(JSON.stringify(detail));
+  process.exit(0);
+}
+
+const checks = Array.isArray(detail.checks) ? detail.checks : [];
+const reviews = Array.isArray(detail.reviews) ? detail.reviews : [];
+const statuses = Array.isArray(detail.commit_statuses) ? detail.commit_statuses : [];
+const state = [fmt(detail.state), truthy(detail.draft) ? "draft" : null, truthy(detail.merged) ? `merged ${when(detail.merged_at)}` : null].filter(Boolean).join(", ");
+
+console.log(`${fmt(detail.repo_id)}#${fmt(detail.number)}  ${fmt(detail.title, "(no title yet)")}`);
+console.log(`state: ${state}  by ${fmt(detail.author_login)}  opened ${when(detail.created_at)}  updated ${when(detail.updated_at)}`);
+console.log(`branch: ${fmt(detail.head_ref)} → ${fmt(detail.base_ref)}  head ${fmt(detail.head_sha).slice(0, 12)}`);
+console.log(`ticket: ${fmt(ticket ?? detail.linear_issue_identifier, "none named")}${detail.linked_issue_state ? ` (stage: ${detail.linked_issue_state})` : ""}`);
+console.log(`github says: mergeable=${fmt(detail.mergeable, "unknown")} state=${fmt(detail.mergeable_state, "unknown")} auto-merge=${truthy(detail.auto_merge) ? "on" : "off"}`);
+if (detail.blocked_on_ask && typeof detail.blocked_on_ask === "object") {
+  const b = detail.blocked_on_ask;
+  console.log(`blocked on an ask: ${fmt(b.identifier ?? b.id, "")} ${fmt(b.title, "")}`.trim());
+}
+console.log(`node id: ${fmt(detail.node_id)}`);
+
+console.log(`checks (${checks.length}):`);
+if (checks.length === 0) console.log("  none reported at this head yet");
+for (const c of checks) console.log(`  ${fmt(c.status)}/${fmt(c.conclusion, "-")}  ${fmt(c.name)}`);
+
+if (statuses.length > 0) {
+  console.log(`commit statuses (${statuses.length}):`);
+  for (const s of statuses) console.log(`  ${fmt(s.state)}  ${fmt(s.context)}`);
+}
+
+console.log(`reviews (${reviews.length}):`);
+if (reviews.length === 0) console.log("  none mirrored; a reviewer's clean pass is a reaction, which this read does not carry");
+for (const r of reviews) console.log(`  ${fmt(r.state)}  ${fmt(r.reviewer_name, fmt(r.reviewer_id))}  ${when(r.submitted_at)}`);
+
+console.log("not mirrored here: PR labels (holds, queue attestation) and the reviewer's reaction — see references/what-a-pr-accumulates.md");
+process.exit(0);