dsh-pstack 0.1.0 → 0.2.0-beta.3

package/{assets → dist/pstack}/skills/reflect/references/synthesizer.md

@@ -14,7 +14,7 @@ Apply each criterion to every finding:
 
 - Durability: still true in 6 months once paths, SHAs, tool versions, and code shapes have changed.
 - Specificity: broad enough to apply across tasks, precise enough that a future agent recognizes when to use it. Reject vague platitudes ("write good code") and hyper-specific facts ("`<specific-skill-name>` has 175 tokens at limit 80").
-- Existing-skill-first: propose `new skill via authoring-a-skill:` only when no existing skill is a real home, the pattern recurs, and the topic deserves its own skill.
+- Existing-skill-first: propose `new skill via create-skill:` only when no existing skill is a real home, the pattern recurs, and the topic deserves its own skill.
 - Convergence: findings echoed by 2+ reviewers carry higher confidence. Singletons must clear a higher bar on the other criteria.
 - Decision-changing: a future agent does something different because of the edit, not just reads more text.
 - Structural-mechanism check: route to Backlog when a lint rule, script, metadata flag, or runtime check already enforces the rule or could enforce it cheaply. Skill prose is for things mechanisms cannot enforce.
@@ -25,7 +25,7 @@ Drop (implementation details that drift):
 - "linter at SHA `bd91aa7` uses chars/4 heuristic"
 - "`<specific-skill-name>` has 175 tokens at limit 80"
 - "Bugbot flagged regex backtracking on May 2"
-- "we renamed a model constant in `encodingForModel`"
+- "we renamed `gpt-4` to `gpt-4o` in `encodingForModel`"
 
 Keep (durable patterns):
 - "closed regex enums for trigger detection are brittle. Prefer schema-validated structures"
@@ -41,7 +41,7 @@ Output exactly the format below. No preamble, no narration. One sentence per cel
 |---|---|---|
 | <failure mode in a skill the parent used> | <change to that skill's body> | <skill path + section> |
 | <skill existed but didn't trigger> | <tune the skill's description so it fires next time> | <tune description: <skill path>> |
-| <new pattern, no existing skill is a real home> | <draft a new skill via authoring-a-skill> | <new skill via authoring-a-skill: <kebab-name>> |
+| <new pattern, no existing skill is a real home> | <draft a new skill via create-skill> | <new skill via create-skill: <kebab-name>> |
 
 One row per finding. The user approves row by row.
 

package/dist/{assets → pstack}/skills/reflect/references/tooling-reviewer.md

@@ -28,7 +28,7 @@ Scan for:
 
 ## Scope to skills and tools the session actually used
 
-Route findings only to skills, tools, or MCPs this transcript used. A skill counts as used when the transcript shows a `read` of its `SKILL.md` (under `.dsh/skills/`, `~/.dsh/skills/`, or `~/.dsh/plugins/`), a `pstack_subagent` prompt naming its path, or a tool call (`bash`, `grep`, MCP, etc.) matching its documented commands. Speculative routings to skills the parent never opened do not count.
+Route findings only to skills, tools, or MCPs this transcript used. A skill counts as used when the transcript shows a `Read` of its `SKILL.md` (under `.cursor/skills/`, `~/.cursor/skills/`, or `~/.cursor/plugins/`), a `Task` prompt naming its path, or a tool call (Shell, Grep, MCP, etc.) matching its documented commands. Speculative routings to skills the parent never opened do not count.
 
 Two finding shapes are valid:
 - The parent invoked the skill and you found a real gap in its body. Route to the skill's relevant section.

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

