@catalyst-cloud/cli 0.13.1 → 0.14.0

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

@@ -1,56 +1,46 @@
-# Why is it stuck: every reason, and who acts
-
-The pack's one reason table; other skills point here. Match the reason `node scripts/explain.mjs <ticket>` prints to a row. "No one acts" is an honest answer. A reason missing here is printed as the cloud spelled it: report it verbatim and say the bundle does not know it. The mechanism is in `references/when-a-phase-fails.md`.
-
-## Reasons that release themselves
-
-`retry_backoff` (a retry rung, `thresholds.retryBackoffMs`), `lease_held`, `intake_lease_held` and `later_phase_lease_held` (a live container holds this or a later phase), `environment_check_running`, `claim_storm` (claimed too often in the last hour), `repo_at_capacity` (every runner seat busy), `stale_failure_episode` (the round would repair a phase already passed, so it is dropped), and `no_branch_to_remediate` / `branch_missing` (the cloud's budgeted release): each clears on its own, and no one acts.
-
-| reason | what it means, and what clears it | who acts |
-| -- | -- | -- |
-| `runner_image_breaker` | fleet-wide: the live runner image fails every phase at startup; the image pin moves; one alert per account | an operator |
-| `routing_unavailable` | refused at kickoff: no route, no eligible slot, or the provider down (the detail says which); clears on recovery | usually no one acts; if it persists, a workspace owner or admin, in settings, checks coding accounts (`references/coding-accounts.md`) |
-| `cooling_down` (with a named callback) | parked on a condition the cloud watches; the callback in `detail` fires | no one acts; if the callback stalls, the person, with their own login, releases it through `unstick` |
-| `wip_limit` | the project is at its work-in-progress limit, so no first phase; a ticket in progress finishing clears it | no one acts on this ticket; the in-progress tickets it waits on each have their own row |
-
-## 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 person, with their own login, answers the ask (`what-needs-me`) |
-| `ask_shape_suspected` | its text reads as a decision request with no ask label | the person, with their own login, answers it as an ask or applies the contract's release label |
-| `blocked` | a live blocking relation holds it | the blocker's owner closes it; for an ask, the person, with their own login |
-| `not_at_dispatch_stage` | the card is not in the dispatch column | the person, with their own login, moves it to the dispatch slot |
-| `not_at_pr_stage` | merge is next but the card is off the PR column | the person, with their own login, returns it to the pr slot and finds the automation that bounced it |
-| `no_change_hold` | a repair round changed nothing | the person, with their own login, comments or pushes; `unstick` can also release it |
-| `waiting_on` | a merge-gate failure the cloud cannot repair holds it at PR | the person, with their own login, reads the merge-wait comment: usually a hold label or an owed review (`catalyst-github`) |
-| `externally_claimed` | a worker outside the cloud holds it | that worker, or the person, with their own login, removes the local-lane label |
-| `environment_check_required` / `environment_check_failed` / `environment_check_expired` / `environment_check_hash_mismatch` | the repository's environment check has not run, failed, aged out, or predates a change | a workspace owner or admin, in settings, runs, fixes or reruns it |
-| `repo_paused` | an operator paused the repository | an operator resumes it |
-| `scope_overlap` | its declared file scope meets a ticket in flight | the person, with their own login, picks which goes first, or waits |
-| `human_owned_pr` | a person's own pull request holds the ticket | the person, with their own login, closes, merges or hands over that pull request, which only they may close. The release command refuses it |
-| `review_not_converging` | validate and repair cycles are not converging (review convergence hold) | the person, with their own login, reads the findings (`catalyst-github`) and comments. The release command refuses it; the hold table in `references/when-a-phase-fails.md` says what clears it |
-| `round_threshold` | the lifetime repair budget is spent (round-threshold hold) | the person, with their own login, answers the ask the cloud raised or pushes a fix; point at that ask rather than raising another. The release command refuses it; see the hold table |
+# Eligibility reasons
+
+Use explain.mjs; unknown reasons stay verbatim. Holds: when-a-phase-fails.md.
+
+## Automatic release
+
+Automatic waits, where no one acts: `retry_backoff`, `lease_held`, `intake_lease_held`, `later_phase_lease_held`, `environment_check_running`, `claim_storm`, `repo_at_capacity`, `stale_failure_episode`, `no_branch_to_remediate` or `branch_missing`. These cover backoff, leases, environment checks, hourly claim throttling, occupied seats, obsolete repair and budgeted missing-branch release.
+
+| reason | release and actor |
+| -- | -- |
+| `runner_image_breaker` | an operator moves faulty startup image pin; one fleet alert |
+| `routing_unavailable` | kickoff route/slot/provider failure; recovery clears it; persistence needs a workspace owner or admin, in settings |
+| `cooling_down` with callback | cloud watches detail's condition; no one acts unless stalled, then own-login release through unstick |
+| `wip_limit` | no one acts on this ticket; project at limit; started work must finish; inspect those tickets' own reasons |
+
+## Human action
+
+| reason | meaning and action |
+| -- | -- |
+| `ask_ticket` | the person, with their own login: labelled question, never work; answer through what-needs-me |
+| `ask_shape_suspected` | the person, with their own login: unlabelled decision text; answer or apply contract release label |
+| `blocked` | blocker owner closes it; for an ask, the person, with their own login, answers |
+| `not_at_dispatch_stage` / `not_at_pr_stage` | the person, with their own login: restore dispatch/PR slot respectively; for PR, fix bouncing automation |
+| `no_change_hold` | the person, with their own login: unchanged repair; comment/push/unstick |
+| `waiting_on` | the person, with their own login: unrepairable PR merge gate; read merge-wait comment for hold/review owed, using catalyst-github |
+| `externally_claimed` | the person, with their own login: outside worker owns it; worker/person removes local-lane label |
+| `environment_check_required` / `environment_check_failed` / `environment_check_expired` / `environment_check_hash_mismatch` | absent/failed/aged/changed environment check; a workspace owner or admin, in settings, runs or fixes it |
+| `repo_paused` | an operator resumes repository |
+| `scope_overlap` | the person, with their own login: declared files overlap running work; choose order or wait |
+| `human_owned_pr` | the person, with their own login: only its human owner closes, merges or hands it over; release refused |
+| `review_not_converging` | the person, with their own login: read findings through catalyst-github, comment; release refused |
+| `round_threshold` | the person, with their own login: lifetime repair budget spent; answer existing ask or push fix, never duplicate ask; release refused |
 
 ## Reasons a release clears once the cause is fixed
 
-The desk does not release. Route these to the `unstick` skill, which reads the history, previews `catalyst release <ticket>`, and runs it or names what a person must do first.
+After a fix, the person, with their own login, routes `phase_parked`, `cooling_down` from failures/round cap, `remediate_parked`, `validate_class_spent` and `branch_gone` to `unstick`. Read history, preview release; recreate deleted branches or drop tickets. Validate-budget also clears by push/comment/ask answer.
 
-| reason | what it means | note | who acts |
-| -- | -- | -- | -- |
-| `phase_parked` / `cooling_down` (repeated failures, or the round cap spent) | the phase is parked | `explain --history` names the park | the person, with their own login |
-| `remediate_parked` | the repair phase itself is parked | as above | the person, with their own login |
-| `validate_class_spent` | the validate-budget hold | a push, comment or ask answer also clears it (the hold table) | the person, with their own login |
-| `branch_gone` | a branch that existed was deleted | recreate it, or drop the ticket | the person, with their own login |
+## Finished
 
-## Reasons that are not problems
+Finished, so no one acts: `ticket_terminal`, `pipeline_complete` and `pr_merged`; report them as closed.
 
-`ticket_terminal`, `pipeline_complete` and `pr_merged` describe finished work; no one acts. Report them as closed.
+## Inconclusive
 
-## When the cloud could not judge
+unknown with `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 unreadable, never absent. Usually recovered next pass. `workflow_mapping_unknown` does not clear without a saved mapping; nor does accompanying `ordering_never_published`. Remap with `catalyst team map <KEY>` as owner/admin; other persistent unknowns need catalyst-onboard.
 
-A status of `unknown` with `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 "I could not look", never "it is not there": report it as inconclusive; most clear on the next pass. `workflow_mapping_unknown` (and `ordering_never_published` with it) does not clear by itself when the team has no saved mapping: a workspace owner or admin maps it (`catalyst team map <KEY>`). If another persists, read readiness (`catalyst-onboard`).
-
-## The one advisory
-
-`human_addressed_unlabeled_ask_suspect` gates nothing: a human-assigned ticket may be an unlabelled ask. List it under waiting-on-human with a question mark.
+`human_addressed_unlabeled_ask_suspect` is advisory: list the human-assigned possible ask under waiting-on-human with a question mark.

package/dist/env/declaration-rules.js

@@ -1,163 +0,0 @@
-// declaration-rules.ts — a vendored, dated copy of catalyst-cloud's rules for a repo-scope
-// `catalyst.env.json`, applied by `validateRepoEnvironmentDeclaration`
-// (packages/environment/src/contract.ts:416-493 on catalyst-cloud `main`; the ticket cites line 488,
-// which falls inside that range). That file lives in the PRIVATE `coalesce-labs/catalyst-cloud`
-// monorepo — no sibling checkout, no npm publication (its one customer, `apps/cli`, is itself
-// "private": true) and no network reachability from this session. Everything below is vendored
-// secondhand from two independent, dated thoughts-pool research passes (2026-09-10 and 2026-09-17)
-// that agreed with each other, following the same idiom this repository's own
-// `test/skills-content.test.ts` already uses to vendor catalyst-cloud's `READINESS_CHECK_IDS` (see
-// that file's `TEAM_CHECK_IDS` and its provenance comment): dated, cited, paired with a test, never
-// hand-copied and trusted on its own.
-//
-// What a parity test built against THIS copy can, and cannot, catch: it can catch this copy DRIFTING
-// FROM ITSELF — a rule dropped, loosened or tightened by a future edit here. It CANNOT notice a new
-// rule landing upstream, because nothing in this repository imports the real function — there is no
-// publish channel for it. The one fixture pinned by a real, run command transcript rather than by
-// prose (`valid-empty-provenance.json`, in `test/fixtures/env-declaration/`) is the strongest anchor
-// this vendored copy has; the rest are pinned by the two agreeing research passes.
-const MAX_ENV_REFS = 128;
-const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-// ⛔ A PREFIX ONLY COUNTS AT A TOKEN BOUNDARY (validate attempt 29, CR-6). These were matched with
-// `text.includes(p)`, and "sk-" is a SUBSTRING of "task-", "risk-" and "disk-" — so a declaration
-// whose setup step was `["npm","run","task-build"]` was refused as containing secret material. Every
-// prefix here is identifier-shaped, so a match is real only at the start of the text or after a
-// character that cannot be part of a token; PEM armour, which is not identifier-shaped and carries
-// its own unmistakable delimiter, keeps a plain substring match of its own.
-// `gho_`, `sk_live_` and `AIza` are in the 2026-09-10 pass's list of upstream's prefixes
-// (thoughts: repos/catalyst/shared/research/2026-09-10-CTC-2020-laptop-environment-inventory.md:65),
-// and `ghs_` is pinned as an upstream entry by the 2026-09-27 CTC-3378 plan v2 (:238). Validate
-// attempt 31 found the first three missing here (and noted `ghs_`), so `env check` said `valid`
-// where upstream's validator refuses.
-// That upstream list ends "and others": this copy still cannot claim to hold every entry.
-const KNOWN_SECRET_PREFIXES = ["ghp_", "gho_", "ghs_", "github_pat_", "sk-", "sk_live_", "AKIA", "AIza", "xoxb-", "xoxp-"];
-const PEM_ARMOUR = "-----BEGIN";
-const KNOWN_SECRET_PREFIX_RE = new RegExp(`(?:^|[^A-Za-z0-9_])(?:${KNOWN_SECRET_PREFIXES.map(escapeForRegExp).join("|")})`);
-function escapeForRegExp(literal) {
-    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-const SECRET_ASSIGNMENT_RE = /\b([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(\S{4,})/g;
-const SECRET_NAME_RE = /(_TOKEN|_SECRET|_KEY|_PASSWORD|_CREDENTIAL)$|^(TOKEN|SECRET|PASSWORD)$/i;
-const REQUIRED_ARRAY_FIELDS = ["toolchains", "systemPackages", "setup", "verify", "services", "environment", "agentAssets", "provenance"];
-const TOP_LEVEL_FIELDS = new Set(["version", ...REQUIRED_ARRAY_FIELDS]);
-/** Empty array = valid. Never reads, and never returns, a value — only field names and paths. */
-export function validateDeclaration(doc) {
-    if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
-        return ["the declaration must be a JSON object"];
-    }
-    const rec = doc;
-    const errors = [];
-    for (const key of Object.keys(rec))
-        if (!TOP_LEVEL_FIELDS.has(key))
-            errors.push(`unknown key "${key}"`);
-    if (rec.version !== 1)
-        errors.push("version must be 1");
-    for (const field of REQUIRED_ARRAY_FIELDS)
-        if (!Array.isArray(rec[field]))
-            errors.push(`${field} must be an array`);
-    // The rules below assume the shape above holds; a missing/wrong-typed field is reported on its own.
-    if (errors.length > 0)
-        return errors;
-    const environment = rec.environment;
-    if (environment.length > MAX_ENV_REFS)
-        errors.push(`environment has ${environment.length} entries; at most ${MAX_ENV_REFS}`);
-    for (const [i, e] of environment.entries()) {
-        if (typeof e !== "object" || e === null) {
-            errors.push(`environment[${i}] must be an object`);
-            continue;
-        }
-        const rec2 = e;
-        if (typeof rec2.name !== "string" || !ENV_NAME_RE.test(rec2.name))
-            errors.push(`environment[${i}].name is not a valid name`);
-        if (typeof rec2.required !== "boolean")
-            errors.push(`environment[${i}].required must be a boolean`);
-        if (!Array.isArray(rec2.provenanceIds))
-            errors.push(`environment[${i}].provenanceIds must be an array`);
-    }
-    for (const field of ["setup", "verify"]) {
-        for (const [i, s] of rec[field].entries()) {
-            if (typeof s !== "object" || s === null) {
-                errors.push(`${field}[${i}] must be an object`);
-                continue;
-            }
-            const rec2 = s;
-            const command = rec2.command;
-            if (!Array.isArray(command) || command.length === 0 || !command.every((c) => typeof c === "string")) {
-                errors.push(`${field}[${i}].command must be an argv array (a bare shell string is refused; ["sh","-lc", …] is the explicit escape)`);
-            }
-            if (typeof rec2.timeoutSeconds !== "number")
-                errors.push(`${field}[${i}].timeoutSeconds must be a number`);
-            if (!Array.isArray(rec2.provenanceIds))
-                errors.push(`${field}[${i}].provenanceIds must be an array`);
-        }
-    }
-    // C-2: services / provenance / agentAssets had no element check at all, so a non-object element
-    // reached the free-text sweep below and threw instead of being reported. The rule is the same one
-    // `environment` and `setup`/`verify` already apply: an element that is not an object is an error.
-    for (const field of ["services", "provenance", "agentAssets"]) {
-        for (const [i, e] of rec[field].entries()) {
-            if (typeof e !== "object" || e === null || Array.isArray(e))
-                errors.push(`${field}[${i}] must be an object`);
-        }
-    }
-    // assertNoSecretMaterial, LAST — a value-SHAPE refusal over every free-text field (argv strings,
-    // service image names, provenance explanations, agent-asset references), never a classifier over
-    // environment[].name: there is nothing to classify there. The refusal names the FIELD, never the
-    // matched text, so this function never prints what it found.
-    for (const { path, text } of collectFreeText(rec)) {
-        if (text.includes(PEM_ARMOUR) || KNOWN_SECRET_PREFIX_RE.test(text)) {
-            errors.push(`${path} appears to contain secret material (matches a known credential prefix)`);
-            continue;
-        }
-        SECRET_ASSIGNMENT_RE.lastIndex = 0;
-        let m;
-        while ((m = SECRET_ASSIGNMENT_RE.exec(text))) {
-            if (SECRET_NAME_RE.test(m[1])) {
-                errors.push(`${path} appears to contain secret material (an assignment shaped like a secret name)`);
-                break;
-            }
-        }
-    }
-    return errors;
-}
-function collectFreeText(rec) {
-    const out = [];
-    for (const field of ["setup", "verify"]) {
-        for (const [i, s] of rec[field].entries()) {
-            const rec2 = asRecord(s);
-            if (rec2 === null)
-                continue;
-            if (Array.isArray(rec2.command)) {
-                for (const c of rec2.command)
-                    if (typeof c === "string")
-                        out.push({ path: `${field}[${i}].command`, text: c });
-            }
-        }
-    }
-    for (const [i, s] of rec.services.entries()) {
-        const rec2 = asRecord(s);
-        if (rec2 === null)
-            continue;
-        if (typeof rec2.image === "string")
-            out.push({ path: `services[${i}].image`, text: rec2.image });
-    }
-    for (const [i, p] of rec.provenance.entries()) {
-        const rec2 = asRecord(p);
-        if (rec2 === null)
-            continue;
-        if (typeof rec2.explanation === "string")
-            out.push({ path: `provenance[${i}].explanation`, text: rec2.explanation });
-    }
-    for (const [i, a] of rec.agentAssets.entries()) {
-        const rec2 = asRecord(a);
-        if (rec2 === null)
-            continue;
-        if (typeof rec2.reference === "string")
-            out.push({ path: `agentAssets[${i}].reference`, text: rec2.reference });
-    }
-    return out;
-}
-/** An element the caller may safely read properties off, or null — a non-object is reported above. */
-function asRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
-}