@mccune1224/pi-pstack 0.1.0 → 0.2.0

package/scripts/sync-upstream.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync, readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, relative, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { applyRules, globsOf, matchesAny, overrideFor, validateSpec } from "./lib/pi-delta-rules.mjs";
+import { isBinary, readUpstreamTree, upstreamVersion } from "./lib/upstream-vendor.mjs";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const VENDORED = ["skills", "agents", "docs"];
+
+function arg(name, fallback) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? fallback : process.argv[index + 1];
+}
+
+const upstreamDir = resolve(arg("--upstream", "/tmp/upstream-plugins"));
+const outDir = resolve(arg("--out", ROOT));
+const specPath = resolve(arg("--spec", join(ROOT, "scripts", "pi-deltas.json")));
+const checkOnly = process.argv.includes("--check-only");
+
+function* walk(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) yield* walk(path);
+    else if (entry.isFile()) yield path;
+  }
+}
+
+const spec = JSON.parse(readFileSync(specPath, "utf8"));
+const problems = validateSpec(spec);
+if (problems.length > 0) {
+  console.error("pi-deltas.json is invalid:");
+  for (const problem of problems) console.error(`  ${problem}`);
+  process.exit(2);
+}
+if (!existsSync(join(upstreamDir, ".git"))) {
+  console.error(`upstream checkout missing at ${upstreamDir}`);
+  console.error("clone it first:  git clone --depth 400 https://github.com/cursor/plugins.git /tmp/upstream-plugins");
+  process.exit(2);
+}
+
+const version = upstreamVersion(upstreamDir, spec.upstream.ref);
+if (spec.upstream.version !== version) {
+  console.error(`pi-deltas.json pins ${spec.upstream.version} but ${spec.upstream.ref} is ${version}`);
+  process.exit(2);
+}
+
+const upstream = readUpstreamTree(upstreamDir, spec.upstream.ref, VENDORED);
+const excludeGlobs = globsOf(spec, "exclude");
+const addGlobs = globsOf(spec, "add");
+
+const serialized = new Map();
+for (const [path, content] of upstream) {
+  if (matchesAny(excludeGlobs, path)) continue;
+  if (overrideFor(spec, path)) continue;
+  serialized.set(path, isBinary(content) ? content : applyRules(content.toString("utf8"), path, spec.rules).content);
+}
+
+const preserved = new Set();
+for (const subtree of VENDORED) {
+  const dir = join(outDir, subtree);
+  if (!existsSync(dir)) continue;
+  for (const file of walk(dir)) {
+    const path = relative(outDir, file);
+    if (matchesAny(addGlobs, path)) preserved.add(path);
+  }
+}
+
+const undeclared = [];
+for (const subtree of VENDORED) {
+  const dir = join(outDir, subtree);
+  if (!existsSync(dir)) continue;
+  for (const file of walk(dir)) {
+    const path = relative(outDir, file);
+    if (serialized.has(path) || preserved.has(path)) continue;
+    if (upstream.has(path) && overrideFor(spec, path)) continue;
+    undeclared.push(path);
+  }
+}
+const toDelete = undeclared.filter((path) => upstream.has(path) || matchesAny(excludeGlobs, path));
+const orphaned = undeclared.filter((path) => !toDelete.includes(path));
+
+if (!checkOnly) {
+  for (const path of toDelete) rmSync(join(outDir, path));
+}
+
+const pending = [...serialized.entries()];
+const changed = [];
+for (const [path, content] of pending) {
+  const target = join(outDir, path);
+  const before = existsSync(target) ? readFileSync(target) : null;
+  const same = before !== null && (typeof content === "string" ? before.toString("utf8") === content : before.equals(content));
+  if (same) continue;
+  changed.push(path);
+  if (checkOnly) continue;
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content);
+}
+
+console.log(`upstream ${version} @ ${spec.upstream.ref.slice(0, 12)}`);
+console.log(`  vendored files: ${serialized.size}`);
+console.log(`  ours-only preserved: ${preserved.size}`);
+console.log(`  removed (upstream dropped them): ${toDelete.length}`);
+console.log(`  written: ${changed.length}`);
+if (changed.length > 0) for (const path of changed) console.log(`  ${checkOnly ? "would write" : "wrote"} ${path}`);
+if (toDelete.length > 0) for (const path of toDelete) console.log(`  ${checkOnly ? "would remove" : "removed"} ${path}`);
+if (orphaned.length > 0) {
+  console.log("\nORPHANED (ours only, undeclared; left in place, declare an add rule or delete):");
+  for (const path of orphaned) console.log(`  ${path}`);
+}
+
+const verify = spawnSync(process.execPath, [join(ROOT, "scripts", "verify-sync.mjs"), "--upstream", upstreamDir, "--spec", specPath, "--root", outDir], {
+  stdio: "inherit",
+});
+const scanner = spawnSync(process.execPath, [join(ROOT, "scripts", "check-pi-isms.mjs"), outDir], { stdio: "inherit" });
+process.exit((verify.status ?? 1) || (scanner.status ?? 1) || (orphaned.length > 0 ? 1 : 0));

