@catalyst-cloud/cli 0.14.6 → 0.14.8

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

@@ -2,18 +2,19 @@
 // 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 query`, `contract` and, when fresh, `replica sql`.
+// input comes from cloud-backed `catalyst query` and `contract`; --local-threads opts into `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]
+const HELP = `Usage: node scripts/is-it-mergeable.mjs <ticket | pr-node-id> [--json] [--local-threads]
 
 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
+  threads    inconclusive when the cloud PR detail carries no thread count;
+             --local-threads opts into reading a local replica caught up to a probed cloud head
 
 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.
@@ -32,14 +33,20 @@ if (!target) {
 }
 
 const { ticket, detail } = resolvePull(target);
-const merge = parseJson(runCliOrExit(["contract", "--path", "merge", "--json"]).stdout);
+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 contract --refresh");
+  console.error(
+    "the contract's merge block did not parse; run: catalyst 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 repoId = typeof detail.repo_id === "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";
@@ -50,75 +57,233 @@ 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`);
+  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");
+  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`);
+  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");
+  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 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}`);
+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`);
+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`);
+  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)`);
+// The default cloud read requires no local writer or database. Thread ancestry remains the
+// cloud evaluator's responsibility; absence of thread evidence never becomes a green leg.
+const localThreads = args.includes("--local-threads");
+const replicaResult = localThreads
+  ? runCli(["replica", "status", "--probe", "--json"])
+  : null;
+const replica =
+  replicaResult?.code === 0 ? parseJson(replicaResult.stdout) : null;
+if (
+  localThreads &&
+  replica?.verdict === "fresh" &&
+  Number.isSafeInteger(replica.cursor) &&
+  replica.cursor >= 0 &&
+  replica.cursor === replica.head
+) {
+  const num = detail.number;
+  if (
+    typeof num !== "number" ||
+    !Number.isSafeInteger(num) ||
+    num <= 0 ||
+    !repoId ||
+    repoId !== repoId.trim() ||
+    repoId.length > 512 ||
+    /[\u0000-\u001f\u007f-\u009f]/.test(repoId)
+  ) {
+    add(
+      "threads",
+      "inconclusive",
+      "the PR identity is incomplete; local thread evidence could not be read",
+    );
+  } else {
+    const esc = repoId.replace(/'/g, "''");
+    const sql = `select resolved, count(*) as n from pr_review_threads where repo_id = '${esc}' and pr_number = ${num} group by resolved`;
+    const result = runCli(["replica", "sql", sql, "--json"]);
+    const rows = parseJson(result.stdout);
+    if (
+      result.code !== 0 ||
+      !Array.isArray(rows) ||
+      rows.some(
+        (row) =>
+          !row ||
+          ![0, 1, null].includes(row.resolved) ||
+          typeof row.n !== "number" ||
+          !Number.isSafeInteger(row.n) ||
+          row.n < 0,
+      )
+    ) {
+      add(
+        "threads",
+        "inconclusive",
+        "the optional local thread read could not be verified; the cloud evaluator decides",
+      );
+    } else {
+      const count = (want) =>
+        rows
+          .filter((r) =>
+            want === null
+              ? r.resolved === null || r.resolved === undefined
+              : 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 replica start --detach) for a local read`);
+  add(
+    "threads",
+    "inconclusive",
+    localThreads
+      ? "the optional local replica has not proven that it is caught up to the cloud head; the cloud evaluator decides"
+      : "the cloud PR detail carries no thread count; the cloud evaluator decides",
+  );
 }
 
 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`;
+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 }));
+  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}`);
+  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/read-pr.mjs

@@ -12,7 +12,7 @@ const HELP = `Usage: node scripts/read-pr.mjs <ticket | pr-node-id> [--all] [--j
   --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).`;
+The first stderr line names the source the CLI read from (the API by default, or an explicitly selected replica).`;
 
 const args = process.argv.slice(2);
 if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
@@ -52,8 +52,15 @@ if (all) {
     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, "")}]`);
+    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);
 }
@@ -66,23 +73,44 @@ if (json) {
 
 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(", ");
+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"}`);
+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(
+    `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)}`);
+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}):`);
@@ -90,8 +118,16 @@ if (statuses.length > 0) {
 }
 
 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)}`);
+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");
+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);

package/skills/catalyst-linear/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: catalyst-linear
 description: >-
