pi-pstack-native 0.0.0-stage → 1.0.0

package/ACCEPTANCE.md

@@ -0,0 +1,40 @@
+# 2333 0.6.0-preview.1 验收报告
+
+> **历史记录：** 本文件记录 2026-10-10 的历史验收快照；其中的包名、版本和测试状态不代表当前主分支。当前状态请参阅 [语义兼容说明](docs/SEMANTIC-COMPATIBILITY.md) 和 CI。
+
+日期：2026-10-10。基线：用户上传的 0.3.4 源码及增强 PRD。交付性质：Preview，未发布到 npm，未操作真实远端 PR。
+
+## 已通过
+
+| 检查 | 结果 | 证明边界 |
+|---|---|---|
+| `npm run build` | PASS | 编译 JavaScript、声明及 CLI，避免 node_modules 类型剥离限制 |
+| `npm run check:types` | PASS | 已安装 TypeScript 和官方 Pi SDK 的严格类型检查 |
+| `npm run check:syntax` | PASS | JS/TS 源码语法 |
+| `npm run check:package` | PASS | 官方 Pi peer、包策略 |
+| `npm run check:parity` | PASS | 51 skills / 23 playbooks 的登记完整性；不是全量 Cursor 行为证明 |
+| `npm test` | **94 / 94 PASS** | 原 62 项回归 + 32 项协议、负向及故障测试 |
+| `npm run check:host` | PASS | 真实 SDK 的 AgentSession 创建，未执行外部模型推理 |
+| 真实 SDK 生命周期 | PASS，包含在测试中 | 真实 AgentSession + 本地 loopback provider；加载 8 个工具，成功、401、取消、恢复 |
+| Git / Ledger | PASS | staged / unstaged / untracked / worktree / 仓库隔离 / source 变更 / log 篡改 |
+| Shipping | PASS，模拟 Provider | 下层未合并阻断上层；head 变化；TOCTOU；单次授权；远端已 merge 后本地异常的恢复 |
+| Program | PASS | 12 Unit 的 pilot / rolling window / Inbox / Store 恢复 / close / orders / pause-resume |
+| Crash gate-start | PASS | 验证进程被 SIGKILL 后，不产生通过台账；重新启动能重新验证 |
+
+安装包已在独立 consumer 中安装：真实 Pi SDK 加载 8 个工具通过；编译后 CLI 的 migrate dry-run 通过；公开 JavaScript API 导入通过。结果见 INSTALLATION-CHECK.md。
+
+## 实现范围
+
+实现入口与实际功能见 IMPLEMENTATION.md 的 FR-01 到 FR-09 对应表。使用说明、命令授权和样例见 examples/README.md。新命令默认 opt-in；无完整严格契约、无权限、无当前证据、远端状态未知都阻断，不用 Agent 的自然语言声明生成通过证据。
+
+关键改进：原子协议状态+审计 envelope；工作区与 index 双指纹；验证子进程监督器；严格 report；末端产物重新验收；服务端期望 head 校验；一次性授权；专用 typed DAG 而非模式别名。
+
+## 仍未通过外部发布门槛
+
+- 未执行真实供应商的认证推理任务；没有真实模型成功率、成本对照或 Cursor 优劣数据。
+- 未使用真实 GitHub PR 执行 create/merge；CLI adapter 与分支保护的端到端行为须在隔离测试仓库继续验证。
+- 20 个真实模型 bug-fix 基准与 runner 已提供，**未运行**。复杂跨模块、Arena、PR 栈的横向真实任务研究仍待追加。
+- 未在 Node 22.19 实际运行本次测试；本次环境为 Node 24.19.0。已提供双版本 CI 配置，CI 尚未被远端运行。
+- 不能把 allowlist / Git Worktree 当作 OS 沙箱；未进行跨主机租约、百万事件或所有 LFS / submodule 情况的兼容性验收。
+
+这些缺口是使用 Preview 标记的理由。不能把本报告理解为“PRD 所有发布验收条件均已满足”或“所有远端/模型路径已验证”。

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+## Unreleased
+
+- Archive a commit-bound authenticated real-model receipt: three models passed the read-only probe on `5deb723`, and `SEMANTICS.json.evidence.realModel` records `status: "passed"` with that receipt.
+- Validate live GitHub delivery against a disposable repository: create, read, close and merge now have a recorded run. Add an opt-in `--merge` gate to the live tier; it stays closed unless `PSTACK_E2E_LIVE_MERGE=1` is set with an explicit write target.
+- Record the npm registry state: `pi-pstack-native` is unpublished, so `1.0.0` is unclaimed; no npm credentials exist in the validation environment.
+- Record the maintainer semantic sign-off in `SEMANTICS.json.review` for the 11 core entrypoints and their declared deviations.
+- State the 1.0.0 guarantee scope explicitly in `docs/PUBLISHING.md`, including the exclusion of Windows real-model workflow acceptance and of branch-protection, review, auto-merge and merge-queue behaviour.
+
+- Prepare the `1.0.0` version in the package manifest and lockfile, while retaining explicit release approval and external validation gates; the version has **not** been published by this change.
+- Align the package identity check with the manifest/lockfile, and document stable-channel installation and outstanding release evidence.
+
+- Rename the repository and package to `pi-pstack-native` and document direct Pi Git installation.
+- Upgrade the pinned pstack source to 0.15.36 and retain the 0.15.32 snapshot; keep maintainer semantic approval and authenticated-model evidence separate.
+- Preserve panel and workflow configuration during setup and validate role-model reasoning selections.
+- Preview available-model defaults and edit individual roles, task overrides and panels in `/setup-pstack`; route Reflect lens models with `modelRole`. Arena and Architect use an eligible cross-judge or return candidates for coordinator selection, and preserve verified candidates after a dropout.
+- Use isolated adversary and independent reproduction sessions for Interrogate; copy staged, unstaged and untracked target changes and never integrate review worktrees automatically. Reports require command evidence and remain subject to coordinator inspection.
+- Add first-pass and rank-all Swarm race templates and an Architect implementation phase. Include the pstack 0.15.36 Statechart TypeScript source and test corpus, plus a compiled runtime that works inside installed Node packages.
+- Fix Windows atomic state writes, build paths, and lock contention; improve task-report diagnostics and benchmark controls.
+
+Earlier entries below describe their original snapshots and may retain historical package names or validation boundaries.
+
+## 0.6.0-preview.1 — Preview
+
+- Add strict Brief, scope/report checks, Artifact, supervised Gate and immutable Ledger.
+- Add GitHub Frontier, authorized SHA-bound shipping, templates, Program Inbox and context.
+- Add panels/budgets, standalone Runner, migration, fault tests and benchmark harness.
+- Preview: real authenticated model/GitHub E2E remain separate release gates.
+- GitHub bootstrap: fix benchmark compiled imports; add offline benchmark smoke, CI, release documentation, and contribution/security guidance.
+- Bind every baseline receipt to the consuming task. Foreign, stale-revision and ownerless baselines are refused with `BASELINE_NOT_OWNED` instead of being trusted on id and fingerprint alone.
+- Commit a program unit's dispatch record with the unit link in one transaction, then rebuild the workflow file from it. Orphan workflow files and files that drifted from their dispatch are refused before a child starts.
+- Redact evidence through one rule table over the joined buffer before tail truncation, and name the read-only tool allowlist once so a read-only profile cannot list a writing tool.
+- Record the pinned upstream 0.15.32 tree and generate a 200-file inventory from it, with one disposition per file, a reference-closure list and a check that fails on drift.
+- Keep unproven rows explicit: 116 files are marked as not reviewed and every file has `evidence: not_run`.
+- Register `in-your-own-words` and `sharpen`, and port `ketchup-video`, `create-formal-verification-skill` and `maintain-formal-verification-skill` with their platform seams and dependency checks.
+- Make the parity manifest able to say it is short of the pinned target: the pending set and its reasons are checked against the target snapshot, so a gap cannot disappear silently.
+- Add behavior contracts for all 23 playbooks, derived from each playbook's numbered steps and roles, with `evidence: not_run` and a drift check in `npm run check`.
+- Add a generated per-record registry for all 81 registered names, carrying source, port, requirements, contracts and evidence, with a validator that refuses a claim its own fields do not support.
+
+
+## Earlier releases
+
+## 0.3.4 — 2026-10-10 (Release Candidate)
+
+- Contain synchronous and asynchronous timer callback failures, emit diagnostic logs, and use bounded exponential retry backoff for transient state-lock and execution-lock contention.
+- Add generation-guarded `start()` / `stop()` lifecycle handling and serialize timer ticks so stopped callbacks cannot rearm and one scheduler cannot overlap its own run.
+- Add per-loop cross-process execution locks held through Pi's asynchronous send. Contending processes preserve the due occurrence and retry after the active send settles.
+- Add real-timer, multi-process regressions for crash isolation, recovery, backoff cadence, stop races, observable sync/async send failures, atomic occurrence claims, in-flight updates, disable, and deletion.
+- Document the scheduler's at-most-once dispatch-attempt semantics: a host crash after durable claim but before Pi accepts the message can lose an occurrence; already submitted messages cannot be recalled.
+- Retain package name `2333`, use the official Pi SDK peer, and align source and package metadata on `0.3.4`.
+
+## 0.3.3 — 2026-10-10 (Release Candidate)
+
+- Align the package, extension banner, package policy check, README, and review metadata on version 0.3.3; retain the npm package name `2333`.
+- Extend real Pi SDK integration coverage with a successful AgentHost turn and a post-failure recovery run using a loopback-only OpenAI-compatible protocol fixture.
+- Add an installed-tarball smoke script that loads the extension from `node_modules/2333` through the real Pi SDK and checks its registered tools.
+- No production runtime behavior changes are intended in this release candidate; external authenticated LLM inference remains a separate validation gate.
+
+## 0.3.2 — 2026-10-10
+
+- Correct child turn success detection: only the current turn's final `stopReason: stop` yields success; provider errors, aborts, truncated output, missing messages, and tool continuations do not.
+- Change cancellation into a persistent two-stage protocol (`cancelling` -> `cancelled` only after the affected work settles). Remote owners poll for persisted cancellation and invoke `session.abort()`; unknown remote status remains unconfirmed.
+- Move workflow lifecycle and call writes into short cross-process file-locked state transactions with revision counters.
+- Replace unrestricted readonly-agent tools with workspace-confined custom read/ls/find/grep and disable nested pstack extension loading for readonly agents.
+- Execute potentially expensive JavaScript regex searches in a time-limited worker thread to avoid blocking the host event loop.
+- Add behavioral regression tests, including independent process contention, cancellation and resume races, boundary/symlink checks, and provider outcome checks.
+- Replace misleading source-string review PASS heuristics with explicit test and release-gate documentation; add TypeScript checking, an installed SDK session smoke test, and a CI workflow.
+- Bring verifier documentation into line with the no-shell profile.
+
+### Incomplete validation / risks
+
+- A real authenticated Pi Host inference integration test is **not** included in the locally executed test results.
+- `cancelling` intentionally remains non-terminal when remote shutdown cannot be confirmed; no implementation can guarantee immediate interruption of a non-cooperative external action without stronger isolation.
+- Custom read-tool path confinement is not an operating system sandbox. Treat untrusted Agent workloads as needing OS-level constraints.

