pi-t3-pstack 0.0.0-stage → 0.1.0

package/pstack/skills/setup-pstack/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: setup-pstack
+description: Configure which T3 provider and model pstack uses per role and at what reasoning budget. Detects the models T3 can run and writes the model sheet that overrides the skill defaults. Use for /setup-pstack, "configure pstack models", "pstack budget", or changing pstack's model choices.
+---
+
+# Setup pstack
+
+Write the model sheet, `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pstack/models.md` when that is set), one per machine. It sets pstack's T3 provider and model per role, and every pstack skill reads it before it dispatches.
+
+## Steps
+
+### 1. Detect available models
+
+Call `orchestrator_capabilities`, or `acp-mcp-call orchestrator_capabilities '{}'` where the T3 tools are not exposed. Its provider instances and their models are the dependable source. A target is valid only when its provider instance can run a child task and lists the model. Note each provider's own option IDs and values, such as `effort` on Claude and `reasoningEffort` on Codex and Grok. Never write a target you have not seen there. The aliases `inherit-parent` and `auto` are always valid.
+
+### 2. Load current state
+
+The default role-to-target mapping is the sheet shape in step 5 below. If the sheet already exists, read it and treat its `# budget` line and its role values as the current choices. If it does not, read `t3-pstack-models.md` in the host's config directory (`$CLAUDE_CONFIG_DIR` or `~/.claude` on Claude Code, `$CODEX_HOME` or `~/.codex` on Codex), where releases before 2.0.0-rc.3 kept the sheet, the same way. Otherwise start from those defaults. A line whose role is not in step 5, such as `how critics`, is from a retired role. Drop it. Carry a `strongest judgment` value over to `hardest tasks`, its new name. Also drop any value that is not a T3 entry, such as a bare family name, a `claude-` slug, or an `@<level>` suffix, and a `default effort` line.
+
+### 3. Budget, map, and confirm
+
+**(a) Ask for a budget.** Ask a structured multiple-choice question (`AskUserQuestion` on Claude Code, numbered options in plain text elsewhere). Offer these four options with these exact labels, and name the current budget when the sheet records one. With no sheet, say that `medium` matches the skill defaults.
+
+- `unlimited - max reasoning`
+- `large - xhigh reasoning`
+- `medium - high reasoning`
+- `small - medium reasoning`
+
+**(b) Apply it.** Build the working table from the defaults, and on a re-run keep any role you changed by provider, list, or alias (`inherit-parent`, `auto`). `unlimited`, `large`, and `small` set the reasoning option of every entry, panel entries included, to `max`, `xhigh`, or `medium`. `medium` writes no reasoning option, so `pstack_model` sets `low`, `medium`, or `high` from each job's complexity. Use the option ID that provider lists. If the provider does not offer that value, use its highest value at or below the target, else mark the role as needing a choice. So Grok, whose reasoning tops out at `xhigh`, stays at `xhigh` under `unlimited`. `inherit-parent` and `auto` do not change. Say when you offer `unlimited` or `large` that a sheet's `xhigh` or `max` still runs only when the user's latest message in that chat is "allow xhigh" (or "allow max"). Otherwise `delegate_task` refuses it, so those budgets mostly fall back to asking.
+
+**(c) Show the roles and confirm.** Show every role with its entry, marking any target not in the detected set as needing a choice. Also list each line step 2 dropped. Ask whether to accept as-is or change specific roles, offering the detected targets plus `inherit-parent` and `auto` (both mean: this role runs on the parent chat's model) as the options. For panel roles (`arena runners`, `architect runners`, `interrogate reviewers`) the value is a list, and one subagent runs per entry, alias entries included, so the list length sets the count. A panel needs at least two model families among its targets. A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `grok`. `arena cross-judge pool` is also a list, but Arena runs one judge. It tries only values from a family other than the parent's. Among those it tries first the ones whose model ran fewer candidates, and list order decides among values that ran as many, so order it by preference. An `inherit-parent` or `auto` value never judges. `swarm workers` is the default target for every worker unless a race or comparison assigns another per arm.
+
+**(d) Ask about the session-start hook.** Ask whether t3-pstack's session-start hook should keep telling new chats when to enter `/poteto-mode`. Write `session hook: on` or `session hook: off`.
+
+### 4. Validate
+
+Write the candidate to a temp file. Call `orchestrator_capabilities` again and save its result to a temp file as `{"providers": [...]}`, copying verbatim the entry of every provider instance the candidate or the defaults name. Run `node <plugin root>/skills/setup-pstack/scripts/t3-sheet.mjs <candidate> <catalog.json>`, where `<plugin root>` is the directory that holds this plugin's `skills/`, and fix every line it prints. If `node` is missing, check each entry against the catalog by reading, and say so. A role with no line runs on its default, so add a line for any role whose default this machine cannot run.
+
+### 5. Write the sheet
+
+Overwrite the sheet with the candidate, creating its directory and writing through any symlink at its path (resolve it with `realpath`). If a different file is already there, run the checker on it and ask before you replace it. Overwrite the whole file so re-runs stay idempotent. Then replace `t3-pstack-models.md` in the host's config directory with a link to the sheet (`ln -sf`), so an older t3-pstack reads the same sheet. Step 2 already read what it held. On Codex, remove any pstack model rows an earlier setup pasted into `<codex-home>/AGENTS.md`. With every default kept, the sheet reads:
+
+```markdown
+# pstack model configuration (T3). One line per role. Delete a line to fall back to the skill default.
+# With a job and size, pstack_model uses the routing table in models.json. `inherit-parent` or `auto` lets the table decide, or routes within the parent chat's family by complexity when no job is given. A named model is used as written.
+# budget: medium (low, medium, or high by job complexity)
+feature, refactoring: inherit-parent
+bug-fix: inherit-parent
+perf-issue: inherit-parent
+hillclimb: inherit-parent
+judgment and prose: inherit-parent
+hardest tasks: inherit-parent
+how explorer: inherit-parent
+how explainer: inherit-parent
+why investigators: inherit-parent
+why synthesizer: inherit-parent
+reflect tooling: inherit-parent
+reflect judgment, divergent, synthesizer: inherit-parent
+arena runners: claudeAgent/claude-opus-5-5, muse/muse-wonder-full-1.0, codex/gpt-6-astra
+arena cross-judge pool: claudeAgent/claude-opus-5-5, muse/muse-wonder-full-1.0, codex/gpt-6.1-sol
+swarm workers: inherit-parent
+architect runners: claudeAgent/claude-opus-5-5, muse/muse-wonder-full-1.0, codex/gpt-6-astra
+interrogate reviewers: claudeAgent/claude-opus-5-5, muse/muse-wonder-full-1.0, codex/gpt-6.1-sol
+session hook: on
+```
+
+### 6. Confirm
+
+Tell the user the sheet was written and that it applies to new sessions. Re-running this skill updates it.
+
+### 7. Offer a verification skill (optional)
+
+Check whether the project has a way to drive the real app for proof (a `verify-*` skill, or an existing harness). If not, offer once: "want a project-local verification skill, so agents can drive the app the way a user does and prove changes work? I can generate one with /create-verification-skill." On yes, read [`../create-verification-skill/SKILL.md`](../create-verification-skill/SKILL.md) from this file and follow it. Do not call the Skill tool for it, since that tool refuses a skill only the user may invoke. On no, move on without pushing.
+
+### 8. Offer a formal verification skill (optional)
+
+Check whether the project already has a formal verification skill (a project skill that runs a model checker, a proof, or another verifier against the code). If not, offer once: "want a formal verification skill, so agents can prove a key property of your code holds in every case in scope, not only the cases tests reach? I can generate one with /create-formal-verification-skill." On yes, read [`../create-formal-verification-skill/SKILL.md`](../create-formal-verification-skill/SKILL.md) from this file and follow it. Do not call the Skill tool for it, since that tool refuses a skill only the user may invoke. On no, move on without pushing.

package/pstack/skills/setup-pstack/scripts/read-sheet.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+# Decode the sheet once, before any consumer interprets its lines. PowerShell
+# 5.1 writes UTF-16LE; other writers may add a UTF-8 BOM or CRLF line endings.
+set -eu
+sheet=$1
+[ -f "$sheet" ] && [ -r "$sheet" ] || exit 1
+if [ "$(od -An -tx1 -N2 "$sheet" | tr -d ' ')" = fffe ]; then
+  text=$(iconv -f UTF-16LE -t UTF-8 "$sheet")
+else
+  text=$(cat "$sheet")
+fi
+bom=$(printf '\357\273\277')
+cr=$(printf '\r')
+printf '%s\n' "$text" | sed -e "1s/^$bom//" -e "s/$cr\$//"

package/pstack/skills/setup-pstack/scripts/t3-sheet.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// The T3 override sheet: one `<role>: <entry>` line per role, or a
+// comma-separated list for a panel role. An entry is
+// `<providerInstanceId>/<modelId>` plus `<optionId>=<value>` pairs, or
+// `inherit-parent` (alias `auto`). An entry maps one to one onto a
+// `delegate_task` target, so this file is the only place the grammar lives:
+// the generator checks the models.json tiers with it, and setup-pstack checks
+// a sheet against the live `orchestrator_capabilities` catalog with it.
+//
+//   node t3-sheet.mjs <sheet.md> <catalog.json>
+//
+// prints one line per problem and exits 1 when there is any.
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const INHERIT = ["inherit-parent", "auto"];
+const HOOK_VALUES = ["on", "off"];
+
+// Throws on a malformed entry; returns null for an inherit alias.
+export function parseEntry(text) {
+  const [target, ...pairs] = text.trim().split(/\s+/);
+  if (INHERIT.includes(target)) {
+    if (pairs.length) throw new Error(`"${text.trim()}": ${target} takes no options`);
+    return null;
+  }
+  const match = target.match(/^([A-Za-z0-9_-]+)\/([A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*)$/);
+  if (!match) throw new Error(`"${text.trim()}" does not start with <providerInstanceId>/<modelId>`);
+  const options = Object.create(null);
+  for (const pair of pairs) {
+    const option = pair.match(/^([A-Za-z0-9_]+)=([A-Za-z0-9._-]+)$/);
+    if (!option) throw new Error(`"${text.trim()}": "${pair}" is not <optionId>=<value>`);
+    if (option[1] in options) throw new Error(`"${text.trim()}" sets "${option[1]}" twice`);
+    options[option[1]] = option[2];
+  }
+  return { providerInstanceId: match[1], model: match[2], options };
+}
+
+// The family is the first segment (`claude`, `gpt`, `grok`) of the model ID's
+// last `/` part, so a Claude model served by a Codex-driver pool still counts as
+// Claude, and an OpenCode route prefix such as `openrouter/` decides nothing.
+export const family = (model) => model.split("/").pop().split("-")[0];
+
+// A panel's families among its concrete targets. An inherit entry does not
+// count: one sheet serves every thread on the machine, so its family depends on
+// the thread that dispatches.
+export function panelFamilies(entries) {
+  return new Set(entries.filter(Boolean).map((e) => family(e.model)));
+}
+
+// Every line but blank lines and `#` headings, as `{ line, key, value }`, with
+// no key or value when the line is not exactly `<key>: <value>`. setup-pstack
+// writes the sheet, so it holds no prose, and one strict rule leaves no shape a
+// misspelled role line can slip through.
+export function parseSheet(markdown) {
+  return markdown
+    .replace(/^\uFEFF/, "")
+    .split(/\r?\n/)
+    .flatMap((line, i) => {
+      if (line.trim() === "" || line.startsWith("#")) return [];
+      const match = line.match(/^([a-z][a-z ,-]*[a-z]): (\S(?:.*\S)?)$/);
+      return [{ line: i + 1, key: match?.[1], value: match?.[2] }];
+    });
+}
+
+// Problems with a parsed sheet, for the role vocabulary of models.json (each
+// role with its `tier`, and the `alias` a released sheet may still use), its
+// tier defaults, and an `orchestrator_capabilities` catalog. A role with no
+// line runs on its tier's default, so that default must dispatch here too.
+// With no catalog, as in the installer's doctor, only the grammar is checked.
+export function checkSheet(sheet, { roles, defaults, catalog }) {
+  const problems = [];
+  const byRole = new Map(roles.flatMap((r) => [[r.role, r], ...(r.alias ? [[r.alias, r]] : [])]));
+  const seen = new Set();
+  for (const { line, key, value } of sheet) {
+    if (!key) {
+      problems.push(`line ${line}: not a "<role>: <value>" line (lowercase role, one space after the colon, no indent or markup)`);
+      continue;
+    }
+    const canonical = byRole.get(key)?.role ?? key;
+    if (seen.has(canonical)) problems.push(`"${key}" appears twice; only one line may set it`);
+    seen.add(canonical);
+    if (key === "session hook") {
+      if (!HOOK_VALUES.includes(value)) problems.push(`session hook: "${value}" is not on or off`);
+      continue;
+    }
+    if (key === "default effort") {
+      problems.push("default effort: T3 entries carry their own options; delete this line");
+      continue;
+    }
+    const role = byRole.get(key);
+    if (!role) {
+      problems.push(`"${key}" is not a pstack role`);
+      continue;
+    }
+    const texts = value.split(",");
+    if (role.tier !== "panel" && texts.length > 1) problems.push(`${key}: takes one entry, not a list`);
+    const entries = [];
+    for (const text of texts) {
+      try {
+        entries.push(parseEntry(text));
+      } catch (err) {
+        problems.push(`${key}: ${err.message}`);
+      }
+    }
+    const runnable = [];
+    for (const entry of entries.filter(Boolean)) {
+      const found = checkTarget(entry, catalog);
+      problems.push(...found.map((p) => `${key}: ${p}`));
+      if (!found.length) runnable.push(entry);
+    }
+    const targets = texts.map((t) => t.trim()).filter((t) => !INHERIT.includes(t));
+    if (new Set(targets).size < targets.length) problems.push(`${key}: lists the same target twice`);
+    if (role.tier === "panel") {
+      const families = panelFamilies(runnable);
+      if (families.size < 2) {
+        problems.push(
+          `${key}: a panel needs at least two model families among its targets (inherit-parent does not count), got ${[...families].join(", ") || "none"}`,
+        );
+      }
+    }
+  }
+  for (const role of roles.filter((r) => !seen.has(r.role))) {
+    for (const entry of [defaults?.[role.tier] ?? []].flat()) {
+      problems.push(...checkTarget(parseEntry(entry), catalog).map((p) => `${role.role} (no line, tier default): ${p}`));
+    }
+  }
+  return problems;
+}
+
+function checkTarget({ providerInstanceId, model, options }, catalog) {
+  if (!catalog) return [];
+  const at = `${providerInstanceId}/${model}`;
+  const provider = catalog.providers.find((p) => p.providerInstanceId === providerInstanceId);
+  if (!provider) return [`${at}: no provider instance "${providerInstanceId}" in this T3`];
+  if (!provider.canRunChildTask || provider.canRunCrossProviderChildTask === false) {
+    const why = (provider.constraints ?? []).join(" ");
+    return [`${at}: "${providerInstanceId}" cannot run child tasks${why ? ` (${why})` : ""}`];
+  }
+  const listed = provider.models.find((m) => m.id === model);
+  if (!listed) return [`${at}: "${providerInstanceId}" does not list model "${model}"`];
+  const known = listed.options ?? [];
+  const problems = [];
+  for (const [id, value] of Object.entries(options)) {
+    const option = known.find((o) => o.id === id);
+    const allowed = option?.type === "boolean" ? ["true", "false"] : (option?.options ?? []).map((o) => o.id);
+    if (!option) problems.push(`${at}: no option "${id}" (has ${known.map((o) => o.id).join(", ") || "none"})`);
+    else if (!allowed.includes(value)) problems.push(`${at}: ${id}=${value} is not one of ${allowed.join(", ")}`);
+  }
+  return problems;
+}
+
+const invoked = process.argv[1] && existsSync(process.argv[1]) ? realpathSync(process.argv[1]) : null;
+if (invoked === fileURLToPath(import.meta.url)) {
+  const [sheetPath, catalogPath] = process.argv.slice(2);
+  if (!sheetPath || !catalogPath) {
+    console.error("usage: t3-sheet.mjs <sheet.md> <catalog.json>");
+    process.exit(2);
+  }
+  const { roles } = JSON.parse(readFileSync(new URL("../../../models.json", import.meta.url), "utf8"));
+  const problems = checkSheet(parseSheet(readFileSync(sheetPath, "utf8")), {
+    roles,
+    defaults: {},
+    catalog: JSON.parse(readFileSync(catalogPath, "utf8")),
+  });
+  for (const problem of problems) console.log(problem);
+  if (problems.length) process.exit(1);
+  console.log("ok: every role line parses and dispatches on this T3");
+}

package/pstack/skills/sharpen/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: sharpen
+description: "Make a task deeper, not bigger, then rewrite the prompt. Use for /sharpen."
+disable-model-invocation: true
+---
+
+I want a deeper version of this task, not a bigger one. Before rewriting it, do four things:
+
+1. Say what a top professional in this field would do here that I'm not asking for.
+2. Name the rawest material they would start from instead of what has already been digested for me.
+3. Name the specific methods and tools they would use.
+4. Say what, other than you or me, would show the result is right.
+
+Then rewrite my prompt to ask for exactly that.
+
+Leave choices that are mine to make open instead of deciding them.

package/pstack/skills/show-me-your-work/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: show-me-your-work
+description: "Keep a reviewable decision trail for long-running or unattended work: a TSV log with one row per decision (what, why, evidence, result). Local by default; commit it when a reviewer needs the trail to trust the result. Use for /show-me-your-work, autonomous or multi-phase runs, or work a human reviews after stepping away."
+disable-model-invocation: true
+---
+
+# Show me your work
+
+Keep one canonical log.
+
+## The format
+
+A single TSV file, one row per decision. Cells stay single-line. Evidence is a pointer, not prose.
+
+Copy `references/decision-log-template.tsv` (the header row) to start a clean log. Columns:
+
+- **ts.** ISO8601 timestamp.
+- **phase.** The phase or workstream.
+- **decision.** What was chosen or done, one line.
+- **why.** The reason in plain words. If a principle drove it, say it plainly, not as a jargon tag.
+- **evidence.** A link or path that proves it: commit SHA, PR number, `file:line`, or an artifact, trace, or screenshot path. Never a paragraph.
+- **result.** The outcome or predicate state: `tests green`, `reverted`, `pixel-diff 0`, `INCONCLUSIVE`, `open`.
+
+An example, plain-spoken so a reviewer reads it at a glance.
+
+```
+ts	phase	decision	why	evidence	result
+2026-05-24T09:02:00Z	frame	counted the work first, about 100 components and roughly 75 hours	wanted to know the size before starting a long run	commit 3a9f1c2	found 5 things to sort out before starting
+2026-05-24T09:40:00Z	harness	took screenshots of the old version before changing anything	so we can compare old against new and catch any visual change	scripts/snapshot.sh, baseline/	saved 120 reference screenshots
+2026-05-24T11:15:00Z	widget	moved the widget styles over without changing how it looks	keep the change small and the result identical	commit 7c21e0a, pixel-diff 0	looks identical, tests pass
+2026-05-24T12:30:00Z	widget	threw out a helper's work because its screenshots were blank	checked the real files instead of trusting its summary	worktree reset	reverted, tightened the instructions for next time
+```
+
+## Logging a row
+
+Write each entry the way you'd tell a teammate what you did. Plain words, concrete actions, no AI speak or abstract jargon (the **unslop** skill applies to log text too).
+
+Use the helper `scripts/log.sh <logfile> <phase> <decision> <why> <evidence> <result>`. It stamps `ts`, writes the header on first use, strips stray tabs/newlines, and prefixes any cell starting with `=`, `+`, `-`, or `@` with a single quote. A bare `printf` appending a row works too, but mind those same bytes if cells come from generated or user-supplied text.
+
+Log decision points and checkpoints, not every action: a fork chosen, a unit completed with its verification result, a pivot or revert with its trigger, a blocker surfaced, a gate fixed. For loop runs, one row per iteration. Skip the trivial and self-evident.
+
+A run is one agent conversation, including its later turns and any summary of it. A pickup, a replacement agent, or a new chat starts a new run. When a run adds to a log that already has rows, its first row has phase `start`, and so does its first row after another run's `start` row. So a run that comes back to a log in a later turn first reads the log's last rows to see whether another run wrote since. A `start` row names the `ts` range of the rows before it that this run did not write, and its evidence names this run, such as its agent id. Use phase `start` for nothing else.
+
+## Where it lives
+
+By default the log is a working artifact, not committed. Keep it at `decisions.tsv` in the work dir, or `.audit/<task-slug>.tsv` when several efforts run at once, and leave it out of git.
+
+Commit it only when the work is ambitious enough that a reviewer needs the trail to trust the result.
+
+## Rules
+
+- Append-only. A wrong call gets a new row that supersedes it. Never edit or delete history.
+- Prefer evidence produced by committed scripts over hand-made one-offs (the **encode-lessons-in-structure** principle skill).
+
+## Audit the log against the transcript
+
+At the end of the run, before handing back, check the log told the truth. Read this run's thread with `t3_thread_read` (`t3_thread_configuration` with no `threadId` returns its ID), and each child's thread by its `childThreadId`. Don't read other projects' threads. That reads unrelated private chats. Walk this run's rows against what actually happened. Each stretch of them begins at one of this run's `start` rows, or at the first row if this run created the log, and ends at the next `start` row of another run:
+
+- Check that every row maps to a real decision or action.
+- Check that each row's evidence resolves and shows what the row claims.
+- A fork, pivot, or abandoned approach that shaped the work but isn't logged is a gap. Add it.
+
+Correct the log, not the story. The audit never edits or removes a row, even an invented one. When a row records neither a real decision nor a real action, or its claim or evidence is wrong, add a row that supersedes it with what actually happened and a pointer that resolves. This audit does not check rows outside this run's stretches. If this run's own work shows one of them is wrong, supersede it like any wrong call.
+
+## Cross-model review of the trail
+
+Before handing back, spawn a subagent on a different model family from the one that did the work. Self-review is not a substitute. The subagent reads the audit trail and the run's transcript, then flags what the user should pay attention to. Not a redo of the work, a scan for what's suboptimal or risky. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill.
+
+- Decisions logged with weak or absent evidence.
+- Verification steps skipped or claimed without proof in the transcript.
+- Choices that look risky in hindsight (premature, scope-creeping, papering over a symptom).
+- Gaps the user would otherwise miss on a casual skim.
+
+Every reply for a run that produced a trail ends with an "Attention" section. Lead with the reviewer's model on its own line (`reviewed by <model>`), then list each flag pointing to specific rows or moments. "No flags" is a valid value. The model name is not.
+
+## Reviewing the trail
+
+Read top to bottom, follow the evidence pointers, spot-check. GitHub renders a committed TSV as a table. `column -s$'\t' -t decisions.tsv` renders it in a terminal.
+
+## Composing this skill
+
+Other skills route their audit trail here instead of inventing one. Reference it by name and let it own the format. Don't restate the columns.

package/pstack/skills/show-me-your-work/references/decision-log-template.tsv

@@ -0,0 +1 @@
+ts	phase	decision	why	evidence	result

package/pstack/skills/show-me-your-work/scripts/log.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Append a well-formed row to a show-me-your-work decision log (TSV).
+# Usage: log.sh <logfile> <phase> <decision> <why> <evidence> <result>
+set -euo pipefail
+
+if [ "$#" -ne 6 ]; then
+	printf 'usage: log.sh <logfile> <phase> <decision> <why> <evidence> <result>\n' >&2
+	exit 1
+fi
+
+logfile="$1"
+shift
+
+logdir="$(dirname "$logfile")"
+if [ -n "$logdir" ] && [ "$logdir" != "." ] && [ ! -d "$logdir" ]; then
+	mkdir -p "$logdir"
+fi
+
+# Use `>>` here, never `>`. A network mount can fail this test for a log
+# that exists. Then the cost is one stray header line, not the rows.
+if [ ! -s "$logfile" ]; then
+	printf 'ts\tphase\tdecision\twhy\tevidence\tresult\n' >> "$logfile"
+fi
+
+ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+# Strip tabs/newlines/CR so cells stay on one line, and prefix any cell
+# whose first char a spreadsheet would parse as a formula (=, +, -, @)
+# with a single quote. The skill expects this log to be read in
+# spreadsheets, so attacker-controlled evidence (PR titles, filenames,
+# generated text) must not become formula execution when a reviewer
+# opens the file.
+clean() {
+	local v
+	v=$(printf '%s' "$1" | tr '\t\n\r' '   ')
+	case "$v" in
+		=*|+*|-*|@*) printf "'%s" "$v" ;;
+		*) printf '%s' "$v" ;;
+	esac
+}
+printf '%s\t%s\t%s\t%s\t%s\t%s\n' \
+	"$ts" "$(clean "$1")" "$(clean "$2")" "$(clean "$3")" "$(clean "$4")" "$(clean "$5")" \
+	>> "$logfile"