package/scripts/verify-guards.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync, appendFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const upstream = resolve(process.argv[2] ?? "/tmp/upstream-plugins");
+
+if (!existsSync(join(upstream, ".git"))) {
+  console.error(`upstream checkout missing at ${upstream}`);
+  console.error("clone it first:  git clone --depth 400 https://github.com/cursor/plugins.git /tmp/upstream-plugins");
+  process.exit(2);
+}
+
+const work = mkdtempSync(join(tmpdir(), "pi-pstack-guards-"));
+for (const entry of ["skills", "agents", "docs", "scripts"]) {
+  cpSync(join(ROOT, entry), join(work, entry), { recursive: true });
+}
+
+const specPath = join(work, "scripts", "pi-deltas.json");
+
+function verifySync() {
+  const result = spawnSync(
+    process.execPath,
+    [join(work, "scripts", "verify-sync.mjs"), "--upstream", upstream, "--spec", specPath, "--root", work],
+    { encoding: "utf8" },
+  );
+  return { code: result.status ?? 1, out: `${result.stdout ?? ""}${result.stderr ?? ""}` };
+}
+
+function readSpec() {
+  return JSON.parse(readFileSync(specPath, "utf8"));
+}
+
+function writeSpec(spec) {
+  writeFileSync(specPath, `${JSON.stringify(spec, null, 2)}\n`);
+}
+
+function editRule(id, patch) {
+  const spec = readSpec();
+  const rule = spec.rules.find((candidate) => candidate.id === id);
+  if (!rule) throw new Error(`no rule named ${id} to mutate`);
+  Object.assign(rule, patch);
+  writeSpec(spec);
+}
+
+const guards = [
+  {
+    name: "a hand edit to a vendored file is caught",
+    why: "this is the case that would make the whole check self-certifying if it failed to fail",
+    mutate: () => appendFileSync(join(work, "skills", "how", "SKILL.md"), "\nedited by hand\n"),
+    expect: (out) => out.includes("skills/how/SKILL.md") && out.includes("FAIL"),
+  },
+  {
+    name: "deleting a rule is caught",
+    why: "rules are load-bearing, so removing one has to surface as unexplained content",
+    mutate: () => {
+      const spec = readSpec();
+      spec.rules = spec.rules.filter((rule) => rule.id !== "pi-dir-skills");
+      writeSpec(spec);
+    },
+    expect: (out) => /unexplained:\s+[1-9]/.test(out) && out.includes("FAIL"),
+  },
+  {
+    name: "a rule whose find no longer matches is caught as stale",
+    why: "upstream moving the text a rule targets is the failure this port exists to prevent",
+    mutate: () => editRule("pi-dir-skills", { find: ".cursor/skills-that-do-not-exist/" }),
+    expect: (out) => out.includes("STALE RULES") && out.includes("pi-dir-skills"),
+  },
+  {
+    name: "an override whose upstream baseline moved is caught",
+    why: "an override silently reverting our version is the risk that makes overrides safe to use",
+    mutate: () => editRule("override-poteto-mode-skill", { basedOn: `sha256:${"0".repeat(64)}` }),
+    expect: (out) => out.includes("override-poteto-mode-skill is stale") && out.includes("FAIL"),
+  },
+  {
+    name: "declared excludes stay absent",
+    why: "a file we declared out of scope reappearing locally should not pass silently",
+    mutate: () => {
+      const spec = readSpec();
+      const dir = join(work, "skills", "make-bot-ui");
+      cpSync(join(work, "skills", "control-ui"), dir, { recursive: true });
+      return spec;
+    },
+    expect: (out) => out.includes("skills/make-bot-ui") && out.includes("FAIL"),
+  },
+];
+
+const restore = () => {
+  for (const entry of ["skills", "agents", "docs", "scripts"]) {
+    rmSync(join(work, entry), { recursive: true, force: true });
+    cpSync(join(ROOT, entry), join(work, entry), { recursive: true });
+  }
+};
+
+const baseline = verifySync();
+if (baseline.code !== 0) {
+  console.error("baseline is not clean, so no guard can be evaluated:");
+  console.error(baseline.out.trim().split("\n").slice(-6).join("\n"));
+  rmSync(work, { recursive: true, force: true });
+  process.exit(2);
+}
+console.log("baseline clean");
+
+let failed = 0;
+for (const guard of guards) {
+  guard.mutate();
+  const result = verifySync();
+  const caught = result.code !== 0 && guard.expect(result.out);
+  console.log(`${caught ? "caught " : "MISSED "} ${guard.name}`);
+  if (!caught) {
+    failed++;
+    console.log(`  why it matters: ${guard.why}`);
+    console.log(`  exit ${result.code}, output tail:`);
+    console.log(result.out.trim().split("\n").slice(-4).map((line) => `    ${line}`).join("\n"));
+  }
+  restore();
+}
+
+const final = verifySync();
+const restored = final.code === 0;
+console.log(`${restored ? "restored" : "DIRTY  "} tree returns to a clean baseline after the mutations`);
+
+rmSync(work, { recursive: true, force: true });
+
+if (failed > 0 || !restored) {
+  console.error(`\nFAIL: ${failed} guard(s) did not catch their mutation`);
+  process.exit(1);
+}
+console.log(`\nPASS: all ${guards.length} guards catch their mutation and the tree is unchanged`);

