@olierjs/fugue-cli 0.1.0 → 0.1.2

package/README.md

@@ -13,7 +13,9 @@ fugue-cli guide
 
 后续更新执行同一条安装命令。包内提供 macOS、Linux、Windows 的 x64 和 arm64 二进制。
 
-安装脚本自动将包内 Skill 同步到 `~/.agents/skills`，包括薄入口 `fugue-stack` 和完整的 `plan-with-remote`。无需手动复制目录。替换同名旧 Skill 或清理本工具管理的过时 Skill 前，会先保存备份；其他 Skill 保持原样。备份放在 `~/.local/share/fugue-cli/backups`，位于技能发现目录之外。
+使用 nvm 管理 Node 时，先在当前终端执行 `nvm use 22.19.0` 或选择更高版本，再安装和运行。启动 Agent 的环境也需要能通过 `PATH` 找到 `fugue-cli`。
+
+安装脚本自动将包内 Skill 同步到 `~/.agents/skills`，包括薄入口 `fugue-stack`、远端规划 `plan-with-remote`、原版 `show-me`、原版 `statechart` 和可视化解释适配 `fugue-show-me`。无需手动复制目录。替换同名旧 Skill 或清理本工具管理的过时 Skill 前，会先保存备份；其他 Skill 保持原样。备份放在 `~/.local/share/fugue-cli/backups`，位于技能发现目录之外。
 
 自动同步通过 npm 的 `postinstall` 执行，需要允许安装脚本运行。清理发生在安装或升级时，针对新版已移除的受管理 Skill；`npm uninstall` 没有对应的自动清理钩子。
 
