@catalyst-cloud/catalyst-skills 0.1.1 → 0.2.0

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,102 @@
+#!/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 account 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";
+
+export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: CATALYST_CLOUD_TOKEN=<account key> npx ${PACKAGE} login`;
+
+/** ~/.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 (!cfg || typeof cfg !== "object" || typeof cfg.key !== "string" || 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/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 visible to an account key here: PR labels (holds, queue attestation) and the reviewer's reaction — see references/what-a-pr-accumulates.md");
+process.exit(0);

package/skills/catalyst-linear/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: catalyst-linear
+description:
+  Catalyst's view of Linear on the customer's own tenant. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the local replica when it is fresh and the origin-fresh API otherwise, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the tenant's agent proxy as the app actor, with every route, stage id, label id and marker read from the tenant contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
+allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+disable-model-invocation: true
+---
+<!-- vendored-from: @catalyst-cloud/catalyst-skills — written in this repository for customer tenants -->
+
+# Catalyst Linear
+
+You read tickets and write to them on the customer's tenant, as Catalyst. Reads come from the replica when it is fresh, else from the API, and every read names its source. Writes go through the tenant's agent proxy as the app actor, with routes, stage ids, label ids and the bookkeeping marker resolved from the tenant contract by the `catalyst-skills` CLI. You never compose a URL, never name a stage by its display name, and never quote a label id or marker from memory.
+
+## Run first
+
+Run each with `--help` first; scripts are executed, never read.
+
+- `node scripts/read-ticket.mjs <ticket> [--comments]` — one ticket, everything inline, source line on stderr.
+- `node scripts/search.mjs <terms>` — tickets, PRs, projects, initiatives matching the terms.
+- `node scripts/comment.mjs <ticket> --body <text> [--parent <id>] [--bookkeeping]` — a comment as the app actor; a machine record takes `--bookkeeping`.
+- `node scripts/move.mjs <ticket> --slot <slot>` — a card move by slot (`--state-type backlog` parks).
+- `node scripts/label.mjs <ticket> --add <name> --remove <name>` — labels, resolved through the contract.
+- `node scripts/create-ticket.mjs --team <key> --title <text>` — a new ticket; cite its identifier only after it prints.
+
+Exit codes: 0 done, 1 not found or a usage error, 2 this machine is not connected or the write was refused (budget spent, slot unmapped, label absent; the one line printed says which).
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| "what did Catalyst write on this ticket?", a comment shape, a label, the marker, the 👀 | `references/what-a-ticket-accumulates.md` |
+| before any read you will report on; "is this current?"; citing; searching | `references/reading-a-ticket.md` |
+| before any comment, move, label or new ticket; identity, budget, slots, ids | `references/writing-to-linear.md` |
+
+## Rules
+
+- **Read before acting.** Never summarise a ticket from its title; read the description and the thread. Cite identifiers and comment ids only after a script printed them.
+- **Name the source.** Quote the source line when freshness matters; a stale replica is never read silently, because the CLI falls back to the API and says so.
+- **Reply where it arrived, as Catalyst.** Thread under the comment you answer (`--parent`); never post as the human.
+- **Records carry the marker.** A merge note, a state-move log, a chain summary: `--bookkeeping`, so it never reads as a human turn. A real question is not bookkeeping.
+- **Move by slot, label by contract.** A stage name is display; the id is the authority, and the CLI resolves both. Moving to `dispatch` dispatches; the backlog-type state parks.
+- **A decision is an ask, not a ticket.** Raise it through `what-needs-me` with options, a default and what it blocks; a question filed as a ticket is held out of dispatch by shape.
+- **One write per need, no loops.** Writes spend a daily budget the contract names; batch, and report a refusal rather than retrying.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Catalyst Linear"
+  short_description: "Read a ticket and what Catalyst wrote on it; comment, move, label and file tickets as the app actor"
+  default_prompt: "Use $catalyst-linear to show me the ticket, its history, and what Catalyst wrote on it."
+policy:
+  allow_implicit_invocation: false

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

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

package/skills/catalyst-linear/references/reading-a-ticket.md

@@ -0,0 +1,50 @@
+# Reading a ticket: freshness first, then the row
+
+This reference restates invariants about how a read is made and reported. Nothing in it is a tenant value.
+
+## Freshness first
+
+Every `query` verb, and therefore `node scripts/read-ticket.mjs` and `node scripts/search.mjs`, prints one stderr line before the answer:
+
+- `source: replica (cursor N)` — the local replica was fresh (its writer heartbeat is young and its cursor non-empty), so the answer is local and cheap. N is the position it had applied.
+- `source: api (replica stale)`, `source: api (replica absent)` or `source: api (replica not configured)` — the answer came from the tenant API, which is origin-fresh: it reflects the mirror's latest ingest, not a cached copy.
+- `source: api (<verb> is api-only)` — search, cycles, pull detail and change feeds are never served from the replica.
+
+Read that line every time. A fresh replica is a preference; the API is the fallback and it is never wrong to read it. What is wrong is silently reading a stale replica, and the CLI does not let that happen: a stale replica falls back to the API and says so. Quote the source in your answer when the freshness of a fact matters ("as of the replica at cursor N" or "from the API just now").
+
+`--source replica` or `--source api` forces one. Forcing the replica when it is absent or stale is refused.
+
+## Then the row
+
+One ticket read returns the whole record: the fields, the description, `labels[]`, `relations[]`, `linked_pulls[]`, `comments[]`, `activity[]` and `agent_sessions[]` inline, plus the project, cycle, team, delegate and parent fields. One call answers "what is this ticket, what happened on it, what is it waiting on, which PR is it". There is no second call to make for the comments.
+
+The summary the script prints puts the counts first and the description last; `--comments` prints every comment with its id, author, time and whether the author is a bot. A comment with a `reply-to` marker is threaded under another; reply under the same parent when you answer it.
+
+## Reading Catalyst's own writes
+
+The comment shapes in `references/what-a-ticket-accumulates.md` tell you which comments are the cloud's. To answer "what happened to this ticket":
+
+1. Phase-outcome comments, newest first, give the attempts and their results.
+2. Remediate-attempt comments give the failure class each round repaired.
+3. The projection-link comments name the documents; open the document (it is attached to the ticket) to read what a phase actually concluded. A fallback comment carries the body inline instead.
+4. `linked_pulls[]` names the PR; `catalyst-github` reads it.
+5. For "what will it do next", leave this skill: `how-catalyst-works` explains the eligibility row.
+
+## When to read a transcript
+
+A phase's transcript (the full session log) exists in the cloud per ticket, but this bundle has no verb for it yet. Read the artifact document first; it is the phase's own account of what it did. Reach for the transcript only when the document leaves the question open, and say that the bundle cannot fetch it so the human opens it from the ticket's attachments.
+
+## What an account key cannot read
+
+Per-ticket execution history beyond the comments (the attempt ledger, the remediation round count against the cap, park state and what releases it) is not readable with an account key yet; `catalyst-skills explain --history <ticket>` prints that by name and where to read it. Do not reconstruct a round count from comments and present it as the cap's count.
+
+## How to cite
+
+- Cite a ticket by its identifier (`KEY-123`), never by title alone, and only after you read it back from a script's output.
+- Cite a comment by its id when you refer to it or reply under it.
+- Cite a document by the title the projection comment gave it.
+- Never summarise a ticket from its title. Read the description and the thread.
+
+## Searching and listing
+
+`node scripts/search.mjs <terms>` matches ticket identifiers and titles, PR titles, project and initiative names and returns a few of each. It is the only search; a list read with a filter is not a search and will hand back the ordinary first page, which reads as a false "not found". Lists (`catalyst-skills query issues --team <key>`, `query projects`, `query cycles`) are for a board view, not for finding one ticket.

package/skills/catalyst-linear/references/what-a-ticket-accumulates.md

@@ -0,0 +1,53 @@
+# What a ticket accumulates as Catalyst works it
+
+This reference restates invariants: the shapes of what the cloud writes onto a ticket. The one live value it needs — the bookkeeping marker and the label names — is on the contract under `vocabulary` and `teams[].labels`; print them with `catalyst-skills contract --path vocabulary` and `catalyst-skills contract --path teams`. Never quote a marker or a label id from memory.
+
+## Comments the cloud posts
+
+| Kind | When | How it opens |
+| -- | -- | -- |
+| Phase outcome | every phase attempt ends | `✅ **Phase complete**` or `🛑 **Phase FAILED**`, then `**Phase**`, an optional `**Attempt**`, `**Artifact**`, a quoted summary, and a park, hold or failure block when there is one; a footer names the event that produced it |
+| Remediate attempt | every remediation round ends | `🔧 **Remediate attempt N — SUCCEEDED**` or `FAILED`, then `**Class**` (the failure class being repaired) and optionally `**Repairing**` and `**Artifact**` |
+| Projection link | an artifact document was created in Linear | `**<phase>** · attempt N — [<title>](<document url>)`, then the storage key and the thoughts-repository path |
+| Projection fallback | Linear refused a document | `> ⚠️ **Fallback comment.** Linear refused a document for this artifact: <reason>` followed by the artifact body fenced inline |
+| Board health | a ticket sat in an active stage with no sign of life | `**Catalyst Cloud · board health**`, what stalled, and "Action taken" |
+| Merge wait | a hold at PR or merge named a cause | says what the merge is waiting on |
+| Ask reply | a human answered an ask | a threaded reply under the answer |
+
+Every one of these is posted by the app actor and is skipped by the comment-wake trigger; none of them wakes an agent.
+
+## One document per phase, attached
+
+Each artifact-bearing phase (research, plan, implement, validate, pr, remediate) projects its artifact into Linear as a document at a deterministic id, titled `<TICKET> · <phase> · attempt <n> · <YYYY-MM-DD>`, attached to the ticket, and announced by the projection-link comment above. Research and plan documents on a ticket that belongs to a project are also linked from the project. The same body is committed into the tenant's thoughts repository when one is configured. Reading the document is how you read what a phase concluded; the phase-outcome comment only summarises it.
+
+## The agent session
+
+A ticket being worked grows a Linear agent session whose **plan** is the ladder itself: phases before the current one completed, the current one in progress, later ones pending. A remediation round is an interrupt with no ladder position and anchors on the phase it interrupted. Activities record a phase starting, the gate running, an artifact being written, a PR being opened, and a terminal report. A session in a pending, active or awaiting-input status is reused; a stale, complete or errored one is replaced by a fresh session. Emission is best-effort: a failure to narrate never blocks a phase.
+
+## Labels
+
+| Role (contract name) | Who applies it | Meaning |
+| -- | -- | -- |
+| ask marker (`vocabulary.askMarkerLabel`, listed under `teams[].labels.ask`) | the cloud, atomically when it files an ask; or a human filing one by hand | this ticket is a question for a human, never work |
+| ask kind family (`vocabulary.askLabelPrefix`, and per-phase `vocabulary.askPhaseLabelPrefix`) | the cloud, or a human | what kind of ask, and which phase raised it |
+| release (`vocabulary.releaseLabel`, listed under `teams[].labels.release`) | **a human only** | releases a ticket the shape detector flagged as an ask; a human-applied ask-kind label outranks it |
+| hold (listed under `teams[].labels.hold`) | the cloud | the marker a team gets instead of a Remediate state move when it has no remediate stage mapped |
+| a local-lane marker | the cloud | a worker outside the cloud holds this ticket; removed at that lane's terminal step |
+
+`(absent)` beside a label in `teams[].labels` means the workspace has no such label yet; the CLI refuses to apply a name it cannot resolve.
+
+## Relations
+
+`blocks` is the only relation Catalyst creates. It is written when an ask is raised, so the ask blocks every ticket waiting on the answer, and it is the signal that ranks the human's inbox: an ask with nothing to block is refused unless the caller declares nothing is blocked, because such an ask would never surface. No other relation type is written by the cloud.
+
+## The bookkeeping marker
+
+A comment that is a machine RECORD (a merge note, a state-move log, a chain summary) rather than a turn in a conversation must begin with the bookkeeping marker from `vocabulary.bookkeeping.marker`. Rules the contract states alongside it: it is a prefix only, never a substring; ASCII case-insensitive; leading whitespace is trimmed first. A marked comment never wakes an agent and never counts as "something happened" for the no-change and validate holds.
+
+It matters on the human-attributed path: a record posted with a personal identity is wire-identical to the human typing it and would wake an agent to reply to its own writeup. A comment posted as the app actor already carries a bot actor and is already skipped; `--bookkeeping` on the comment script is still correct there, and harmless.
+
+A real question that merely mentions the word is not bookkeeping and still wakes, deliberately.
+
+## The eyes acknowledgement
+
+When a genuine human comment lands (not a bot, not agent-authored, not an automation signature, not bookkeeping), the cloud reacts with 👀 and records a durable wake; the record is written even if the reaction fails. When a bot or agent reply observed at ingest is threaded under that comment, the 👀 is removed and the wake resolves. No live session is required for either half. So: reply in-thread, under the comment you are answering, or the acknowledgement never clears.

package/skills/catalyst-linear/references/writing-to-linear.md

@@ -0,0 +1,43 @@
+# Writing to Linear: identity, budget, slots, labels
+
+This reference restates the write mechanism. The live values it depends on — the route table, the daily write budget, the stage map, the label ids — are read by the CLI from the contract (`routes`, `thresholds`, `teams[].stages`, `teams[].labels`) on every write. Nothing here is a literal to copy.
+
+## Every write is one script
+
+| Want | Run |
+| -- | -- |
+| a comment, threaded or top-level | `node scripts/comment.mjs <ticket> --body <text> [--parent <commentId>] [--bookkeeping]` |
+| a card move | `node scripts/move.mjs <ticket> --slot <slot>` or `--state-type backlog` |
+| a label on or off | `node scripts/label.mjs <ticket> --add <name> --remove <name>` |
+| a new ticket | `node scripts/create-ticket.mjs --team <key> --title <text>` |
+| a decision for a human | not here: the `what-needs-me` skill raises an ask with options, a default and what it blocks |
+
+Each script wraps one `catalyst-skills write` verb, which posts to the route the contract names, as the tenant's app actor, with the account key this machine connected with. No script composes a URL, and none needs a Linear credential of its own.
+
+## App actor versus personal identity
+
+Every write goes out as the tenant's Catalyst app actor by default. That identity is what the cloud's own comment-wake trigger recognises as "not a human", so an app-actor comment never wakes an agent to reply to it, never needs the bookkeeping marker to be safe, and reads to the human as Catalyst speaking. `--as-user` switches a comment or a new ticket to the personal identity behind the key; use it only when the human asked for that attribution, and then mark any machine record with `--bookkeeping`, because on that path the record is indistinguishable from the human typing it.
+
+Reply where the message arrived: a comment inside a thread is answered with `--parent <commentId>`, in that thread, and never as a new ticket. Never post as the human; you speak as Catalyst, or as yourself by role.
+
+## The daily write budget
+
+Every write route spends one unit of a per-host daily budget the contract publishes as `thresholds.hostDailyWriteBudget`; a label call spends one unit whatever the label count; reads spend none. When the budget is spent, the CLI refuses with exit 2 and a line that names the budget and the retry time. Do not retry in a loop; report it, and batch what you can into fewer writes (one comment, not five).
+
+## State moves are by slot, never by name
+
+`--slot <slot>` names one of the eleven slots; the CLI resolves it to this team's live state id from the contract. It refuses when the slot is unmapped for the team, and when the mapped state no longer exists in Linear (the map needs fixing in tenant settings first). Moving to `dispatch` is how work is dispatched; nothing is offered from any other column. Backlog is not a slot: `--state-type backlog` resolves the team's first backlog-type state from its live workflow states, and moving a card there parks it and stops remediation rounds. A move never fabricates a state id, and a move by stage name is not offered because names are display fields that survive re-imports while ids do not.
+
+## Labels are by contract id
+
+A name the contract lists for the team (the ask marker, the hold label, the release label) resolves to that team's preferred id; when the workspace has no such label the CLI refuses rather than inventing one. Any other value is sent as a label id as given, so a label outside Catalyst's own set needs its id, which the ticket record's `labels[]` shows.
+
+Two labels are a human's, not yours: the release label (which frees a ticket the shape detector held) is applied by a human; the hold labels on a pull request are `catalyst-github`'s subject.
+
+## A new ticket takes the team key
+
+`create-ticket.mjs --team <key>` names the team by the prefix its identifiers carry; the CLI resolves the team id from the contract and the cloud fences the write to your tenant on the team, not only on the credential. Cite the identifier only after the script prints it; a guessed number is usually a real, unrelated ticket. Do not file a question for a human this way: a ticket whose text reads as a decision request is held out of dispatch by shape until someone releases it, and it would never reach the human's inbox with what it blocks.
+
+## What is never offered
+
+Delegation (assigning a ticket to an agent) is an operator action, not a tenant write. Answering an ask on the human's behalf is not a write you make; the human answers, and `what-needs-me` records the acceptance. Editing another actor's comment is not available.