@catalyst-cloud/catalyst-skills 0.1.1 → 0.2.1

package/skills/run-this-project/scripts/lib/cli.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: by spawning the catalyst-skills
+// CLI. The CLI holds the SDK and the account key; this file holds neither. It reads
+// ~/.config/catalyst-cloud/customer.json (under CATALYST_SKILLS_HOME when set, else HOME) for the
+// CLI path that login recorded and falls back to `npx @catalyst-cloud/catalyst-skills`.
+//
+// Exit codes every script built on this file shares: 2 = this machine is not connected, 1 = the
+// script's own check failed, 0 = fine.
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE_NAME = "@catalyst-cloud/catalyst-skills";
+export const NOT_CONFIGURED_EXIT = 2;
+export const CHECK_FAILED_EXIT = 1;
+
+export function homeDir() {
+  return process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? process.env.USERPROFILE ?? "/";
+}
+
+export function configDir() {
+  return join(homeDir(), ".config", "catalyst-cloud");
+}
+
+export function configPath() {
+  return join(configDir(), "customer.json");
+}
+
+/** The stored config, or null when the file is absent or unreadable. Never throws. */
+export function loadCustomerConfig() {
+  const path = configPath();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || typeof parsed.key !== "string" || typeof parsed.account !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Print the one not-connected line and exit 2. */
+export function requireConfigured() {
+  const cfg = loadCustomerConfig();
+  if (cfg) return cfg;
+  console.error(`not connected: ${configPath()} is missing or unreadable — run: CATALYST_CLOUD_TOKEN=<account key> npx ${PACKAGE_NAME} login`);
+  process.exit(NOT_CONFIGURED_EXIT);
+}
+
+/** The command and argument prefix that reaches the CLI on this machine. */
+export function cliCommand(cfg = loadCustomerConfig()) {
+  if (cfg && typeof cfg.cliPath === "string" && existsSync(cfg.cliPath)) {
+    return { command: process.execPath, prefix: [cfg.cliPath], via: `node ${cfg.cliPath}` };
+  }
+  const npx = process.platform === "win32" ? "npx.cmd" : "npx";
+  return { command: npx, prefix: [PACKAGE_NAME], via: `npx ${PACKAGE_NAME}` };
+}
+
+/**
+ * Run one CLI verb and capture its output. Resolves `{code, stdout, stderr, notConfigured}`;
+ * `notConfigured` is true when the CLI itself said the machine is not connected.
+ */
+export function runCli(args, { stdin } = {}) {
+  const { command, prefix } = cliCommand();
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, [...prefix, ...args], {
+      stdio: [stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+      env: process.env,
+      shell: process.platform === "win32",
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += String(d)));
+    child.stderr.on("data", (d) => (stderr += String(d)));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      resolve({ code: code ?? 1, stdout, stderr, notConfigured: /not (joined|connected)/i.test(stderr) || /not (joined|connected)/i.test(stdout) });
+    });
+    if (stdin !== undefined) child.stdin.end(stdin);
+  });
+}
+
+/**
+ * Run one CLI verb with the terminal attached, so a long-running verb such as `watch` streams
+ * straight through. Resolves with the exit code; SIGINT and SIGTERM are forwarded to the child.
+ */
+export function execCli(args) {
+  const { command, prefix } = cliCommand();
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, [...prefix, ...args], { stdio: "inherit", env: process.env, shell: process.platform === "win32" });
+    const forward = (sig) => () => {
+      try {
+        child.kill(sig);
+      } catch {
+        // already gone
+      }
+    };
+    const onInt = forward("SIGINT");
+    const onTerm = forward("SIGTERM");
+    process.on("SIGINT", onInt);
+    process.on("SIGTERM", onTerm);
+    child.on("error", reject);
+    child.on("close", (code) => {
+      process.off("SIGINT", onInt);
+      process.off("SIGTERM", onTerm);
+      resolve(code ?? 1);
+    });
+  });
+}
+
+/** Parse the CLI's --json output; a parse failure names the first line of what came back. */
+export function parseJson(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    throw new Error(`the CLI did not answer with JSON: ${stdout.split("\n")[0] ?? "(empty)"}`);
+  }
+}
+
+/** Exit 2 with the CLI's own not-connected line when a call reports it; otherwise return the result. */
+export function guard(result) {
+  if (result.notConfigured) {
+    process.stderr.write(result.stderr || result.stdout);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  return result;
+}
+
+/** A tiny flag parser: `--name value`, `--name=value`, `--flag`, repeatable names collected as arrays. */
+export function parseFlags(argv, { values = [], repeat = [], booleans = [] } = {}) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (!a.startsWith("--")) {
+      positionals.push(a);
+      continue;
+    }
+    let name = a.slice(2);
+    let value;
+    const eq = name.indexOf("=");
+    if (eq !== -1) {
+      value = name.slice(eq + 1);
+      name = name.slice(0, eq);
+    }
+    if (booleans.includes(name)) {
+      flags[name] = true;
+      continue;
+    }
+    if (!values.includes(name) && !repeat.includes(name)) {
+      console.error(`unknown option: --${name} (try --help)`);
+      process.exit(CHECK_FAILED_EXIT);
+    }
+    if (value === undefined) {
+      value = argv[++i];
+      if (value === undefined) {
+        console.error(`--${name} needs a value`);
+        process.exit(CHECK_FAILED_EXIT);
+      }
+    }
+    if (repeat.includes(name)) flags[name] = [...(flags[name] ?? []), value];
+    else flags[name] = value;
+  }
+  return { flags, positionals };
+}
+
+export function wantsHelp(argv) {
+  return argv.includes("--help") || argv.includes("-h");
+}
+
+const HELP = `lib/cli.mjs — shared helper; not a command.
+
+Resolves the catalyst-skills CLI (the path login recorded in ${configPath()}, else npx ${PACKAGE_NAME})
+and runs one verb for the script that imports it. Run any sibling script with --help instead.`;
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  console.log(HELP);
+  process.exit(0);
+}

