@catalyst-cloud/catalyst-skills 0.5.0 → 0.8.0

package/skills/how-catalyst-works/scripts/show-my-map.mjs

@@ -1,94 +0,0 @@
-#!/usr/bin/env node
-// show-my-map.mjs — this tenant's stage map, ladder and thresholds, straight from the contract:
-// per team, every slot with the Linear stage it maps to, its type, whether that state still exists
-// and how the mapping was chosen; then the ladder and the live failure thresholds.
-import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, wantsHelp } from "./lib/cli.mjs";
-
-const HELP = `Usage: node scripts/show-my-map.mjs [--team <key>] [--json]
-
-Prints the tenant contract's stage map, ladder and thresholds. Nothing here is guessed: every value is
-read from the contract Catalyst Cloud serves for your tenant. Wraps: catalyst-skills contract --path.
-
-  --team <key>   only this team
-  --json         one JSON document: { slots, teams, ladder, thresholds }
-  --help         this text
-
-A slot marked * is load-bearing: dispatch, intake, pr, done and canceled must be mapped for the
-ladder to move at all; the others are informational. "(unmapped)" means the team has no stage for
-that slot; "(state gone)" means the mapped Linear state no longer exists and needs re-mapping in
-settings.
-
-Exit 0, 1 on a usage error or an unknown team, 2 when this machine is not connected to a tenant or
-the contract could not be read (the line says which).`;
-
-const LOAD_BEARING = new Set(["dispatch", "intake", "pr", "done", "canceled"]);
-
-const argv = process.argv.slice(2);
-if (wantsHelp(argv)) {
-  console.log(HELP);
-  process.exit(0);
-}
-const { flags } = parseFlags(argv, { bool: ["json"], value: ["team"] });
-
-function contractPath(path) {
-  const r = runCli(["contract", "--path", path, "--json"]);
-  exitOnFailure(r);
-  const v = parseJson(r.stdout);
-  if (v === null || v === undefined) {
-    relayStderr(r);
-    console.error(`contract --path ${path} returned nothing readable`);
-    process.exit(1);
-  }
-  return { value: v, stderr: r.stderr };
-}
-
-const slotsRead = contractPath("slots");
-if (slotsRead.stderr.trim()) console.error(slotsRead.stderr.trimEnd());
-const slots = slotsRead.value;
-let teams = contractPath("teams").value;
-const ladder = contractPath("ladder").value;
-const thresholds = contractPath("thresholds").value;
-
-if (flags.team) {
-  const want = flags.team.toUpperCase();
-  teams = teams.filter((t) => String(t.key ?? "").toUpperCase() === want);
-  if (teams.length === 0) {
-    console.error(`no team with key ${flags.team} on this tenant's contract`);
-    process.exit(1);
-  }
-}
-
-if (flags.json) {
-  console.log(JSON.stringify({ slots, teams, ladder, thresholds }));
-  process.exit(0);
-}
-
-const pad = (s, n) => String(s).padEnd(n);
-for (const team of teams) {
-  console.log(`== team ${team.key ?? "(no key)"} — ${team.name ?? team.id} — workflow ${team.workflowMode}, git automation ${team.gitAutomation}, readiness ${team.readiness?.status ?? "unknown"}`);
-  console.log(`   ${pad("slot", 12)}${pad("stage", 22)}${pad("type", 12)}${pad("exists", 8)}source`);
-  for (const slot of slots) {
-    const s = team.stages?.[slot];
-    const mark = LOAD_BEARING.has(slot) ? "*" : " ";
-    if (!s) {
-      console.log(`  ${mark}${pad(slot, 12)}(unmapped)`);
-      continue;
-    }
-    const name = s.stateStillExists ? (s.name ?? "(unnamed)") : "(state gone)";
-    console.log(`  ${mark}${pad(slot, 12)}${pad(name, 22)}${pad(s.type ?? "-", 12)}${pad(s.stateStillExists ? "yes" : "NO", 8)}${s.source}`);
-  }
-  const labels = team.labels ?? {};
-  const describe = (list) => (list ?? []).map((l) => `${l.name}${l.preferredId ? "" : " (absent)"}`).join(", ") || "none";
-  console.log(`   labels: ask ${describe(labels.ask)}; hold ${describe(labels.hold)}; release ${describe(labels.release)}`);
-}
-
-console.log("== ladder");
-console.log(`   phases: ${(ladder.phases ?? []).join(" → ")}`);
-console.log(`   keying: ${ladder.keying} (${ladder.keyingScope}); intake ${ladder.intakeEnabled ? "enabled" : "off"}`);
-
-console.log("== thresholds (live, fleet-wide)");
-const minutes = (ms) => `${Math.round(ms / 60000)} min`;
-console.log(`   park after ${thresholds.parkAfterConsecutiveFailures} consecutive failures`);
-console.log(`   remediate round cap ${thresholds.remediateRoundCap} (escalated budget ${thresholds.remediateEscalatedRoundBudget}, rewind budget ${thresholds.remediateRewindBudget})`);
-console.log(`   retry backoff ${(thresholds.retryBackoffMs ?? []).map(minutes).join(", ")}`);
-console.log(`   write budget ${thresholds.hostDailyWriteBudget} per host per day`);

