Skip to content

2.0.0-rc.17: Lauren's eb4db2b, a skill that draws a TLA+ model as a statechart a PM can read - #41

Merged
chhoumann merged 3 commits into
mainfrom
sync/eb4db2b
Oct 22, 2026
Merged

chhoumann merged 3 commits into
mainfrom
sync/eb4db2b

Conversation

@chhoumann

@chhoumann chhoumann commented Oct 22, 2026 •

Copy link
Copy Markdown
Owner

t3-pstack moves to Lauren Tan's pstack at cursor/plugins eb4db2b for all three components. Only pstack changed upstream, and its version moves to 0.15.30.

  • pstack #741 adds a new skill, statechart. It draws what an app's user sees as a Mermaid statechart generated from a TLA+ model, so a PM or a designer can judge the design without reading TLA+. TLC checks each rule the PM agrees to as an invariant. Each state is gray when it works, red when it is still wrong, and green when an open fix fixes it, and each class of counterexample is drawn as a numbered path. from-spec draws the chart, --fixed shows what an open fix changes, --against audits the code against an existing spec, and from-chart turns an agreed chart into a TLA+ skeleton and compares the two. poteto-help gains its row. Upstream's README row, guide page, harness copy, and version bump sit outside every synced component.

Unlike earlier syncs, this one brings Lauren's code, not only text. The skill is a 36-line SKILL.md plus about 6,000 lines of Node scripts (statechart.mjs, tlc-to-chart.mjs, chart-to-tla.mjs, compare-charts.mjs, lib.mjs), a bundled OutputFolder TLA+ model, and a 2,790-line node:test suite. All of it is byte-identical to upstream. No substitution, fork, or hook changed.

