pi-pstack-native 0.0.0-stage → 1.0.0

package/dist/workflow/graph.d.ts

@@ -0,0 +1,10 @@
+import type { WorkflowNodeSpec } from "../runtime/types.js";
+export declare function validateGraph(nodes: WorkflowNodeSpec[]): void;
+export declare function chainNodes(tasks: Array<Omit<WorkflowNodeSpec, "dependsOn">>): WorkflowNodeSpec[];
+export declare function dependencyEdges(nodes: WorkflowNodeSpec[]): Array<{
+    from: string;
+    to: string;
+}>;
+export declare function downstreamKeys(nodes: Record<string, {
+    dependsOn: string[];
+}>, root: string): Set<string>;

package/dist/workflow/graph.js

@@ -0,0 +1,60 @@
+export function validateGraph(nodes) {
+    if (!Array.isArray(nodes) || nodes.length === 0)
+        throw new Error("Workflow requires at least one node.");
+    const keys = new Set();
+    for (const node of nodes) {
+        if (!node.key || ['__proto__', 'constructor', 'prototype'].includes(node.key) || !/^[a-zA-Z0-9._-]+$/.test(node.key))
+            throw new Error(`Invalid workflow node key: ${node.key || "(empty)"}`);
+        if (keys.has(node.key))
+            throw new Error(`Duplicate workflow node key: ${node.key}`);
+        keys.add(node.key);
+        if (!node.task?.trim())
+            throw new Error(`Workflow node ${node.key} has no task.`);
+    }
+    for (const node of nodes) {
+        for (const dep of node.dependsOn ?? []) {
+            if (!keys.has(dep))
+                throw new Error(`Workflow node ${node.key} depends on unknown node ${dep}.`);
+            if (dep === node.key)
+                throw new Error(`Workflow node ${node.key} cannot depend on itself.`);
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const byKey = new Map(nodes.map((node) => [node.key, node]));
+    const visit = (key) => {
+        if (visited.has(key))
+            return;
+        if (visiting.has(key))
+            throw new Error(`Workflow contains a dependency cycle at ${key}.`);
+        visiting.add(key);
+        for (const dep of byKey.get(key)?.dependsOn ?? [])
+            visit(dep);
+        visiting.delete(key);
+        visited.add(key);
+    };
+    for (const key of keys)
+        visit(key);
+}
+export function chainNodes(tasks) {
+    return tasks.map((task, index) => ({ ...task, dependsOn: index === 0 ? [] : [tasks[index - 1].key] }));
+}
+export function dependencyEdges(nodes) {
+    return nodes.flatMap((node) => (node.dependsOn ?? []).map((dep) => ({ from: dep, to: node.key })));
+}
+export function downstreamKeys(nodes, root) {
+    const result = new Set();
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const [key, node] of Object.entries(nodes)) {
+            if (key === root || result.has(key))
+                continue;
+            if (node.dependsOn.some((dep) => dep === root || result.has(dep))) {
+                result.add(key);
+                changed = true;
+            }
+        }
+    }
+    return result;
+}

package/dist/worktree/manager.d.ts

@@ -0,0 +1,20 @@
+export interface WorktreeInfo {
+    path: string;
+    branch: string;
+    repoRoot: string;
+    baseRef: string;
+}
+export declare function gitRoot(cwd: string): Promise<string | undefined>;
+export declare function createWorktree(cwd: string, ownerId: string, baseRef?: string): Promise<WorktreeInfo>;
+export declare function isWorktreeDirty(path: string): Promise<boolean>;
+export declare function removeWorktree(info: WorktreeInfo, force?: boolean): Promise<void>;
+export declare function auditWorktree(info: WorktreeInfo, comparisonBase?: string): Promise<{
+    path: string;
+    branch: string;
+    comparisonBase: string;
+    baseSha: string;
+    headSha: string;
+    dirty: boolean;
+    ahead: number;
+    merged: boolean;
+}>;

package/dist/worktree/manager.js