package/scripts/verify-sync.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync, existsSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { applyRules, globsOf, hashContent, matchGlob, matchesAny, overrideFor, validateSpec } from "./lib/pi-delta-rules.mjs";
+import { isBinary, readUpstreamTree, upstreamVersion } from "./lib/upstream-vendor.mjs";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const VENDORED = ["skills", "agents", "docs"];
+
+function arg(name, fallback) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? fallback : process.argv[index + 1];
+}
+
+const upstreamDir = resolve(arg("--upstream", "/tmp/upstream-plugins"));
+const specPath = resolve(arg("--spec", join(ROOT, "scripts", "pi-deltas.json")));
+const treeRoot = resolve(arg("--root", ROOT));
+const jsonPath = arg("--json", "");
+const acceptOverrides = process.argv.includes("--accept-overrides");
+
+if (!existsSync(join(upstreamDir, ".git"))) {
+  console.error(`upstream checkout missing at ${upstreamDir}`);
+  console.error("clone it first:  git clone --depth 400 https://github.com/cursor/plugins.git /tmp/upstream-plugins");
+  process.exit(2);
+}
+
+const spec = JSON.parse(readFileSync(specPath, "utf8"));
+const problems = validateSpec(spec);
+if (problems.length > 0) {
+  console.error("pi-deltas.json is invalid:");
+  for (const problem of problems) console.error(`  ${problem}`);
+  process.exit(2);
+}
+
+const upstream = readUpstreamTree(upstreamDir, spec.upstream.ref, VENDORED);
+const version = upstreamVersion(upstreamDir, spec.upstream.ref);
+
+if (acceptOverrides) {
+  let updated = 0;
+  for (const rule of spec.rules) {
+    if (rule.kind !== "override") continue;
+    const source = upstream.get(rule.path);
+    if (source === undefined) {
+      console.error(`override ${rule.id}: ${rule.path} is not present upstream; declare it as an add instead`);
+      process.exit(2);
+    }
+    const next = hashContent(source);    if (next !== rule.basedOn) {
+      rule.basedOn = next;
+      updated++;
+    }
+  }
+  writeFileSync(specPath, `${JSON.stringify(spec, null, 2)}\n`);
+  console.log(`re-baselined ${updated} override(s) in ${specPath}`);
+  console.log("review that you merged the upstream changes into each override before committing.");
+  process.exit(0);
+}
+
+function* walk(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) yield* walk(path);
+    else if (entry.isFile()) yield path;
+  }
+}
+
+const localFiles = new Set();
+for (const subtree of VENDORED) {
+  const dir = join(treeRoot, subtree);
+  if (!existsSync(dir)) continue;
+  for (const file of walk(dir)) localFiles.add(relative(treeRoot, file));
+}
+
+const excludeGlobs = globsOf(spec, "exclude");
+const addGlobs = globsOf(spec, "add");
+const match = [];
+const delta = [];
+const overrides = [];
+const unexplained = [];
+const excluded = [];
+const added = [];
+const usedRuleIds = new Set();
+
+for (const [path, upstreamContent] of upstream) {
+  if (matchesAny(excludeGlobs, path)) {
+    excluded.push(path);
+    usedRuleIds.add(spec.rules.find((rule) => rule.kind === "exclude" && matchGlob(rule.path, path)).id);
+    if (localFiles.has(path)) unexplained.push({ path, reason: "declared exclude but the file is present locally" });
+    continue;
+  }
+  const override = overrideFor(spec, path);
+  if (override) {
+    usedRuleIds.add(override.id);
+    const localPath = join(treeRoot, path);
+    if (!existsSync(localPath)) {
+      unexplained.push({ path, reason: `override ${override.id} declares this file, but it is missing locally` });
+      continue;
+    }
+    const actual = hashContent(upstreamContent);
+    if (actual === override.basedOn) {
+      overrides.push({ path, rules: [override.id] });
+    } else {
+      unexplained.push({
+        path,
+        reason: `override ${override.id} is stale: upstream content changed since it was baselined. Merge the upstream edits into the local file, then run --accept-overrides.`,
+      });
+    }
+    continue;
+  }
+  const localPath = join(treeRoot, path);
+  if (!existsSync(localPath) || !statSync(localPath).isFile()) {
+    unexplained.push({ path, reason: "present upstream, missing locally, not declared as an exclude" });
+    continue;
+  }
+  if (isBinary(upstreamContent)) {
+    if (readFileSync(localPath).equals(upstreamContent)) match.push(path);
+    else unexplained.push({ path, reason: "binary file differs and rules cannot explain it" });
+    continue;
+  }
+  const upstreamText = upstreamContent.toString("utf8");
+  const { content, applied } = applyRules(upstreamText, path, spec.rules);
+  for (const id of applied) usedRuleIds.add(id);
+  const local = readFileSync(localPath, "utf8");
+  if (local === content) {
+    if (applied.length > 0) delta.push({ path, rules: applied });
+    else match.push(path);
+  } else {
+    unexplained.push({ path, reason: "local content differs and no rule explains it" });
+  }
+}
+
+for (const path of localFiles) {
+  if (upstream.has(path)) continue;
+  const add = spec.rules.find((rule) => rule.kind === "add" && matchGlob(rule.path, path));
+  if (add) {
+    usedRuleIds.add(add.id);
+    added.push(path);
+    continue;
+  }
+  unexplained.push({ path, reason: "present locally, absent upstream, not declared as an add" });
+}
+
+const staleRules = spec.rules
+  .filter((rule) => rule.kind === "substitute" || rule.kind === "insert")
+  .filter((rule) => !usedRuleIds.has(rule.id))
+  .map((rule) => rule.id);
+const staleStructural = spec.rules
+  .filter((rule) => rule.kind === "exclude" || rule.kind === "add" || rule.kind === "override")
+  .filter((rule) => !usedRuleIds.has(rule.id))
+  .map((rule) => rule.id);
+
+const report = {
+  generatedAt: new Date().toISOString(),
+  tree: treeRoot,
+  upstream: { dir: upstreamDir, ref: spec.upstream.ref, version },
+  counts: {
+    upstreamFiles: upstream.size,
+    match: match.length,
+    delta: delta.length,
+    override: overrides.length,
+    excluded: excluded.length,
+    added: added.length,
+    unexplained: unexplained.length,
+    staleRules: staleRules.length + staleStructural.length,
+  },
+  delta,
+  overrides,
+  excluded,
+  added,
+  unexplained: unexplained.map(({ path, reason }) => ({ path, reason })),
+  staleRules: [...staleRules, ...staleStructural],
+};
+
+console.log(`upstream ${version} @ ${spec.upstream.ref.slice(0, 12)} (${upstreamDir})`);
+console.log(`  match (verbatim upstream): ${match.length}`);
+console.log(`  pi-delta (rule-explained): ${delta.length}`);
+console.log(`  override (ours, baselined): ${overrides.length}`);
+console.log(`  excluded (declared):       ${excluded.length}`);
+console.log(`  added (ours only):         ${added.length}`);
+console.log(`  unexplained:               ${unexplained.length}`);
+console.log(`  stale rules:               ${report.counts.staleRules}`);
+if (delta.length > 0) {
+  console.log("\nrule-explained deltas:");
+  for (const entry of delta) console.log(`  ${entry.path}  <- ${entry.rules.join(", ")}`);
+}
+if (overrides.length > 0) {
+  console.log("\noverrides (ours, baselined against upstream):");
+  for (const entry of overrides) console.log(`  ${entry.path}  <- ${entry.rules.join(", ")}`);
+}
+if (unexplained.length > 0) {
+  console.log("\nUNEXPLAINED (declare a rule in scripts/pi-deltas.json, or let the sync vendor it):");
+  for (const entry of unexplained) console.log(`  ${entry.path}: ${entry.reason}`);
+}
+if (report.counts.staleRules > 0) {
+  console.log("\nSTALE RULES (upstream moved; retire or retarget these):");
+  for (const id of report.staleRules) console.log(`  ${id}`);
+}
+
+if (jsonPath) {
+  writeFileSync(resolve(jsonPath), `${JSON.stringify(report, null, 2)}\n`);
+  console.log(`\nreport: ${resolve(jsonPath)}`);
+}
+
+const ok = unexplained.length === 0 && report.counts.staleRules === 0;
+console.log(`\n${ok ? "PASS" : "FAIL"} (scripts/verify-sync.mjs)`);
+process.exit(ok ? 0 : 1);

