dsh-pstack 0.3.0-beta.1 → 0.3.1

package/dist/pstack/skills/poteto-mode/scripts/worktree-audit.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# Read-only worktree prune audit. Classifies every git worktree by size, merge
+# state, uncommitted work, remote/PR state, and the most recent chat that
+# operated in it. Emits a table sorted by size with a suggested bucket. Never
+# deletes anything; deletion stays a human-gated step in the playbook.
+#
+# Usage: worktree-audit.sh [-b|--base <ref>] [repo-path]
+#   repo-path defaults to the current repo.
+#   -b sets the ref the MERGED column checks against (e.g. origin/integration).
+#   Without it the base is origin/HEAD, then origin/main, then origin/master.
+#   origin/HEAD is the remote's default branch, not necessarily the branch PRs
+#   merge into; pass -b when they differ.
+set -u
+
+base=""
+while [ $# -gt 0 ]; do
+	case "$1" in
+	-b|--base) [ $# -ge 2 ] || { echo "error: $1 needs a ref" >&2; exit 2; }; base="$2"; shift 2 ;;
+	-h|--help) sed -n '2,/^set -u/p' "$0" | sed '$d; s/^# \{0,1\}//'; exit 0 ;;
+	-*) echo "error: unknown option: $1" >&2; exit 2 ;;
+	*) break ;;
+	esac
+done
+
+repo="${1:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+[ -z "$repo" ] && { echo "not in a git repo; pass a repo path" >&2; exit 1; }
+cd "$repo" || exit 1
+git rev-parse --git-dir >/dev/null 2>&1 || { echo "error: not a git repo: $repo" >&2; exit 1; }
+
+# Main worktree is the first entry; everything else is a candidate.
+main_wt=$(git worktree list --porcelain | awk '/^worktree /{print $2; exit}')
+
+if [ -z "$base" ]; then
+	for cand in "$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null)" origin/main origin/master; do
+		[ -n "$cand" ] && git rev-parse --verify --quiet "$cand^{commit}" >/dev/null && { base="$cand"; break; }
+	done
+	[ -z "$base" ] && { echo "error: no base ref (origin/HEAD, origin/main, origin/master all missing); pass -b <ref>" >&2; exit 1; }
+	echo "warn: no -b given; MERGED checks against $base" >&2
+fi
+
+# The base drives the merge check. The fetch is best-effort (stale is fine for
+# a first pass) and runs before the check, since -b may name a branch not
+# fetched yet. The explicit refspec creates it even in a single-branch clone.
+case "$base" in
+origin/*) git fetch origin "+refs/heads/${base#origin/}:refs/remotes/$base" --quiet 2>/dev/null \
+	|| echo "warn: could not fetch $base; merged column may be stale" >&2 ;;
+esac
+git rev-parse --verify --quiet "$base^{commit}" >/dev/null 2>&1 || { echo "error: base ref not found: $base" >&2; exit 1; }
+
+# GNU coreutils (Linux, Homebrew gnubin) reads `stat -f` as file system status
+# and `date -r` as a file, so pick the stat and date flags once.
+if stat -c %Y / >/dev/null 2>&1; then
+	stat_fmt=(-c '%Y %n'); fmt_day() { date -d "@$1" '+%Y-%m-%d'; }
+else
+	stat_fmt=(-f '%m %N'); fmt_day() { date -r "$1" '+%Y-%m-%d'; }
+fi
+
+# PR state by branch, fetched once as [{number, state, head}] with a lowercase
+# state. Origin when its CLI can read this repo's PRs, otherwise gh. Empty when
+# neither can.
+prs=$(mktemp)
+if command -v origin >/dev/null 2>&1 \
+	&& raw=$(origin pr list --author "@me" --state all --limit 1000 \
+		--json number,status,headRef 2>/dev/null); then
+	printf '%s' "$raw" | jq '[.[] | {number, state: .status, head: .headRef}]' > "$prs" 2>/dev/null
+elif raw=$(gh pr list --author "@me" --state all --limit 1000 \
+	--json number,state,headRefName 2>/dev/null); then
+	printf '%s' "$raw" | jq '[.[] | {number, state: (.state | ascii_downcase), head: .headRefName}]' > "$prs" 2>/dev/null
+fi
+[ -s "$prs" ] || echo "[]" > "$prs"
+
+# Transcripts dir: ~/.cursor/projects/<slugified-repo-path>/agent-transcripts.
+slug=$(printf '%s' "$main_wt" | sed 's#^/##; s#/#-#g')
+transcripts="$HOME/.cursor/projects/$slug/agent-transcripts"
+now=$(date +%s)
+
+echo "# base: $base"
+printf "SIZE\tAGE\tMERGED\tDIRTY\tREMOTE\tPR\tLAST_CHAT\tBUCKET\tWORKTREE\n"
+
+git worktree list --porcelain | awk '/^worktree /{print $2}' | while read -r wt; do
+	[ "$wt" = "$main_wt" ] && continue
+
+	size=$(du -sh "$wt" 2>/dev/null | awk '{print $1}')
+	head=$(git -C "$wt" rev-parse HEAD 2>/dev/null)
+	head_ts=$(git -C "$wt" log -1 --format='%ct' HEAD 2>/dev/null || echo 0)
+	age=$([ "$head_ts" -gt 0 ] 2>/dev/null && echo "$(( (now - head_ts) / 86400 ))d" || echo "?")
+
+	# Squash-merged branches are not ancestors of the base, so PR state is the
+	# real signal; merge-base only catches fast-forward/rebase merges.
+	git merge-base --is-ancestor "$head" "$base" 2>/dev/null && merged=YES || merged=no
+
+	# Distinguish real WIP (tracked edits) from disposable untracked scratch.
+	porcelain=$(git -C "$wt" status --porcelain 2>/dev/null)
+	if [ -z "$porcelain" ]; then dirty=clean
+	elif printf '%s\n' "$porcelain" | grep -qv '^??'; then
+		dirty="wip:$(printf '%s\n' "$porcelain" | grep -cv '^??')"
+	else dirty="scratch:$(printf '%s\n' "$porcelain" | grep -c '^??')"; fi
+
+	branch=$(git -C "$wt" symbolic-ref --quiet --short HEAD 2>/dev/null || echo "")
+	if [ -z "$branch" ]; then remote=detached
+	elif git -C "$wt" show-ref --verify --quiet "refs/remotes/origin/$branch"; then
+		[ "$(git -C "$wt" rev-parse "origin/$branch" 2>/dev/null)" = "$head" ] \
+			&& remote=pushed \
+			|| remote="ahead$(git -C "$wt" rev-list --count "origin/$branch..HEAD" 2>/dev/null)"
+	else remote=no-remote; fi
+
+	pr=$([ -n "$branch" ] && jq -r --arg b "$branch" \
+		'.[] | select(.head==$b) | "#\(.number)/\(.state)"' "$prs" 2>/dev/null | head -1)
+	[ -z "$pr" ] && pr="-"
+
+	# Most recent chat whose transcript operated in this worktree. Match path
+	# followed by "/" or a quote so glint-482 does not match glint-482-r37.
+	last="-"; last_ts=0
+	if [ -d "$transcripts" ]; then
+		f=$(rg -l -e "${wt}/" -e "${wt}\"" "$transcripts" 2>/dev/null \
+			| xargs stat "${stat_fmt[@]}" 2>/dev/null | sort -rn | head -1)
+		if [ -n "$f" ]; then last_ts=$(echo "$f" | awk '{print $1}')
+			last=$(fmt_day "$last_ts" 2>/dev/null); fi
+	fi
+	recent=$([ "$last_ts" -gt 0 ] 2>/dev/null && [ $(( (now - last_ts) / 86400 )) -le 4 ] && echo yes || echo no)
+
+	case "$dirty" in wip:*) bucket=hold-wip ;; *)
+		case "$pr" in */open|*/draft) bucket=hold-open-pr ;; *)
+			if [ "$recent" = yes ]; then bucket=verify-recent-chat
+			elif [ "$merged" = YES ] || [ "$pr" != "-" ]; then bucket=safe
+			else bucket=review; fi ;;
+		esac ;;
+	esac
+
+	printf "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n" \
+		"$size" "$age" "$merged" "$dirty" "$remote" "$pr" "$last" "$bucket" "$wt"
+done | sort -t$'\t' -k1,1 -rh
+
+rm -f "$prs"

package/dist/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/dist/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");
+}

package/dist/pstack/skills/statechart/scripts/backends/mermaid.ts

@@ -0,0 +1,201 @@
+import { append, byText, type Chart, type ChartState, type Region, tupleKey } from "../ir.ts";
+
+const BLANK = /\p{White_Space}/u;
+const SAFE = /^[\p{L}\p{N} !'()+,\-./=?[\]"_|@{}:\\^%<>]$/u;
+const HAZARD =
+  /:(?=:|$|\S*#)|\\(?=n)|%(?=%)|<(?=[\p{L}/!?])|_(?![\p{L}\p{N}])|(?<![\p{L}\p{N}])_/giu;
+const DIRECTION = /(direction)\s+(?=LR|RL|TB|BT)/gi;
+const DOUBLE_BRACKET = /\[(?=\[)/g;
+const C4 = /C4(?=Container|Component|Dynamic|Deployment)/g;
+const UNDRAWN = /[\0\x80-\x9f]/;
+const REWRITTEN = ["fl°", "¶ß"];
+const MARKER = /(?<=marker-end=)"/g;
+const firstOf = new Map<number, number>();
+for (const pair of REWRITTEN) {
+  const [first, second] = [...pair].map((c) => c.codePointAt(0) ?? 0);
+  firstOf.set(second, first);
+}
+const KEPT = 0;
+const BLANKED = 1;
+const DROPPED = 2;
+const CODED = 3;
+const JOINS = 4;
+const kindOf = (n: number) => {
+  const c = String.fromCodePoint(n);
+  const kind =
+    c === " "
+      ? KEPT
+      : BLANK.test(c)
+        ? BLANKED
+        : UNDRAWN.test(c)
+          ? DROPPED
+          : SAFE.test(c)
+            ? KEPT
+            : CODED;
+  return firstOf.has(n) ? kind | JOINS : kind;
+};
+const ASCII = Uint8Array.from({ length: 128 }, (_, n) => kindOf(n));
+const wide = new Map<number, number>();
+const kindAt = (n: number) => {
+  if (n < 128) return ASCII[n];
+  let kind = wide.get(n);
+  if (kind === undefined) wide.set(n, (kind = kindOf(n)));
+  return kind;
+};
+const encode = (s: string, ref: (n: number) => string) => {
+  let out = "";
+  let run = 0;
+  let last = -1;
+  for (let i = 0; i < s.length;) {
+    let n = s.charCodeAt(i);
+    let width = 1;
+    if (n >= 0xd800 && n <= 0xdfff) {
+      const low = s.charCodeAt(i + 1);
+      if (n <= 0xdbff && low >= 0xdc00 && low <= 0xdfff) {
+        n = 0x10000 + ((n - 0xd800) << 10) + (low - 0xdc00);
+        width = 2;
+      } else n = 0xfffd;
+    }
+    let kind = kindAt(n);
+    if (kind === DROPPED) {
+      out += s.slice(run, i);
+      run = i + width;
+    } else {
+      const joined = kind >= JOINS && firstOf.get(n) === last;
+      kind &= ~JOINS;
+      if (joined || kind !== KEPT) {
+        out += s.slice(run, i);
+        if (joined) out += ref(0x2060);
+        if (kind === KEPT) run = i;
+        else {
+          out += kind === BLANKED ? " " : ref(n);
+          run = i + width;
+        }
+      }
+      last = n;
+    }
+    i += width;
+  }
+  return out + s.slice(run);
+};
+const code = (s: string, ref: (n: number) => string) =>
+  encode(s, ref)
+    .replace(MARKER, `${ref(0x2060)}"`)
+    .replace(HAZARD, (c) => ref(c.charCodeAt(0)));
+const esc = (s: string, quoted = false) => {
+  const plain = code(s, (n) => `#${n};`);
+  const out = quoted ? plain.replaceAll('"', "#34;") : plain;
+  if (!out.trim()) return "#32;";
+  const turned = out.replace(DIRECTION, "$1#32;");
+  const opened = turned.includes("[[") ? turned.replace(DOUBLE_BRACKET, "#91;") : turned;
+  return opened.includes("C4") ? opened.replace(C4, "C#52;") : opened;
+};
+
+const or = (names: Iterable<string>) => [...names].sort(byText).join(" or ");
+
+const MARK_STYLES = {
+  breaks: "fill:#ffecee,stroke:#e72e3b,stroke-width:2.5px,color:#cd2834",
+  mayBreak: "fill:#fff3e6,stroke:#e8730c,stroke-width:2.5px,color:#b85a06",
+};
+
+export function mermaidLines(chart: Chart) {
+  let next = 0;
+  const marks: string[] = [];
+  const used = new Set<string>();
+  const rules = { breaks: new Set<string>(), mayBreak: new Set<string>() };
+  const region = (r: Region) => {
+    const out: string[] = [];
+    const topIds = new Map<string, string>();
+    const nestedIds = new Map<string, string>();
+    const id = (path: string[]) => {
+      const top = path.length === 1;
+      const named = top ? topIds : nestedIds;
+      const k = top ? path[0] : tupleKey(path);
+      let s = named.get(k);
+      if (s === undefined) named.set(k, (s = `s${next++}`));
+      return s;
+    };
+    const known = new Map<string[], string>();
+    const idOf = (path: string[]) => {
+      let s = known.get(path);
+      if (s === undefined) known.set(path, (s = id(path)));
+      return s;
+    };
+    const tree = (prefix: string[], indent: string, below: ChartState[]) => {
+      const heads = new Map<string, ChartState[]>();
+      for (const s of below) append(heads, s.path[prefix.length], s);
+      for (const [head, under] of heads) {
+        const path = [...prefix, head];
+        let leaf: ChartState | undefined;
+        const inner: ChartState[] = [];
+        for (const s of under)
+          if (s.path.length > path.length) inner.push(s);
+          else leaf = s;
+        if (inner.length) {
+          out.push(`${indent}state "${esc(head, true)}" as ${id(path)} {`);
+          tree(path, indent + "  ", inner);
+          out.push(`${indent}}`);
+        } else if (leaf) {
+          const sid = idOf(leaf.path);
+          out.push(`${indent}${sid}: ${esc(head)}`);
+          let mark: "breaks" | "mayBreak" | undefined =
+            leaf.breaks.length && !leaf.works ? "mayBreak" : undefined;
+          if (mark) for (const b of leaf.breaks) if (b.always) mark = "breaks";
+          if (mark) for (const b of leaf.breaks) rules[mark].add(b.rule.name);
+          const trail = [leaf.lead && "bugPath", leaf.repeats && "repeats"];
+          const color = leaf.group === undefined ? undefined : chart.colors[String(leaf.group)];
+          for (const cls of [color, mark, ...trail])
+            if (cls) {
+              used.add(cls);
+              marks.push(`  class ${sid} ${cls}`);
+            }
+        }
+      }
+    };
+    tree([], "  ", r.states);
+    for (const s of r.states) if (s.start) out.push(`  [*] --> ${idOf(s.path)}`);
+    for (const s of r.steps)
+      out.push(
+        `  ${idOf(s.from)} --> ${idOf(s.to)}: ${esc(s.label + (s.when ? ` [${s.when}]` : ""))}`,
+      );
+    return out;
+  };
+  let body: string[];
+  if (chart.regions.length > 1) {
+    body = [`  state "At the same time" as all {`];
+    for (const [i, r] of chart.regions.entries()) {
+      if (i) body.push("    --");
+      body.push(`    state "${esc(r.name, true)}" as r${i} {`);
+      for (const line of region(r)) body.push(`    ${line}`);
+      body.push("    }");
+    }
+    body.push("  }");
+  } else body = region(chart.regions[0]);
+  const legend: string[][] = [];
+  for (const entry of [
+    ...Object.entries(chart.colors),
+    [`Breaks ${or(rules.breaks)}`, "breaks"],
+    [`Breaks ${or(rules.mayBreak)} in some cases`, "mayBreak"],
+    [`Path to the ${or(chart.paths)} bug`, "bugPath"],
+    [`Repeats forever, so ${or(chart.loops)} breaks`, "repeats"],
+  ])
+    if (used.has(entry[1])) legend.push(entry);
+  const lines: string[] = [];
+  const title = chart.title && code(chart.title, (n) => `fl°°${n}¶ß`).replaceAll("<", "fl°°60¶ß");
+  if (title) lines.push("---", `title: ${JSON.stringify(title)}`, "---");
+  lines.push("stateDiagram-v2");
+  if (chart.regions.length > 1) lines.push("  direction LR");
+  if (legend.length) {
+    lines.push(`  state "Legend" as legend {`);
+    for (const [i, [text]] of legend.entries()) lines.push(`    lg${i}: ${esc(text)}`);
+    lines.push("  }");
+    for (const [i, [, cls]] of legend.entries()) lines.push(`  class lg${i} ${cls}`);
+  }
+  for (const line of body) lines.push(line);
+  for (const [cls, style] of Object.entries(MARK_STYLES))
+    if (used.has(cls)) lines.push(`  classDef ${cls} ${style}`);
+  for (const line of marks) lines.push(line);
+  return lines;
+}
+
+export const mermaid = (chart: Chart) => mermaidLines(chart).join("\n");

package/dist/pstack/skills/statechart/scripts/backends/plain-text.ts

@@ -0,0 +1,72 @@
+import { EC, LEVEL, type Message, PART, type Part } from "../ir.ts";
+
+const PREFIX: { [level: number]: string } = {
+  [LEVEL.ERROR]: "Error: ",
+  [LEVEL.TLCBUG]: "TLC Bug: ",
+  [LEVEL.WARNING]: "Warning: ",
+  [LEVEL.STATE]: "State ",
+};
+const MINUTE = 60_000;
+const HOUR = 3_600_000;
+const DAY = 86_400_000;
+
+const pad = (n: number) => String(n).padStart(2, "0");
+
+export function runtime(ms: number) {
+  const t = new Date(ms > DAY ? ms - DAY : ms);
+  const [hh, mm, ss] = [t.getUTCHours(), t.getUTCMinutes(), t.getUTCSeconds()].map(pad);
+  if (ms > DAY)
+    return `${Math.floor((t.getTime() - Date.UTC(t.getUTCFullYear(), 0, 1)) / DAY) + 1}d ${hh}h`;
+  if (ms > HOUR) return `${hh}h ${mm}min`;
+  if (ms > MINUTE) return `${mm}min ${ss}s`;
+  return `${ss}s`;
+}
+
+const firstLine = ({ code, level }: Message, line: string) => {
+  if (code === EC.TLC_BACK_TO_STATE)
+    return line.replace(/^(\d+): Back to state: /, "Back to state $1: ");
+  if (code === EC.TLC_FINISHED)
+    return line.replace(
+      /^Finished in (\d+)ms/,
+      (_, ms: string) => `Finished in ${runtime(Number(ms))}`,
+    );
+  return (PREFIX[level] ?? "") + line;
+};
+
+const render = (m: Message): string =>
+  (m.beforeMarker ?? "") +
+  firstLine(m, m.body.map((part) => (typeof part === "string" ? part : render(part))).join("\n"));
+
+function* printed(parts: Iterable<Part>): Generator<string> {
+  let warned = false;
+  let progress: Message | undefined;
+  for (const part of parts) {
+    if (progress?.body.length && (typeof part === "string" || part.code !== EC.TLC_STATS))
+      yield render(progress);
+    progress = undefined;
+    if (typeof part === "string") {
+      yield part;
+      continue;
+    }
+    if (part.code === EC.TLC_SANY_START || part.code === EC.TLC_SANY_END) continue;
+    if (part.code === EC.TLC_PROGRESS_STATS) progress = part;
+    else if (part.body.length) yield render(part);
+    if (part.level === LEVEL.WARNING && !warned) {
+      yield "(Use the -nowarning option to disable this warning.)";
+      warned = true;
+    }
+  }
+  if (progress?.body.length) yield render(progress);
+}
+
+export function* plainText(parts: Iterable<Part>): Generator<string> {
+  let chunk = "";
+  for (const line of printed(parts)) {
+    chunk += `${line}\n`;
+    if (chunk.length >= PART) {
+      yield chunk;
+      chunk = "";
+    }
+  }
+  if (chunk) yield chunk;
+}

package/dist/pstack/skills/statechart/scripts/backends/report.ts

@@ -0,0 +1,177 @@
+import {
+  type Bug,
+  CHART_STATES,
+  type Chart,
+  type Graph,
+  hasSection,
+  list,
+  must,
+  type Property,
+  RERUN_STATES,
+  ruleKey,
+  type Spec,
+  type Stop,
+  type Story,
+  type Verdict,
+} from "../ir.ts";
+
+const stepsOf = (story: Story) => {
+  const path: { step?: string; state: string }[] = [];
+  for (const { step, state } of story) {
+    const parts: string[] = [];
+    for (const [name, names] of Object.entries(state))
+      parts.push((name ? `${name} ` : "") + names.join(" / "));
+    path.push({ step, state: parts.join(", ") });
+  }
+  return path;
+};
+
+const forever = (loop: { state: string }[], stutters: boolean | undefined) => {
+  const quoted = new Set<string>();
+  for (const p of loop) quoted.add(`"${p.state}"`);
+  const runs = [...quoted];
+  if (stutters) return `The run stops in ${runs[0]} forever.`;
+  return runs.length === 1
+    ? `The run stays in ${runs[0]} forever.`
+    : `The run loops through ${list(runs)} forever.`;
+};
+
+const fenced = (text: string) => ["```", text, "```"].join("\n");
+
+export function report(
+  {
+    spec,
+    graph,
+    paths,
+    rules,
+    properties,
+    stop,
+    drawing,
+    states,
+  }: {
+    spec: Spec;
+    graph: Graph;
+    paths: Bug[] | undefined;
+    rules: Verdict[];
+    properties: Property[];
+    stop: Stop | undefined;
+    drawing: { status: number | null } | undefined;
+    states: { distinct: number; initial: number; complete: boolean; cut: boolean };
+  },
+  found: Bug[],
+  chart: Chart | undefined,
+  stories: Map<Bug, Story>,
+) {
+  let size = 0;
+  let arrows = 0;
+  for (const r of chart?.regions ?? []) {
+    size += r.states.length;
+    arrows += r.steps.length;
+  }
+  let past = 0;
+  let pastSteps = 0;
+  let excluded = 0;
+  for (const s of graph.states.values()) {
+    if (s.excluded) excluded++;
+    else if (s.past) past++;
+  }
+  for (const t of graph.steps) if (must(graph.states, t.to).past) pastSteps++;
+  const includes = (n: number) =>
+    chart ? `, and the chart includes ${n === 1 ? "it" : "them"}` : "";
+  const out = [
+    `# ${spec.module}`,
+    "",
+    paths
+      ? `TLC reached ${states.complete && !states.cut && states.distinct > CHART_STATES ? `${states.distinct.toLocaleString("en-US")} states, more than` : "more states than"} the chart budget of ${CHART_STATES}, so ${chart ? `the chart draws only the bug paths: ${size} states and ${arrows} arrows` : "the command wrote no chart.mmd"}.`
+      : `TLC reached ${graph.states.size - past - excluded} states and ${graph.steps.length - pastSteps} steps. The chart draws ${size} states and ${arrows} arrows.`,
+  ];
+  if (drawing)
+    out.push(
+      `TLC stopped the drawing run with exit ${drawing.status}, so the chart draws only the states that it reached before it stopped.`,
+    );
+  if (!paths && !drawing && graph.states.size === past + excluded)
+    out.push(
+      states.initial
+        ? "Every initial state is outside the constraints, so TLC explores none of them."
+        : "TLC found no state that satisfies Init, so no state can break a rule.",
+    );
+  if (past)
+    out.push(
+      `${past === 1 ? "1 state outside the constraints ends" : `${past} states outside the constraints each end`} a rule's path${includes(past)}. TLC checks the rules in a state outside the constraints, but it does not explore past it.`,
+    );
+  if (excluded)
+    out.push(
+      `${excluded === 1 ? "1 step that the constraints exclude ends" : `${excluded} steps that the constraints exclude each end`} a rule's path${includes(excluded)}. TLC checks the rules after such a step, but it does not take the step.`,
+    );
+  if (chart?.inside)
+    out.push(`The chart does not draw ${chart.inside} steps that stay in one chart state.`);
+  if (chart?.quiet)
+    out.push(`The view hides ${chart.quiet} steps, so the chart does not draw them.`);
+  for (const { rule, outcome } of rules)
+    if (
+      !paths &&
+      rule.kind === "deadlock" &&
+      outcome === "broken" &&
+      (drawing || hasSection(spec, "CONSTRAINT", "ACTION_CONSTRAINT"))
+    )
+      out.push(
+        drawing
+          ? "The chart marks only the deadlock that TLC reports, because the drawing run stopped before it reached every state."
+          : "The chart marks only the deadlock that TLC reports. Under a CONSTRAINT or an ACTION_CONSTRAINT, a state with no step in the chart can still have steps that the constraints leave out, and TLC does not count it as a deadlock.",
+      );
+  if (chart?.lie) out.push(`${chart.lie} So the chart draws parent states in place of regions.`);
+  out.push(...(chart?.notes ?? []));
+  const merged: string[] = [];
+  for (const k of ["VIEW", "SYMMETRY"]) if (hasSection(spec, k)) merged.push(k);
+  if (chart && merged.length)
+    out.push(
+      `With ${list(merged)}, TLC keeps one representative for each group of states that it counts as the same. An arrow can lead to the representative rather than to the state that the step reaches.`,
+    );
+  for (const bug of found) {
+    const steps = `${bug.path.length} step${bug.path.length === 1 ? "" : "s"}`;
+    out.push("", `## ${bug.rule.name} breaks`);
+    out.push(
+      bug.rule.kind === "property"
+        ? `TLC's counterexample is in tlc-${bug.rule.name}.out. It has ${steps}:`
+        : `The shortest path has ${steps}:`,
+    );
+    const path = stepsOf(must(stories, bug));
+    for (const [i, p] of path.entries()) out.push(`${i}. ${p.step ? `${p.step}: ` : ""}${p.state}`);
+    if (bug.loop !== undefined) out.push(forever(path.slice(bug.loop), bug.stutters));
+  }
+  const drawn = new Set<string>();
+  for (const b of found) drawn.add(ruleKey(b.rule));
+  const holds: string[] = [];
+  const unchecked: string[] = [];
+  for (const { rule, outcome, messages } of [...rules, ...properties]) {
+    if (outcome === "holds") holds.push(rule.name);
+    else if (outcome === "not checked") unchecked.push(rule.name);
+    else if (messages && !drawn.has(ruleKey(rule)))
+      out.push(
+        "",
+        `## ${rule.name} breaks`,
+        `TLC found a counterexample. It is in tlc-${rule.name}.out.`,
+      );
+  }
+  if (holds.length) out.push("", "## Rules that hold", holds.join(", "));
+  if (unchecked.length) out.push("", "## Rules not checked", unchecked.join(", "));
+  if (unchecked.length && states.cut)
+    out.push(
+      `After the first break, each TLC run stops at ${RERUN_STATES.toLocaleString("en-US")} distinct states. A run reached that bound before it checked ${unchecked.length === 1 ? "this rule" : "these rules"} in every state.`,
+    );
+  if (stop)
+    out.push(
+      ...(unchecked.length
+        ? [
+            `TLC stopped with exit ${stop.status} before it checked ${unchecked.length === 1 ? "this rule" : "these rules"}:`,
+          ]
+        : ["", "## TLC stopped", `TLC stopped with exit ${stop.status}:`]),
+      fenced(stop.message),
+    );
+  for (const p of properties)
+    if (p.outcome === "holds" && p.initialOnly)
+      out.push(
+        `TLC checked ${p.rule.name} only in the initial states, because it has no [], <>, or ~>. List it as an INVARIANT to check every state.`,
+      );
+  return out.join("\n");
+}