pi-pstack-native 0.0.0-stage → 1.0.0

package/skills/maintain-formal-verification-skill/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: maintain-formal-verification-skill
+description: "Bring a project's formal verification back in line with the code after the code changes: find the commits that touched verified code, update the model, harness, or properties to describe the code as it is now, rerun, and say whether each failure is drift in the verification or a bug in the code. Use for /maintain-formal-verification-skill, \"is the model still true to the code\", or after merges and refactors that touched verified code without rechecking it."
+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/maintain-formal-verification-skill/SKILL.md. The following body is retained verbatim.
+
+
+# Maintain a formal verification skill
+
+A formal check proves a property of what it describes. When the code changes and the verification does not, the check can keep passing while it describes code that no longer exists. That pass is the dangerous case, because it looks like a proof. This skill is the upkeep loop for a verify skill that `/create-formal-verification-skill` generated, or for any project-local skill that runs a model checker, prover, or code-level verifier against named code. The project-local skill handles a change that an agent makes while it uses that skill. This skill handles the changes that skipped it: merges, edits made without the skill, and drift that builds up across many commits.
+
+## Outcomes
+
+Give each check one outcome, and say which:
+
+- **in sync**: no change since the last sync alters what the check describes, and the check passes.
+- **updated**: the code changed, the verification now describes the new code, and the check passes.
+- **bug**: the verification describes the current code, and the code breaks the property. This is a finding about the code. It is not drift.
+- **blocked**: the check could not be brought back in line or could not run. Say exactly why.
+
+A check can be both updated and bug: the update makes the verification describe the code again, and then the property fails on it.
+
+## Edit scope
+
+Edit only the verification: models, harnesses, property files, and the verify skill itself. Never edit product code during a run, unless the user asks you to. When a property fails on the current code, do not weaken the property or the model to make it pass. Report the failure.
+
+## Pass
+
+1. **Find the checks.** A verify skill has no fixed name, so find it by what it does: a project skill that runs a model checker, a prover, or another verifier against named code. Read each one you find, or the one the user named. For each check, collect the property, the code it covers, the bounds and assumptions, the command that runs it, and the commit where it was last confirmed to describe the code. If no verify skill exists, stop and point at `/create-formal-verification-skill`. If the skill does not record a sync commit, use the last commit that changed the verification files, and say that you did.
+
+2. **Run it as it is.** Run each check once before you change anything, and record the result. A pass here does not tell you that the code is correct. It tells you that the old description still holds. A failure here can be drift or a bug. Do not decide which until step 5.
+
+3. **Read every change to covered code.** Diff the covered files from the sync commit to the current commit, and read each commit message. Also look for code that moved: a covered function that is renamed, split, or moved to another file is still covered code. Also look for new code that touches the state that a check guards, such as a new function that writes the same fields. For each change, decide which of these it is:
+   - **No effect.** The change does not alter anything the verification describes, such as formatting, comments, or code paths that the verification does not cover. Check this against the model or harness, not against the commit message.
+   - **The verification no longer describes the code.** A step that was one indivisible action is now two, a branch was added or removed, a check moved, a new path reaches the guarded state, or a value now has a different range. The model or harness must change.
+   - **The promise changed on purpose.** The change alters what the code promises, and evidence in the change says that this is intended: the doc comment, the tests, the changelog, or the commit message. The property must change, and you must cite that evidence.
+   - **The promise may be broken.** The code changed, and no evidence says that the promise changed. Treat a failure that follows as a bug candidate.
+
+4. **Update from the code, not from the result.** Change the model or harness so that each changed part again points to code that a reviewer can open, and keep one indivisible step in the code as one step in the verification. Write the update from the code before you rerun, and do not shape it by what makes the check pass. Change a property only for a promise that changed on purpose. Write down the old wording, the new wording, and the evidence. Keep the bounds unless the change makes them wrong. If you must reduce a bound, say so in the report.
+
+5. **Rerun and judge each result.**
+   - **Pass:** the check can now pass on a description that has lost the ability to fail. Break the new code the way the property guards against, such as removing a new check or reordering a new step, and confirm that the check catches it. Then drop the break.
+   - **Fail:** replay the counterexample against the real code, step by step. If a step cannot happen in the code, the verification is wrong. Fix the verification, and say what was wrong. If every step can happen, it is a bug. Name the commit that introduced it, tell the counterexample as a sequence of steps in the code's own words, and state the harm in one sentence. If a cheap test or reproduction against the real code shows the bug, add it to the report as evidence. Do not commit it to the product code.
+
+6. **Update the verify skill.** Update the code that each check covers, the commands, the bounds, the assumptions, and the sync commit. Set the sync commit to the commit that you checked. Do not move the sync commit for a blocked check, and say so in the report. Then follow the verify skill once as the next agent would, so that you know its steps still run.
+
+## Report
+
+Tell the user, for each check:
+
+- the outcome, and the commits that you read;
+- what changed in the verification and why, with a short reason for each change: the code changed shape, or the promise changed on purpose (with the evidence);
+- the rerun result, and the break that you used to show the updated check can still fail;
+- each bug, in plain words: the counterexample as steps in the code's words, the harm, and the commit that introduced it;
+- what the verification still does not cover, including new code that it should cover and does not.
+
+Say outright which failures were drift in the verification and which were bugs in the code. For a check that passed before you updated it and fails after, say that the old pass was on a stale description.
+
+Put the verification updates in a change of their own, separate from any product fix.
+
+
+## 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/maintain-verification-skill/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: maintain-verification-skill
+description: "Periodic pass that keeps a project's verification skill and feature map honest: parallel source readers per feature, one live session driving every feature, at most one PR of proven corrections. Use for /maintain-verification-skill or \"audit the verify skill\"."
+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/maintain-verification-skill/SKILL.md. The following body is retained verbatim.
+
+
+# Maintain a verification skill
+
+A feature map rots the moment the app changes. This skill is the upkeep loop for a skill generated by `/create-verification-skill` (or any project-local verification skill with a feature map). The unit of rigor is the feature, not every sentence: cover every feature file from source and exercise every feature live, without terminalising every bullet.
+
+## Outcomes
+
+Pick one, and say which:
+
+- **clean** — every feature got source and live coverage; nothing worth shipping. No branch, no PR.
+- **changed** — one PR ships proven doc, harness, or map corrections.
+- **blocked** — coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it.
+
+## Edit scope
+
+Only edit the verification skill's own directory (its SKILL.md, features/, and any harness scripts it owns). Never edit product code during a run: a behavior the map describes that the app no longer does is either doc drift (fix the map) or a product regression (report it, don't paper over it in docs).
+
+## Pass
+
+0. **Locate the target.** Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually `.cursor/skills/verify-*/`). Several candidates → ask which one; none → stop and point at `/create-verification-skill` instead of inventing a target.
+
+1. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
+
+2. **Source wave.** One read-only subagent per feature file, launched concurrently. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Children never drive the app and never edit files. Return shape: feature summary / source entry points / likely drift or none / one recipe.
+
+3. **Reconcile.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map — require a concrete source path before calling one missing.
+
+4. **Live pass.** Required even when source looks clean. The coordinator owns all driving; follow the verification skill's own launch model — one long-lived instance driven serially for servers and UIs, or a fresh isolated session per drive for short-lived CLIs (the skill's Launch section decides, not this one). Exercise every feature at least once, and hold three invariants the whole pass, whatever the failure: (1) never drive an instance you haven't health-checked since it last did something surprising — doctor before first drive, doctor on each fresh session where sessions are the unit, doctor again after any failed drive, and where doctor can't see the failure (a wedged UI state on a healthy process), reset to a known state or relaunch rather than hoping; (2) evidence captured so far survives every cleanup, checked at its named location, not assumed; (3) nothing a drive started outlives that drive's usefulness — failed-iteration residue is cleaned whether the session is stuck, exited, or shared (for a shared instance, clean the residue, not the instance). A doctor failure caused by skill drift is drift: fix it under edit scope and retry once — restart whatever the fix invalidated, nothing more — before calling the pass `blocked`. A feature that can't be reached is `verified-unreachable` only with the concrete prerequisite (auth, entitlement, OS, external state) and the route attempted; if the map omits that prerequisite, that's drift. Any harness fix from triage gets re-driven live before it ships. Final teardown happens after the last drive of the run — including those re-proofs — so nothing outlives the run (evidence stays, per the skill).
+
+5. **Triage.** Wrong or missing user-POV description → doc drift, fix it. Working behavior the harness can't drive → harness gap, fix it; a harness fix follows the same helpers rule as generation (scripts executable, invocation documented in the skill body). App behavior that's actually broken → product gap; record it for the user, keep it out of this PR.
+
+6. **Ship or stop.** For changed: one PR of proven corrections, re-read every changed file first. For clean or blocked: no PR, report the outcome and the coverage honestly.
+
+Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location; don't commit them.
+
+
+## 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/make-bot-ui/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: make-bot-ui
+description: "Compatibility notice for Cursor pstack's make-bot-ui skill. This capability is Cursor-specific and is not implemented by pi-pstack-native."
+disable-model-invocation: true
+---
+# make-bot-ui
+
+This upstream capability depends on Cursor-specific bot/webhook behavior. `pi-pstack-native` does not silently emulate it. Use the project's normal web/UI stack or another explicit Pi tool when the user asks for an equivalent product feature.

