@catalyst-cloud/cli 0.15.6 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.16.0
+
+The CLI, skills and plugin now share the 0.16 release line with the SDK and installer. The CLI installs the matching Node replica module for local cache commands. Update the CLI and update the Catalyst plugin through your agent's plugin manager.
+
 ## 0.15.6
 
 Setup checks current readiness and waits up to one minute while Catalyst reads repository settings.

package/dist/args.js

@@ -280,6 +280,25 @@ export const FLAG_TABLES = {
             value: false,
             help: "raise: declare that nothing is blocked",
         },
+        "gates-pr": {
+            value: true,
+            repeat: true,
+            help: "raise: a PR whose hold the answer releases (repeatable; needs --released-by)",
+        },
+        "gates-label": {
+            value: true,
+            repeat: true,
+            help: "raise: the hold label the answer removes: hold or hold:preview (repeatable; default hold)",
+        },
+        "released-by": {
+            value: true,
+            repeat: true,
+            help: "raise: an option letter whose answer releases the hold (repeatable)",
+        },
+        "gates-repo": {
+            value: true,
+            help: "raise: the --gates-pr repository as owner/name (default: the account's only repository)",
+        },
         anyone: {
             value: false,
             help: "list: every open ask in the tenant, not only the ones assigned to you",
@@ -479,7 +498,7 @@ export const VERB_USAGE = {
     queue: "queue [--team K] [--json]",
     watch: "watch [--team K] [--ticket T]... [--project P] [--exec CMD] [--cursor-file <path>] [--from cursor|head]",
     write: "write <comment <ticket> --body|--stdin [--parent] [--bookkeeping] [--as-user] | state <ticket> --slot|--state-id|--state-type | label <ticket> --add... --remove... | create --team --title [--description|--stdin] [--label] [--priority] | reaction <ticket>|--comment <id> --emoji <e> | attachment <ticket> --title --url | session <ticket> [--title] [--plan-file] [--activity]>",
-    ask: "ask <raise --team --title [--context] [--option]... [--default] --blocks <ticket>...|--nothing-to-block [--ask-key] | accept <askTicket> --answer <commentId> --role <role> | list [--anyone] [--json]>",
+    ask: "ask <raise --team --title [--context] [--option]... [--default] --blocks <ticket>...|--nothing-to-block [--ask-key] [--gates-pr <n>... --released-by <letter>... [--gates-label hold|hold:preview]... [--gates-repo <owner/name>]] | accept <askTicket> --answer <commentId> --role <role> | list [--anyone] [--json]>",
     ready: "ready [--onboarding] [--local-sync] [--json] [--offline]",
     accounts: "accounts [--json]",
     mcp: "mcp <add <name> --url URL <--auth none|--bearer SECRET_NAME|--header NAME=SECRET_NAME...>|list|remove <name>> [--json]",

package/dist/ask.js

@@ -39,6 +39,7 @@ async function raise(args, ctx, doc, api) {
     if (options.length > doc.askTemplate.maxLetteredOptions) {
         throw new UsageError(`ask raise takes at most ${doc.askTemplate.maxLetteredOptions} options`);
     }
+    const gates = askGates(args, options, doc);
     const blocks = [];
     for (const t of flagList(args, "blocks"))
         blocks.push((await resolveIssue(api, t)).id);
@@ -55,10 +56,65 @@ async function raise(args, ctx, doc, api) {
         body.nothingToBlock = true;
     if (flagString(args, "ask-key"))
         body.askKey = flagString(args, "ask-key");
+    if (gates)
+        body.gates = gates;
     const result = await postAgent(api, doc, "ask", body);
     ctx.stdout(args.json ? JSON.stringify(result) : `ask raised: ${String(result.identifier ?? result.id ?? "ok")}${blocks.length ? ` (blocks ${blocks.length})` : ""}`);
     return 0;
 }
+/** The hold labels an answered ask may lift; the cloud's ask route refuses any other with a 400. */
+const GATE_LABELS = ["hold", "hold:preview"];
+const OWNER_NAME = /^[^/\s]+\/[^/\s]+$/;
+/** CTC-5044 — the PR hold an answer releases. Absent unless --gates-pr is given, so an ask without it
+ *  posts exactly the body it always did. Everything the route would refuse (a label outside
+ *  {@link GATE_LABELS}, a letter that is not one of this ask's options) is refused here first, before
+ *  any ticket is resolved or anything is posted. Options are lettered A, B, C in the order given. */
+function askGates(args, options, doc) {
+    const prs = flagList(args, "gates-pr");
+    if (prs.length === 0) {
+        for (const f of ["released-by", "gates-label", "gates-repo"]) {
+            if (flagList(args, f).length || flagString(args, f))
+                throw new UsageError(`ask raise takes --${f} only with --gates-pr <n>`);
+        }
+        return undefined;
+    }
+    const pr = [...new Set(prs.map((n) => {
+            if (!/^[1-9]\d*$/.test(n))
+                throw new UsageError(`--gates-pr must be a PR number (got "${n}")`);
+            return Number(n);
+        }))];
+    const labels = [...new Set(flagList(args, "gates-label"))];
+    for (const l of labels) {
+        if (!GATE_LABELS.includes(l))
+            throw new UsageError(`--gates-label ${l} is not a hold an answer can release; use one of: ${GATE_LABELS.join(", ")}`);
+    }
+    const released = [...new Set(flagList(args, "released-by").map((l) => l.trim().toUpperCase()))];
+    if (released.length === 0)
+        throw new UsageError("--gates-pr needs --released-by <letter>: the option whose answer releases the hold");
+    const letters = options.map((_, i) => String.fromCharCode(65 + i));
+    for (const l of released) {
+        if (!letters.includes(l))
+            throw new UsageError(`--released-by ${l} is not one of this ask's options (${letters.length ? letters.join(", ") : "it has none; add --option"})`);
+    }
+    const registered = doc.merge.repositories.map((r) => `${r.owner}/${r.name}`);
+    const named = flagString(args, "gates-repo");
+    let repo;
+    if (named !== undefined) {
+        if (!OWNER_NAME.test(named))
+            throw new UsageError(`--gates-repo must be owner/name (got "${named}")`);
+        const match = registered.find((r) => r.toLowerCase() === named.toLowerCase());
+        if (registered.length && !match)
+            throw new UsageError(`--gates-repo ${named} is not a repository this account registers (${registered.join(", ")})`);
+        repo = match ?? named;
+    }
+    else if (registered.length === 1) {
+        repo = registered[0];
+    }
+    else {
+        throw new UsageError(`--gates-pr needs --gates-repo <owner/name>: this account registers ${registered.length ? registered.join(", ") : "no repository"}`);
+    }
+    return { repo, pr: pr.length === 1 ? pr[0] : pr, labels: labels.length ? labels : ["hold"], releasedBy: released };
+}
 async function accept(args, ctx, doc, api, rest) {
     const askTicket = rest[0];
     const answer = flagString(args, "answer");

package/dist/onboard-github-copy.js

@@ -0,0 +1,2 @@
+/** GitHub can require sudo confirmation before an install or permission change. */
+export const GITHUB_CONFIRM_ACCESS = "GitHub may show Confirm access. Use the two-factor code for the GitHub account you are signed in to.";

package/dist/onboard-github.js

@@ -1,4 +1,5 @@
 import { finishOnTheWeb } from "./consent-browser.js";
+import { GITHUB_CONFIRM_ACCESS } from "./onboard-github-copy.js";
 import { loadConfig, normalizeBaseUrl } from "./config.js";
 import { pollConsent } from "./onboard-consent.js";
 import { GITHUB_PERMISSION, githubInstallationPage, parsePermissions, } from "./onboard-permissions.js";
@@ -468,6 +469,7 @@ export function githubInstallationAdapter(options) {
                     reason: "github_installation_admin_required",
                 };
             // The signed URL is transient credential material: only the browser receives it.
+            ctx.stderr(GITHUB_CONFIRM_ACCESS);
             let browserUnavailable = false;
             try {
                 await options.openBrowser(url, signal);

package/dist/onboard-next.js

@@ -1,4 +1,5 @@
 import { nativeEgressInstallCommands } from "./onboard-runner-egress.js";
+import { GITHUB_CONFIRM_ACCESS } from "./onboard-github-copy.js";
 import { INSTALL_COMMAND, loadConfig, normalizeBaseUrl } from "./config.js";
 import { githubInstallationPage } from "./onboard-permissions.js";
 import { valuesFacts, valuesFix } from "./ready-copy.js";
@@ -138,7 +139,7 @@ const REASONS = {
     runner_needs_runner_flag: "This machine was set up to run Catalyst's work, but its runner is not running or not enrolled. To bring it up, run catalyst onboard --runner.",
     runner_capability_pending: "The runner enrolled but has not reported its capacity yet. Run catalyst onboard again in a minute.",
     runner_admission_unverified: "Setup could not read whether the team's pool admits runner hosts. Run catalyst onboard again to retry.",
-    github_app_permissions_outdated: "GitHub App needs updated permissions. An organization owner on GitHub accepts the pending request on the App's installation page, then run catalyst onboard.",
+    github_app_permissions_outdated: `The existing GitHub App installation needs updated permissions accepted. ${GITHUB_CONFIRM_ACCESS} An organization owner on GitHub opens the App's installation page, chooses Review permissions, then Accept new permissions. Run catalyst onboard afterward.`,
     github_app_repository_missing: "The GitHub App installation cannot reach a repository a project registers. An organization owner on GitHub adds it under the installation's Repository access, then run catalyst onboard.",
     github_app_repository_not_installed: "No GitHub App installation can reach a repository a project registers. A workspace owner or administrator installs the GitHub App on its owner: run catalyst onboard.",
     github_app_permissions_unverified: "The GitHub App installation works, but its granted permissions could not be checked. Run catalyst onboard to try again.",
@@ -246,7 +247,7 @@ function permissionText(step, baseUrl) {
         case "github_app_permissions_outdated":
             if (!url)
                 return undefined;
-            return `GitHub App needs updated permissions${org ? ` on ${org}` : ""}${missing ? `: ${missing}` : ""}. ${github} reviews and accepts the request at ${url}, then run catalyst onboard.`;
+            return `The existing GitHub App installation${org ? ` on ${org}` : ""} needs updated permissions accepted${missing ? `: ${missing}` : ""}. ${GITHUB_CONFIRM_ACCESS} ${github} chooses Review permissions, then Accept new permissions at ${url}. Run catalyst onboard afterward.`;
         case "github_app_repository_missing":
             if (!url || !repository)
                 return undefined;

package/dist/onboard-ui.js

@@ -1,3 +1,4 @@
+import { GITHUB_CONFIRM_ACCESS } from "./onboard-github-copy.js";
 import { COMPUTER_CHECKS, standalonePlan, standalonePlanNotes, pendingContinuation, } from "./onboard-standalone-copy.js";
 import { trackedPrompt } from "./setup-prompt-frame.js";
 import { createOnboardInterrupts } from "./onboard-interrupts.js";
@@ -157,11 +158,13 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             return;
         if (renderer &&
             currentStep === "linear.adopt" &&
-            text.endsWith("already has every state and label"))
+            text.endsWith("has every required state and label"))
             return;
         if (renderer) {
             if (currentStep &&
                 setupBrowserInstruction(currentStep, deps.baseUrl?.())) {
+                if (currentStep === "github.install" && text === GITHUB_CONFIRM_ACCESS)
+                    renderer.detail(text);
                 if (/no browser opened|could not open a browser/i.test(text))
                     browserOpened = false;
                 return;
@@ -1028,6 +1031,8 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
                     ? status()
                     : "waiting for you, up to 10 minutes");
                 renderer.action(browser.instruction);
+                if (currentStep === "github.install")
+                    renderer.detail(GITHUB_CONFIRM_ACCESS);
                 if (browser.url)
                     renderer.detail(renderer.link(browser.url));
                 renderer.detail(renderer.dim(interactive ? "Ctrl-C skips this step." : "Ctrl-C stops setup."));

package/dist/onboard-workflow.js

@@ -145,13 +145,36 @@ export function observeOnboardWorkflow(value, team, now) {
             : {}),
     };
 }
-const label = (text) => text
+const plainText = (text) => text
     .replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g, "")
-    .trim()
-    .slice(0, 80);
+    .trim();
+const label = (text) => plainText(text).slice(0, 80);
 const listed = (names) => names.length > 10
     ? `${names.slice(0, 10).join(", ")}, and ${names.length - 10} more`
     : names.join(", ");
+function unfinishedLabelLines(plan) {
+    return [
+        ...plan.labels.filter((row) => row.outcome === "refused").map((row) => {
+            const name = plainText(row.name);
+            const reason = plainText(row.reason ?? "Linear did not supply a reason.");
+            const guidance = name === "review-followup"
+                ? "Optional for the cloud workflow; no action is needed to finish setup."
+                : [
+                    name === "catalyst-not-an-ask"
+                        ? "Required for the cloud workflow. Without this label, work held by the ask-shape check cannot be released."
+                        : "Only missing required labels block workflow readiness.",
+                    "Ask a Linear workspace administrator to resolve the reported refusal and make this label available to the team, then run catalyst onboard.",
+                ].join(" ");
+            return `Linear refused label: ${name}. ${reason} ${guidance}`;
+        }),
+        ...(plan.labelsNotCreated ?? []).map((row) => {
+            const entry = object(row);
+            const name = typeof entry?.name === "string" ? plainText(entry.name) : "";
+            const reason = typeof entry?.reason === "string" ? plainText(entry.reason) : "";
+            return `Label not added: ${name || "Unnamed label"}. ${reason || "The server did not supply a reason; run catalyst onboard again to retry."}`;
+        }),
+    ];
+}
 /** The adopt preview in plain words: stages and labels it creates or keeps. Linear's names are data. */
 export function adoptPlanLines(plan) {
     const group = (rows, outcome) => rows.filter((row) => row.outcome === outcome).map((row) => label(row.name));
@@ -161,11 +184,10 @@ export function adoptPlanLines(plan) {
         ["Linear refused stages", group(plan.stages, "refused")],
         ["Create labels", group(plan.labels, "would-create")],
         ["Labels already present", group(plan.labels, "already-present")],
-        ["Linear refused labels", group(plan.labels, "refused")],
     ]
         .filter(([, names]) => names.length > 0)
         .map(([title, names]) => `${title}: ${listed(names)}`)
-        .concat(plan.unfilledLoadBearing?.length ? [`Required work stages still missing: ${plan.unfilledLoadBearing.length}`] : [], (plan.provenanceGaps?.length ?? 0) + (plan.labelProvenanceGaps?.length ?? 0) ? ["Some existing states or labels have no recorded creator; setup keeps them"] : [], plan.labelsNotCreated?.length ? [`Labels that cannot be added: ${plan.labelsNotCreated.length}`] : []);
+        .concat(plan.unfilledLoadBearing?.length ? [`Required work stages still missing: ${plan.unfilledLoadBearing.length}`] : [], (plan.provenanceGaps?.length ?? 0) + (plan.labelProvenanceGaps?.length ?? 0) ? ["Some existing states or labels have no recorded creator; setup keeps them"] : [], unfinishedLabelLines(plan));
 }
 /** The only adopt bodies setup sends: this team, and the approved mode and hash. */
 export function adoptRequestAllowed(body, team, allow) {
@@ -391,7 +413,7 @@ export function onboardWorkflowVerificationAdapter(input = {}) {
                     : {}),
             },
         };
-    }, () => input.message?.(`${onboardTeamKey(journal) ?? "This team"} already has every state and label`));
+    }, () => input.message?.(`${onboardTeamKey(journal) ?? "This team"} has every required state and label`));
     if (!adopts)
         return { check };
     // A local non-admin never gets here; a 403 means the seat changed after login.