package/pstack/skills/statechart/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: statechart
+description: "Check a TLA+ model of a system that moves between states, such as a product flow, a protocol, or a service, and draw it as a Mermaid statechart. The report gives the shortest path to each state that breaks a rule. Use for /statechart, or to show a bug as a path through states."
+disable-model-invocation: true
+---
+
+# Statechart
+
+The chart shows how a system moves between states, in the words of the person who reads it. That person, the reader, decides whether the behavior is right.
+
+## Run
+
+Work in a scratch folder outside the repo. Write a TLA+ spec and its config. Then run:
+
+```sh
+<skill dir>/scripts/statechart SPEC.tla [--config FILE] [--view FILE] [--out DIR]
+```
+
+`scripts/statechart.ts` is TypeScript, so run it with a runtime that can execute TypeScript.
+
+The first run installs TLC and Java with mise and needs the network.
+
+## Write the spec
+
+- Write each rule that the reader agrees to as an INVARIANT. A rule can be about a screen, a result, a stored value, or a message. If the model has no variable for a rule, add the variable. Never weaken a rule to make it hold.
+- Write `Next` as a disjunction of the actions, such as `YouPressPlay \/ YouPressStop`. If you do not, TLC names every step `Next`.
+- A state with no step out breaks `NoDeadlock`, also when it is a correct end state. When an INVARIANT or a PROPERTY already has that name, the rule is `CHECK_DEADLOCK`. Add to `Next` an action that is true only in the end states and changes nothing, such as `Done == phase \in {"paid", "failed"} /\ UNCHANGED vars`, and give it a label in `step()`.
+
+## Pick the chart
+
+You do the work that needs judgment: the words on each state and arrow, the phases and their colors, the title, and the report to the reader. Put your work in a view module, and give it with `--view`.
+
+To show the reader's words, the view exports `state(vars)`. The value that `state()` returns picks the form:
+
+- A string gives a flat chart: `export const state = (v) => (v.paid ? "Paid" : "Paying");`
+- An array gives parent states: `export const state = (v) => v.main.split(".");`
+- An object gives one parallel region for each key: `export const state = (v) => ({ Playback: v.playback, Volume: v.volume });`
+
+Label each state with what the reader can see or cares about, such as "Paying" or "Lease held, write pending". Keep variable names out of labels. In `vars`, a TLA+ sequence is an object with keys from 1, so `v.pc[1]` is `pc[1]`. A set is an array.
+
+The view can also export `step(action, from, to)`. It gets the TLC action name and the values before and after the step, and it returns the label of the arrow. Write each step label as the user sees it happen, such as "you press play" or "the connect fails". Do not name the code or the TLA+ action. Two actions that end the same in the chart get the same label, so that they share one arrow.
+
+When a step can occur only in some conditions, end its label with the condition in brackets, in the reader's words, such as `you press play [while the file loads]`. In a regions chart, the command writes the condition on the other regions on the arrow, in the words of their labels, such as `[when Offline]`. Your brackets replace it, and two arrows from one state can then look the same. So in a regions chart, do not write brackets for a condition on another region. When a value that no label shows decides where a step goes, name the result in the label, such as "the roster read fails".
+
+The view can also export these:
+
+- `group(vars)` returns the name of a phase. Each chart state gets the color of its group. When the model states behind one chart state are in different groups, that state gets no color.
+- `colors` gives each group name a color class.
+- `title` is a string that the chart shows at the top.
+
+The command calls `state()` and `group()` at most once for each model state, and `step()` at most once for each step. The chart and the report both use those answers. So make each function depend only on its arguments.
+
+The chart does not draw a step that stays in one label. Split a label when the reader must see such a step.
+
+Aim for about 20 arrows or fewer, because a busier chart is hard to read. First return coarser labels from `state()`. Give one label to values that act the same, and leave out a detail that the reader does not need, such as a call in flight whose return changes nothing. Keep each state of a bug path, and keep each mark. When a merge changes a `breaks` state to `mayBreak`, it hides where a rule breaks. Do not merge two states that break different rules, because the reader then cannot see which rule breaks where. If the chart is still too busy, return `null` from `step()` for the steps that the reader does not need, such as a reset that every state has, or a step whose arrow repeats what other arrows show. Obey these rules when you hide steps:
+
+- Keep each chart state reachable by arrows from a start state.
+- Keep at least one arrow out of each chart state that has a step out in the model.
+- Hide all the steps of an arrow, or none of them. When you hide only some, its condition gets narrower.
+- In the hand-off, say which steps the chart hides.
+
+## Read the report
+
+- In the chart, a state that breaks a rule has the class `breaks`. When only some model states behind it break the rule, it has the class `mayBreak`. The Legend names the rules of each mark. When two rules break, it names both on one mark, so say in the hand-off which state breaks which rule. In a regions chart, a state gets a mark when each combination of region states that includes it can break a rule. When a combination can break a rule and none of its states has a mark, each state in that combination gets a mark.
+- TLC goes past a state that breaks a rule, so the chart shows the states after a bug.
+- Because TLC goes past bugs, a model with no limit on its states can run without end. Keep the constants small, or add a CONSTRAINT.
+- With a VIEW or a SYMMETRY, TLC counts states that it treats as the same as one state, and the chart draws that one state. An arrow can lead to it rather than to the state that the step reaches, and the report says so.
+- TLC checks the rules in each state past a CONSTRAINT or an ACTION_CONSTRAINT, but it does not explore that state or check it for deadlock. When TLC's shortest path for a rule ends in such a state, the chart draws that state, and the report gives that path. The chart does not draw the other states past the bound. A deadlock in such a state does not show. TLC also checks the rules after each step that an ACTION_CONSTRAINT excludes, also when it reaches the next state another way. When TLC's shortest path for a rule ends with such a step, the chart draws that step.
+- The command checks the rules with TLC on the config as written, with one worker. When a rule breaks, the command removes that rule and runs TLC again, until no rule breaks. After the first break, each run stops at 100,000 distinct states, so that a large model does not run without end. When a run reaches that bound or stops on an error, the report lists the rules that it did not check under "Rules not checked", and the chart does not mark them. A rule that is not checked can hold or break. To check it, remove the rules that break from the config, or make the model smaller. The bound adds a module that changes TLC's order of the variables, so for a property TLC can find a different counterexample than a run without the bound.
+- `tlc.out` is what TLC printed on the config as written. When the chart does not show the bug path of a rule that breaks, `tlc-RULE.out` is what TLC printed for the run that found it. When TLC repeats its first warning, plain TLC prints it twice, but `tlc.out` shows it once, because TLC leaves the second copy out of the output that this command reads. That happens only when Java runs with `-XX:+UseParallelGC`, since otherwise TLC's first warning is its advice to pass that flag, which it prints once.
+
+## Show the chart
+
+Show `chart.mmd` to the user as a `mermaid` code block. The chart has a budget of 500 states, counted by TLC on the config as written. Above that, the chart draws only the paths to the rules that break, and when no rule breaks, the command writes no `chart.mmd`. It still checks each rule, and the report gives the state count and each bug path. To see the whole graph, make the model smaller.
+
+Render charts with Pele. When the user asks for an image, or a chart is too large to read as text, follow `references/render.md`. Do not use a different renderer unless the user asks for it.
+
+## Hand off
+
+Give each chart and its Mermaid text to the person who must decide. Add one line for each bug: the rule, the reader's sentence for that rule, and the path as the report numbers it. Say what the model leaves out. Give the command that makes the files again, with a new `--out` folder.
+
+When the model describes code, replay each bug path against the real code, as a test or a live repro, one step for each action. If a bug does not occur, think that the model is wrong until you show that it is not.