package/skills/ml-development/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: ml-development
+disable-model-invocation: true
+description: "Develop, debug, compare, evaluate, or reproduce machine learning and AI algorithms with explicit data splits, baselines, experiment budgets, and traceable evidence. Use for model training, algorithm implementation, hyperparameter tuning, evaluation, ablation, or reproducibility."
+---
+
+# ML algorithm development
+
+Help the user carry a concrete ML task through the applicable stages below. This is a Pi-native addition, not an upstream pstack playbook or a promise of autonomous training infrastructure. Adapt it to the task: traditional ML, deep learning, LLM/agent evaluation, or a user-provided algorithm. Do not fabricate measurements, data access, experiment runs, or claims of improvement.
+
+## Route and read
+
+1. Inspect the repository and existing instructions first. Find the data sources, code, configs, splits, metrics, commands, tracking system, and relevant hardware using available evidence; state what is unknown. Prefer existing project conventions and tools over introducing frameworks.
+2. Read the complete relevant bundled files, including every page when using `pstack_skill`:
+   - Goals, constraints or missing setup: `ml-development/playbooks/01-scope.md`.
+   - Data or split design: `ml-development/playbooks/02-data.md`.
+   - Baseline or implementation: `ml-development/playbooks/03-baseline.md`.
+   - Experiments, tuning or performance improvement: `ml-development/playbooks/04-experiments.md`.
+   - Model/LLM evaluation or comparison: `ml-development/playbooks/05-evaluation.md`.
+   - Reproduction, handoff or run audit: `ml-development/playbooks/06-reproducibility.md`.
+3. For a broad development request use the stages in order. For a narrow request, start at the relevant stage and check its prerequisites; do not manufacture missing results. If required data, labels, hardware, permission or a metric is unavailable, continue independent work and mark the dependent stage blocked or inconclusive.
+4. Keep decisions in the project's existing tracker or a project-local record. Use `references/run-record.md` as a minimum evidence schema and `references/experiment-matrix.md` for a concrete experiment plan. Paths and identifiers are examples, not permission to overwrite existing artifacts.
+
+## Rules for execution
+
+- Follow the user's scope, resource budget and repository instructions. Establish dataset access, storage, expected duration, compute availability, and an execution budget before paid, long-running or shared-resource jobs. Use authorization already given; if a material limit is missing, prepare a bounded plan and obtain the missing constraint before launching dependent work. Do not publish data, models or results or start remote jobs without authorization.
+- Pi child-agent token, cost and elapsed-time limits are not GPU-hour limits or operating-system supervision of spawned training processes. Without an authorized, bounded execution surface that can terminate and account for the full training process tree, prepare commands and a plan instead of launching long-running, remote or potentially unbounded training. A small, clearly bounded local smoke may run if permitted. Never report an unenforced budget as enforced.
+- Separate code tests, smoke runs, validation-set selection and final test evaluation. Never tune on the final test set. If an existing test set has influenced selection, disclose it and avoid claiming a clean independent test.
+- Fix the comparison protocol before experiments: dataset/version and split, primary metric and direction, baseline, budgets, train/eval commands, seeds, checkpoint selection, and acceptance thresholds or decision criteria. For paired comparisons use the same data and protocol; list differences that cannot be controlled.
+- Use appropriate split units and check leakage: group entities, timestamps, duplicates and related samples as the task requires; fit preprocessing on training data only. For LLMs also track prompts, decoding, model/provider versions and possible evaluation contamination.
+- Run a small, low-cost smoke only when within the user's scope. Record failures, timeouts, missing dependencies and partial runs; never present a partial or unavailable check as passed. Use repeated runs and uncertainty estimates when feasible, with the unit of independence stated. A single run is preliminary.
+- Keep training, evaluation, checkpoint and hardware evidence traceable. Models or datasets from the network are optional and require the access needed by the task. A seed alone does not guarantee determinism across devices, kernels, versions or distributed execution.
+- Treat verification-policy allowlists, role permissions and worktree boundaries as they actually exist. A worktree is not an OS sandbox; never use hidden credentials or private data in public artifacts. Ask for missing access only when necessary.
+- Do not conflate a passing code test, a completed training job, a passing benchmark metric and an accepted deployment decision. Report each separately with measured outcomes and limitations. Do not claim superiority from one noisy run or from unsupported metrics.
+
+## Pi integration
+
+Start explicitly with `/skill:ml-development <task>`; this Skill opts out of model-initiated discovery (`disable-model-invocation: true`) and ordinary ML requests do not auto-select it. `/poteto-mode <task>` does not automatically select these playbooks; explicitly request both when needed. Reuse existing `scout` and `architect` for investigation/design, `worker` for permitted changes, and read-only `reviewer` or `verifier` for evidence inspection. Read-only roles cannot run training or shell verification; use an authorized execution lane for checks and have the verifier inspect actual results. Use `pstack_workflow` only for real independent subagent tasks, not one agent per stage. No new ML role or training executor is provided by this Skill. Never infer that an upstream pstack skill has reviewed or approved this suite.