package/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+This is a Pi-native adaptation of pstack. Please open an issue describing the problem, a minimal reproduction, expected behavior, and the Pi SDK/Node versions before large changes.
+
+## Local development
+
+Use Node.js >=22.19.0 and a compatible `@earendil-works/pi-coding-agent` SDK.
+
+```bash
+npm install
+npm run check
+npm run check:types
+npm run build
+npm run check:host
+npm run benchmark:smoke
+```
+
+The host check creates a Pi AgentSession but does **not** test a paid/live model. Remote PR tests must use a disposable repository and never run destructive commands on third-party repositories.
+
+## Pull requests
+
+- Preserve upstream pstack attribution and MIT notices.
+- Include regression tests for any workflow, safety, artifact, or ledger behavior changed.
+- State whether your test used a loopback provider or authenticated inference.
+- Include failure and restart paths when modifying persistence, recovery, locks, or shipping logic.
+- Keep compatibility for legacy graph/chain/parallel usage unless the change is explicitly breaking.
+- Avoid committing secrets, `node_modules`, local `~/.pi` data, or benchmark outputs.
+
+See [SECURITY.md](SECURITY.md) before reporting security issues.

package/IMPLEMENTATION.md

@@ -0,0 +1,38 @@
+# 2333 0.6.0-preview.1：方案与实现边界
+
+> **历史记录：** 本文件记录早期方案和实现边界；当前实现及兼容状态以 [运行时参考](docs/REFERENCE.md) 和 [语义兼容说明](docs/SEMANTIC-COMPATIBILITY.md) 为准。
+
+本包基于用户上传的 0.3.4 源码，参照 2026-10-10 的增强 PRD。沿用 Pi AgentSession 与原 DAG 引擎，不另建调度器。版本使用 Preview：本地行为测试不能替代真实供应商和真实 GitHub 的交付验收。
+
+## 相比 PRD 的改进
+
+1. 新协议对象和审计事件共用一个带 revision 的原子 JSON envelope。短锁、临时文件 fsync、rename 和目录 fsync 形成明确提交边界；验证日志另存，Ledger 引用 checksum，日志缺失或损坏不通过。不宣称多文件事务或远端 exactly-once。
+2. 将 Call 的执行完成、当前 Artifact 的确定性验证、TaskReport 的接受与远端交付分别处理。过去节点的 artifact 变 stale，不应导致已经重新验证的后继产物永远无法完成；最终验收检查 DAG 终端产物，前驱验收在派发依赖时检查。
+3. Git 指纹包含完整 commit SHA、tree、index tree、源文件字节、可执行位、symlink target、非 ignored untracked 文件。工作树共享 common git dir 身份，不把两个独立仓库的相同 SHA 视为一个产物。带冲突索引、submodule 或无法读取的文件 fail closed。
+4. Runner 使用精确 argv allowlist、无 shell、独立环境、截断脱敏日志、超时和父进程连接监督。验证前后检查整个指纹，验证期间发生写入时只会得到 stale。
+5. Merge 既重读 Frontier，又通过 `gh pr merge --match-head-commit` 校验期望 head；授权绑定 stack、generation、digest、单个 PR，五分钟有效且请求前消费。远端已 merge、本地记录失败时，恢复读取远端，不重发旧授权。
+6. 模型评分不作为机器验收。Arena 的 evaluation / selection、Review findings 和 partition coverage 使用结构化 Report 校验；模型 family 独立性必须显式提供映射，不根据供应商名猜测。
+
+## 实际可用能力
+
+| PRD | 实现入口 | 边界 |
+|---|---|---|
+| FR-01 Contract | `contracts/brief.ts`；workflow strict / brief；pstack_verify contract/revise | scope 做开始与结束检查；不是操作系统写入沙箱。运行中不允许偷偷改 Brief；停止后显式修订，恢复加载当前版本。 |
+| FR-02 Gates | `verification/runner.ts`；command/file/diff/test-report/human-approval/llm-review | 默认没有任何 command 授权。LLM review 仅咨询；人工批准须 CLI 显式操作。JUnit 支持标准 testsuite 属性和简单结果，不支持全部 XML 扩展。 |
+| FR-03 Artifact/Ledger | `fingerprint.ts`；verify；ledgerCurrent；invalidation | 指纹失配立即拒绝，历史 Ledger 不覆写；显式 invalidation 事件可审计。只忽略 Git ignore 规则所排除的 untracked；验收关键输入不能放到 ignore 中。 |
+| FR-04 Frontier/Shipping | `delivery/*`；pstack_delivery；CLI ship | 首期 GitHub CLI；只合并最低未合并且已验收 PR；默认 dry-run。需要实际仓库 branch protection / merge queue 保证服务端 base/CI/review 的最终约束。 |
+| FR-05 Program/Playbooks | ProgramCoordinator、pilot、rolling window、Inbox、close；PR prepare | Program 结束谓词为 all-units-verified。跨 Unit 共同交付须另有 Integrator Workflow；不把独立 Unit 全通过等同于合并产物通过。 |
+| FR-06 Templates | buildTemplate / workflow template / plan | Arena、race、partition、Review、autopilot-stack/full 都编译为现有 DAG；失败 panel 明确阻断，不隐藏失败、不自动降级。 |
+| FR-07 Models/Budget | models panels/workflows、node thinkingLevel/budget、host usage | fail-closed model selection；运行中监测，预算后不派发新节点。单个已发出的模型响应可能超预算，不能承诺供应商硬计费上限。 |
+| FR-08 Context | pstack_context、pstack-handoff | 从 Store 重建索引和 current evidence；可提供 watermark。不是接管 Pi 的自动 compaction，也不以摘要代替事实。 |
+| FR-09 Runner | CLI run；SDK explicit agentDir；lease/fencing | 扫描显式 workflow allowlist；凭据缺失 blocked；租约失效暂停派发并请求取消。FileLock 限定本机共享文件系统，不支持跨主机分布式租约。 |
+| E10 Quality | 原回归、protocol 故障测试、SDK lifecycle、consumer smoke、20-task benchmark harness | SDK 测试使用真实 SDK + loopback provider。20 个真实模型任务基准已提供，尚未运行，不包含 Cursor 实测对照。 |
+
+## 已知不能从本地测试推导的结论
+
+- 不声称真实 LLM 已成功执行全部复杂任务，也不声称等价于 Cursor Cloud Agent 或私有 API。
+- GitHub adapter 的远端调用需 `gh` 与用户授权；本次未使用真实 GitHub token，远端路径由模拟 Provider 覆盖。
+- 命令 allowlist 不能证明项目脚本没有恶意行为。严格任务面对不可信代码，应在操作系统/容器沙箱内运行整个 Pi/Runner；不会把本地受限进程伪装为容器隔离。
+- symlink target 被纳入快照，外部 target 内容不纳入；file gate 拒绝越界 symlink。Git LFS 工作区 hash 使用实际 checkout 字节；跨机器路径身份和大小写差异不提供全局内容寻址保证。
+- 状态锁基于本地文件系统，不保证网络文件系统语义。协议 envelope 随历史增长；当前适合中小型本地项目，未完成百万事件压测。
+- 自动 push、force-push、deploy、删除远端分支未提供。开放 PR 以已验收 commit 和实际 remote branch SHA 为前置，授权 CLI 操作仍需远端状态核查。