package/skills/architect/SKILL.md

@@ -10,7 +10,7 @@ Design before implementing. Sketch types, function signatures, class shapes, and
 
 ## Start
 
-Open a todolist with one entry per phase before starting. Autonomous mode without checkpoints needs the list to show phase position and keep phases from silently disappearing.
+Open a todolist with one entry per phase before starting.
 
 1. Ground
 2. Sketch
@@ -20,7 +20,7 @@ Open a todolist with one entry per phase before starting. Autonomous mode withou
 
 ## 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. Critique mode if existing structure is the constraint or the design must push back on it.
+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 traced model `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.
 
@@ -28,9 +28,9 @@ Skip Phase A only when the work is genuinely greenfield with no surrounding syst
 
 ## 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. Each candidate produces a design package shaped per `references/rationale-template.md`: the caller's usage written first, then the type sketch, function signatures, module map, and prose rationale derived from it.
+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. Each candidate produces a design package shaped per `references/rationale-template.md`.
 
-Use your configured architect runners (defaults `inherit`, `inherit`, `inherit`, `inherit`).
+Use your configured architect runners (default: inherit, the parent session model).
 
 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.
 
@@ -46,7 +46,7 @@ Default: proceed directly to implementation with the synthesized design. No huma
 
 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. That's the "scaffold first" mode of the **foundational-thinking** principle skill; subsequent commits read as filling in bodies against a stable contract. 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.
+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.
 
@@ -54,7 +54,7 @@ If the human pushes back on the shape (in a checkpoint or after the fact), treat
 
 Replace `not implemented` bodies with code, pseudocode with logic. The synthesized sketch is the contract.
 
-Deviations from the sketch are signal worth surfacing, 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. Surface it; don't bolt it on.
+Deviations from the sketch are signal worth surfacing, 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
 
@@ -67,17 +67,17 @@ The signal is a *pattern*, not single instances. Tells:
 - 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. Surfacing deviations is Phase D's job; a repeated pattern of them is Phase E's trigger.
+- 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. The rewrite signal is repeated friction of the same shape, not single hard cases.
+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. The implementation lessons enter the new design as inputs, not vibes.
+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.
+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.

package/skills/architect/references/rationale-template.md

@@ -8,11 +8,11 @@ The prose that ships alongside the type sketch. One page. Sentence-case headings
 
 ## Usage (caller's view)
 
-*Write this first, before the type sketch. Show the README or quickstart the consumer reads, plus two or three realistic call sites in their own code. What they import, what they call, what comes back. The type sketch in [Shape](#shape) is derived from this. The two must agree; when they diverge, reconcile the sketch to the usage, not the reverse. The caller's experience is the spec. The types serve it.*
+*Write this first, before the type sketch. Show the README or quickstart the consumer reads, plus two or three realistic call sites in their own code. What they import, what they call, what comes back. The type sketch in [Shape](#shape) is derived from this. The two must agree. When they diverge, reconcile the sketch to the usage, not the reverse. The caller's experience is the spec. The types serve it.*
 
 ## Shape
 
-*The recommended architecture. Data structures first; then how data flows through the signatures. Name the load-bearing decisions. State which invariants are encoded in types, where validation lives, and what the system deliberately does not do. Judge interface depth explicitly. State what complexity the public surface hides, what remains exposed to callers, and why the interface is no larger than needed. Cite the principle behind each decision (e.g., `per boundary-discipline`); don't restate it.*
+*The recommended architecture. Data structures first. Then how data flows through the signatures. Name the load-bearing decisions. State which invariants are encoded in types, where validation lives, and what the system deliberately does not do. Judge interface depth explicitly. State what complexity the public surface hides, what remains exposed to callers, and why the interface is no larger than needed. Cite the principle behind each decision (e.g., `per boundary-discipline`). Don't restate it.*
 
 ## Synthesis decision
 

package/skills/architect/references/runner-prompt.md

@@ -1,20 +1,20 @@
 # Architect runner prompt
 
-The orchestrator passes this file through to every parallel candidate runner during Phase B and fills in the variable inputs around it: the task, the Phase A grounding artifacts, the isolated working directory, and the path to write outputs. The working directory is a git worktree when available, otherwise a per-runner subdirectory under the sketch dir; what matters is independence between candidates.
+The orchestrator passes this file through to every parallel candidate runner during Phase B and fills in the variable inputs around it: the task, the Phase A grounding artifacts, the isolated working directory, and the path to write outputs. The working directory is a git worktree when available, otherwise a per-runner subdirectory under the sketch dir. What matters is independence between candidates.
 
-You are producing one candidate design in architect's parallel exploration. Read the **architect** skill in full first; that's the workflow you're inside. Output a candidate design package: type sketch, function signatures, module map, and prose rationale shaped per [`rationale-template.md`](rationale-template.md).
+You are producing one candidate design in architect's parallel exploration. Read the **architect** skill in full first. That's the workflow you're inside. Output a candidate design package: type sketch, function signatures, module map, and prose rationale shaped per [`rationale-template.md`](rationale-template.md).
 
 Apply the following discipline. The orchestrator compares candidates on these axes to pick a base.
 
-- Caller's usage first. Write the README-style usage and two or three real call sites before the types, then derive the type sketch from them. The usage is the spec; the two must agree, so reconcile the sketch to the usage, not the reverse.
-- Data structures first. Get the core types right and the code becomes obvious. Trace each dominant access pattern through the proposed structure; if the answer is "we'll add a map / index / cache later," the structure is wrong.
-- Interface depth. Compare the capability hidden behind the public surface relative to the size of that surface. Prefer a simple interface that pulls complexity into the callee, even when the implementation becomes less simple. Do not put transport or wire types on the public surface; parse into domain types behind the interface.
+- Caller's usage first. Write the README-style usage and two or three real call sites before the types, then derive the type sketch from them. The usage is the spec. The two must agree, so reconcile the sketch to the usage, not the reverse.
+- Data structures first. Get the core types right and the code becomes obvious. Trace each dominant access pattern through the proposed structure. If the answer is "we'll add a map / index / cache later," the structure is wrong.
+- Interface depth. Compare the capability hidden behind the public surface relative to the size of that surface. Prefer a simple interface that pulls complexity into the callee, even when the implementation becomes less simple. Do not put transport or wire types on the public API. Parse into domain types behind the interface.
 - Shared state: if two actors might both write, ask "what happens?" If the answer isn't "nothing," default to per-actor state with a merge at the read boundary, per the **separate-before-serializing-shared-state** principle skill.
 - Make boundaries visible. `not implemented` errors for bodies, `// TODO` pseudocode for tricky logic, doc comments stating intent and invariants. A reader should trace data from input to output by reading types and signatures alone.
 - Encode invariants in types: hard-to-misuse types > runtime checks > prose comments, per the **encode-lessons-in-structure** principle skill.