package/skills/ml-development/playbooks/01-scope.md

@@ -0,0 +1,14 @@
+# Scope and decision contract
+
+## Inputs
+User objective and success criteria; project code and prior results; dataset and label availability; constraints on compute, time, cost, privacy and deployment. Distinguish user-specified values from inferred assumptions.
+
+## Steps
+1. Identify the task, unit of prediction and intended use. For LLM or agent work define the task, model/provider, prompt and decoding, tool calls, evaluation cases and what counts as success.
+2. Define the primary metric, direction and a meaningful target or decision rule; list secondary metrics, failure costs and resource constraints. If data or the metric cannot be inferred, request what is essential while continuing a plan or code inspection.
+3. Locate a credible existing baseline or define a simple baseline and fair comparison protocol. Record current evidence and dependencies; do not infer a baseline from project claims.
+4. Define available data, split strategy, hardware, execution environment, run budget, reproducibility and outputs. Separate local CPU smoke work from costly GPU, remote or provider calls. Do not launch an unbounded sweep.
+5. Write a concise plan: stages, expected artifacts, checks, stop conditions, risks and blocked decisions. Reuse existing pipelines, test suites and experiment tracking when appropriate.
+
+## Output and gate
+A decision contract containing goal, metrics, baseline, data/split, constraints, budget, environment and evidence locations. If a required item is unknown, label it unknown and do not claim the dependent stage is ready. Continue tasks that do not need that item.

