@catalyst-cloud/catalyst-skills 0.1.1 → 0.2.0

package/dist/watch.js

@@ -0,0 +1,173 @@
+// watch.ts — `watch [--team K] [--ticket T]... [--project P] [--exec CMD] [--cursor-file] [--from]`:
+// one JSON line per in-scope change frame, cursor advanced after the reaction, over the SDK's live
+// stream. Scope is filtered on the client from the frame's entity and row; a project scope resolves
+// an issue reference to its project through GET /api/v1/issues/:ref, cached in memory.
+import { spawn } from "node:child_process";
+import { flagList, flagString } from "./args.js";
+import { apiBase, requireConfig, watchCursorPathFor } from "./config.js";
+import { loadContract } from "./contract.js";
+import { CliError, UsageError } from "./errors.js";
+import { apiClient } from "./http.js";
+import { loadSdk } from "./sdk.js";
+import { createLiveEventsClient } from "./watch/consumer.js";
+import { CursorFileError } from "./watch/cursor-file.js";
+const ROW_ISSUE_REFS = ["identifier", "linear_issue_identifier", "issue_identifier", "issue_id", "linear_issue_id"];
+/** Decide whether one frame falls inside the scope. An empty scope admits everything. Rows that only
+ *  carry an issue reference (comments, sessions, PRs) resolve it through `resolve` for project scope. */
+export async function inScope(frame, scope, resolve) {
+    const hasScope = Boolean(scope.teamId || scope.teamKey || (scope.tickets && scope.tickets.length) || scope.projectId);
+    if (!hasScope)
+        return true;
+    const row = frame.row ?? {};
+    const refs = ROW_ISSUE_REFS.map((k) => row[k]).filter((v) => typeof v === "string" && v !== "");
+    const upperTickets = (scope.tickets ?? []).map((t) => t.toUpperCase());
+    if (upperTickets.length > 0) {
+        if (refs.some((r) => upperTickets.includes(r.toUpperCase())))
+            return true;
+        for (const r of refs) {
+            const info = await resolve(r);
+            if (info?.identifier && upperTickets.includes(info.identifier.toUpperCase()))
+                return true;
+        }
+    }
+    if (scope.projectId) {
+        if (row.project_id === scope.projectId || row.id === scope.projectId)
+            return true;
+        for (const r of refs) {
+            const info = await resolve(r);
+            if (info?.projectId === scope.projectId)
+                return true;
+        }
+    }
+    if (scope.teamId || scope.teamKey) {
+        if (scope.teamId && (row.team_id === scope.teamId || row.teamId === scope.teamId))
+            return true;
+        if (scope.teamKey && refs.some((r) => /^[A-Za-z]+-\d+$/.test(r) && r.toUpperCase().startsWith(`${scope.teamKey.toUpperCase()}-`)))
+            return true;
+        for (const r of refs) {
+            const info = await resolve(r);
+            if (info && scope.teamId && info.teamId === scope.teamId)
+                return true;
+            if (info?.identifier && scope.teamKey && info.identifier.toUpperCase().startsWith(`${scope.teamKey.toUpperCase()}-`))
+                return true;
+        }
+    }
+    return false;
+}
+/** Resolve issue references through the API, cached per process. */
+export function apiIssueResolver(cfg, ctx) {
+    const api = apiClient(cfg, ctx);
+    const cache = new Map();
+    return async (ref) => {
+        if (cache.has(ref))
+            return cache.get(ref);
+        let out = null;
+        try {
+            const res = await api.getJson(`/api/v1/issues/${encodeURIComponent(ref)}`, { accept: [404] });
+            if (res.status !== 404 && res.body) {
+                out = {
+                    id: typeof res.body.id === "string" ? res.body.id : null,
+                    identifier: typeof res.body.identifier === "string" ? res.body.identifier : null,
+                    projectId: typeof res.body.project_id === "string" ? res.body.project_id : null,
+                    teamId: typeof res.body.team_id === "string" ? res.body.team_id : null,
+                };
+            }
+        }
+        catch {
+            out = null;
+        }
+        cache.set(ref, out);
+        return out;
+    };
+}
+/**
+ * Run `--exec CMD` once with the frame on stdin; a non-zero exit is a failed reaction.
+ *
+ * The child's EXIT CODE is the whole contract, and a broken pipe is not a failure on its own. A
+ * handler that exits before reading the frame is ordinary and often correct — `grep -q`, `head -1`,
+ * a script that fails fast — and so is one that simply died. In every one of those cases the write
+ * lands on a pipe with nothing at the other end and raises EPIPE asynchronously. Node delivers that
+ * as an `error` event on the child's stdin, and a stream with no `error` listener rethrows it as an
+ * unhandled error, which takes down the whole watch: one misbehaving handler and the customer stops
+ * receiving their tenant's events. So the pipe is allowed to break, and the exit code still decides.
+ */
+export function execReaction(cmd, env) {
+    return (frame) => new Promise((resolve, reject) => {
+        const child = spawn("sh", ["-c", cmd], { stdio: ["pipe", "inherit", "inherit"], env });
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`--exec exited ${code}`))));
+        // Listen before writing: attaching afterwards races the synchronous part of `end()`.
+        child.stdin.on("error", () => { });
+        try {
+            if (child.stdin.writable)
+                child.stdin.end(`${JSON.stringify(frame)}\n`);
+        }
+        catch {
+            // A stdin already destroyed throws here rather than emitting; same verdict, wait for close.
+        }
+    });
+}
+export async function runWatch(ctx, cfg, opts, deps = {}) {
+    const sdk = deps.sdk ?? (await loadSdk());
+    const resolve = deps.resolver ?? apiIssueResolver(cfg, ctx);
+    const react = opts.exec ? execReaction(opts.exec, ctx.env) : undefined;
+    let handle;
+    try {
+        handle = buildHandle();
+    }
+    catch (err) {
+        if (err instanceof CursorFileError)
+            throw new CliError(`${err.message} (${err.path})`, "cursor-file");
+        throw err;
+    }
+    deps.onHandle?.(handle);
+    const stopped = deps.waitForStop ??
+        (() => new Promise((done) => {
+            process.once("SIGINT", () => done());
+            process.once("SIGTERM", () => done());
+        }));
+    const running = handle.client.start();
+    await stopped();
+    handle.client.stop();
+    await running;
+    return 0;
+    function buildHandle() {
+        return createLiveEventsClient(sdk, {
+            baseUrl: apiBase(cfg),
+            accountId: cfg.account,
+            token: cfg.key,
+            cursorFile: opts.cursorFile ?? watchCursorPathFor(ctx.home),
+            fromHead: opts.fromHead,
+            fetchImpl: ctx.fetch,
+            wsFactory: deps.wsFactory,
+            backoffMs: deps.backoffMs,
+            maxBackoffMs: deps.maxBackoffMs,
+            log: (level, msg) => ctx.stderr(`[watch ${level}] ${msg}`),
+            onStatus: (s) => ctx.stderr(`[watch] status=${s}`),
+            onReseed: (cursor) => ctx.stderr(`[watch] resync: cursor moved to head ${cursor}`),
+            onEvent: async (frame) => {
+                if (!(await inScope(frame, opts.scope, resolve)))
+                    return;
+                ctx.stdout(JSON.stringify(frame));
+                if (react)
+                    await react(frame);
+            },
+        });
+    }
+}
+export async function cmdWatch(args, ctx, deps = {}) {
+    const cfg = requireConfig(ctx);
+    const from = flagString(args, "from") ?? "cursor";
+    if (from !== "cursor" && from !== "head")
+        throw new UsageError("--from must be cursor or head");
+    const scope = { tickets: flagList(args, "ticket"), projectId: flagString(args, "project") };
+    const teamKey = flagString(args, "team");
+    if (teamKey) {
+        const { doc } = await loadContract(ctx, cfg);
+        const team = doc.teams.find((t) => (t.key ?? "").toUpperCase() === teamKey.toUpperCase());
+        scope.teamKey = teamKey;
+        if (team)
+            scope.teamId = team.id;
+    }
+    return runWatch(ctx, cfg, { scope, exec: flagString(args, "exec"), cursorFile: flagString(args, "cursor-file"), fromHead: from === "head" }, deps);
+}