@@ -27,24 +29,72 @@ fugue-cli --help
 fugue-cli --version
 ```
 
+在目标项目中启动支持 Skill 的 Agent，描述要完成的工作，例如：
+
+```text
+$fugue-stack 根据这份已确认需求实现功能，完成后审查差异并验证。
+$fugue-stack 审查当前代码变更，列出有实际影响的问题。
+$fugue-show-me 用最小的结构图解释这次改动。
+$fugue-show-me 检查取消与重试交错时的状态变化，画出可能的缺陷路径。
+```
+
+`fugue-cli guide` 输出工作指南，编码、审查和解释由当前 Agent 按指南执行。若安装后暂时看不到新 Skill，可重新启动 Agent 后再选择入口。
+
 需求理解、规划和需求或方案解释继续由 `plan-with-remote` 及远端规划服务负责。指南提供规划技能的绝对路径；该技能的客户端需要 Git、已配置的规划服务，以及已在服务中登记的目标仓库，配置说明见 [configuration.md](skills/plan-with-remote/references/configuration.md)。
 
 编码、代码审查与验证、面向人的实现解释由当前 Agent 按指南完成。读取指南本身不会发起规划、修改项目或调用模型。远端规划返回的正式文档继续按 Markdown 原文保存，批准版本由规划客户端和服务端管理。
 
+## 上游技能
+
+`show-me` 完整目录原样引入自 [humanlayer/skills](https://github.com/humanlayer/skills/tree/653b6411c1f70c275a18e37673b042ff99f67ceb/plugins/show-me/skills/show-me)，保留原始说明和 Agent 调用配置。来源、固定提交和目录记录在 [upstream-skills.json](upstream-skills.json)，MIT 许可保留在 [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES)。
+
+`statechart` 完整目录原样引入自 [cursor/plugins 的 pstack](https://github.com/cursor/plugins/tree/99b609a72323b70204eab407c622f436e858e112/pstack/skills/statechart)，包括原始说明、脚本和测试。同样在来源记录中固定提交，并保留 MIT 许可。
+
+需要可视化解释时，总览路由到 [fugue-show-me](skills/fugue-show-me/SKILL.md)：由 `show-me` 选择通用表达形式，需要分析状态变化、检查行为规则或展示缺陷路径时配合 `statechart`。适配维护在独立目录中；更新上游时整体替换原版目录并更新来源记录。
+
+## 状态图依赖
+
+`statechart` 使用 Node.js 和 npm；模型检查还需要 [mise](https://mise.jdx.dev/getting-started.html)。macOS 可先安装：
+
+```sh
+brew install mise
+node ~/.agents/skills/statechart/scripts/statechart.mjs --help
+```
+
+首次模型检查由原版脚本通过 mise 安装 Java Temurin 25 和 TLC 1.7.4，需要联网下载约 305 MB。若使用已有环境，可按上游帮助设置 `JAVA` 和 `TLA2TOOLS`。首次 PNG 出图会将 `pele@1.8.0` 和 `@resvg/resvg-js@2.6.2` 安装到用户缓存目录；仅渲染现成 Mermaid 图时不运行 TLC。
+
+该版 TLC 无法解析模型字符串中的中文。模型使用 ASCII 标识符和字符串值，中文标签放在映射文件中，从模型生成中文状态图。
+
+输入和产物放在目标仓库之外的临时目录，按上游要求交付 PNG、Mermaid 源码、缺陷说明和再生成命令。模型检查结果与真实代码复现结果分别说明。
+
 ## 开发与发布
 
 开发与打包需要 Go >=1.23 和 Node >=22.19.0。
 
+验证尚未发布到 npm 的仓库版本时，在仓库根目录打包，再安装生成的本地包：
+
+```sh
+npm pack
+npm install -g ./olierjs-fugue-cli-0.1.2.tgz
+fugue-cli --version
+fugue-cli guide
+```
+
+本地包安装同样会运行 Skill 自动同步。`@latest` 使用 npm 上的已发布版本，本地包使用本次构建的仓库版本。
+
 ```sh
 go test ./...
 node --test tests/*.test.mjs
+node --test skills/statechart/scripts/test/statechart.test.mjs
 npm pack
 ```
 
+上游测试包含 Linux 的 `LD_PRELOAD` 故障注入，并对临时路径和英文 Java 诊断文本作精确断言；macOS 上需单独核对这些环境差异。
+
 `npm pack` 的 `prepack` 自动构建各平台二进制，并将版本写入命令。发布目标固定为 npmjs，包名为 `@olierjs/fugue-cli`。发布验收后的包：
 
 ```sh
-npm publish ./olierjs-fugue-cli-0.1.0.tgz --access public
+npm publish ./olierjs-fugue-cli-0.1.2.tgz --access public
 ```
 
 Go 命令入口位于 [cmd/fugue-cli](cmd/fugue-cli/main.go)，指南源码位于 [guide.md](internal/cli/guide.md)，入口技能位于 [SKILL.md](skills/fugue-stack/SKILL.md)。

package/THIRD_PARTY_NOTICES

@@ -1,4 +1,4 @@
-Third-party dependencies included in the compiled fugue-cli binaries.
+Third-party components distributed with fugue-cli.
 
 
 github.com/spf13/cobra v1.10.2
@@ -414,3 +414,54 @@ github.com/inconshreveable/mousetrap v1.1.0
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
+
+humanlayer/skills: show-me (653b6411c1f70c275a18e37673b042ff99f67ceb)
+https://github.com/humanlayer/skills/tree/653b6411c1f70c275a18e37673b042ff99f67ceb/plugins/show-me/skills/show-me
+
+MIT License
+
+Copyright (c) 2026 HumanLayer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+cursor/plugins: pstack statechart (99b609a72323b70204eab407c622f436e858e112)
+https://github.com/cursor/plugins/tree/99b609a72323b70204eab407c622f436e858e112/pstack/skills/statechart
+
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olierjs/fugue-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Fugue 需求交付工作指南与 Agent 技能",
   "type": "module",
   "bin": { "fugue-cli": "bin/fugue-cli.mjs" },
@@ -10,6 +10,7 @@
     "scripts/postinstall.mjs",
     "scripts/skills.mjs",
     "skills/",
+    "upstream-skills.json",
     "THIRD_PARTY_NOTICES"
   ],
   "engines": { "node": ">=22.19.0" },

package/skills/fugue-show-me/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: fugue-show-me
+description: 使用 show-me 和 statechart 可视化解释当前实现、代码变更、运行结果或状态变化；当用户需要图解、结构示意或缺陷路径时使用。
+---
+
+# 可视化解释
+
+先阅读并遵循[上游 show-me](../show-me/SKILL.md)，由它指导表达形式的选择。
+
+需要分析状态转换、并发、重试、取消、恢复或缺陷路径，并检查行为规则、对比修复时，阅读并遵循[上游 statechart](../statechart/SKILL.md)的建模、模型检查、出图与交付要求。用 `show-me` 解释整体结构，用 `statechart` 展示状态变化和缺陷路径，按当前问题需要组合。
+
+原版脚本安装的 TLC 使用 ASCII 模型标识符和字符串值，中文状态与步骤标签写在映射文件中，再从模型生成中文图示。
+
+说明使用用户的语言，依据当前源码、差异或已有材料，只展示本次问题需要的内容。
+
+将上游的 `Bash(open ...)` 对应为当前宿主可用的终端或文件预览工具，按实际操作系统打开 HTML 或图片。交付本地文件时提供绝对路径链接；仅在实际打开成功后说明已打开。

package/skills/show-me/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: show-me
+description: Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.
+disable-model-invocation: true
+---
+
+Help the user understand the current topic of conversation visually. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear.
+
+- Show logic or an algorithm as pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+- Show runtime control flow as a call tree:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+- Show UI structure as a component tree, including state and module boundaries that matter:
+
+```tsx
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+- Show file responsibility or a broad refactor as a shallow file tree:
+
+```text
+src/
+├── commands/       # parses user actions
+├── sessions/       # owns session state
+└── transport/      # sends API requests
+```
+
+- Show component interaction, control flow, or data flow with Mermaid:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+- Use `diff` when the point is what changes and the surrounding shape already exists. Match the diff shape to the topic.
+
+For a component change:
+
+```diff
+ <SessionPage>
+   useSessionEvents()
+   <SessionToolbar>
++    <RunSkillButton />
+   <SessionTimeline>
++    <SkillResultCard />
+```
+
+For a file-layout change:
+
+```diff
+ src/
+ ├── commands/
++│   └── show-me.ts       # expands the slash command
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+For a call-tree or call-stack change:
+
+```diff
+ submitForm
+   createSession
+     persistPrompt
++    expandSkillMention
+     launchAgent
+-  navigateToSession
++  navigateToSession
++    subscribeToEvents
+```
+
+For a state or control-flow change:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+- Show the whole block when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1)
+  return `use the ${skillName} skill`
+}
+```
+
+- For a visual UI, layout, state comparison, or concept too dense for Mermaid, write one focused HTML file — a diagram, an infographic, or a short slide deck, whichever fits the point. Match the product's colors, type, spacing, and components; use real labels and data; support desktop and mobile. Then open it for the user:
+
+```
+Bash(open path/to/show-me-{description}.html)
+```
+
+### guidance
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point.
+
+You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.

package/skills/show-me/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/skills/statechart/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: statechart
+description: "Draw how any system moves between states, such as a product flow, a protocol, or a service, as a Mermaid statechart from a TLA+ model. Each bug is a numbered path with blue borders to a state that breaks a rule. Use for /statechart, to show a bug as a path through states, or to turn an agreed chart into a TLA+ skeleton."
+disable-model-invocation: true
+---
+
+# Statechart
+
+The chart shows how a system moves between states, in the words of the person who reads it. The scripts call that person the reader, as in `readerActions` and reader steps. The reader decides whether the behavior is right. The reader can be a PM who reads a product flow, an engineer who reads a protocol or a service, or a reviewer who reads a design. Label each state with what the reader can observe or cares about, such as "Paying" in an app or "Lease held, write pending" in a lock service. Label each step with the event that moves the system, such as "tap Pay" in an app, "the request reads the count" in a service, or "the lease expires" in a lock service. Keep variable and action names out of labels.
+
+Run `node <skill dir>/scripts/statechart.mjs --help` for the commands and for how to read a chart. Work in a scratch folder outside the repo. The command writes its files next to its input. The first run installs TLC and Java with mise, which downloads about 305 MB and needs the network. The help's TLC section tells how to use a TLC and Java that you have.
+
+## Pick the direction
+
+Use `from-spec` when a TLA+ model exists, or when the code or design is concrete enough to model. Use `from-chart` when there is no model, and the people who own the behavior should agree on it before anyone builds or changes it.
+
+If the code already has a TLA+ spec, start from a copy of that spec. Add the variables that the labels and rules need, and keep the spec's existing invariants. To audit the code against that spec, make the copy model what the code does, and pass the spec unchanged as `--against`. Check it with the config that its authors say it passes, and pass that config as `--against-config` unless it has the spec's file name. One mapping labels both models, so label states and steps from variables that both have. A label that reads a variable that only the copy has must test `"name" in v` first, and label the spec's states another way. When a model describes code, tie every variable and action to code that a reviewer can open, and take its name from that code. Make each action one indivisible step in the code. Put the file and line of the code that checks each condition of an action in a comment on that condition, as in `\* pay.ts:120`.
+
+## Spec to chart
+
+1. Choose the chart's states. When the reader cares about something that a label would hide, put it in the label, such as "Paying, charged twice" when the screen still says "Paying" after a second charge. Start with few states. Split a state when the split separates two bugs, or when the reader must see a step that leaves the label the same, such as a request that reads a count, because the chart does not draw such a step.
+2. Write each rule that the reader agrees to as one invariant, with the reader's sentence as its comment. A rule can be about any state in the model: what a screen shows, what a request returns, a stored value, or a message between parts. When the model describes code, the rule also names the code that can change that state. If the model has no variable for what a rule is about, add the variable. Do not drop the rule. For a rule that applies once everything settles, define `Settled == ~ENABLED System`, where `System` is the disjunction of the actions that happen without the reader. For a rule that applies at a narrower point, such as after each request finishes, write a predicate for that point and make the rule hold where it is true. For a goal that the system must be able to reach, write a rule that says the goal never happens, and pass that rule with `--expect-broken`. The path that breaks it is then a way to the goal. The chart still draws the goal as a state that breaks a rule, and `stories.md` tells it as a bug, so name each goal rule in the hand-off. Report each other broken rule as a bug. Never weaken a rule to make the chart pass.
+3. Run `from-spec`, then fill in the mapping file it writes. Put the labels in `state` and `step`. When the chart must separate what the reader does from what happens around the reader, list the reader's actions in `readerActions` by action name. Leave the list empty when every action counts the same. When the overview is too large to read, add `--cover`. The overview then keeps only the shortest path to each settled state, plus every bug path, and the command lists what it leaves out. When two bugs end in the same state for different reasons, add `cause` and make it name each reason. To color the states by what the reader cares about, such as "Order shipped", return that group from `group`. The legend names the groups, and in the PNG a state that breaks a rule is red in place of its group color.
+4. If there is a proposed fix, model it and pass that model as `--fixed`.
+5. Render each chart with `--png` and look at every PNG. Check that each numbered path reads in order. If a label reads like code, fix `state` or `step` and run the command again.
+6. When the model describes code, replay each bug's story against the real code, as a test or a live repro, one step per model action. Drive only entry points that a user, a client, or another part of the system reaches, and assert only what they can observe. A test that asserts a flag that it sets, or that searches the source text, proves nothing. When a run proves part of the story and reading the code proves the rest, say which part each proves. When the test copies code that it cannot import, give the commit and line range of the copy, and list what the copy leaves out. If a bug does not reproduce, assume the model is wrong until you show otherwise. Fix the model, not the rule. For a design with no code yet, the TLC trace is the evidence, and the hand-off must say so.
+
+## Chart to spec
+
+1. Draw the chart that the reader agrees to. Use one region for each part that changes independently, such as a device's connection and the job that the device runs. Add one `%% never` line per rule, with the reader's sentence. Draw an event that stops or restarts a part, such as "the app closes" or "the process restarts", as an edge to the state that comes next. Run `render CHART.mmd` to get a PNG of the chart for the reader.
+2. Run `from-chart`. If a rule breaks, the agreed chart has a design bug. Take the bug to the people who agreed to the chart.
+3. Add the real code's guards and variables to the spec that `from-chart` wrote, and run `from-chart` again. For each difference it prints, ask the reader whether the code is wrong or the chart needs a correction.
+
+## Hand off
+
+Give the PNG and the Mermaid source of each chart to the person who must decide. Add one line per bug with the rule it breaks, its steps as the chart numbers them, whether it reproduced, and whether the proposed fix fixes it. A broken PROPERTY has no path on the chart, so give the TLC counterexample that `stories.md` names for it. With `--against`, also say whether the spec already lists it: in the configs that `stories.md` names, in the spec's notes on what the model leaves out, or not at all. When the model describes code, do not report that a rule holds while the command lists conditions with no file and line. Take every count you quote from `summary.json`. Attach `stories.md` and the command that regenerates everything. Say what the model leaves out.

package/skills/statechart/scripts/bug-states.mjs

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import { BROKEN_MARK, parseValue, stateKey } from "./lib.mjs";
+import { SEP } from "./chart-parts.mjs";
+
+export function firstBad(raw) {
+  const badStates = new Map();
+  for (const t of raw) {
+    if (!badStates.has(t.invariant)) badStates.set(t.invariant, new Set());
+    badStates.get(t.invariant).add(stateKey(t.steps[t.steps.length - 1].vars));
+  }
+  const cuts = [];
+  const seen = new Set();
+  for (const t of raw) {
+    const first = t.steps.findIndex((s) => badStates.get(t.invariant).has(stateKey(s.vars)));
+    const cut = { invariant: t.invariant, steps: t.steps.slice(0, first + 1) };
+    const id = `${t.invariant}${SEP}${stateKey(cut.steps[cut.steps.length - 1].vars)}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    cuts.push(cut);
+  }
+  return cuts;
+}
+
+export const byOrder = (a, b) =>
+  a.steps - b.steps ||
+  a.trace.steps.length - b.trace.steps.length ||
+  (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+const lastKey = (t) => stateKey(t.steps[t.steps.length - 1].vars);
+export const badOf = (raw, rule) => new Set(raw.filter((t) => t.invariant === rule).map(lastKey));
+export function reachableAvoiding({ graph: g, stateKeys }, bad) {
+  const ok = (id) => !bad.has(stateKeys.get(id));
+  const next = new Map();
+  for (const e of g.edges) {
+    if (!next.has(e.from)) next.set(e.from, []);
+    next.get(e.from).push(e.to);
+  }
+  const clean = new Set([...g.nodes.values()].filter((n) => n.init && ok(n.id)).map((n) => n.id));
+  for (const id of clean) for (const to of next.get(id) ?? []) if (ok(to)) clean.add(to);
+  return clean;
+}
+
+export const diverges = (c) => c.second?.key !== undefined;
+export function readBroken(file) {
+  if (!file) return [];
+  const lines = fs.readFileSync(file, "utf8").split("\n");
+  const marked = new RegExp(`^<<\\s*"${BROKEN_MARK}",`);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!marked.test(lines[i])) continue;
+    let text = lines[i];
+    while (typeof parseValue(text) === "string" && i + 1 < lines.length) text += `\n${lines[++i]}`;
+    const [, vars, broken] = parseValue(text);
+    out.push({ key: stateKey(vars), rules: broken });
+  }
+  return out;
+}
+export const badStates = (raw, broken, counts = () => true) =>
+  new Set([
+    ...raw.filter((t) => counts(t.invariant)).map(lastKey),
+    ...broken.filter((b) => b.rules.some(counts)).map((b) => b.key),
+  ]);
+export function labelStatus(m, keys, bad) {
+  const good = reachableAvoiding(m, bad);
+  const kinds = new Map();
+  for (const n of m.graph.nodes.values()) {
+    const k = keys.get(n.id);
+    if (!kinds.has(k)) kinds.set(k, new Set());
+    kinds.get(k).add(bad.has(m.stateKeys.get(n.id)) ? "bad" : good.has(n.id) ? "good" : "after");
+  }
+  return (k) => {
+    const has = kinds.get(k);
+    if (!has) return undefined;
+    if (has.has("bad")) return has.has("good") ? "mixed" : "wrong";
+    return has.has("good") ? "works" : "after";
+  };
+}
+
+export const RANK = ["works", "fixed", "after", "mixed", "wrong", "worse"];
+export const worst = (...all) =>
+  all.filter(Boolean).reduce((a, b) => (RANK.indexOf(b) > RANK.indexOf(a) ? b : a), "works");

package/skills/statechart/scripts/chart-edges.mjs

@@ -0,0 +1,68 @@
+import { edgeId } from "./chart-parts.mjs";
+import { diverges } from "./bug-states.mjs";
+
+export const edgesAlong = (c) =>
+  c.path.slice(1).map((p, i) => ({
+    id: edgeId(c.path[i].key, p.key),
+    from: c.path[i].key,
+    to: p.key,
+    label: p.label,
+    guard: p.guard,
+  }));
+
+export function chartEdges({ args, now, secondQ, modelEdges, classes, chosen, coverOff }) {
+  const edges = new Map(modelEdges);
+  for (const { second: s } of classes.filter(diverges)) {
+    if (modelEdges.has(s.edge)) continue;
+    if (!edges.has(s.edge))
+      edges.set(s.edge, {
+        from: s.from,
+        to: s.key,
+        labels: new Set(),
+        secondOnly: true,
+        apart: s.apart,
+      });
+    edges.get(s.edge).labels.add(s.overview);
+  }
+  const pathNumbers = new Map();
+  (chosen ? edgesAlong(chosen) : []).forEach((step, i) => {
+    if (!pathNumbers.has(step.id)) pathNumbers.set(step.id, []);
+    const shown = step.guard ? `${step.label} [${step.guard}]` : step.label;
+    pathNumbers.get(step.id).push({ n: i + 1, label: step.label, shown });
+    if (!edges.has(step.id))
+      edges.set(step.id, { from: step.from, to: step.to, labels: new Set([step.label]) });
+  });
+  const bugSteps = classes.flatMap(edgesAlong);
+  const pathEdges = new Map();
+  for (const step of bugSteps) {
+    if (edges.has(step.id)) continue;
+    if (!pathEdges.has(step.id))
+      pathEdges.set(step.id, { from: step.from, to: step.to, labels: new Set() });
+    pathEdges.get(step.id).labels.add(step.label);
+  }
+  for (const [id, e] of pathEdges) edges.set(id, e);
+  if (!args.cover || coverOff) return { edges, pathNumbers, coverEdges: null };
+
+  const coverEdges = new Set(bugSteps.map((step) => step.id));
+  const bfs = (q, targets) => {
+    const parent = new Map([...q.initial].map((k) => [k, null]));
+    const outEdges = new Map();
+    for (const [id, e] of q.edges) {
+      if (!outEdges.has(e.from)) outEdges.set(e.from, []);
+      outEdges.get(e.from).push([id, e]);
+    }
+    for (const k of parent.keys())
+      for (const [id, e] of outEdges.get(k) ?? []) if (!parent.has(e.to)) parent.set(e.to, id);
+    for (const t of targets) {
+      for (let id = parent.get(t); id; id = parent.get(q.edges.get(id).from)) coverEdges.add(id);
+    }
+  };
+  bfs(now, now.settled);
+  if (secondQ)
+    bfs(
+      secondQ,
+      [...secondQ.settled].filter((k) => !now.nodes.has(k)),
+    );
+  for (const c of classes.filter(diverges)) coverEdges.add(c.second.edge);
+  return { edges, pathNumbers, coverEdges };
+}

package/skills/statechart/scripts/chart-parts.mjs

@@ -0,0 +1,21 @@
+export const SEP = "\u0000";
+export const edgeId = (from, to) => `${from}${SEP}${SEP}${to}`;
+
+export function guarded(guards, label) {
+  const words = guards?.get(label);
+  return words && !words.has("") ? `${label} [${[...words].sort().join(" or ")}]` : label;
+}
+export const addGuard = (guards, label, words) => {
+  if (!guards.has(label)) guards.set(label, new Set());
+  guards.get(label).add(words);
+};
+
+export const frontMatter = (title) => [
+  "---",
+  ...(title ? [`title: ${JSON.stringify(title)}`] : []),
+  "config:",
+  "  markdownAutoWrap: false",
+  "  state:",
+  "    useMaxWidth: false",
+  "---",
+];