package/skills/how-catalyst-works/scripts/whats-running.mjs

@@ -1,65 +0,0 @@
-#!/usr/bin/env node
-// whats-running.mjs — what Catalyst is executing right now (fleet activity, the agent roster, lease
-// attributions), optionally the dispatch queue and the coding-account line.
-import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, wantsHelp } from "./lib/cli.mjs";
-
-const HELP = `Usage: node scripts/whats-running.mjs [--queue] [--accounts] [--team <key>] [--json]
-
-Prints what is executing on your tenant. Wraps: catalyst-skills running, queue, accounts.
-
-  --queue        also print the dispatch queue (what runs next, in order)
-  --team <key>   with --queue: one team's queue
-  --accounts     also print the coding-account line (provider, state, windows — never a credential)
-  --json         one JSON document: { running, queue?, accounts? }
-  --help         this text
-
-Exit 0, 1 on a usage error, 2 when this machine is not connected to a tenant or the cloud refused
-a read (the line says which).`;
-
-const argv = process.argv.slice(2);
-if (wantsHelp(argv)) {
-  console.log(HELP);
-  process.exit(0);
-}
-const { flags } = parseFlags(argv, { bool: ["queue", "accounts", "json"], value: ["team"] });
-
-const out = {};
-const running = runCli(["running", "--json"]);
-exitOnFailure(running);
-relayStderr(running);
-out.running = parseJson(running.stdout) ?? running.stdout.trimEnd();
-
-if (flags.queue) {
-  const args = ["queue", "--json"];
-  if (flags.team) args.push("--team", flags.team);
-  const queue = runCli(args);
-  exitOnFailure(queue);
-  relayStderr(queue);
-  out.queue = parseJson(queue.stdout) ?? queue.stdout.trimEnd();
-}
-
-if (flags.accounts) {
-  const accounts = runCli(["accounts"]);
-  exitOnFailure(accounts);
-  relayStderr(accounts);
-  out.accounts = accounts.stdout.trimEnd();
-}
-
-if (flags.json) {
-  console.log(JSON.stringify(out));
-  process.exit(0);
-}
-
-const section = (title, value) => {
-  console.log(`== ${title}`);
-  console.log(typeof value === "string" ? value : JSON.stringify(value, null, 2));
-};
-if (out.running && typeof out.running === "object") {
-  section("fleet activity", out.running.fleetActivity ?? out.running);
-  if (out.running.agentRoster !== undefined) section("agent roster", out.running.agentRoster);
-  if (out.running.leaseAttributions !== undefined) section("lease attributions", out.running.leaseAttributions);
-} else {
-  section("running", out.running);
-}
-if (out.queue !== undefined) section("dispatch queue", out.queue);
-if (out.accounts !== undefined) section("coding accounts", out.accounts);

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