package/dist/write.js

@@ -0,0 +1,224 @@
+// write.ts — writes to Linear as the app actor through the agent proxy. Every route path comes from
+// the contract's route table (never a literal); every stage id from `teams[].stages` by slot; every
+// label id from `teams[].labels`; the bookkeeping marker from `vocabulary`. `delegate` is never offered.
+import { readFileSync } from "node:fs";
+import { flagBool, flagInt, flagList, flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { bookkeepingPrefix, labelId, loadContract, routePath, stageIdForSlot, teamByKey, teamForTicket } from "./contract.js";
+import { CliError, UsageError } from "./errors.js";
+import { apiClient } from "./http.js";
+/** A ticket identifier → its Linear id (and team/project) through GET /api/v1/issues/:identifier. */
+export async function resolveIssue(api, ticket) {
+    const res = await api.getJson(`/api/v1/issues/${encodeURIComponent(ticket)}`, { accept: [404] });
+    if (res.status === 404 || !res.body || typeof res.body.id !== "string") {
+        throw new CliError(`ticket ${ticket} is not in the mirror — check the identifier`, "ticket-unknown");
+    }
+    return {
+        id: res.body.id,
+        identifier: typeof res.body.identifier === "string" ? res.body.identifier : ticket,
+        teamId: typeof res.body.team_id === "string" ? res.body.team_id : null,
+        projectId: typeof res.body.project_id === "string" ? res.body.project_id : null,
+    };
+}
+/** GET /api/v1/workflow-stages, read tolerantly: `{teams:[{teamId|id|key, states|stages:[...]}]}`,
+ *  `{stages:[...]}` or a bare array of states each carrying `team_id|teamId`. */
+export async function fetchWorkflowStates(api) {
+    const res = await api.getJson("/api/v1/workflow-stages");
+    const out = [];
+    const push = (s, teamId) => {
+        if (typeof s.id !== "string")
+            return;
+        out.push({
+            id: s.id,
+            name: String(s.name ?? ""),
+            type: String(s.type ?? ""),
+            teamId: (typeof s.team_id === "string" ? s.team_id : typeof s.teamId === "string" ? s.teamId : teamId) ?? null,
+        });
+    };
+    const body = res.body;
+    if (Array.isArray(body)) {
+        for (const s of body)
+            push(s, null);
+    }
+    else if (body && typeof body === "object") {
+        const teams = body.teams;
+        if (Array.isArray(teams)) {
+            for (const t of teams) {
+                const teamId = typeof t.teamId === "string" ? t.teamId : typeof t.id === "string" ? t.id : typeof t.team_id === "string" ? t.team_id : null;
+                const states = (t.states ?? t.stages);
+                if (Array.isArray(states))
+                    for (const s of states)
+                        push(s, teamId);
+            }
+        }
+        const stages = body.stages ?? body.states;
+        if (Array.isArray(stages))
+            for (const s of stages)
+                push(s, null);
+    }
+    return out;
+}
+/** The first state of `type` on `teamId`, in the order the route lists them. */
+export function firstStateOfType(states, teamId, type) {
+    const hit = states.find((s) => s.teamId === teamId && s.type.toLowerCase() === type.toLowerCase());
+    if (!hit) {
+        const seen = [...new Set(states.filter((s) => s.teamId === teamId).map((s) => s.type))].join(", ") || "none";
+        throw new CliError(`team ${teamId} has no state of type "${type}" (types seen: ${seen})`, "state-type-unknown");
+    }
+    return hit;
+}
+/** Post to a contract route by name; a budget refusal names the contract's daily budget. */
+export async function postAgent(api, doc, routeName, body) {
+    try {
+        const res = await api.postJson(routePath(doc, routeName), body);
+        return res.body;
+    }
+    catch (err) {
+        if (err instanceof CliError && err.code === "budget") {
+            throw new CliError(`${err.message} — the contract's thresholds.hostDailyWriteBudget is ${doc.thresholds.hostDailyWriteBudget} writes per host per day`, "budget", 2, 429);
+        }
+        throw err;
+    }
+}
+export async function cmdWrite(args, ctx, deps = {}) {
+    const [sub, ...rest] = positionals(args);
+    if (!sub)
+        throw new UsageError("write needs a subcommand: comment | state | label | create | reaction | attachment | session");
+    const cfg = requireConfig(ctx);
+    const { doc } = await loadContract(ctx, cfg);
+    const api = apiClient(cfg, ctx);
+    const asUser = flagBool(args, "as-user");
+    let result;
+    switch (sub) {
+        case "comment": {
+            const ticket = needTicket(rest, "comment <ticket>");
+            let body = flagString(args, "body");
+            if (flagBool(args, "stdin"))
+                body = (await (deps.readStdin ?? readStdin)()).trimEnd();
+            if (!body)
+                throw new UsageError("write comment needs --body <text> or --stdin");
+            if (flagBool(args, "bookkeeping"))
+                body = `${bookkeepingPrefix(doc)} ${body}`;
+            const issue = await resolveIssue(api, ticket);
+            result = await postAgent(api, doc, "issue-comment", {
+                issueId: issue.id,
+                body,
+                ...(flagString(args, "parent") ? { parentId: flagString(args, "parent") } : {}),
+                ...(asUser ? { createAsUser: true } : {}),
+            });
+            break;
+        }
+        case "state": {
+            const ticket = needTicket(rest, "state <ticket>");
+            const issue = await resolveIssue(api, ticket);
+            const slot = flagString(args, "slot");
+            const stateId = flagString(args, "state-id");
+            const stateType = flagString(args, "state-type");
+            let target;
+            if (stateId)
+                target = stateId;
+            else if (slot)
+                target = stageIdForSlot(teamForTicket(doc, issue.identifier), slot);
+            else if (stateType) {
+                const team = teamForTicket(doc, issue.identifier);
+                target = firstStateOfType(await fetchWorkflowStates(api), issue.teamId ?? team.id, stateType).id;
+            }
+            else
+                throw new UsageError("write state needs --slot <slot>, --state-id <id> or --state-type <type>");
+            result = await postAgent(api, doc, "issue-state", { issueId: issue.id, stateId: target });
+            break;
+        }
+        case "label": {
+            const ticket = needTicket(rest, "label <ticket>");
+            const add = flagList(args, "add");
+            const remove = flagList(args, "remove");
+            if (add.length === 0 && remove.length === 0)
+                throw new UsageError("write label needs --add <name|id> and/or --remove <name|id>");
+            const issue = await resolveIssue(api, ticket);
+            const team = teamForTicket(doc, issue.identifier);
+            const results = [];
+            if (add.length)
+                results.push(await postAgent(api, doc, "issue-label", { issueId: issue.id, labelIds: add.map((n) => labelId(team, n)), mode: "add" }));
+            if (remove.length)
+                results.push(await postAgent(api, doc, "issue-label", { issueId: issue.id, labelIds: remove.map((n) => labelId(team, n)), mode: "remove" }));
+            result = results.length === 1 ? results[0] : results;
+            break;
+        }
+        case "create": {
+            const teamKey = flagString(args, "team");
+            const title = flagString(args, "title");
+            if (!teamKey || !title)
+                throw new UsageError("write create needs --team <key> and --title <text>");
+            const team = teamByKey(doc, teamKey);
+            const labels = flagList(args, "label").map((n) => labelId(team, n));
+            const priority = flagString(args, "priority") !== undefined ? flagInt(args, "priority", 0) : undefined;
+            result = await postAgent(api, doc, "issue-create", {
+                teamId: team.id,
+                title,
+                ...(labels.length ? { labelIds: labels } : {}),
+                ...(priority !== undefined ? { priority } : {}),
+                ...(asUser ? { createAsUser: true } : {}),
+            });
+            break;
+        }
+        case "reaction": {
+            const emoji = flagString(args, "emoji");
+            if (!emoji)
+                throw new UsageError("write reaction needs --emoji <e>");
+            const commentId = flagString(args, "comment");
+            const body = { emoji, ...(asUser ? { createAsUser: true } : {}) };
+            if (commentId)
+                body.commentId = commentId;
+            else
+                body.issueId = (await resolveIssue(api, needTicket(rest, "reaction <ticket>|--comment <id>"))).id;
+            result = await postAgent(api, doc, "reaction", body);
+            break;
+        }
+        case "attachment": {
+            const ticket = needTicket(rest, "attachment <ticket>");
+            const title = flagString(args, "title");
+            const url = flagString(args, "url");
+            if (!title || !url)
+                throw new UsageError("write attachment needs --title <t> and --url <u>");
+            const issue = await resolveIssue(api, ticket);
+            result = await postAgent(api, doc, "attachment", { issueId: issue.id, title, url });
+            break;
+        }
+        case "session": {
+            const ticket = needTicket(rest, "session <ticket>");
+            const issue = await resolveIssue(api, ticket);
+            const planFile = flagString(args, "plan-file");
+            const plan = planFile ? JSON.parse(readFileSync(planFile, "utf8")) : undefined;
+            result = await postAgent(api, doc, "session", {
+                issueId: issue.id,
+                ...(flagString(args, "title") ? { title: flagString(args, "title") } : {}),
+                ...(plan !== undefined ? { plan } : {}),
+                ...(flagString(args, "activity") ? { activity: flagString(args, "activity") } : {}),
+                ...(flagString(args, "url") ? { url: flagString(args, "url") } : {}),
+            });
+            break;
+        }
+        case "delegate":
+            throw new UsageError("write delegate is not offered: delegation is an operator action, not a tenant write");
+        default:
+            throw new UsageError(`unknown write subcommand: ${sub}`);
+    }
+    ctx.stdout(args.json ? JSON.stringify(result ?? {}) : describeWrite(sub, result));
+    return 0;
+}
+function needTicket(rest, usage) {
+    const t = rest[0];
+    if (!t)
+        throw new UsageError(`write ${usage}`);
+    return t;
+}
+function describeWrite(sub, result) {
+    const id = result && typeof result === "object" ? result.id ?? result.commentId ?? result.issueId : undefined;
+    return `${sub}: ok${id ? ` (${String(id)})` : ""}`;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@catalyst-cloud/catalyst-skills",
-  "version": "0.1.1",
-  "description": "Customer skill bundle for catalyst-cloud: install the concierge, steward, ask, linearis, join and setup skills from npm and join your tenant with one command. No catalyst repository checkout required.",
+  "version": "0.2.0",
+  "description": "Customer skill bundle for Catalyst Cloud: eight skills named from the executive's seat (whats-happening, what-needs-me, run-this-project, catalyst-setup, catalyst-linear, catalyst-github, how-catalyst-works, connect-me) plus the catalyst-skills CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command.",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -16,7 +16,7 @@
     "url": "https://github.com/coalesce-labs/catalyst-cloud-skills/issues"
   },
   "engines": {
-    "node": ">=18.17"
+    "node": ">=22"
   },
   "bin": {
     "catalyst-skills": "bin/catalyst-skills.js"
@@ -30,14 +30,18 @@
     "LICENSE"
   ],
   "catalystCloud": {
-    "tenantContractRange": "0.x"
+    "tenantContractRange": "1.x"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json",
     "prepack": "tsc -p tsconfig.build.json",
     "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "version:sync": "node scripts/sync-plugin-version.mjs"
+  },
+  "dependencies": {
+    "@catalyst-cloud/sdk": "^0.8.49"
   },
   "devDependencies": {
     "@types/node": "^26.3.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 — 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 an account 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.