-- Validate at boundaries, trust types inside, per the **boundary-discipline** principle skill. Business logic as pure functions; the shell stays thin.
+- Validate at boundaries, trust types inside, per the **boundary-discipline** principle skill. Business logic as pure functions. The shell stays thin.
 - Single source of truth per invariant. Derive instead of sync.
 - Idempotent state transitions where applicable, per the **make-operations-idempotent** principle skill. Ask what happens if the operation runs twice or crashes halfway.
 - Short call chains. If tracing the flow needs more than three files, flatten the hierarchy, per the **laziness-protocol** and **minimize-reader-load** principle skills.
 
-You are one of several runners, each on a different model. Produce the best design your model can make; don't hedge against the others. Differences between candidates are the signal used to pick a base and graft. Converging on a safe-looking middle defeats the exploration.
+You are one of several runners, each on a different model. Produce the best design your model can make. Don't hedge against the others. Differences between candidates are the signal used to pick a base and graft. Converging on a safe-looking middle defeats the exploration.

package/skills/arena/SKILL.md

@@ -10,7 +10,7 @@ Fan out N parallel attempts at the same task. Read every candidate end to end. P
 
 ## Start
 
-Open a todolist with one entry per phase before launching anything. The arena runs autonomously and the list keeps phases from silently disappearing.
+Open a todolist with one entry per phase before launching anything.
 
 1. Frame
 2. Fan out