@@ -0,0 +1,80 @@
+---
+name: setup-pstack
+description: Configure which models pstack uses per role and at what reasoning budget. Detects your available models and writes an always-applied rule that overrides the skill defaults. Use for /setup-pstack, "configure pstack models", "pstack budget", or changing pstack's model choices.
+---
+
+# Setup pstack
+
+In DeepSeek Harness, read [the DSH adapter](../../docs/harness/dsh.md) once per session before you follow this skill. It maps the Cursor names in pstack skills to DeepSeek Harness.
+
+Write `~/.cursor/rules/pstack-models.mdc`, an always-applied rule that sets pstack's model per role.
+
+## Steps
+
+### 1. Detect available models
+
+Enumerate the model slugs you can pass to a `Task` subagent in this session. That is the dependable source. If Cursor also exposes a models API or CLI that lists the user's entitled models, prefer it for completeness. If you cannot detect any, ask the user to paste the slugs they have access to. Never write a real slug you have not confirmed is available. The aliases `inherit-parent` and `auto` are always valid even though they are not detected slugs.
+
+### 2. Load current state
+
+The default role-to-model mapping is the rule shape shown in step 5 below. If `~/.cursor/rules/pstack-models.mdc` already exists, read it and treat its `# budget` line and its role values as the current choices. 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.
+
+### 3. Budget, map, and confirm
+
+**(a) Ask for a budget.** Prefer AskQuestion over free text. Offer these four options with these exact labels, and name the current budget when the rule records one. With no rule, say that `large` 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 skill defaults, and on a re-run keep any role you changed by family, list, or alias (`inherit-parent`, `auto`). `unlimited`, `large`, `medium`, and `small` set the effort token of every real slug, panel entries included, to `max`, `xhigh`, `high`, or `medium`. The effort token is the last token, or the one before a trailing `fast`, on the ladder `max` > `xhigh` > `high` > `medium` > `low`. If the result is not a detected slug, use the same family's detected slug with the highest effort at or below the target, else mark the role as needing a choice. `inherit-parent` and `auto` do not change. So `unlimited` turns `claude-opus-5-5-xhigh` into `claude-opus-5-5-max`. Grok slugs top out at `xhigh`, so under `unlimited` the fallback puts Grok at `xhigh` and keeps `grok-4.7-xhigh-fast` as it is. `large` keeps both defaults. `small` turns them into `claude-opus-5-5-medium` and `grok-4.7-medium-fast`.
+
+**(c) Show the roles and confirm.** Show every role with its model, marking any real slug 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 models plus `inherit-parent` and `auto` (both mean: this role runs on the parent chat model, which is how Auto users stay on Auto) as the options. Prefer AskQuestion over free text. 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. `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, in list order, so order it by preference. An `inherit-parent` or `auto` value never judges. `swarm workers` is the default model for every worker unless a race or comparison assigns another model per arm.
+
+### 4. Validate
+
+Every real slug written must be in the detected set. `inherit-parent` and `auto` always pass. If a chosen real slug is not available, stop and ask again.
+
+### 5. Write the rule
+
+Write `~/.cursor/rules/pstack-models.mdc` with `alwaysApply: true`, a `# budget` line with the chosen label and its target effort, and one line per role, using the same labels poteto-mode uses. Overwrite the whole file so re-runs stay idempotent. Shape:
+
+```
+---
+description: pstack per-role model choices (overrides skill defaults)
+alwaysApply: true
+---
+# pstack model configuration. One line per role. Delete a line to fall back to the skill default.
+# `inherit-parent` or `auto` as a value: the role runs on the parent chat model (omit Task `model`). Alias entries in a panel list still count toward its fan-out.
+# budget: large (xhigh)
+feature, refactoring: grok-4.7-xhigh-fast
+bug-fix: grok-4.7-xhigh-fast
+perf-issue: grok-4.7-xhigh-fast
+hillclimb: grok-4.7-xhigh-fast
+judgment and prose: claude-opus-5-5-xhigh
+hardest tasks: claude-opus-5-5-xhigh
+how explorer: grok-4.7-xhigh-fast
+how explainer: claude-opus-5-5-xhigh
+why investigators: grok-4.7-xhigh-fast
+why synthesizer: claude-opus-5-5-xhigh
+reflect tooling: grok-4.7-xhigh-fast
+reflect judgment, divergent, synthesizer: claude-opus-5-5-xhigh
+arena runners: claude-opus-5-5-xhigh, grok-4.7-xhigh-fast
+arena cross-judge pool: claude-opus-5-5-xhigh, grok-4.7-xhigh-fast
+swarm workers: grok-4.7-xhigh-fast
+architect runners: claude-opus-5-5-xhigh, grok-4.7-xhigh-fast
+interrogate reviewers: claude-opus-5-5-xhigh, grok-4.7-xhigh-fast
+```
+
+### 6. Confirm
+
+Tell the user the rule 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, invoke `/create-verification-skill` (resolves wherever pstack is installed: workspace, user, or plugin). 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, invoke `/create-formal-verification-skill` (resolves wherever pstack is installed: workspace, user, or plugin). On no, move on without pushing.

package/{assets → dist/pstack}/skills/sharpen/SKILL.md

@@ -1,11 +1,9 @@
 ---
 name: sharpen
-description: Make a task deeper, not bigger, then rewrite the prompt. Use for /sharpen.
+description: "Make a task deeper, not bigger, then rewrite the prompt. Use for /sharpen."
 disable-model-invocation: true
 ---
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
 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.

package/{assets → dist/pstack}/skills/show-me-your-work/SKILL.md

