@catalyst-cloud/catalyst-skills 0.1.1 → 0.2.0

package/skills/whats-happening/assets/status-reply.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Catalyst status reply",
+  "description": "The one-reply shape a status answer follows. Every line names a ticket identifier; nothing in it is a guess. Fill it from scripts/snapshot.mjs and scripts/explain.mjs, then render it as prose in this order.",
+  "type": "object",
+  "required": ["asOf", "source", "inFlight", "blocked", "closed", "next"],
+  "properties": {
+    "asOf": { "type": "string", "format": "date-time", "description": "When the snapshot was taken (snapshot.takenAt)." },
+    "source": {
+      "type": "string",
+      "description": "Where the facts came from, in one clause: the API, or the replica with its cursor and heartbeat age. Copy the snapshot's source line; never omit it when the replica was stale."
+    },
+    "scope": { "type": "string", "description": "The team key or project the reply covers, when the human asked about one." },
+    "inFlight": {
+      "type": "array",
+      "description": "Tickets a phase is running on right now, or that sit mid-ladder with a live lease. One entry per ticket.",
+      "items": { "$ref": "#/$defs/line" }
+    },
+    "blocked": {
+      "type": "array",
+      "description": "Tickets nothing is offered for, each with the reason in the human's words and who or what releases it.",
+      "items": {
+        "allOf": [
+          { "$ref": "#/$defs/line" },
+          {
+            "properties": {
+              "reason": { "type": "string", "description": "The explainer's reason, translated (references/why-is-it-stuck.md)." },
+              "onWhom": { "type": "string", "description": "The human, a named role, the cloud itself, or a clock — never blank." }
+            },
+            "required": ["reason", "onWhom"]
+          }
+        ]
+      }
+    },
+    "waitingOnHuman": {
+      "type": "array",
+      "description": "Open asks, ranked by what each holds. Taken from snapshot.waitingOnHuman; the what-needs-me skill owns the detail.",
+      "items": {
+        "type": "object",
+        "required": ["ticket", "question", "holds"],
+        "properties": {
+          "ticket": { "type": "string" },
+          "question": { "type": "string" },
+          "holds": { "type": "array", "items": { "type": "string" }, "description": "Ticket identifiers the answer releases." }
+        }
+      }
+    },
+    "closed": {
+      "type": "array",
+      "description": "Tickets that reached the done slot since the window the human asked about (or since the last reply).",
+      "items": { "$ref": "#/$defs/line" }
+    },
+    "next": {
+      "type": "array",
+      "description": "What the queue will pick up next, in queue order, with the phase each will run.",
+      "items": { "$ref": "#/$defs/line" }
+    },
+    "cannotSee": {
+      "type": "array",
+      "description": "Facts the account key cannot read yet, named, with where the human can read them (the CLI prints the URL).",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "line": {
+      "type": "object",
+      "required": ["ticket", "summary"],
+      "properties": {
+        "ticket": { "type": "string", "description": "The identifier, KEY-123 shape." },
+        "summary": { "type": "string", "description": "One clause: what it is and where it stands." },
+        "stage": { "type": "string", "description": "The stage name as the contract spells it for this team." },
+        "phase": { "type": "string", "description": "The ladder phase running or offered, when known." },
+        "age": { "type": "string", "description": "How long it has sat where it is, in human units." }
+      }
+    }
+  }
+}

package/skills/whats-happening/references/reading-the-board.md