package/pstack/skills/statechart/references/render.md

@@ -0,0 +1,93 @@
+# Render a chart
+
+Render each `.mmd` file that you show with the npm package `pele@1.9.0`, and give the user the SVG. Install Pele once, outside the repo. Write each SVG next to its `.mmd` file, with the same name. The API is at https://pele.run/api. Pass `{ limit: 1_000_000, outputLimit: 8_000_000, maxEdges: 10_000 }` as the options of `render`. Pele's defaults are smaller than a chart of 500 states can be. When Pele throws a `PeleError`, show the user the Mermaid text and the error.
+
+## Colors
+
+Pele ignores Mermaid `theme` and `themeVariables`. Set its `--pele-*` CSS variables on `.pele`. https://pele.run/theming lists them. The command gives each state the color class of its group, such as `class sN teal`. It marks each bad state with `class sN breaks` or `class sN mayBreak`, each state on the shortest path to a bug with `class sN bugPath`, and each state that a PROPERTY counterexample repeats forever with `class sN repeats`. Pele puts these classes on the state's node. Color the classes with CSS.
+
+The `.mmd` file has a `classDef` line for `breaks` and for `mayBreak`, so that any Mermaid viewer shows the bug marks. It has no `classDef` for the group colors, `bugPath`, or `repeats`. Pele writes each `classDef` color as a `style` attribute on the node, and a `style` attribute wins over a normal CSS rule. So the rules for the marks below use `!important`. Without it, a dark theme keeps the light mark colors. A bug mark sets the fill and the text, and `bugPath` and `repeats` set the border. Put the mark rules after the group colors, so that a mark shows over the group color.
+
+These colors are suggestions. They are the colors of the old skill. Put them in a `<style>` element at the start of each SVG. Each SVG then follows the light or dark setting of the viewer.
+
+```css
+.pele {
+  --pele-bg: #ffffff;
+  --pele-fg: #1c1c1c;
+  --pele-muted: #656565;
+  --pele-line: #808080;
+  --pele-surface: #fcfcfc;
+  --pele-surface-alt: #f1f1f1;
+  --pele-border: #c9c9c9;
+}
+.pele .blue rect { fill: #c3e0ff; }
+.pele .orange rect { fill: #f0d3bf; }
+.pele .purple rect { fill: #e3d5ff; }
+.pele .yellow rect { fill: #f0dcbf; }
+.pele .teal rect { fill: #bfe3df; }
+.pele .tan rect { fill: #e5d9ce; }
+.pele .pink rect { fill: #ffcbe6; }
+.pele .breaks rect {
+  fill: #ffecee !important;
+  stroke: #e72e3b !important;
+  stroke-width: 2.5px !important;
+}
+.pele .breaks text {
+  fill: #cd2834 !important;
+}
+.pele .mayBreak rect {
+  fill: #fff3e6 !important;
+  stroke: #e8730c !important;
+  stroke-width: 2.5px !important;
+}
+.pele .mayBreak text {
+  fill: #b85a06 !important;
+}
+.pele .bugPath rect {
+  stroke: #1680f3 !important;
+  stroke-width: 2.5px !important;
+}
+.pele .repeats rect {
+  stroke: #9b35d6 !important;
+  stroke-width: 2.5px !important;
+  stroke-dasharray: 6 3;
+}
+@media (prefers-color-scheme: dark) {
+  .pele {
+    --pele-bg: #1f1f1f;
+    --pele-fg: #f5f5f5;
+    --pele-muted: #acacac;
+    --pele-line: #939393;
+    --pele-surface: #121212;
+    --pele-surface-alt: #2c2c2c;
+    --pele-border: #4e4e4e;
+  }
+  .pele .blue rect { fill: #1b3857; }
+  .pele .orange rect { fill: #573117; }
+  .pele .purple rect { fill: #3c2e57; }
+  .pele .yellow rect { fill: #573d17; }
+  .pele .teal rect { fill: #174641; }
+  .pele .tan rect { fill: #3d3127; }
+  .pele .pink rect { fill: #57233e; }
+  .pele .breaks rect {
+    fill: #2e2021 !important;
+    stroke: #cf2b35 !important;
+  }
+  .pele .breaks text {
+    fill: #ff6463 !important;
+  }
+  .pele .mayBreak rect {
+    fill: #2e2619 !important;
+    stroke: #d0700f !important;
+  }
+  .pele .mayBreak text {
+    fill: #ffa257 !important;
+  }
+  .pele .bugPath rect {
+    stroke: #116dd2 !important;
+  }
+  .pele .repeats rect {
+    stroke: #9a3fcf !important;
+  }
+}
+```