@@ -4,10 +4,10 @@ description: "Keep a reviewable decision trail for long-running or unattended wo
 disable-model-invocation: true
 ---
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
 # Show me your work
 
+In DeepSeek Harness, read [the DSH adapter](../../docs/harness/dsh.md) once per session before you follow this skill. It maps the Cursor names in pstack skills to DeepSeek Harness.
+
 Keep one canonical log.
 
 ## The format
@@ -56,7 +56,7 @@ Commit it only when the work is ambitious enough that a reviewer needs the trail
 
 ## 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 session log under `$DSH_HOME/sessions/<workspace-slug>/<session-id>/`. The system prompt names the workspace. Do not scan other workspace directories. Walk this run's rows against what actually happened. Each stretch 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:
+At the end of the run, before handing back, check the log told the truth. Read this run's transcript under the active workspace's `agent-transcripts/` directory (the system prompt names the path). Don't glob across `~/.cursor/projects/*/`. 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.

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

@@ -0,0 +1,106 @@
+import { appendFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+// runtime/skills/show-me-your-work/scripts/log.ts
+/**
+* Append one well-formed row to a show-me-your-work decision log (TSV).
+*
+* A Node replacement for the upstream `scripts/log.sh`. The observable rules are
+* the shell script's, because `skills/show-me-your-work/SKILL.md` tells the model
+* to read this file in a spreadsheet:
+*
+* - The header is written once, and only when the file is missing or empty.
+* - Rows are appended, never rewritten. A network mount can make the emptiness
+*   test lie for a file that exists, and the cost is one stray header line, not
+*   the rows.
+* - Tabs, CRs, and LFs inside a cell become spaces, so a cell always stays on one
+*   line and a row always has exactly six columns.
+* - A cell starting with `=`, `+`, `-`, or `@` gets one leading quote. Evidence
+*   is attacker-controlled (PR titles, filenames, generated text), and a
+*   spreadsheet parses those four characters as a formula.
+* - The row ends with a newline.
+*
+* No shell, no `date` process, and no `tr`/`printf` semantics to reproduce.
+*/
+/** The exact header line, including its trailing newline. */
+const HEADER = "ts	phase	decision	why	evidence	result\n";
+/**
+* Usage text.
+*
+* The shell script printed `log.sh` here because that was its own name. The
+* shipped file is `log.mjs`, and an error that tells the reader to run a script
+* this package no longer contains is worse than one that names the real path. The
+* exit code and the stream are unchanged.
+*/
+const USAGE = "usage: log.mjs <logfile> <phase> <decision> <why> <evidence> <result>\n";
+/** Formula-leading characters a spreadsheet would evaluate. */
+const FORMULA_PREFIXES = [
+	"=",
+	"+",
+	"-",
+	"@"
+];
+/**
+* One cell as the spreadsheet sees it.
+*
+* Exported because the skill's own contract is worth a unit test: the rules are
+* about what lands in a cell, not about how a row is assembled.
+*/
+function cleanCell(value) {
+	const flat = value.replaceAll(/[\t\n\r]/g, " ");
+	return FORMULA_PREFIXES.some((prefix) => flat.startsWith(prefix)) ? `'${flat}` : flat;
+}
+/** `YYYY-MM-DDTHH:MM:SSZ`, the format `date -u +%Y-%m-%dT%H:%M:%SZ` prints. */
+function timestamp(now = /* @__PURE__ */ new Date()) {
+	return now.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** Read whether a file is missing or empty, treating any read failure as empty. */
+function isEmptyOrMissing(logfile) {
+	if (!existsSync(logfile)) return true;
+	try {
+		return statSync(logfile).size === 0;
+	} catch {
+		return true;
+	}
+}
+/**
+* Append one row.
+*
+* @param logfile - target TSV; its parent directories are created as needed.
+* @param cells - exactly five cell values: phase, decision, why, evidence, result.
+* @param now - injectable clock, so the timestamp format is testable.
+* @returns the row written, without re-reading the file.
+* @throws {TypeError} when `cells` does not hold exactly five values.
+*/
+function appendDecisionRow(logfile, cells, now = /* @__PURE__ */ new Date()) {
+	if (cells.length !== 5) throw new TypeError(`expected 5 cells after the logfile, received ${cells.length}`);
+	const absolute = resolve(logfile);
+	const directory = dirname(absolute);
+	if (directory !== "" && !existsSync(directory)) mkdirSync(directory, { recursive: true });
+	if (isEmptyOrMissing(absolute)) appendFileSync(absolute, HEADER);
+	const row = `${[timestamp(now), ...cells.map(cleanCell)].join("	")}\n`;
+	appendFileSync(absolute, row);
+	return row;
+}
+/** Run the CLI. Returns the process exit code. */
+function main(argv, io = {
+	stdout: (value) => process.stdout.write(value),
+	stderr: (value) => process.stderr.write(value)
+}) {
+	if (argv.length !== 6) {
+		io.stderr(USAGE);
+		return 1;
+	}
+	const [logfile, ...cells] = argv;
+	try {
+		appendDecisionRow(logfile, cells);
+		return 0;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		io.stderr(`log.mjs: ${message}\n`);
+		return 1;
+	}
+}
+const entryPoint = process.argv[1];
+if (entryPoint !== void 0 && resolve(entryPoint) === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2));
+export { HEADER, USAGE, appendDecisionRow, cleanCell, main, timestamp };

package/dist/pstack/skills/show-me-your-work/scripts/log.test.mjs

@@ -0,0 +1,56 @@
+import { expect } from "../../poteto-mode/scripts/expect.mjs";
+import "../../poteto-mode/scripts/support.mjs";
+import { HEADER, appendDecisionRow, cleanCell, main, timestamp } from "./log.mjs";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+// runtime/skills/show-me-your-work/scripts/log.test.ts
+test("writes the header once and appends a clean row", () => {
+	const directory = mkdtempSync(join(tmpdir(), "pstack-log-"));
+	const file = join(directory, "nested", "decisions.tsv");
+	try {
+		appendDecisionRow(file, [
+			"build",
+			"=cmd",
+			"why	here",
+			"ev\nidence",
+			"@result"
+		], /* @__PURE__ */ new Date("2026-10-28T10:00:00.123Z"));
+		appendDecisionRow(file, [
+			"build",
+			"second",
+			"why",
+			"evidence",
+			"result"
+		], /* @__PURE__ */ new Date("2026-10-28T10:00:01Z"));
+		const lines = readFileSync(file, "utf8").split("\n");
+		expect(lines[0]).toBe(HEADER.trimEnd());
+		expect(lines[1]).toBe("2026-10-28T10:00:00Z	build	'=cmd	why here	ev idence	'@result");
+		expect(lines[2]).toBe("2026-10-28T10:00:01Z	build	second	why	evidence	result");
+		expect(lines.filter((line) => line === HEADER.trimEnd())).toHaveLength(1);
+	} finally {
+		rmSync(directory, {
+			recursive: true,
+			force: true
+		});
+	}
+});
+test("cleans spreadsheet-sensitive cells and stamps UTC", () => {
+	expect(cleanCell("=SUM(A1)")).toBe("'=SUM(A1)");
+	expect(cleanCell("+1")).toBe("'+1");
+	expect(cleanCell("-1")).toBe("'-1");
+	expect(cleanCell("@x")).toBe("'@x");
+	expect(cleanCell("plain")).toBe("plain");
+	expect(timestamp(/* @__PURE__ */ new Date("2026-10-28T10:00:00.999Z"))).toBe("2026-10-28T10:00:00Z");
+});
+test("usage errors exit 1", () => {
+	const errors = [];
+	const code = main([], {
+		stdout: () => {},
+		stderr: (value) => errors.push(value)
+	});
+	expect(code).toBe(1);
+	expect(errors.join("")).toContain("usage: log.mjs");
+});
+export {};

package/dist/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/dist/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/dist/pstack/skills/statechart/scripts/backends/cfg.mjs

@@ -0,0 +1,31 @@
+import { RERUN_STATES } from "../ir.mjs";
+// runtime/skills/statechart/scripts/backends/cfg.ts
+function configText(sections, extra) {
+	const lines = [];
+	for (const s of sections) lines.push(`${s.key} ${s.tokens.join(" ")}`);
+	lines.push(...extra);
+	return lines.join("\n");
+}
+const boundRun = (module) => [
+	`---- MODULE ChartBound ----`,
+	`EXTENDS ${module}`,
+	`ChartTLC == INSTANCE TLC`,
+	`ChartNaturals == INSTANCE Naturals`,
+	`ChartBound == ChartNaturals!<(ChartTLC!TLCGet("distinct"), ${RERUN_STATES})`,
+	`====`
+].join("\n");
+function chartRun({ module, variables, invariants }, tag) {
+	const every = [];
+	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"), 500)`,
+		`ChartBroken == ${every.join("")}{}`,
+		`ChartMark == ChartBroken = {} \\/ ChartTLC!PrintT(<<"${tag}", <<${variables.join(", ")}>>, ChartBroken>>)`,
+		`====`
+	].join("\n");
+}
+export { boundRun, chartRun, configText };