@@ -0,0 +1,43 @@
+# Reading the board
+
+This reference restates invariants: what the stages are, what order they come in, and what "stuck" means. The names your team uses for each stage, and which state ids they map to, are tenant facts read live from the contract; `node scripts/snapshot.mjs --board` prints the board already grouped and ordered by them.
+
+## Stages are slots, names are display
+
+Catalyst thinks in eleven **slots** in pipeline order: dispatch, intake, research, plan, implement, remediate, verify, review, pr, done, canceled. Each of your teams maps some or all of those slots onto its own Linear workflow states. The contract carries, per team and per slot, the state id (the authority), the live state name and type (display), and whether the state still exists in Linear. A team may have adopted Catalyst's recommended states, mapped its existing ones, or mixed the two; the contract's `workflowMode` says which.
+
+Five slots are load-bearing and a missing one is a distinct silent failure: **dispatch** (where a card goes to be picked up), **intake** (an optional first pass for tickets that have never entered the ladder), **pr** (where a card sits while its pull request is reviewed and merged), **done** and **canceled**. The other six are informational: a wrong mapping there costs a warning, not a stall.
+
+Read a board by slot, never by name. Two teams can call the same slot different things, and a state renamed in Linear keeps its id and its slot.
+
+## Work in progress by stage
+
+The snapshot's `board` block groups open tickets by state name in slot order, drops terminal states, and lists any state name that maps to no slot at the end. Read it top to bottom:
+
+- **dispatch** holds what is ready and waiting for a container. A long dispatch column with nothing in flight is a capacity or eligibility question, not a work question: run `explain` on the first row.
+- **intake** through **pr** are the ladder. A card advances one slot when the matching phase completes; a failed phase writes no board state, so a card that has not moved is either still running, retrying in place, or moved sideways to remediate.
+- **remediate** is an interrupt, not a step. A card there was moved by a failure and returns to its exact previous stage when a repair round succeeds. Count remediate cards separately; they are not progress.
+- Backlog-type states are not slots. A ticket there is parked or not yet chosen; nothing is offered for it and nothing is wrong with it.
+
+## Aging
+
+Age is time since `updated_at`, or since the lease started for a ticket in flight. Report it in human units. Compare it to the phase, not to a fixed number: a research phase and a merge wait have different natural durations, and the cloud's own retry backoff (the contract's `thresholds.retryBackoffMs`) explains many short waits.
+
+## What counts as stuck
+
+A ticket is **stuck** only when all three hold:
+
+1. Nothing is offered for it: the queue lists it excluded, or `explain` gives a reason rather than a position.
+2. The reason does not release itself. Backoffs, cooldowns that name a callback, and fleet-wide holds that clear when the cloud repins are waits, not stalls. The table in `references/why-is-it-stuck.md` marks which is which.
+3. No one is acting on the release: no open ask names it, no human comment landed after the failure, no push arrived.
+
+Everything else is **waiting**, and the reply says what it is waiting on. Calling a wait "stuck" sends the human to fix something the cloud is already handling.
+
+## The signals the cloud posts on the ticket itself
+
+Before declaring anything, read the ticket's comments (`catalyst-skills query issue <id>`; the `catalyst-linear` skill explains each shape). The cloud posts a phase-outcome card on every completion and failure, a remediate-attempt card per repair round, a board-health note when it detects a stall itself, and a merge-wait note when a merge is held. Those comments are the execution history a key can read today; the per-ticket ledger behind them is not visible to an account key yet, and `explain --history` says so.
+
+## Two things that look like work and are not
+
+- A ticket carrying the ask marker label, or whose text reads as a decision request, is a question. It is excluded from dispatch by design and belongs in the waiting-on-human block.
+- A ticket claimed by a worker outside the cloud (the local-lane label) is being worked, but not by Catalyst; report it as in flight elsewhere and do not chase the cloud for it.

package/skills/whats-happening/references/reprioritising.md

@@ -0,0 +1,37 @@
+# Reprioritising
+
+This reference restates invariants: how Catalyst orders work and which levers a person actually has. The live queue is `catalyst-skills queue [--team K]` (inside `node scripts/snapshot.mjs`); the thresholds behind backoffs and parks are the contract's `thresholds` block, printed in the snapshot's `tenant` section.
+
+## How the cloud orders work
+
+Each team's queue is derived by the cloud itself from the team's own tickets, so there is nothing a session publishes and nothing that goes stale between sessions. The order is:
+
+1. **Priority** ascending, as set on the Linear ticket (urgent first).
+2. **Created time** ascending: older tickets first among equals.
+3. **Identifier** ascending, as the final tiebreak.
+
+Tickets that are already **mid-ladder** join the same candidate set and sort ahead by how many phases they have completed, so a ticket that is nearly done finishes before a fresh one starts. That is an ordering rule only; it never makes an ineligible ticket eligible.
+
+Within the order, dispatch is bounded per repository (a concurrency cap the tenant admin can set in settings, and a paused repository resolves to zero) and split across teams so one team cannot starve another. Comment-wake work, where the cloud answers a human comment on a ticket, shares the same cap as relay work.
+
+The queue is recomputed on every ingest that touches the team and on each alarm pass, so a change you make shows up within seconds, not on a schedule.
+
+## The three levers a person has
+
+**1. Priority on the ticket.** Change the Linear priority and the queue reorders itself. This is the lever for "do this one first". It does not jump a running phase; it changes what is picked up next.
+
+**2. The dispatch column.** A card is offered only when it sits in the team's dispatch slot (and, for a ticket that has never entered the ladder, the intake slot when intake is enabled). Moving a card into that slot is how work is started; moving it out to a backlog-type state is how work is stopped without cancelling it. The `run-this-project` skill has the script; through this skill you describe the move and let the person or the project owner make it.
+
+**3. Holds.** A PR label from the contract's `merge.prLabels` set keeps an otherwise-mergeable pull request out of the merge queue until a person removes it. A blocking relation from an ask holds every ticket the ask names. Applying the release label the contract names frees a ticket the ask-shape detector flagged by mistake.
+
+Everything else that looks like a lever is not one from a key: unparking a phase, clearing a repair hold, resetting a validate budget and re-pinning a base are operator actions today, and the reply says so and names the settings page rather than promising them.
+
+## What not to promise
+
+- **A running phase is not interrupted** by any of the three levers. It finishes or fails on its own; then the new order applies.
+- **A failed phase does not need re-queueing.** A pre-branch failure or an infrastructure failure retries in place after a backoff; a later failure moves the card to the remediate slot and queues a repair round, capped by the contract's `thresholds.remediateRoundCap`; repeated failures park it after `thresholds.parkAfterConsecutiveFailures`. Moving the card by hand during that sequence usually restarts the count rather than shortening it.
+- **Priority is not urgency to the human.** An urgent ticket that is blocked on an ask still waits for the ask. The what-needs-me ranking (by what an answer releases) is the right list for the human; the queue is the right list for the fleet.
+
+## Answering "why is that one not next?"
+
+Run `explain` on it. If the answer is a position, it is next in order and the cloud is bounded by capacity: say how many are ahead and whether any run at all (if nothing runs anywhere, the likely cause is coding-account capacity, which a key cannot read yet, so name the settings page). If the answer is a reason, use `references/why-is-it-stuck.md`. If the answer is that the ticket is not in the explainer, it is on another team, terminal, or unknown to the mirror: check the identifier before anything else.