@@ -21,32 +21,32 @@ Open a todolist with one entry per phase before launching anything. The arena ru
 
 ## Phase A: Frame
 
-The N candidates will receive the same prompt, so the prompt is the contract. Get it right before spawning anything.
+The N candidates will receive the same prompt, so the prompt is the contract.
 
 1. State the artifact each candidate is producing.
-2. Derive the rubric. State what success looks like for *this* task, then turn it into 3-6 concrete gradeable criteria. Concrete: `Adds a --dry-run flag that skips writes`. Vague: `code is correct`. The rubric is the picker's tool in Phase D; candidates only see the task.
-3. Pick the runners. Use the `arena runners` role list from Pi settings (`subagents.agentOverrides`, set via `/pstack-setup`) when present. Otherwise default to one runner on each of `inherit`, `inherit`, `inherit`, `inherit`. Spawn more when the arena covers multiple design directions. Same model N times when the work is generation-bound rather than judgment-sensitive.
-4. Assign output paths. Each candidate writes to its own location (a git worktree where possible, otherwise `/tmp/arena-<slug>/candidate-<n>/`). N candidates writing to the same path is shared mutable state and fails the the **separate-before-serializing-shared-state** principle skill test.
+2. Derive the rubric. State what success looks like for *this* task, then turn it into 3-6 concrete gradeable criteria. The rubric is the picker's tool in Phase D. Candidates only see the task.
+3. Pick the runners. Use `arena runners` from the `subagents.*` keys in Pi settings when present. Otherwise default to one each on your configured panel, one model family per runner. Spawn more when the arena covers multiple design directions. Same model N times when the work is generation-bound rather than judgment-sensitive.
+4. Assign output paths. Each candidate writes to its own location (a git worktree where possible, otherwise `/tmp/arena-<slug>/candidate-<n>/`), per the **separate-before-serializing-shared-state** principle skill.
 
 ## Phase B: Fan out
 
 Spawn all N subagents in one message with `run_in_background: true`, each with the task, the path to the shared grounding, its own output path, and instructions to produce both the artifact and a short rationale.
 
