pi-pstack-native 0.0.0-stage → 1.0.0

package/docs/UPSTREAM-0.15.17.md

@@ -0,0 +1,51 @@
+# Upstream 0.15.17 review
+
+## Verified material
+
+The GitHub commit API returned `978ca6e9c0e012047cd5058b8e829240336e704e` for 0.15.17 and `00b14f1df36b32a8dd1529324a3a459f6563b127` for 0.15.16. The pinned archive's plugin manifest says `0.15.17`. All 165 pstack files matched the Git blob SHAs in the untruncated official tree. [The provenance file](upstream-provenance-0.15.17.json) records URLs, SHAs, and the complete changed-file list.
+
+```bash
+gh api repos/cursor/plugins/commits/978ca6e9c0e012047cd5058b8e829240336e704e
+gh api repos/cursor/plugins/commits/00b14f1df36b32a8dd1529324a3a459f6563b127
+curl -fsSL https://api.github.com/repos/cursor/plugins/tarball/978ca6e9c0e012047cd5058b8e829240336e704e -o /tmp/parity-upstream.tar.gz
+mkdir -p /tmp/parity-upstream-01517
+tar -xzf /tmp/parity-upstream.tar.gz --strip-components=1 -C /tmp/parity-upstream-01517
+node scripts/sync-upstream.mjs --from /tmp/parity-upstream-01517/pstack --write-report docs/upstream-sync-0.15.17.json
+```
+
+The sync run passed with 52 skills, 23 playbooks, and no name drift. It reports runtime seams, not semantic approval. Counts come from the official tree, not ADAPTED labels.
+
+## 0.15.16 wording review
+
+The official commit is a prompt-distillation change. The review below covers its changed content by group. Local ports retain shorter Pi instructions rather than copying each prompt and auxiliary file. ADAPTED labels describe represented intent, not a behavioral audit.
+
+| Upstream change group | Semantic point retained or strengthened | Intentional Pi difference |
+|---|---|---|
+| `architect`, `arena` | Ground the design, compare shapes, choose a base, graft deliberately, verify the final artifact. | Native roles and worktrees replace Cursor model defaults and Task calls. A narrow design can remain local. Runner templates are not vendored. |
+| `benchmark-checklist`, `principle-explain-the-number` | Measure the limiter, tune both sides, count errors, confirm work ran, and compare end-to-end impact. | Local guidance asks for enough alternating trials rather than a universal five-run rule. A requested one-run ballpark is labeled. No performance claim is added. |
+| `figure-it-out`, `how` | Keep the hypothesis loop, verifiable units, and complexity-based exploration. | Pi durable workflows replace Task fanout. A simple explanation can stay in the parent rather than require a child. |
+| `interrogate` and reviewer/rubric references | Review execution against intent, trace callers and failure paths, reconcile independent findings, and separate blockers from preference. The PR playbook now names these checks. | Local reviewers may have distinct angles. Upstream favors model diversity over assigned personas. Auxiliary reviewer prompts are not vendored. |
+| `poteto-mode` | Read leaf principles, keep investigations read-only, use prototypes for observable questions, apply prose checks, and declare PR status mode before polling. | The local skill now makes these triggers explicit. Native tools and the stricter external-write authorization rule remain. |
+| `opening-a-pr` | Retain a short review brief, mandatory Scope, ready PRs, parent-targeted stacks, tool provenance, and deferred babysit. | GitHub API and CLI access do not implement Cursor's private PR-tool metadata. Cleanup is a diff reread without a mandatory Cursor plugin. Local Verification and other required headings cannot be dropped. |
+| `trace-forensics` | A fixed capture stays read-only. A paired capture can confirm a finding. Without one, label the strongest supported hypothesis. | Use available parsers and Pi evidence. No Cursor control tool is required. |
+| `principle-build-the-lever`, `principle-encode-lessons-in-structure` | Make evidence rerunnable and put recurring constraints in structure. | The local PR validator is a small deterministic check, not a new framework. |
+| `principle-minimize-reader-load`, `principle-model-the-domain`, `principle-type-system-discipline` | Minimize hidden state and indirection. Model real states and parse at boundaries. | Local principles keep the compact Pattern/Avoid/Proof form instead of copying upstream examples. |
+| `principle-never-block-on-the-human`, `principle-redesign-from-first-principles`, `principle-subtract-before-you-add`, `principle-test-behavior-not-implementation` | Proceed on reversible work, integrate requirements coherently, remove dead paths, and assert observed behavior. | Publishing and merges still need explicit authorization. Structural skill tests prove text and loader behavior only. |
+| `reflect` and reviewer/synthesizer references | Keep workspace-bounded evidence, reject already-covered lessons, and require approval before skill edits. | Approval and routing are now explicit locally. Read-only Pi reviewers do not inherit Cursor agent-mode MCP behavior. Backlog writes also need authorization. Auxiliary role prompts are not vendored. |
+| `technical-writing`, `unslop` | Keep complete sentences, real identifiers, one action word, short PR briefs, concrete claims, and no decorative metaphors. | Local writing skills now strengthen these checks but keep compact instructions instead of the full numbered catalog. |
+| `why` and epistemics/investigator/source/synthesizer references | Keep historical citations, confidence separation, source gaps, and caution about telemetry correlation. | Local fact/inference/unknown labels are coarser than upstream's five tiers. Source-specific MCP instructions are not vendored. No access to absent sources is implied. |
+| plugin manifest | The version moves to 0.15.16 before 0.15.17. | Pi package version remains independent of the upstream semantic baseline. |
+
+## 0.15.17 ketchup port
+
+The new skill uses `/skill:ketchup`, not a Cursor command. It finds the last user-authored message before the request. Role alone is not evidence of authorship. Notifications, scheduled prompts, and child completion messages do not move the cutoff. Unknown provenance is a stated gap, not a guessed cutoff.
+
+Status rechecks are read-only. Only user-dependent decisions or steps are action items. Older unanswered items remain visible. Each summary names the affected work, choices, costs, recommendation, and unanswered default so it remains useful outside the chat.
+
+## Evidence and limits
+
+`node --test docs/parity.test.mjs` checks the official Pi skill loader, required ketchup text, PR-body validation, and fixture handoff negatives. [The stack guide](PR-PROTOCOL.md) includes a sample.
+
+Chat behavior itself was not exercised. That harness belongs to issue #6. No credentialed model call ran. Live stack operations, independent model review behavior, and Cursor private platform behavior are not proven by these checks.
+
+Upstream pstack is by Lauren Tan under MIT terms. Preserve [LICENSE](../LICENSE) and [NOTICE.md](../NOTICE.md). This independent port is not endorsed by Cursor.