package/skills/whats-happening/references/routing-work.md

@@ -0,0 +1,36 @@
+# Routing work
+
+This reference restates an invariant: what this skill does when the person asks for something to be done rather than known, and where a decision goes. Nothing here is tenant-specific.
+
+## Three kinds of request
+
+A message from the person is one of three things, and you decide which in the first sentence of your reply:
+
+1. **A question.** "Where is X? Why is Y stuck? What closed today?" Answer it in the one-reply shape (`references/status-reply.md`). No routing.
+2. **A request for work.** "Get X done. Ship the Y change. Own this until it closes." Turn it into a project with an owner, in one pass, as below.
+3. **A decision only they can make**, surfaced by you or by the cloud. That is never answered here; it goes to `what-needs-me`.
+
+A request that contains a decision is both: route the work and raise the decision, and say in the reply that you did both.
+
+## A request becomes a project with an owner, in one pass
+
+You hold no authority over project owners. Your job is to make the work visible and hand it to a single-threaded owner, then get out of the way.
+
+1. **Find the existing home first.** `catalyst-skills query projects` and `query search <terms>`. A request that fits an open project is a ticket in that project, not a new project. Duplicate projects split one goal's status across two places.
+2. **Scaffold when there is no home.** State the outcome in one sentence, the first ticket or two, and who owns it. Tickets are created through the `catalyst-linear` skill (the app actor, the team key from the contract); a project itself is created by the person in Linear, so name what you want it called and ask them to create it if none fits.
+3. **Name the owner.** The owner is a `run-this-project` session for that project, or a person. Say which, in the reply. Tell the person the one command that starts the owner session, and do not start long-running work inside this session: the desk answers questions; the owner reacts to events.
+4. **Say what you did.** The reply ends with the identifiers created, the owner named, and the next thing the person will see.
+
+Cite an identifier only after the create call returned it. A guessed number is usually a real, unrelated ticket.
+
+## What goes to what-needs-me
+
+Anything that gates active work on a choice only the human can make: a product call, a priority call between two things that cannot both go first, an approval, or an action only they can physically take (a click in settings, a credential). It is raised as an ask through the `what-needs-me` skill with the question, the options, the default that fires if they stay silent, and what it blocks, and it is raised **before** anyone proceeds on the default.
+
+Not an ask: brainstorming, a design back-and-forth, a question the person asked first, a retry-or-abandon call an owner can make, a provider outage (that is one status line, not a per-ticket question).
+
+## Three rules that bind this skill
+
+- **Never answer as the human.** You do not pick an option on an open ask, close one, or post in their voice. When their answer arrives in chat, it is recorded on the ask through `what-needs-me` so the record is complete, and it is recorded as the app actor, never as them.
+- **Escalate inward, never outward.** An instrument reports to the project owner; the owner asks the desk; the desk asks the human, as an ask. A single stuck ticket is never a page to the human. A system-level failure (provider down, out of capacity, rate-limited) is one line in the status reply, not a question per ticket.
+- **One door.** If the person needs a second place to look after your reply, add the missing block to the reply next time rather than pointing them at a dashboard.

package/skills/whats-happening/references/status-reply.md