package/skills/run-this-project/scripts/make-ready.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// make-ready.mjs — the two card moves a steward makes. Dispatch is a move into the team's dispatch
+// slot; parking is a move into the team's backlog-type state, which is not a slot, so the CLI
+// resolves it from the team's live workflow states. Every id comes from the contract or the live
+// state list; nothing here names a stage.
+import { CHECK_FAILED_EXIT, guard, parseFlags, parseJson, requireConfigured, runCli, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/make-ready.mjs <ticket> [--park] [--note <text>] [--json]
+
+Without --park: moves the card into the team's dispatch column, so the cloud offers its next phase.
+With --park:    moves the card into the team's backlog-type state, so nothing further is offered.
+
+Options:
+  --note <text>   also post a bookkeeping comment saying why (prefixed with the contract's marker,
+                  so it wakes nothing)
+  --json          print the CLI's JSON answers instead of the summary lines
+  --help          this text
+
+After a dispatch move the script asks the eligibility explainer about the ticket and prints its
+verdict. A verdict about a stale or unpublished ordering right after a move is normal: the cloud
+re-derives the queue within a pass; ask again in a minute.
+
+Exit codes: 2 not connected; 1 the move was refused (the CLI's reason is printed); 0 moved.`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags, positionals } = parseFlags(argv, { values: ["note"], booleans: ["park", "json"] });
+const ticket = positionals[0];
+if (!ticket || positionals.length !== 1) {
+  console.error("make-ready needs exactly one ticket identifier (see --help)");
+  process.exit(CHECK_FAILED_EXIT);
+}
+requireConfigured();
+
+const moveArgs = flags.park ? ["write", "state", ticket, "--state-type", "backlog"] : ["write", "state", ticket, "--slot", "dispatch"];
+const moved = guard(await runCli([...moveArgs, "--json"]));
+if (moved.code !== 0) {
+  process.stderr.write(moved.stderr || moved.stdout);
+  process.exit(CHECK_FAILED_EXIT);
+}
+const out = { ticket, action: flags.park ? "parked" : "dispatched", move: parseJson(moved.stdout) };
+
+if (flags.note) {
+  const body = `${flags.park ? "parked" : "dispatched"} by run-this-project: ${flags.note}`;
+  const noted = guard(await runCli(["write", "comment", ticket, "--bookkeeping", "--body", body, "--json"]));
+  out.note = noted.code === 0 ? parseJson(noted.stdout) : { failed: (noted.stderr || noted.stdout).trim() };
+}
+
+if (!flags.park) {
+  const explained = guard(await runCli(["explain", ticket, "--json"]));
+  out.eligibility = explained.code === 0 ? parseJson(explained.stdout) : { failed: (explained.stderr || explained.stdout).trim() };
+}
+
+if (flags.json) {
+  console.log(JSON.stringify(out));
+} else {
+  console.log(`${ticket}: ${out.action}`);
+  if (out.note) console.log(out.note.failed ? `note: not posted (${out.note.failed})` : "note: posted as a bookkeeping comment");
+  if (out.eligibility) console.log(out.eligibility.failed ? `eligibility: unknown (${out.eligibility.failed})` : `eligibility: ${out.eligibility.explanation}`);
+}
+process.exit(0);

package/skills/run-this-project/scripts/watch-scope.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// watch-scope.mjs — subscribe to the tenant stream filtered to one scope and pass every in-scope
+// frame through, one JSON line each. This is `catalyst-skills watch` with the scope flags checked
+// up front; the CLI owns the socket, the cursor file, the replay and the reconnects.
+import { CHECK_FAILED_EXIT, execCli, parseFlags, requireConfigured, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/watch-scope.mjs (--project <id> | --team <key> | --ticket <id>...) [options]
+
+Streams one JSON line per change inside the scope: a ticket, a comment, a pull request, a check, a
+review thread, an agent session or a fleet anomaly. Runs until the session ends (Ctrl-C).
+
+Scope (at least one; they combine):
+  --project <id>      every ticket in this Linear project, resolved through the ticket's own record
+  --team <key>        every ticket whose identifier carries this team key
+  --ticket <id>       one ticket (repeatable)
+
+Options:
+  --exec <command>    run this shell command once per frame with the frame on stdin; a non-zero exit
+                      is a failed reaction, so the cursor holds and the frame is offered again
+  --from cursor|head  start from the saved cursor (default) or skip straight to the tenant head
+  --cursor-file <p>   where the cursor lives (default ~/.config/catalyst-cloud/watch-cursor.json)
+  --help              this text
+
+Exit codes: 2 not connected; 1 no scope given; otherwise the CLI's own exit code.
+
+In Claude Code, arm a monitor on this command and react to each line in the same turn. In a harness
+with no monitor, pass --exec so the reaction still happens per frame and nothing polls.`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags, positionals } = parseFlags(argv, {
+  values: ["project", "team", "exec", "from", "cursor-file"],
+  repeat: ["ticket"],
+});
+if (positionals.length > 0) {
+  console.error(`unexpected argument: ${positionals[0]} (scope is given with --project, --team or --ticket)`);
+  process.exit(CHECK_FAILED_EXIT);
+}
+if (!flags.project && !flags.team && !(flags.ticket && flags.ticket.length)) {
+  console.error("watch-scope needs a scope: --project <id>, --team <key> or --ticket <id> (see --help)");
+  process.exit(CHECK_FAILED_EXIT);
+}
+if (flags.from && flags.from !== "cursor" && flags.from !== "head") {
+  console.error("--from must be cursor or head");
+  process.exit(CHECK_FAILED_EXIT);
+}
+requireConfigured();
+
+const args = ["watch"];
+if (flags.project) args.push("--project", flags.project);
+if (flags.team) args.push("--team", flags.team);
+for (const t of flags.ticket ?? []) args.push("--ticket", t);
+if (flags.exec) args.push("--exec", flags.exec);
+if (flags.from) args.push("--from", flags.from);
+if (flags["cursor-file"]) args.push("--cursor-file", flags["cursor-file"]);
+
+const code = await execCli(args);
+process.exit(code);

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

@@ -0,0 +1,41 @@
+---
+name: what-needs-me
+description: >-
+  The human's decision inbox on a Catalyst Cloud tenant, 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 what each answer releases, files an ask through the cloud's ask route with the tenant's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
+disable-model-invocation: true
+allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+---
+<!-- vendored-from: @catalyst-cloud/catalyst-skills — written in this repository for customer tenants -->
+
+# What needs me
+
+An ask is one decision only the human can make, filed as a ticket in their own Linear so that question, options, default, answer and who answered are one record. This skill reads that inbox ranked by blast radius, raises a new ask when work is gated, and settles the answer so the held work releases. The cloud renders the ask body from the tenant's template, applies the ask labels and creates the blocking relations; you pass fields, never headings.
+
+## Run first
+
+Scripts are run, never read. Each prints `--help`; exit 2 means this machine is not connected (run the `connect-me` skill), exit 1 means the check itself failed or an argument was missing.
+
+- `node scripts/inbox.mjs --help` — the open asks, ranked by the priority-weighted work each holds; `--json` for the rows.
+- `node scripts/raise.mjs --help` — file one decision: `--team`, `--title`, `--option` (repeated), `--default`, and `--blocks` (repeated) or `--nothing-to-block`.
+- `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
+
+| when | read |
+| -- | -- |
+| about to file an ask, or unsure whether something is one | `references/raising-a-decision.md` |
+| presenting the inbox, or the person asks what "waiting on me" means | `references/reading-the-inbox.md` |
+| an answer arrived, anywhere | `references/settling-an-answer.md` |
+
+The `catalyst-linear` skill posts the comment that carries an answer given in chat and reads an ask's thread; `whats-happening` explains a held ticket that stays excluded after the answer.
+
+## Rules
+
+- **File before proceeding on the default.** Work may run on a default only after the ask exists; a default with no ticket behind it is a guess, not a decision.
+- **One ask per decision.** Read the inbox first; attach new held tickets to an open ask rather than filing a twin. Duplicates split one decision's urgency across rows.
+- **Every ask names what it blocks.** The ranking the human sees is by held work weighted by priority, never by age; an ask that holds nothing does not reach Waiting on me unless you chose `--nothing-to-block` on purpose.
+- **Never answer as the human.** You do not pick an option, close an ask on their behalf, or post in their voice. Their answer is quoted into the ask as the app actor and recorded with its comment id.
+- **A free-text reply is recorded, never interpreted into an option.** If it does not answer the question, ask the one clarification in the thread and leave the ask open.
+- **Escalate inward.** A project owner raises asks for its scope; the desk raises what has no owner; a single stuck ticket or a provider outage is never an ask.
+- **Tenant facts come from the contract.** Team keys, label names, the option cap and the template are read live by the CLI; never restate them.
+- **Cite an identifier only after the create call returned it.**

package/skills/what-needs-me/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "What needs me"
+  short_description: "Your decision inbox on Catalyst Cloud, ranked by what each answer releases; raises and settles asks"
+  default_prompt: "Use $what-needs-me to show me what is waiting on my decision."
+policy:
+  allow_implicit_invocation: false

package/skills/what-needs-me/agents/portability.yaml

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

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

@@ -0,0 +1,41 @@
+# Raising a decision
+
+This reference restates invariants: what an ask is, when it is filed, and what it must carry. The body text, the headings, the option format and the cap on options are tenant facts served by the contract's `askTemplate` block and rendered by the cloud itself; `node scripts/raise.mjs` passes fields and never composes a heading.
+
+## What an ask is
+
+An ask is one decision only the human can make, filed as a ticket in the tenant's own Linear so that the question, the options, the default, the answer and who answered are one record the next agent can read. The cloud labels it as an ask, excludes it from dispatch (a question is never work), and holds every ticket it blocks until it is answered. It appears in the human's Waiting-on-me view when it is assigned to them and blocks open work.
+
+## When to file one
+
+File an ask when active work is gated on a product call, a priority call between two things that cannot both go first, an approval, or an action only the human can physically take (a click in settings, a credential, a payment). File it **before** proceeding on the default, never after, and never only as a TODO line, a board row, a handoff note or a chat question. Those may point at the ask's identifier; they never replace it.
+
+Do not file one for brainstorming, a design back-and-forth, a question the human asked first, a retry-or-abandon call a project owner can make, or a system-level failure (a provider down, out of capacity, rate-limited: that is one status line, and the affected tickets retry on their own).
+
+## What it carries
+
+1. **The question**, one sentence, as the title (`--title`).
+2. **Context** the human needs to answer without opening anything else (`--context`), short.
+3. **Options**, each one line, realistic, at most the number the contract allows (`--option`, repeated). The cloud letters and formats them.
+4. **The default if silent** (`--default`): what proceeds and after how long. It must be sane enough to actually run. Note that nothing in the cloud applies the default on a timer; the raising agent applies it, after the ask exists, and records that it did.
+5. **What it blocks** (`--blocks`, repeated): every ticket held until the answer lands. The cloud creates the blocking relations atomically with the ticket. An ask that holds nothing is refused unless you say `--nothing-to-block` on purpose, because an ask with no blocking relation never surfaces in Waiting on me and is indistinguishable from ordinary work.
+
+`--ask-key` is an idempotency key: a re-run with the same key does not file a second ask.
+
+## One ask per decision
+
+Run `node scripts/inbox.mjs` first and read the titles. When the same decision is already open, attach the new held tickets to it rather than filing again (the `catalyst-linear` skill adds the relation or a comment naming them). Duplicates split one decision's urgency across several rows and sink it below trivia in the ranking.
+
+## Who raises, and where
+
+- A decision inside a project scope is raised by that project's owner; the desk raises what has no owner.
+- The ask is filed on the team the held work belongs to (`--team`), from the contract's team list. An approvals team, when the contract names one, is where an approval with no natural team goes.
+- Never raise an ask on someone else's behalf about their own scope, and never answer one for the human.
+
+## After filing
+
+Cite the identifier the script printed, and only that. Proceed on the default if the work allows it, and say so in the ask's thread (a bookkeeping comment) so the record shows the default was taken. When the answer arrives, `references/settling-an-answer.md`.
+
+## Ranking
+
+The human sees asks ranked by how much open work each holds, weighted by that work's priority (urgent counts most), never by age. That is why `--blocks` must be complete: an ask that names one held ticket when it really holds a project sinks below a chore.

package/skills/what-needs-me/references/reading-the-inbox.md

@@ -0,0 +1,38 @@
+# Reading the inbox
+
+This reference restates invariants: what "waiting on me" means, how declared and inferred asks differ, and how to present the queue. The label that marks an ask, its prefix, and the release label are the contract's `vocabulary`; `node scripts/inbox.mjs` reads them from the CLI and never from prose.
+
+## What waiting-on-me means
+
+The tenant's own Waiting-on-me view lists a ticket for a person when all four hold:
+
+1. it is **assigned** to that person;
+2. it has **no delegate** (a ticket delegated to an agent is the agent's, not the human's);
+3. it is still **open**;
+4. what it **blocks** reaches open work: at least one ticket it holds is itself not done or canceled.
+
+A ticket that carries the ask marker label and is assigned to the person shows even with zero blocks. That is the **declared** ask. The four-part rule above is the **inferred** one, and the view offers both modes: asks only (the default) and everything the person is holding up, minus items an open unblock ask already covers.
+
+So an ask that holds nothing is real, but the person may never see it in their own view. `inbox.mjs` lists such asks last and marked, so you can attach the work they should block.
+
+## What the script reads
+
+`catalyst-skills ask list` reads the open tickets carrying the team's ask label (by the label ids and prefix the contract serves), follows each one's blocking relations to the tickets it holds, drops held tickets that are already terminal, and scores the rest by priority weight: urgent 4, high 3, medium 2, low 1, none 1. It does not filter by assignee, because the account key reads the tenant, not one person. When the human asks "what needs me", the answer is the ranked list; when they ask "what needs anyone", it is the same list.
+
+## Presenting the queue
+
+- Ranked by score, highest first. Never by age, never by identifier. An ask that holds a project outranks one that holds a chore, whatever their dates.
+- One line per ask: rank, identifier, what it holds (identifiers), the question. The human decides from the question and the held work, so both must be on the line.
+- Asks that hold nothing come after a break, marked as not visible in Waiting on me until they block something.
+- When the list is empty, say "nothing needs you" and stop. Do not pad it with suspected asks.
+- A ticket `explain` flagged as `ask_shape_suspected` (its text reads as a decision but it carries no ask label) is mentioned separately with a question mark: it is either an ask the human should label, or a false positive they release with the release label the contract names.
+
+## What the inbox is not
+
+- It is not the dispatch queue. Held tickets are excluded from dispatch by their blocking relation; answering the ask releases them into the ordinary order.
+- It is not a place to answer. Nothing in this skill picks an option, closes an ask on the human's behalf, or posts in their voice. When they answer in chat, `references/settling-an-answer.md`.
+- It is not a stall detector. A ticket parked by repeated failures, a merge hold, or a coding-account wall is a status question for `whats-happening`, not a decision until someone makes it one by raising an ask.
+
+## Free-text and interpreted replies
+
+A human reply that names no option is recorded by the cloud and interpreted for display, but never auto-applied and never written back to Linear as a decision. Treat it the same way: read it, ask the human to confirm which option it means if that is unclear, and settle only once a comment on the ask states the answer.

package/skills/what-needs-me/references/settling-an-answer.md

@@ -0,0 +1,37 @@
+# Settling an answer
+
+This reference restates invariants: where an answer is posted, how it is recorded, and how held work is released. The routes and the bookkeeping marker are the contract's; `node scripts/settle.mjs` reads them through the CLI.
+
+## The rule
+
+The answer lives on the ask. Wherever it arrived (a comment on the ask, a comment on a held ticket, a chat message, a call), it ends as a comment on the ask ticket, and that comment is recorded as the accepted answer. Question, options, default, answer and who answered are then one record.
+
+## The three steps
+
+**1. Post the answer where it should live.** If the human answered in the ask's thread, nothing to do. If they answered anywhere else, post a comment on the ask that states the answer, as the app actor, never as the human, and attribute it in the text ("the owner answered in chat: option B"). Use the `catalyst-linear` skill's comment script; it returns the comment id. Do not paraphrase into a different option; quote what they said.
+
+**2. Record it.** `node scripts/settle.mjs <ask> --answer <commentId> --role <role>` calls the cloud's ask-accept with the ask, the answering comment and the role doing the recording. The script first checks the comment is really on the ask (an id from a different ticket is refused before anything is written), then records, then reads the ask's blocking relations.
+
+**3. Release the held work.** For every open ticket the ask blocks, the script posts one bookkeeping comment naming the ask, the comment id and the first line of the answer, so the next phase or agent on that ticket reads the decision without opening the ask. The comment carries the contract's bookkeeping prefix, which means the cloud's comment-wake trigger ignores it: a record, not a turn in a conversation. Pass `--no-release-note` to skip this when the held tickets are about to be canceled anyway.
+
+With `--close`, the script also moves the ask to its team's done slot. The blocking relations stay on the record; a done ticket does not block anything, so the held tickets become dispatchable on the cloud's next pass. Close only when the answer is complete; an answer that raises a follow-up question keeps the ask open and the follow-up goes in the same thread.
+
+## Free-text replies
+
+A reply that names no option ("do whichever is cheaper", "ask me again Thursday") is recorded exactly as written. Nothing in the cloud or in this skill turns it into an option. Read it, decide whether it answers the question, and if it does not, reply in the thread with the one clarification needed and leave the ask open. If it does, settle with that comment as the answer and let the release note carry the quoted line.
+
+## Who settles
+
+The role that raised the ask, or the owner of the scope it belongs to. The desk settles asks that have no owner. The human never has to run anything; their part ends when they answer. Never settle another role's ask without saying so in the thread.
+
+## After settling
+
+- Tell the human, in one line, what was recorded and what it released.
+- The held tickets need no further action from you: their exclusion reason was the blocking relation, and the queue recomputes on the cloud's next pass. If one stays excluded, `whats-happening` explains why.
+- If the answer changes priorities or scope, that is a routing change for the project owner, not a second ask.
+
+## When it cannot be settled
+
+- The comment id is not on the ask: post the answer on the ask first, then settle with the new id.
+- The write budget for the day is spent: the CLI names the budget from the contract and exits 2. Say so; the record waits, the human's answer is not lost.
+- The ask is on a team the contract does not list: the tenant admin maps the team in settings; the `catalyst-setup` skill reads readiness.

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

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// inbox.mjs — "what needs me?": the open asks on this tenant, ranked by what each answer releases.
+// A thin wrapper over `catalyst-skills ask list`, which reads the open tickets carrying the team's
+// ask label (from the contract), follows each one's blocking relations, and weights held work by
+// priority. Prints the ranked list; --json prints the CLI's rows unchanged.
+import { mustRun, parseFlags, parseJson, printHelp } from "./lib/cli.mjs";
+
+const SPEC = {
+  json: { value: false, help: "print the ranked rows as JSON: {identifier, title, state, blocks[], score}" },
+  team: { value: true, help: "only asks whose identifier carries this team key" },
+  all: { value: false, help: "include asks that hold nothing (by default they are listed last, marked)" },
+};
+
+const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
+if (help) {
+  printHelp("node scripts/inbox.mjs [--json] [--team K] [--all] [--help]", SPEC, [
+    "Rank: the sum over held open tickets of a priority weight (urgent 4 ... low 1, none 1), highest first.",
+    "An ask that holds nothing is real but will not appear in the tenant's Waiting-on-me view; it is",
+    "listed last with a marker so you can attach the work it should block (references/reading-the-inbox.md).",
+  ]);
+  process.exit(0);
+}
+
+const rows = parseJson(mustRun(["ask", "list", "--json"], { quiet: true }).stdout, "ask list");
+const wanted = flags.team ? rows.filter((r) => String(r.identifier).toUpperCase().startsWith(`${flags.team.toUpperCase()}-`)) : rows;
+if (flags.json) {
+  process.stdout.write(JSON.stringify(wanted) + "\n");
+  process.exit(0);
+}
+if (wanted.length === 0) {
+  process.stdout.write("nothing needs you: no open asks\n");
+  process.exit(0);
+}
+const holding = wanted.filter((r) => r.blocks.length > 0);
+const idle = wanted.filter((r) => r.blocks.length === 0);
+let n = 0;
+for (const r of holding) {
+  n += 1;
+  process.stdout.write(`${n}. ${r.identifier}  holds ${r.blocks.length} (weight ${r.score}): ${r.blocks.join(", ")}\n   ${r.title}\n`);
+}
+if (idle.length && (flags.all || holding.length === 0)) {
+  process.stdout.write(`${holding.length ? "\n" : ""}asks that hold nothing (not shown in Waiting on me until they block something):\n`);
+  for (const r of idle) process.stdout.write(`   ${r.identifier}  ${r.title}\n`);
+} else if (idle.length) {
+  process.stdout.write(`\n(${idle.length} more ask${idle.length === 1 ? "" : "s"} hold nothing; --all lists them)\n`);
+}
+process.exit(0);