@@ -1,45 +0,0 @@
----
-name: run-this-project
-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 tenant stream for the scope through the catalyst-skills 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.
-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 -->
-
-# Run this project
-
-You are the steward: the single-threaded owner of ONE project or ticket set, from now until it closes. The person says "run this project for me" and hands you a scope. Catalyst does the phases; you make work ready and visible, react to what happens, unblock, and keep one status summary the person can read. You hold no authority over other stewards and you are not the desk; `whats-happening` is the desk.
-
-## Run first
-
-Scripts are run, never read. Each prints its own `--help`.
-
-1. `node scripts/scope-status.mjs --project <id>` (or `--team <key>`): tickets by stage in the contract's order, what is running and queued in scope, and stalls against the local policy. Run it once to take the scope, and again after any resync.
-2. `node scripts/watch-scope.mjs --project <id>`: the subscription. In Claude Code, arm a monitor on it and react to each printed line in the same turn. In a harness with no monitor, add `--exec <command>` so a reaction still runs per frame.
-3. `node scripts/make-ready.mjs <ticket>` to dispatch; `--park` to stop; `--note <why>` to record it.
-4. `catalyst-skills explain <ticket>` whenever a ticket is not moving: one paragraph naming the reason and what releases it.
-
-Every script exits 2 when this machine is not connected (run `catalyst-skills login`), 1 when its own check fails.
-
-## Load on demand
-
-| when | read |
-| -- | -- |
-| arming the watch, deciding what a frame means, a reaction failed, a resync line printed | `references/reacting-to-events.md` |
-| dispatching or parking a ticket, judging whether a phase actually ran, writing a ticket for Catalyst | `references/making-work-ready.md` |
-| something is not moving, tuning the stall policy, deciding whether a human needs to hear about it | `references/stalls-and-escalation.md` |
-| the exclusion vocabulary in depth, the ladder, this team's stage map | the `how-catalyst-works` skill |
-| raising or settling a decision | the `what-needs-me` skill |
-| a PR's checks, review and merge legs | the `catalyst-github` skill |
-
-## Rules
-
-- **React, never poll.** A loop that re-reads the API or the replica is a defect. The stream and the cursor file are the mechanism; a reaction that throws leaves the cursor so the frame is offered again.
-- **Dispatch is a card move.** The cloud takes work from the dispatch column and writes every later stage itself. Your two moves are into dispatch and into the backlog; never hand-move a card into a ladder stage.
-- **Evidence a phase ran is the outcome comment, the attached document and the agent session,** not the clock and not the card's column.
-- **Tenant facts come from the contract, live.** Never restate a stage name, label id, team id, threshold or template in prose; run `catalyst-skills contract --path <a.b.c>` when you need one.
-- **Escalate inward.** Instrument, then you, then the desk, then the human as an ask filed through `what-needs-me` with what it blocks. Decide the technical calls yourself; take the sane default and record it; a fleet or provider condition is one note, never one ask per ticket.
-- **Reply where the message arrived,** in-thread, tagged, as the app actor. Never post as the human, never answer someone else's ask. Bookkeeping records take the contract's marker (`catalyst-skills write comment --bookkeeping`).
-- **One status summary,** kept current after every reaction: in flight, blocked and on whom, closed, next, each line with a ticket id. Where a human decision is pending, the line carries the ask's id.
-- **Say what a key cannot see.** PR labels and reactions are not mirrored; the CLI says so by name and points at settings. A park or hold is released from the person's own login once its cause is fixed, through the `unstick` skill (`catalyst-skills release`). Execution history (`explain --history`) and coding-account status (`accounts`) ARE readable — read them rather than reconstructing them from comments.

package/skills/run-this-project/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Run this project"
-  short_description: "Own one Catalyst project end to end: react to its events, make tickets ready, chase stalls, escalate inward"
-  default_prompt: "Use $run-this-project to run project <id> for me until it closes."
-policy:
-  allow_implicit_invocation: false

package/skills/run-this-project/agents/portability.yaml

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