package/INSTALLATION-CHECK.md

@@ -0,0 +1,13 @@
+# 安装验证
+
+> **历史记录：** 本文件是早期安装测试记录；包名、SDK 版本和结果属于当时的环境。当前安装方式见 [README](README.md)。
+
+2333 0.6.0-preview.1，Node 24.19.0，官方 Pi SDK 1.1.0。
+
+- 在独立 consumer 目录从实际 tgz 安装：PASS。
+- SDK 扩展加载：PASS。
+- 注册工具：pstack_agents、pstack_workflow、pstack_graph、pstack_worktrees、pstack_verify、pstack_delivery、pstack_context、pstack_program。
+- 安装后的 pstack-runner migrate dry-run：PASS（空 Store，不造验证记录）。
+- 安装后的公开 JS API 导入：PASS，fingerprint / buildTemplate / ProgramCoordinator 可用。
+- CLI 和公开 API 使用 dist JavaScript；Pi 使用 src/extension.ts 的 SDK loader。
+- 未执行真实供应商推理、真实 GitHub merge 或远端 CI。详细边界见 ACCEPTANCE.md。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,14 @@
+# Notices
+
+`pi-pstack-native` is a Pi-native semantic port of **pstack**. Earlier project releases used the package name `2333`.
+
+- **pstack** by Lauren Tan — MIT. Upstream repository: `cursor/plugins`, path `pstack`. It is the source specification for skill names, playbook concepts, principles, and workflow semantics.
+- **Pi** by Earendil Works / contributors — official runtime APIs used by this package through `@earendil-works/pi-coding-agent`.
+
+The 0.6.0-preview.1 runtime does not include or require `@whamp/pi-pstack`, `pi-subagents`, `pi-durable-subagents`, or `pi-agents`.
+
+This project does not claim authorship of upstream pstack. Upstream copyright and MIT terms remain in effect for copied or substantially derived pstack material. The Pi-native runtime, state engine, scheduler, worktree manager, and adaptation code are original implementation work in this package.
+
+The historical skill Markdown and references under `vendor/upstream/0.15.17/pstack/` are copied verbatim from cursor/plugins commit `978ca6e9c0e012047cd5058b8e829240336e704e`. The upstream MIT notice is retained at `vendor/upstream/0.15.17/pstack/LICENSE`.
+
+The active source snapshot is `vendor/upstream/0.15.36/pstack/` at cursor/plugins commit `c742dd61706fbacc1b95f1a20b7b988cf096ce6c`. It retains the upstream MIT license and includes Skill Markdown, references and the statechart toolchain. Generated supported entrypoints retain those upstream bodies. The earlier 0.15.17 snapshot is kept for historical provenance.