package/docs/VALIDATION.md

@@ -0,0 +1,59 @@
+# Release chain validation record — 2026-10-11
+
+This record covers the release chain only. Package `2333@0.6.0-preview.1`, official Pi SDK 1.1.0, Node 22.19.0, 24.21.0 and 26.0.0. Earlier notes in `ACCEPTANCE.md` and in the replaced version of this file described a different container and left most release steps unrun.
+
+## Reproduce
+
+```bash
+npm install
+npm run check:release
+```
+
+`npm run check:release` runs the source checks, the strict typecheck, the build, the Pi SDK session smoke, the offline benchmark integrity check, and then packs the real tarball, installs it into a clean consumer directory, and loads the installed extension, public JavaScript API and CLI. `npm pack` in this repository runs the same chain through `prepack`, so the tarball is gated when it is created. npm runs no lifecycle for `npm publish ./file.tgz`, so a tarball packed elsewhere carries no gate.
+
+## Results
+
+| Step | Result | Proof boundary |
+|---|---|---|
+| `npm run check:syntax` | PASS, 79 files | Syntax only |
+| `npm run check:package` | PASS | Package policy only |
+| `npm run check:parity` | PASS | Declared semantic scope, not source equivalence |
+| `npm test` | PASS, 100 tests | Branch behavior, not absence of every defect |
+| `npm run check:types` | PASS | Installed Pi SDK and TypeScript, strict, source and tests |
+| `npm run build` | PASS | Compiled JavaScript, declarations and CLI |
+| `npm run check:host` | PASS | Real AgentSession creation, no provider inference |
+| `npm run benchmark:smoke` | PASS | Entry links for real, 20 fixtures validate, no model run |
+| `npm run smoke:installed` | PASS | Real tarball installed in a clean consumer, Node 22.19.0 and 24.21.0 |
+| `npm publish --dry-run --tag preview` | PASS | Whole publish path, no registry write |
+| GitHub Actions run 38156153556 | PASS | Both matrix jobs, on the bootstrap commit |
+
+Both supported CI runtimes pass the whole chain, run locally on Node 22.19.0 and Node 24.21.0 with dependencies installed:
+
+```text
+################ NODE v22.19.0 ################
+check:release EXIT=0
+ℹ tests 100
+ℹ pass 100
+ℹ fail 0
+Pi SDK session creation contract: PASS (no provider inference performed)
+Benchmark entry imports validated: 4; link: ok; fixtures: 20. No external model was called.
+installed package smoke PASS: .../consumer/node_modules/2333/package.json
+install smoke PASS: 2333-0.6.0-preview.1.tgz (226 KiB) installed with @earendil-works/pi-coding-agent@1.1.0 on Node v22.19.0
+```
+
+## Defects fixed in this change
+
+1. **Benchmark output path.** The entry helper returned `argv[0]` for an absent flag, so a run without `--output` wrote into a directory named `--agent-dir`. Evidence before the fix: `"results": "/private/tmp/pkgtest/--agent-dir/results.json"`.
+2. **Benchmark exit code.** A run that verified 0 of 20 cases printed its summary and exited 0. Now an unverified case, an empty case list, or a blocked runner exits non-zero and prints the reason.
+3. **Benchmark import check.** `scripts/check-benchmark.mjs` matched import text with a regular expression. With the `export` keyword stripped from `runnerOnce` in `dist/runner/service.js` it still printed `imports validated: 4` and exited 0, while a real import failed with `does not provide an export named 'runnerOnce'`. It now spawns a child process that imports the entry for real, and the tampered case exits 1.
+4. **Benchmark entry detection.** The entry guard compared `import.meta.url` with an unresolved `process.argv[1]`, so running the entry through a symlink ran nothing and exited 0, and Node `--preserve-symlinks-main` did the same. The guard now compares the real paths of both sides, and the regression test covers both invocations.
+5. **Standing Orders restore semantics.** `orders.digest` was written by `updateOrders` and read by nobody, so a restored program dispatched instructions that did not match their digest. Dispatch now fails closed with `ORDERS_INTEGRITY_MISMATCH`, and each unit records the orders revision in force when it was dispatched, so a restored program can tell which revision its work ran under. Evidence before the fix: `tampered orders accepted: {"revision":1,"instructions":["TAMPERED RULE"],"digest":"c2304aad..."}`.
+6. **Installed package smoke test.** The script existed in `test/` but no script, CI job or publish step ran it, and it never touched the compiled public API or CLI. It now runs through `npm run smoke:installed` from a real tarball, asserts the published file list, imports the public API from `dist/`, and runs the published CLI.
+7. **Release gate placement.** The strict typecheck and the smoke checks were not part of packing. `prepublishOnly` does not run for `npm publish ./tarball.tgz`, and npm runs no lifecycle at all for a file publish, so the gate now sits on `prepack`. A tarball created by `npm pack` in this repository is gated. A tarball packed elsewhere is not, and that limit is npm's lifecycle, not a choice here.
+
+## Still not verified here
+
+- Authenticated external model inference. The benchmark harness is offline-verified only, so no model success rate, cost or comparison exists yet.
+- Real GitHub PR create and merge against a disposable test repository.
+- No `package-lock.json` is committed, so CI installs are not byte-reproducible.
+- No operating-system sandbox claim. Allowlists and git worktrees are not isolation boundaries.