-  Catalyst's view of Linear on the customer's own cloud account. 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 account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's 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).
+  Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the cloud API by default, with local replica reads available as an explicit opt-in, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's 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:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.8 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 
-You read tickets and write to them in the person's cloud account, as Catalyst. Reads come from the replica when it is fresh, else the API, and name their source. Writes go out as the app actor, with routes, stage ids, label ids and the bookkeeping marker resolved from the contract by the `catalyst` CLI.
+You read tickets and write to them in the person's cloud account, as Catalyst. Reads come from the cloud API by default and name their source. A person may explicitly choose a local replica read; setup does not require a replica. Writes go out as the app actor, with routes, stage ids, label ids and the bookkeeping marker resolved from the contract by the `catalyst` CLI.
 
 ## Run first
 
@@ -30,6 +30,8 @@ Exit codes: 0 done, 1 not found or a usage error, 2 this machine is not connecte
 | "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` |
+| which command answers a ticket question from the cloud: stage, last phase, PR, what changed | `references/reading-from-the-cloud.md` |
+| local SQL, only when `catalyst replica status --json` reports `configured: true` | `references/local-replica.md` |
 
 ## Rules
 

package/skills/catalyst-linear/references/local-replica.md

@@ -0,0 +1,91 @@
+# Reading a ticket from the local replica (opt-in)
+
+Load this only when `catalyst replica status --json` reports `configured: true`. On any other machine, read from the cloud (`references/reading-from-the-cloud.md`) and do not mention the replica.
+
+The replica is an on-machine SQLite copy of the account. It exists only when the person opted in to local sync. It is for ad hoc SQL and many repeated reads. It is never required, and the cloud read stays the default.
+
+## Check it is caught up first
+
+Run `catalyst replica status --probe --json` before every local read.
+
+- Read locally only when `verdict` is `fresh` and `cursor` equals `head`. That proves the copy is caught up with the cloud at that moment.
+- `fresh` without the probe proves a live writer, not a caught-up copy.
+- `stale` (exit 1) or `absent` (exit 3) with `configured: true` means the person opted in and the writer is down. Answer from the cloud and say the local copy is behind. `catalyst replica start --detach` restarts it, but only start it when the person asks.
+
+Quote the cursor with any local answer, for example "from the local replica at cursor 4810".
+
+## Two ways to read it
+
+- `catalyst query issue <KEY-123> --source replica` reads the ticket from the local copy. A replica built by an older SDK can lack fields the cloud read has, such as `linked_pulls`. `--source replica` on an absent replica is refused, never silently answered from the API.
+- `catalyst replica sql "<one SELECT>" --json` runs one read-only `SELECT` and prints rows. Anything other than a single `SELECT` is refused.
+
+`catalyst replica schema` prints every table with its columns, and `catalyst replica schema <table>` prints one. Read the columns before writing SQL against a table this page does not cover.
+
+## What the tables hold
+
+Timestamps are milliseconds since the epoch. A row with `removed_at` set was deleted upstream, so filter `removed_at is null` for current rows.
+
+| table | one row is | join on |
+| -- | -- | -- |
+| `issues` | a ticket: `identifier`, `title`, `state`, `state_type`, `assignee`, `delegate_name`, `priority`, `team_key`, `project_id`, `cycle_id`, `parent_identifier`, `updated_at` | `id` |
+| `comments` | a comment: `body`, `author_name`, `is_bot`, `parent_id`, `created_at` | `issue_id` = `issues.id` |
+| `issue_history` | one change to a ticket: `from_state` / `to_state` and the other `from_*` / `to_*` pairs, `created_at` | `issue_id` = `issues.id` |
+| `relations` | a link between tickets: `type`, `issue_identifier`, `related_identifier` | identifiers |
+| `labels`, `issue_labels` | a label, and which ticket carries it | `issue_labels.label_id` = `labels.id` |
+| `agent_sessions` | an agent session on a ticket: `status`, `created_at` | `issue_id` = `issues.id` |
+| `pull_requests` | a pull request that names a ticket in `linear_issue_identifier` | `linear_issue_identifier` = `issues.identifier` |
+
+## Recipes
+
+Replace `ENG-123` and `ENG` with the real identifier and team key.
+
+One ticket's current fields:
+
+```sql
+select identifier, title, state, assignee, delegate_name, priority, updated_at
+from issues where identifier = 'ENG-123' and removed_at is null
+```
+
+The newest comments on a ticket, Catalyst's own first:
+
+```sql
+select c.created_at, c.author_name, c.is_bot, substr(c.body, 1, 200) as body
+from comments c join issues i on i.id = c.issue_id
+where i.identifier = 'ENG-123' and c.removed_at is null
+order by c.is_bot desc, c.created_at desc limit 20
+```
+
+Every state change on a ticket, oldest first:
+
+```sql
+select h.created_at, h.from_state, h.to_state
+from issue_history h join issues i on i.id = h.issue_id
+where i.identifier = 'ENG-123' and h.to_state is not null
+order by h.created_at
+```
+
+How many tickets sit in each state on one team:
+
+```sql
+select state, count(*) as n from issues
+where team_key = 'ENG' and removed_at is null
+group by state order by n desc
+```
+
+What a ticket blocks and what blocks it:
+
+```sql
+select type, issue_identifier, related_identifier from relations
+where issue_identifier = 'ENG-123' or related_identifier = 'ENG-123'
+```
+
+Pull requests that name a ticket:
+
+```sql
+select repo_id, number, state, draft, merged, head_sha
+from pull_requests where linear_issue_identifier = 'ENG-123'
+```
+
+## What the replica does not answer
+
+Phase attempts, remediate rounds, park state and the live lease are not in the replica. `catalyst history <KEY-123>` reads them from the cloud. So do eligibility (`catalyst explain <KEY-123>`) and search (`node scripts/search.mjs`).

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