@@ -0,0 +1,34 @@
+# The one-reply shape
+
+This reference restates an invariant of this skill: how a status answer is shaped. The facts inside it come live from `node scripts/snapshot.mjs` and `node scripts/explain.mjs`; the machine-readable schema is `assets/status-reply.json`.
+
+## The rule
+
+The person asked one question and gets one reply. If they would need a second surface, a second message, or a follow-up question from you to know where things stand, the reply is wrong. Every line names a ticket identifier. Nothing in the reply is a guess: a fact you could not read is named as unreadable, with where it lives.
+
+## The five blocks, in this order
+
+1. **In flight.** Tickets a phase is running on right now, or that hold a live lease mid-ladder. Source: the snapshot's `running` block (fleet activity, the agent roster, lease attributions). One line per ticket: identifier, the phase running, how long it has run.
+2. **Blocked, and on whom.** Tickets nothing is offered for. Source: the queue's excluded rows, then `explain` on each one the person cares about. Every line carries the reason in the person's words and who releases it: the human (an ask), a role, the cloud itself (a backoff, a park that self-releases), or a clock. "On whom" is never blank; if you cannot tell, say the reason the cloud gave and that the release is unknown to a key.
+3. **Waiting on the human.** The open asks, ranked by what each one holds. Source: `waitingOnHuman` in the snapshot. Keep this to identifier, the question, and what it releases; the `what-needs-me` skill owns the detail and the settling.
+4. **Closed.** What reached the done slot in the window the person asked about (or since your last reply). Source: `query issues` filtered by the team's done-slot stage name from the contract, or the change feed for a time window. When you did not read a window, say "since my last reply" and mean it.
+5. **Next.** What the queue picks up next, in the cloud's order, with the phase each will run. Source: the snapshot's `queue` block. Do not reorder it to what you think should be next; the levers are in `references/reprioritising.md`.
+
+A sixth block, **cannot see**, appears only when it is non-empty: the facts an account key cannot read yet (coding-account status, per-ticket execution history), each with the URL the CLI printed.
+
+## The header line
+
+The reply opens with one clause that says when and from where: the snapshot's `takenAt` and its source line. When the replica was stale or absent, the reply says the numbers came from the API; when it was fresh, it says the cursor. This is not decoration. A stale source that goes unmentioned is the way a wrong status reply happens.
+
+## Writing the lines
+
+- Identifier first, then the stage as the contract spells it for that team, then one clause. `KEY-123 · <stage name> · implement running 14 min`.
+- Age in human units (minutes, hours, days), from `updated_at` or the lease's start, never a raw timestamp.
+- A reason is the translation from `references/why-is-it-stuck.md`, not the cloud's snake_case token, unless the token is one the table does not know, in which case quote it as the cloud spelled it.
+- No adjectives about health. "Stuck" has a definition (`references/reading-the-board.md`); use it only when it applies.
+
+## What the reply never does
+
+- It never restates a stage name, threshold or label from memory. The snapshot's `tenant` block carries the live values; read them there each time.
+- It never answers an ask, proposes a default on the human's behalf inside the status reply, or moves anything. Routing a request is `references/routing-work.md`; a decision is the `what-needs-me` skill.
+- It never pads a short answer. When one ticket is in flight and nothing is blocked, the reply is three lines.

package/skills/whats-happening/references/why-is-it-stuck.md