-The rationale is mandatory. Without it, the parent cannot tell whether a candidate's structure is principled or accidental, which makes Phase E grafting unreliable. Each rationale names the alternatives the candidate considered and what it rejected.
+Each rationale names the alternatives the candidate considered and what it rejected.
 
 If a candidate fails to produce output, proceed with N-1 and note the dropout in the synthesis record.
 
 ## Phase C: Cross-judge
 
-After all Phase B candidates complete, choose one model from the `arena cross-judge pool` in Pi settings when present. Otherwise use `inherit`. Prefer a different model family from the parent's. Spawn one read-only judge subagent on that model. It sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with the parent's reading in Phase D, not with the candidates themselves. Spawning while candidates are still writing means the judge sees partial or empty outputs and reports them as dropouts.
+After all Phase B candidates complete, choose one model from the `arena cross-judge pool` in the `subagents.*` keys in Pi settings when present. Otherwise use your configured panel, one model family per runner. Prefer a different model family from the parent's. Spawn one readonly judge subagent on that model. It sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with the parent's reading in Phase D, not with the candidates themselves. Don't spawn the judge while candidates are still writing.
 
 ## Phase D: Pick a base
 
-Read every candidate end to end before picking. Skimming N candidates surfaces only the candidate whose surface looks most familiar.
+Read every candidate end to end before picking.
 
 Score each candidate against the rubric criterion by criterion, not on holistic feel. Compare against the cross-judge. Agreement on the base confirms the pick. Disagreement means one of you is biased or the rubric was ambiguous. Read both rationales before deciding.
 