@@ -440,7 +462,10 @@ export function onboardWorkflowVerificationAdapter(input = {}) {
                     }
                     const created = (rows) => rows.filter((row) => row.outcome === "created").length;
                     const stages = created(reply.stages), labels = created(reply.labels);
-                    summary = `Applied the Catalyst workflow to ${key}: created ${stages} ${stages === 1 ? "stage" : "stages"} and ${labels} ${labels === 1 ? "label" : "labels"}.`;
+                    summary = [
+                        `Applied the Catalyst workflow to ${key}: created ${stages} ${stages === 1 ? "stage" : "stages"} and ${labels} ${labels === 1 ? "label" : "labels"}.`,
+                        ...unfinishedLabelLines(reply),
+                    ].join("\n");
                     return { state: "done" };
                 }, () => input.message?.(summary));
                 // Only the server's own plan-stale answer plans again; a later identity refusal does not.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.15.6",
+  "version": "0.16.0",
   "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "license": "MIT",
   "type": "module",
@@ -48,18 +48,21 @@
     "paths:check": "node scripts/vendor-paths.mjs --check",
     "prose:check": "node scripts/check-public-prose.mjs",
     "settings:check": "node scripts/vendor-settings.mjs --check",
-    "self-host:check": "node scripts/vendor-self-host.mjs --check"
+    "self-host:check": "node scripts/vendor-self-host.mjs --check",
+    "release:check": "node scripts/release-train-check.mjs && node --test scripts/release-train-check.test.mjs",
+    "prepublishOnly": "node scripts/release-train-check.mjs --publish cli"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "0.14.1",
+    "@catalyst-cloud/sdk": "0.16.0",
     "@clack/prompts": "1.8.1",
     "fast-string-width": "3.0.2",
     "fast-wrap-ansi": "0.2.2",
     "smol-toml": "^1.7.1",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.0",