package/skills/run-this-project/assets/stall-policy.json

@@ -1,15 +0,0 @@
-{
-  "$comment": "Stall thresholds in minutes, per workflow slot, for scope-status.mjs. This is local policy a human sets once, not a cloud value: copy this file to ~/.config/catalyst-cloud/stall-policy.json and edit it there. A ticket counts as stalled when it has sat in a slot longer than the threshold with no update and nothing running or leased on it. 'dispatch' is how long a card may wait in the dispatch column before you ask why nothing picked it up; 'pr' is how long a card may wait for merge evidence; 'default' covers any slot not named.",
-  "minutes": {
-    "dispatch": 60,
-    "intake": 60,
-    "research": 90,
-    "plan": 90,
-    "implement": 120,
-    "remediate": 120,
-    "verify": 90,
-    "review": 90,
-    "pr": 240,
-    "default": 120
-  }
-}

package/skills/run-this-project/references/making-work-ready.md

@@ -1,60 +0,0 @@
-# Making work ready
-
-This reference restates invariants of how Catalyst takes work. The tenant's own values (which Linear state is the dispatch column, which state is the backlog, the ask and release label ids, the round cap and the park threshold) are read live from `catalyst-skills contract`; the scripts here never name a stage.
-
-## The steward's two moves
-
-Catalyst does not take work by being asked. It takes work by finding a card in the team's dispatch column and offering that card's next phase to a runner. So the steward's dispatch verb is a card move, and its stop verb is a card move:
-
-```sh
-node scripts/make-ready.mjs ENG-41            # move into the dispatch column; the cloud offers the next phase
-node scripts/make-ready.mjs ENG-41 --park     # move into the team's backlog-type state; nothing further is offered
-node scripts/make-ready.mjs ENG-41 --park --note "waiting on the vendor's API change"
-```
-
-Dispatch resolves the dispatch slot on the ticket's team from the contract. Parking resolves the team's first backlog-type state from its live workflow states, because the backlog is deliberately not one of the eleven slots. Those are the only two state moves you make. Every other stage move on a ticket in the ladder is the cloud's, written when a phase completes; moving a card forward by hand does not run a phase, it only confuses the advance table, and moving it backwards by hand does not undo one.
-
-## What a dispatchable ticket carries
-
-Before the move, the ticket needs, in the record itself:
-
-- A title that states the outcome. A phase agent reads the ticket, not your chat.
-- A description that says what done looks like: the behaviour, the constraints, the files or surfaces if you know them, acceptance criteria a validate phase can check.
-- The right team. The team key is the ticket prefix, and the team's stage map and labels are what the cloud will use.
-- A priority. Queue order inside a team is priority first, then creation time, then identifier, so an unset priority sorts last.
-- No live blocking relation. A ticket with an open blocker is excluded as `blocked` until the blocker closes.
-- No ask on it. A ticket that carries the ask label, or whose own text reads as a decision request (an ask-shaped title, lettered options, a "default if silent" line), is excluded as a question rather than work. If a real ticket trips the shape detector, a human applies the release label named in the contract's vocabulary; you can also rewrite the text so it reads as work.
-- Declared scope when the team enforces it: a ticket whose declared files overlap a ticket already in flight is held as `scope_overlap` for the implement phase.
-
-A ticket does not need a branch, a PR, or any artifact to be dispatched: the ladder creates those. A ticket that has never entered the ladder starts at intake when the tenant enables it, otherwise at research.
-
-## After the move
-
-`make-ready.mjs` asks the eligibility explainer as soon as the move lands and prints the verdict. Read it as follows:
-
-- `offered` or `eligible` with a queue position: done; a runner will pick it up in the next dispatch pass, ordered by priority, then age, then identifier, with tickets already mid-ladder ahead of fresh ones.
-- An ordering that is stale or never published: the cloud re-derives the team's queue within a pass of the move; ask again in a minute with `catalyst-skills explain <ticket>`.
-- Any other exclusion reason: the paragraph names it and what releases it. The reasons and what unblocks each are in `how-catalyst-works` and in `whats-happening`'s "why is it stuck" reference.
-
-## Evidence a phase ran
-
-Do not infer progress from time passing. A phase leaves three kinds of evidence on the ticket, and a card move alone is not one of them:
-
-1. **The outcome comment.** The cloud posts a card per phase: a completed phase names the phase, the attempt, and its artifact; a failed phase names the phase, the attempt, and the failure class, and may carry a park or hold block. A remediate round posts its own attempt card with the round number and the class it is repairing. These arrive as comment frames on the watch.
-2. **The attachment and document.** Each artifact-bearing phase (research, plan, implement, validate, pr, remediate) is projected to a Linear document titled with the ticket, the phase, the attempt and the date, attached to the ticket, with a short link comment. Research and plan on a ticket with a project also appear as a project link.
-3. **The agent session.** The ticket's agent session carries the ladder as its plan, with the phases before the current one completed, the current one in progress, and the rest pending; its activities are the phase start, the gate, artifacts written, the PR opened, and the report.
-
-The card's stage is the fourth, weakest signal: a completed phase moves the card to the stage the advance table names, a failed phase writes no stage at all, and Done is written only when the pull request actually merges, by the merge webhook, never by a phase. A card sitting in a stage tells you which phase last finished, not whether the next one is running; `scripts/scope-status.mjs` shows running and leased phases beside the stage for exactly that reason.
-
-## Parking, and what it does not do
-
-Parking is the lever that stops the cloud offering more rounds on a ticket: moved out of the dispatch column and the ladder's stages, the ticket is excluded at the next offer. It does not kill a phase that is already running under a lease; that container finishes its phase, posts its outcome, and the next offer finds the card parked. If you park a ticket the cloud has itself parked (three consecutive failures, or the remediate round cap), record why in a bookkeeping note. Releasing a cloud park is not a card move: once its cause is fixed, the `unstick` skill releases it with `catalyst-skills release <ticket>`, and only a refusal that names a person's action becomes an ask.
-
-Un-parking is the same dispatch move again. The counted attempts and rounds do not reset when a card comes back; the contract's thresholds say how many remain.
-
-## What you never do to make work ready
-
-- Never move a card into a research, plan, implement, validate, PR, done or canceled stage by hand to "skip ahead". The cloud reads those stages as the record of what ran.
-- Never remove an ask label or apply the release label yourself; a human decides whether a ticket is a question.
-- Never dispatch two tickets that touch the same files at once; serialise them or let the second one wait as `scope_overlap`.
-- Never dispatch a ticket you have not read in full.