package/PARITY.json

@@ -0,0 +1,133 @@
+{
+  "upstream": "0.15.36",
+  "upstreamCommit": "c742dd61706fbacc1b95f1a20b7b988cf096ce6c",
+  "claim": "pinned-source-with-pi-adapter",
+  "skills": {
+    "architect": "ADAPTED",
+    "arena": "ADAPTED",
+    "automate-me": "ADAPTED",
+    "benchmark-checklist": "ADAPTED",
+    "blast-radius": "ADAPTED",
+    "bro": "ADAPTED",
+    "correct": "ADAPTED",
+    "create-formal-verification-skill": "ADAPTED",
+    "create-verification-skill": "ADAPTED",
+    "figure-it-out": "ADAPTED",
+    "how": "ADAPTED",
+    "in-your-own-words": "ADAPTED",
+    "interrogate": "ADAPTED",
+    "ketchup": "ADAPTED",
+    "ketchup-video": "ADAPTED",
+    "maintain-formal-verification-skill": "ADAPTED",
+    "maintain-verification-skill": "ADAPTED",
+    "make-bot-ui": "CURSOR_ONLY",
+    "no-comments": "ADAPTED",
+    "poteto-help": "ADAPTED",
+    "poteto-mode": "ADAPTED",
+    "principle-attack-the-premise": "ADAPTED",
+    "principle-boundary-discipline": "ADAPTED",
+    "principle-build-the-lever": "ADAPTED",
+    "principle-encode-lessons-in-structure": "ADAPTED",
+    "principle-exhaust-the-design-space": "ADAPTED",
+    "principle-experience-first": "ADAPTED",
+    "principle-explain-the-number": "ADAPTED",
+    "principle-fix-root-causes": "ADAPTED",
+    "principle-foundational-thinking": "ADAPTED",
+    "principle-guard-the-context-window": "ADAPTED",
+    "principle-laziness-protocol": "ADAPTED",
+    "principle-make-operations-idempotent": "ADAPTED",
+    "principle-migrate-callers-then-delete-legacy-apis": "ADAPTED",
+    "principle-minimize-reader-load": "ADAPTED",
+    "principle-model-the-domain": "ADAPTED",
+    "principle-never-block-on-the-human": "ADAPTED",
+    "principle-outcome-oriented-execution": "ADAPTED",
+    "principle-prove-it-works": "ADAPTED",
+    "principle-redesign-from-first-principles": "ADAPTED",
+    "principle-separate-before-serializing-shared-state": "ADAPTED",
+    "principle-sequence-verifiable-units": "ADAPTED",
+    "principle-subtract-before-you-add": "ADAPTED",
+    "principle-test-behavior-not-implementation": "ADAPTED",
+    "principle-type-system-discipline": "ADAPTED",
+    "recall": "ADAPTED",
+    "reflect": "ADAPTED",
+    "setup-pstack": "ADAPTED",
+    "sharpen": "ADAPTED",
+    "show-me-your-work": "ADAPTED",
+    "statechart": "ADAPTED",
+    "swarm": "ADAPTED",
+    "tdd": "ADAPTED",
+    "teach": "ADAPTED",
+    "technical-writing": "ADAPTED",
+    "typescript-best-practices": "ADAPTED",
+    "unslop": "ADAPTED",
+    "why": "ADAPTED"
+  },
+  "playbooks": {
+    "authoring-a-skill": "ADAPTED",
+    "autonomous-run": "ADAPTED",
+    "autopilot-full": "ADAPTED",
+    "autopilot-stack": "ADAPTED",
+    "babysit": "ADAPTED",
+    "bug-fix": "ADAPTED",
+    "eval": "ADAPTED",
+    "feature": "ADAPTED",
+    "hillclimb": "ADAPTED",
+    "investigation": "ADAPTED",
+    "multi-phase-plan": "ADAPTED",
+    "opening-a-pr": "ADAPTED",
+    "orchestrate": "ADAPTED",
+    "pause-safely": "ADAPTED",
+    "perf-issue": "ADAPTED",
+    "prototype": "ADAPTED",
+    "refactoring": "ADAPTED",
+    "runtime-forensics": "ADAPTED",
+    "session-pickup": "ADAPTED",
+    "shipping": "ADAPTED",
+    "trace-forensics": "ADAPTED",
+    "visual-parity": "ADAPTED",
+    "worktree-cleanup": "ADAPTED"
+  },
+  "piOnly": {
+    "pstack-runtime": "PI_ONLY",
+    "native-agent-runtime": "PI_ONLY",
+    "durable-workflow-engine": "PI_ONLY",
+    "pstack-loop": "PI_ONLY"
+  },
+  "cursorOnly": [
+    "make-bot-ui"
+  ],
+  "unsupportedPlatformBehavior": [
+    "Cursor private built-in PR-tool provenance",
+    "upstream watcher merge-queue verdict protocol",
+    "Cursor-only cleanup plugins",
+    "Benny automations (no Pi event source; documented as unsupported in plan section 0.11)"
+  ],
+  "pending": [],
+  "coverage": {
+    "topLevelSkills": 58,
+    "potetoPlaybooks": 23,
+    "countEvidence": "docs/upstream-sync-0.15.36.json",
+    "records": "docs/registry-records-0.15.36.json",
+    "countsMean": "observed upstream names, not exercised behavior",
+    "behavioralAudit": "not-claimed",
+    "ketchupEvidence": "Pi skill loader and structural sections only; chat behavior not exercised (issue #6)",
+    "fileLevelAudit": "not-claimed",
+    "auxiliaryFiles": "All latest Skill Markdown/references and statechart scripts are pinned; other scripts, assets and external platform dependencies are not claimed equivalent.",
+    "targetSkills": 58,
+    "targetPlaybooks": 23,
+    "targetInventory": "docs/upstream-target-0.15.36.json",
+    "pendingTargetSkills": [],
+    "pendingTargetReasons": {},
+    "semanticMapping": "SEMANTICS.json",
+    "semanticMappingScope": "11 core workflows; critical rules only; see per-rule evidence boundaries",
+    "behavioralParity": "not-claimed"
+  },
+  "previousBaseline": {
+    "version": "0.15.32",
+    "commit": "99b609a72323b70204eab407c622f436e858e112",
+    "previousBaseline": {
+      "version": "0.15.17",
+      "commit": "978ca6e9c0e012047cd5058b8e829240336e704e"
+    }
+  }
+}