+    "@catalyst-cloud/sdk-replica-node": "0.16.0"
   },
   "devDependencies": {
-    "@catalyst-cloud/schema": "0.13.1",
+    "@catalyst-cloud/schema": "0.16.0",
     "@types/node": "^26.3.0",
     "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ 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:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.0 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -4,7 +4,7 @@ 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 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.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.0 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 

package/skills/catalyst-onboard/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up Catalyst Cloud and say whether setup is working. Walks a person from nothing to their first ticket running, one step at a time: the coding account, the project, the integrations and connected accounts, each repository's settings file, then one real ticket moving. Also logs this machine in, reads the readiness verdict with who can fix each failure, and checks the optional local replica. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", "log me in", "which account is this machine on", "am I set up", "what is missing", "why does nothing happen" or "is the replica running", when a login expired, or when a skill script exits 2 saying this machine is not connected. Does every step a key can do through the catalyst CLI, hands over the exact page for the steps only a browser can do, and never claims a step it did not watch succeed.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.0 — written in this repository for customer accounts -->
 
 # Onboard me
 

package/skills/catalyst-onboard/references/declaring-a-repository.md

@@ -14,7 +14,7 @@ The assistant prepares `.catalyst/catalyst.toml` from the repository. Never ask
 
 Show a short preview with the project/team, setup and verify commands, variable names, which are marked secret, and confirmation that every variable is optional. Do not include values. Ask the person to approve this exact draft. Before approval, do not write or replace `.catalyst/catalyst.toml`, remove `catalyst.env.json`, or open a settings PR.
 
-After approval, write the validated file. When converting a legacy-only repository, remove `catalyst.env.json` in the same change. Open the settings PR, then offer to watch it merge. Once merged, give the owner or admin a direct link to approve the new declaration revision at Settings → Your projects → the project → Repositories → the repository → Environment → Setup declaration → Approve this revision. The direct route is `/settings/projects/$projectId/repositories/$repoId/environment/declaration`; use the project and repository ids from Catalyst instead of guessing them.
+After approval, write the validated file. When converting a legacy-only repository, remove `catalyst.env.json` in the same change. Open the settings PR, then offer to watch it merge. A reviewed merge is the approval. Catalyst approves the exact merged revision, with no second step, when someone other than the PR's author approved the merged head commit, or when a workspace owner or admin merged the PR. Tell the person this before they merge: the approving review is their consent to the setup commands and secret names in the file, so a reviewer should read it like code. A direct push, an unreviewed merge, or an approval left before the last commit leaves the revision proposed. Only then give an owner or admin a direct link to approve it at Settings → Your projects → the project → Repositories → the repository → Environment → Setup declaration → Approve this revision. The direct route is `/settings/projects/$projectId/repositories/$repoId/environment/declaration`; use the project and repository ids from Catalyst instead of guessing them.
 
 ## File shape
 

package/skills/catalyst-onboard/references/reading-ready.md

@@ -44,7 +44,7 @@ A team is `ready`, `degraded`, `blocked` or `unchecked` (no pass yet, a note). S
 | `writes_land` | Catalyst has written to the team | `no_write_observed` clears on the first move; a refused write: check the connection and permissions | owner or admin when refused; otherwise nobody |
 | `webhook_covers_team` | the team's events arrive | `no_delivery_observed` clears once a registered repository's events flow | owner or admin, by registering the repository |
 | `hosts_current` | no connected host runs an older mapping | `references/what-a-phase-needs.md`; `no_host_connected` is waiting | whoever runs that host |
-| `environment_declared` | the default repository's `.catalyst/catalyst.toml` is ingested, valid and approved | the reason names the step: register a default repository, commit or fix the file, or approve it (`references/declaring-a-repository.md`) | owner or admin, except committing the file, which is whoever can push |
+| `environment_declared` | the default repository's `.catalyst/catalyst.toml` is ingested, valid and approved | the reason names the step: register a default repository, commit or fix the file through a reviewed pull request, or approve a revision that merged without one (`references/declaring-a-repository.md`) | owner or admin, except committing the file, which is whoever can push |
 | `tools_resolvable` | every MCP server and CLI the declaration names resolves | `tool_reference_unresolved`: add the secret or fix the declaration; `toolchain_cli_missing` is not self-service | owner or admin, in the declaration or Settings → Environment |
 | `reviewer_required` | the repository can merge under its policy | a strict policy with no reviewer: configure one at Settings → Your projects → the project → Repositories → the repository → Code reviews, or relax the policy; only the merge waits | owner or admin, in settings |
 | `reviewer_configured` | a code reviewer is configured at all | configure one there; a fail never blocks or degrades | owner or admin, in settings; nobody is required when it fails |

package/skills/catalyst-onboard/scripts/where-am-i.mjs

@@ -1050,7 +1050,7 @@ const DECL_REASONS = {
     page: null,
   },
   declaration_awaiting_approval: {
-    text: "the declaration is proposed and waits for approval: Settings → Your projects → the project → Repositories → the repository → Environment → Setup declaration → Approve this revision",
+    text: "the declaration is proposed and waits for approval, because no review approved it (a non-author approval of the merged head, or a merge by an owner or admin): approve it at Settings → Your projects → the project → Repositories → the repository → Environment → Setup declaration → Approve this revision",
     who: "a workspace owner or admin",
     page: "/settings/projects",
   },
@@ -1058,7 +1058,7 @@ const DECL_REASONS = {
 const DECL_DO =
   "write .catalyst/catalyst.toml with references/declaring-a-repository.md, then open a pull request";
 let declNext =
-  "commit .catalyst/catalyst.toml to the repository and have an owner or admin approve it";
+  "merge .catalyst/catalyst.toml through a pull request that someone other than the author approves; that review approves it";
 if (!connected) {
   add(
     "repository declarations",

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

@@ -4,7 +4,7 @@ description: >-
   Own one Catalyst Cloud project end to end until it closes. Use when the person says "run this project for me", "own this until it ships", "keep this moving", or hands you a project id or a set of tickets to drive. Subscribes to the account's event stream for the scope through the catalyst CLI, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Writes to Linear as the app actor; never polls.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.0 — written in this repository for customer accounts -->
 
 # Run this project
 

package/skills/unstick/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.0 — written in this repository for customer accounts -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   The human's decision inbox on Catalyst Cloud, and the one way an agent raises a decision on their behalf. Use when the person asks "what needs me?", "what am I blocking?", or when active work is gated on a choice only they can make. Lists open asks ranked by how much open work each one holds, files an ask through the cloud's ask route with the account's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.0 — written in this repository for customer accounts -->
 
 # What needs me
 
@@ -15,7 +15,7 @@ An ask is one decision only the human can make, filed as a ticket in their own L
 Scripts are run, never read. Each prints `--help`; exit 2 means this machine is not connected (the `catalyst-onboard` skill connects it), exit 1 means the check itself failed or an argument was missing.
 
 - `node scripts/inbox.mjs --help`: the open asks assigned to the connected person, most open tickets held first, then the oldest; `--anyone` for everyone's; `--json` for `{scope, asks}`.
-- `node scripts/raise.mjs --help`: file one decision: `--team`, `--title`, `--option` (repeated), `--default`, and `--blocks` (repeated) or `--nothing-to-block`.
+- `node scripts/raise.mjs --help`: file one decision: `--team`, `--title`, `--option` (repeated), `--default`, and `--blocks` (repeated) or `--nothing-to-block`. When the ask decides whether a held PR may merge, `--gates-pr` (repeated) with `--released-by <letter>` makes the answer lift that PR's hold label.
 - `node scripts/settle.mjs --help`: record the answering comment on an ask and post a release note on every ticket it held; `--close` moves the ask to the done slot.
 
 ## Load on demand

package/skills/what-needs-me/references/raising-a-decision.md

@@ -18,6 +18,17 @@ Brainstorming, design back-and-forth, a question the human asked first, a retry-
 
 `--ask-key` is an idempotency key: a re-run with the same key does not file a second ask.
 
+## When the answer releases a PR hold
+
+When the decision is whether a held PR may merge, name the PR so the answer lifts the hold itself:
+
+- `--gates-pr <n>` (repeated): each PR the answer releases.
+- `--released-by <letter>` (repeated, required with `--gates-pr`): the option letters that release it. Options are lettered A, B, C in the order you gave them, and a letter outside that range is refused.
+- `--gates-label hold|hold:preview` (repeated, default `hold`): the labels the answer removes. No other label is accepted.
+- `--gates-repo <owner/name>`: the PR's repository. It defaults to the account's repository when the account registers exactly one, and must be one the account registers.
+
+An answer with any other letter leaves the labels in place.
+
 ## One ask per decision
 
 Run `node scripts/inbox.mjs` first. When the same decision is already open, attach the new held tickets to it (the `catalyst-linear` skill adds the relation or a comment) rather than filing a twin that splits its urgency.

package/skills/what-needs-me/scripts/raise.mjs

@@ -14,12 +14,16 @@ const SPEC = {
   blocks: { value: true, repeat: true, help: "a ticket this decision holds (repeat per ticket)" },
   "nothing-to-block": { value: false, help: "declare that no ticket is held (the ask then never shows in Waiting on me)" },
   "ask-key": { value: true, help: "idempotency key so a re-run does not file a second ask" },
+  "gates-pr": { value: true, repeat: true, help: "a PR whose hold label the answer removes (repeat per PR; needs --released-by)" },
+  "gates-label": { value: true, repeat: true, help: "the hold the answer removes: hold or hold:preview (repeatable; default hold)" },
+  "released-by": { value: true, repeat: true, help: "an option letter whose answer releases the hold (repeat per letter)" },
+  "gates-repo": { value: true, help: "the --gates-pr repository as owner/name (default: the account's only repository)" },
   json: { value: false, help: "print the cloud's response as JSON" },
 };
 
 const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
 if (help) {
-  printHelp("node scripts/raise.mjs --team <key> --title <question> [--context <text>] [--option <text>]... [--default <text>] --blocks <ticket>... | --nothing-to-block [--ask-key <key>] [--json] [--help]", SPEC, [
+  printHelp("node scripts/raise.mjs --team <key> --title <question> [--context <text>] [--option <text>]... [--default <text>] --blocks <ticket>... | --nothing-to-block [--ask-key <key>] [--gates-pr <n>... --released-by <letter>... [--gates-label hold|hold:preview]... [--gates-repo <owner/name>]] [--json] [--help]", SPEC, [
     "Search for an existing ask first (node scripts/inbox.mjs); one decision, one ask.",
     "File BEFORE proceeding on the default. Cite the identifier only from this script's output.",
   ]);
@@ -41,6 +45,10 @@ if (flags.default) args.push("--default", flags.default);
 for (const b of flags.blocks ?? []) args.push("--blocks", b);
 if (flags["nothing-to-block"]) args.push("--nothing-to-block");
 if (flags["ask-key"]) args.push("--ask-key", flags["ask-key"]);
+for (const n of flags["gates-pr"] ?? []) args.push("--gates-pr", n);
+for (const l of flags["gates-label"] ?? []) args.push("--gates-label", l);
+for (const l of flags["released-by"] ?? []) args.push("--released-by", l);
+if (flags["gates-repo"]) args.push("--gates-repo", flags["gates-repo"]);
 args.push("--json");
 
 const result = parseJson(mustRun(args, { quiet: true }).stdout, "ask raise");
@@ -49,5 +57,6 @@ if (flags.json) process.stdout.write(JSON.stringify(result) + "\n");
 else {
   process.stdout.write(`ask raised: ${id ?? "(no identifier returned)"}${flags.blocks ? ` — holds ${flags.blocks.join(", ")}` : " — holds nothing"}\n`);
   if (flags.default) process.stdout.write(`default if silent: ${flags.default}\n`);
+  if (flags["gates-pr"]) process.stdout.write(`answer ${flags["released-by"].join(" or ")} releases the hold on PR ${flags["gates-pr"].map((n) => `#${n}`).join(", ")}\n`);
 }
 process.exit(0);

package/skills/what-this-repo-needs/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups (build/test, deploy-only, bindings), each with where it was found, what uses it, and where a local value would come from. Never reads a value or prints one. Also checks the environment variable table in `.catalyst/catalyst.toml` offline. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing the declaration.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.0 — written in this repository for customer accounts -->
 
 # What this repository needs
 

package/skills/whats-happening/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Use for "what's happening?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer as the human.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.0 — written in this repository for customer accounts -->
 
 # What's happening