@@ -4,13 +4,13 @@
 
 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, so the answer is local and cheap.
-- `source: api (replica stale|absent|not configured)`: the answer came from the origin-fresh cloud API; a stale replica always falls back.
+- `source: replica (--source replica)`: the person explicitly selected the optional local replica.
+- `source: api (cloud reads by default)`: the answer came from the cloud API; no local replica is needed.
 - `source: api (<verb> is api-only)`: search, cycles, pull detail and change feeds never come from the replica.
 
 Quote the source when a fact's freshness matters ("as of the replica at cursor N", "from the API just now").
 
-`--source replica` or `--source api` forces one. Forcing the replica when it is absent or stale is refused.
+`--source replica` or `--source api` forces one. Forcing the replica when it is absent is refused. No offline-browsing promise is made.
 
 ## Then the row
 

package/skills/catalyst-linear/references/reading-from-the-cloud.md

@@ -0,0 +1,38 @@
+# Reading ticket facts from the cloud
+
+Cloud reads are the default on every machine. They need no local writer and no local database. Every command below reads the cloud through the `catalyst` CLI.
+
+| question | command |
+| -- | -- |
+| What stage is the ticket in, who has it, which PRs name it? | `catalyst query issue <KEY-123>`, or `node scripts/read-ticket.mjs <KEY-123>` |
+| What did Catalyst and people write on it? | `node scripts/read-ticket.mjs <KEY-123> --comments`; comments and activity come inline with the ticket |
+| What was the last phase, and how did it end? | `catalyst history <KEY-123>` |
+| How many remediate rounds against the cap? Is it parked, and what releases it? | `catalyst history <KEY-123>` |
+| Why is it not running, or what runs next? | `catalyst explain <KEY-123>` |
+| What is the PR's state, checks and reviews? | `catalyst query pulls --ticket <KEY-123>`, then `catalyst query pull <node-id>` |
+| What changed across the account since a point? | `catalyst query changes --since head`, then the cursor it prints |
+| Find a ticket by words | `node scripts/search.mjs <terms>` |
+| What happened to it, event by event? | `catalyst events query --ticket <KEY-123>` |
+| Wait until its phase finishes | `catalyst events wait-for --ticket <KEY-123> --type relay.phase.completed --after <head> --timeout 300` |
+
+## Reading the answer
+
+The first stderr line names the source: `source: api (...)`. Quote it when freshness matters ("from the API just now").
+
+The ticket read returns the whole record, so a question about one field still downloads comments and activity. That is fine for one ticket. For many tickets, use a list (`catalyst query issues --team <key>`) and read one record only where the list is not enough.
+
+A smaller read is coming: the cloud will answer a ticket or its execution history with only the status fields. No CLI flag selects it yet, so read the full record and pick the fields you need.
+
+## Events
+
+`catalyst events` reads the cloud by default and needs no local file.
+
+- `catalyst events query --ticket <KEY-123>` prints the ticket's events, newest first. Add `--type`, `--limit` (up to 200), `--order asc` and `--before` or `--after` to page. An empty page says which sequences the cloud has indexed, so "no match" is not "never happened".
+- To wait for something to happen, first run `catalyst events status --json` and keep its `head`. Then run `catalyst events wait-for --ticket <KEY-123> --type relay.phase.completed --after <head> --timeout 300`. Exit 0 prints the event, exit 1 is a timeout, and exit 4 means the cloud was unreachable.
+- `catalyst events tail --ticket <KEY-123>` stays in the foreground and prints one JSON line per new event.
+
+The ticket filter reads the event's ticket entity, `payload.ticket`, and the lease that caused it. `--from-cache` reads this machine's local event cache instead. It exists only where local sync is on, and it pays off when several agents on one machine share it.
+
+## The local replica
+
+Only on a machine where `catalyst replica status --json` reports `configured: true`, `references/local-replica.md` adds local SQL. Everywhere else, these cloud reads are the whole answer.