pi-pstack-native 0.0.0-stage → 1.0.0

package/scripts/upstream/playbooks.mjs

@@ -0,0 +1,143 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { readJSON } from './core.mjs';
+import { PROFILES } from '../../src/agent/profiles.ts';
+
+const contractPath = 'docs/playbook-contracts.json';
+const playbookDir = 'skills/poteto-mode/playbooks';
+const evidenceStates = ['not_run', 'blocked', 'passed', 'failed', 'stale'];
+
+/* The minimum observable behavior and refusal for each playbook, copied from
+   section 7.3 of docs/PRD-PSTACK-NATIVE-NEXT.md. The table is the contract
+   source; the playbook file supplies roles and tools. */
+const minimum = {
+  'authoring-a-skill': ['按实际运行环境生成并验证 Skill', '文件存在但无法加载或调用'],
+  'autonomous-run': ['在授权范围内持续推进，保留停止条件', '把自治授权扩大为未授权外部动作'],
+  'autopilot-full': ['每个 PR 有 Owner，代码变更后重新验证', '旧 Head 的审查被新代码复用'],
+  'autopilot-stack': ['正确建立线性依赖和父分支，交付有序栈', '把所有子 PR 直接指向 trunk'],
+  babysit: ['根据请求选择模式，读取 CI 和审查状态', '创建 PR 后未经触发就自动开始轮询'],
+  'bug-fix': ['复现、缩小根因、实现、原始场景验证', '错误场景或无法判断的结果被记为修复成功'],
+  eval: ['固定样本和评价规则，保留盲评与失败', '修改规则后继续使用旧分数比较'],
+  feature: ['从数据结构和需求建立可运行行为', '仅凭实现者总结认定需求满足'],
+  hillclimb: ['逐次记录假设、基线、测量和接受决定', '无可比测量就保留所谓优化'],
+  investigation: ['从实际证据回答，保留来源状态', '未经任务授权修改仓库或远端'],
+  'multi-phase-plan': ['每阶段有目标、依赖、产物和验收', '前一阶段未验收就把后续阶段标为完成'],
+  'opening-a-pr': ['按目标基线确定 PR 状态、父分支和正文', '在权限或验证不足时声称已创建 PR'],
+  orchestrate: ['维护长期任务、指令版本和阶段交付', '旧指令下的孤立 Workflow 自动恢复'],
+  'pause-safely': ['记录在途动作、产物和恢复条件', '把暂停视为外部副作用已撤销'],
+  'perf-issue': ['用相同场景建立基线并解释限制因素', '改变工作量后宣称性能提升'],
+  prototype: ['用最小实验回答具体设计分歧', '把试验代码默认为生产实现'],
+  refactoring: ['保留明确的外部行为并运行验证', '结构改动中混入未经授权的需求变更'],
+  'runtime-forensics': ['读取运行中证据并确认触发机制', '仅凭静态推测关闭运行时问题'],
+  'session-pickup': ['从当前代码、状态和历史证据恢复任务', '仅依赖旧摘要继续写入'],
+  shipping: ['独立验证，按底部连续已验证区间交付并读回', 'CI 绿、排队或启用 auto-merge 被当作已合并'],
+  'trace-forensics': ['分析指定采样材料，标明采集条件和局限', '在材料不支持时推断根因已确认'],
+  'visual-parity': ['在固定视口和状态下对比真实图像', '用组件存在或文字总结证明视觉一致'],
+  'worktree-cleanup': ['检查归属、改动和合并状态，再执行已授权清理', '强制删除未知或含未保留修改的工作区'],
+};
+
+const roleNames = Object.keys(PROFILES).sort((a, b) => b.length - a.length);
+const rolePattern = new RegExp(`\\b(?:${roleNames.map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})\\b`, 'g');
+
+function playbookFiles(root) {
+  const dir = join(root, playbookDir);
+  if (!existsSync(dir)) throw new Error(`PLAYBOOK_DIR_MISSING: ${playbookDir}`);
+  return readdirSync(dir).filter((name) => name.endsWith('.md')).sort().map((name) => name.slice(0, -3));
+}
+
+function stepsSection(text) {
+  const start = text.search(/^##\s+Steps\s*$/m);
+  if (start < 0) return '';
+  const rest = text.slice(start);
+  const next = rest.slice(1).search(/^##\s/m);
+  return next < 0 ? rest : rest.slice(0, next + 1);
+}
+
+function rolesIn(text) {
+  return [...new Set(text.match(rolePattern) ?? [])].sort();
+}
+
+function orderedSteps(text) {
+  const steps = [];
+  for (const match of text.matchAll(/^(\d+)\.\s+(.+)$/gm)) {
+    const step = match[2].replace(/`([^`]*)`/g, '$1').trim();
+    steps.push({ order: steps.length + 1, sourceOrder: Number(match[1]), text: step });
+  }
+  if(!steps.length)for(const match of text.matchAll(/^\*\*([^*]+)\*\*\s+(.+)$/gm))steps.push({order:steps.length+1,text:`${match[1]} ${match[2]}`.trim()});
+  return steps;
+}
+
+export function buildContracts({ root }) {
+  const names = playbookFiles(root);
+  const unknown = names.filter((name) => !Object.hasOwn(minimum, name));
+  if (unknown.length) throw new Error(`PLAYBOOK_CONTRACT_MISSING: ${unknown.join(', ')}`);
+  const extra = Object.keys(minimum).filter((name) => !names.includes(name));
+  if (extra.length) throw new Error(`PLAYBOOK_CONTRACT_ORPHAN: ${extra.join(', ')}`);
+  const parent = readFileSync(join(root, 'skills/poteto-mode/SKILL.md'), 'utf8');
+  const manualOnly = /^disable-model-invocation:\s*true$/m.test(parent);
+  const contracts = names.map((name) => {
+    const text = readFileSync(join(root, playbookDir, `${name}.md`), 'utf8');
+    const steps = stepsSection(text);
+    const roles = rolesIn(steps);
+    const tools = [...new Set(roles.flatMap((role) => PROFILES[role]?.tools ?? []))].sort();
+    const [observe, mustReject] = minimum[name];
+    return {
+      name,
+      source: `${playbookDir}/${name}.md`,
+      trigger: `the operator asks for a task that matches ${name}, or names it explicitly`,
+      manualOnly,
+      roles,
+      parentOnly: roles.length === 0,
+      tools,
+      requiredSteps: orderedSteps(steps),
+      observe: [observe],
+      mustReject: [mustReject],
+      evidence: { status: 'not_run', refs: [] },
+    };
+  });
+  return {
+    schemaVersion: 1,
+    source: { plan: 'docs/PRD-PSTACK-NATIVE-NEXT.md section 7.3', profiles: 'src/agent/profiles.ts' },
+    contracts,
+  };
+}
+
+export function validateContracts(document, { root }) {
+  const fail = (message) => { throw new Error(`CONTRACT_${message}`); };
+  if (document?.schemaVersion !== 1) fail('SCHEMA_VERSION');
+  const fresh = buildContracts({ root });
+  if (!Array.isArray(document.contracts) || document.contracts.length !== fresh.contracts.length) fail('COUNT_MISMATCH');
+  const names = new Set();
+  for (const [index, contract] of document.contracts.entries()) {
+    const expected = fresh.contracts[index];
+    if (!contract || typeof contract !== 'object') fail('ENTRY_SHAPE');
+    if (contract.source !== expected.source) fail(`SOURCE_MISMATCH: ${contract.source}`);
+    if (names.has(contract.name)) fail(`DUPLICATE: ${contract.name}`);
+    names.add(contract.name);
+    if (!Array.isArray(contract.observe) || contract.observe.length === 0) fail(`OBSERVE_EMPTY: ${contract.name}`);
+    if (!Array.isArray(contract.mustReject) || contract.mustReject.length === 0) fail(`REJECT_EMPTY: ${contract.name}`);
+    if (!Array.isArray(contract.requiredSteps) || contract.requiredSteps.length !== expected.requiredSteps.length) fail(`STEPS_MISMATCH: ${contract.name}`);
+    if (expected.requiredSteps.length === 0) fail(`STEPS_EMPTY: ${contract.name}`);
+    for (const [stepIndex, step] of contract.requiredSteps.entries()) {
+      if (step.order !== stepIndex + 1) fail(`STEP_ORDER: ${contract.name} ${step.order}`);
+      if (typeof step.text !== 'string' || step.text.trim().length === 0) fail(`STEP_EMPTY: ${contract.name}`);
+    }
+    if (JSON.stringify(contract.roles) !== JSON.stringify(expected.roles)) fail(`ROLES_MISMATCH: ${contract.name}`);
+    if (contract.parentOnly !== (contract.roles.length === 0)) fail(`PARENT_ONLY_MISMATCH: ${contract.name}`);
+    for (const role of contract.roles) if (!Object.hasOwn(PROFILES, role)) fail(`UNKNOWN_ROLE: ${role}`);
+    if (JSON.stringify(contract.tools) !== JSON.stringify(expected.tools)) fail(`TOOLS_MISMATCH: ${contract.name}`);
+    if (contract.manualOnly !== expected.manualOnly) fail(`MANUAL_ONLY_MISMATCH: ${contract.name}`);
+    if (!evidenceStates.includes(contract.evidence?.status)) fail(`EVIDENCE_STATE: ${contract.name}`);
+    if (!Array.isArray(contract.evidence.refs)) fail(`EVIDENCE_REFS: ${contract.name}`);
+    if (contract.evidence.status === 'passed' && contract.evidence.refs.length === 0) fail(`EVIDENCE_UNSUPPORTED: ${contract.name}`);
+    if (contract.evidence.status === 'not_run' && contract.evidence.refs.length > 0) fail(`EVIDENCE_STALE_REF: ${contract.name}`);
+  }
+  for (const name of fresh.contracts.map((contract) => contract.name)) if (!names.has(name)) fail(`MISSING: ${name}`);
+  return document;
+}
+
+export function readContracts(root) {
+  return validateContracts(readJSON(join(root, contractPath)), { root });
+}
+
+export { contractPath };

package/scripts/upstream/records.mjs

@@ -0,0 +1,113 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { readJSON, safePath, shaPattern } from './core.mjs';
+import { buildInventory, readSnapshot } from './inventory.mjs';
+
+export const recordsPath = 'docs/registry-records-0.15.36.json';
+const kindOrder = ['skill', 'playbook'];
+const registryOf = { skill: 'skills', playbook: 'playbooks' };
+const handlingOf = { ADAPTED: 'adapted', CURSOR_ONLY: 'cursor-only' };
+const statusOf = { adapted: 'ADAPTED', 'cursor-only': 'CURSOR_ONLY' };
+const evidenceStates = ['not_run', 'blocked', 'passed', 'failed', 'stale'];
+const fields = {
+  document: ['schemaVersion', 'target', 'records'],
+  target: ['commit', 'version', 'snapshotDigest'],
+  record: ['name', 'kind', 'source', 'port', 'requirements', 'contracts', 'evidence'],
+  source: ['path', 'blob'],
+  port: ['path', 'handling', 'ruleVersion', 'differences'],
+  differences: ['status'],
+  requirements: ['status'],
+  contracts: ['ids'],
+  evidence: ['status', 'refs'],
+};
+const nonempty = value => typeof value === 'string' && value.trim().length > 0;
+const reject = message => { throw new Error(`RECORDS_${message}`); };
+const recordPath = (kind, name) => kind === 'skill' ? `skills/${name}/SKILL.md` : `skills/poteto-mode/playbooks/${name}.md`;
+
+function shape(value, keys, scope) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) reject(`SHAPE: ${scope}`);
+  const unknown = Object.keys(value).filter(key => !keys.includes(key));
+  if (unknown.length) reject(`UNKNOWN_FIELD: ${scope} has ${unknown.join(', ')}`);
+}
+function reference({ root }) {
+  const snapshot = readSnapshot(root), parity = readJSON(join(root, 'PARITY.json'));
+  const ports = new Map(buildInventory({ snapshot, parity, localRoot: root }).entries.map(entry => [entry.source.path, entry.port]));
+  return { snapshot, parity, ports };
+}
+function names({ parity }) {
+  return kindOrder.flatMap(kind => Object.keys(parity[registryOf[kind]] ?? {}).sort((a, b) => a.localeCompare(b, 'en')).map(name => ({ kind, name })));
+}
+function kindInParity(parity, name) {
+  if (Object.hasOwn(parity.skills ?? {}, name)) return 'skill';
+  if (Object.hasOwn(parity.playbooks ?? {}, name)) return 'playbook';
+  return undefined;
+}
+function localExists(root, path) {
+  try { return existsSync(join(root, safePath(path))); } catch { return false; }
+}
+
+export function buildRecords({ root }) {
+  const { snapshot, parity, ports } = reference({ root });
+  const blobs = new Map(snapshot.blobs.map(blob => [blob.path, blob.blob]));
+  const records = names({ parity }).map(({ kind, name }) => {
+    const status = parity[registryOf[kind]][name], path = recordPath(kind, name), blob = blobs.get(path), handling = handlingOf[status];
+    if (blob === undefined) reject(`SOURCE_BLOB_MISSING: ${kind} ${name} has no snapshot blob at ${path}`);
+    if (handling === undefined) reject(`STATUS_UNSUPPORTED: ${kind} ${name} is ${status} in PARITY.json`);
+    const port = {...(status === 'ADAPTED' ? { path: ports.get(path)?.path } : {}), handling, ruleVersion: 1, differences: { status: 'not_recorded' }};
+    if (status === 'ADAPTED' && !nonempty(port.path)) reject(`PORT_PATH_MISSING: ${kind} ${name} has no inventory local path`);
+    return { name, kind, source: { path, blob }, port, requirements: { status: 'not_recorded' }, contracts: { ids: kind === 'playbook' ? [name] : [] }, evidence: { status: 'not_run', refs: [] } };
+  });
+  return { schemaVersion: 1, target: { commit: snapshot.commit, version: snapshot.version, snapshotDigest: snapshot.blobDigest }, records };
+}
+
+export function validateRecords(document, { root }) {
+  const { snapshot, parity, ports } = reference({ root });
+  shape(document, fields.document, 'document');
+  if (document.schemaVersion !== 1) reject('SCHEMA_VERSION');
+  shape(document.target, fields.target, 'target');
+  if (!isDeepStrictEqual(document.target, { commit: snapshot.commit, version: snapshot.version, snapshotDigest: snapshot.blobDigest })) reject('TARGET_MISMATCH');
+  if (!Array.isArray(document.records)) reject('SHAPE: records must be an array');
+  const blobs = new Map(snapshot.blobs.map(blob => [blob.path, blob.blob]));
+  const seen = new Set();
+  for (const record of document.records) {
+    shape(record, fields.record, 'record');
+    if (!nonempty(record.name) || record.name.includes('/')) reject('NAME: a record needs a plain name');
+    if (seen.has(record.name)) reject(`NAME_DUPLICATE: ${record.name}`);
+    seen.add(record.name);
+    const kind = kindInParity(parity, record.name);
+    if (kind === undefined) reject(`NOT_IN_PARITY: ${record.name}`);
+    if (record.kind !== kind) reject(`KIND: ${record.name} is a ${kind} in PARITY.json`);
+    const status = parity[registryOf[kind]][record.name], path = recordPath(kind, record.name);
+    shape(record.source, fields.source, `${record.name} source`);
+    if (record.source.path !== path) reject(`SOURCE_PATH: ${record.name} must cite ${path}`);
+    if (typeof record.source.blob !== 'string' || !shaPattern.test(record.source.blob) || blobs.get(path) !== record.source.blob) reject(`SOURCE_BLOB: ${record.name} must cite the snapshot blob at ${path}`);
+    shape(record.port, fields.port, `${record.name} port`);
+    if (!Object.hasOwn(statusOf, record.port.handling)) reject(`PORT_HANDLING: ${record.name} is ${record.port.handling}`);
+    if (statusOf[record.port.handling] !== status) reject(`PORT_STATUS_MISMATCH: ${record.name} is ${status} in PARITY.json`);
+    if (record.port.ruleVersion !== 1) reject(`PORT_RULE_VERSION: ${record.name}`);
+    shape(record.port.differences, fields.differences, `${record.name} differences`);
+    if (!nonempty(record.port.differences.status)) reject(`DIFFERENCES: ${record.name} needs a status`);
+    if (record.port.handling === 'adapted') {
+      if (!nonempty(record.port.path)) reject(`PORT_PATH_MISSING: ${record.name} is adapted without a local path`);
+      if (!localExists(root, record.port.path)) reject(`PORT_PATH_ABSENT: ${record.name} has no file at ${record.port.path}`);
+      if (record.port.path !== ports.get(path)?.path) reject(`PORT_PATH_MISMATCH: ${record.name} port path is not the inventory local path`);
+    } else if (record.port.path !== undefined) reject(`PORT_PATH_UNEXPECTED: ${record.name} is cursor-only and carries no local path`);
+    shape(record.requirements, fields.requirements, `${record.name} requirements`);
+    if (record.requirements.status !== 'not_recorded') reject(`REQUIREMENTS_STATUS: ${record.name} is ${record.requirements.status}`);
+    shape(record.contracts, fields.contracts, `${record.name} contracts`);
+    const ids = record.contracts.ids;
+    if (!Array.isArray(ids) || !ids.every(nonempty)) reject(`CONTRACTS_IDS: ${record.name} needs contract IDs as non-empty strings`);
+    if (kind === 'skill' && ids.length > 0) reject(`CONTRACTS_SKILL_ID: ${record.name} is a skill and claims ${ids.join(', ')}`);
+    if (kind === 'playbook' && !isDeepStrictEqual(ids, [record.name])) reject(`CONTRACTS_PLAYBOOK_ID: ${record.name} must cite only its own contract`);
+    shape(record.evidence, fields.evidence, `${record.name} evidence`);
+    if (!evidenceStates.includes(record.evidence.status)) reject(`EVIDENCE_STATUS: ${record.name} is ${record.evidence.status}`);
+    if (!Array.isArray(record.evidence.refs) || !record.evidence.refs.every(nonempty)) reject(`EVIDENCE_REFS: ${record.name} needs references as non-empty strings`);
+    if (record.evidence.status === 'passed' && (record.requirements.status === 'not_recorded' || ids.length === 0 || record.evidence.refs.length === 0 || record.port.differences.status === 'not_recorded')) reject(`EVIDENCE_UNSUPPORTED: ${record.name} claims a pass its fields do not support`);
+    if (record.evidence.status === 'not_run' && record.evidence.refs.length > 0) reject(`EVIDENCE_STALE_REF: ${record.name} is not_run and carries references`);
+  }
+  const expected = names({ parity });
+  for (const { kind, name } of expected) if (!seen.has(name)) reject(`MISSING_RECORD: ${kind} ${name} is in PARITY.json without a record`);
+  if (!isDeepStrictEqual(document.records.map(record => `${record.kind}:${record.name}`), expected.map(entry => `${entry.kind}:${entry.name}`))) reject('ORDER: records must be sorted by kind then name');
+  return document;
+}

package/scripts/upstream/records.test.mjs

@@ -0,0 +1,116 @@
+import assert from 'node:assert/strict';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { test } from 'node:test';
+import { checkRecords } from '../check-records.mjs';
+import { readJSON } from './core.mjs';
+import { buildRecords, recordsPath, validateRecords } from './records.mjs';
+
+const root = resolve('.');
+const serialize = document => `${JSON.stringify(document, null, 2)}\n`;
+const committed = () => readJSON(join(root, recordsPath));
+const find = (document, kind, name) => document.records.find(record => record.kind === kind && record.name === name);
+
+test('the pinned snapshot yields one record per registry name', () => {
+  const document = checkRecords(root);
+  const parity = readJSON(join(root, 'PARITY.json'));
+  assert.equal(document.records.length, 81);
+  assert.equal(document.records.filter(record => record.kind === 'skill').length, 58);
+  assert.equal(document.records.filter(record => record.kind === 'playbook').length, 23);
+  assert.deepEqual(document.records.map(record => record.name).sort(), [...Object.keys(parity.skills), ...Object.keys(parity.playbooks)].sort());
+  assert.deepEqual(document.target, { commit: 'c742dd61706fbacc1b95f1a20b7b988cf096ce6c', version: '0.15.36', snapshotDigest: '44d926c3b018434eb9ae6ab24354bda5fd158a7eda1565401fe75de4acddce9f' });
+});
+
+test('the committed record file matches a fresh build byte for byte', () => {
+  assert.equal(readFileSync(join(root, recordsPath), 'utf8'), serialize(buildRecords({ root })));
+});
+
+test('every adapted record points at a local file that exists', () => {
+  const adapted = committed().records.filter(record => record.port.handling === 'adapted');
+  assert.equal(adapted.length, 80);
+  for (const record of adapted) assert.ok(existsSync(join(root, record.port.path)), `${record.name} has ${record.port.path}`);
+});
+
+test('every record claims no evidence and records no differences or requirements', () => {
+  for (const record of committed().records) {
+    assert.equal(record.evidence.status, 'not_run');
+    assert.deepEqual(record.evidence.refs, []);
+    assert.deepEqual(record.requirements, { status: 'not_recorded' });
+    assert.deepEqual(record.port.differences, { status: 'not_recorded' });
+    assert.equal(record.port.ruleVersion, 1);
+  }
+});
+
+test('a cursor-only record keeps its source and drops the local path', () => {
+  const record = find(committed(), 'skill', 'make-bot-ui');
+  assert.equal(record.port.handling, 'cursor-only');
+  assert.equal(record.port.path, undefined);
+  assert.equal(record.source.path, 'skills/make-bot-ui/SKILL.md');
+});
+
+test('a playbook cites its own contract and a skill cites none', () => {
+  assert.deepEqual(find(committed(), 'playbook', 'babysit').contracts.ids, ['babysit']);
+  assert.deepEqual(find(committed(), 'skill', 'architect').contracts.ids, []);
+});
+
+const rejections = [
+  ['wrong schema version', document => { document.schemaVersion = 2; }, /RECORDS_SCHEMA_VERSION/],
+  ['target mismatch', document => { document.target.version = '0.15.31'; }, /RECORDS_TARGET_MISMATCH/],
+  ['a record with no name', document => { delete document.records[0].name; }, /RECORDS_NAME:/],
+  ['a duplicate name', document => { document.records[1].name = document.records[0].name; }, /RECORDS_NAME_DUPLICATE/],
+  ['a wrong kind', document => { find(document, 'skill', 'architect').kind = 'playbook'; }, /RECORDS_KIND/],
+  ['a record absent from PARITY.json', document => { find(document, 'skill', 'architect').name = 'ghost'; }, /RECORDS_NOT_IN_PARITY/],
+  ['a parity name with no record', document => { document.records.pop(); }, /RECORDS_MISSING_RECORD/],
+  ['a source path that is not the expected one', document => { find(document, 'skill', 'architect').source.path = 'skills/arena/SKILL.md'; }, /RECORDS_SOURCE_PATH/],
+  ['a blob that is not 40 hex', document => { find(document, 'skill', 'architect').source.blob = 'abc'; }, /RECORDS_SOURCE_BLOB/],
+  ['a blob that is not the snapshot blob', document => { find(document, 'skill', 'architect').source.blob = '0'.repeat(40); }, /RECORDS_SOURCE_BLOB/],
+  ['an unknown handling', document => { find(document, 'skill', 'architect').port.handling = 'vendored'; }, /RECORDS_PORT_HANDLING/],
+  ['handling that disagrees with the registry', document => { find(document, 'skill', 'make-bot-ui').port.handling = 'adapted'; }, /RECORDS_PORT_STATUS_MISMATCH/],
+  ['an adapted record with no port path', document => { delete find(document, 'skill', 'architect').port.path; }, /RECORDS_PORT_PATH_MISSING/],
+  ['an adapted port path with no file', document => { find(document, 'skill', 'architect').port.path = 'skills/ghost/SKILL.md'; }, /RECORDS_PORT_PATH_ABSENT/],
+  ['an adapted port path that differs from the inventory', document => { find(document, 'skill', 'architect').port.path = 'skills/arena/SKILL.md'; }, /RECORDS_PORT_PATH_MISMATCH/],
+  ['a cursor-only record carrying a path', document => { find(document, 'skill', 'make-bot-ui').port.path = 'skills/make-bot-ui/SKILL.md'; }, /RECORDS_PORT_PATH_UNEXPECTED/],
+  ['requirements that are not not_recorded', document => { find(document, 'skill', 'architect').requirements.status = 'recorded'; }, /RECORDS_REQUIREMENTS_STATUS/],
+  ['contracts.ids that is not an array', document => { find(document, 'skill', 'architect').contracts.ids = 'architect'; }, /RECORDS_CONTRACTS_IDS/],
+  ['contracts.ids with a blank entry', document => { find(document, 'skill', 'architect').contracts.ids = ['  ']; }, /RECORDS_CONTRACTS_IDS/],
+  ['playbook ids that are not its own name', document => { find(document, 'playbook', 'babysit').contracts.ids = ['shipping']; }, /RECORDS_CONTRACTS_PLAYBOOK_ID/],
+  ['a playbook citing two ids', document => { find(document, 'playbook', 'babysit').contracts.ids = ['babysit', 'shipping']; }, /RECORDS_CONTRACTS_PLAYBOOK_ID/],
+  ['a skill claiming a contract id', document => { find(document, 'skill', 'architect').contracts.ids = ['architect']; }, /RECORDS_CONTRACTS_SKILL_ID/],
+  ['an unknown evidence state', document => { find(document, 'skill', 'architect').evidence.status = 'unknown'; }, /RECORDS_EVIDENCE_STATUS/],
+  ['evidence refs that are not strings', document => { find(document, 'skill', 'architect').evidence.refs = [7]; }, /RECORDS_EVIDENCE_REFS/],
+  ['a passed claim with no references', document => { find(document, 'playbook', 'babysit').evidence = { status: 'passed', refs: [] }; }, /RECORDS_EVIDENCE_UNSUPPORTED/],
+  ['a passed claim while requirements are not recorded', document => { find(document, 'playbook', 'babysit').evidence = { status: 'passed', refs: ['docs/log.txt'] }; }, /RECORDS_EVIDENCE_UNSUPPORTED/],
+  ['not-run evidence carrying references', document => { find(document, 'skill', 'architect').evidence.refs = ['docs/log.txt']; }, /RECORDS_EVIDENCE_STALE_REF/],
+  ['an unknown record field', document => { find(document, 'skill', 'architect').note = 'x'; }, /RECORDS_UNKNOWN_FIELD/],
+  ['an unknown source field', document => { find(document, 'skill', 'architect').source.mode = '100644'; }, /RECORDS_UNKNOWN_FIELD/],
+  ['an unknown document field', document => { document.generatedAt = 'now'; }, /RECORDS_UNKNOWN_FIELD/],
+  ['a rule version drift', document => { find(document, 'skill', 'architect').port.ruleVersion = 2; }, /RECORDS_PORT_RULE_VERSION/],
+  ['differences without a status', document => { find(document, 'skill', 'architect').port.differences = {}; }, /RECORDS_DIFFERENCES/],
+  ['records out of kind then name order', document => { document.records.reverse(); }, /RECORDS_ORDER/],
+];
+
+for (const [name, mutate, pattern] of rejections) {
+  test(`records reject ${name}`, () => {
+    const changed = committed();
+    mutate(changed);
+    assert.throws(() => validateRecords(changed, { root }), pattern);
+  });
+}
+
+test('a registry name without a snapshot blob fails the build loudly', () => {
+  const box = mkdtempSync(join(tmpdir(), 'registry-records-'));
+  try {
+    cpSync(join(root, 'PARITY.json'), join(box, 'PARITY.json'));
+    for (const path of ['vendor', 'skills', 'scripts', 'docs/upstream-target-0.15.36.json', 'docs/upstream-dispositions-0.15.36.json', 'LICENSE']) {
+      mkdirSync(dirname(join(box, path)), { recursive: true });
+      cpSync(join(root, path), join(box, path), { recursive: true });
+    }
+    const parity = readJSON(join(box, 'PARITY.json'));
+    parity.skills.ghost = 'ADAPTED';
+    writeFileSync(join(box, 'PARITY.json'), serialize(parity));
+    assert.throws(() => buildRecords({ root: box }), /RECORDS_SOURCE_BLOB_MISSING: skill ghost/);
+  } finally {
+    rmSync(box, { recursive: true, force: true });
+  }
+});

package/scripts/upstream/report.d.ts

@@ -0,0 +1,30 @@
+/** Detection is advisory. No report state authorizes baseline advancement. */
+export type GateStatus = 'passed' | 'failed' | 'not_run';
+export interface SyncReport {
+  schemaVersion: 1;
+  source: { repository: 'cursor/plugins'; path: 'pstack' };
+  baseline: Snapshot;
+  candidate: Snapshot;
+  syncId: string;
+  changes: Change[];
+  nameDrift: Record<'skills' | 'playbooks', { added: string[]; deleted: string[] }>;
+  runtimeSeams: { taskId: string; side: 'baseline' | 'candidate'; path: string; line: number; name: string; evidence: string; certainty: 'keyword-hit-needs-review'; mapping: string }[];
+  impact: { history_diverged: boolean; manualReviewRequired: boolean; limitations: string[] };
+  gates: { command: string; status: GateStatus }[];
+  status: 'no_change' | 'changes_detected' | 'blocked';
+  lifecycle: 'detected' | 'blocked';
+  fingerprint: string;
+  generatedAt: string;
+}
+interface Snapshot { sha: string; version: string; names: { skills: string[]; playbooks: string[] } }
+interface Change {
+  id: string; path: string; oldPath: string;
+  status: 'added' | 'modified' | 'deleted' | 'renamed';
+  oldBlob: string | null; newBlob: string | null; oldMode: string | null; newMode: string | null;
+  category: 'skill' | 'playbook' | 'reference' | 'script' | 'agent' | 'manifest' | 'docs' | 'other';
+  content: { baseline: string; candidate: string }; rawEvidence: string; summary: string;
+  localFiles: string[];
+  disposition: 'PORT' | 'PI_EQUIVALENT' | 'CURSOR_ONLY' | 'DOC_ONLY' | 'IGNORE_WITH_REASON';
+  risk: 'high' | 'medium' | 'low'; manualReview: true; owner: null;
+  intent: string; acceptance: string[]; evidenceStatus: 'missing'; taskStatus: 'pending';
+}

package/skills/architect/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: architect
+description: "Sketch types, signatures, and module structure before code, then stay in the loop while implementation fills in. Use for /architect, 'architect this', 'design this', or non-trivial work where jumping to code would lock in the wrong shape."
+disable-model-invocation: true
+---
+
+<!-- Generated by scripts/semantics/generate.mjs; edit the source mapping/adapter, not this file. -->
+
+# Pi adapter for the pinned pstack source
+
+The behavior source is the `vendor/upstream/0.15.36/pstack/` snapshot at `c742dd61706fbacc1b95f1a20b7b988cf096ce6c`. Generated supported Skill/playbook entrypoints retain the upstream Markdown after this Pi prelude. The eleven core workflows have critical-rule mappings; preserving a source body does not prove that a model followed it. The full source inventory is pinned separately; maintainer semantic sign-off remains pending.
+
+Apply user instructions and repository authority first. Read referenced source Markdown through `pstack_skill` with `upstream/skills/<skill>/...` resource IDs, consuming every page. Statechart's 0.15.36 TypeScript runtime and its test corpus are bundled under `skills/statechart/scripts`; the older 0.15.32 `.mjs` tools are retained for compatibility. Java/TLC and optional renderers are external dependencies. Other Cursor plugins, private APIs, drivers and cloud resources are not supplied.
+
+For Statechart execution, run `node <skill-dir>/../../dist/statechart/statechart.js SPEC.tla [--config FILE] [--view FILE] [--out DIR]`. This compiled copy is required in installed packages because Node does not strip TypeScript inside `node_modules`. The upstream source and test corpus remain unchanged.
+
+## Platform substitutions
+
+- Task workers use `pstack_agents` and `pstack_workflow` Pi AgentSessions. The parent owns the playbook. Parallel writers use Git worktrees; integrated delivery uses an explicit integrator and verification. These are local processes, not cloud VMs or OS sandboxes.
+- `/setup-pstack` previews model roles and suggested panels using models visible in the current Pi session; edit only what needs changing. Existing choices are preserved. Panels with the same model in several seats do not provide model diversity. Model roles use `models.json`; pass the playbook and, for named roles such as Reflect's `tooling`, `judgment`, `divergent`, and `synthesizer`, `modelRole` when dispatching. Explicit node models take precedence.
+- Pi `thinkingLevel` replaces Cursor's reasoning slug conventions. Optional same-family fallback chooses a registered model from the same provider and reports it; a supported lower reasoning level may be used and reported. Unknown families are not guessed, Cursor `-fast` aliases are not rewritten, and authentication/inference failures are not automatically retried.
+- For an unconfigured panel, plans suggest available Pi models and disclose repeated seats. Unresolvable configured seats are dropped or replaced with an available survivor or the parent, with notes. A known-family parent gets a judge only from another recognized family; if none is available, the plan produces candidates only and the coordinator must inspect, choose, integrate and verify them. A failed or unaccepted candidate is excluded only after the other candidates settle; verified survivors remain eligible and the dropout is recorded.
+- Arena's cross-judge uses confined `pstack_candidates` access to verified worktrees. The integrator independently reads and compares candidates before selecting and grafting. Architect's template includes a separate implementation phase after the selected sketch; the coordinator still owns upstream grounding (`how`/`why`) and optional checkpoints.
+- Interrogate creates a worktree for each adversary, copies the reviewed staged, unstaged and untracked changes, and runs a separate repro-verifier on each worktree. No adversary changes are integrated. Both sessions must report command, observed and expected output; synthesis can only carry reproductions present in a verifier report. These sessions use Pi's ordinary writable-agent shell permissions; the verification-policy allowlist controls native gate commands, not their interactive shell. Model reports are not independently attested receipts: the coordinator must inspect actual command evidence and the effect of any repro edits before claiming a finding is verified.
+- Swarm supports partition, best-of, first-pass and rank-all race templates. First-pass waits for a candidate's deterministic acceptance, requests cooperative cancellation of the remaining sessions, and waits for them to settle. Rank-all reports every rank without automatically integrating a winner. Mixed partition/race still needs an explicit DAG.
+- Custom Mode maps to sticky `/poteto-mode`. `/loop` maps to `/pstack-loop`, which requires an active Pi host and cannot promise cloud-root scheduling or exact delivery across a crash.
+- Use an available named CLI/UI driver for real-surface proof. Without one, return blocked or inconclusive with the exact reason; unit tests, fake providers and worker reports cannot replace a live lane.
+
+## Explicit policy deviations
+
+- Native exact-head/base ledgers invalidate verification when either changes, including patch-preserving restacks; upstream can reuse some patch-ID-stable verdicts.
+- Read-only reviewer, scout and verifier sessions inspect confined source and evidence but cannot run shell commands or live MCP. Deterministic commands run in an authorized runner or writable lane. For external investigation, the parent supplies evidence snapshots and verifies decisive citations.
+- Autopilot templates prepare local DAG artifacts. The coordinator remains responsible for the owner lifecycle, early PRs, periodic audit, rebase discipline, countersigns and stop propagation. A stack template alone does not deliver a remote PR stack. Babysit stops at merge-ready; shipping and remote writes require the actual applicable authorization.
+- Opening a PR does not start a babysit. Finish the phase or stack before a requested babysit unless an explicitly assigned full-autonomy owner owns the loop and has reported code-ready. Babysit stops before merge; operator-reserved items never merge automatically.
+
+## Unsupported operations
+
+`Cursor-private-PR-provenance`, `Cursor-watch-READY`, `Cursor-cleanup-plugin` and `Bugbot-pass-dismissal` are unsupported. GitHub/Origin and native states are alternatives with their own evidence boundaries, not proof that a Cursor operation ran. `make-bot-ui` and the Cursor automation event pack require Cursor-specific surfaces. Report these limitations rather than marking unavailable operations complete.
+
+## Evidence boundary
+
+`SEMANTICS.json` records selected critical-rule mappings, exact source lines, deviations, bound tests and file fingerprints. Inventory counts, source hashes, deterministic checks, Pi SDK/fake-provider tests, real-model runs and maintainer semantic review are separate evidence levels. Advancing the source pin and passing CI do not establish complete Cursor/Pi equivalence or maintainer approval.
+
+
+## Pi panel execution
+
+Use `/setup-pstack` to review or change the architect panel. Unconfigured panels use disclosed session-available suggestions. Use `pstack_semantics` with action `panel` and name `architect` to resolve the configured seats against the model registry; this does not check authentication or run inference. Then use `pstack_workflow` with template.kind `architect`; it loads those seats automatically. Create the strict brief and, for arena/architect, a rubric. Plan first and inspect the resulting models. A plan or preflight does not mean execution ran. Arena/architect use one read-only cross-judge when an eligible different-family model is available. When skipped, inspect and select candidates yourself. Interrogate uses isolated adversaries and separate repro sessions; inspect their real command evidence.
+
+---
+
+## Pinned upstream instructions
+
+Source: cursor/plugins@c742dd61706fbacc1b95f1a20b7b988cf096ce6c, pstack/skills/architect/SKILL.md. The following body is retained verbatim.
+
+
+# Architect
+
+Sketch types, function signatures, class shapes, and module boundaries with `not implemented` bodies and pseudocode. Synthesize across multiple model perspectives, then fill in code against the chosen sketch.
+
+## Start
+
+Open a todolist with one entry per phase before starting.
+
+1. Ground
+2. Sketch
+3. Agree
+4. Implement
+5. Scrap
+
+## Phase A: Ground the problem
+
+Build a real mental model of every system the new code touches. Run the **how** skill over the relevant subsystems. Naming a file isn't grounding. Produce the architectural explanation `how` prescribes. If the design redefines ownership or layering, also run the **why** skill on the existing shape so the rationale becomes a constraint, not a guess.
+
+Skip Phase A only when the work is genuinely greenfield with no surrounding system to integrate.
+
+## Phase B: Sketch
+
+Run the **arena** skill with the design-sketch task and the Phase A grounding artifacts. Pass `references/runner-prompt.md` as each runner's prompt.
+
+Take the runners from the `architect runners` line in the `pstack-models.mdc` rule, in place of the `arena runners` line. If the rule or that line is missing, use `claude-opus-5-5-xhigh` and `grok-4.7-xhigh-fast`. Alias and rejected entries follow the runner rules in the **arena** skill's Phase A.
+
+Design it twice. Require at least two structurally distinct candidates before synthesis, even when the first looks sufficient. This is the **exhaust-the-design-space** principle skill made concrete. Whole-shape alternatives, not point fixes inside one shape.
+
+Screen every candidate against [`references/design-red-flags.md`](references/design-red-flags.md) before synthesis. Assume the next contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Prefer the design where a change that looks right from one file is right for the whole repo.
+
+Compare viable candidates on interface depth. Prefer the design that hides more complexity behind a smaller, simpler public surface. A rich interface can keep call chains short by concentrating capability instead of scattering it across layers.
+
+Arena returns one synthesized design package. Its synthesis decision fills the rationale's "Synthesis decision" section.
+
+## Phase C: Agree (opt-in)
+
+Default: proceed directly to implementation with the synthesized design. No human checkpoint.
+
+Opt in to a checkpoint when the invoker explicitly asks: "/architect with checkpoint," "stop and show me before implementing," or similar. Then surface the synthesized design and pause for sign-off.
+
+The synthesis can ship as its own commit either way, as the "scaffold first" mode of the **foundational-thinking** principle skill. Planned and scoped breakage during fill-in is fine, per the **outcome-oriented-execution** principle skill. For adversarial pressure on the design before implementing, run the **interrogate** skill on the synthesized sketch.
+
+If the human pushes back on the shape (in a checkpoint or after the fact), treat that as Phase A evidence. Re-ground and re-run Phase B before writing more code.
+
+## Phase D: Implement against the sketch
+
+Replace `not implemented` bodies with code, pseudocode with logic. The synthesized sketch is the contract. Deviations from it are signal to surface, not friction to absorb silently. If a function needs a parameter the sketch didn't anticipate, ask whether the sketch was wrong, the requirement was missed, or the implementation is overreaching.
+
+## Phase E: Scrap when the architecture is wrong
+
+If implementation keeps producing friction the sketch can't absorb, throw the sketch out. Don't bolt fixes onto a wrong design, per the **redesign-from-first-principles** and **fix-root-causes** principle skills.
+
+The signal is a *pattern*, not single instances. Tells:
+
+- The same shape of workaround appearing repeatedly across unrelated code.
+- Multiple unrelated edge cases that all need special-case branches.
+- Types that need escape hatches (`any`, casts, optional fields always set in practice) to compile.
+- The "we need a lock" reflex when the sketch said the state wasn't shared.
+- Callers having to know the abstraction's internal rules to use it.
+- Two or more independent Phase D deviations of the same shape across the implementation.
+
+Use judgment. A few edge cases don't condemn an architecture. Some problems are legitimately complex. Complexity in the data is not complexity in the design.
+
+When you scrap:
+
+1. Re-run the **how** skill over what's been built.
+2. Redesign as if the new constraints had been day-one assumptions, per redesign-from-first-principles.
+3. Subtract before adding, per the **subtract-before-you-add** principle skill. The new sketch should be smaller than the old one before it grows.
+4. Return to Phase B and re-run arena.
+
+## Outputs
+
+The caller's usage is written first and the type sketch derived from it. One file with new types and signatures for small changes. Module map plus type definitions for larger work. The rationale ships alongside, shaped per `references/rationale-template.md`, including the usage sketch and the synthesis decision.
+
+
+## Pi execution tools
+
+Use `pstack_agents` for one child and `pstack_workflow` / `pstack_graph` for an explicit DAG. Roles are `architect`, `worker`, `reviewer`, `verifier`, `synthesizer` and `integrator`. Parallel writers use isolated worktrees, then an integrator. A verifier directly depends on the artifact owner. Inspect workflow status on recovery; completed nodes are not replayed. Check remote state before retrying external effects. `pstack_worktrees` cleans only owned clean worktrees.

package/skills/architect/references/design-red-flags.md

@@ -0,0 +1,57 @@
+# Design red flags
+
+Screen every candidate before synthesis. A red flag is a reason to revise or reject the shape.
+
+## Shallow module
+
+A shallow module exposes a large interface while hiding little complexity. Judge depth by the capability and policy hidden behind the public surface relative to the size of that surface. Prefer a simple interface backed by substantial behavior.
+
+Do not confuse a deep module with a deep call chain. A deep call chain scatters understanding across layers. A deep module concentrates capability behind one interface.
+
+Look for these signs:
+
+- Callers coordinate several methods to complete one operation.
+- Public options expose internal stages or implementation choices.
+- Learning the interface does not save the caller from learning the implementation.
+
+## Information leakage
+
+Information leakage makes multiple modules depend on the same internal decision. A representation, policy, or protocol detail appears in more than one place, so changing it requires coordinated edits.
+
+Public re-exports of transport or wire types are leakage. Parse external data into domain types behind the interface. Keep storage schemas, framework objects, and protocol details private.
+
+## Temporal decomposition
+
+Temporal decomposition organizes modules by execution order instead of the knowledge they own. Separate load, validate, transform, and save stages often repeat one representation and its invariants across several boundaries.
+
+Group code around domain knowledge and ownership. Methods that run at different times can still belong to one module when they protect the same decisions.
+
+## Pass-through method
+
+A pass-through method forwards the same arguments to another method with the same shape. It adds a layer without hiding complexity.
+
+Remove it or move responsibility to the module that can complete the operation. Keep a forwarding boundary only when it adds policy, adaptation, or a distinct abstraction.
+
+## Split ownership
+
+More than one module writes the same state or keeps its own copy of it. An agent that edits one writer can't see the others, so their rules diverge.
+
+Give each piece of state one owner. Other modules read it or ask the owner to change it.
+
+## Two ways to do one task
+
+The design supports more than one way to do the same task. An agent copies whichever way it finds first, so every way keeps gaining callers.
+
+Keep one way. Move callers off the others and delete them in the same change.
+
+## Importable internals
+
+A caller can import a module's internals. An agent takes the shortest path that compiles, so it imports them directly and they become part of the interface.
+
+Make internals unreachable from outside the module, so an import from outside fails the build.
+
+## Hand-synced list
+
+Two or more places list the same items, and adding an item means editing every list. An agent that sees one list updates only that one.
+
+Keep one list and derive the others from it. If a list can't be derived, make the build fail when the lists disagree.