@catalyst-cloud/cli 0.9.5 → 0.13.1

package/dist/repo.js

@@ -0,0 +1,297 @@
+// repo.ts — `catalyst repo agents-block` and `catalyst repo agent-setup`: a repository's agent setup,
+// read and changed in a checkout the person names, never through git and never through the cloud.
+//
+//   repo agents-block <path> [--write]        the one Catalyst block in AGENTS.md, marker-delimited,
+//                                             replaced in place on a rerun (never duplicated)
+//   repo agent-setup <path> [--apply] [--with-check]
+//                                             what the repository holds for agents, whether it is
+//                                             portable, the plan that would make it so, and --apply
+//
+// Portable means: AGENTS.md is canonical; CLAUDE.md is a thin file that imports it with a line that
+// is exactly `@AGENTS.md` plus Claude-only notes; `.agents/skills` and `.agents/rules` are canonical
+// and `.claude/skills` and `.claude/rules` are relative symlinks to them. Every write lands in the
+// working tree only: committing, branching and the pull request are the person's, in the open.
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { flagBool, positionals } from "./args.js";
+import { UsageError } from "./errors.js";
+export const BLOCK_START = "<!-- catalyst:start -->";
+export const BLOCK_END = "<!-- catalyst:end -->";
+/** The two skills the block names. ONE place each: the packs are being consolidated, and a rename
+ *  lands here, then `repo agents-block --write` brings every repository's block up to date. */
+export const BLOCK_PROCESS_SKILL = "whats-happening";
+export const BLOCK_DECISION_SKILL = "catalyst-sop";
+/** ⭐ THE block, word for word. Harness-agnostic; names the skills, never the process. */
+export const CATALYST_AGENTS_BLOCK = [
+    BLOCK_START,
+    "## Catalyst",
+    "",
+    `This repository is worked through Catalyst: tickets move through a pipeline of agent-run phases, and pull requests merge through its queue. Before you plan, branch, review or merge here, load the skill that explains the process instead of inferring it from this file: \`${BLOCK_PROCESS_SKILL}\` (how a ticket runs, what each phase produces, why work waits), and \`${BLOCK_DECISION_SKILL}\` when it is installed (what to do when work stalls on a decision). Keep this block as it is; onboarding maintains it.`,
+    BLOCK_END,
+].join("\n");
+/** Where the block sits in `text`, or null. Only the FIRST start marker and the first end after it count. */
+function locateBlock(text) {
+    const start = text.indexOf(BLOCK_START);
+    if (start === -1)
+        return null;
+    const endAt = text.indexOf(BLOCK_END, start);
+    if (endAt === -1)
+        return null;
+    return { start, end: endAt + BLOCK_END.length };
+}
+/** The block's state in an AGENTS.md text (`null` text = no file). */
+export function blockState(text) {
+    if (text === null)
+        return "absent";
+    const at = locateBlock(text);
+    if (at === null)
+        return "missing";
+    return text.slice(at.start, at.end) === CATALYST_AGENTS_BLOCK ? "current" : "stale";
+}
+/** The text with the block current: replaced in place, appended after one blank line, or the whole
+ *  file. Pure and idempotent: applying it to its own output changes nothing. */
+export function withBlock(text) {
+    if (text === null || text.trim() === "")
+        return `${CATALYST_AGENTS_BLOCK}\n`;
+    const at = locateBlock(text);
+    if (at !== null)
+        return `${text.slice(0, at.start)}${CATALYST_AGENTS_BLOCK}${text.slice(at.end)}`;
+    const body = text.replace(/\s+$/, "");
+    return `${body}\n\n${CATALYST_AGENTS_BLOCK}\n`;
+}
+function linkState(root, rel, canonicalRel) {
+    const p = join(root, rel);
+    let st;
+    try {
+        st = lstatSync(p);
+    }
+    catch {
+        return { kind: "absent" };
+    }
+    if (st.isSymbolicLink()) {
+        const target = readlinkSync(p);
+        const resolved = resolve(dirname(p), target);
+        return { kind: "symlink", target, resolvesToCanonical: resolved === resolve(root, canonicalRel) && existsSync(resolved) };
+    }
+    return st.isDirectory() ? { kind: "dir" } : { kind: "file" };
+}
+const OTHER_MARKERS = [".codex", ".cursor", ".cursorrules", ".windsurfrules", "GEMINI.md", ".github/copilot-instructions.md"];
+/** Read a checkout's agent setup. Never writes. */
+export function inspectRepo(root) {
+    const agentsPath = join(root, "AGENTS.md");
+    const claudePath = join(root, "CLAUDE.md");
+    const agentsText = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : null;
+    const claudeText = existsSync(claudePath) ? readFileSync(claudePath, "utf8") : null;
+    const claudeLines = claudeText === null ? [] : claudeText.split("\n");
+    const importsAgentsMd = claudeLines.some((l) => l.trim() === "@AGENTS.md");
+    const otherLines = claudeLines.filter((l) => l.trim() !== "" && l.trim() !== "@AGENTS.md").length;
+    const report = {
+        path: root,
+        agentsMd: { present: agentsText !== null, lines: agentsText === null ? 0 : agentsText.replace(/\n$/, "").split("\n").length, bytes: agentsText === null ? 0 : Buffer.byteLength(agentsText), block: blockState(agentsText) },
+        claudeMd: { present: claudeText !== null, importsAgentsMd, otherLines },
+        agentsDir: { skills: isDir(join(root, ".agents", "skills")), rules: isDir(join(root, ".agents", "rules")) },
+        claudeDir: { skills: linkState(root, ".claude/skills", ".agents/skills"), rules: linkState(root, ".claude/rules", ".agents/rules") },
+        others: OTHER_MARKERS.filter((m) => existsSync(join(root, m))),
+        verdict: "portable",
+        plan: [],
+        blockers: [],
+    };
+    // CLAUDE.md with guidance of its own and no import: its content belongs in AGENTS.md.
+    if (report.claudeMd.present && !importsAgentsMd) {
+        report.plan.push(report.agentsMd.present
+            ? "append CLAUDE.md's content to AGENTS.md and leave CLAUDE.md as the thin importer (`@AGENTS.md` plus Claude-only notes)"
+            : "create AGENTS.md from CLAUDE.md's content and leave CLAUDE.md as the thin importer (`@AGENTS.md`)");
+    }
+    else if (!report.agentsMd.present && !report.claudeMd.present) {
+        report.plan.push("create AGENTS.md (the Catalyst block starts it; add the repository's own guidance there)");
+    }
+    for (const name of ["skills", "rules"]) {
+        const c = report.claudeDir[name];
+        const canonical = report.agentsDir[name];
+        if (c.kind === "dir" && !canonical)
+            report.plan.push(`move .claude/${name} to .agents/${name} and leave .claude/${name} as a relative symlink to it`);
+        else if (c.kind === "dir" && canonical)
+            report.blockers.push(`.claude/${name} and .agents/${name} are both real directories: merge them by hand, then leave .claude/${name} as a relative symlink`);
+        else if (c.kind === "symlink" && !c.resolvesToCanonical)
+            report.blockers.push(`.claude/${name} is a symlink to ${c.target}, not to .agents/${name}: point it there by hand`);
+        else if (c.kind === "absent" && canonical)
+            report.plan.push(`add .claude/${name} as a relative symlink to .agents/${name}`);
+        else if (c.kind === "file")
+            report.blockers.push(`.claude/${name} is a file, not a directory: look at it by hand`);
+    }
+    if (report.blockers.length > 0)
+        report.verdict = "needs_hand_merge";
+    else if (report.plan.length > 0)
+        report.verdict = "convertible";
+    return report;
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+const THIN_CLAUDE_MD = "# CLAUDE.md\n\nAll project context for any coding agent is in AGENTS.md, imported below. Only Claude-specific notes belong in this file.\n\n@AGENTS.md\n";
+/** Perform a convertible plan in the working tree. Refuses when anything needs a hand merge. */
+export function applyPlan(root, before) {
+    if (before.verdict === "needs_hand_merge")
+        throw new UsageError(`nothing applied: ${before.blockers.join("; ")}`);
+    const done = [];
+    const agentsPath = join(root, "AGENTS.md");
+    const claudePath = join(root, "CLAUDE.md");
+    if (before.claudeMd.present && !before.claudeMd.importsAgentsMd) {
+        const claudeText = readFileSync(claudePath, "utf8");
+        const existing = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8").replace(/\s+$/, "") : "";
+        const merged = existing === "" ? claudeText.replace(/\s+$/, "") + "\n" : `${existing}\n\n${claudeText.replace(/\s+$/, "")}\n`;
+        writeFileSync(agentsPath, merged);
+        writeFileSync(claudePath, THIN_CLAUDE_MD);
+        done.push(before.agentsMd.present ? "appended CLAUDE.md's content to AGENTS.md; CLAUDE.md now imports it" : "created AGENTS.md from CLAUDE.md; CLAUDE.md now imports it");
+    }
+    else if (!before.agentsMd.present && !before.claudeMd.present) {
+        writeFileSync(agentsPath, withBlock(null));
+        done.push("created AGENTS.md holding the Catalyst block");
+    }
+    for (const name of ["skills", "rules"]) {
+        const c = before.claudeDir[name];
+        const canonicalPath = join(root, ".agents", name);
+        const claudeLink = join(root, ".claude", name);
+        if (c.kind === "dir" && !before.agentsDir[name]) {
+            mkdirSync(join(root, ".agents"), { recursive: true });
+            renameSync(claudeLink, canonicalPath);
+            symlinkSync(relative(dirname(claudeLink), canonicalPath), claudeLink, "dir");
+            done.push(`moved .claude/${name} to .agents/${name} and left a relative symlink`);
+        }
+        else if (c.kind === "absent" && before.agentsDir[name]) {
+            mkdirSync(join(root, ".claude"), { recursive: true });
+            symlinkSync(relative(dirname(claudeLink), canonicalPath), claudeLink, "dir");
+            done.push(`added .claude/${name} as a relative symlink to .agents/${name}`);
+        }
+    }
+    return done;
+}
+/** The lightweight check a customer can run in CI: node only, no dependencies, exit 1 on a finding. */
+export const AGENTS_MD_CHECK_SCRIPT = `#!/usr/bin/env node
+// agents-md-check.mjs — keeps this repository's agent setup portable. Run it in CI:
+//   node scripts/agents-md-check.mjs
+// It fails when CLAUDE.md stops importing AGENTS.md, when .claude/skills or .claude/rules stops being
+// a relative symlink into .agents/, when AGENTS.md outgrows its budget, or when a repository path
+// AGENTS.md cites no longer exists. Budgets: AGENTS_MD_MAX_LINES and AGENTS_MD_MAX_BYTES (env).
+import { existsSync, lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+const root = process.cwd();
+const maxLines = Number(process.env.AGENTS_MD_MAX_LINES ?? 120);
+const maxBytes = Number(process.env.AGENTS_MD_MAX_BYTES ?? 16 * 1024);
+const findings = [];
+const agents = existsSync("AGENTS.md") ? readFileSync("AGENTS.md", "utf8") : null;
+if (agents === null) findings.push("AGENTS.md is missing");
+else {
+  const lines = agents.replace(/\\n$/, "").split("\\n");
+  if (lines.length > maxLines) findings.push(\`AGENTS.md is \${lines.length} lines (budget \${maxLines})\`);
+  if (Buffer.byteLength(agents) > maxBytes) findings.push(\`AGENTS.md is \${Buffer.byteLength(agents)} bytes (budget \${maxBytes})\`);
+  for (const m of agents.matchAll(/\`([\\w.-]+(?:\\/[\\w.-]+)+)\`/g)) {
+    const p = m[1];
+    if (!existsSync(resolve(root, p))) findings.push(\`AGENTS.md cites \${p}, which does not exist\`);
+  }
+}
+if (existsSync("CLAUDE.md")) {
+  const n = readFileSync("CLAUDE.md", "utf8").split("\\n").filter((l) => l.trim() === "@AGENTS.md").length;
+  if (n !== 1) findings.push(\`CLAUDE.md must import AGENTS.md on exactly one line reading @AGENTS.md (found \${n})\`);
+}
+for (const name of ["skills", "rules"]) {
+  const link = \`.claude/\${name}\`;
+  const canonical = \`.agents/\${name}\`;
+  if (!existsSync(canonical) && !existsSync(link)) continue;
+  let st;
+  try { st = lstatSync(link); } catch { findings.push(\`\${link} is missing; make it a relative symlink to \${canonical}\`); continue; }
+  if (!st.isSymbolicLink()) { findings.push(\`\${link} is a real \${st.isDirectory() ? "directory" : "file"}; make \${canonical} canonical and \${link} a relative symlink\`); continue; }
+  const target = readlinkSync(link);
+  if (target.startsWith("/")) findings.push(\`\${link} is an absolute symlink (\${target}); make it relative\`);
+  if (resolve(dirname(link), target) !== resolve(root, canonical)) findings.push(\`\${link} points at \${target}, not \${canonical}\`);
+}
+for (const f of findings) console.error(\`agents-md-check: \${f}\`);
+if (findings.length > 0) process.exit(1);
+console.log("agents-md-check: portable");
+`;
+const describeLink = (s) => (s.kind === "symlink" ? `symlink → ${s.target}${s.resolvesToCanonical ? "" : " (not the canonical directory)"}` : s.kind === "dir" ? "real directory" : s.kind === "file" ? "a file" : "absent");
+export function reportLines(r) {
+    const lines = [
+        `repository: ${r.path}`,
+        `AGENTS.md: ${r.agentsMd.present ? `${r.agentsMd.lines} lines, ${r.agentsMd.bytes} bytes; Catalyst block ${r.agentsMd.block}` : "absent"}`,
+        `CLAUDE.md: ${r.claudeMd.present ? (r.claudeMd.importsAgentsMd ? `imports AGENTS.md${r.claudeMd.otherLines ? ` plus ${r.claudeMd.otherLines} lines of Claude-only notes` : ""}` : `${r.claudeMd.otherLines} lines of its own guidance, no @AGENTS.md import`) : "absent"}`,
+        `.agents/skills: ${r.agentsDir.skills ? "present" : "absent"}; .claude/skills: ${describeLink(r.claudeDir.skills)}`,
+        `.agents/rules: ${r.agentsDir.rules ? "present" : "absent"}; .claude/rules: ${describeLink(r.claudeDir.rules)}`,
+    ];
+    if (r.others.length > 0)
+        lines.push(`also present: ${r.others.join(", ")}`);
+    lines.push(`verdict: ${r.verdict === "portable" ? "portable (AGENTS.md canonical, Claude files import or link to it)" : r.verdict === "convertible" ? "convertible; --apply performs this plan in the working tree:" : "needs a hand merge before --apply:"}`);
+    for (const p of r.plan)
+        lines.push(`  - ${p}`);
+    for (const b of r.blockers)
+        lines.push(`  ⛔ ${b}`);
+    if (r.agentsMd.block !== "current")
+        lines.push(`  - the Catalyst block is ${r.agentsMd.block}: catalyst repo agents-block ${r.path} --write`);
+    return lines;
+}
+function checkoutRoot(args, sub) {
+    const [, path, ...extra] = positionals(args);
+    if (!path)
+        throw new UsageError(`repo ${sub} needs the checkout's path`);
+    if (extra.length > 0)
+        throw new UsageError(`repo ${sub} takes one path`);
+    const root = resolve(path);
+    if (!isDir(root))
+        throw new UsageError(`${path} is not a directory on this machine`);
+    return root;
+}
+export async function cmdRepo(args, ctx) {
+    const [sub] = positionals(args);
+    if (sub !== "agents-block" && sub !== "agent-setup")
+        throw new UsageError("repo needs agents-block <path> [--write] or agent-setup <path> [--apply] [--with-check]");
+    const root = checkoutRoot(args, sub);
+    const emit = (body, lines) => { if (args.json)
+        ctx.stdout(JSON.stringify(body));
+    else
+        for (const l of lines)
+            ctx.stdout(l); };
+    if (sub === "agents-block") {
+        if (flagBool(args, "apply") || flagBool(args, "with-check"))
+            throw new UsageError("--apply and --with-check belong to repo agent-setup");
+        const file = join(root, "AGENTS.md");
+        const before = existsSync(file) ? readFileSync(file, "utf8") : null;
+        const state = blockState(before);
+        if (!flagBool(args, "write")) {
+            const hint = state === "current" ? "nothing to do" : `run with --write to ${state === "absent" ? "create AGENTS.md with it" : state === "missing" ? "append it" : "bring it up to date"} (in the working tree; commit it on a branch and open a pull request)`;
+            emit({ path: root, agentsMd: before !== null, block: state, changed: false }, [`AGENTS.md: Catalyst block ${state} — ${hint}`]);
+            return state === "current" ? 0 : 1;
+        }
+        const after = withBlock(before);
+        const changed = after !== before;
+        if (changed)
+            writeFileSync(file, after);
+        emit({ path: root, agentsMd: true, block: "current", changed, was: state }, [
+            changed ? `AGENTS.md: Catalyst block ${state === "absent" ? "written to a new AGENTS.md" : state === "missing" ? "appended" : "updated in place"}; commit it on a branch and open a pull request` : "AGENTS.md: Catalyst block already current; nothing changed",
+        ]);
+        return 0;
+    }
+    if (flagBool(args, "write"))
+        throw new UsageError("--write belongs to repo agents-block");
+    const before = inspectRepo(root);
+    const applied = [];
+    if (flagBool(args, "apply"))
+        applied.push(...applyPlan(root, before));
+    if (flagBool(args, "with-check")) {
+        const dir = join(root, "scripts");
+        mkdirSync(dir, { recursive: true });
+        const target = join(dir, "agents-md-check.mjs");
+        const same = existsSync(target) && readFileSync(target, "utf8") === AGENTS_MD_CHECK_SCRIPT;
+        if (!same)
+            writeFileSync(target, AGENTS_MD_CHECK_SCRIPT, { mode: 0o755 });
+        applied.push(same ? "scripts/agents-md-check.mjs already current" : "wrote scripts/agents-md-check.mjs (run it in CI: node scripts/agents-md-check.mjs)");
+    }
+    const after = applied.length > 0 ? inspectRepo(root) : before;
+    emit({ ...after, applied }, [...(applied.length ? ["applied:", ...applied.map((a) => `  - ${a}`)] : []), ...reportLines(after)]);
+    return after.verdict === "portable" && after.agentsMd.block === "current" ? 0 : 1;
+}

package/dist/runtime-verb.js

@@ -1,4 +1,4 @@
-// runtime-verb.ts — CTC-2158, Tier 2. `catalyst-skills runtime status|install|path|uninstall`: the
+// runtime-verb.ts — CTC-2158, Tier 2. `catalyst runtime status|install|path|uninstall`: the
 // verb every unsupported-runtime message points at. It downloads the pinned Node named by
 // package.json's `catalystCloud.pinnedNode`, verifies it, and unpacks it under this CLI's own
 // cache — it never touches the machine's default Node and needs no admin rights.

package/dist/secret.js

@@ -1,4 +1,4 @@
-// secret.ts — `catalyst-skills secret set|import`: put a repository's secrets into the cloud from the
+// secret.ts — `catalyst secret set|import`: put a repository's secrets into the cloud from the
 // terminal, as the person who is logged in (CTC-3549). The cloud gates both on an admin or owner seat,
 // encrypts the value, and records who wrote it and where it came from, never the value itself.
 //

package/dist/skill-shape.js

@@ -85,7 +85,7 @@ export function validateSkillDir(dir) {
     if (lines.length > MAX_SKILL_LINES)
         problems.push(`${name}: SKILL.md is ${lines.length} lines (max ${MAX_SKILL_LINES})`);
     const fm = parseFrontmatter(lines);
-    let mutatingFrontmatter = false;
+    let manualOnlyFrontmatter = false;
     if (!fm)
         problems.push(`${name}: SKILL.md must start with YAML frontmatter (---)`);
     else {
@@ -99,7 +99,7 @@ export function validateSkillDir(dir) {
             problems.push(`${name}: frontmatter is missing "description"`);
         else if (fm.fields.description.length > MAX_DESCRIPTION_CHARS)
             problems.push(`${name}: description is ${fm.fields.description.length} characters (max ${MAX_DESCRIPTION_CHARS})`);
-        mutatingFrontmatter = fm.fields["disable-model-invocation"] === "true";
+        manualOnlyFrontmatter = fm.fields["disable-model-invocation"] === "true";
         if (fm.closeIndex !== -1) {
             const after = lines[fm.closeIndex + 1] ?? "";
             if (!(after.startsWith("<!--") && after.includes(PROVENANCE_MARKER))) {
@@ -142,10 +142,14 @@ export function validateSkillDir(dir) {
             }
         }
     }
+    // Invocation is one choice written in three places: SKILL.md's `disable-model-invocation`, the
+    // OpenAI sidecar's `allow_implicit_invocation`, and portability's `invocation`. They must agree.
+    // Whether a skill writes (`mutating`) is a separate fact: a skill that writes can still be picked
+    // by the model, and its own scoped controls (a write budget, a preview) govern the write.
     const portability = join(dir, "agents", "portability.yaml");
     const openai = join(dir, "agents", "openai.yaml");
-    let mutating = false;
-    let implicitFalse = false;
+    let explicitPortability = null;
+    let implicitFalse = null;
     if (!existsSync(portability))
         problems.push(`${name}: agents/portability.yaml is missing`);
     else {
@@ -154,7 +158,14 @@ export function validateSkillDir(dir) {
             problems.push(`${name}: agents/portability.yaml does not declare "effects"`);
         if (!/^exposure:\s*\[\s*"?catalog"?\s*\]\s*$/m.test(y))
             problems.push(`${name}: agents/portability.yaml must declare exposure: [catalog]`);
-        mutating = /^mutating:\s*true\s*$/m.test(y);
+        const mutating = /^mutating:\s*true\s*$/m.test(y);
+        const effectsEmpty = /^effects:\s*\[\s*\]\s*$/m.test(y);
+        if (mutating && effectsEmpty)
+            problems.push(`${name}: agents/portability.yaml says mutating: true but lists no effects`);
+        if (!mutating && /^effects:\s*\[\s*[^\]\s]/m.test(y))
+            problems.push(`${name}: agents/portability.yaml lists effects but lacks mutating: true`);
+        const inv = /^invocation:\s*(\w+)\s*$/m.exec(y)?.[1];
+        explicitPortability = inv === undefined ? null : inv === "explicit";
     }
     if (!existsSync(openai))
         problems.push(`${name}: agents/openai.yaml is missing`);
@@ -164,15 +175,12 @@ export function validateSkillDir(dir) {
             problems.push(`${name}: agents/openai.yaml has no "policy:" block`);
         if (!/allow_implicit_invocation:\s*(true|false)/.test(y))
             problems.push(`${name}: agents/openai.yaml does not set policy.allow_implicit_invocation`);
-        implicitFalse = /allow_implicit_invocation:\s*false/.test(y);
+        else
+            implicitFalse = /allow_implicit_invocation:\s*false/.test(y);
     }
-    if (mutating || mutatingFrontmatter || implicitFalse) {
-        if (!mutating)
-            problems.push(`${name}: disable-model-invocation / allow_implicit_invocation: false are set but agents/portability.yaml lacks mutating: true`);
-        if (!mutatingFrontmatter)
-            problems.push(`${name}: is mutating but SKILL.md does not set disable-model-invocation: true`);
-        if (!implicitFalse)
-            problems.push(`${name}: is mutating but agents/openai.yaml does not set policy.allow_implicit_invocation: false`);
+    const manualFlags = [manualOnlyFrontmatter, implicitFalse, explicitPortability].filter((v) => v !== null);
+    if (new Set(manualFlags).size > 1) {
+        problems.push(`${name}: the invocation fields disagree about whether the model may pick this skill (SKILL.md disable-model-invocation: ${manualOnlyFrontmatter}, agents/openai.yaml allow_implicit_invocation: ${implicitFalse === null ? "unset" : !implicitFalse}, agents/portability.yaml invocation: ${explicitPortability === null ? "unset" : explicitPortability ? "explicit" : "implicit"})`);
     }
     for (const p of walk(dir)) {
         const rel = relative(dir, p);

package/dist/skills.js

@@ -1,9 +1,9 @@
 // skills.ts — copying the bundled skills into the user's skills directory, and the one-line update
 // notice a new version prints on its next session.
-import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { defaultSkillsDirFor, upgradeCommand } from "./config.js";
+import { defaultSkillsDirFor, readManifest, upgradeCommand } from "./config.js";
 import { semverOlder } from "./semver.js";
 import { PROVENANCE_MARKER, parseFrontmatter, parseProvenanceVersion } from "./skill-shape.js";
 export function skillsSourceDir() {
@@ -16,9 +16,14 @@ export function skillsSourceDir() {
  * `onlyExisting` is the update path: it refreshes copies this package already made and creates
  * none. That is what keeps the update notice from planting a second copy of every skill beside a
  * set the customer's agent installed as a plugin.
+ *
+ * Both paths then remove a retired skill: a folder in the target that carries this bundle's
+ * provenance stamp but whose name this bundle no longer ships. Left in place, it keeps routing
+ * requests to a skill that was merged away. A folder without the stamp (a person's own skill), a
+ * symlink, and a folder stamped by a NEWER bundle than this one are never removed.
  */
-export function installSkills(targetDir, opts, sourceDir = skillsSourceDir()) {
-    const result = { installed: [], skipped: [] };
+export function installSkills(targetDir, opts, sourceDir = skillsSourceDir(), bundleVersion = readManifest().version) {
+    const result = { installed: [], skipped: [], removed: [] };
     if (existsSync(targetDir) && !statSync(targetDir).isDirectory()) {
         throw new Error(`${targetDir} is not a directory`);
     }
@@ -49,8 +54,43 @@ export function installSkills(targetDir, opts, sourceDir = skillsSourceDir()) {
         cpSync(src, dst, { recursive: true });
         result.installed.push(name);
     }
+    result.removed = removeRetiredSkills(targetDir, new Set(names.filter((n) => existsSync(join(sourceDir, n, "SKILL.md")))), bundleVersion);
     return result;
 }
+/** Remove every stamped folder in `targetDir` whose name `shipped` no longer carries. */
+function removeRetiredSkills(targetDir, shipped, bundleVersion) {
+    if (!existsSync(targetDir))
+        return [];
+    const removed = [];
+    for (const e of readdirSync(targetDir, { withFileTypes: true })) {
+        if (shipped.has(e.name))
+            continue;
+        const dir = join(targetDir, e.name);
+        // lstat, not the dirent alone: a symlink belongs to whoever linked it and is never followed.
+        if (isSymlink(dir) || !e.isDirectory())
+            continue;
+        const skillMd = join(dir, "SKILL.md");
+        if (!existsSync(skillMd))
+            continue;
+        let text;
+        try {
+            text = readFileSync(skillMd, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const line = provenanceLine(text);
+        if (line === undefined)
+            continue;
+        const stamp = parseProvenanceVersion(line);
+        // A newer bundle may ship a skill this one does not know yet; an older CLI must not delete it.
+        if (stamp !== null && semverOlder(bundleVersion, stamp))
+            continue;
+        rmSync(dir, { recursive: true, force: true });
+        removed.push(e.name);
+    }
+    return removed.sort();
+}
 function isSymlink(path) {
     try {
         return lstatSync(path).isSymbolicLink();

package/dist/transport.js

@@ -32,7 +32,16 @@ export class ApiClient {
         const url = this.url(path, opts.query);
         const res = await this.send(url, { method: "GET", headers });
         if (opts.accept?.includes(res.status)) {
-            return { status: res.status, body: undefined, headers: res.headers };
+            let body = undefined;
+            if (opts.parseAccepted) {
+                try {
+                    body = (await res.json());
+                }
+                catch {
+                    body = undefined;
+                }
+            }
+            return { status: res.status, body, headers: res.headers };
         }
         await this.refuseIfNotOk(res, `GET ${path}`);
         return { status: res.status, body: await this.parseBody(res, `GET ${path}`), headers: res.headers };
@@ -87,6 +96,22 @@ export class ApiClient {
             await this.refuseIfNotOk(res, `POST ${path}`);
         return { status: res.status, body: await this.parseBody(res, `POST ${path}`), headers: res.headers };
     }
+    /** PUT a JSON body. Same contract as {@link postJson}: `accept` lists statuses returned as replies. */
+    async putJson(path, body, opts = {}) {
+        const url = this.url(path);
+        const res = await this.send(url, {
+            method: "PUT",
+            headers: {
+                authorization: `Bearer ${await this.credential()}`,
+                accept: "application/json",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!opts.accept?.includes(res.status))
+            await this.refuseIfNotOk(res, `PUT ${path}`);
+        return { status: res.status, body: await this.parseBody(res, `PUT ${path}`), headers: res.headers };
+    }
     async send(url, init) {
         try {
             return await this.fetchImpl(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.9.5",
-  "description": "Customer skill bundle for Catalyst Cloud, named from the executive's seat — get set up, see what is happening, see what needs you, run a project, unstick what is stuck — plus the catalyst CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command. The skills directory is the roster; this line never counts it.",
+  "version": "0.13.1",
+  "description": "Customer skill bundle for Catalyst Cloud, named from the executive's seat — get set up, see what is happening, see what needs you, run a project, unstick what is stuck — plus the catalyst CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your cloud account with one command. The skills directory is the roster; this line never counts it.",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -45,16 +45,17 @@
     "skill-lib:sync": "node scripts/sync-skill-lib.mjs",
     "skills:scan": "node scripts/scan-skills.mjs",
     "evals": "node scripts/run-evals.mjs",
-    "paths:check": "node scripts/vendor-paths.mjs --check"
+    "paths:check": "node scripts/vendor-paths.mjs --check",
+    "prose:check": "node scripts/check-public-prose.mjs"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "^0.12.0"
+    "@catalyst-cloud/sdk": "^0.13.1",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",
     "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11",
-    "yaml": "^2.9.0"
+    "vitest": "^4.1.11"
   }
 }

package/skills/catalyst-github/SKILL.md

@@ -2,20 +2,20 @@
 name: catalyst-github
 description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
-allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.1 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 
-You answer for the pull requests Catalyst opens and moves. The person asking wants to see one PR, know what is red, and know whether it will merge. Everything tenant-specific (the reviewer's login, the merge policy per repository, the four PR label names, the required checks) comes from the contract at run time and is printed by the scripts; you never restate it from memory.
+You answer for the pull requests Catalyst opens and moves. The person asking wants to see one PR, know what is red, and know whether it will merge. Everything account-specific (the reviewer's login, the merge policy per repository, the four PR label names, the required checks) comes from the contract at run time and is printed by the scripts; you never restate it from memory.
 
 ## Run first
 
-- `node scripts/read-pr.mjs --help` — a ticket's PR (or a PR by node id): state, branch, head, linked ticket, GitHub's mergeable state, every check, status and review. `--all` lists every PR for a ticket.
-- `node scripts/is-it-mergeable.mjs --help` — the three legs (checks, reviewer signal, unresolved threads) judged under the repository's policy, plus the prerequisites; exit 1 when a leg is red.
+- `node scripts/read-pr.mjs --help`: a ticket's PR (or a PR by node id): state, branch, head, linked ticket, GitHub's mergeable state, every check, status and review. `--all` lists every PR for a ticket.
+- `node scripts/is-it-mergeable.mjs --help`: the three legs (checks, reviewer signal, unresolved threads) judged under the repository's policy, plus the prerequisites; exit 1 when a leg is red.
 
-Both read through `catalyst-skills query`, `contract` and, when fresh, `replica`; the first stderr line names the source, and your answer repeats it.
+Both read through `catalyst query`, `contract` and, when fresh, `replica`; the first stderr line names the source, and your answer repeats it.
 
 ## Load on demand
 
@@ -26,7 +26,7 @@ Both read through `catalyst-skills query`, `contract` and, when fresh, `replica`
 
 ## Rules
 
-- Never compose a URL or call the API yourself. Every read is a `catalyst-skills` verb behind a script; run the script, do not read it.
+- Never compose a URL or call the API yourself. Every read is a `catalyst` verb behind a script; run the script, do not read it.
 - A queue-ready label is the cloud's attestation, never a lever you apply; "merged by the queue" is the terminal signal.
 - Hold labels are the human's lever. Describe them; do not apply or remove them.
 - Say what a key cannot see by name (PR labels, the reviewer's reaction, the queue's own state); never guess it.

package/skills/catalyst-github/references/is-it-mergeable.md

@@ -1,6 +1,6 @@
 # Is it mergeable?
 
-The rule is invariant; the policy that applies to a repository is not. The policy names, the default, each repository's resolved policy and its source (repository setting, tenant setting, or the default), the reviewer login and the required check names all come from the contract's `merge` block at run time. `node scripts/is-it-mergeable.mjs <ticket>` reads them and prints one line per leg; the text below explains what those lines mean.
+The rule is invariant; the policy that applies to a repository is not. The policy names, the default, each repository's resolved policy and its source (repository setting, account setting, or the default), the reviewer login and the required check names all come from the contract's `merge` block at run time. `node scripts/is-it-mergeable.mjs <ticket>` reads them and prints one line per leg; the text below explains what those lines mean.
 
 ## Prerequisites before any leg counts
 
@@ -28,7 +28,13 @@ Three policy names are served on `merge.policies`; the default is `merge.default
 | the strict variant | a clean pass at the current head, always. Findings on an earlier head keep blocking until the reviewer looks again. |
 | checks and threads only | the reviewer requirement is dropped entirely; the two unconditional legs decide. |
 
-A clean pass is a reaction: a thumbs-up from the reviewer login posted at or after the head commit's own timestamp. The comment-shaped clean pass ("no major issues" in place of threads) is honoured only if `cleanPassShapes[]` says so for that kind; the script does not judge it either way.
+A clean pass is one of three signals from the reviewer login, most reliable first:
+
+1. **A GitHub review on the exact head commit.** A review names the commit it was submitted against, so it cannot be mistaken for an earlier head.
+2. **A 👍 reaction**, which counts only if it was given after the current head commit was made. The reaction carries no commit, so the cloud compares its time with the head commit's date, and that date is set by whoever made the commit. A push of a commit made before the 👍 (a force-push back to an older commit, a commit prepared earlier) can read as covered. A normal rebase or amend stamps a fresh date, so the everyday path works.
+3. **A clean-pass comment** ("no major issues" in place of threads), honoured only if `cleanPassShapes[]` says so for that kind, with the same timing rule as the 👍.
+
+A new push needs a fresh signal at the new head. The script judges none of these three itself.
 
 ## What the script can and cannot see
 

package/skills/catalyst-github/references/what-a-pr-accumulates.md

@@ -1,6 +1,6 @@
 # What a pull request accumulates as Catalyst moves a ticket
 
-Most of this page restates invariants: how Catalyst names branches, opens and rewrites pull requests, and what it pushes when. The parts that vary per tenant are read live from the contract's `merge` block and never restated here: the reviewer's login (`merge.reviewerLogin`), which clean-pass shapes are honoured (`merge.cleanPassShapes[]`), the four PR label names (`merge.prLabels`), the checks the cloud waits on (`merge.cloudRemediateRequiredChecks`, on a 1.x contract only), and the policy per repository (`merge.repositories[]`, else `merge.defaultPolicy`). `catalyst-skills contract --path merge` prints them.
+How Catalyst names branches, opens and rewrites pull requests, and what it pushes when, is the same for every account. The parts that vary are read live from the contract's `merge` block and never restated here: the reviewer's login (`merge.reviewerLogin`), which clean-pass shapes are honoured (`merge.cleanPassShapes[]`), the four PR label names (`merge.prLabels`), the checks the cloud waits on (`merge.cloudRemediateRequiredChecks`, on a 1.x contract only), and the policy per repository (`merge.repositories[]`, else `merge.defaultPolicy`). `catalyst contract --path merge` prints them.
 
 ## The branch
 
@@ -29,7 +29,7 @@ Three phases rewrite history on the ticket branch: implement pushes fresh with f
 
 ## The reviewer signal
 
-An automated reviewer (login from the contract) reviews every PR. Its signal is one of four: clean, findings at the current head, findings at an earlier head, no review. A clean pass is a reaction, not a review object: a thumbs-up from the reviewer posted at or after the head commit's own timestamp. A second shape, a terse "no major issues" comment in place of review threads, exists as a documented convention; whether it is honoured is served on `cleanPassShapes[].honoured` and must be read there, never assumed. What counts under each policy is on `references/is-it-mergeable.md`.
+An automated reviewer (login from the contract) reviews every PR. Its signal is one of four: clean, findings at the current head, findings at an earlier head, no review. A clean pass is usually a 👍 reaction from the reviewer, which counts only if it was given after the current head commit was made; a GitHub review on that exact commit is the most reliable signal. A terse "no major issues" comment in place of review threads is a documented convention; whether it is honoured is served on `cleanPassShapes[].honoured` and must be read there, never assumed. What counts under each policy is on `references/is-it-mergeable.md`.
 
 ## Labels on the PR
 
@@ -42,7 +42,7 @@ Four labels matter, all named on `merge.prLabels`, all matched exactly (a queue'
 | `handStepsHold` | the cloud, automatically | the PR touches a path the queue configuration excludes (schema or migration paths, typically), so a person has to merge it by hand. |
 | `preview` | a human | "deploy me a preview and hold the merge until I have looked". Removing the label is the approval. |
 
-The mirror does not carry PR labels or reactions, so your key cannot read which holds a PR carries or whether the reviewer reacted; the scripts say so by name. GitHub's own page, or the tenant's settings, is where those live.
+The mirror does not carry PR labels or reactions, so your key cannot read which holds a PR carries or whether the reviewer reacted; the scripts say so by name. GitHub's own page, or the account's settings, is where those live.
 
 ## The queue is optional and opt-out