package/skills/ml-development/playbooks/02-data.md

@@ -0,0 +1,14 @@
+# Data and leakage checks
+
+## Inputs
+Accessible data and data dictionary, labels, split definitions, preprocessing and allowed use. Avoid copying raw private data into logs, issues or model prompts.
+
+## Steps
+1. Record dataset identity/version or immutable digest where available, source, license/access boundary, label definition, sample and group units, timestamp range, and any known label or collection biases. Count missing, duplicate, malformed and out-of-range values using safe aggregates.
+2. Identify independent units and split according to the task: grouped subjects/users, chronological cutoff for forecasting, or another justified split. Document stratification only if appropriate and feasible. Verify no group, duplicate or future information crosses the protected boundary.
+3. Split before fitting normalization, imputation, feature selection, tokenizers learned from task data, or other learned transforms; fit on training data only. Use the same transform for held-out examples. Do not treat arbitrary train/test random splitting as valid for time-series or grouped data.
+4. Reserve validation for model selection and a final test set for the predeclared final assessment. If the test set has already influenced decisions, record contamination and use an independent holdout if available; otherwise mark the conclusion limited.
+5. For generated/LLM evaluations, record case source/version, prompts, reference policy and potential benchmark contamination; separate deterministic checks from LLM-as-judge and calibrate any judge against labeled examples where available.
+
+## Output and gate
+A data/split manifest, checks and remaining risks. If splits, target leakage or the evaluation unit cannot be verified, stop claims about generalization; make the missing evidence explicit.