package/PARITY.md

@@ -0,0 +1,156 @@
+# pstack 0.15.36 source integration on Pi 1.4
+
+The active source is `cursor/plugins` commit `c742dd61706fbacc1b95f1a20b7b988cf096ce6c` (pstack 0.15.36). Pi SDK 1.4.0 is locked and the peer minimum is `^1.4.0`. [Provenance](docs/upstream-provenance-0.15.36.json) verifies all 573 upstream blobs; [source counts](docs/upstream-sync-0.15.36.json) record 58 Skills and 23 playbooks.
+
+All upstream names are registered. The 57 supported Skills and all 23 playbooks are generated from unchanged upstream bodies plus a separate Pi adapter. `make-bot-ui` remains unsupported. Statechart includes the 0.15.36 TypeScript runtime and test corpus, its CLI and external-tool requirements; see [statechart evidence](docs/STATECHART.md). The file inventory distinguishes local source, vendored source, unsupported operations and remaining platform-only work; name coverage is not full file or behavioral parity.
+
+The 0.15.17 snapshot is historical provenance, not the active Skill source. The source upgrade does not grant maintainer semantic approval or fabricate authenticated model evidence. See [the upgrade audit](docs/upstream-upgrade-0.15.36.md) and [current evidence boundary](docs/SEMANTIC-COMPATIBILITY.md).
+
+## Native additions 0.6.0-preview.1
+
+Brief/Gate/Ledger/Frontier/Program and specialized DAG templates are native implementations. They do not prove full Cursor parity or benchmark superiority. See [IMPLEMENTATION.md](IMPLEMENTATION.md) and [ACCEPTANCE.md](ACCEPTANCE.md) for the proof boundary.
+
+## Runtime mapping
+
+| Upstream concept | Native implementation |
+|---|---|
+| Task subagent | Pi `AgentSession` through `AgentHost` |
+| parallel Tasks | persistent DAG workflow engine |
+| cloud agent | Pi child session; independent parallel writers use Git worktree isolation |
+| model rule | `~/.pi/agent/pstack-native/models.json` |
+| Custom Mode | sticky `/poteto-mode` |
+| `/loop` | `/pstack-loop` session scheduler (active Pi session, one-run catch-up) |
+| interrupted worker | reopen child Pi session and resume |
+| several isolated writer outputs | explicit `integrator` node converges into target checkout |
+
+## Skills
+
+| Skill | Status |
+|---|---|
+| `architect` | ADAPTED |
+| `arena` | ADAPTED |
+| `automate-me` | ADAPTED |
+| `benchmark-checklist` | ADAPTED |
+| `blast-radius` | ADAPTED |
+| `bro` | ADAPTED |
+| `correct` | ADAPTED |
+| `create-formal-verification-skill` | ADAPTED |
+| `create-verification-skill` | ADAPTED |
+| `figure-it-out` | ADAPTED |
+| `how` | ADAPTED |
+| `in-your-own-words` | ADAPTED |
+| `interrogate` | ADAPTED |
+| `ketchup` | ADAPTED |
+| `ketchup-video` | ADAPTED |
+| `maintain-formal-verification-skill` | ADAPTED |
+| `maintain-verification-skill` | ADAPTED |
+| `make-bot-ui` | CURSOR_ONLY |
+| `no-comments` | ADAPTED |
+| `poteto-help` | ADAPTED |
+| `poteto-mode` | ADAPTED |
+| `principle-attack-the-premise` | ADAPTED |
+| `principle-boundary-discipline` | ADAPTED |
+| `principle-build-the-lever` | ADAPTED |
+| `principle-encode-lessons-in-structure` | ADAPTED |
+| `principle-exhaust-the-design-space` | ADAPTED |
+| `principle-experience-first` | ADAPTED |
+| `principle-explain-the-number` | ADAPTED |
+| `principle-fix-root-causes` | ADAPTED |
+| `principle-foundational-thinking` | ADAPTED |
+| `principle-guard-the-context-window` | ADAPTED |
+| `principle-laziness-protocol` | ADAPTED |
+| `principle-make-operations-idempotent` | ADAPTED |
+| `principle-migrate-callers-then-delete-legacy-apis` | ADAPTED |
+| `principle-minimize-reader-load` | ADAPTED |
+| `principle-model-the-domain` | ADAPTED |
+| `principle-never-block-on-the-human` | ADAPTED |
+| `principle-outcome-oriented-execution` | ADAPTED |
+| `principle-prove-it-works` | ADAPTED |
+| `principle-redesign-from-first-principles` | ADAPTED |
+| `principle-separate-before-serializing-shared-state` | ADAPTED |
+| `principle-sequence-verifiable-units` | ADAPTED |
+| `principle-subtract-before-you-add` | ADAPTED |
+| `principle-test-behavior-not-implementation` | ADAPTED |
+| `principle-type-system-discipline` | ADAPTED |
+| `recall` | ADAPTED |
+| `reflect` | ADAPTED |
+| `setup-pstack` | ADAPTED |
+| `sharpen` | ADAPTED |
+| `show-me-your-work` | ADAPTED |
+| `statechart` | ADAPTED |
+| `swarm` | ADAPTED |
+| `tdd` | ADAPTED |
+| `teach` | ADAPTED |
+| `technical-writing` | ADAPTED |
+| `typescript-best-practices` | ADAPTED |
+| `unslop` | ADAPTED |
+| `why` | ADAPTED |
+
+## Poteto playbooks
+
+| Playbook | Status |
+|---|---|
+| `authoring-a-skill` | ADAPTED |
+| `autonomous-run` | ADAPTED |
+| `autopilot-full` | ADAPTED |
+| `autopilot-stack` | ADAPTED |
+| `babysit` | ADAPTED |
+| `bug-fix` | ADAPTED |
+| `eval` | ADAPTED |
+| `feature` | ADAPTED |
+| `hillclimb` | ADAPTED |
+| `investigation` | ADAPTED |
+| `multi-phase-plan` | ADAPTED |
+| `opening-a-pr` | ADAPTED |
+| `orchestrate` | ADAPTED |
+| `pause-safely` | ADAPTED |
+| `perf-issue` | ADAPTED |
+| `prototype` | ADAPTED |
+| `refactoring` | ADAPTED |
+| `runtime-forensics` | ADAPTED |
+| `session-pickup` | ADAPTED |
+| `shipping` | ADAPTED |
+| `trace-forensics` | ADAPTED |
+| `visual-parity` | ADAPTED |
+| `worktree-cleanup` | ADAPTED |
+
+## Claim boundary
+
+- `ADAPTED` means behavior is represented with Pi-native instructions. It is not a test result or proof of complete behavioral equivalence.
+- Ketchup has official Pi loader and structural tests. Chat behavior itself was not exercised. That harness belongs to issue #6.
+- PR-body and handoff tests use local fixture state. They do not prove live forge behavior.
+- `CURSOR_ONLY` is explicit and never silently treated as working.
+- `PENDING_PORT` must be zero before a release can claim its **listed top-level semantic coverage**.
+- This release does **not** claim byte-for-byte or auxiliary-file parity with Cursor pstack.
+- `PARITY.json.coverage.fileLevelAudit = "not-claimed"` keeps the 52/23 observed name count separate from auxiliary-file and behavioral coverage.
+
+## Attribution
+
+Upstream pstack is by Lauren Tan under MIT terms. This port is independent and is not endorsed by Cursor. Preserve upstream copyright and license obligations for derived material. See [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md).
+
+## Historical 0.15.23 candidate (superseded)
+
+This archived candidate predates the current 0.15.36 source integration. The restatement Skill,
+chat catch-up/verification/Poteto rules, safe bundled-resource access,
+external evidence snapshots, linear PR-stack CLI, all-page review-thread
+checks and explicit-base worktree audit are candidate implementations.
+[The candidate receipt](docs/upstream-sync/candidate-0.15.23.json) maps every
+pinned diff to code/tests or an explicit platform limit. All entries await
+maintainer semantic review. The active Skill loader can expose candidate
+Skills; their availability does not advance the reviewed baseline.
+
+Exact Cursor watcher/merge-queue verdicts, Bugbot pass-based dismissal policy,
+Cursor manifests/cloud/private-tool provenance and Cursor transcript/simulator
+cleanup remain unsupported. Local read-only investigation uses supplied
+snapshots rather than implicit MCP access. Native head/base verification stays
+stricter than the upstream patch-ID/noisy-build reuse rule.
+
+## Core semantic compatibility audit (issue #16)
+
+All supported entrypoints retain the latest pinned upstream body; the eleven core workflows have critical mappings and an explicit [Pi adapter](docs/PI-SEMANTIC-ADAPTER.md). [SEMANTICS.json](SEMANTICS.json) maps exact source lines and critical rules to test names and reviewed file fingerprints. The source snapshot contains all baseline Skill Markdown and references plus the license, checked against Git blob IDs. This is critical-rule mapping coverage, not a completed audit of every sentence or demonstrated model behavior.
+
+`npm run check:semantics` fails on unreviewed local source, adapter, implementation or bound-test drift. `npm run check:semantics -- --from /path/to/cursor-plugins --commit <full-sha>` reports file/step diffs and blocks only unreviewed relevant upstream changes. Explicit per-file, exact-commit sign-off receipts may acknowledge a change without advancing the baseline. Inventory scans cannot advance semantic approval.
+
+See [the evidence tiers and real-model procedure](docs/SEMANTIC-COMPATIBILITY.md). The active source and inventory target are both 0.15.36. Maintainer semantic sign-off remains separate from that source pin.
+
+[PR #17](https://github.com/2333sky/pi-pstack-native/pull/17) has merged the core implementation. [Its CI](https://github.com/2333sky/pi-pstack-native/actions/runs/40299080693) passed on Node 22.19 and 24, including semantic checks and offline/fake-provider Pi SDK tests. This does not change `SEMANTICS.json.evidence.realModel.status = "not-run"` or `review.status = "pending-maintainer-signoff"`. See [the acceptance checklist](docs/SEMANTIC-COMPATIBILITY.md#completing-issue-16) for the remaining evidence and review record. Neither merging this implementation nor completing its CI advances the reviewed upstream baseline.