pi-pstack-native 0.0.0-stage → 1.0.0

package/docs/PUBLISHING.md

@@ -0,0 +1,61 @@
+# Release preparation
+
+The public repository is [2333sky/pi-pstack-native](https://github.com/2333sky/pi-pstack-native). The package manifest name is `pi-pstack-native`; GitHub availability does not mean an npm release exists. Current installation uses the Git source documented in the [project overview](../README.md).
+
+## Validate a candidate
+
+Use Node.js 22.19 or later and a clean checkout with the lockfile:
+
+```bash
+npm ci
+npm run check:release
+```
+
+The release chain includes source and semantic checks, tests, typecheck, build, Pi SDK host smoke, offline/fake-provider E2E, benchmark smoke, and a clean installed-tarball check. GitHub Actions also tests Node 22/24 and focused Windows persistence and build behavior. These checks are not authenticated model inference or a live GitHub delivery test. Record the exact commit and environment for any additional validation; see [semantic compatibility](SEMANTIC-COMPATIBILITY.md) and the [live test plan](LIVE-TEST-PLAN.zh-CN.md).
+
+`npm pack` runs the release chain through `prepack`. Publishing an already-created tarball does not rerun the package's lifecycle scripts, so validate the exact artifact before publication.
+
+## Prepare a release
+
+1. Review the version, changelog, package contents, license notices, dependency inventory, and [security policy](../SECURITY.md).
+2. Inspect CI and any external-model or GitHub test results separately; preserve unresolved issues and do not infer semantic sign-off from a green build.
+3. Choose whether a GitHub release or npm publication is appropriate and accurately describe the version and validation evidence.
+4. Create a tag, GitHub release, or npm publication only when the maintainer explicitly authorizes that external action. Registry ownership and availability must be checked at publication time.
+
+## Proposed 1.0.0 stable release
+
+The package manifest and lockfile may be prepared at `1.0.0` ahead of the actual release. **This is release preparation, not proof of production readiness or publication.** Do not tag, announce, or publish `1.0.0` until the remaining items below are closed.
+
+### Recorded evidence
+
+| Item | State | Record |
+| --- | --- | --- |
+| Authenticated real-model probe | Passed on `5deb723` for three models | [semantic smoke receipt](evidence/semantic-smoke-5deb723.json) |
+| Live GitHub pull request create, read, close and merge | Passed on `5deb723` against a disposable private repository | [live GitHub receipt](evidence/live-github-5deb723.json) |
+| npm name and version availability | `pi-pstack-native` returned `404` from the public registry on 2026-10-30, so no version is published and `1.0.0` is unclaimed | `npm view pi-pstack-native versions` |
+| npm publishing credentials | Absent in the validation environment; `npm whoami` returns `ENEEDAUTH` | — |
+| Maintainer semantic review | `signed-off` by `2333sky` at 2026-10-30T16:33:31Z | `SEMANTICS.json.review`; covers the 11 core entrypoints and their declared deviations |
+
+The live GitHub receipt covers one create/read/close/merge cycle on an unprotected repository with a single operator account. It does not cover branch protection, required reviews, auto-merge, a merge queue or concurrent delivery against the same pull request.
+
+### Open before 1.0.0
+
+- **Release-commit validation.** Validate the exact release commit with `npm ci`, `npm run check:release`, `npm pack --dry-run`, an inspected tarball, and successful CI; record any skipped acceptance as such.
+- **npm publication rights.** Ownership cannot be verified without credentials. Confirm at publication time that the publishing account holds the name.
+
+### Guarantee scope for 1.0.0
+
+`SEMANTICS.json.review` is `signed-off` by `2333sky` for the 11 core entrypoints and their declared deviations. The guarantee is deliberately narrower than full Cursor/Pi behavioural parity:
+
+- **Included.** Critical-rule mappings for the 11 core entrypoints, the declared Pi deviations, deterministic offline/fake-provider tests, the installed-package smoke, the three-model real-model probe, and live GitHub pull request create/read/close/merge on an unprotected repository.
+- **Excluded.** Windows real-model workflow acceptance. The only Windows real-model number is the user-reported 13/20 workflow acceptance plus a separate 20/20 per-case rerun at commit `4d75ea0b`. Neither is bound to a commit in this repository and neither was re-run for this candidate, so they are not part of the 1.0.0 guarantee. Do not present 13/20 and 20/20 as one result. The Windows evidence 1.0.0 does rest on is CI: atomic state persistence, the build check and five repetitions of the cross-process lock test on `windows-latest`.
+- **Excluded.** Branch protection, required reviews, auto-merge, merge queues and concurrent delivery against one pull request.
+- **Excluded.** Full behavioural parity with Cursor, review-swarm quality, and any live UI/CLI behaviour outside the recorded receipts.
+
+**Only after explicit maintainer approval**, a publisher with npm access and the applicable second-factor authorization may publish the reviewed commit with `npm publish --tag latest` (unscoped packages are public). Publishing a version without `--tag` also selects `latest`; spell it out to avoid ambiguity. Verify `npm view pi-pstack-native@1.0.0 version`, `npm dist-tag ls pi-pstack-native`, and an actual `pi install npm:pi-pstack-native` afterward. Create a Git tag/GitHub release only with release authorization.
+
+If the evidence gaps remain unacceptable, do not label this candidate stable: retain a prerelease version and publish it using `--tag next` instead.
+
+The earlier `0.6.0-preview.1` instructions were for the preview candidate and are not the stable release procedure.
+
+Earlier installation and release results are historical records: [installation check](../INSTALLATION-CHECK.md) and [release validation](VALIDATION.md).

package/docs/README.md

@@ -0,0 +1,30 @@
+# Documentation index
+
+[Project overview](../README.md) · [中文说明](../README.zh-CN.md)
+
+## Start and operate
+
+| Document | Purpose |
+| --- | --- |
+| [Chinese user guide](../README.zh-CN.md) | Installation, model setup, commands, workflows, and troubleshooting. |
+| [Runtime and maintainer reference](REFERENCE.md) | Agent and workflow behavior, recovery, scheduling, verification, benchmark, and upstream sync. |
+| [AI algorithm workflow](ML-WORKFLOWS.zh-CN.md) | Chinese guide to the ML Skill, experiment stages, and open-source tools. |
+| [Examples](../examples/README.md) | Strict briefs, policy, templates, CLI, and benchmark examples. |
+| [PR protocol](PR-PROTOCOL.md) | Evidence, stack preparation, and authorized delivery. |
+| [Statechart](STATECHART.md) | Statechart toolchain and external dependencies. |
+| [Live test plan](LIVE-TEST-PLAN.zh-CN.md) · [Windows test record](WINDOWS-MODEL-TEST.zh-CN.md) | Procedure and user-reported Windows model results. |
+
+## Maintain and review
+
+| Document | Purpose |
+| --- | --- |
+| [Contributing](../CONTRIBUTING.md) · [Security](../SECURITY.md) | Development workflow and vulnerability reporting. |
+| [Semantic compatibility](SEMANTIC-COMPATIBILITY.md) · [Parity](../PARITY.md) | Scope of adaptation, limitations, and evidence status. |
+| [Pi semantic adapter](PI-SEMANTIC-ADAPTER.md) | Platform substitutions and deliberate deviations. |
+| [Dependencies](DEPENDENCIES.md) · [Publishing](PUBLISHING.md) | Locked SDK, dependency review, and release preparation. |
+| [Upstream 0.15.36 upgrade](upstream-upgrade-0.15.36.md) · [PR #41 plan](PR-41-ALIGNMENT-PLAN.zh-CN.md) | Source changes, implementation plan, and evidence boundaries. |
+| [Changelog](../CHANGELOG.md) | Product changes and earlier version history. |
+
+## Historical records
+
+[Acceptance](../ACCEPTANCE.md), [installation check](../INSTALLATION-CHECK.md), [implementation notes](../IMPLEMENTATION.md), [original PRD](../PRD.md), and [release validation](VALIDATION.md) record earlier snapshots. Their package names, versions, test counts, and pending items describe those snapshots; consult the current compatibility documents and CI for present status. The `upstream-sync/` reports and `vendor/upstream/` snapshots retain provenance and are used by review and drift checks.

package/docs/REFERENCE.md

@@ -0,0 +1,357 @@
+# Runtime and maintainer reference
+
+[Documentation index](README.md) · [Project overview](../README.md) · [中文说明](../README.zh-CN.md)
+
+## Native agent tools
+
+The model receives Pi-native pstack tools:
+
+- `pstack_agents` — run/start/status/send/stop one bounded Pi child session. A background writable `start` defaults to a worktree so it cannot silently collide with the parent checkout.
+- `pstack_workflow` — run persistent dependency graphs with bounded concurrency and explicit integration semantics.
+- `pstack_graph` — lower-level explicit DAG edges.
+
+For code that must land in the user's checkout, prefer `pstack_workflow` over several independent `pstack_agents` starts. The workflow engine knows when to keep one writer local, isolate parallel writers, and require an integration owner.
+
+## Model setup and routing
+
+Run `/setup-pstack` in Pi's interactive UI. Choose a reasoning budget, then page through the role models, task overrides and suggested panels. Save the choices or edit individual roles, task roles or panel seats, including their order. The budget and fallback policy can be changed from the review screen. A new setup starts with `large` selected; a rerun selects the existing level. Existing values and unrelated configuration are preserved; cancelling before saving does not write a partial configuration. Fresh suggestions use models available to the session, prefer different recognized families for runner seats where possible, and report repeated seats. Registry visibility does not prove a successful inference.
+
+Unavailable explicit models and incompatible reasoning levels are marked in the preview and must be fixed before saving; the wizard stays open so a model, budget or fallback can be changed. `auto` and `inherit-parent` remain valid model aliases. If the configuration file is malformed, or changes while setup is open, setup stops without overwriting it.
+
+After a successful save, when a parent model is selected, setup starts a model turn to inspect the project for a real-app harness or `verify-*` Skill and for a project-local formal-verification Skill. If either is missing, the agent is instructed to offer its corresponding creation Skill and wait for the user's answer. This inspection and the subsequent conversation depend on the model and have not been proved by the configuration save itself; no verification Skill is created automatically. Without a parent model, setup reports the manual Skill commands instead.
+
+The `unlimited`, `large`, `medium`, and `small` budget choices map to Pi `max`, `xhigh`, `high`, and `medium` thinking levels. The optional `same-family` fallback selects a recognized family from the same provider or lowers an unsupported reasoning level, with a note; it does not switch providers, rewrite Cursor `-fast` slugs or retry authentication/inference errors. Legacy configurations without a policy retain `disabled`.
+
+Pass `playbook` to `pstack_agents` or `pstack_workflow` for task overrides; for named roles such as `reflect` tooling, judgment, divergent and synthesizer, pass `modelRole` as well. An explicit model wins over a named role, then a profile override, then the generic role default. The coordinator must actually supply the routing fields.
+
+Arena, architect and interrogate load configured panels; unconfigured panels use disclosed session-available suggestions. Unavailable seats are reported and replaced or dropped when possible. With a known parent family, arena/architect choose a judge only from a different recognized family; without one, their plan returns candidates for the coordinator to compare, integrate and verify. With a judge, verified worktrees are available through confined `pstack_candidates`, and failed candidates are recorded and excluded before comparing surviving verified work. Architect adds an implementation phase after the chosen sketch; the coordinator still owns grounding and any requested checkpoint.
+
+Interrogate copies the fixed target's staged, unstaged and untracked files into isolated adversary worktrees. A separate repro session reruns each adversary's findings in its worktree; no changes are integrated. Reports require commands and observed/expected output, but are model statements, so inspect actual command evidence and repro edits before accepting a finding. Swarm offers partition, best-of, first-pass and rank-all; mixed partition/race requires an explicit DAG. First-pass cancellation is cooperative and the workflow waits for remaining calls to settle.
+
+Use `pstack_semantics` with `action: "panel"` and `pstack_workflow` with `action: "plan"` to inspect seats, fallbacks and judge-skip notes. Templates require a strict brief; arena/architect require a rubric. Registry resolution does not prove authentication or successful inference.
+
+## Durable recovery
+
+State lives under:
+
+```text
+~/.pi/agent/pstack-native/
+├── workflows/
+├── agents/
+├── journals/
+├── sessions/
+├── worktrees/
+├── loops/
+├── locks/
+├── config.json
+└── models.json
+```
+
+A completed workflow node is never automatically repeated on process recovery. A node that was running reopens its existing Pi child session and gets a resume instruction to inspect current repository/session state before continuing. Fresh dead-process locks are detected by PID and cleared immediately; live owners keep their locks.
+
+The implementation deliberately uses Pi Coding Agent's persistent `AgentSession`/`SessionManager` for conversations and a pstack-native atomic JSON + append-only journal for orchestration. It does **not** open a second `@earendil-works/pi-durable` Harness inside the extension, because that would create a second model/auth/conversation owner beside Coding Agent. The storage boundary is isolated so it can move to a future official bridge without changing pstack workflow semantics.
+
+## Writer and integration semantics
+
+A simple change:
+
+```text
+worker (target checkout) -> verifier (same checkout)
+```
+
+Parallel independent changes:
+
+```text
+worker-a (worktree A) --\
+                       integrator (target checkout) -> verifier
+worker-b (worktree B) --/
+```
+
+The engine rejects a writable node that depends on several writable artifacts unless that node uses profile `integrator`. It also rejects a reviewer/verifier that directly depends on several isolated writer artifacts; integrate first, then verify the combined checkout.
+
+## Poteto Mode
+
+`/poteto-mode` is sticky in the current Pi session:
+
+```text
+/poteto-mode <task>
+/poteto-mode off
+```
+
+The native `poteto-mode` skill routes work to one of 23 adapted playbooks and tells the model to use Pi-native agent/workflow tools instead of literal Cursor `Task`, cloud-agent, Custom Mode, or `/loop` mechanics.
+
+## Chat catch-up
+
+Run `/skill:ketchup` to catch up on this chat since your last user-authored message before the request. Notifications and child completion messages do not move that cutoff. The skill rechecks status without writes and lists decisions or steps that need you. Each decision includes enough context to read on its own. Structural tests cover discovery and required text. Chat behavior itself was not exercised. Its harness belongs to issue #6.
+
+## PR handoff
+
+[Opening a PR](../skills/poteto-mode/playbooks/opening-a-pr.md) requires Why, What changed, Scope, Blast Radius, and Verification headings. Tradeoffs is optional. Open ready PRs. A stacked child targets its parent branch. Finish the phase or stack before a requested babysit pass, unless an explicitly assigned full-autonomy owner owns the loop. External writes and merges still need explicit authorization. See the [sample stack and local negative checks](../docs/PR-PROTOCOL.md). Cursor private PR-tool provenance and watcher verdicts remain unsupported.
+
+## Repeating checks
+
+```text
+/pstack-loop 20m inspect CI and continue only if the next gate is clear
+/pstack-loop list
+/pstack-loop status <id>
+/pstack-loop run <id>
+/pstack-loop pause <id>
+/pstack-loop resume <id>
+/pstack-loop stop <id>
+```
+
+The scheduler is session-local. It does **not** wake a closed Pi process or a sleeping machine. If a run was missed, the default policy performs at most one catch-up after the same session resumes. Loop state uses an atomic cross-process lock; each loop also has an execution lock held through Pi's asynchronous `sendUserMessage()` call. If another process owns either lock, the due time remains available and the scheduler retries with bounded exponential backoff.
+
+The scheduler advances the durable occurrence before sending it, which gives cooperating schedulers an **at-most-once dispatch attempt per claimed occurrence**, not exactly-once delivery. A host crash after the state claim but before Pi accepts the message can lose that occurrence. Updates, disabling, or removal affect future unclaimed occurrences; they cannot recall a message already submitted to Pi. `stop()` prevents future timer callbacks and does not preempt an in-flight Pi turn.
+
+## Skill discovery toggle
+
+```text
+/pstack status
+/pstack off
+/pstack on
+```
+
+Skills are supplied through Pi's `resources_discover` hook. Turning them off and reloading removes this package's skill directory from discovery while leaving runtime/status commands available.
+
+## Compatibility claim
+
+See `PARITY.json` and `PARITY.md`.
+
+- `ADAPTED`: the top-level skill/playbook behavior is represented with Pi-native runtime semantics.
+- `CURSOR_ONLY`: known unsupported Cursor-only behavior; never silently claimed as working.
+- `PI_ONLY`: native control/runtime capability added by this port.
+- `PENDING_PORT`: incomplete item inside the listed semantic coverage.
+
+**Active source pin:** Cursor pstack **0.15.36** at `c742dd61706fbacc1b95f1a20b7b988cf096ce6c`. Its 58 Skill names and 23 playbooks are registered: 57 Skills and all playbooks retain the latest source body through generated Pi entrypoints; `make-bot-ui` stays Cursor-only. Statechart now ships its complete upstream scripts and references; see [toolchain requirements](../docs/STATECHART.md). [Source provenance](../docs/upstream-provenance-0.15.36.json) verifies all 573 upstream blobs. These counts and byte checks do not prove model behavior. Maintainer semantic approval and authenticated real-model evidence remain separate, pending records in `SEMANTICS.json`. The previous source snapshot and historical reports are retained.
+
+## Safety boundaries
+
+- Unknown or dirty worktrees are never force-deleted automatically.
+- Reviewer profiles receive no bash/edit/write tools.
+- Verifiers have no bash/edit/write tools. Writable worker/integrator agents run tests and preserve evidence; verifiers inspect files and logs using confined read/search tools.
+- External effects such as pushes, PR comments, remote API writes, and merges are not made exactly-once by a local journal. Recovery instructions require inspecting remote state before repeating them.
+- Runtime-created worktrees are kept until explicit cleanup so crash recovery never destroys uncertain work.
+
+## Validation and review
+
+```bash
+npm run check
+npm test
+node --test docs/parity.test.mjs
+npm run review
+npm pack
+```
+
+The current suite covers graph validation, bounded concurrency, chain dependencies, failed-dependency propagation, process recovery, recovery beyond a concurrency window, terminal wake-up semantics, dead/live locks, writer placement, explicit integration, verifier artifact placement, dirty-worktree refusal, read-only path confinement, loop schedule locking, atomic state/journals, and model/reasoning routing. Static review also checks nested-runtime wiring and the depth cap.
+
+A user reported Windows real-model runs, including a rerun at commit `4d75ea0b`. See the [Windows test record](WINDOWS-MODEL-TEST.zh-CN.md). The real Pi SDK is also exercised by lifecycle, fake-provider E2E and installed-package smoke tests. Authenticated real-model inference is a separate tier: the managed environment's recorded model check found no configured authorized models. A Pi provider credential is required before that tier can run here. See [the current acceptance status and cloud-environment procedure](../docs/SEMANTIC-COMPATIBILITY.md#implementation-and-acceptance-status).
+
+## License and provenance
+
+MIT. Upstream pstack semantics/content are attributed to Lauren Tan and retain upstream MIT obligations. New Pi-native runtime code belongs to this project. See `NOTICE.md`.
+
+## Benchmark
+
+Each case records the deterministic test gate as `testEvidence` and the task-report decision as `contractAccepted`, separately from `verified` (current workflow acceptance). A passing test gate is evidence for the checked artifact, not a general model-quality score; the benchmark exits successfully only when every selected workflow is verified.
+
+```bash
+npm run build
+npm run benchmark:smoke   # offline import-path and fixture checks; not an LLM benchmark
+npm run benchmark -- --agent-dir /absolute/path/to/pi-agent --model provider/model --output /absolute/results
+```
+
+`benchmark:smoke` does **not** measure real tasks. Model-driven benchmarks require separately configured credentials, run in dedicated local repositories, and have not been used to justify performance claims.
+
+The live benchmark defaults to 20 cases, up to 200,000 tokens and 600 seconds per case. This can incur substantial model charges. Use `--limit 1` for an initial run and `--max-tokens N` to set a lower per-case token budget; unknown options are rejected.
+
+## Continuous upstream sync (M1–M4)
+
+Detection ≠ porting ≠ semantic review ≠ integration. The reviewed baseline in
+`UPSTREAM.json`/`PARITY.json` stays unchanged when a scan, proposal or test passes.
+Tools use Node standard libraries and Git; no AI API key is needed.
+
+```bash
+npm run upstream:scan -- --candidate-ref main
+npm run upstream:scan -- --from /path/to/cursor/plugins/pstack --candidate-ref <full-sha>
+npm run sync:upstream -- --from /path/to/cursor/plugins/pstack
+npm run upstream:plan -- --report docs/upstream-sync/reports/<sync_id>.json
+npm run upstream:verify -- --report docs/upstream-sync/reports/<sync_id>.json
+```
+
+`--baseline-ref <sha>` overrides the scan baseline only. Network mode accepts
+`main` or a full SHA and fetches the approved `cursor/plugins` source into an
+isolated temporary bare repository. Offline `--from` requires a Git checkout
+with both commits available (loose archives cannot establish history evidence).
+Only committed `pstack/` content is inspected. Upstream hooks, scripts, prompts,
+lifecycle scripts and Actions files are never executed by the detector.
+Legacy `--write-report <relative-path>` remains available within this checkout.
+
+Reports and task packages are in `docs/upstream-sync/{reports,tasks}/` with
+stable SHA-derived IDs, Git blob/mode evidence, name drift, advisory mappings,
+old/new Cursor seam locations, risk and pending acceptance work. Keyword hits
+are not runtime-dependency proof. Auxiliary files, binary/non-UTF8 content,
+symlinks and oversized files remain visible for human review; files over
+512 KiB are not interpreted. Whole Git operations are capped at 32 MiB and
+120 seconds; trees/seams over 10,000 entries fail explicitly. Reports do not
+embed raw upstream prose, shell output, environment or credential-bearing URLs.
+
+Exit codes: 0 = `no_change` or `changes_detected` (inspect JSON status),
+3 = `blocked`, 2 = `error`. A branch-history divergence blocks proposals.
+Failures preserve the baseline and can be retried. Same SHA pair produces the
+same fingerprint; an intentional local mapping change produces a fingerprint-suffixed report
+revision while inconsistent upstream evidence is rejected. Historical reports
+are retained. Content-addressed reports and historical
+`docs/upstream-sync-0.15.17.json` are retained.
+
+The daily workflow scans with read-only permissions, needs no npm install and
+uploads reports when content changes. Issue writes occur in a separate trusted
+job and are **opt-in**: set repository variable `UPSTREAM_SYNC_NOTIFY=true` for
+scheduled notifications or select `notify` on manual dispatch. Issues are keyed
+by `sync_id`, including closed Issues. No-change scans create no remote resource.
+Network/API failures fail the job; the next run retries from the unchanged
+baseline. Notifications choose tracking Issues rather than report PRs.
+
+### Optional isolated candidate workflow
+
+Commit the detector reports first, then prepare an isolated worktree:
+
+```bash
+npm run upstream:prepare -- --report docs/upstream-sync/reports/<sync_id>.json --worktree /absolute/new/worktree
+cd /absolute/new/worktree
+# Give docs/upstream-sync/tasks/<sync_id>.md to your explicitly authorized developer Agent.
+# Port semantics, add tests and per-task rationale/evidence/unresolved differences; commit changes.
+npm ci --no-audit --no-fund
+npm run upstream:verify -- --report docs/upstream-sync/reports/<sync_id>.json
+# Commit ONLY generated verification evidence after a clean committed candidate was verified.
+npm run upstream:propose -- --report docs/upstream-sync/reports/<sync_id>.json
+# Optional remote write, requires separately configured Git/gh credentials and explicit flag:
+npm run upstream:propose -- --report docs/upstream-sync/reports/<sync_id>.json --repo 2333sky/pi-pstack-native --allow-remote-write
+```
+
+M4 exports a constrained Agent prompt; it does not select a provider/model or
+launch autonomous inference. Agent execution needs the existing Pi isolation
+and authorization policy (a worktree alone is not an OS sandbox). Preparation
+refuses a dirty checkout or existing destination. Proposal requires the prepared
+worktree branch, committed candidate, all seven gates, unchanged source since
+verification, and unchanged baseline metadata. Remote proposals are deduplicated
+**draft** sync PRs; this specific maintenance flow intentionally differs from the
+normal ready-PR playbook. No automatic merge, npm publish or baseline advancement.
+A failed/partial candidate remains local/blocked; review its verification JSON.
+
+`upstream:verify` runs check, types, build, host, offline/fake E2E, benchmark smoke
+and installed-package smoke and records passed/failed individually. Live
+credentialed LLM/GitHub E2E and semantic review remain `not_run`; these are not
+inferred from smoke results. Tests execute local candidate code and therefore
+must run in a trusted or externally sandboxed environment.
+
+Maintainers grant semantic approval in a separately reviewed metadata change only
+after every relevant task is resolved (including explicit unsupported behavior), required
+CI is green and semantic approval is obtained. Point `coverage.countEvidence`
+to the validated pinned report, update both manifests' SHA/version together,
+match names/counts/files, retain `make-bot-ui` and all unsupported declarations,
+and retain the PENDING_PORT blocking gate. Only after that PR is approved and
+merged may the candidate be described as integrated. No CLI provides an
+`integrated` shortcut. See [implementation evidence](../docs/upstream-sync/IMPLEMENTATION.md).
+
+## Candidate pstack 0.15.23 behavior ports
+
+This historical candidate has been superseded by the active **0.15.36** source pin. Its behavior changes were implemented or explicitly mapped in
+[the per-file candidate receipt](../docs/upstream-sync/candidate-0.15.23.json),
+with every upstream diff accounted for. The archived receipt retains its original **proposed / pending maintainer semantic review** status; it does not describe current source availability or prove Cursor equivalence.
+See [port details and limitations](../docs/upstream-sync/PORT-0.15.23.md).
+
+## Read-only children and external evidence
+
+Reviewer/scout/verifier/synthesizer children receive only confined
+`read/ls/find/grep`, `pstack_skill` and `pstack_evidence`. Their active SDK tool
+allowlist excludes bash/edit/write and unrestricted builtin reads. The resource
+tool reads only bundled Skill/reference Markdown by ID, such as
+`poteto-mode/SKILL.md` or `why/references/epistemics.md`; it rejects traversal,
+symlinks, scripts and arbitrary files. Paginate until `hasMore=false` for a
+full Skill. Normal workspace reads still reject files outside the worktree.
+
+For external investigation, the **parent** performs authorized live queries
+and supplies `evidencePackets` on an agent or workflow node. Each packet has
+one category (`source-control`, `issues`, `documents`, `team-chat`,
+`observability`, `errors`, `analytics`), a status (`available`, `empty`,
+`unavailable`, `inconclusive`), a reason and bounded items with `source`,
+`observedAt`, and `excerpt`. The child receives a fixed snapshot, marked
+parent-supplied and not independently verified. Missing access is unavailable,
+not an empty search or permission to find credentials. The parent must verify
+decisive citations against authorized sources and sanitize sensitive data.
+No live MCP/credential forwarding is enabled by this change.
+
+## Actual linear PR stacks
+
+The `autopilot-stack` DAG is a **local preparation** template. Its
+`deliveryContract=remote-stack-required` prevents treating its completion as
+PR-stack delivery. Prepare separate clean worktree branches in a linear chain,
+verify each exact head against its exact parent, and push those branches only
+when authorized. The root owns topology; each worker owns its branch.
+
+A stack input contains `repo`, `rootBase`, `owner`, and ordered `lanes`:
+
+```json
+{
+  "repo": "owner/repository",
+  "rootBase": "main",
+  "owner": "operator",
+  "lanes": [
+    {"key":"first","cwd":"/absolute/worktree-one","head":"feature/one","ledgerId":"ver_first","title":"First unit"},
+    {"key":"second","cwd":"/absolute/worktree-two","head":"feature/two","ledgerId":"ver_second","title":"Second unit"}
+  ]
+}
+```
+
+```bash
+npm run build
+pstack-runner stack-plan /absolute/stack-input.json /absolute/stack-plan.json
+pstack-runner stack-open /absolute/stack-plan.json             # dry-run
+pstack-runner stack-open /absolute/stack-plan.json --approve   # explicit remote PR creation
+```
+
+Only the first PR targets `rootBase`; each child targets the preceding branch.
+`rootBase` is operator input: the first frontier refuses to take its trunk from
+the PRs under review, and no later refresh can retarget it. Preparation verifies
+shared repository identity, distinct clean worktrees,
+branch ancestry, remote heads, current accepted behavior ledgers and exact
+parent diff bases. Plans contain stable patch IDs and reject source/ref drift.
+Opening rechecks each pair and reuses only an existing open, ready PR matching
+that pair. It reads every newly created PR back and compares head and base; a ref
+that moves during creation revokes that lane's ledger and stops the remaining
+lanes. It does not rebase, force-push, retarget, push branches, merge or
+arm auto-merge. Publish branches separately with the user's authority.
+
+Existing custom PRProvider adapters must supply a checked reviewThreads summary, an explicit draft flag and a merge state; absent or unrecognized values block, because missing evidence is not evidence of a safe state. Only `draft: false` with the `CLEAN` merge state passes. Native Frontier snapshots paginate review threads, refuse invalid/repeated
+cursors and moved heads, and block unavailable/unresolved review evidence,
+drafts and blocked merge states even if CI passes. Native states are
+`waiting/reviewable/advance/complete/closed`; they do not pretend to be Cursor
+watcher verdicts. Auto-merge requested is not proof of queue readiness.
+After a lower PR merges, the root must explicitly prepare/retarget the new frontier to the pinned trunk branch; the native gate refuses landing it into the old parent branch. Head/base changes always invalidate native ledgers; a matching patch ID does
+not bypass re-verification. GitHub branch protection must enforce final
+server-side merge requirements.
+
+## Explicit-base audit and strict plans
+
+`pstack-runner worktree-audit /absolute/worktree-info.json origin/parent`
+reads the explicit PR base and reports dirty/ahead/merged state without deleting
+anything. The info object uses the existing `WorktreeInfo` fields `path`,
+`branch`, `repoRoot`, `baseRef`. Cursor transcript/sidebar/simulator inspection
+remains unsupported; runtime-owned cleanup and active/dirty guards remain.
+
+`npm run check:plan -- /absolute/plan.md` checks the strict upstream program
+checklist format with corrected Markdown fence handling and native loop markers.
+The format's ten live-proof lanes are opt-in, not authority to launch agents,
+spend model budget or run credentialed E2E. No Bun lifecycle is imported.
+
+When local mappings change for the same upstream SHA pair, scans now preserve
+the original report and write a fingerprint-suffixed revision. Git blob bytes
+are checked against their SHA. Different upstream evidence under the same ID
+still fails explicitly; historical evidence is never silently overwritten.
+
+## Core upstream semantics
+
+All supported entrypoints preserve the fixed 0.15.36 source body; the eleven core workflows have critical-rule mappings, with [Pi-specific mappings and deviations](../docs/PI-SEMANTIC-ADAPTER.md) kept separately. `pstack_skill` exposes original Markdown to read-only children; `pstack_semantics` checks capabilities, declared task routing, model panels and round receipts. These checks complement native DAG/ledger/Frontier gates. See [semantic compatibility and evidence tiers](../docs/SEMANTIC-COMPATIBILITY.md). Neither ADAPTED inventory entries nor offline tests establish complete behavioral parity.
+
+[PR #17](https://github.com/2333sky/pi-pstack-native/pull/17) merged the initial 0.15.17 compatibility infrastructure. The [0.15.36 upgrade](../docs/upstream-upgrade-0.15.36.md) describes the current source pin; Pi remains locked to SDK 1.4.0. The foundation PR’s Node 22.19 / 24 CI passed. A subsequent user-reported Windows real-model run is described in the [test record](WINDOWS-MODEL-TEST.zh-CN.md); the repository's commit-bound authenticated-model receipt is archived for `5deb723` in [the semantic smoke evidence](evidence/semantic-smoke-5deb723.json), and semantic review is recorded as `signed-off` in `SEMANTICS.json.review` for the 11 core entrypoints and their declared deviations. [The remaining acceptance steps](../docs/SEMANTIC-COMPATIBILITY.md#completing-issue-16) explain how to reuse or refresh that evidence without treating a merge or an unavailable-model probe as a passing model test.

package/docs/SEMANTIC-COMPATIBILITY.md

@@ -0,0 +1,135 @@
+# Core semantic compatibility
+
+Issue #16 separates behavior source, platform adaptation and exercised evidence. The active source is pstack 0.15.36 at `c742dd61706fbacc1b95f1a20b7b988cf096ce6c`, on Pi SDK 1.4.0. The source pin and availability inventory are current; maintainer semantic approval and a commit-bound authenticated model receipt remain separate pending records. A user reported Windows real-model runs, including an independent rerun at commit `4d75ea0b`; see [the test record](WINDOWS-MODEL-TEST.zh-CN.md).
+
+## Implementation and acceptance status
+
+[PR #17](https://github.com/2333sky/pi-pstack-native/pull/17) merged on 2026-10-26 as commit [`f355eaed`](https://github.com/2333sky/pi-pstack-native/commit/f355eaedcabbcee6c1429f8a5341974b6833dd22). Its tested head, `a4e04df4128bf83e60404ef54329bf8814aa6cbc`, passed [CI on Node 22.19 and 24](https://github.com/2333sky/pi-pstack-native/actions/runs/40299080693).
+
+| Item | Recorded status | Evidence boundary |
+|---|---|---|
+| Pinned source, Pi adapter, 11 core entrypoints and 35 critical-rule mappings | Merged | Source traceability and declared adaptations |
+| Semantic checks, negative fixtures, typecheck and build | Passed | Deterministic local/CI behavior |
+| Real Pi SDK lifecycle, offline/fake-provider E2E and installed-package smoke | Passed | Actual SDK/session integration with scripted model responses; no authenticated external inference |
+| User-reported Windows real-model runs | Reported: 13/20 workflow acceptance and 20/20 independent tests at `4d75ea0b` | Full original result files have not been attached to the repository; see the [Windows record](WINDOWS-MODEL-TEST.zh-CN.md) |
+| Limited real Pi + real-model probe | Passed on `5deb723` for `opencode-go/claude-haiku-5-5`, `custom/gpt-5.6-sol` and `opencode-go/gpt-5.6-luna` | [Receipt](evidence/semantic-smoke-5deb723.json); one read-only probe per model, no implementation or live surface |
+| Live GitHub delivery operations | Passed on `5deb723`: create, read, close and merge against a disposable private repository | [Receipt](evidence/live-github-5deb723.json); unprotected repository, single operator account, no review or auto-merge |
+| Maintainer semantic review record | `signed-off` by `2333sky` at 2026-10-30T16:33:31Z | Recorded in `SEMANTICS.json.review` with a concrete rationale; it covers the 11 core entrypoints and their declared deviations only |
+
+The latest-source upgrade retains the evidence tiers below and adds [statechart toolchain validation](STATECHART.md). The [upgrade audit](upstream-upgrade-0.15.36.md) records changed source files and mapping decisions. The merged PR/CI links above document the earlier foundation, not a test of every later source change.
+
+The managed environment check on 2026-10-26 found zero configured authorized models through the real Pi SDK. The SDK itself is installed and usable. This is a missing provider-authorization prerequisite, rather than a requirement to run the test on a personal computer. Environment configuration may change; check the SDK's available models again before a new run.
+
+A probe of an unavailable model returned `blocked` with `inference: false`. That verifies the unavailable-model path and supplies no real-model inference evidence. Inventory coverage, mapped rules, exercised SDK behavior and model behavior remain separate claims.
+
+## Source and adapter
+
+`vendor/upstream/0.15.36/pstack/` contains 141 pinned source artifacts: Skill/playbook/reference Markdown, the statechart runtime, the manifest and upstream MIT license. The statechart test corpus is available in the installed Skill tree. Every vendored file is checked against its original Git blob ID and length; the source provenance report additionally verifies all 573 upstream files. Images, other plugins, Cursor runtime scripts, cloud infrastructure and private tools are outside the executable Pi port. The earlier 0.15.17 snapshot remains historical evidence.
+
+The five core Skills (`poteto-mode`, `architect`, `arena`, `swarm`, `interrogate`) and six core playbooks (`bug-fix`, `feature`, `autopilot-full`, `autopilot-stack`, `babysit`, `shipping`) retain critical-rule mappings. All 57 supported Skills and all 23 playbooks are generated entrypoints whose upstream body is retained verbatim. The separate [Pi adapter](PI-SEMANTIC-ADAPTER.md) explains tool substitutions, model selection, paths, worktrees, loop limitations, read-only verification, template choreography differences, authority boundaries and unsupported operations.
+
+Regenerate after an intentional adapter/source change:
+
+```sh
+node --experimental-strip-types scripts/semantics/generate.mjs --write
+npm run upstream:contracts
+```
+
+## Maintaining Pi-local Poteto engineering checkpoints
+
+Poteto Mode has a **Pi-local engineering overlay** in `scripts/semantics/generate.mjs` (the `engineeringOverlay` branch for `poteto-mode/SKILL.md`). It supplies **First make it work → Then make it right → Practice**, failed-premise recovery, subagent handoff and evidence-reporting guidance. The generated `skills/poteto-mode/SKILL.md` combines the Pi adapter, this local overlay and the pinned upstream Markdown. **Do not edit the generated Skill to maintain these checkpoints**: regeneration would replace manual edits. This overlay is prompt-level guidance; it does not override native verification gates or authorize remote writes.
+
+When a new upstream `cursor/plugins` pstack revision is available:
+
+1. **Start from a branch containing the local overlay**, after its change has been merged. Run `npm run upstream:scan` to compare the pinned revision with the upstream candidate. Review the recorded report under `docs/upstream-sync/`. Exit code 3 indicates relevant semantic drift needing review, not permission to skip it. For a reviewed report, `npm run upstream:plan -- --report <report-path>` exports the task plan; upgrades should use an isolated branch/worktree.
+2. **Port and review the upstream changes**. Update the pinned `vendor/upstream/` snapshot and matching `UPSTREAM.json`, `PARITY.json`, `SEMANTICS.json`, provenance/inventory, relevant Pi mappings, tests and versioned documentation as appropriate. The scan/plan commands do not advance this baseline automatically. Check changed Poteto instructions, TDD/bug-fix/refactoring principles, and any renamed Skill entrypoint for duplication or conflict with the overlay; adjust the local generator only if needed. Keep the new pinned upstream instructions verbatim.
+3. **Regenerate, review, and validate** from the upgraded checkout:
+
+   ```sh
+   node --experimental-strip-types scripts/semantics/generate.mjs --write
+   npm run upstream:contracts
+   npm run check:semantics
+   npm run test:semantics
+   npm run check
+   npm run check:types
+   npm run build
+   npm run check:e2e
+   ```
+
+4. **Check the generated boundary before merging**: `skills/poteto-mode/SKILL.md` must contain `## Pi engineering checkpoints for code-changing tasks` **exactly once**, followed by `## Pinned upstream instructions` from the upgraded snapshot. Review the generated diff: confirm no new contradictory or redundant rules, and that the checkpoints still reach code-writing subagents and integrated-artifact verification. If upstream renames or removes the Poteto entrypoint, intentionally update the generator's resource match and affected mappings/tests instead of silently dropping the overlay.
+5. **Preserve provenance and review status**. When reviewed local files (including the generator) change, update their SHA-256 entries in `SEMANTICS.json.reviewedFiles` alongside the actual review and relevant tests. A refreshed digest, passing CI, or a regenerated file does **not** constitute maintainer semantic sign-off. Record genuine review, and separately label offline/fake-provider and authenticated-model evidence. Submit and review the upgrade as its own PR; do not automatically push, publish or merge.
+
+For a new upstream revision that does not modify Poteto or related engineering instructions, the overlay should regenerate unchanged, but the checks above still protect its placement and semantics. A model following these checkpoints in a live coding task requires separate behavioral evaluation; the static checks only validate source generation and compatibility records.
+
+Read-only children and the parent can read original Markdown with `pstack_skill`, including `upstream/skills/poteto-mode/playbooks/shipping.md` and original `references/` paths. Reads are paginated; every page is required. Script execution and arbitrary paths are rejected. The snapshot is not a separately discovered Skill tree.
+
+`pstack_semantics` checks explicit capability requests, maps declared task intents to playbooks, preflights independent model panels, and evaluates supplied round receipts. Its checks are deterministic and do not attest that an evidence file is true. Native AgentSession/DAG execution, verification ledgers, Frontier checks and human merge authorization remain the execution gates. The adapter does not execute, publish or merge anything itself.
+
+## Reviewable drift
+
+`SEMANTICS.json` contains exact source ranges and hashes, per-file/per-step fingerprints, critical-rule mappings, status, Pi mapping, rationale, scope and test names. Every platform override also has its own upstream source range, status, mapping, rationale, scope and bound tests. Status is one of `equivalent`, `adapted-with-deviation`, `unsupported`, `not-yet-verified`. A source-preservation test is explicitly not a model-behavior test. The mappings audit selected critical rules; every sentence has not been behaviorally exercised.
+
+```sh
+npm run check:semantics
+npm run test:semantics
+npm run check:semantics -- --from /path/to/cursor-plugins --commit <40-character-commit>
+```
+
+The scheduled upstream scan also writes this semantic report beside its inventory report and uploads it as a CI artifact. The last command reads committed Git objects, reports before/after file and numbered-step/section fingerprints and text, and exits 3 for unreviewed relevant changes. Core files, their architect/interrogate/poteto-mode references, statechart scripts, and upstream source paths cited by an explicit override are relevant. Other vendored Markdown changes are reported without failing this scoped gate. Newly introduced core reference files are detected. This is not a claim that changes outside the audited scope are safe.
+
+A `driftReviews` receipt must identify `commit`, `path`, exact `before`/`after` Git blob IDs (null for additions/deletions), `status: signed-off`, a named `reviewer`, `rationale`, and bound `tests` file paths. It acknowledges that exact candidate change; it does not update the snapshot or baseline. Changes to local source, adapter, runtime implementations or bound tests fail the local fingerprint gate. After reviewing a local change, update its `reviewedFiles` SHA-256, affected mapping/tests and generated entrypoints together. A hash update alone supplies no semantic approval.
+
+A source upgrade updates the snapshot, mappings, tests and active metadata together. It does not grant semantic approval. No scan, generation, test, inventory command or drift acknowledgement records maintainer approval. The review state is stored separately in `SEMANTICS.json.review`; it remains `pending-maintainer-signoff` after the implementation merge until a maintainer records their semantic review.
+
+## Evidence tiers
+
+| Tier | What it establishes | What it cannot establish |
+|---|---|---|
+| PARITY inventory | Available names and dispositions | Equivalent decisions or execution |
+| SEMANTICS mapping and generated-body check | Exact upstream traceability and explicit overrides | Model instruction following |
+| Offline semantic fixtures | Routing, panel requirements, receipt freshness/independence, no silent skip, merge boundaries, negative mappings and drift blocking | Truth of caller-supplied receipts or real-surface proof |
+| Existing real Pi SDK / fake-provider E2E | Actual AgentSession tools, isolated writers, integration, exact artifacts, SIGKILL recovery and stale shipping rejection | External model reasoning or live GitHub parity |
+| Opt-in real Pi + model probe | Source reading, unsupported-capability rejection and status routing through one configured model | Complete workflow, independent review quality, live UI/CLI proof or merge behavior |
+
+CI runs semantic fixtures through `npm test`, the semantic fingerprint gate through `npm run check`, and existing offline/fake-provider E2E through `npm run check:e2e` on Node 22.19 and 24 with Pi 1.4.0. A separate Node 24 / Java 21 job runs the pinned upstream statechart suite with TLC 1.7.4. No model credentials are required for those tiers; the statechart job downloads its public toolchain and renderer packages.
+
+## Limited real-model smoke
+
+Use existing authorized Pi credentials and an explicit available provider/model. The command can run in this managed cloud environment once a provider credential is configured, or in another authorized Pi environment. ChatGPT access and GitHub authentication do not by themselves configure a Pi model provider.
+
+For a managed cloud run:
+
+1. Configure a provider credential through the environment's Secrets settings, using the variable supported by that provider, such as `OPENAI_API_KEY` for OpenAI. Ensure the selected model's API endpoint is allowed by the environment's network policy. Keep credential values out of the receipt and repository.
+2. Start the test process after the updated environment configuration is active. Select the exact Pi `provider/model` identifier; `pi --list-models` lists available models when the Pi CLI is installed. An empty available-model list means the prerequisite is still unmet.
+3. Run from the repository root on a clean checkout of the revision being verified. Install dependencies with `npm ci` if needed. Replace `provider/model` below with the selected identifier.
+
+This probe only enables two read-only model tools in a temporary checkout. It does not enable shell/write tools, dispatch workers or contact a forge:
+
+```sh
+mkdir -p work/semantic-smoke
+git rev-parse HEAD > work/semantic-smoke/source-commit.txt
+npm run --silent smoke:semantics:real -- --model provider/model > work/semantic-smoke/result.json
+```
+
+Inspect the command's exit code and the JSON receipt together:
+
+| Result | Exit code and receipt | Meaning |
+|---|---|---|
+| Passed | Exit 0; `status: "passed"`, `inference: true`, and all three probe checks true | One model completed the source-read, unsupported-capability and status-routing probe |
+| Blocked | Exit 2; `status: "blocked"`, `inference: false` when the requested model/auth is unavailable | No authenticated model inference was exercised |
+| Failed | Exit 1, a failed/incomplete probe, or a runtime error | Investigate; do not record a passing result |
+
+The three probe checks are `completeSourceRead`, `unsupportedRefused` and `statusRoutedToBabysit`. The JSON receipt includes the model and evidence boundary. The harness does not persist raw model output or credentials. Preserve the receipt together with `source-commit.txt`; after checking the files, archive them in a stable repository evidence path or a linked CI artifact. A result applies to its tested commit and model. It is not proof of complete implementation, review-swarm quality, live UI/CLI behavior or merge safety.
+
+The repository's commit-bound authenticated real-model receipt is [archived for `5deb723`](evidence/semantic-smoke-5deb723.json): three models passed the probe, and one earlier model identifier that its provider rejected is recorded there as a failed attempt. The separate user-reported Windows real-model runs, including a rerun at commit `4d75ea0b`, are recorded [here](WINDOWS-MODEL-TEST.zh-CN.md); full original result files are not recorded in this repository. Existing real SDK tests use a loopback provider. CI runs the repeatable offline/fake-provider tiers without provider credentials; it does not automatically run this authenticated probe.
+
+## Completing issue #16
+
+The remaining acceptance work is a review record. Evidence for the other item is archived, but a documentation update alone completes neither item.
+
+1. ~~Run the limited real-model probe successfully and archive the receipt, tested source commit and model.~~ Done for `5deb723`: see [the receipt](evidence/semantic-smoke-5deb723.json). `SEMANTICS.json.evidence.realModel` records `status: "passed"` with that receipt. A later source change to a reviewed file invalidates the binding and requires a new run.
+2. ~~Have the maintainer review the critical mappings and intentional deviations.~~ Done: `SEMANTICS.json.review` records `status: "signed-off"`, reviewer `2333sky`, the timestamp and a rationale, with the scope unchanged. The sign-off does not claim full Cursor behavioural parity and does not cover Windows real-model workflow acceptance.
+3. Submit the evidence and metadata update, run `npm run check:semantics` and `npm run test:semantics`, and require the normal CI checks on that revision. Review any intervening mapped source/runtime changes before reusing earlier evidence.
+4. Recheck [issue #16](https://github.com/2333sky/pi-pstack-native/issues/16)'s acceptance criteria and record what the evidence establishes before closing it as completed. If a criterion is intentionally deferred, track it in a linked follow-up and explicitly agree the revised scope rather than checking it off as passed.
+
+These steps do not require advancing the reviewed upstream baseline or claiming complete Cursor/Pi behavioral equivalence. Full live-surface implementation/review/merge scenarios remain separate evidence work.

package/docs/STATECHART.md

@@ -0,0 +1,13 @@
+# Statechart on Pi
+
+The active Skill and TypeScript statechart source are pinned to pstack 0.15.36 at `c742dd61706fbacc1b95f1a20b7b988cf096ce6c`. The upstream runtime and test corpus are installed under `skills/statechart/scripts/`. The build compiles the 0.15.36 runtime to `dist/statechart/`, since Node does not strip TypeScript inside `node_modules`; the older 0.15.32 `.mjs` CLI is retained for compatibility.
+
+For the active version, provide a TLA+ specification and configuration:
+
+```sh
+node dist/statechart/statechart.js SPEC.tla --config SPEC.cfg --out OUTPUT
+```
+
+The output includes `report.md` and, where applicable, `chart.mmd`. Java 11 or later and TLC are external prerequisites. Set `TLA2TOOLS` to a local `tla2tools.jar` and optionally `JAVA` to the Java executable. Without `TLA2TOOLS`, upstream attempts installation through `mise` and the network. Missing prerequisites are errors, not evidence of a successful run. See the Skill's `references/render.md` for optional rendering.
+
+`npm run test:statechart` runs the upstream TypeScript suite, including the pinned corpus. Some tests require Java, TLC and a working process-inspection environment. Tests that report a skip are not live-TLC evidence. CI runs a real-TLC smoke in addition to deterministic checks; consult the actual CI run for its result. Neither a successful toolchain test nor a generated model proves that an arbitrary application's code matches the model.