@@ -0,0 +1,57 @@
+# Why is it stuck
+
+This reference restates an invariant: the vocabulary the cloud's eligibility explainer uses when nothing is offered for a ticket, translated for a person, with what releases each. `node scripts/explain.mjs <ticket>` prints the reason for one ticket; this table turns it into the next action. The `how-catalyst-works` skill carries the mechanism behind each row.
+
+## How to read a reason
+
+`explain` prints one paragraph: the queue position (or none), the status, the reason, a detail or marker when the cloud gave one, the last failure, and any advisories. Match the reason to a row below. "Releases itself" means the cloud clears it with no human action; "needs" names who acts. When a reason is not in this table, `explain` prints it as the cloud spelled it; report it verbatim and say the bundle does not know it.
+
+## Reasons that release themselves
+
+| reason | what it means | how it clears |
+| -- | -- | -- |
+| `retry_backoff` | the failed phase is retrying in place and waiting out its rung | a clock; the rungs are the contract's `thresholds.retryBackoffMs` |
+| `lease_held` | a live container already holds this phase | the phase finishes |
+| `intake_lease_held` | a later phase is offered while an intake container still holds the ticket | intake finishes |
+| `environment_check_running` | the repository's environment check is in flight | the check finishes |
+| `runner_image_breaker` | fleet-wide: the live runner image fails every phase at startup, so dispatch is held rather than parking tickets | the cloud moves the pin; one alert per tenant, no per-ticket action |
+| `routing_unavailable` | claimed, then refused at kickoff: no route, no eligible coding-account slot, or the provider is unavailable | provider recovery or a slot freeing; if it persists, the tenant admin checks coding accounts in settings |
+| `cooling_down` (with a named callback) | the phase is parked on a condition the cloud watches | the callback fires; the `detail` names it |
+
+## Reasons that need a human
+
+| reason | what it means | who acts and how |
+| -- | -- | -- |
+| `ask_ticket` | it carries an ask label; a question is never work | the human answers the ask (`what-needs-me`) |
+| `ask_shape_suspected` | its own text reads as a decision request though it carries no ask label | the human either answers it as an ask or applies the release label the contract names |
+| `blocked` | a live blocking relation holds it | whoever owns the blocker closes it; if the blocker is an ask, that is the human |
+| `not_at_dispatch_stage` | the card is not in the team's dispatch column | someone moves the card to the dispatch slot (`references/reprioritising.md`) |
+| `not_at_pr_stage` | merge is next but the card is not in the PR column | the card returns to the pr slot; an automation that bounced it should be found |
+| `no_change_hold` | a repair round changed nothing | a human comment on the ticket, or a new push to the branch |
+| `waiting_on` | a merge-gate failure with no cause the cloud can repair | read the merge-wait comment on the ticket; usually a hold label or a review a person must give (`catalyst-github`) |
+| `externally_claimed` | a worker outside the cloud holds it | that worker, or the human removes the local-lane label |
+| `environment_check_required` / `_failed` / `_expired` / `_hash_mismatch` | the repository's environment gate has not passed | the tenant admin runs or fixes the environment check in settings |
+| `repo_paused` | an operator paused the repository | the operator resumes it |
+| `scope_overlap` | its declared file scope intersects a ticket already in flight | wait for the other ticket, or the human decides which goes first |
+
+## Reasons that need an operator, and what a key cannot do
+
+| reason | what it means | note |
+| -- | -- | -- |
+| `cooling_down` (parked after repeated failures, or the round cap was spent) | the phase is parked and does not release itself | an operator unparks it; an account key has no unpark verb yet, so the reply names the park and the settings page |
+| `remediate_parked` | the repair phase itself is parked, so the failing phase has nowhere to be repaired | as above |
+| `validate_class_spent` | this validate failure already spent its one repair round in this episode | as above; a human comment may release the hold |
+| `no_branch_to_remediate` / `branch_missing` / `branch_gone` | a branch-dependent phase has no branch to clone | the cloud releases missing-branch parks on its own budget; a deleted branch needs a human to decide |
+| `stale_failure_episode` | the ladder advanced after the recorded failure | informational; the round is dropped |
+
+## Reasons that are not problems
+
+`ticket_terminal` (done or canceled), `pipeline_complete` (every phase ran), and `pr_merged` (the PR merged, nothing left to clone) describe finished work. Report them as closed, not blocked.
+
+## When the cloud could not judge
+
+A status of `unknown` with a reason such as `ordering_never_published`, `ordering_stale`, `workflow_mapping_unknown`, `ticket_unknown`, `dependency_snapshot_unknown`, `blocker_unknown`, `label_snapshot_unknown`, `prior_artifact_unknown`, `scope_unknown`, `scope_occupancy_unknown` or `branch_snapshot_unknown` means the evaluator failed closed rather than guessing. Most clear on the cloud's next pass. If one persists for a team, the readiness checks (`catalyst-setup`) are the next read.
+
+## The one advisory
+
+`human_addressed_unlabeled_ask_suspect` gates nothing: the ticket is assigned to a human with no delegate and may be an unlabelled ask. Mention it in the waiting-on-human block with a question mark.

package/skills/whats-happening/scripts/explain.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// explain.mjs — "why is this ticket stuck?" in one paragraph. A thin wrapper over
+// `catalyst-skills explain <ticket>`, which reads the cloud's eligibility explainer for the ticket's
+// team and translates the exclusion reason, the failure block and any advisories into plain English.
+import { mustRun, parseFlags, printHelp } from "./lib/cli.mjs";
+
+const SPEC = {
+  json: { value: false, help: "print the raw eligibility row and the explanation as JSON" },
+  history: { value: false, help: "ask for the per-ticket execution history (the CLI says when a key cannot see it yet)" },
+};
+
+const { help, flags, positionals } = parseFlags(process.argv.slice(2), SPEC);
+const ticket = positionals[0];
+if (help || !ticket) {
+  printHelp("node scripts/explain.mjs <ticket> [--json] [--history] [--help]", SPEC, [
+    "The ticket is its identifier (the KEY-123 shape). The explanation names the queue position, the status,",
+    "the reason nothing is offered, the last failure, and what releases it; an unknown reason is printed as the",
+    "cloud spelled it. Read references/why-is-it-stuck.md to turn the reason into the next action.",
+  ]);
+  process.exit(help ? 0 : 1);
+}
+
+const args = ["explain", ticket];
+if (flags.history) args.push("--history");
+if (flags.json) args.push("--json");
+const r = mustRun(args);
+process.stdout.write(r.stdout.endsWith("\n") ? r.stdout : `${r.stdout}\n`);
+process.exit(0);

