Skip to content

docs(statechart): use upstream's report wording everywhere - #30

Merged
Jrecos merged 1 commit into
mainfrom
docs/statechart-upstream-wording
Nov 1, 2026
Merged

Jrecos merged 1 commit into
mainfrom
docs/statechart-upstream-wording

Conversation

@Jrecos

@Jrecos Jrecos commented Nov 1, 2026

Copy link
Copy Markdown
Owner

Why

/statechart should read and work exactly like Lauren Tan's 0.15.36 skill. PR #29 restored the skill, but four other pages still described its report in the port's words. This PR uses upstream's sentences on all four.

What changed

  • docs/guide/06-verify-and-ship.md, create-formal-verification-skill, and the poteto-help route now use upstream's statechart sentence verbatim.
  • The README table row says the skill marks each state that breaks a rule and gives the shortest path to it.
  • The adaptation reasons in upstream.json match the files again.

Scope

  • Statechart sentences only. The OMP path and placement adaptations in those files stay.

Blast Radius

Docs and help text only. No code, test, or dependency changes.

Verification

  • bun run check:content and bun run typecheck pass.
  • A v1.9.1 run on a model with a broken invariant printed "The shortest path has 3 steps", which matches the restored wording.

Three docs and the help router still described the statechart report in
the port's words. Use upstream 0.15.36's sentences, so every page says
what the restored skill says. The skill reports the shortest path to each
state that breaks a rule.

The adaptation reasons in upstream.json no longer claim the wording fix,
and the README reason describes the byte-for-byte skill.
@Jrecos

Jrecos commented Nov 1, 2026

Copy link
Copy Markdown
Owner Author

Verdict: PASS+NOTES

Head e7696e5, base 5082e8b. Independent review from a detached worktree (bun install --frozen-lockfile clean).

Check 1. Byte parity with upstream. PASS.
docs/guide/06-verify-and-ship.md:126, skills/create-formal-verification-skill/SKILL.md:35, and skills/poteto-help/SKILL.md:86 are cmp-equal to the same statechart paragraphs in pstack/ at pin 1ba91fc25c0977741dd0e267849e6234b037ed0a. Set-difference of the divergence lines against upstream removes exactly those three lines and adds none. git diff 5082e8b e7696e5 is 8 insertions and 8 deletions over 5 files, every one a statechart sentence or an upstream.json reason line.

Check 2. Sentence fact-check. PASS+NOTES, four CONFIRMED, one WRONG.

  • docs/guide/06-verify-and-ship.md:126 "The chart marks each state that breaks a rule, and the report gives the shortest path to it in the reader's words." CONFIRMED. Marks at skills/statechart/SKILL.md:64, shortest path at skills/statechart/scripts/backends/report.ts:136, reader words from view labels built in skills/statechart/scripts/passes/label.ts:243-256. Caveat, rules left unchecked after the 100,000-state rerun bound are not marked (SKILL.md:69).
  • create-formal-verification-skill/SKILL.md:35, first sentence, "each invariant violation ... as its shortest path in plain words." CONFIRMED for invariants (report.ts:136). Narrower than the code, which also reports deadlock paths (report.ts:136) and property counterexamples (report.ts:135, report.ts:153).
  • create-formal-verification-skill/SKILL.md:35, second sentence, "When the check passes, /statechart draws a chart of how the system moves between states." WRONG as written. SKILL.md:74 states that above the 500-state budget a passing check writes no chart.mmd. Chart construction is gated on judged.states.distinct <= CHART_STATES at skills/statechart/scripts/run.ts:412, with CHART_STATES = 500 at skills/statechart/scripts/ir.ts:139, and pipeline.ts writes chart.mmd only when a chart exists. The base text carried that qualifier and this PR drops it.
  • skills/poteto-help/SKILL.md:86 CONFIRMED (SKILL.md:3, SKILL.md:64, report.ts:136).
  • README.md:201 CONFIRMED (SKILL.md:3, SKILL.md:64, report.ts:136). Meaning now matches upstream README.md:157 while keeping this table's sentence style.

Check 3. Adaptation reasons still describe real divergence. PASS+NOTES.

  • README.md reason CONFIRMED. Every named item is verifiable. All 407 files under skills/statechart are cmp-identical to upstream, so "shipped byte for byte" holds. The tsconfig.json root exclude is ["skills/statechart/scripts/**"]. Renderer installs happen at test time in skills/statechart/scripts/test/render.test.ts:39,42. fast-check is pinned 4.5.3 in package.json:34. NOTE, the rewrite drops the "offline TLA2TOOLS/JAVA alternative" item while that text is still live at README.md:356.
  • docs/guide/06-verify-and-ship.md reason CONFIRMED. Its only remaining divergence is the verify-skill placement line at :62, and dropping the statechart clause is correct. NOTE, the reason names .omp/skills/verify-<app>/ while the edited line also permits .agents/skills/. Pre-existing wording, not introduced here.
  • skills/poteto-help/SKILL.md reason CONFIRMED. Each retained item is still divergent, marketplace install :38, session-branch persistence :52, /setup-pstack :27 and :33, native tasks :46, OMP /loop :111, repository links :38. Dropping the statechart clause is correct because the row now equals upstream.
  • skills/create-formal-verification-skill/SKILL.md reason CONFIRMED. Retained item matches the divergence at :32, the placement link to omp-create-skill. Dropping the statechart clause is correct.

Check 4. Gate commands. PASS.
bun run check:content exit 0, output check-content: OK for 1138 inventory files, 59 skills. bun run typecheck exit 0, tsc --noEmit. Both invoked directly, no pipe.

Notes. The single WRONG sentence is upstream's own wording, and this PR's goal is exact upstream parity, so I do not block on it. Raise the 500-state qualifier upstream rather than diverging here. The same applies to the temporal-counterexample coverage this PR removes, which is real behavior at report.ts:135 and report.ts:153.

@Jrecos
Jrecos merged commit deee472 into main Nov 1, 2026
2 checks passed
github-actions Bot added a commit that referenced this pull request Nov 1, 2026
Cut from the merge of pull request #30 "docs(statechart): use upstream's report wording everywhere" (deee472).
Snapshots main at release time, so it can carry changes merged after that pull request.
@Jrecos
Jrecos deleted the docs/statechart-upstream-wording branch November 1, 2026 07:12
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