-Pick the base on which candidate a future maintainer can extend most easily without breaking invariants. Prefer the cleaner boundary or smaller surface area when two feel tied, per the Laziness Protocol.
+Pick the base on which candidate a future maintainer can extend most easily without breaking invariants. Prefer the cleaner boundary or smaller API when two feel tied, per the Laziness Protocol.
 
 Record the pick and the reason in a short synthesis note alongside the base artifact, including the cross-judge's verdict.
 
@@ -56,13 +56,13 @@ Walk each losing candidate once more and identify what is worth porting into the
 
 Fold each graft in by hand, per the **redesign-from-first-principles** principle skill. Don't paste mechanically. The result has to remain coherent under one mental model.
 
-Record what was grafted, from which candidate, and what was rejected and why. The rejection notes are the highest-signal part of the record. Future readers learn from what you considered and dropped, not just what you kept.
+Record what was grafted, from which candidate, and what was rejected and why.
 
 When N candidates converge on the same shape, that is a strong agreement signal. Note the convergence in the record and ship the consensus shape. No graft is needed. When N candidates wildly diverge, Phase A was under-specified. Reframe and re-run rather than averaging the divergence.
 
 ## Phase F: Verify
 
-The synthesized artifact has to hold up under the same scrutiny as any other output, per the **prove-it-works** principle skill. The arena does not earn you a pass.
+The synthesized artifact has to hold up under the same scrutiny as any other output, per the **prove-it-works** principle skill.
 
 If verification surfaces a problem the arena did not catch, either Phase A was wrong (re-frame and re-run) or one candidate caught it and you missed the graft (go back to Phase E). Don't paper over.