package/skills/whats-happening/scripts/lib/cli.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills CLI.
+// The CLI holds the SDK and the account key; this file holds neither. It reads customer.json only
+// to learn where the CLI lives, and it exits 2 with one line when the machine is not connected.
+// Run any script beside this one with --help; this file is a library and is never run directly.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const NOT_CONFIGURED_EXIT = 2;
+
+export function configPath() {
+  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/";
+  return join(home, ".config", "catalyst-cloud", "customer.json");
+}
+
+/** The connected-machine config, or exit 2 with the one line that says how to connect. */
+export function loadConfig() {
+  const path = configPath();
+  if (!existsSync(path)) notConfigured(`no config at ${path}`);
+  try {
+    const cfg = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof cfg !== "object" || cfg === null || typeof cfg.key !== "string") notConfigured(`config at ${path} has no key`);
+    return cfg;
+  } catch (err) {
+    if (err && err.exitCode === NOT_CONFIGURED_EXIT) throw err;
+    notConfigured(`config at ${path} is unreadable`);
+  }
+}
+
+function notConfigured(why) {
+  process.stderr.write(`not connected (${why}) — run: CATALYST_CLOUD_TOKEN=<account key> npx ${PACKAGE} login\n`);
+  process.exit(NOT_CONFIGURED_EXIT);
+}
+
+/**
+ * Run one catalyst-skills verb and return {code, stdout, stderr}. Uses the CLI path the login
+ * recorded when it still exists, else `npx <package>`. A CLI exit of 2 with a "not joined" or
+ * "not connected" line is turned into this script's own exit 2, so every caller sees one contract.
+ */
+export function runCli(args, opts = {}) {
+  const cfg = loadConfig();
+  const useRecorded = typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
+  const cmd = useRecorded ? process.execPath : "npx";
+  const argv = useRecorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
+  const res = spawnSync(cmd, argv, {
+    input: opts.stdin,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    shell: !useRecorded && process.platform === "win32",
+    env: process.env,
+  });
+  if (res.error) {
+    process.stderr.write(`could not run ${cmd}: ${res.error.message}\n`);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  const stdout = res.stdout ?? "";
+  const stderr = res.stderr ?? "";
+  if (res.status === NOT_CONFIGURED_EXIT && /not (joined|connected|configured)/i.test(stderr)) {
+    process.stderr.write(stderr);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  return { code: res.status ?? 1, stdout, stderr };
+}
+
+/** Run a verb and require success; on failure print the CLI's own stderr and exit with its code (or 1). */
+export function mustRun(args, opts = {}) {
+  const r = runCli(args, opts);
+  if (r.code !== 0) {
+    if (r.stderr) process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
+    if (r.stdout && !opts.quiet) process.stdout.write(r.stdout.endsWith("\n") ? r.stdout : `${r.stdout}\n`);
+    process.exit(r.code === 0 ? 1 : r.code);
+  }
+  return r;
+}
+
+/** Parse the CLI's --json stdout; a non-JSON answer is a failed check, exit 1. */
+export function parseJson(stdout, what = "output") {
+  try {
+    return JSON.parse(stdout.trim());
+  } catch {
+    process.stderr.write(`could not parse ${what} as JSON: ${stdout.trim().slice(0, 200)}\n`);
+    process.exit(1);
+  }
+}
+
+/** Minimal flag parsing for the scripts: --name value, --name=value, --flag, repeated flags collect. */
+export function parseFlags(argv, spec) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") return { help: true, flags, positionals };
+    if (a.startsWith("--")) {
+      let name = a.slice(2);
+      let value;
+      const eq = name.indexOf("=");
+      if (eq !== -1) {
+        value = name.slice(eq + 1);
+        name = name.slice(0, eq);
+      }
+      const s = spec[name];
+      if (!s) {
+        process.stderr.write(`unknown option --${name} (try --help)\n`);
+        process.exit(1);
+      }
+      if (s.value) {
+        if (value === undefined) value = argv[++i];
+        if (value === undefined || value === "") {
+          process.stderr.write(`--${name} needs a value\n`);
+          process.exit(1);
+        }
+        if (s.repeat) (flags[name] ??= []).push(value);
+        else flags[name] = value;
+      } else flags[name] = true;
+      continue;
+    }
+    positionals.push(a);
+  }
+  return { help: false, flags, positionals };
+}
+
+export function printHelp(usage, spec, notes = []) {
+  const lines = [`Usage: ${usage}`, ""];
+  const names = Object.keys(spec);
+  if (names.length) {
+    lines.push("Options:");
+    for (const n of names) lines.push(`  --${n}${spec[n].value ? " <value>" : ""}  ${spec[n].help}`);
+    lines.push("");
+  }
+  lines.push(...notes, "", "Exit codes: 0 ok · 1 the check failed or the arguments were wrong · 2 this machine is not connected to a tenant");
+  process.stdout.write(lines.join("\n") + "\n");
+}