package/skills/ml-development/playbooks/03-baseline.md

@@ -0,0 +1,14 @@
+# Baseline and implementation
+
+## Inputs
+Decision contract, usable training/validation splits, project environment and executable baseline or source implementation.
+
+## Steps
+1. Capture the original code revision and dirty state, dataset/split IDs, command, configuration, dependency and hardware versions. Do not reset or overwrite user work.
+2. Choose a simple or existing baseline that can actually run under the same split and metric; state why it is relevant. When reproducing a paper, separate reported settings from inferred substitutions and identify gaps before implementation.
+3. Implement the smallest meaningful vertical slice: loader, model or algorithm, loss/objective, train/update, checkpoint, inference and evaluation. Preserve user conventions. Use one writer or isolated writers and an explicit integrator when parallel changes must be combined.
+4. Add meaningful checks for shapes, dtype, labels and edge cases; test loss/gradient finiteness, a tiny overfit or known synthetic case when appropriate, and ensure evaluation mode and preprocessing are consistent. A fake or synthetic check is not a real-data result.
+5. Run a bounded smoke only when resources and permissions allow; record exact invocation, actual output, runtime and failure. If there is no runnable data or hardware, deliver the implementation and a reproducible plan with the missing run marked not performed.
+
+## Output and gate
+Baseline evidence, implementation and test results. Do not call an algorithm reproduced or improved solely because code compiles, a smoke test passes, or a model describes the result.

package/skills/ml-development/playbooks/04-experiments.md

@@ -0,0 +1,14 @@
+# Experiments and optimization
+
+## Inputs
+Runnable baseline and validation protocol, objective/constraints, run/time/compute/cost limits and available tracking system.
+
+## Steps
+1. Express each hypothesis, mechanism, variable(s), range, expected direction and falsifying observation. Select a small matrix within the actual budget; mark dependencies and invalid combinations. When multiple factors interact, use an appropriate factorial or other design rather than insisting every experiment changes only one factor.
+2. Predefine the primary comparison and decision criteria, independent unit, seed/fold/replicate plan, and test budget. Compare baseline and candidate on matched splits and settings; separate exploratory tuning from confirmation. If the budget permits only one run, state that uncertainty remains.
+3. For each trial capture revision/dirty diff, data and split IDs, config, environment, seed, hardware, started/finished state, logs, checkpoint, metrics, runtime and resource usage. Preserve failed, pruned and partial trials. Do not label a pruned trial as a completed model.
+4. Run trials only within authorized resources. A child-agent token/time budget does not bound a spawned training process, GPU time or external billing. For long-running, shared, remotely billed or potentially unbounded training, require an execution surface authorized to enforce limits and terminate the process tree; otherwise produce the runnable command and mark execution `not run`. Use existing DVC, MLflow, Optuna or other tooling if present and appropriate; do not install or transmit data merely because this Skill mentions them.
+5. Compare changes in a table with matched baselines, uncertainty or replicate spread, cost and failure modes. Investigate confounding, data leakage, selection bias and run-to-run variation. Record accepted and rejected hypotheses and their evidence; do not repeatedly select against the final test.
+
+## Output and gate
+Experiment matrix, per-run records and a decision with the evidence and limits. No improvement claim without the actual comparable results; no statistical significance claim without a suitable analysis and enough independent observations.