package/pstack/skills/statechart/scripts/backends/cfg.ts

@@ -0,0 +1,33 @@
+import { CHART_STATES, type ConfigSection, RERUN_STATES, type Spec } from "../ir.ts";
+
+export function configText(sections: ConfigSection[], extra: string[]) {
+  const lines: string[] = [];
+  for (const s of sections) lines.push(`${s.key} ${s.tokens.join(" ")}`);
+  lines.push(...extra);
+  return lines.join("\n");
+}
+
+export const boundRun = (module: string) =>
+  [
+    `---- MODULE ChartBound ----`,
+    `EXTENDS ${module}`,
+    `ChartTLC == INSTANCE TLC`,
+    `ChartNaturals == INSTANCE Naturals`,
+    `ChartBound == ChartNaturals!<(ChartTLC!TLCGet("distinct"), ${RERUN_STATES})`,
+    `====`,
+  ].join("\n");
+
+export function chartRun({ module, variables, invariants }: Spec, tag: string) {
+  const every: string[] = [];
+  for (const name of invariants) every.push(`(IF ~${name} THEN {"${name}"} ELSE {}) \\cup `);
+  return [
+    `---- MODULE ChartRun ----`,
+    `EXTENDS ${module}`,
+    `ChartTLC == INSTANCE TLC`,
+    `ChartNaturals == INSTANCE Naturals`,
+    `ChartBudget == ChartNaturals!<=(ChartTLC!TLCGet("distinct"), ${CHART_STATES})`,
+    `ChartBroken == ${every.join("")}{}`,
+    `ChartMark == ChartBroken = {} \\/ ChartTLC!PrintT(<<"${tag}", <<${variables.join(", ")}>>, ChartBroken>>)`,
+    `====`,
+  ].join("\n");
+}