package/skills/whats-happening/scripts/snapshot.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// snapshot.mjs — one call that answers "where are we?": the tenant contract (trimmed to what a
+// status reply needs), what is running, what is queued, what is waiting on a human, and whether the
+// local replica is fresh. Prints ONE JSON document on stdout and the source line on stderr.
+import { mustRun, parseFlags, parseJson, printHelp, runCli } from "./lib/cli.mjs";
+
+const SPEC = {
+  team: { value: true, help: "limit the queue and the board to this team key" },
+  board: { value: false, help: "also include open tickets grouped by stage, in the contract's slot order" },
+  limit: { value: true, help: "board: max tickets to read (default 200)" },
+  "full-contract": { value: false, help: "include the whole contract instead of the trimmed tenant block" },
+};
+
+const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
+if (help) {
+  printHelp("node scripts/snapshot.mjs [--team K] [--board] [--limit N] [--full-contract] [--help]", SPEC, [
+    "Runs, in order: catalyst-skills contract, running, queue, ask list, replica status (and query issues with --board).",
+    "Output: one JSON document {takenAt, source, tenant, running, queue, waitingOnHuman, board?, errors?}.",
+    "A section the cloud refused is reported under errors and the rest still prints; exit 1 in that case.",
+    "Every tenant fact (stage names, thresholds, teams) comes from the contract in this output, never from prose.",
+  ]);
+  process.exit(0);
+}
+
+const errors = {};
+const section = (name, args) => {
+  const r = runCli(args);
+  if (r.code !== 0) {
+    errors[name] = (r.stderr || r.stdout || `exit ${r.code}`).trim().split("\n").at(-1);
+    return null;
+  }
+  return parseJson(r.stdout, name);
+};
+
+const contract = parseJson(mustRun(["contract", "--json"], { quiet: true }).stdout, "contract");
+// `replica status` exits 0 fresh, 1 stale, 3 absent — all three are verdicts with JSON on stdout,
+// not failures; only a non-JSON answer is an error.
+const replica = (() => {
+  const r = runCli(["replica", "status", "--json"]);
+  try {
+    return JSON.parse(r.stdout.trim());
+  } catch {
+    errors.replica = (r.stderr || r.stdout || `exit ${r.code}`).trim().split("\n").at(-1);
+    return { verdict: "unknown", cursor: null, heartbeatAgeMs: null };
+  }
+})();
+const running = section("running", ["running", "--json"]);
+const queue = section("queue", flags.team ? ["queue", "--team", flags.team, "--json"] : ["queue", "--json"]);
+const asks = section("waitingOnHuman", ["ask", "list", "--json"]);
+
+const out = {
+  takenAt: new Date().toISOString(),
+  source: {
+    reads: "api",
+    replica: replica.verdict,
+    replicaCursor: replica.cursor ?? null,
+    replicaHeartbeatAgeMs: replica.heartbeatAgeMs ?? null,
+  },
+  tenant: flags["full-contract"] ? contract : trimContract(contract, flags.team),
+  running,
+  queue,
+  waitingOnHuman: asks,
+};
+
+if (flags.board) {
+  const args = ["query", "issues", "--limit", String(flags.limit ?? 200), "--json"];
+  if (flags.team) args.push("--team", flags.team);
+  const r = runCli(args);
+  const sourceLine = (r.stderr.match(/^source: .*$/m) ?? [null])[0];
+  if (r.code !== 0) errors.board = (r.stderr || `exit ${r.code}`).trim().split("\n").at(-1);
+  else {
+    const rows = parseJson(r.stdout, "issues");
+    out.board = groupByStage(rows, contract, flags.team);
+    if (sourceLine) out.source.board = sourceLine.replace(/^source: /, "");
+  }
+}
+
+if (Object.keys(errors).length) out.errors = errors;
+process.stderr.write(`source: api for running/queue/asks; replica ${replica.verdict}${replica.cursor != null ? ` (cursor ${replica.cursor})` : ""}${out.source.board ? `; board from ${out.source.board}` : ""}\n`);
+process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+process.exit(Object.keys(errors).length ? 1 : 0);
+
+/** The contract facts a status reply needs, and nothing a reply should not paste. */
+function trimContract(doc, teamKey) {
+  const teams = (doc.teams ?? []).filter((t) => !teamKey || String(t.key ?? "").toUpperCase() === teamKey.toUpperCase());
+  return {
+    contractVersion: doc.contractVersion,
+    account: { slug: doc.account?.slug, name: doc.account?.name },
+    slots: doc.slots,
+    ladder: { phases: doc.ladder?.phases, intakeEnabled: doc.ladder?.intakeEnabled, keying: doc.ladder?.keying },
+    thresholds: doc.thresholds,
+    mergeDefaultPolicy: doc.merge?.defaultPolicy,
+    teams: teams.map((t) => ({
+      key: t.key,
+      name: t.name,
+      workflowMode: t.workflowMode,
+      readiness: t.readiness?.status,
+      stages: Object.fromEntries(
+        (doc.slots ?? Object.keys(t.stages ?? {}))
+          .filter((slot) => t.stages?.[slot])
+          .map((slot) => [slot, { name: t.stages[slot].name, type: t.stages[slot].type, stateStillExists: t.stages[slot].stateStillExists }]),
+      ),
+      labels: {
+        ask: (t.labels?.ask ?? []).map((l) => l.name),
+        hold: (t.labels?.hold ?? []).map((l) => l.name),
+        release: (t.labels?.release ?? []).map((l) => l.name),
+      },
+    })),
+  };
+}
+
+/** Open tickets by stage name, ordered by the contract's slot order for the ticket's team; unmapped
+ *  state names follow, alphabetically. Terminal-typed states are dropped so the board is work only. */
+function groupByStage(rows, doc, teamKey) {
+  const order = [];
+  const seen = new Set();
+  const terminal = new Set();
+  for (const t of doc.teams ?? []) {
+    if (teamKey && String(t.key ?? "").toUpperCase() !== teamKey.toUpperCase()) continue;
+    for (const slot of doc.slots ?? []) {
+      const s = t.stages?.[slot];
+      if (!s?.name) continue;
+      if (slot === "done" || slot === "canceled" || ["completed", "canceled", "cancelled"].includes(String(s.type ?? "").toLowerCase())) terminal.add(s.name);
+      else if (!seen.has(s.name)) {
+        seen.add(s.name);
+        order.push(s.name);
+      }
+    }
+  }
+  const byStage = {};
+  for (const r of rows) {
+    const state = String(r.state ?? "unknown");
+    if (terminal.has(state)) continue;
+    (byStage[state] ??= []).push({
+      identifier: r.identifier,
+      title: r.title,
+      priority: r.priority ?? null,
+      assignee: r.assignee_name ?? r.assignee ?? null,
+      updatedAt: r.updated_at ?? null,
+      projectId: r.project_id ?? null,
+    });
+  }
+  const extra = Object.keys(byStage).filter((s) => !seen.has(s)).sort();
+  return { stageOrder: [...order, ...extra], byStage, terminalStagesDropped: [...terminal] };
+}