package/skills/run-this-project/references/reacting-to-events.md

@@ -1,76 +0,0 @@
-# Reacting to events
-
-This reference restates invariants of the Catalyst Cloud stream and the `watch` verb. Nothing here varies per tenant; the tenant facts a reaction needs (stage ids, label ids, the ask team) come from `catalyst-skills contract` at the moment you need them.
-
-## The mechanism
-
-A steward never polls. It subscribes once to the tenant stream through the SDK's live client and reacts to each change as it arrives. The verb is `catalyst-skills watch`, and this skill's `scripts/watch-scope.mjs` is that verb with the scope checked up front:
-
-```sh
-node scripts/watch-scope.mjs --project <id>          # every ticket in the project
-node scripts/watch-scope.mjs --team <key>            # every ticket on the team
-node scripts/watch-scope.mjs --ticket ENG-41 --ticket ENG-42
-```
-
-The stream itself is tenant-wide; scope is filtered on this machine from each frame's entity and row, and a row that only carries a ticket reference (a comment, a session, a pull request) is resolved to its project through the ticket's own record, cached for the life of the watch. The cost of an ignored frame is one JSON parse, so a wide scope is fine.
-
-**In Claude Code**, arm a monitor on the command above. Each line it prints is one applied change inside the scope, delivered into your session as an event. React to it in the same turn: read what changed, decide, act, and only then let the turn end.
-
-**In Codex, OpenCode, or any harness without a monitor**, pass `--exec`:
-
-```sh
-node scripts/watch-scope.mjs --project <id> --exec 'node my-reaction.mjs'
-```
-
-The command runs once per frame with the frame on stdin. A non-zero exit is a failed reaction (see the cursor rule). Nothing polls in either shape.
-
-## The frame
-
-One JSON object per line, exactly what the SDK delivers:
-
-```json
-{"type":"change","accountId":"<tenant>","seq":4182,"entity":"comments","entityId":"<id>","op":"upsert","row":{...}}
-```
-
-`seq` is the tenant-wide position. `entity` is one of the mirror's feed tables. `op` is `upsert` or `delete`. `row` is the mirrored row when the op is an upsert; a delete carries the id only. A frame for another tenant is refused by the CLI and never printed.
-
-## Entities that matter to a scope
-
-| entity | what a change means | first reaction |
-| -- | -- | -- |
-| `issues` | a card moved, was retitled, re-prioritised, assigned, or created | if it moved into a stage the cloud owns, note the advance; if it moved out of the ladder by hand, ask why before touching it |
-| `comments` | someone or something wrote on a ticket | a human comment in your scope is answered in-thread by you, tagged; a cloud outcome card (phase complete, phase failed, remediate attempt, board health, merge wait) is your execution signal, read it |
-| `issue_labels`, `labels` | a label was added or removed | an ask label means a question, not work; a hold label means the cloud wants a human; the release label means a human cleared a false positive |
-| `relations` | a blocks relation appeared or went away | a new blocker on your ticket is a dependency to chase; a blocker closing may make a card dispatchable again |
-| `pull_requests`, `pr_events`, `pushes` | the branch and PR state changed | a PR going ready-for-review or merged is a milestone; a force-push after a resolved review thread is worth a look |
-| `check_runs`, `check_suites`, `commit_statuses` | CI moved | red on a required check after the queue label wakes an automatic remediation; you watch, you do not re-run it |
-| `reviews`, `pr_review_threads`, `pr_review_comments` | the reviewer spoke | unresolved threads block the merge; a clean pass is a reaction or a terse comment, not a review object |
-| `agent_sessions`, `agent_activities` | a phase started, wrote an artifact, opened a PR, reported | the plan on the session is the ladder itself; the current phase is the one in progress |
-| `fleet_activity`, `fleet_host_liveness` | a runner picked up or dropped a phase | a phase running is not a stall, whatever the clock says |
-| `fleet_anomalies` | the cloud raised a fleet-level alert | one alert covers every ticket it touches; never escalate it per ticket |
-| `workflow_states`, `team_workflow_mapping` | the tenant's stage map changed | refresh the contract (`catalyst-skills contract --refresh`) before the next state move |
-| `projects`, `cycles`, `initiatives` | your scope's container changed | update the status summary |
-
-Entities not listed still arrive when they are in scope; ignore what you do not need.
-
-## The same-turn rule
-
-A frame is reacted to in the turn it arrives, not batched for a later pass. The reaction is whatever the table above says plus anything the situation obviously needs, and it ends with the one status summary for the scope being current. If a reaction needs a human decision, file the ask through `what-needs-me` before proceeding on the default, in that same turn.
-
-## The cursor rule
-
-The cursor file (`~/.config/catalyst-cloud/watch-cursor.json`, stamped with the tenant) advances only after the reaction returns. A reaction that throws, or an `--exec` command that exits non-zero, leaves the cursor at the last good frame; the CLI closes the socket and the SDK's reconnect replays from that cursor, so the failed frame is offered again. Delivery is therefore at-least-once: make reactions safe to repeat (check before you write, prefer idempotent writes such as a label add over a fresh comment).
-
-Two consequences. First, a crash mid-reaction replays, never loses. Second, a reaction that keeps failing keeps the watch pinned on one frame; fix the reaction rather than skipping the frame, or restart with `--from head` and re-read the scope with `scripts/scope-status.mjs` to catch up on what you missed.
-
-## What to do on resync
-
-When the tenant tells the stream it can no longer replay from your cursor, the CLI prints one line on standard error, `[watch] resync: cursor moved to head <n>`, and continues from the head. No rows are copied. Anything that happened between your old cursor and the head is not replayed, so a resync is your cue to run `scripts/scope-status.mjs` once and reconcile the summary against the live state.
-
-## Starting a watch on an existing project
-
-Start with `--from head` when you are picking up a project that has been running without a steward; the backlog of old frames is not worth replaying, and `scope-status.mjs` gives you the present state in one call. Start from the saved cursor (the default) when you are resuming your own watch after a break, so nothing that happened in between is lost.
-
-## The honest limit
-
-The stream carries the mirror's entity changes. It does not carry the relay ledger's phase failures, parks, remediate rounds or backoff timers as first-class frames. Between frames you learn those from the outcome comments the cloud posts on the ticket, which do arrive as `comments` frames: a phase-failed card names the phase, the attempt and the failure class; a remediate-attempt card names the round; a board-health comment names a stall the cloud itself noticed. For the current verdict on any ticket, ask the explainer: `catalyst-skills explain <ticket>` turns the exclusion reason and the last failure into one paragraph. `catalyst-skills explain --history <ticket>` prints the per-phase attempt ledger, the remediation rounds against the cap, and any park with what releases it.

