pstack-claude-mirror 0.0.0-stage → 0.9.133

package/plugins/pstack/skills/poteto-mode/scripts/worktree-audit.mjs

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+// Read-only worktree prune audit. Classifies every git worktree by size, merge
+// state, uncommitted work, ignored files outside build and cache directories,
+// commits only its HEAD reflog reaches, remote/PR state, and the most recent chat that
+// operated in it, then prints a table sorted by size with a suggested bucket.
+// Never deletes anything; deletion stays a human-gated step in the playbook.
+//
+//   node worktree-audit.mjs [repo-path] [transcripts-path ...]
+//
+// Without a transcripts path it scans every runtime's transcripts directory
+// that exists: Claude Code's projects under $CLAUDE_CONFIG_DIR, Codex's sessions
+// and archived_sessions under $CODEX_HOME, and Pi's sessions and pstack subagent
+// sessions under $PI_CODING_AGENT_DIR (defaults: ~/.claude, ~/.codex, ~/.pi/agent).
+//
+// Every probe yields a Fact, { known: true, value } or { known: false }. A hold
+// bucket needs only its own fact; `safe` needs every fact known.
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { candidates, rethrowUnlessRemoved } from "../../reflect/scripts/find-transcript.mjs";
+
+const known = (value) => ({ known: true, value });
+const UNKNOWN = Object.freeze({ known: false });
+const probe = (read) => {
+  try {
+    return known(read());
+  } catch {
+    return UNKNOWN;
+  }
+};
+const bind = (fact, next) => (fact.known ? next(fact.value) : UNKNOWN);
+
+const DAY = 86400;
+const RECENT_DAYS = 4;
+const HEADER = ["SIZE", "AGE", "MERGED", "DIRTY", "REMOTE", "PR", "LAST_CHAT", "BUCKET", "LOCKED", "WORKTREE"];
+// Merged and closed PRs drop out of gh's default open-only listing.
+const GH_PR_LIST = ["pr", "list", "--author", "@me", "--state", "all", "--limit", "1000",
+  "--json", "number,state,headRefName,headRefOid"];
+// An ignored path under one of these names is a rebuildable build or cache
+// artifact. Any other ignored path, such as `.env`, may exist nowhere else.
+export const DISPOSABLE = new Set([
+  ".build", ".cache", ".dart_tool", ".DS_Store", ".gradle", ".lake", ".lycheecache", ".mypy_cache", ".next", ".nuxt",
+  ".parcel-cache", ".pytest_cache", ".ruff_cache", ".svelte-kit", ".tox", ".turbo", ".venv", "__pycache__", "build",
+  "coverage", "DerivedData", "dist", "node_modules", "target", "venv",
+]);
+
+export function classify(facts) {
+  const { locked, dirty, orphans, pr, recent, ancestry, head } = facts;
+  if (locked.known && locked.value !== null) return "hold-locked";
+  if (dirty.known && dirty.value.wip > 0) return "hold-wip";
+  if (dirty.known && dirty.value.untracked > 0) return "hold-untracked";
+  if (orphans.known && orphans.value > 0) return "hold-reflog";
+  if (dirty.known && dirty.value.ignored > 0) return "hold-ignored";
+  if (pr.known && pr.value?.state === "OPEN") return "hold-open-pr";
+  if (recent.known && recent.value) return "verify-recent-chat";
+  if (Object.values(facts).some((fact) => !fact.known)) return "review";
+  if (ancestry.value) return "safe";
+  if (pr.value?.state === "MERGED" && pr.value.headRefOid === head.value) return "safe";
+  return "review";
+}
+
+// The default 1 MiB buffer fails a status that lists several thousand untracked files.
+function git(cwd, ...args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: Infinity })
+    .replace(/\n+$/, "");
+}
+
+const runGh = (args, cwd) =>
+  execFileSync("gh", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+
+// `--porcelain -z` output: NUL-separated fields, one record per worktree, the
+// primary worktree first.
+export function parseWorktrees(output) {
+  const worktrees = [];
+  for (const field of output.split("\0")) {
+    if (field.startsWith("worktree ")) worktrees.push({ path: field.slice("worktree ".length), prunable: false, locked: null });
+    else if (field.startsWith("prunable")) worktrees.at(-1).prunable = true;
+    else if (field.startsWith("locked")) worktrees.at(-1).locked = field.slice("locked ".length);
+  }
+  return worktrees;
+}
+
+export function defaultTranscriptRoots({
+  claudeConfigDir = process.env.CLAUDE_CONFIG_DIR,
+  codexHome = process.env.CODEX_HOME,
+  piAgentDir = process.env.PI_CODING_AGENT_DIR,
+  copilotHome = process.env.COPILOT_HOME,
+  home = homedir(),
+  stat = statSync,
+} = {}) {
+  const claude = join(claudeConfigDir || join(home, ".claude"), "projects");
+  const codex = codexHome || join(home, ".codex");
+  const piAgent = piAgentDir || join(home, ".pi", "agent");
+  const copilot = join(copilotHome || join(home, ".copilot"), "session-state");
+  const found = [claude, join(codex, "sessions"), join(codex, "archived_sessions"),
+    join(piAgent, "sessions"), join(piAgent, "pstack"), copilot].filter((root) => {
+      try {
+        return stat(root, { throwIfNoEntry: false }) !== undefined;
+      } catch (error) {
+        return !["ENOENT", "ENOTDIR"].includes(error.code);
+      }
+    });
+  return found.length ? found : [claude];
+}
+
+// APFS inode numbers pass 2^53, where two of them read as one number.
+const fileId = (path, stat) => {
+  const { dev, ino } = stat(path, { bigint: true });
+  return `${dev}:${ino}`;
+};
+
+// A link is known by the identity stat reports for what it lands on, and by
+// the name realpathSync gives it when it gives one. The name alone misses
+// links: node resolves `..` in a target before the links in it and keeps a
+// firmlink route as written, and bun opens the target to name it, which macOS
+// refuses for its autofs /home or can hang there. A dangling or looping link (ENOENT, ELOOP)
+// spells nothing. When stat fails any other way the route is closed to this
+// process and the link could land anywhere, so the error propagates and the
+// caller leaves the worktree's chat fact unknown.
+export function symlinkTargets(dir, stat = statSync) {
+  return readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isSymbolicLink()).flatMap((entry) => {
+    const link = join(dir, entry.name);
+    try {
+      return [[link, { id: fileId(link, stat), name: process.platform === "darwin" && process.versions.bun ? undefined : probe(() => realpathSync(link)).value }]];
+    } catch (error) {
+      if (["ENOENT", "ELOOP"].includes(error.code)) return [];
+      throw error;
+    }
+  });
+}
+
+// Git reports a worktree by its resolved path, while a session may name it
+// through a symlink in an ancestor directory, as macOS spells /private/tmp/x
+// as /tmp/x, or through several, as /tmp/link/x when /private/tmp/link points
+// at /private/tmp/real. A worktree whose directory is gone keeps git's spelling.
+export function pathSpellings(path, linksIn = symlinkTargets, stat = statSync) {
+  let resolved;
+  try {
+    resolved = realpathSync(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return [path];
+    throw error;
+  }
+  const ancestors = [];
+  for (let dir = dirname(resolved); ; dir = dirname(dir)) {
+    ancestors.unshift(dir);
+    if (dir === dirname(dir)) break;
+  }
+  const onPath = [...ancestors, resolved];
+  // A link lands on every directory that it names or that shares its identity:
+  // a filesystem may report one identity for several, and a spare spelling
+  // costs a hold where a missed one can cost the worktree.
+  const links = ancestors.flatMap((dir) => linksIn(dir).flatMap(([link, { id, name }]) =>
+    onPath.filter((target) => target === name || fileId(target, stat) === id).map((target) => [dir, link, target])));
+  // Spell each directory from the root down, so a link's own directory is
+  // already spelled when the link is applied. A link back up to an ancestor of
+  // its directory is applied through that directory's resolved spelling only,
+  // which keeps the set finite.
+  const spelled = new Map();
+  for (const dir of onPath) {
+    const parent = dirname(dir);
+    const forms = new Set(parent === dir ? [dir] : spelled.get(parent).map((form) => join(form, basename(dir))));
+    for (const [home, link, target] of links) {
+      if (target === dir) for (const form of spelled.get(home) ?? [home]) forms.add(join(form, basename(link)));
+    }
+    spelled.set(dir, [...forms]);
+  }
+  return [...new Set([path, ...spelled.get(resolved)])];
+}
+
+// A transcript names a worktree up to a boundary byte or the end of the JSON
+// string, never a bare prefix, so `/x/candidate` does not inherit a chat that
+// ran in `/x/candidate-long`. Only JSONL is scanned, so the path appears
+// JSON-escaped and a `\` after it opens the escape of a quote, backslash, or
+// control byte. `.` counts only before another boundary (a sentence-final
+// path), because `/x/candidate.bak` is a plausible sibling. `*`, `$`, and `{`
+// stay out: they extend a path by glob or expansion. `?` globs too, but it
+// also ends a question or a URL's path, and a false match costs only a hold.
+const BOUNDARY = new Set(Buffer.from("/\\\"' `:;),|&<>]}?!"));
+const DOT = ".".charCodeAt(0);
+const bounded = (text, at) => at === text.length || BOUNDARY.has(text[at]);
+function mentions(text, needle) {
+  for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + 1)) {
+    const end = at + needle.length;
+    if (bounded(text, end) || (text[end] === DOT && bounded(text, end + 1))) return true;
+  }
+  return false;
+}
+
+// Git on Windows may spell a path with forward slashes while the session uses backslashes.
+function transcriptNeedles(spellings) {
+  const forms = spellings.flatMap((spelling) => (/^(?:[a-z]:[\\/]|\\\\|\/\/)/i.test(spelling)
+    ? [spelling.replaceAll("\\", "/"), spelling.replaceAll("/", "\\")]
+    : [spelling]));
+  return [...new Set(forms)].map((form) => Buffer.from(JSON.stringify(form).slice(1, -1)));
+}
+
+// `spellings` maps each worktree path to every spelling a session could use.
+export function lastChats(roots, spellings) {
+  const needles = [...spellings].map(([path, forms]) => [path, transcriptNeedles(forms)]);
+  const latest = new Map();
+  for (const { path: file } of roots.flatMap((root) => candidates(root, Infinity))) {
+    let text, mtime;
+    try {
+      text = readFileSync(file);
+      // A session can resume after enumeration. Its new content must use its
+      // current timestamp, not the old one used to order the candidates.
+      mtime = Math.floor(statSync(file).mtimeMs / 1000);
+    } catch (error) {
+      rethrowUnlessRemoved(error);
+      continue;
+    }
+    for (const [path, forms] of needles) {
+      if (mtime > (latest.get(path) ?? 0) && forms.some((needle) => mentions(text, needle))) latest.set(path, mtime);
+    }
+  }
+  return latest;
+}
+
+// The trunk is whatever the remote says it is; main only when it publishes no
+// usable HEAD.
+function trunkName(repo) {
+  const advertised = probe(() => git(repo, "ls-remote", "--symref", "origin", "HEAD"));
+  return (advertised.known && /^ref: refs\/heads\/(.+)\tHEAD$/m.exec(advertised.value)?.[1]) || "main";
+}
+
+function isAncestor(repo, head, trunk) {
+  try {
+    git(repo, "merge-base", "--is-ancestor", head, `refs/remotes/origin/${trunk}`);
+    return true;
+  } catch (error) {
+    if (error.status === 1) return false;
+    throw error;
+  }
+}
+
+// `--ignored=matching` prints an ignored directory once, as `!! node_modules/`,
+// and an ignored file inside a tracked directory by its own path.
+function dirtyState(path) {
+  const lines = git(path, "status", "--porcelain", "--untracked-files=all", "--ignored=matching", "--ignore-submodules=none")
+    .split("\n").filter(Boolean);
+  const untracked = lines.filter((line) => line.startsWith("??")).length;
+  const ignoredLines = lines.filter((line) => line.startsWith("!!"));
+  const ignored = ignoredLines.filter((line) => {
+    const parts = line.slice(3).replace(/^"|"$/g, "").split("/");
+    return !parts.some((part) => DISPOSABLE.has(part));
+  }).length;
+  return { wip: lines.length - untracked - ignoredLines.length, untracked, ignored };
+}
+
+// Counts commits that only this worktree's HEAD reflog reaches, which
+// `git worktree remove` deletes. A commit a branch reflog also lists, such as
+// a rebased branch's old tip, lives in the shared logs and survives removal.
+function reflogOnly(path, branchLogged) {
+  const visited = new Set(git(path, "rev-list", "--walk-reflogs", "HEAD").split("\n").filter(Boolean));
+  const input = [...visited, ...[...branchLogged].map((sha) => `^${sha}`)].join("\n");
+  // `--not` before `--stdin` leaves the stdin revisions unnegated.
+  return Number(execFileSync("git", ["rev-list", "--count", "--not", "--branches", "--tags", "--remotes", "--stdin"], {
+    cwd: path, encoding: "utf8", input: `${input}\n`, stdio: ["pipe", "pipe", "pipe"], maxBuffer: Infinity,
+  }).trim());
+}
+
+function remoteState(path, branch, head) {
+  const sha = git(path, "for-each-ref", "--format=%(objectname)", `refs/remotes/origin/${branch}`);
+  if (!sha) return "no-remote";
+  if (sha === head) return "pushed";
+  return `ahead${git(path, "rev-list", "--count", `refs/remotes/origin/${branch}..HEAD`)}`;
+}
+
+export function duSize(output) {
+  return output.trim().split(/\s/)[0];
+}
+
+function size(path) {
+  try {
+    return duSize(execFileSync("du", ["-sh", path], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }));
+  } catch {
+    return "?";
+  }
+}
+
+// Orders du's human-readable sizes the way `sort -h` does.
+function sizeKey(label) {
+  const match = /^(\d+(?:\.\d+)?)([KMGTPE]?)/.exec(label);
+  if (!match) return 0;
+  return Number(match[1]) * 1024 ** (match[2] ? "KMGTPE".indexOf(match[2]) + 1 : 0);
+}
+
+function dirtyLabel({ wip, untracked, ignored }, orphans) {
+  return [
+    wip > 0 && `wip:${wip}`,
+    untracked > 0 && `untracked:${untracked}`,
+    ignored > 0 && `ignored:${ignored}`,
+    orphans.known && orphans.value > 0 && `reflog:${orphans.value}`,
+  ].filter(Boolean).join(",") || "clean";
+}
+
+// `--porcelain -z` hands over the lock reason raw, newlines included.
+function lockedLabel(locked) {
+  if (locked === null) return "-";
+  return locked.replace(/\s+/g, " ").trim() || "locked";
+}
+
+function auditWorktree({ path, locked }, { repo, trunk, fetched, prs, chats, branchLogs, now }) {
+  const head = probe(() => git(path, "rev-parse", "HEAD"));
+  const age = bind(head, () => probe(() => Math.trunc((now - Number(git(path, "log", "-1", "--format=%ct", "HEAD"))) / DAY)));
+  const ancestry = bind(head, (sha) => probe(() => isAncestor(repo, sha, trunk)));
+  const dirty = probe(() => dirtyState(path));
+  const orphans = bind(head, () => bind(branchLogs, (logged) => probe(() => reflogOnly(path, logged))));
+  const branch = probe(() => {
+    const name = git(path, "rev-parse", "--abbrev-ref", "HEAD");
+    return name === "HEAD" ? null : name;
+  });
+  const remote = bind(branch, (name) => (name === null ? known("detached") : probe(() => remoteState(path, name, head.value))));
+  const pr = bind(prs, (list) => bind(branch, (name) => {
+    const matching = list.filter((entry) => name !== null && entry.headRefName === name);
+    // A branch can target several bases; a newer closed PR does not end an older open one.
+    return known(matching.find((entry) => entry.state === "OPEN") ?? matching[0] ?? null);
+  }));
+  const lastChat = chats.get(path);
+  const recent = bind(lastChat, (ts) => known(ts !== null && Math.trunc((now - ts) / DAY) <= RECENT_DAYS));
+  const bucket = classify({ trunk: fetched, head, age, ancestry, dirty, orphans, remote, pr, recent, locked: known(locked) });
+  return [
+    size(path),
+    age.known ? `${age.value}d` : "?",
+    ancestry.known ? (ancestry.value ? "YES" : "no") : "?",
+    dirty.known ? dirtyLabel(dirty.value, orphans) : "unknown",
+    remote.known ? remote.value : "unknown",
+    pr.known && pr.value ? `#${pr.value.number}/${pr.value.state}` : "-",
+    lastChat.known && lastChat.value !== null ? new Date(lastChat.value * 1000).toISOString().slice(0, 10) : "-",
+    bucket,
+    lockedLabel(locked),
+    path,
+  ];
+}
+
+// Discovery failures keep the table printing, but leave their facts unknown so
+// no row they touch can reach `safe`.
+export function audit({
+  repo,
+  transcripts,
+  gh = runGh,
+  warn = (line) => console.error(line),
+  now = Math.floor(Date.now() / 1000),
+}) {
+  const discover = (read, message) => {
+    try {
+      return known(read());
+    } catch (error) {
+      warn(`warn: ${message}: ${String(error.stderr ?? "").trim() || error.message}`);
+      return UNKNOWN;
+    }
+  };
+  const trunk = trunkName(repo);
+  // An explicit refspec updates the ref even where a single-branch clone does not track it.
+  const fetched = discover(
+    () => git(repo, "fetch", "origin", `+refs/heads/${trunk}:refs/remotes/origin/${trunk}`),
+    `could not fetch origin/${trunk}; merged column may be stale`,
+  );
+  const prs = discover(() => {
+    const list = JSON.parse(gh(GH_PR_LIST, repo));
+    if (!Array.isArray(list)) throw new Error("gh returned JSON that is not an array");
+    return list;
+  }, "gh pr list failed; PR column will be empty");
+
+  const worktrees = parseWorktrees(git(repo, "worktree", "list", "--porcelain", "-z")).slice(1);
+  const live = worktrees.filter((worktree) => !worktree.prunable).map((worktree) => worktree.path);
+  // Worktrees share ancestors, so each directory's links are read once.
+  const links = new Map();
+  const linksIn = (dir) => links.get(dir) ?? links.set(dir, symlinkTargets(dir)).get(dir);
+  const spellings = new Map(live.map((path) => [
+    path,
+    discover(() => pathSpellings(path, linksIn), `could not resolve the spellings of ${path}; LAST_CHAT column will be empty`),
+  ]));
+  const scanFailed = "transcript scan failed; LAST_CHAT column will be empty";
+  const missing = discover(
+    () => transcripts.filter((root) => !statSync(root, { throwIfNoEntry: false })?.isDirectory()),
+    scanFailed,
+  );
+  // Every root must be readable: a chat the scan could not see might be recent.
+  const found = bind(missing, (roots) => {
+    for (const root of roots) warn(`warn: ${root} not found; LAST_CHAT column will be empty`);
+    if (roots.length) return UNKNOWN;
+    const knownSpellings = new Map([...spellings].filter(([, fact]) => fact.known).map(([path, fact]) => [path, fact.value]));
+    return discover(() => lastChats(transcripts, knownSpellings), scanFailed);
+  });
+  const chats = new Map(live.map((path) => [
+    path,
+    bind(spellings.get(path), () => bind(found, (latest) => known(latest.get(path) ?? null))),
+  ]));
+
+  const branchLogs = discover(
+    () => new Set(git(repo, "rev-list", "--walk-reflogs", "--branches").split("\n").filter(Boolean)),
+    "could not read branch reflogs; no worktree can reach safe",
+  );
+  const context = { repo, trunk, fetched, prs, chats, branchLogs, now };
+  const rows = worktrees.map((worktree) =>
+    worktree.prunable
+      ? ["-", "?", "-", "-", "-", "-", "-", "prunable", "-", worktree.path]
+      : auditWorktree(worktree, context),
+  );
+  rows.sort((a, b) => sizeKey(b[0]) - sizeKey(a[0]) || (a.join("\t") < b.join("\t") ? 1 : -1));
+  return [HEADER, ...rows].map((row) => `${row.join("\t")}\n`).join("");
+}
+
+function main(argv) {
+  const [repoArg, ...transcriptsArgs] = argv;
+  const repo = probe(() => git(repoArg || process.cwd(), "rev-parse", "--show-toplevel"));
+  if (!repo.known) {
+    console.error("not in a git repo; pass a repo path");
+    return 1;
+  }
+  const transcripts = transcriptsArgs.length ? transcriptsArgs : defaultTranscriptRoots();
+  process.stdout.write(audit({ repo: repo.value, transcripts }));
+  return 0;
+}
+
+// node leaves argv[1] unresolved and may set it to a non-file (`node -e ... arg`).
+function invokedDirectly() {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/plugins/pstack/skills/principle-attack-the-premise/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-attack-the-premise
+description: "Apply when two or more fixes that share one premise have failed the same gate. Write the premise down and test it directly before you write another fix that assumes it."
+user-invocable: false
+---
+
+# Attack the Premise
+
+When two or more fixes that share one premise have failed the same gate, suspect the premise, not the fixes.
+
+**Why:** Each failed fix is evidence against the belief it assumed. A third fix on the same premise spends effort where the evidence already says the cause is not.
+
+**Pattern:**
+- **Write the premise down.** The premise is the one sentence that every failed fix assumed.
+- **Test the premise before the next fix.** Find an observation that would come out differently if the premise were false, and make it. Look at how the failures are distributed, not only at how large they are. Make the check rerunnable per [Build the Lever](../principle-build-the-lever/SKILL.md).
+- **Follow the evidence.** If it contradicts the premise, the cause is elsewhere. Look for what the failures have in common that the premise did not predict. If it confirms the premise, ask the next "why" per [Fix Root Causes](../principle-fix-root-causes/SKILL.md). The earlier fixes may have treated a consequence instead of the cause.
+- **Remove the condition instead of compensating for it**, per the [Laziness Protocol](../principle-laziness-protocol/SKILL.md). If the evidence shows that one part always lands on the losing side, change what puts it there. A mechanism that cleans up after it leaves the cause in place and adds work on every run.
+
+**Stop:** Do not start the next fix before the premise is written down and tested.
+
+This principle is distinct from [Redesign from First Principles](../principle-redesign-from-first-principles/SKILL.md), which rebuilds a design around a new requirement. It questions a fact the current design assumes.

package/plugins/pstack/skills/principle-boundary-discipline/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: principle-boundary-discipline
+description: "Apply when wiring validation, error handling, or framework adapters. Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions."
+user-invocable: false
+---
+
+# Boundary Discipline
+
+Place validation, type narrowing, and error handling at system boundaries. Trust internal code unconditionally. Business logic lives in pure functions. The shell is thin and mechanical.
+
+**Why:** Scattered validation is noisy, redundant, and gives a false sense of safety. Keep logic out of framework wiring so it can be tested without the framework.
+
+**The pattern:**
+- **At boundaries** (CLI args, config files, external APIs, network protocols): validate, return errors, handle defensively.
+- **Inside the system:** typed data, error propagation, no re-validation. Trust the types.
+- **Across the boundary.** Expose domain concepts, not the boundary's private representation. Keep general-purpose mechanism inside and special-purpose policy at the edge.
+
+**Applications:**
+
+Validation and error handling:
+- Validate config at parse time (the boundary), not inside business logic
+- Parse raw data into domain types at the boundary
+- Do not re-export transport, storage, framework, or wire types through the public surface
+- No redundant nil checks deep in call chains if the boundary already validated
+
+Code organization:
+- Business logic in pure functions with no framework dependencies
+- Parse functions: pure transforms from raw bytes to typed state
+- Prompt construction: structured state in, string out
+- Scoring and assessment: pure transforms from state to results
+
+**The tests:**
+- "Is this data crossing a system boundary right now?" If not, validation is redundant.
+- "Can this be a pure function that the shell just calls?" If yes, extract it.

package/plugins/pstack/skills/principle-build-the-lever/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: principle-build-the-lever
+description: "Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, generator, or a skill your subagents follow) instead of working by hand. The tool is the artifact a reviewer can rerun."
+user-invocable: false
+---
+# Build the Lever
+
+When the work isn't trivial, build the tool that does it instead of doing it by hand.
+
+A codemod, generator, or script does the work the same way every time and reruns for free. The tool is one artifact a reviewer can read and rerun to check the work. Hand-done changes can only be re-verified by redoing them. A deterministic script turns "trust me" into "run this".
+
+Default to building the lever. Skip it only when the task is trivial, a couple of obvious edits you can see at a glance.
+
+- Do the first unit by hand to learn the recipe, then build the tool. Prove it by rerunning it on that unit and diffing against your hand-done version. Make the lever safe to rerun.
+- For a comparison tool, seed one known-bad change for each output it claims to compare, and confirm the tool reports each mismatch. For example, change a total, then separately swap item assignments while keeping the totals. If required input is missing, the tool must refuse or report the result as inconclusive, never as a match. Keep these controls with the experiment and rerun them before you trust its results.
+- Codemod or script for edits, generator for repetitive files, a dump-to-sqlite query for analysis, a rerunnable check for verification.
+- A deterministic lever beats fan-out. If the tool can process every unit in one pass, run it yourself. Don't fan out delegates to hand-apply what a script can do.
+- When you fan work out to subagents, write the lever as a skill they all read: the recipe, the verification contract, and the do-not-touch fences in one artifact. Keep it outside the delegates' write scope so they can't quietly edit the contract.
+- Applying this principle produces a file. If you cited it and there is no codemod, script, generator, or delegate skill in the diff, you didn't apply it.
+- Commit the lever when the work outlives the session.
+
+The bar is triviality, not repetition. A one-off still earns a lever when the lever is what makes the work checkable. Per the [Laziness Protocol](../principle-laziness-protocol/SKILL.md), build the smallest script that does or proves the job, never a framework.
+
+Distinct from [Encode Lessons in Structure](../principle-encode-lessons-in-structure/SKILL.md), which makes a recurring instruction a durable guardrail. This is throughput and reviewability on the work in front of you. For scripting the verification itself, see [Prove It Works](../principle-prove-it-works/SKILL.md).

package/plugins/pstack/skills/principle-encode-lessons-in-structure/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: principle-encode-lessons-in-structure
+description: "Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text."
+user-invocable: false
+---
+
+# Encode Lessons in Structure
+
+If the lesson needs judgment and cannot be encoded, make the instruction more prominent and add an example of the failure mode.
+
+**Corollary:** If the fix is structural, only use the structural fix. The instruction is the symptom.

package/plugins/pstack/skills/principle-exhaust-the-design-space/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: principle-exhaust-the-design-space
+description: "Apply when facing a novel UI interaction or architectural decision with no precedent in the codebase. Build 2-3 competing prototypes and compare side by side before committing."
+user-invocable: false
+---
+
+# Exhaust the Design Space
+
+It also applies to product design decisions where user experience depends on feel, not logic.

package/plugins/pstack/skills/principle-experience-first/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-experience-first
+description: "Apply when product, UX, or feature-scope tradeoffs come up. Choose user delight over implementation convenience; ship fewer polished features over more rough ones."
+user-invocable: false
+---
+
+# Experience First
+
+When implementation convenience conflicts with user delight, choose delight.
+
+- Every feature, control, and option must be justified
+- Ship less, ship better (polished experience with three features beats rough one with ten)
+- Prototype before committing (design decisions are cheaper in throwaway HTML than production code)
+- Get the details right (transitions, alignment, spacing, feedback, error states)
+- Tighten the core loop (every feature should serve the central workflow or get out of the way)
+
+The user is whoever consumes the work. For a UI that is the end user. For a library or an internal API it is the colleague who imports it. The engineer who maintains the code next is a user too. Weigh their experience the same way, and explain impact from their perspective.
+
+Foundations should serve the experience. Foundational thinking governs the *sequence* of work. This principle governs the *target*.

package/plugins/pstack/skills/principle-explain-the-number/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: principle-explain-the-number
+description: "Apply before you measure, and before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think."
+user-invocable: false
+---
+
+# Explain the Number
+
+- **Write the decision before you run.** Name the result that would change a decision, and the noise floor. Stop when the run-to-run spread is larger than the effect.
+- **Ask "why not double?"** Name the resource or code path that bounds the result, such as a core, a lock, the disk, the network, or the load generator itself. Get it from a profile or from system counters taken during a run, then map it to source. A guess from reading the code is not a limiter. If you cannot say why the number is not twice as good, you do not know what you measured.
+- **List what else the number could be measuring, and rule out each one with evidence.** The usual suspects are errors, skipped or cached work, code that never ran, an untuned side (one left on default settings), noise, and a piece too small to matter end to end.
+- **Keep the evidence with the number.** Put the run count, the spread, and the limiter in the notes or a linked artifact.
+
+For a performance number, run the full procedure with the [benchmark-checklist](../benchmark-checklist/SKILL.md) skill. For an eval result, ask the same of the trials: did every run do the task, does the gap hold across trials and models, and does the scenario matter.
+
+You skipped this when a run started without the result that would change a decision, when the evidence behind a number has no run count, no spread, or no named limiter, or when the time saved is larger than the time the changed piece took.
+
+Distinct from [Prove It Works](../principle-prove-it-works/SKILL.md), which checks that an output is real.

package/plugins/pstack/skills/principle-fix-root-causes/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-fix-root-causes
+description: "Apply when debugging. Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it handles is legitimate."
+user-invocable: false
+---
+
+# Fix Root Causes
+
+When debugging, fix the fault, not the place where it surfaced. The symptom is where a wrong state became visible. The root cause is the first place the system did something it should not do, or failed to handle a state it should handle.
+
+**Why:** A symptom fix hides the evidence and leaves the fault free to surface somewhere else. Each one makes the system harder to reason about, because the code now carries a workaround for a bug that nobody named.
+
+**Pattern:**
+- Reproduce first.
+- Ask "why" at each step until the answer is a wrong decision in the code, not a consequence of an earlier one.
+- When stuck, instrument. Read the actual error and the actual state. Do not guess.
+- Ask whether the state that triggered the symptom is legitimate. If the system may be in that state, the code that broke on it is the root cause, and handling the state there is the fix. If the state should never exist, a check where it broke hides the bug. Find what produced the state. Guards, retries, swallowed errors, clamped values, and discarded state are the usual ways to hide a bug.
+- When something fails only after a restart, suspect persisted state first: config files, caches, lock files, serialized state.
+- Check for the pattern, not just the instance. Find every place with the same fault and fix them all.
+- If a workaround needs a paragraph-long comment to justify it, the code is wrong. Fix the code, not the comment.
+- If the deciding fact took a deep dig to find, propose the cheap, always-on signal that would have shown it at first look.

package/plugins/pstack/skills/principle-foundational-thinking/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-foundational-thinking
+description: "Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious."
+user-invocable: false
+---
+
+# Foundational Thinking
+
+**Structural decisions** protect option value. **Code-level decisions** protect simplicity.
+
+**Data structures first.** Get the data shape right before writing logic. Define core types early, trace every access pattern, and choose structures that match the dominant paths.
+
+At code level, DRY the structure, not every line. Types and data models should converge. Three similar statements still beat a premature abstraction. Prefer explicit over clever. Test behavior and edge cases, not line counts.
+
+**Concurrency corollary.** Before sharing state between actors, ask "what happens if another actor modifies this concurrently?" If not "nothing", isolate.
+
+**Scaffold first.** If something helps every later phase, do it first. Ask "does every subsequent phase benefit from this existing?" CI, linting, test infrastructure, and shared types are scaffold. Sequence for option value: setup before features, tests before fixes. Keep commits small and single-purpose.
+
+Each increment should land a coherent abstraction or deepen one that exists. Do not spread a new capability across callers as special-case coordination.
+
+Subtraction comes before scaffolding. Remove dead code first, then lay foundations.

package/plugins/pstack/skills/principle-guard-the-context-window/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: principle-guard-the-context-window
+description: "Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread, not raw payloads."
+user-invocable: false
+---
+
+# Guard the Context Window
+
+**Why:** Context overflow degrades reasoning quality, creates compression artifacts, and halts progress.
+
+**Pattern:**
+- **Size phases and cap scope.** Limit files per phase, set turn budgets, account for mechanism costs.

package/plugins/pstack/skills/principle-laziness-protocol/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: principle-laziness-protocol
+description: "Apply when refactoring, evaluating diff size, or tempted to add abstractions, layers, or signal threading. Bias toward deletion and the smallest change that solves the problem."
+user-invocable: false
+---
+
+# Laziness Protocol
+
+- **Consolidate decisions.** Do not repeat the same choice in several places. Put it behind one source of truth and pass the result as a simple flag.
+- **Minimize the diff.** Make the smallest change that solves the problem. Fewer lines beat "elegant" boilerplate.