package/skills/ml-development/playbooks/05-evaluation.md

@@ -0,0 +1,14 @@
+# Evaluation and comparison
+
+## Inputs
+Frozen candidate and baseline, predeclared metrics, locked evaluation split or cases, inference settings and available labels.
+
+## Steps
+1. Evaluate baseline and candidate using the same dataset version, split, preprocessing, metric implementation and output definition. For stochastic methods record seeds, sampling parameters and number of repeats. If any setting differs, disclose the confound rather than treating it as a controlled comparison.
+2. Report primary and relevant secondary metrics, denominator and unit; include failure/error cases and important slices with sample sizes. Use confidence intervals or paired comparisons appropriate to the sampling design where feasible; do not treat repeated predictions on one case as independent cases.
+3. For LLMs/agents record model/provider version, prompt or template, decoding, context, tool access, evaluation dataset and execution environment. Separate task pass rate from report format, tool availability, timeout, cost and operator acceptance. Inspect contamination and label uncertainty. A model judge is not ground truth without calibration.
+4. Report baseline and candidate latency, throughput, memory and cost only if actually measured, with hardware, batch size, warm-up and measurement method. Avoid extrapolating training throughput from one unrepresentative run.
+5. Freeze the choice before final holdout evaluation. If final evaluation is unavailable, contaminated, repeatedly inspected or insufficient for the decision, report that limitation and avoid claiming independent generalization.
+
+## Output and gate
+A compact comparison table with dataset/split, metrics, sample size, uncertainty, resource costs, evidence paths and failed or missing runs. Indicate whether thresholds and constraints are satisfied; never turn missing evidence into a pass.

package/skills/ml-development/playbooks/06-reproducibility.md

@@ -0,0 +1,13 @@
+# Reproduction and handoff
+
+## Inputs
+Experiment records, selected candidate and baseline, code and artifact access, and evaluation evidence.
+
+## Steps
+1. Link each claim to a run ID and evidence: code commit plus dirty changes, data/split version, configuration, dependency versions, hardware, seeds, command, logs and checkpoint. Capture missing or unavailable information as such.
+2. Where authorized and feasible, replay the selected run or a scaled-down verification on the stated surface and compare actual outputs to the recorded acceptance tolerance. A smoke replay shows the pipeline works at that scale; it does not prove the original metrics reproduce.
+3. Record nondeterministic operations, hardware/software variance, failed runs, limitations of external data/model versions, access restrictions and differences between original and replay. Never promise bitwise reproducibility from seed alone.
+4. Provide reproducible commands and paths, the measured baseline/candidate comparison, test evidence, unresolved risks and the next action. Separate an implementation-ready result from a validated model and from a deployment decision.
+
+## Output and gate
+A handoff that allows an authorized colleague to locate and reproduce the work, or a precise list of missing inputs and blocked steps. Do not upload datasets, checkpoints, logs or credentials without user authorization.

package/skills/ml-development/references/experiment-matrix.md