package/docs/WINDOWS-MODEL-TEST.zh-CN.md

@@ -0,0 +1,27 @@
+# Windows 真实模型测试记录
+
+本记录依据使用者提供的 Windows 实测结果整理。它描述的是一次具体测试，而不是对所有版本、模型或任务的保证。
+
+## 测试环境
+
+- Windows 11、Git Bash；Node.js 24.18.0、npm 11.16.0。
+- Pi 模型：`deepseek/deepseek-flash`，推理等级 `max`。
+- 被测目录不是 Git 仓库，没有记录提交 ID；测试期间修改了本地代码和 benchmark 参数，因此无法据此确认其与某个仓库提交完全一致。
+- 不含真实 GitHub 远程交付测试；报告说明环境没有 `gh`，且测试未推送、未创建 PR。
+
+## 使用者报告的结果
+
+| 项目 | 报告结果 | 范围 |
+| --- | --- | --- |
+| 真实模型 benchmark | 最终一轮 20/20 | 本地测试源码已修复，预算调整为每例 200,000 tokens、600 秒；用于测试的额外 schema 提示已撤掉。 |
+| 本地编排场景 | 6 个场景符合设计 | 覆盖单任务、并行整合、失败阻断、过期证据、只读评审和已完成节点不重复执行。只读评审报告缺少 `findings`，按合同被拒绝。 |
+| 产品和诊断问题 | 报告中列出的修复已提交 | Windows 构建、任务报告格式、解析诊断、验证原因、benchmark 参数和锁竞争等后续修复见 [PR #32](https://github.com/2333sky/pi-pstack-native/pull/32)。 |
+| 完整 Windows 测试 | 并非全通过 | 报告中的 `npm test` 为 179/189，`test:upstream` 为 78/82；涉及符号链接权限、Windows 不支持换行文件名等条件。后续 Windows CI 针对状态持久化、构建和跨进程锁增加了检查。 |
+
+上述结果由用户报告，未在当前环境独立复跑。仓库的 `SEMANTICS.json` 仍未记录绑定提交的真实模型验收回执，维护者语义签署仍待完成。这不否定已经发生的实测；如果将来补充具体提交、测试记录和结果文件，可以作为仓库验收证据进一步核对。
+
+## 独立复跑：提交 4d75ea0b
+
+用户随后报告对 GitHub 压缩包 `4d75ea0b1cf3f6396ea2d06062718a0588611063` 的解压副本进行 Windows 独立复跑：真实模型 benchmark 的工作流验收为 **13/20**；随后逐个重新运行用例测试，**20/20** 的代码结果通过。工作流验收同时检查任务报告和验证证据，不能把该数字直接作为模型代码正确率。
+
+报告还记录 `npm test` 为 182/191、`test:upstream` 为 79/82；剩余失败涉及符号链接权限、换行文件名和 Windows 路径条件。此次未执行真实 GitHub 交付或扩展对照。上述结果由用户提供；本仓库目前没有该次运行的完整原始结果文件，因此不将其登记为已签署的语义验收。

package/docs/evidence/live-github-5deb723.json

@@ -0,0 +1,44 @@
+{
+  "tier": "live-github",
+  "harness": "test/live/github-live.test.ts",
+  "runner": "scripts/e2e-live.mjs",
+  "sourceCommit": "5deb7233524a1db2b1139d8d574a1747fa57a49c",
+  "recordedAt": "2026-10-30T16:17:00Z",
+  "environment": {
+    "pi": "1.4.0",
+    "node": "v26.0.0",
+    "platform": "darwin",
+    "gh": "authenticated operator account"
+  },
+  "target": {
+    "repository": "2333sky/pi-pstack-live-probe",
+    "kind": "disposable private repository created only for this run and deleted afterwards; it held no project data, no credentials and no branch protection",
+    "base": "main",
+    "protection": "no branch protection, no required reviews, no merge queue"
+  },
+  "command": "npm run test:live -- --repo 2333sky/pi-pstack-live-probe --confirm 2333sky/pi-pstack-live-probe --clone /tmp/live-probe --merge",
+  "results": {
+    "read": "passed",
+    "write": "passed",
+    "merge": "passed"
+  },
+  "covered": [
+    "gh reads the named repository and the current head of its base branch",
+    "gh reads one pull request and returns head sha, base ref, CI state and review decision",
+    "the frontier refreshes and plans a dry run against live pull request state",
+    "an operator clone pushes a branch and opens a pull request",
+    "the opened pull request is read back and its head sha matches the pushed commit",
+    "the pull request is closed and its branch deleted",
+    "GitHubCLI.merge runs `gh pr merge --merge --match-head-commit` and the pull request reaches state MERGED",
+    "the merged commit is reachable from the base branch"
+  ],
+  "notCovered": [
+    "submitting a review or a change request",
+    "auto-merge and merge queue behaviour",
+    "branch protection rules, required checks and required reviews",
+    "repository permission levels other than the operator account",
+    "concurrent delivery runs against the same pull request"
+  ],
+  "boundary": "One live create/read/close/merge cycle against an unprotected disposable repository with a single operator account. It does not establish behaviour under branch protection, review requirements or concurrent contention.",
+  "cleanup": "The probe branch and every probe pull request were closed or deleted during the run, and the repository was deleted afterwards. Deleting it needs the `delete_repo` scope, which the operator token had to be granted before the deletion."
+}

package/docs/evidence/semantic-smoke-5deb723.json

@@ -0,0 +1,49 @@
+{
+  "tier": "real-pi-real-model",
+  "harness": "scripts/semantics/real-pi-smoke.mjs",
+  "procedure": "docs/SEMANTIC-COMPATIBILITY.md",
+  "sourceCommit": "5deb7233524a1db2b1139d8d574a1747fa57a49c",
+  "recordedAt": "2026-10-30T16:14:00Z",
+  "environment": {
+    "pi": "1.4.0",
+    "node": "v26.0.0",
+    "platform": "darwin"
+  },
+  "runs": [
+    {
+      "model": "opencode-go/claude-haiku-5-5",
+      "status": "passed",
+      "completeSourceRead": true,
+      "unsupportedRefused": true,
+      "statusRoutedToBabysit": true,
+      "inference": true
+    },
+    {
+      "model": "custom/gpt-5.6-sol",
+      "status": "passed",
+      "completeSourceRead": true,
+      "unsupportedRefused": true,
+      "statusRoutedToBabysit": true,
+      "inference": true
+    },
+    {
+      "model": "opencode-go/gpt-5.6-luna",
+      "status": "passed",
+      "completeSourceRead": true,
+      "unsupportedRefused": true,
+      "statusRoutedToBabysit": true,
+      "inference": true
+    }
+  ],
+  "failedAttempts": [
+    {
+      "model": "custom/gpt-5.5",
+      "status": "failed",
+      "inference": true,
+      "reason": "custom API error (400) model_not_found: unknown provider for model gpt-5.5",
+      "note": "The configured endpoint rejected the model identifier before any probe check ran. This attempt is recorded as failed, not as a passing or blocked probe."
+    }
+  ],
+  "boundary": "One read-only shipping/source/capability/routing probe per model. No implementation, live surface, review swarm, merge or full behavioral parity is covered. The harness persists no raw model output and no credentials.",
+  "notes": "The tested source commit is 5deb723; the commit that adds this file changes only evidence and documentation, and no file listed in SEMANTICS.json.reviewedFiles. Earlier runs that used a model identifier rejected by its provider are recorded above instead of being discarded."
+}

package/docs/parity.test.mjs

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { test } from "node:test";
+import { loadSkillsFromDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+const read = (path) => readFileSync(new URL(`../${path}`, import.meta.url), "utf8");
+const body = "## Why\nReview a small change.\n## What changed\nAdd a check.\n## Scope\nOnly the check. No runtime change.\n## Blast Radius\nRepository checks only.\n## Verification\nThe fixture passed.\n";
+const state = { isDraft: false, base: "feature/root", parentBranch: "feature/root", trunk: "main", babysit: false, phaseComplete: false, ownerFullAutonomy: false };
+const validate = async (text, snapshot = state) => (await import("./validate-pr.mjs")).validatePR(text, snapshot);
+
+test("ketchup loads with valid Pi frontmatter and required sections", () => {
+  const source = read("skills/ketchup/SKILL.md");
+  const { frontmatter } = parseFrontmatter(source);
+  assert.equal(frontmatter.name, "ketchup");
+  assert.equal(typeof frontmatter.description, "string");
+  assert.ok(frontmatter.description.length > 0);
+  assert.equal(frontmatter["disable-model-invocation"], true);
+  const result = loadSkillsFromDir({ dir: resolve("skills/ketchup"), source: "path" });
+  assert.deepEqual(result.diagnostics, []);
+  assert.deepEqual(result.skills.map((skill) => skill.name), ["ketchup"]);
+  for (const section of ["Gather what changed", "Write the reply", "Visuals"]) {
+    assert.ok(source.includes(`## ${section}`), `missing ketchup section ${section}`);
+  }
+  for (const rule of ["last message they wrote", "Notifications", "subagent results", "read-only", "only the user can take", "remembers their last message"]) {
+    assert.ok(source.includes(rule), `missing ketchup rule ${rule}`);
+  }
+});
+
+test("opening and babysit document ready stacked PRs and deferred handoff", () => {
+  const opening = read("skills/poteto-mode/playbooks/opening-a-pr.md");
+  for (const heading of ["Why", "What changed", "Scope", "Tradeoffs", "Blast Radius", "Verification"]) {
+    assert.ok(opening.includes(`## ${heading}`), `missing PR heading ${heading}`);
+  }
+  for (const rule of ["ready, never as a draft", "parent branch", "built-in PR tool", "phase or stack", "full-autonomy", "operator-reserved items never merge automatically", "Babysit stops before merge"]) {
+    assert.ok(opening.includes(rule), `missing opening rule ${rule}`);
+  }
+  const babysit = read("skills/poteto-mode/playbooks/babysit.md");
+  assert.ok(babysit.includes("Opening a PR does not start a babysit"));
+  assert.ok(babysit.includes("full-autonomy"));
+});
+
+test("ready child targets its parent and waits for phase completion", async () => {
+  assert.deepEqual(await validate(body), []);
+  assert.deepEqual(await validate(body, { ...state, parentBranch: null, base: "main" }), []);
+  assert.deepEqual(await validate(body, { ...state, babysit: true, phaseComplete: true }), []);
+  assert.deepEqual(await validate(body, { ...state, babysit: true, ownerFullAutonomy: true }), []);
+});
+
+test("reject a draft PR", async () => {
+  assert.deepEqual(await validate(body, { ...state, isDraft: true }), ["PR must be ready, not draft"]);
+});
+
+test("reject a child with the wrong base", async () => {
+  assert.deepEqual(await validate(body, { ...state, base: "main" }), ["PR base must be feature/root"]);
+});
+
+test("reject premature babysit", async () => {
+  assert.deepEqual(await validate(body, { ...state, babysit: true }), ["babysit must wait for phase or stack completion"]);
+});
+
+test("reject missing Scope or Verification", async () => {
+  for (const heading of ["Scope", "Verification"]) {
+    const incomplete = body.replace(new RegExp(`## ${heading}\\n[^#]+`), "");
+    assert.deepEqual(await validate(incomplete), [`missing section ${heading}`]);
+  }
+});
+
+test("reject empty sections and headings inside fenced code", async () => {
+  assert.deepEqual(await validate(body.replace("Only the check. No runtime change.", "")), ["empty section Scope"]);
+  assert.deepEqual(await validate(body.replace("## Scope", "```md\n## Scope").replace("## Blast Radius", "```\n## Blast Radius")), ["missing section Scope"]);
+});
+
+test("reject malformed snapshots instead of treating strings as authorization", async () => {
+  assert.deepEqual(await validate(body, { ...state, ownerFullAutonomy: "false" }), ["invalid state ownerFullAutonomy"]);
+  assert.deepEqual(await validate(body, { ...state, isDraft: null }), ["invalid state isDraft"]);
+});
+
+test("PR body CLI validates the sample file", () => {
+  const result = spawnSync(process.execPath, ["docs/validate-pr.mjs", "docs/stacked-pr-body.md"], { encoding: "utf8" });
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.stdout, "PR protocol ok\n");
+});