package/skills/ask/SKILL.md

@@ -1,37 +0,0 @@
----
-name: ask
-description:
-  Record a decision request to the human on the customer's catalyst-cloud tenant. Use when active work is gated on a decision only the human can make — a product/priority/approval call or an action only they can take. The ask carries the question, concrete options, a default that fires if they are silent, and what it blocks. Never use for brainstorming or questions the human asked first.
----
-
-<!-- vendored-from: @catalyst-cloud/catalyst-skills — adapted from the catalyst repository's catalyst-dev plugin (plugins/dev/skills/ask) for customer tenants -->
-
-# Ask — one decision, one record
-
-An ask is a decision request with a deadline-shaped default. It exists so that a question the human must answer is **one record they can find**, not a TODO line, a chat message, or a hope.
-
-## Shape of an ask
-
-An ask always carries, verbatim:
-
-1. **The question** — one sentence, as its title.
-2. **Options** — the realistic choices, each one line.
-3. **Default if silent** — what proceeds, and after how long. The default must be sane enough to actually run.
-4. **Blocks** — what work is held until it is answered, named by ticket or scope.
-
-## Where an ask lives
-
-An ask is a **ticket in the tenant's own Linear**, labelled `catalyst-ask`, written through the same Linear write access the `linearis` skill uses (the customer's own Linear tooling and credential — never a credential you improvised). The tenant's mirror recognises that label and holds the ticket out of the dispatchable pool, so a question is never mistaken for work. Cite the ask's identifier only after the create call returned it.
-
-## Rules
-
-- **File the ask BEFORE proceeding on the default.** Work may continue on the default only after the ask ticket exists; it may never run gated on an unasked question, and it may never run on a default that has no ticket behind it.
-- **One ask per decision.** Search for an existing ask first (`/api/v1/search?q=<terms>` through the `linearis` skill) — a duplicate splits one decision's urgency across two records.
-- **The human answers in the ask**, and when the answer arrives elsewhere (chat), post it back to the ask so question, options, default, answer, and who answered are one record.
-- **Never answer another role's ask**, and never answer as the human.
-- **Not everything is an ask.** Brainstorming, design back-and-forth, and questions the human asked first need no ticket. Operational retries, provider outages, and anything another agent can decide are never asks.
-- **Rank by blast radius**, not age: an ask that blocks a whole project outranks one that blocks a chore.
-
-## When no ticket can be filed
-
-If the tenant has no Linear write access wired up (the `linearis` skill reports none), the ask **cannot be filed, so the default does not fire**. Stop the gated work, and say so in your reply to the human with all four fields spelled out and the one action that unblocks everything: wire the Linear write path (or file the ask ticket by hand and tell you its identifier). Do not record the ask in a status summary, a TODO, or a handoff as a substitute — those are pointers to an ask, never the ask — and do not proceed on the default while no ticket exists.