Commits

  1. Sync. bun tools/sync.mjs moves each component's pin from 88d4751 to eb4db2b, adds the 12 files under skills/statechart/, and adds poteto-help's row through existing substitutions. Each of the 12 files matches upstream's at eb4db2b under cmp, file modes included. The 15 declared forks were left alone. cursor-team-kit and thermos synced with no file changes.
  2. CI. A new Skill script tests job runs node --test plugins/pstack/skills/*/scripts/test/*.test.mjs on Node 20, the step #741 added to upstream's validate-plugins.yml, which the port does not sync. Node 20 is the version upstream uses and the oldest the installer accepts. actions/setup-node is pinned by SHA at v7.1.0. The runner has no TLC, so 31 of the 58 tests skip, as they do upstream.
  3. Release. VERSION and the manifests move to 2.0.0-rc.17. CHANGES gets the entry with its behavior-delta table. NOTICE, NOTICE-skills, poteto-mode's copy of the notice, and the README point at eb4db2b, the README's pinned installer command names the new tag, and its skill count moves from 64 to 65.

On T3

The skill and its scripts name no Cursor tool, .cursor/ path, model, cloud agent, or subagent, so no rule is needed. It keeps Lauren's disable-model-invocation: true. On Claude Code the user types /t3-pstack:statechart, and on Codex $t3-pstack:statechart. poteto-mode does not route to it, upstream or here.

The agent runs the scripts with node <skill dir>/scripts/statechart.mjs. They import only Node built-ins, and the installer already requires Node 20. They write only to the system temp folder and beside their input, never into the installed plugin folder. TLC comes from TLA2TOOLS and JAVA. Without TLA2TOOLS the scripts print where to download tla2tools.jar and exit 2. --png renders through npx -y @mermaid-js/mermaid-cli.

Each external call has a limit worth knowing.

  • In a Codex thread under the workspace-write sandbox, TLC cannot run. Its fingerprint set is an RMI object that listens on a local port, and the sandbox denies the listen (java.rmi.server.ExportException: Listen failed on port: 0, SocketException: Operation not permitted). The script exits 2 and keeps TLC's output. npx cannot reach the npm registry there either. In full access, or after the user approves an escalated run, both work. In TLC 1.7.4 every fingerprint set extends java.rmi.server.UnicastRemoteObject, so any TLC run in that sandbox fails this way, not only this skill's.
  • On Windows, spawnSync("npx", ...) without a shell should not find npx.cmd, so --png would print "could not render" and exit 2. This is inferred from how Node starts processes on Windows and was not run.
  • On macOS with TLC, two tests fail on their own assumptions, not the scripts'. One compares a /var temp path with Java's canonical /private/var form and passes once TMPDIR is the canonical path. The other fails renames with LD_PRELOAD, which macOS ignores. Both pass on Linux.

Checks

  • bun tools/sync.mjs <component> eb4db2b --dry-run for pstack, cursor-team-kit, and thermos after the sync exits 0 for each, with no undeclared fork, no denylist hit, and no unmatched substitution. pstack reads 132 unchanged files and the same 15 declared forks with 551 changed lines, and tools/forks.json is unchanged.
  • bun tools/generate.mjs --check reports 17 generated files current and passes the hooks freeze check.
  • GIT_CONFIG_GLOBAL=/dev/null bun test tests/ --timeout 30000 passes 550, skips 46, and fails 0.
  • The skill's tests on Node 24 without TLC pass 27 and skip 31. On Linux with Node 20.20.2, OpenJDK 17, and TLC 1.7.4, 57 pass and the PID-namespace test skips because Docker blocks unprivileged unshare. On macOS with Java 21 and TLC 1.7.4, 55 pass, 1 skips, and the 2 tests above fail.
  • markdownlint is clean on every changed file. actionlint 1.7.12 and zizmor 1.29.0 (pedantic) report nothing on ci.yml.
  • t3-sheet.mjs against this machine's sheet and catalog reports that every role line parses and dispatches.
  • T3_PSTACK_E2E=1 bun test tests/install-e2e.test.mjs with the real claude 2.1.308 and codex 0.163.0 CLIs passes 12 of 12.
  • In CI, Skill script tests ran on Node 20.20.2 and passed 27 of 58, with the 31 TLC tests skipped.
  • Install. tools/install.mjs install --source <this branch> into a throwaway HOME installs 2.0.0-rc.17 in Claude Code and Codex, and every check passes. claude plugin details t3-pstack@t3-pstack lists 65 skills, statechart among them, and Claude Code 2.1.308's session init lists t3-pstack:statechart. Codex 0.163.0's app-server skills/list returns 65 t3-pstack: skills, t3-pstack:statechart enabled.
  • End to end. statechart.mjs from-spec OutputFolder.tla --png on the bundled model, with TLC 1.7.4 and Java 21, finds that all five rules hold and draws a 19-state chart in two parallel regions from 4,294 model states. It writes chart.mmd, chart.png, stories.md, and summary.json and exits 0. Without TLA2TOOLS the same command prints the download hint and exits 2.

All three components move from 88d4751 to eb4db2b. Upstream changed only
pstack. A new skill, statechart, draws what an app's user sees as a
Mermaid statechart generated from a TLA+ model (pstack #741). TLC checks
each rule the reader agrees to as an invariant, each state is marked as
working, still wrong, or fixed by an open change, and each class of
counterexample is drawn as a numbered path. It also turns an agreed chart
into a TLA+ skeleton and compares a drawn chart with the agreed one. The
skill is a SKILL.md plus Node scripts (statechart.mjs, tlc-to-chart.mjs,
chart-to-tla.mjs, compare-charts.mjs, lib.mjs), a bundled OutputFolder
model, and a node:test suite. The scripts find TLC only through TLA2TOOLS
and JAVA and exit 2 without them, and --png renders through npx
@mermaid-js/mermaid-cli. poteto-help gains its row.

bun tools/sync.mjs added the skill and updated poteto-help cleanly. The
12 new files are byte-identical to upstream. The skill names no Cursor
tool, path, model, command, or subagent, so it takes no substitution and
keeps Lauren's disable-model-invocation flag. The 15 declared forks were
left alone, and cursor-team-kit and thermos synced with no file changes.
Upstream's pstack README, guide page, version bump, harness tree, and CI
step sit outside every synced component.
pstack #741 added a node --test step for the skills' own script tests to
upstream's validate-plugins.yml, which the port does not sync. A new Skill
script tests job runs the same command, node --test
plugins/pstack/skills/*/scripts/test/*.test.mjs, on Node 20, the version
upstream uses and the oldest the installer accepts. Today that is the
statechart suite. The runner has no TLC, so the 31 tests that need it
skip, as they do upstream. setup-node is pinned by SHA at v7.1.0 like
every other action here.
VERSION, the manifests, and package.json move to 2.0.0-rc.17. CHANGES.md
gets the entry with its behavior-delta table. NOTICE.md, NOTICE-skills.md,
poteto-mode's copy of the notice, and the README point at upstream
eb4db2b, the README's pinned installer command names the new tag, and its
skill count moves to 65 for statechart.
@chhoumann
chhoumann merged commit 987ccb4 into main Oct 22, 2026
13 checks passed
@chhoumann
chhoumann deleted the sync/eb4db2b branch October 22, 2026 09:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant