pi-pstack-native 0.0.0-stage → 1.0.0

package/skills/statechart/scripts/tlc-tools.mjs

@@ -0,0 +1,69 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+// TLC's v1.8.0 is a rolling pre-release whose jar is re-uploaded, so pin the newest immutable
+// release. The scripts read 1.7.4's output, which has no trace spec.
+export const TLC_TOOL =
+  "github:tlaplus/tlaplus[asset_pattern=tla2tools.jar,checksum=sha256:936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88]@1.7.4";
+export const JAVA_TOOL = "java@temurin-25";
+
+const SET_TLC_VARS =
+  "set TLA2TOOLS to the path of tla2tools.jar, and JAVA to a java binary (Java 11 or later).";
+const indent = (text) => text.replace(/^/gm, "  ");
+
+export function findTlc() {
+  const { TLA2TOOLS, JAVA } = process.env;
+  for (const [name, file] of Object.entries({ JAVA, TLA2TOOLS }))
+    if (file && !fs.existsSync(file)) throw new Error(`${name} is ${file}, which does not exist.`);
+  if (TLA2TOOLS) return { jar: TLA2TOOLS, java: JAVA || "java" };
+  const command = (tools) =>
+    `cd "$(mktemp -d)" && MISE_CEILING_PATHS="$PWD" mise install ${tools.map((t) => `'${t}'`).join(" ")}`;
+  const empty = fs.mkdtempSync(path.join(os.tmpdir(), "statechart-mise-"));
+  const env = { ...process.env, MISE_CEILING_PATHS: empty };
+  const run = (...args) => spawnSync("mise", args, { cwd: empty, env, encoding: "utf8" });
+  const mise = (...args) => {
+    const r = run(...args);
+    if (r.error)
+      throw new Error(
+        `Cannot find TLC. It installs with mise, which cannot start: ${r.error.message}. Install mise (https://mise.jdx.dev), or ${SET_TLC_VARS}`,
+      );
+    if (r.status === 0) return r.stdout.trim();
+    const said = (r.stderr ?? "").trim();
+    if (!said || /not installed|mise bin/.test(said)) return "";
+    throw new Error(
+      `Cannot find TLC, because mise failed:\n${indent(said)}\nThe install command: ${command(JAVA ? [TLC_TOOL] : [JAVA_TOOL, TLC_TOOL])}\nFix that, or ${SET_TLC_VARS}`,
+    );
+  };
+  const resolve = () => {
+    const home = mise("where", TLC_TOOL);
+    const jar = home && path.join(home, "tla2tools.jar");
+    const java = JAVA || mise("which", "java", "--tool", JAVA_TOOL);
+    return { jar: jar && fs.existsSync(jar) ? jar : "", java };
+  };
+  try {
+    const found = resolve();
+    if (found.jar && found.java) return found;
+    const tools = [!found.java && JAVA_TOOL, !found.jar && TLC_TOOL].filter(Boolean);
+    const names = [!found.jar && "TLC", !found.java && "Java"].filter(Boolean);
+    console.error(`Installing ${names.join(" and ")} with mise. This happens once.`);
+    const r = run("install", "--quiet", ...tools);
+    const installed = resolve();
+    if (installed.jar && installed.java) return installed;
+    const said =
+      `${r.stderr ?? ""}${r.stdout ?? ""}`.trim() ||
+      `mise install exited ${r.status}, with no output`;
+    throw new Error(
+      `Cannot find TLC, and mise could not install it:\n${indent(said)}\nThe install command: ${command(tools)}\nOr ${SET_TLC_VARS}`,
+    );
+  } finally {
+    fs.rmSync(empty, { recursive: true, force: true });
+  }
+}
+
+export function cannotRunTlc({ java, jar }, r) {
+  const said = `java exited ${r.status ?? r.signal}:\n${indent(`${r.stderr}${r.stdout}`.trim())}`;
+  return `cannot run TLC with ${java} -cp ${jar}: ${r.error?.message ?? said}\nFix that, or ${SET_TLC_VARS}`;
+}

package/skills/statechart/scripts/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "strict": true,
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "module": "nodenext",
+    "types": ["node"]
+  }
+}

package/skills/statechart/scripts/ways-in.mjs