package/skills/run-this-project/references/stalls-and-escalation.md

@@ -1,63 +0,0 @@
-# Stalls and escalation
-
-The stall thresholds here are **local policy**, set once by the human who owns the tenant and read by `scripts/scope-status.mjs`. They are not cloud values and the cloud does not enforce them; the cloud's own enforcement numbers (retry backoff, the park threshold, the remediate round cap, the write budget) are on the contract and printed by `how-catalyst-works`. The chase order and the escalation rule below are invariants.
-
-## The policy file
-
-`assets/stall-policy.json` ships the defaults: minutes a ticket may sit in each slot with no update and nothing running or leased on it before it counts as stalled. To change them, copy that file to `~/.config/catalyst-cloud/stall-policy.json` and edit it there; the script prefers the local copy and prints which file it used. Pass `--stall-policy <file>` to use another.
-
-Two slots deserve thought when tuning. The dispatch slot's threshold is how long a card may wait to be picked up before you ask why nothing took it; on a busy tenant with a full queue that is capacity, not a stall, and the answer is to wait or re-prioritise. The PR slot's threshold is how long a card may wait for merge evidence; reviews and CI take real time, so set it generously.
-
-## What counts as stuck
-
-A ticket is stuck when all of these hold at once: it is in an active slot (not done, not canceled), nothing is running or leased on it, its last update is older than the slot's threshold, and the eligibility explainer does not name a reason that is simply waiting out a clock. `scope-status.mjs` checks the first three and hands you the fourth as a command to run.
-
-A running phase is never a stall, however long it has run; the cloud's own timeout will fail it and the outcome card will say so. A ticket in retry backoff is waiting out a rung of two, five or fifteen minutes and is not a stall either.
-
-## The chase order
-
-Run `catalyst-skills explain <ticket>` first, and let its reason pick the row:
-
-| the explainer says | what it means | your move |
-| -- | -- | -- |
-| offered, with a position | the queue has it; a runner is the bottleneck | wait; if every ticket waits, it is capacity, see below |
-| lease held, intake lease held | a container has it | not a stall; wait for the outcome card |
-| retry backoff | a pre-branch or infrastructure failure is retrying in place | wait out the rung; three in a row parks it, and then it is a real stall |
-| blocked | a live blocks relation | chase the blocker: is it dispatchable, is it an ask nobody answered, is it done but still open |
-| ask ticket, ask shape suspected | the ticket is a question | route it to `what-needs-me`; if it is really work, a human applies the release label |
-| not at dispatch stage | somebody moved the card, or it never entered | read the card's history; re-dispatch with `make-ready.mjs` if it should run |
-| phase parked, cooling down, remediate parked | the cloud parked it after repeated failure or the round cap | read the last outcome card for the class; once its cause is fixed, the `unstick` skill releases it (`catalyst-skills release <ticket> --because <what changed>`); if the fix is a decision, file an ask |
-| no change hold | a remediate round changed nothing | a human comment on the ticket, or a new push to the branch, releases it; say what should change |
-| validate class spent, stale failure episode | the repair budget for this failure is used, or the ladder moved on | read the outcome cards; usually a decision about the approach, so an ask |
-| waiting on | a merge-gate failure with no automatic repair | read the merge-wait comment and the PR's three legs through `catalyst-github` |
-| branch missing, branch gone, no branch to remediate | the branch the phase needs does not exist | a hand-deleted branch is a human question; a never-created one means implement has not run, so check the earlier phases |
-| environment check required, running, failed, expired, hash mismatch | the repository's environment gate | a repository setting; the tenant admin resolves it in settings, one ask for the repository, not per ticket |
-| scope overlap | another in-flight ticket owns the files | wait for it, or re-order by priority |
-| routing unavailable, no eligible slot, runner image breaker, repo paused | a fleet or provider condition | one fleet note, never per ticket; see below |
-| pr merged, pipeline complete, ticket terminal | it is finished | close the loop in the summary; if the card is not Done a minute after the merge, that is a finding, not a chore |
-
-Where the explainer names a reason not in this table, it prints the raw reason; read it as spelled and consult `how-catalyst-works`.
-
-## Capacity and fleet conditions are one note, not many asks
-
-When several tickets in scope are offered and nothing picks them up, or the explainer names a routing, slot, provider or image condition, the cause is shared: coding-account headroom, a provider outage, a paused repository, a poisoned runner image. Write one line in the status summary naming the condition and the tickets it holds. Do not file an ask per ticket. `catalyst-skills accounts` reads coding-account status (state, usage windows, walls, quarantine); enrolling, pausing or removing an account is the settings page, not you.
-
-## Escalate inward, never outward
-
-The order is instrument, then you (the steward), then the desk (`whats-happening`), then the human, and the human only ever sees an ask. An instrument or a script that pages a human directly is a defect. So is a stall report that reaches the human as a bare label, a board row, or a chat aside with no ask behind it.
-
-Before anything reaches the human, answer three questions:
-
-1. **Can I decide this myself?** Which approach, retry or abandon, rebase or re-cut, re-order two tickets: yours. Decide, record the decision in a bookkeeping note on the ticket, and move on.
-2. **Does this need to block at all?** If a sane default exists, take it, record it, and file the ask anyway so the human can overrule; the work does not wait.
-3. **Who else can move this?** Another steward, the desk, a repository owner. Pulling in a peer is preferred over pulling in the human.
-
-Only a genuine product, priority or approval decision, or an action only a human can physically take (close a person's own pull request, read a review that will not converge, resolve a repository setting, apply the release label, answer a merge policy question), survives to become an ask.
-
-## When a stall becomes an ask
-
-File it through `what-needs-me`, never by hand and never as the human. The ask carries the question as its title, the options, the default that fires if silent, and what it blocks, with the stalled ticket named in the blocks list so the human's inbox ranks it by what it holds. Search for an existing ask about the same decision first and attach the new ticket to it rather than filing a second one; two asks for one decision split its urgency and sink both. Once filed, proceed on the default and say so in the ticket.
-
-## Reply where the message arrived
-
-A human comment inside your scope is answered by you, in that thread, tagged, as the app actor. A question only a human can decide becomes an ask; you do not answer it, and you never post as the human. A bookkeeping record (a state move, a decision you took, a chain summary) carries the contract's bookkeeping marker as a prefix so it wakes nothing; the `--bookkeeping` flag on `catalyst-skills write comment` adds it.

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

@@ -1,185 +0,0 @@
-#!/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 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";
-import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
-
-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 (!hasCredential(parsed) || 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: ${CONNECT_COMMAND}`);
-  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);
-}