@@ -0,0 +1,11 @@
+# Experiment matrix template
+
+Fill from the task; the example illustrates a controlled comparison and is not evidence of a run.
+
+| ID | Hypothesis / change | Comparison | Split / seeds | Budget | Outcome / decision |
+| --- | --- | --- | --- | --- | --- |
+| baseline | Existing or simple baseline | — | Fixed validation split; recorded seeds | User-defined | Not run |
+| candidate-a | One justified algorithm change | baseline | Same split and matched seeds | User-defined | Not run |
+| confirmation | Repeat the chosen comparison | baseline | Predeclared independent replicates | User-defined | Not run |
+
+Before launch specify the primary metric and direction, acceptable regressions, limits on runtime/cost/compute, early-stop rule, and expected outputs. When interactions matter, record a factorial or other justified design rather than using this one-factor example. Keep the final test split outside iterative tuning.

package/skills/ml-development/references/run-record.md

@@ -0,0 +1,19 @@
+# Minimum run record
+
+Use the existing experiment tracker if one is available; otherwise create a project-local record appropriate to the project. A record is evidence only when its fields reflect an actual run.
+
+| Field | Record |
+| --- | --- |
+| Run ID and purpose | Baseline/candidate, hypothesis and linked task |
+| Code | Full Git commit and clean/dirty state; if dirty, save an authorized, recoverable patch or source snapshot, not only its hash |
+| Data | Immutable dataset ID, version or digest when available; recoverable split manifest with grouping/time cutoff and preprocessing fit scope; access/location rules |
+| Configuration | Saved resolved config and actual commands/arguments, model/weights, seeds and decoding if relevant; link to code that consumes them |
+| Environment | Dependency lockfile or environment export when available, OS, device/GPU, drivers and distributed setup |
+| State | Run ID, start/end, process exit status, completed/failed/pruned/blocked/not run, errors and reason |
+| Outcomes | Metric definitions, per-split scores, sample counts, runtime, memory/cost if measured |
+| Artifacts | Stable local or authorized tracker paths for logs, evaluation output, checkpoint and recovery metadata; content digests if available |
+| Caveats | Leakage/contamination checks, nondeterminism, missing data and deviations |
+
+A hash without the underlying recoverable patch, dataset, config or artifact is not a reproducibility guarantee. If a dependency cannot be preserved, record its availability and limitation explicitly. An independent replay on the specified environment can support reproducibility; a synthetic smoke only supports pipeline operability, and an independent scientific replication is a distinct claim.
+
+Never include credentials or raw private samples in a shareable record. Do not upload or copy restricted artifacts merely to satisfy a field. If a field is unknown, write `unknown` rather than guessing.

package/skills/no-comments/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: no-comments
+description: "Spawn Comment Sicko, fix accepted findings, and offer encodings for claimed constraints."
+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/no-comments/SKILL.md. The following body is retained verbatim.
+
+
+# No comments
+
+Spawn Comment Sicko. Act on accepted findings.
+
+Defer to Comment Sicko's fresh perspective.
+
+## Scope
+
+Use the caller's files or diff. Otherwise use the current diff against the base branch, default `main`, including the working tree.
+
+## Steps
+
+1. Spawn `Task` with `subagent_type: "comment-sicko"`. Pass the scope. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill. Do not restate its rules.
+2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, run `/how` or `/why` on their symbol. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail `/no-comments`.
+3. Fix trivial accepted flags directly by deleting a dead path, dropping a parameter, or using the real API. If any fix needs a shape, run `/architect` once for the accepted set and surrounding code. Stop at the sketch. Architect shapes. Step 4 implements.
+4. Implement the smallest root-cause fix in scope. Remove every named workaround. If the root cause is out of scope, land the smallest in-scope fix and report the rest open. The **principle-fix-root-causes** and **principle-redesign-from-first-principles** skills guide intent only. Neither authorizes widening the fence nor fixing instances outside it. Never bolt on symptom guards.
+5. Constraint comments say `do not remove`, `do not change wording`, or `talk to X before changing`. Leave keeps about things we cannot change. Offer the cheapest in-scope type, runtime, test, or CI lint. Wait for interactive approval. Unattended and eval require caller pre-approval. If approved, encode then delete. Otherwise delete, report the constraint open, and sketch out-of-scope work.
+6. Report the deletion count, restored comments, reruns, architect sketch, fixes, encoding offers, encodings, unenforced constraints, and other open work.
+
+
+## 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.