@@ -0,0 +1,69 @@
+import { joinAnd } from "./lib.mjs";
+import { badOf, reachableAvoiding } from "./bug-states.mjs";
+
+export function stepsIntoBugs(cs, m, raw, { story, summary, next }) {
+  if (!cs.length || (!story && !summary)) return cs;
+  const { graph: g, stateKeys } = m;
+  const unnamed = new Set(next);
+  const rules = new Set(cs.map((c) => c.invariant));
+  const clean = new Map([...rules].map((r) => [r, reachableAvoiding(m, badOf(raw, r))]));
+  const byEnd = new Map();
+  for (const c of cs) for (const k of c.ends) byEnd.set(k, [...(byEnd.get(k) ?? []), c]);
+  const ways = new Map(cs.map((c) => [c, { steps: new Map(), n: 0, nameless: 0, action: null }]));
+  for (const e of g.edges) {
+    const into = byEnd.get(stateKeys.get(e.to))?.filter((c) => clean.get(c.invariant).has(e.from));
+    if (!into?.length) continue;
+    const [before, after] = [g.nodes.get(e.from).vars, g.nodes.get(e.to).vars];
+    const label = m.step(e.action, before, after) || e.action;
+    const moves = m.key(before) !== m.key(after);
+    for (const c of into) {
+      const w = ways.get(c);
+      const s = w.steps.get(label) ?? { n: 0, moves: false };
+      w.steps.set(label, { n: s.n + 1, moves: s.moves || moves });
+      w.n++;
+      if (!unnamed.has(e.action)) continue;
+      w.nameless++;
+      w.action = e.action;
+    }
+  }
+  const starts = [...g.nodes.values()].filter((n) => n.init).map((n) => stateKeys.get(n.id));
+  return cs.map((c) => {
+    const { steps, n, nameless, action } = ways.get(c);
+    const lastSteps = [...steps]
+      .sort((a, b) => b[1].n - a[1].n || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+      .map(([l]) => l);
+    const onPath = new Set(c.path.slice(1).map((p) => p.label));
+    const startsIn = starts.filter((k) => c.ends.has(k)).length;
+    return {
+      ...c,
+      lastSteps,
+      keptSteps: new Set(lastSteps.filter((l) => !steps.get(l).moves && !onPath.has(l))),
+      nameless: nameless ? { action, all: nameless === n } : null,
+      waysIn: n + startsIn,
+      startsHere: startsIn > 0,
+    };
+  });
+}
+
+export function waysLine(c) {
+  const quoted = c.lastSteps.map(
+    (l) => `"${l}"${c.keptSteps.has(l) ? " (the state stays the same)" : ""}`,
+  );
+  const named = quoted.slice(0, 5);
+  const more = quoted.length - named.length;
+  const list = joinAnd(more ? [...named, `${more} more`] : named);
+  const steps = c.nameless
+    ? `In the model, steps labeled ${list} lead into this bug. TLC names ${c.nameless.all ? "them" : "some of them"} ${c.nameless.action}, the whole next-state action, so the story cannot count them.`
+    : c.lastSteps.length === 1
+      ? `In the model, one step leads into this bug: ${list}.`
+      : c.lastSteps.length
+        ? `In the model, ${c.lastSteps.length} different steps lead into this bug: ${list}.`
+        : "";
+  const start = !c.startsHere
+    ? ""
+    : steps
+      ? "The model can also start in this bug."
+      : "The model starts in this bug.";
+  const shortest = c.waysIn > 1 ? "The steps below are the shortest path that TLC found." : "";
+  return [steps, start, shortest].filter(Boolean).join(" ");
+}

package/skills/statechart/scripts/worker.ts

@@ -0,0 +1,35 @@
+import { Buffer } from "node:buffer";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { inspect } from "node:util";
+import { checkView } from "./frontends/view.ts";
+import { compile } from "./pipeline.ts";
+import { check, messageOf } from "./run.ts";
+
+const [stage, specFile, configFile, viewFile] = process.argv.slice(2);
+
+try {
+  const view = checkView(
+    viewFile ? await import(pathToFileURL(path.resolve(viewFile)).href) : {},
+    inspect,
+  );
+  const { files, exit } = compile(await check(specFile, configFile), view);
+  const draft = path.join(stage, "draft");
+  fs.mkdirSync(draft);
+  for (const [name, parts] of files) {
+    const fd = fs.openSync(path.join(draft, name), "wx");
+    try {
+      for (const part of parts)
+        fs.writeSync(fd, typeof part === "string" ? Buffer.from(part) : part);
+      fs.writeSync(fd, "\n");
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+  fs.renameSync(draft, path.join(stage, "done"));
+  process.exit(exit);
+} catch (error) {
+  console.error(messageOf(error));
+  process.exit(2);
+}

package/skills/swarm/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: swarm
+description: "Fan out N parallel workers, drain them, and return one report. Use for /swarm, 'swarm this', or parallel coverage, races, gauntlets, and exploration."
+disable-model-invocation: true
+---
+
+<!-- Generated by scripts/semantics/generate.mjs; edit the source mapping/adapter, not this file. -->
+
+# Pi adapter for the pinned pstack source
+
+The behavior source is the `vendor/upstream/0.15.36/pstack/` snapshot at `c742dd61706fbacc1b95f1a20b7b988cf096ce6c`. Generated supported Skill/playbook entrypoints retain the upstream Markdown after this Pi prelude. The eleven core workflows have critical-rule mappings; preserving a source body does not prove that a model followed it. The full source inventory is pinned separately; maintainer semantic sign-off remains pending.
+
+Apply user instructions and repository authority first. Read referenced source Markdown through `pstack_skill` with `upstream/skills/<skill>/...` resource IDs, consuming every page. Statechart's 0.15.36 TypeScript runtime and its test corpus are bundled under `skills/statechart/scripts`; the older 0.15.32 `.mjs` tools are retained for compatibility. Java/TLC and optional renderers are external dependencies. Other Cursor plugins, private APIs, drivers and cloud resources are not supplied.
+
+For Statechart execution, run `node <skill-dir>/../../dist/statechart/statechart.js SPEC.tla [--config FILE] [--view FILE] [--out DIR]`. This compiled copy is required in installed packages because Node does not strip TypeScript inside `node_modules`. The upstream source and test corpus remain unchanged.
+
+## Platform substitutions
+
+- Task workers use `pstack_agents` and `pstack_workflow` Pi AgentSessions. The parent owns the playbook. Parallel writers use Git worktrees; integrated delivery uses an explicit integrator and verification. These are local processes, not cloud VMs or OS sandboxes.
+- `/setup-pstack` previews model roles and suggested panels using models visible in the current Pi session; edit only what needs changing. Existing choices are preserved. Panels with the same model in several seats do not provide model diversity. Model roles use `models.json`; pass the playbook and, for named roles such as Reflect's `tooling`, `judgment`, `divergent`, and `synthesizer`, `modelRole` when dispatching. Explicit node models take precedence.
+- Pi `thinkingLevel` replaces Cursor's reasoning slug conventions. Optional same-family fallback chooses a registered model from the same provider and reports it; a supported lower reasoning level may be used and reported. Unknown families are not guessed, Cursor `-fast` aliases are not rewritten, and authentication/inference failures are not automatically retried.
+- For an unconfigured panel, plans suggest available Pi models and disclose repeated seats. Unresolvable configured seats are dropped or replaced with an available survivor or the parent, with notes. A known-family parent gets a judge only from another recognized family; if none is available, the plan produces candidates only and the coordinator must inspect, choose, integrate and verify them. A failed or unaccepted candidate is excluded only after the other candidates settle; verified survivors remain eligible and the dropout is recorded.
+- Arena's cross-judge uses confined `pstack_candidates` access to verified worktrees. The integrator independently reads and compares candidates before selecting and grafting. Architect's template includes a separate implementation phase after the selected sketch; the coordinator still owns upstream grounding (`how`/`why`) and optional checkpoints.
+- Interrogate creates a worktree for each adversary, copies the reviewed staged, unstaged and untracked changes, and runs a separate repro-verifier on each worktree. No adversary changes are integrated. Both sessions must report command, observed and expected output; synthesis can only carry reproductions present in a verifier report. These sessions use Pi's ordinary writable-agent shell permissions; the verification-policy allowlist controls native gate commands, not their interactive shell. Model reports are not independently attested receipts: the coordinator must inspect actual command evidence and the effect of any repro edits before claiming a finding is verified.
+- Swarm supports partition, best-of, first-pass and rank-all race templates. First-pass waits for a candidate's deterministic acceptance, requests cooperative cancellation of the remaining sessions, and waits for them to settle. Rank-all reports every rank without automatically integrating a winner. Mixed partition/race still needs an explicit DAG.
+- Custom Mode maps to sticky `/poteto-mode`. `/loop` maps to `/pstack-loop`, which requires an active Pi host and cannot promise cloud-root scheduling or exact delivery across a crash.
+- Use an available named CLI/UI driver for real-surface proof. Without one, return blocked or inconclusive with the exact reason; unit tests, fake providers and worker reports cannot replace a live lane.
+
+## Explicit policy deviations
+
+- Native exact-head/base ledgers invalidate verification when either changes, including patch-preserving restacks; upstream can reuse some patch-ID-stable verdicts.
+- Read-only reviewer, scout and verifier sessions inspect confined source and evidence but cannot run shell commands or live MCP. Deterministic commands run in an authorized runner or writable lane. For external investigation, the parent supplies evidence snapshots and verifies decisive citations.
+- Autopilot templates prepare local DAG artifacts. The coordinator remains responsible for the owner lifecycle, early PRs, periodic audit, rebase discipline, countersigns and stop propagation. A stack template alone does not deliver a remote PR stack. Babysit stops at merge-ready; shipping and remote writes require the actual applicable authorization.
+- Opening a PR does not start a babysit. Finish the phase or stack before a requested babysit unless an explicitly assigned full-autonomy owner owns the loop and has reported code-ready. Babysit stops before merge; operator-reserved items never merge automatically.
+
+## Unsupported operations
+
+`Cursor-private-PR-provenance`, `Cursor-watch-READY`, `Cursor-cleanup-plugin` and `Bugbot-pass-dismissal` are unsupported. GitHub/Origin and native states are alternatives with their own evidence boundaries, not proof that a Cursor operation ran. `make-bot-ui` and the Cursor automation event pack require Cursor-specific surfaces. Report these limitations rather than marking unavailable operations complete.
+
+## Evidence boundary
+
+`SEMANTICS.json` records selected critical-rule mappings, exact source lines, deviations, bound tests and file fingerprints. Inventory counts, source hashes, deterministic checks, Pi SDK/fake-provider tests, real-model runs and maintainer semantic review are separate evidence levels. Advancing the source pin and passing CI do not establish complete Cursor/Pi equivalence or maintainer approval.
+
+
+---
+
+## Pinned upstream instructions
+
+Source: cursor/plugins@c742dd61706fbacc1b95f1a20b7b988cf096ce6c, pstack/skills/swarm/SKILL.md. The following body is retained verbatim.
+
+
+# Swarm
+
+## Start
+
+Open a todolist with one entry per phase before launching anything.
+
+1. Frame
+2. Fan out
+3. Aggregate
+4. Report
+
+## Phase A: Frame
+
+1. State the done predicate and the artifact or report the swarm must return.
+2. Choose the shape. Partition into slices, race N workers on identical briefs, or mix both. For a race or mixed shape, declare `first pass`, `rank all`, or `best-of` before spawning.
+3. Pick the worker model from the `swarm workers` line in `~/.cursor/rules/pstack-models.mdc`. If the rule or that line is missing, use `grok-4.7-xhigh-fast`. For `auto` or `inherit-parent`, omit `model` so the workers run on the parent model. If the Task tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message. For a model race, name each arm's model up front. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill.
+4. Give each worker its own writable output when it writes. When workers verify or measure commits, each brief names the exact SHAs. A measurement brief also names the method (sample count, what one sample is, order). The worker records both in its result.
+
+## Phase B: Fan out
+
+Spawn all N workers in one message with `subagent_type: generalPurpose`, `environment: "cloud"`, `run_in_background: true`, and the step 3 model, left unset for `auto` or `inherit-parent`. Use `environment: "local"` only when the worker needs access to something on the user's computer.
+
+When a worker must start from a non-default pushed branch, pass `cloud_base_branch`.
+
+Every brief stands alone. Include the goal, scope, exact slice or race arm, how to verify, and what to report. Reports use `PASS`, `ISSUES`, or `BLOCKED` with evidence. A worker that can prove a defect reports `ISSUES` and lists every issue it can prove, not only the first.
+
+If a worker drops out, proceed with N-1 and note it.
+
+## Phase C: Aggregate
+
+Read the terminal results. Drop a result that does not record the SHAs and method its brief names, and respawn that worker once. After a second miss, record a gap. A gap does not count as a pass. For coverage, every required slice needs a result. For a race, apply the selection rule declared up front. Use first pass, rank all, or best-of. Do not paste raw worker dumps.
+
+## Phase D: Report
+
+Return one consolidated in-chat report with a result table, issue one-liners, gaps or dropouts, and the race rule when used.
+
+
+## Pi execution tools
+
+Use `pstack_agents` for one child and `pstack_workflow` / `pstack_graph` for an explicit DAG. Roles are `architect`, `worker`, `reviewer`, `verifier`, `synthesizer` and `integrator`. Parallel writers use isolated worktrees, then an integrator. A verifier directly depends on the artifact owner. Inspect workflow status on recovery; completed nodes are not replayed. Check remote state before retrying external effects. `pstack_worktrees` cleans only owned clean worktrees.

package/skills/tdd/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: tdd
+description: "Use only when the user explicitly asks for TDD, a failing test, or a regression test, OR when the bug has an obvious cheap local test target. Skip when the test path is unclear, expensive, integration-heavy, or not requested."
+disable-model-invocation: true
+---
+
+<!-- Generated by scripts/semantics/generate.mjs; edit the source mapping/adapter, not this file. -->
+
+# Pi adapter for the pinned pstack source
+
+The behavior source is the `vendor/upstream/0.15.36/pstack/` snapshot at `c742dd61706fbacc1b95f1a20b7b988cf096ce6c`. Generated supported Skill/playbook entrypoints retain the upstream Markdown after this Pi prelude. The eleven core workflows have critical-rule mappings; preserving a source body does not prove that a model followed it. The full source inventory is pinned separately; maintainer semantic sign-off remains pending.
+
+Apply user instructions and repository authority first. Read referenced source Markdown through `pstack_skill` with `upstream/skills/<skill>/...` resource IDs, consuming every page. Statechart's 0.15.36 TypeScript runtime and its test corpus are bundled under `skills/statechart/scripts`; the older 0.15.32 `.mjs` tools are retained for compatibility. Java/TLC and optional renderers are external dependencies. Other Cursor plugins, private APIs, drivers and cloud resources are not supplied.
+
+For Statechart execution, run `node <skill-dir>/../../dist/statechart/statechart.js SPEC.tla [--config FILE] [--view FILE] [--out DIR]`. This compiled copy is required in installed packages because Node does not strip TypeScript inside `node_modules`. The upstream source and test corpus remain unchanged.
+
+## Platform substitutions
+
+- Task workers use `pstack_agents` and `pstack_workflow` Pi AgentSessions. The parent owns the playbook. Parallel writers use Git worktrees; integrated delivery uses an explicit integrator and verification. These are local processes, not cloud VMs or OS sandboxes.
+- `/setup-pstack` previews model roles and suggested panels using models visible in the current Pi session; edit only what needs changing. Existing choices are preserved. Panels with the same model in several seats do not provide model diversity. Model roles use `models.json`; pass the playbook and, for named roles such as Reflect's `tooling`, `judgment`, `divergent`, and `synthesizer`, `modelRole` when dispatching. Explicit node models take precedence.
+- Pi `thinkingLevel` replaces Cursor's reasoning slug conventions. Optional same-family fallback chooses a registered model from the same provider and reports it; a supported lower reasoning level may be used and reported. Unknown families are not guessed, Cursor `-fast` aliases are not rewritten, and authentication/inference failures are not automatically retried.
+- For an unconfigured panel, plans suggest available Pi models and disclose repeated seats. Unresolvable configured seats are dropped or replaced with an available survivor or the parent, with notes. A known-family parent gets a judge only from another recognized family; if none is available, the plan produces candidates only and the coordinator must inspect, choose, integrate and verify them. A failed or unaccepted candidate is excluded only after the other candidates settle; verified survivors remain eligible and the dropout is recorded.
+- Arena's cross-judge uses confined `pstack_candidates` access to verified worktrees. The integrator independently reads and compares candidates before selecting and grafting. Architect's template includes a separate implementation phase after the selected sketch; the coordinator still owns upstream grounding (`how`/`why`) and optional checkpoints.
+- Interrogate creates a worktree for each adversary, copies the reviewed staged, unstaged and untracked changes, and runs a separate repro-verifier on each worktree. No adversary changes are integrated. Both sessions must report command, observed and expected output; synthesis can only carry reproductions present in a verifier report. These sessions use Pi's ordinary writable-agent shell permissions; the verification-policy allowlist controls native gate commands, not their interactive shell. Model reports are not independently attested receipts: the coordinator must inspect actual command evidence and the effect of any repro edits before claiming a finding is verified.
+- Swarm supports partition, best-of, first-pass and rank-all race templates. First-pass waits for a candidate's deterministic acceptance, requests cooperative cancellation of the remaining sessions, and waits for them to settle. Rank-all reports every rank without automatically integrating a winner. Mixed partition/race still needs an explicit DAG.
+- Custom Mode maps to sticky `/poteto-mode`. `/loop` maps to `/pstack-loop`, which requires an active Pi host and cannot promise cloud-root scheduling or exact delivery across a crash.
+- Use an available named CLI/UI driver for real-surface proof. Without one, return blocked or inconclusive with the exact reason; unit tests, fake providers and worker reports cannot replace a live lane.
+
+## Explicit policy deviations
+
+- Native exact-head/base ledgers invalidate verification when either changes, including patch-preserving restacks; upstream can reuse some patch-ID-stable verdicts.
+- Read-only reviewer, scout and verifier sessions inspect confined source and evidence but cannot run shell commands or live MCP. Deterministic commands run in an authorized runner or writable lane. For external investigation, the parent supplies evidence snapshots and verifies decisive citations.
+- Autopilot templates prepare local DAG artifacts. The coordinator remains responsible for the owner lifecycle, early PRs, periodic audit, rebase discipline, countersigns and stop propagation. A stack template alone does not deliver a remote PR stack. Babysit stops at merge-ready; shipping and remote writes require the actual applicable authorization.
+- Opening a PR does not start a babysit. Finish the phase or stack before a requested babysit unless an explicitly assigned full-autonomy owner owns the loop and has reported code-ready. Babysit stops before merge; operator-reserved items never merge automatically.
+
+## Unsupported operations
+
+`Cursor-private-PR-provenance`, `Cursor-watch-READY`, `Cursor-cleanup-plugin` and `Bugbot-pass-dismissal` are unsupported. GitHub/Origin and native states are alternatives with their own evidence boundaries, not proof that a Cursor operation ran. `make-bot-ui` and the Cursor automation event pack require Cursor-specific surfaces. Report these limitations rather than marking unavailable operations complete.
+
+## Evidence boundary
+
+`SEMANTICS.json` records selected critical-rule mappings, exact source lines, deviations, bound tests and file fingerprints. Inventory counts, source hashes, deterministic checks, Pi SDK/fake-provider tests, real-model runs and maintainer semantic review are separate evidence levels. Advancing the source pin and passing CI do not establish complete Cursor/Pi equivalence or maintainer approval.
+
+
+---
+
+## Pinned upstream instructions
+
+Source: cursor/plugins@c742dd61706fbacc1b95f1a20b7b988cf096ce6c, pstack/skills/tdd/SKILL.md. The following body is retained verbatim.
+
+
+# TDD Bug Fix
+
+When fixing a bug with a clear, cheap test path, make the broken behavior executable before changing production code. The goal is a focused regression test that fails before the fix and passes after it.
+
+Do not force a test when it would be impractical. If the available test would require broad harness setup, brittle mocks, slow end-to-end infrastructure, production-only state, vague reproduction steps, or large unrelated fixture churn, skip adding a new test and use the closest useful verification instead.
+
+## Workflow
+
+1. **Understand the bug.** Identify the intended behavior, current behavior, affected path, and smallest observable reproduction.
+2. **Choose the narrowest executable check.** Prefer the closest unit, component, integration, or regression test already used for that codepath. If no practical test path is obvious, do not create one from scratch just to satisfy the workflow.
+3. **Write the failing test first.** Add the smallest focused test that would have caught the bug. The test should encode intended behavior, not mirror the current implementation.
+4. **Run the new test before fixing.** Confirm it fails for the intended reason. If it passes or fails for an unrelated reason, correct the test or reproduction before editing the implementation.
+5. **Fix the bug.** Make the smallest production change that satisfies the intended behavior while preserving nearby contracts.
+6. **Rerun the regression test.** Confirm the test now passes.
+
+## If a Failing Test Is Impractical
+
+Use the closest executable regression check instead: a targeted script, manual reproduction command, browser automation, snapshot comparison, log assertion, or focused integration check.
+
+Prefer no new test over a bad test. A bad test is one that mostly tests mocks, encodes current implementation details, depends on timing or unrelated global state, needs expensive infrastructure for a small fix, or would be deleted immediately after proving the fix.
+
+## Guardrails
+
+- Do not change tests merely to match a wrong implementation.
+- Do not weaken existing assertions unless the expected behavior has genuinely changed and the reason is clear.
+- Keep the regression test focused on the bug. Avoid broad fixture churn or unrelated coverage expansion.
+- If the bug is flaky, make the test deterministic where possible and document the signal being locked down.
+- If the bug exposes a broader class of failures, first land the focused regression path, then consider additional sibling coverage.
+
+## Final Response
+
+Report the evidence, not just the outcome:
+
+- Name the failing-before test or executable check and the failure it produced.
+- Name the passing-after test run and any nearby validation performed.
+- If failing-before evidence could not be demonstrated, state why and describe the closest regression check used instead.
+
+
+## Pi execution tools
+
+Use `pstack_agents` for one child and `pstack_workflow` / `pstack_graph` for an explicit DAG. Roles are `architect`, `worker`, `reviewer`, `verifier`, `synthesizer` and `integrator`. Parallel writers use isolated worktrees, then an integrator. A verifier directly depends on the artifact owner. Inspect workflow status on recovery; completed nodes are not replayed. Check remote state before retrying external effects. `pstack_worktrees` cleans only owned clean worktrees.

package/skills/teach/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: teach
+description: "Explain a body of work plainly so a person actually understands it. Runs the `how` and `why` skills and weaves what they find into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me'."
+disable-model-invocation: true
+---
+
+<!-- Generated by scripts/semantics/generate.mjs; edit the source mapping/adapter, not this file. -->
+
+# Pi adapter for the pinned pstack source
+
+The behavior source is the `vendor/upstream/0.15.36/pstack/` snapshot at `c742dd61706fbacc1b95f1a20b7b988cf096ce6c`. Generated supported Skill/playbook entrypoints retain the upstream Markdown after this Pi prelude. The eleven core workflows have critical-rule mappings; preserving a source body does not prove that a model followed it. The full source inventory is pinned separately; maintainer semantic sign-off remains pending.
+
+Apply user instructions and repository authority first. Read referenced source Markdown through `pstack_skill` with `upstream/skills/<skill>/...` resource IDs, consuming every page. Statechart's 0.15.36 TypeScript runtime and its test corpus are bundled under `skills/statechart/scripts`; the older 0.15.32 `.mjs` tools are retained for compatibility. Java/TLC and optional renderers are external dependencies. Other Cursor plugins, private APIs, drivers and cloud resources are not supplied.
+
+For Statechart execution, run `node <skill-dir>/../../dist/statechart/statechart.js SPEC.tla [--config FILE] [--view FILE] [--out DIR]`. This compiled copy is required in installed packages because Node does not strip TypeScript inside `node_modules`. The upstream source and test corpus remain unchanged.
+
+## Platform substitutions
+
+- Task workers use `pstack_agents` and `pstack_workflow` Pi AgentSessions. The parent owns the playbook. Parallel writers use Git worktrees; integrated delivery uses an explicit integrator and verification. These are local processes, not cloud VMs or OS sandboxes.
+- `/setup-pstack` previews model roles and suggested panels using models visible in the current Pi session; edit only what needs changing. Existing choices are preserved. Panels with the same model in several seats do not provide model diversity. Model roles use `models.json`; pass the playbook and, for named roles such as Reflect's `tooling`, `judgment`, `divergent`, and `synthesizer`, `modelRole` when dispatching. Explicit node models take precedence.
+- Pi `thinkingLevel` replaces Cursor's reasoning slug conventions. Optional same-family fallback chooses a registered model from the same provider and reports it; a supported lower reasoning level may be used and reported. Unknown families are not guessed, Cursor `-fast` aliases are not rewritten, and authentication/inference failures are not automatically retried.
+- For an unconfigured panel, plans suggest available Pi models and disclose repeated seats. Unresolvable configured seats are dropped or replaced with an available survivor or the parent, with notes. A known-family parent gets a judge only from another recognized family; if none is available, the plan produces candidates only and the coordinator must inspect, choose, integrate and verify them. A failed or unaccepted candidate is excluded only after the other candidates settle; verified survivors remain eligible and the dropout is recorded.
+- Arena's cross-judge uses confined `pstack_candidates` access to verified worktrees. The integrator independently reads and compares candidates before selecting and grafting. Architect's template includes a separate implementation phase after the selected sketch; the coordinator still owns upstream grounding (`how`/`why`) and optional checkpoints.
+- Interrogate creates a worktree for each adversary, copies the reviewed staged, unstaged and untracked changes, and runs a separate repro-verifier on each worktree. No adversary changes are integrated. Both sessions must report command, observed and expected output; synthesis can only carry reproductions present in a verifier report. These sessions use Pi's ordinary writable-agent shell permissions; the verification-policy allowlist controls native gate commands, not their interactive shell. Model reports are not independently attested receipts: the coordinator must inspect actual command evidence and the effect of any repro edits before claiming a finding is verified.
+- Swarm supports partition, best-of, first-pass and rank-all race templates. First-pass waits for a candidate's deterministic acceptance, requests cooperative cancellation of the remaining sessions, and waits for them to settle. Rank-all reports every rank without automatically integrating a winner. Mixed partition/race still needs an explicit DAG.
+- Custom Mode maps to sticky `/poteto-mode`. `/loop` maps to `/pstack-loop`, which requires an active Pi host and cannot promise cloud-root scheduling or exact delivery across a crash.
+- Use an available named CLI/UI driver for real-surface proof. Without one, return blocked or inconclusive with the exact reason; unit tests, fake providers and worker reports cannot replace a live lane.
+
+## Explicit policy deviations
+
+- Native exact-head/base ledgers invalidate verification when either changes, including patch-preserving restacks; upstream can reuse some patch-ID-stable verdicts.
+- Read-only reviewer, scout and verifier sessions inspect confined source and evidence but cannot run shell commands or live MCP. Deterministic commands run in an authorized runner or writable lane. For external investigation, the parent supplies evidence snapshots and verifies decisive citations.
+- Autopilot templates prepare local DAG artifacts. The coordinator remains responsible for the owner lifecycle, early PRs, periodic audit, rebase discipline, countersigns and stop propagation. A stack template alone does not deliver a remote PR stack. Babysit stops at merge-ready; shipping and remote writes require the actual applicable authorization.
+- Opening a PR does not start a babysit. Finish the phase or stack before a requested babysit unless an explicitly assigned full-autonomy owner owns the loop and has reported code-ready. Babysit stops before merge; operator-reserved items never merge automatically.
+
+## Unsupported operations
+
+`Cursor-private-PR-provenance`, `Cursor-watch-READY`, `Cursor-cleanup-plugin` and `Bugbot-pass-dismissal` are unsupported. GitHub/Origin and native states are alternatives with their own evidence boundaries, not proof that a Cursor operation ran. `make-bot-ui` and the Cursor automation event pack require Cursor-specific surfaces. Report these limitations rather than marking unavailable operations complete.
+
+## Evidence boundary
+
+`SEMANTICS.json` records selected critical-rule mappings, exact source lines, deviations, bound tests and file fingerprints. Inventory counts, source hashes, deterministic checks, Pi SDK/fake-provider tests, real-model runs and maintainer semantic review are separate evidence levels. Advancing the source pin and passing CI do not establish complete Cursor/Pi equivalence or maintainer approval.
+
+
+---
+
+## Pinned upstream instructions
+
+Source: cursor/plugins@c742dd61706fbacc1b95f1a20b7b988cf096ce6c, pstack/skills/teach/SKILL.md. The following body is retained verbatim.
+
+
+# Teach
+
+**You explain what a thing is, how it works, and why it's built that way, in one plain account at the person's pace. The goal is that they understand it, not that you change anything.**
+
+Teach sits on top of `how` and `why`. Get your bearings on what the work is and what it touches, then run `how` for how it works and `why` for why it's that way. Those are real skill invocations that do their own digging. Blend what they find into one plain explanation, lead with what matters to the person, and go deeper when they ask. Reword freely for teaching, with one exception. Keep `why`'s confidence language intact (its hedges are findings, not style).
+
+1. Decide the few things they should walk away understanding. Choose them from why they're asking (about to change it, reviewing it, debugging it, new to it) and what they already know, both read from the conversation, not quizzed out of them. Skip what they plainly already know. Put the depth where their question is.
+2. Let `how` and `why` do the work, don't redo it. Read the code yourself to get oriented, then run `how` for how it works and `why` for why. Run them in parallel and combine the results. Match the size to the question. Run both for a subsystem, maybe one is enough for a small change. Keep `why` narrow by default since its full sweep is slow. Put the narrowing in the ask itself (a scoped question, git plus a source or two) so `why` records the skipped categories per its own contract, and widen it only when the reasons are the point.
+3. Start with a plain definition. Name the thing and say what it is in general terms, the way a senior engineer would say it out loud, with its common name if it has one. Then tie it to the case in front of you ("in X, we use this to ...") and build from there: how it works, the deeper reasons, the edge cases. For each part, explain the idea so it clicks: the problem it solves and how it actually works. Walk through what happens as the person does the thing (opens a long chat, scrolls up) when that is what makes it land. Listing functions and constants is reference, not teaching. Don't print framing labels ("the one idea to hold onto", "the thing to walk away with", "the key insight", "at its core", "TL;DR"). Give the smallest complete answer first, a sentence or two, not a dense paragraph, then stop. Add layers when they ask. Never a wall of text.
+4. Keep it a conversation, not a lecture or a performance. Offer to go deeper or move on, and follow their lead. No quizzes. No pacing theater. Don't print "Pause", don't ask them to say it back, don't announce "the sentence to nail", and don't flag a part as important or hard ("here is the part worth slowing down on", "this is the tricky part", "here is where it gets interesting"). Just say it. When you would pause, stop and let them respond. Running one-shot with no live human, deliver it cleanly and put any offer to go deeper at the end.
+5. Show, don't only tell, and build the picture up diagram by diagram. Open the diff, the code, or the debugger when that is the fastest way to land it. Draw when a picture lands faster than words. For anything with three or more moving parts, do not draw one diagram with all of them at once. Draw a short series instead, where each diagram redraws the last and adds a single part, so the reader watches the system assemble. A single all-at-once diagram, especially one saved for the end, is a reference, not teaching. Concretely, to teach a flow from A to B to C, draw it three times. First A to B. Then redraw and add C. Then redraw and add the return edge or the next piece. Match the medium to the idea, and use both kinds when both help. A mermaid diagram fits a flow or structure where the labels carry the meaning. When the idea is spatial, like layout, overlap, scroll position, or a before and after, reach for the image-generation tool and draw it marker-on-whiteboard style with a few short labels, since image models garble long text. Generate that picture, don't settle for describing it in words. The build-up rule holds for generated images too. A single simple point needs no figure.
+
+Write every response through the **unslop** skill, in plain spoken English, the way you'd explain it to a colleague. Be tight, not terse. Cut filler and hedging, keep the part that makes it click. State the concrete mechanism, not a metaphor, a framing, or a preview of what is coming. This is the target density: "Virtualization runs in two parts, one for rendering and one for loading from disk. When an item scrolls out past the buffer, both its DOM node and its in-memory data are evicted." Normal sentence case, not all-lowercase. No em dashes. Prefer periods over commas. Keep each sentence to one or two commas. If clauses pile up, split them into separate sentences. Give each concept one name and keep it. Avoid mirror sentences ("A without B, or B without A") and tidy closers ("the rest follows", "it all falls out"). The words in these steps are directions to you, not labels to print. Don't echo the structure as headers or stock phrases.
+
+**Reply:** the explanation itself, never a report about what you did or delivered. Lead with the main point, then the plain account of what it is, how it works, and why, and the threads worth chasing with `how` or `why`.
+
+
+## Pi execution tools
+
+Use `pstack_agents` for one child and `pstack_workflow` / `pstack_graph` for an explicit DAG. Roles are `architect`, `worker`, `reviewer`, `verifier`, `synthesizer` and `integrator`. Parallel writers use isolated worktrees, then an integrator. A verifier directly depends on the artifact owner. Inspect workflow status on recovery; completed nodes are not replayed. Check remote state before retrying external effects. `pstack_worktrees` cleans only owned clean worktrees.