@@ -0,0 +1,68 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { worktreeRoot } from "../runtime/home.js";
+const execFileAsync = promisify(execFile);
+function safe(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "call";
+}
+async function git(cwd, args) {
+    const result = await execFileAsync("git", args, { cwd, encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
+    return result.stdout.trim();
+}
+export async function gitRoot(cwd) {
+    try {
+        return await git(cwd, ["rev-parse", "--show-toplevel"]);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function createWorktree(cwd, ownerId, baseRef = "HEAD") {
+    const repoRoot = await gitRoot(cwd);
+    if (!repoRoot)
+        throw new Error(`Worktree isolation requires a Git repository: ${cwd}`);
+    const root = worktreeRoot();
+    mkdirSync(root, { recursive: true });
+    const suffix = safe(ownerId);
+    const branch = `pstack-native/${suffix}`;
+    const path = resolve(join(root, `${safe(basename(repoRoot))}-${suffix}`));
+    if (existsSync(path))
+        throw new Error(`Refusing to overwrite existing worktree path: ${path}`);
+    try {
+        await git(repoRoot, ["worktree", "add", "-b", branch, path, baseRef]);
+    }
+    catch (error) {
+        rmSync(path, { recursive: true, force: true });
+        throw error;
+    }
+    return { path, branch, repoRoot, baseRef };
+}
+export async function isWorktreeDirty(path) {
+    return (await git(path, ["status", "--porcelain"])) !== "";
+}
+export async function removeWorktree(info, force = false) {
+    if (!existsSync(info.path))
+        return;
+    if (!force && await isWorktreeDirty(info.path))
+        throw new Error(`Refusing to remove dirty worktree: ${info.path}`);
+    await git(info.repoRoot, ["worktree", "remove", ...(force ? ["--force"] : []), info.path]);
+}
+export async function auditWorktree(info, comparisonBase = info.baseRef) {
+    if (!comparisonBase || comparisonBase.startsWith('-') || !/^[A-Za-z0-9_./-]+$/.test(comparisonBase))
+        throw new Error('Invalid comparison base');
+    const headSha = await git(info.path, ['rev-parse', 'HEAD']), baseSha = await git(info.repoRoot, ['rev-parse', '--verify', `${comparisonBase}^{commit}`]);
+    const actualBranch = await git(info.path, ['branch', '--show-current']);
+    if (actualBranch !== info.branch)
+        throw new Error('Worktree branch changed');
+    const ahead = Number(await git(info.path, ['rev-list', '--count', `${baseSha}..${headSha}`]));
+    let merged = true;
+    try {
+        await git(info.path, ['merge-base', '--is-ancestor', headSha, baseSha]);
+    }
+    catch {
+        merged = false;
+    }
+    return { path: info.path, branch: actualBranch, comparisonBase, baseSha, headSha, dirty: await isWorktreeDirty(info.path), ahead, merged };
+}

package/dist/worktree/snapshot.d.ts

@@ -0,0 +1,2 @@
+/** Copy the exact staged, unstaged and untracked review target into a new Git worktree. */
+export declare function copyReviewSnapshot(source: string, target: string): void;

package/dist/worktree/snapshot.js

@@ -0,0 +1,43 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { copyFileSync, lstatSync, mkdirSync, readlinkSync, realpathSync, symlinkSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { fingerprint, sameFingerprint } from "../artifacts/fingerprint.js";
+/** Copy the exact staged, unstaged and untracked review target into a new Git worktree. */
+export function copyReviewSnapshot(source, target) {
+    const root = realpathSync(execFileSync('git', ['-C', source, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim());
+    const dest = realpathSync(target);
+    const before = fingerprint(root);
+    const git = (args) => execFileSync('git', ['-C', root, ...args], { maxBuffer: 32 * 1024 * 1024 });
+    const apply = (patch, staged) => {
+        if (!patch.length)
+            return;
+        const result = spawnSync('git', ['-C', dest, 'apply', '--binary', ...(staged ? ['--index'] : [])], { input: patch, maxBuffer: 32 * 1024 * 1024 });
+        if (result.status !== 0)
+            throw new Error(`REVIEW_SNAPSHOT_PATCH_FAILED: ${result.stderr.toString('utf8').slice(0, 1000)}`);
+    };
+    apply(git(['diff', '--no-ext-diff', '--binary', '--cached', 'HEAD', '--']), true);
+    apply(git(['diff', '--no-ext-diff', '--binary', '--']), false);
+    const untracked = git(['ls-files', '--others', '--exclude-standard', '-z']).toString('utf8').split('\0').filter(Boolean);
+    for (const path of untracked) {
+        if (isAbsolute(path) || path.split('/').some(part => !part || part === '.' || part === '..'))
+            throw new Error('REVIEW_SNAPSHOT_UNSAFE_PATH');
+        const from = join(root, path), to = join(dest, path);
+        const parent = realpathSync(dirname(from));
+        const rel = relative(root, parent);
+        if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+            throw new Error('REVIEW_SNAPSHOT_UNSAFE_PATH');
+        mkdirSync(dirname(to), { recursive: true });
+        const destParent = realpathSync(dirname(to));
+        if (!destParent.startsWith(`${dest}${sep}`) && destParent !== dest)
+            throw new Error('REVIEW_SNAPSHOT_UNSAFE_PATH');
+        const stat = lstatSync(from);
+        if (stat.isSymbolicLink())
+            symlinkSync(readlinkSync(from), to);
+        else if (stat.isFile())
+            copyFileSync(from, to);
+        else
+            throw new Error('REVIEW_SNAPSHOT_UNSUPPORTED_FILE');
+    }
+    if (!sameFingerprint(before, fingerprint(root)) || !sameFingerprint(before, fingerprint(dest)))
+        throw new Error('REVIEW_SNAPSHOT_CHANGED');
+}

package/docs/DEPENDENCIES.md

@@ -0,0 +1,35 @@
+# Locked dependency review
+
+The active SDK is `@earendil-works/pi-coding-agent` **1.4.0**, the npm `latest` release checked on 2026-10-26. Development uses the exact version and the peer minimum is `^1.4.0`. `package-lock.json` pins the SDK and its dependency graph; `npm ci` reproduces it. The supported Node range stays `>=22.19.0`, matching the SDK.
+
+| Package | Locked version | Declared license |
+|---|---|---|
+| `@earendil-works/pi-coding-agent` | `1.4.0` | MIT |
+| `@earendil-works/pi-agent-core` | `1.4.0` | MIT |
+| `@earendil-works/pi-ai` | `1.4.0` | MIT |
+| `@types/node` | `22.20.5` | MIT |
+| `typescript` | `5.9.3` | Apache-2.0 |
+
+The upgrade was installed and checked on Node 24.19.0 / npm 11.9.0. CI retains Node 22.19.0 and 24.x. SDK lifecycle, source extension loading, compiled API/CLI and a clean installed tarball are separate checks in `npm run check:release`.
+
+## License inventory
+
+The lock contains 120 dependency entries, including optional packages for other platforms.
+
+| Declared license | Locked entries |
+|---|---:|
+| 0BSD | 1 |
+| Apache-2.0 | 37 |
+| BSD-3-Clause | 13 |
+| BlueOak-1.0.0 | 2 |
+| ISC | 7 |
+| MIT | 59 |
+| Unlicense | 1 |
+
+This inventories package metadata rather than asserting a source-level license audit. Keep upstream notices when redistributing code. No node_modules files are committed.
+
+Statechart's Java/TLC and optional PNG renderer are external tools, not new runtime dependencies of the Pi extension. Their pinned versions and validation boundary are in [STATECHART.md](STATECHART.md).
+
+## Historical compatibility
+
+The earlier 1.1.0 to 1.2.0 upgrade repaired an SDK/codemode import mismatch. That history does not establish support for SDK versions older than the current `^1.4.0` peer range.

package/docs/LIVE-TEST-PLAN.zh-CN.md

@@ -0,0 +1,161 @@
+# 真实模型与交付场景测试计划
+
+本文用于验证 `pi-pstack-native` 在真实模型、实际开发任务和 GitHub 交付中的表现，并为与其他 Pi 扩展进行对照提供统一方法。本文是测试计划，不是测试通过记录。离线测试、模拟供应商测试、真实模型推理和真实 GitHub 操作分别记录结果，不互相替代。
+
+项目现有入口和证据边界见 [SEMANTIC-COMPATIBILITY.md](SEMANTIC-COMPATIBILITY.md)、[RUNBOOK.md](RUNBOOK.md)、[examples/README.md](../examples/README.md) 和 [ACCEPTANCE.md](../ACCEPTANCE.md)。执行时以被测 commit 的代码和文档为准；旧报告只适用于其记录的版本和环境。
+
+## 1. 测试准备
+
+- 固定并记录本项目 commit、Pi 版本、Node 和 npm 版本、操作系统、模型供应商/模型 ID、推理级别及角色配置。对照扩展也要记录其版本、依赖及配置。
+- 使用隔离的测试工作区及专门的 Pi agent 目录。设置预算和超时上限；记录调用次数、token 和费用，并限制并发，避免意外支出。
+- 模型测试需要真实供应商授权和可用模型。GitHub 登录或 ChatGPT 登录本身不代表 Pi 已配置模型。凭证通过运行环境的安全配置提供；不要写入仓库、命令输出、报告或示例文件。
+- 真实 GitHub 写入使用操作者明确指定的可丢弃仓库、专用克隆和受限账号。确认目标仓库、分支保护、CI 配置及权限；确保测试克隆干净，能切换到指定 base 分支。worktree 和只读工具不构成操作系统沙箱。
+- 测试数据和输出保存在仓库外或专用目录。保留来源 commit、配置摘要、日志、验证记录及人工检查结果；分享前检查敏感信息。
+
+在项目根目录确认环境并运行基线检查：
+
+```bash
+git status --short
+git rev-parse HEAD
+node --version
+npm --version
+pi --version
+pi --list-models
+
+npm ci
+npm run check
+npm run check:types
+npm run check:e2e
+npm run build
+npm run check:host
+```
+
+这些检查验证源码、类型、构建、SDK 或模拟场景；即使全部通过，也不代表调用了真实模型或 GitHub。安装依赖和执行仓库脚本会运行项目代码，应在信任的环境中进行。`pi --list-models` 用于选择准确 ID；模型列出也不等于凭证和调用已验证。
+
+## 2. 真实模型语义冒烟测试
+
+选择实际可用的 `provider/model`，在项目根目录执行：
+
+```bash
+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
+```
+
+将 `provider/model` 替换为真实模型 ID；分别保存退出码、`result.json` 和 commit。该探针在临时工作区只启用两个只读模型工具，不启动写入代理或访问 GitHub。
+
+| 结果 | 判定 |
+| --- | --- |
+| 退出码 0，`status: "passed"`、`inference: true`，`completeSourceRead`、`unsupportedRefused`、`statusRoutedToBabysit` 均为 true | 该 commit 与模型通过有限语义探针。 |
+| 退出码 2，`status: "blocked"`、`inference: false` | 模型或认证不可用；标记为阻塞，没有真实推理证据。 |
+| 退出码 1、结果不完整或任一检查失败 | 标记为失败，保留原因并排查。 |
+
+该测试不能证明完整工作流、多代理审查、UI/CLI 交互或 PR 合并行为。若结果要进入正式项目记录，应按 [SEMANTIC-COMPATIBILITY.md](SEMANTIC-COMPATIBILITY.md) 的证据与维护者审阅流程操作，不能把模型调用通过等同于语义审核通过。
+
+## 3. 真实模型开发任务
+
+先运行项目的简单 bug-fix benchmark。其使用单独配置了 SDK 认证和模型的 Pi agent 目录，并要求输出绝对路径：
+
+```bash
+npm run benchmark -- \
+  --agent-dir /absolute/path/to/dedicated-pi-agent \
+  --model provider/model \
+  --output /absolute/path/to/benchmark-output
+```
+
+脚本生成 20 个种子 bug-fix 仓库，记录执行、验证和供应商用量。记录各案例结果、退出码、失败和阻塞原因；不可用模型不是失败修复，也不能算通过。`npm run benchmark:smoke` 仅验证离线入口和 fixture，**不调用真实模型**。这些简单题不能证明复杂协作或交付表现，详见 [examples/README.md](../examples/README.md)。
+
+在此基础上另备固定快照的测试仓库；先准备代理不可修改的独立验收测试，测试结束后对最终代码运行。每次用新的干净工作区，记录工作树、最终 diff、检查命令、退出码与工作流状态。
+
+| 场景 | 执行 | 预期证据 |
+| --- | --- | --- |
+| 单任务修复 | 给可复现 bug，要求修复、验证并解释结果。 | 独立回归测试通过；实际命令与退出码可查。 |
+| 并行写入与集成 | 两个工作者分别修改不同模块，再由集成者合并并验证。 | 记录不同 worktree、集成后的两个改动，以及针对最终产物的独立测试。 |
+| 检查失败 | 提供一个故意失败的验收条件或验证命令。 | 系统报告失败或阻塞；没有把失败标成已验证。 |
+| 中断恢复 | 只在可丢弃环境中，在运行中终止拥有测试工作流的进程，检查状态后恢复。 | 已完成节点不被误重跑；进行中节点恢复或明确失败；无虚假的通过结果。 |
+| 产物变化 | 验证后改动测试产物或 commit，再尝试使用旧证据。 | 旧证据被标记过期或被阻断；重新验证后才可使用。 |
+| 独立审查 | 准备带已知缺陷的变更，交由只读审查角色检查。 | 审查者能读取所需内容，发现结果可追溯；没有写工具。漏报如实记录。 |
+
+示例任务提示词，可针对 fixture 调整：
+
+> 使用 pstack workflow 修复测试仓库中的两个独立问题。先给出计划和验收条件；分别执行修改，集成后验证最终工作区。不要 push、创建 PR 或合并。报告各节点状态、最终 diff、实际执行的检查及退出码。
+
+操作者独立核对最终代码及测试结果，不能只采信代理的自然语言报告。中断恢复的断言应通过会话、节点和工作区记录核实；是否产生重复外部操作还需单独检查远端。
+
+## 4. 真实 GitHub 交付
+
+### 4.1 项目自带的实时探针
+
+在本项目根目录使用已认证的 `gh`，先运行只读探针。将 `owner/disposable-repo` 换成同一个实际的可丢弃仓库，base 换成其实际分支：
+
+```bash
+node --experimental-strip-types scripts/e2e-live.mjs \
+  --repo owner/disposable-repo \
+  --confirm owner/disposable-repo \
+  --base main
+```
+
+可按 [RUNBOOK.md](RUNBOOK.md) 添加 `--pr` 读取已有 PR。确认目标仓库和测试克隆后，再按需执行会产生远端写入的探针：
+
+```bash
+node --experimental-strip-types scripts/e2e-live.mjs \
+  --repo owner/disposable-repo \
+  --confirm owner/disposable-repo \
+  --base main \
+  --clone /absolute/path/to/disposable-clone \
+  --write
+```
+
+**写入探针会切换测试克隆的分支，创建并推送临时分支，创建真实 PR，读取 PR，然后尝试关闭 PR 和删除分支。它不会合并 PR，也不调用真实模型。** 检查测试是否被跳过、退出码及 GitHub 实际状态；中断后核查并按输出清理遗留 PR、远端分支、克隆状态和临时目录。上述脚本行为可对照 [github-live.test.ts](../test/live/github-live.test.ts)。
+
+### 4.2 真实模型到真实 PR 的端到端测试
+
+自带的 GitHub 探针与模型探针彼此独立，不能合起来直接证明模型交付。要测试完整链路，在可丢弃仓库中：
+
+1. 准备带确定性失败测试的问题、CI 和受保护 base；记录起始 commit、验收条件和操作者。
+2. 启动真实模型任务，先修复、集成并执行独立测试；检查最终 diff、工作流及验证 ledger。
+3. 提交并推送测试分支。按 [examples/README.md](../examples/README.md) 为实际 PR 的当前 commit 重新取得 `run-pr` 验证证据；检查目标仓库、head、base、CI 和审查状态。
+4. 先通过项目命令执行 dry-run，检查阻断条件。真实创建 PR、推送或合并属于独立的远端写操作，应由操作者针对测试仓库明确授权；不可把 dry-run 当成已交付。
+5. 检验负向条件：验证后移动 head、CI 失败、审查未满足或远端证据不可用时，不得沿用旧证据进入合并。恢复正常条件后重新验证，再执行已明确授权的测试合并。
+6. 查询实际 PR 和目标分支，核对合并的代码、head/base 和 CI；在目标分支重新执行验收测试。对多 PR stack，额外检查依赖顺序、base 变化和逐个重新授权。
+
+实际测试前阅读 [PR-PROTOCOL.md](PR-PROTOCOL.md) 和 [examples/README.md](../examples/README.md)，按被测版本准备 strict Brief、验证策略和真实 PR 配置。远端写操作不是本地日志所能保证的 exactly-once：发生中断后先读取远端状态，再决定是否重试。
+
+## 5. 扩展对照测试
+
+至少比较裸 Pi、`pi-pstack-native` 和一个对照扩展；按需要加入更多扩展。固定模型版本、推理级别、任务描述、起始 commit、外部工具、权限、时间与费用上限。每次使用独立工作区和新会话；记录各方案依赖、代理数量和实际调用。如果方案不能支持同一任务，记录为不支持或阻塞，不把它当成零分实现。
+
+先选 3–5 个代表性任务，包括简单修复、跨模块改动、并行集成和交付阻断；每组每题重复 2–3 次作为试运行。样本少时只用于发现问题，不能据此断言整体优劣。扩展前应固定题集与验收方法，尽量交错运行顺序，记录模型或环境变更。
+
+| 指标 | 记录方法 |
+| --- | --- |
+| 独立验收成功率 | 最终代码通过事先准备的独立测试的次数 / 完成尝试次数；另列阻塞次数。 |
+| 错误完成 | 声称完成或验证通过，但独立验收失败的次数。 |
+| 集成与交付正确性 | 最终变更是否齐全，PR head/base、CI 和验证证据是否一致。 |
+| 恢复与阻断 | 中断恢复结果、失败传播、旧证据失效、重复远端操作。 |
+| 资源和人工成本 | 耗时、调用数、token、费用、人工介入次数。 |
+| 失败分类 | 代码实现、扩展运行时、模型、权限、环境或未知；保留原始证据。 |
+
+比较时保留每次运行的原始结果，报告样本数与不确定性；模型自评或技能数量不作为独立成功证据。
+
+## 6. 结果记录模板
+
+```text
+日期及操作者：
+测试项目 commit / 包版本：
+Pi / Node / npm / OS：
+供应商与模型 / 推理级别 / 角色配置：
+场景、任务 ID、仓库起始 commit：
+隔离环境及权限范围：
+预算、并发和超时：
+执行命令 / 工作流 ID / 实际检查及退出码：
+最终产物 commit / PR head 和 base（如适用）：
+独立验收结果 / CI / 审查状态：
+token、费用、耗时和人工介入：
+结果：通过 / 失败 / 阻塞 / 跳过
+日志与证据位置：
+已知限制、未验证项和后续事项：
+```
+
+测试结果只对记录的代码版本、配置、模型和场景负责。不要把 skipped、blocked、模拟 provider 或 dry-run 记为真实模型、真实 PR 或真实合并通过。

package/docs/ML-WORKFLOWS.zh-CN.md

@@ -0,0 +1,49 @@
+# AI 算法研发工作流
+
+`ml-development` 是随 pi-pstack-native 提供的 Pi Skill，用于组织机器学习、深度学习和大模型评测任务。它把数据、实验与证据串起来，适用于已有项目，也适用于从零搭建小型实验。它提供工作方法和记录模板；训练框架、数据、计算资源和评测命令仍由实际项目决定。
+
+## 开源实践调研
+
+下面是本流程参考的开源工具及其适用边界。它们解决的问题不同，**不需要全部安装**。
+
+| 项目 | 适合解决的问题 | 本流程借鉴的做法 | 选择时考虑 |
+| --- | --- | --- | --- |
+| [DVC](https://doc.dvc.org/user-guide/pipelines/defining-pipelines) | 数据与模型产物版本、可复现的多阶段流水线 | 记录数据版本、参数、代码和阶段依赖 | 多人协作、大文件及复杂流水线时有价值；小项目可以先用现有脚本和清单。 |
+| [MLflow Tracking](https://mlflow.org/docs/latest/ml/tracking/) | 记录实验参数、指标、代码版本和产物 | 用统一记录关联运行、配置、数据、指标和产物 | 适合实验数量较多时检索比较；单次实验也可先使用项目内记录。 |
+| [Optuna](https://optuna.readthedocs.io/en/stable/tutorial/20_recipes/002_multi_objective.html) | 超参数搜索、多目标优化 | 先定义搜索空间、预算和评价方式，再比较试验 | 搜索本身消耗计算资源；种子不能保证所有场景可复现，参见其[复现说明](https://optuna.readthedocs.io/en/stable/faq.html)。 |
+| [scikit-learn](https://scikit-learn.org/stable/common_pitfalls.html) | 传统机器学习的基线、预处理和评估 | 按任务选择切分单位，在训练集拟合预处理，防止数据泄漏 | 即使使用其他框架，也应检查数据、特征工程与评估之间是否泄漏。 |
+| [PyTorch](https://docs.pytorch.org/docs/stable/notes/randomness.html) | 深度学习训练与计算 | 记录随机性、软件和硬件环境，区分固定种子与可复现性 | 不同平台、版本和算子可能产生差异；确定性设置可能影响性能或不可用。 |
+| [lm-evaluation-harness](https://github.com/EleutherAI/lm-evaluation-harness) | 大模型任务评测与标准化比较 | 记录任务、模型、提示、生成设置和评测版本 | 公共 benchmark 不自动代表实际业务表现，还需检查数据污染、成本和任务适配性。 |
+
+这些项目是可选工具和方法参考，当前 Skill 不会自动部署它们，也不会要求使用某家云服务或实验平台。
+
+## 使用
+
+在安装本扩展的 Pi 会话中显式调用：
+
+```text
+/skill:ml-development 为当前分类项目建立可复现的基线：检查数据切分，确定主指标，运行预算内的冒烟测试，并记录下一轮实验计划。
+```
+
+此 Skill 采用显式调用模式（`disable-model-invocation: true`），不会因为普通的 ML 自然语言请求自动触发。可以在 `/skill:ml-development` 后用自然语言描述任务。与 `/poteto-mode` 配合时需明确要求两者；Poteto 的上游路由不会自动选择本套流程。Skill 的调用依赖模型实际遵循指令，不保证自动启动子代理或训练任务。
+
+建议在请求中提供数据位置与使用权限、任务目标、已有基线、评估指标、时间和计算预算；如果存在独立测试集，还应说明其使用规则。涉及长时间训练、付费服务或共享计算资源时，先明确预算及使用范围。Pi 子代理的 token、费用、运行时长预算不会自动约束外部训练进程、GPU 用量或云服务计费；没有能管理完整进程树并强制执行预算的授权执行环境时，应只准备命令与计划，不启动此类训练。未提供必要数据或设备时，流程会尽量完成独立的准备工作，并说明哪些步骤无法执行。
+
+## 六个阶段
+
+1. **定义问题**：明确预测对象、约束、指标方向、现有基线和预算。
+2. **准备数据**：记录数据版本及切分方法，检查重复、时间和实体泄漏；只在训练集拟合预处理。
+3. **建立基线**：复用现有实现或建立简单基线；先运行必要的低成本代码检查和冒烟测试。
+4. **规划实验**：列出假设、对照、参数范围和资源上限；记录失败和中止的试验。
+5. **评估比较**：在一致协议下报告指标、样本量及可行的误差或不确定性；保留最终测试集用于冻结方案后的评估。
+6. **复现与交付**：记录代码、数据标识、依赖、硬件、配置、命令、随机性和产物位置，同时说明无法复现的部分。
+
+可以按任务只执行相关阶段；例如已有模型的评估从第五阶段开始，但仍要检查数据切分和比较协议。随包提供的 [运行记录](../skills/ml-development/references/run-record.md) 和 [实验矩阵](../skills/ml-development/references/experiment-matrix.md) 是模板，不会自动覆盖项目文件。
+
+## 示例与结果解读
+
+- **监督学习**：用户提供已有数据集，要求按用户或时间分组切分，以指定指标比较简单基线与候选模型。实验应记录数据版本、训练集拟合的变换、样本数和验证结果；最终测试集不参与调参。
+- **大模型或代理评测**：固定模型版本、提示词、采样参数、工具权限和用例集，分别记录任务本身是否成功、报告格式是否符合合同、评测是否运行以及验收结果。不能仅凭一个 `verified` 数字判断模型能力。
+- **缺少 GPU 或数据权限**：可以检查仓库、设计实验和编写适当的离线测试；训练或真实模型评测应标记为未运行，不得把模拟结果当成真实性能。
+
+Skill 及其六个阶段可以通过扩展的 `pstack_skill` 工具供子代理读取。复用已有的 `scout`、`architect`、`worker`、`reviewer`、`verifier` 角色，无须为六个阶段各建一个 Agent。`reviewer` 和 `verifier` 仅能只读检查证据，不能执行训练命令；并行任务仍由现有工作流权限、验证策略和实际模型调用决定。Git worktree 不是操作系统安全沙箱，不应在公开记录中包含凭证或敏感数据。

package/docs/PI-SEMANTIC-ADAPTER.md

@@ -0,0 +1,34 @@
+# Pi adapter for the pinned pstack source
+
+The behavior source is the `vendor/upstream/0.15.36/pstack/` snapshot at `c742dd61706fbacc1b95f1a20b7b988cf096ce6c`. Generated supported Skill/playbook entrypoints retain the upstream Markdown after this Pi prelude. The eleven core workflows have critical-rule mappings; preserving a source body does not prove that a model followed it. The full source inventory is pinned separately; maintainer semantic sign-off remains pending.
+
+Apply user instructions and repository authority first. Read referenced source Markdown through `pstack_skill` with `upstream/skills/<skill>/...` resource IDs, consuming every page. Statechart's 0.15.36 TypeScript runtime and its test corpus are bundled under `skills/statechart/scripts`; the older 0.15.32 `.mjs` tools are retained for compatibility. Java/TLC and optional renderers are external dependencies. Other Cursor plugins, private APIs, drivers and cloud resources are not supplied.
+
+For Statechart execution, run `node <skill-dir>/../../dist/statechart/statechart.js SPEC.tla [--config FILE] [--view FILE] [--out DIR]`. This compiled copy is required in installed packages because Node does not strip TypeScript inside `node_modules`. The upstream source and test corpus remain unchanged.
+
+## Platform substitutions
+
+- Task workers use `pstack_agents` and `pstack_workflow` Pi AgentSessions. The parent owns the playbook. Parallel writers use Git worktrees; integrated delivery uses an explicit integrator and verification. These are local processes, not cloud VMs or OS sandboxes.
+- `/setup-pstack` previews model roles and suggested panels using models visible in the current Pi session; edit only what needs changing. Existing choices are preserved. Panels with the same model in several seats do not provide model diversity. Model roles use `models.json`; pass the playbook and, for named roles such as Reflect's `tooling`, `judgment`, `divergent`, and `synthesizer`, `modelRole` when dispatching. Explicit node models take precedence.
+- Pi `thinkingLevel` replaces Cursor's reasoning slug conventions. Optional same-family fallback chooses a registered model from the same provider and reports it; a supported lower reasoning level may be used and reported. Unknown families are not guessed, Cursor `-fast` aliases are not rewritten, and authentication/inference failures are not automatically retried.
+- For an unconfigured panel, plans suggest available Pi models and disclose repeated seats. Unresolvable configured seats are dropped or replaced with an available survivor or the parent, with notes. A known-family parent gets a judge only from another recognized family; if none is available, the plan produces candidates only and the coordinator must inspect, choose, integrate and verify them. A failed or unaccepted candidate is excluded only after the other candidates settle; verified survivors remain eligible and the dropout is recorded.
+- Arena's cross-judge uses confined `pstack_candidates` access to verified worktrees. The integrator independently reads and compares candidates before selecting and grafting. Architect's template includes a separate implementation phase after the selected sketch; the coordinator still owns upstream grounding (`how`/`why`) and optional checkpoints.
+- Interrogate creates a worktree for each adversary, copies the reviewed staged, unstaged and untracked changes, and runs a separate repro-verifier on each worktree. No adversary changes are integrated. Both sessions must report command, observed and expected output; synthesis can only carry reproductions present in a verifier report. These sessions use Pi's ordinary writable-agent shell permissions; the verification-policy allowlist controls native gate commands, not their interactive shell. Model reports are not independently attested receipts: the coordinator must inspect actual command evidence and the effect of any repro edits before claiming a finding is verified.
+- Swarm supports partition, best-of, first-pass and rank-all race templates. First-pass waits for a candidate's deterministic acceptance, requests cooperative cancellation of the remaining sessions, and waits for them to settle. Rank-all reports every rank without automatically integrating a winner. Mixed partition/race still needs an explicit DAG.
+- Custom Mode maps to sticky `/poteto-mode`. `/loop` maps to `/pstack-loop`, which requires an active Pi host and cannot promise cloud-root scheduling or exact delivery across a crash.
+- Use an available named CLI/UI driver for real-surface proof. Without one, return blocked or inconclusive with the exact reason; unit tests, fake providers and worker reports cannot replace a live lane.
+
+## Explicit policy deviations
+
+- Native exact-head/base ledgers invalidate verification when either changes, including patch-preserving restacks; upstream can reuse some patch-ID-stable verdicts.
+- Read-only reviewer, scout and verifier sessions inspect confined source and evidence but cannot run shell commands or live MCP. Deterministic commands run in an authorized runner or writable lane. For external investigation, the parent supplies evidence snapshots and verifies decisive citations.
+- Autopilot templates prepare local DAG artifacts. The coordinator remains responsible for the owner lifecycle, early PRs, periodic audit, rebase discipline, countersigns and stop propagation. A stack template alone does not deliver a remote PR stack. Babysit stops at merge-ready; shipping and remote writes require the actual applicable authorization.
+- Opening a PR does not start a babysit. Finish the phase or stack before a requested babysit unless an explicitly assigned full-autonomy owner owns the loop and has reported code-ready. Babysit stops before merge; operator-reserved items never merge automatically.
+
+## Unsupported operations
+
+`Cursor-private-PR-provenance`, `Cursor-watch-READY`, `Cursor-cleanup-plugin` and `Bugbot-pass-dismissal` are unsupported. GitHub/Origin and native states are alternatives with their own evidence boundaries, not proof that a Cursor operation ran. `make-bot-ui` and the Cursor automation event pack require Cursor-specific surfaces. Report these limitations rather than marking unavailable operations complete.
+
+## Evidence boundary
+
+`SEMANTICS.json` records selected critical-rule mappings, exact source lines, deviations, bound tests and file fingerprints. Inventory counts, source hashes, deterministic checks, Pi SDK/fake-provider tests, real-model runs and maintainer semantic review are separate evidence levels. Advancing the source pin and passing CI do not establish complete Cursor/Pi equivalence or maintainer approval.

package/docs/PR-41-ALIGNMENT-PLAN.zh-CN.md

@@ -0,0 +1,30 @@
+# PR #41：向原版 pstack 靠拢的实施方案
+
+## 目标和基准
+
+以 `cursor/plugins` 的 pstack 0.15.36（`c742dd61706fbacc1b95f1a20b7b988cf096ce6c`）为对照，改善 Pi 上的配置、委派、候选比较、审查和交付体验。保留 Pi 的 provider/model 与权限边界，不能把 Cursor 模型名、云服务或私有接口当作 Pi 已有能力。
+
+## 实施顺序
+
+1. 同步上游源码、辅助资源、状态图工具链和清单；核对 0.15.32 以来的行为变化，更新适配映射、漂移检查和契约。尚未验证或无法映射的行为明确记录，不能因复制 Markdown 而声称已实现。
+2. 重做 `/setup-pstack` 的默认配置和编辑路径：利用 Pi 实际可用的模型建立可审阅的初始映射与多席面板；允许保留现有配置、只改所需项和分配 Reflect 角色。配置与执行使用同一套路由；回退、重复模型和未配置的能力向用户说明。
+3. 将 Arena / Architect 对齐上游的候选、交叉裁判、选取、整合和失败处理语义：选择不同于已知父模型家族的裁判；可用候选不足或裁判不可用时给出明确的退路和记录；仍检查候选所有权与新鲜度。Architect 还需保留理解问题和后续实现阶段。
+4. 将 Interrogate 调整为隔离的对抗工作区：评审者运行复现并提交命令与输出，由独立执行路径复核后只保留已证实的发现；不得自动应用评审者的修改。
+5. 补足可在 Pi 中实现的 Swarm 选择策略、Autopilot/Orchestrate 协调和任务路由；外部操作、权限、云隔离、MCP 和调度能力与 Pi 实际环境一致，不虚构等价实现。
+6. 为每个行为和失败路径补充针对性测试，运行类型检查、仓库检查、Pi SDK/模拟服务端到端及安装验证；有条件时运行真实模型，记录其模型、提交和结果。更新 PR 描述和剩余差异。
+
+## 验收边界
+
+- 模型面板、单模型回退、交叉裁判、候选缺席、审查复现和结果整合必须有可执行测试；源文件和名称覆盖不等于行为等价。
+- 未配置真实模型凭证或服务不可达时，不能把模拟服务测试写成真实模型验收。
+- 不复制 Cursor 私有 API、绕过现有执行边界或把本地进程称为云代理；暂不可用的能力保留可见说明。
+- 升级来源和通过测试不代表维护者已完成语义签署。
+
+## 本次落地与剩余边界
+
+- 已固定并核对 0.15.36 上游树；新增 Statechart 编译产物，确保安装到 `node_modules` 后仍可由 Node 启动。
+- 已合入主分支新增的逐条注册表协议，并将当前记录及校验切换到 0.15.36；0.15.32 记录作为历史保留。
+- 已增加可审阅的默认配置、局部编辑和 Reflect 角色路由；Arena 支持异家族裁判、无裁判交由协调者选择、候选掉队后保留已验证结果。
+- 已增加隔离的 Interrogate 对抗与复跑会话、Architect 的后续实现节点，以及 Swarm 的 `first-pass` 和 `rank-all`。Interrogate 的模型报告仍须由协调者核对实际执行证据。
+- Swarm 混合分片/竞赛仍需显式 DAG；Autopilot 的远程 PR 生命周期仍由协调者完成。Cursor 云代理、私有 watcher、自动化事件、实时 MCP 转发和独立云调度没有被冒充为 Pi 原生能力。
+- 真实 Java/TLC 已用于新 Statechart 的 Counter 示例和安装包验证。完整新版 Statechart 套件在本环境受进程检查和资源条件影响，未记作通过；真实外部模型推理和真实远程交付仍待独立验证。

package/docs/PR-PROTOCOL.md

@@ -0,0 +1,48 @@
+# PR protocol checks
+
+Strict task reports may include `unresolved` and `deviations` entries as `{ "severity": "advisory", "description": "..." }` for non-blocking information or `blocking` for unresolved acceptance issues. Legacy string entries remain blocking. Advisory notes are retained in the report, but cannot substitute for passing gates or current artifact evidence. `base` and `head` must be full commit IDs.
+
+## Sample stack
+
+The root branch `feature/validation-api` adds a small validation API. Its ready PR targets `main`. The child branch `feature/validation-cli` starts at the root branch's exact tip. Its ready PR targets `feature/validation-api`, not `main`. Independent work branches from `main` instead.
+
+Publish both only after explicit authorization. Do not start a babysit after the root PR opens. Finish the stack and return both URLs. Queue a separate babysit pass when requested. An explicitly assigned full-autonomy owner with an assigned loop is the exception. Merge permission remains separate.
+
+[The sample child body](stacked-pr-body.md) shows the required headings. Validate it without remote writes.
+
+```bash
+node docs/validate-pr.mjs docs/stacked-pr-body.md
+node --test docs/parity.test.mjs
+```
+
+The first command prints `PR protocol ok`. The tests reject draft PRs, children with the wrong base, early babysit starts, missing Scope or Verification, empty sections, and headings hidden in fenced code. Tradeoffs is optional. The validator accepts heading case differences, including `Blast radius`.
+
+## State snapshots
+
+To check readiness and handoff as well as the body, pass a local JSON file as the second argument. This example describes the child before the stack is complete.
+
+```json
+{
+  "isDraft": false,
+  "base": "feature/validation-api",
+  "parentBranch": "feature/validation-api",
+  "trunk": "main",
+  "babysit": false,
+  "phaseComplete": false,
+  "ownerFullAutonomy": false
+}
+```
+
+A root uses `parentBranch: null` and targets `trunk`. Set `babysit` to true only after phase or stack completion, or for an explicitly assigned full-autonomy owner. This snapshot is fixture data. The validator does not contact a forge, authorize writes, verify a parent's exact commit, or prove an agent follows the playbook.
+
+## Forge and provenance
+
+Select `gh` once, or Origin when available and able to resolve the repository. Keep that forge for operations throughout the run. The GitHub API is the remote service. `gh pr` is a CLI client, and `gh api` calls the service directly.
+
+Cursor's built-in PR tools track run-specific provenance. The API and CLI do not provide that metadata. When a harness supplies an owning PR tool, use it for create, edit, retarget, and mark-ready operations. Set `draft: false`. Use the selected forge only for operations that tool does not cover.
+
+Pi does not implement Cursor's private PR-tool metadata or upstream watcher's merge-queue verdicts. These remain unsupported platform behavior. The local playbooks use read-only forge state and stop at merge-ready. Opening a PR and merging it both need explicit authorization.
+
+## Proof boundary
+
+The tests load ketchup with the official Pi skill loader and check its sections and cutoff wording. Chat behavior itself was not exercised. That harness belongs to issue #6. The PR tests check local bodies and fixture state only. They do not prove live review, stack handoff, or merge behavior.