dsh-pstack 0.0.0-stage → 0.2.0-beta.1

package/assets/skills/poteto-mode/playbooks/visual-parity.md

@@ -0,0 +1,11 @@
+### Visual parity
+
+**You own pixel-exact equivalence. The baseline is the spec. You do not touch it.** Equivalence is verified by image diff, not by eye.
+
+1. Establish the baseline first, before any migration: a visual regression harness that screenshots the current component across its states, plus the target when matching two implementations. No baseline, no parity claim. A blocking prerequisite, not a follow-up. Freeze it before the first component moves: record the harness command and the baseline image paths, and do not regenerate a baseline mid-run, because a diff against a baseline you rewrote proves nothing.
+2. Anti-shortcut clauses, stated and held: no harness modifications, no baseline tampering, no component restructuring to make a diff pass. If the baseline looks wrong, stop and ask, don't edit it. Editing it is the one shortcut that makes every later diff meaningless.
+3. Migrate one component at a time. Parallelize across local worktrees, one owner per component, because two writers in one checkout overwrite each other (the **separate-before-serializing-shared-state** principle skill). Give each owner its own `create_worktree` checkout and pass that absolute path as its `cwd`; a worktree separates the working directory and the branch, not ports, caches, or services, so name whatever else the component shares. Shared primitives migrate first as a blocking phase.
+4. Verify each component against its baseline with a real image diff on the matching surface. Name the comparison tool and prove it separates before migrating anything. A nonzero diff is a fail, so investigate the pixel delta and iterate until it reaches zero. If this machine has no image comparison that reports a per-image delta, stop and say so: without it the run can only report what the eye saw, and that is not a parity claim. A goal can drive the iteration when the run is long, with a zero-diff predicate and `update_goal` `complete` only when every component's diff is zero, but a goal measures nothing itself, so a completed goal is not a parity verdict.
+5. Run **Opening a PR** per component or per safe batch.
+
+**Reply:** components migrated, the diff result for each, the comparison tool and the frozen baseline harness location, what's left, and whether parity is claimed or unverified.

package/assets/skills/poteto-mode/playbooks/worktree-cleanup.md

@@ -0,0 +1,20 @@
+### Worktree and simulator cleanup
+
+1. Snapshot and audit. Record `df -h /`, then run `pstack_script` with `id: "worktree-audit"` and `args: ["-b", "<pr-base-ref>", "--sessions", "<json>", "<repo-path>"]` (principle-build-the-lever). The tool runs the bundled script on the Host's own runtime, so no `bun`, `bash`, or `node` on the PATH is involved. Without `-b` it checks `MERGED` against `origin/HEAD`, so pass `-b origin/<branch>` when PRs target another branch. It reads paths from `git worktree list`, never hand-typed, since a hand-typed `myrepo-worktrees/x` misses one that lives elsewhere (principle-encode-lessons-in-structure). It classifies each worktree by size, age, merge state, uncommitted work, PR state, and the newest session that touched it, then suggests a bucket.
+
+    Its session input is an array you build from `pstack_history` results, one entry per session you read:
+
+    ```json
+    [{"sessionId": "<session.id>", "cwd": "<session.cwd>", "lastEventTime": 0}]
+    ```
+
+    Use the largest `events[].time` in that session's page as `lastEventTime`. The script never reads the session store, so an entry you omit is a worktree it cannot see, and omitting the whole array leaves `LAST_CHAT` as `-` and the bucket as `unknown-usage`. A `pstack_history` result passed through unchanged is refused: that tool returns one object, never an array. Pass `background: true` for a large tree.
+2. The bucket is advice, not permission. The pinned and active sessions are the real artifact (principle-prove-it-works). Pinned state has no public source in this host, so the script prints `PINNED unknown` for every row; ask the user for the pinned and in-use set instead of inferring it, and cross-check every candidate. When the user names a pinned or in-use worktree, that set wins over any `safe` bucket.
+3. Verify usage before deleting. For every `verify-recent-chat` or `unknown-usage` row, or anything you doubt, ask the user which sessions are still live, and read the ones you may with `pstack_history` to see which worktree paths those events touch. Do not scan the session store for paths (principle-guard-the-context-window: session logs are bulk). An active session can start arena and repro trees in sibling worktrees, so a worktree can be in use even when its name never appears in the user's own summary. Pick each subagent's role per the Subagents section of `poteto-mode`; read its `SKILL.md` at its absolute resource path. Start from the level the role line names, raise it for hard work and lower it for routine work by passing `reasoningEffort`; a child that cannot call `set_reasoning_effort` keeps the level you gave it.
+4. Pause on irreversible loss. `wip:N` is N tracked uncommitted edits. Show the diff and get a decision first, since removing a clean worktree is recoverable from its branch but uncommitted work is gone. `scratch:N` is untracked throwaway, safe to drop, but name the files. Per Autonomy, clean and merged and not-in-use proceeds. `wip` and in-use pause.
+5. Prune the confirmed set. Re-read `git worktree list` and confirm each absolute path with the user immediately before touching it, and remove only paths approved in this run. Per path, `git worktree remove --force <path>`. If the dir survives on ignored build artifacts, `rm -rf` that same verified path, then `git worktree prune`. Branch refs survive, so no commits are lost. Confirm with `df -h /` and re-list.
+6. Simulators and other reclaimers. Simulators are usually the next-biggest win. `xcrun simctl --set testing delete all` (XCTestDevices clones), `xcrun simctl delete unavailable`, and `xcrun simctl runtime list` then `runtime delete <id>` for old runtimes. More when needed: Xcode `DerivedData` and `iOS DeviceSupport`, `~/Library/Application Support/Cursor` (`state.vscdb.backup`, and `snapshots/roots/<root>` where a `<root>` named for a folder you opened as a workspace balloons), package caches (pnpm, uv, brew, yarn). Clear only caches the user has not said to keep.
+
+This is the one playbook that deletes user state with no code review to catch a slip, so the gates above are the review.
+
+**Reply:** `df -h /` before and after with space reclaimed, the worktrees pruned, and a one-line reason for each held back (in use by which session, or which uncommitted work). State the pinned set as the user gave it, and name anything still unknown.

package/assets/skills/poteto-mode/references/bugbot-triage.md

@@ -0,0 +1,142 @@
+# Bugbot triage
+
+Use this reference when the Babysit playbook (`../playbooks/babysit.md`) handles Bugbot or review-automation comments. The goal is not to ignore Bugbot by default. The goal is to stop treating every comment as a required code change.
+
+## Decision rubric
+
+Classify each Bugbot thread before acting:
+
+- `fix`: The comment identifies a plausible correctness, security, privacy, data loss, auth, billing, migration, idempotency, race, or shipped-behavior issue. Fix it in the lowest owning PR, then reply with the commit SHA and resolve the thread.
+- `dismiss`: The comment matches a documented low-risk noisy pattern, and the current code/context proves the concern does not need a code change. Reply with a short reason and resolve the thread.
+- `ask`: The comment is novel, high-severity, security/privacy/data-related, or ambiguous. Ask the user instead of guessing.
+
+When in doubt, ask. Skipping a noisy code-quality comment is cheap; skipping a real data or security bug is not.
+
+## Learned pattern format
+
+Add future patterns in this shape:
+
+```markdown
+### <short pattern name>
+
+- Confidence: candidate | recurring | strong
+- Skip when: <conditions that must be true>
+- Do not skip when: <risk boundaries>
+- Example signal: <phrases or code context that identify the pattern>
+- Source: <PR/comment URL or short historical note>
+```
+
+Use `candidate` for one or two examples. Use `recurring` after multiple real dismissals. Use `strong` only when the pattern is narrow, repeatedly verified, and low-risk.
+
+## Recurring skip candidates
+
+### Intentional UI or design-system visual changes
+
+- Confidence: candidate
+- Skip when: The PR description, screenshots, design review, or nearby code makes the visual change explicit, and the Bugbot comment is only restating that a shared visual default changed.
+- Do not skip when: The comment points to accessibility, focus visibility, keyboard navigation, color contrast, or a component API contract that the PR did not intentionally change.
+- Example signal: Comments about focus outlines, button sizes, spacing, or shared component visual defaults where the owner replies "intentional" or "intended".
+
+### Upstack or stack-local usage Bugbot cannot see
+
+- Confidence: candidate
+- Skip when: Bugbot flags an export, component, helper, or file as unused, and the active forge's PR list and diffs, upper-stack diffs, or PR context show it is used by a later PR in the stack.
+- Do not skip when: The current PR is not part of a stack, the symbol is public API, or the supposed upstack use cannot be verified.
+- Example signal: "Exported component is never used" with a human reply like "used upstack".
+
+### Temporary duplication during parallel implementation
+
+- Confidence: candidate
+- Skip when: The PR intentionally duplicates a small amount of code to keep a new path parallel to an old path that is being deleted, replaced, or proven out.
+- Do not skip when: The duplicated code changes security, billing, data access, API behavior, or a long-lived shared abstraction would clearly reduce risk.
+- Example signal: "Significant duplication" or "duplicated validation logic" where the owner explains the old path will be deleted or the duplicate logic is intentionally local.
+
+### Existing framework or component invariant covers the warning
+
+- Confidence: candidate
+- Skip when: The concern is already guaranteed by a shared component, framework contract, type invariant, or single source of truth visible in the current diff or nearby code.
+- Do not skip when: The invariant is assumed but not enforced, depends on timing, or crosses async/state boundaries where values can diverge.
+- Example signal: Comments about missing max-height on an inner popover when the shared popover enforces viewport bounds, or nullable values where the local checked value and passed value share the same source.
+
+### Owner-declared follow-up or deferred cleanup
+
+- Confidence: candidate
+- Skip when: The PR owner explicitly says the issue is a known follow-up, the behavior is not made worse by the current PR, and the comment is not about a high-risk area.
+- Do not skip when: The agent is acting without owner input, the issue is medium/high severity product behavior, or deferring would merge a new regression.
+- Example signal: "I'll worry about that later" or "we'll delete this eventually".
+
+### Self-withdrawn or explicit false-positive rule comments
+
+- Confidence: recurring
+- Skip when: The comment body or a later Bugbot reply explicitly says the finding is withdrawn, compliant, or a false positive, and the agent can verify the relevant rule locally.
+- Do not skip when: The only evidence is a human saying "false positive" on a high-risk issue without explanation.
+- Example signal: A file-naming rule comment whose body says the file is already compliant.
+
+## Ask by default
+
+Do not auto-skip these categories, even if a previous PR dismissed something similar:
+
+- Security, privacy, auth, billing, data retention, training-data, and permission-boundary findings.
+- High-severity findings.
+- Migration, schema, idempotency, concurrency, and cross-system behavior findings.
+- Comments where the suggested fix is small and clearly reduces risk without changing product intent.
+
+Historical data showed humans sometimes dismiss security/data-flow comments. Treat those as owner judgment calls, not team-wide skip rules.
+
+## Candidate learnings from recent babysits
+
+Append new candidate learnings here during or after babysitting when they look team-useful but not yet mature. Prefer promoting recurring candidates into the section above once several PRs confirm the pattern.
+
+### Manual reimplementations of native browser behavior
+
+- Confidence: candidate
+- Skip when: Practically never. When a diff replaces native browser behavior with a manual equivalent (native sticky → JS-positioned clones, native scroll targeting → forwarded wheel/touch events, paint-order occlusion → masks/clip-path), Bugbot's logic-bug findings against that code have been consistently legitimate.
+- Do not skip when: The finding concerns event-forwarding gaps (wheel deltaMode, touch pans, scroll-chaining at edges, tap slop), mask/clip hit-testing divergence, or observer-vs-React state timing races in such code. Default to fix.
+- Example signal: "masks do not affect hit-testing", "overlay blocks wheel scroll", "ignores deltaMode", "runs in the IntersectionObserver callback before React applies state".
+- Source: one sticky-occlusion PR: six Bugbot passes, roughly eighteen findings, every one fixed rather than dismissed.
+
+### Contract-test drift claims are cheaply verifiable — run the test first
+
+- Confidence: candidate
+- Skip when: Never skip the verification itself; it costs one command. When a PR
+  ships a contract test that pins protocol or documentation prose (regexes over
+  a SKILL.md, snapshot of doc wording), and Bugbot claims "the test no longer
+  matches the doc" (or vice versa), run that test on the PR tip before
+  classifying. A red run confirms the claim empirically; a green run is a
+  concrete disproof for the dismissal reply.
+- Do not skip when: n/a — this is a verification shortcut, not a dismissal
+  pattern. Note that repeat-pass lean-dismiss heuristics would misfire here:
+  prose-pinning tests drift precisely BECAUSE earlier fix rounds edit the prose.
+- Example signal: "Contract test omits the pre-fix wait" on a PR whose earlier
+  fix commits reworded the pinned passage; the test run on the tip failed on
+  exactly the cited assertion.
+- Source: one prose-pinning PR with eight Bugbot passes; the claim was real on
+  pass 7 despite every earlier pass being fixed-and-resolved.
+
+### Stale security-review finding already fixed later in the same PR
+
+- Confidence: candidate
+- Skip when: An agentic security review (or similar) claims a missing authz/validation call, and the current PR tip clearly includes that exact gate (with tests), typically added in a later hardening commit after the review ran.
+- Do not skip when: The cited helper is a no-op for the principal under discussion, the check runs after the side effect it guards, or coverage for the claimed principal is missing.
+- Example signal: A HIGH "missing authorization check" finding while the exact guard is already called before the side effect on the tip.
+- Source: one webhook-endpoint PR whose hardening commit postdated the review run.
+
+### Widening a deliberately narrow error condition would mask the real error
+
+- Confidence: candidate
+- Skip when: The finding asks to broaden a narrow error condition (a specific
+  `errno`, error code, or status class) into a catch-all, and that narrowness
+  encodes a real distinction. The canonical shape is a dependency fallback
+  gated on `ENOENT`: "binary is not installed" is a different situation from
+  "the command ran and failed". Retrying on any non-zero exit would re-run a
+  legitimate failure (not found, expired auth, network) against the fallback
+  and then report the fallback's error, hiding the true one.
+- Do not skip when: The narrow condition misses a case in the SAME category
+  (another "binary unusable" errno such as `EACCES`, another transport-level
+  failure), the unhandled path loses data or leaves partial state, or the retry
+  is idempotent AND the original error is still surfaced.
+- Example signal: "only retries when X fails with ENOENT … never tries the
+  fallback even when a working Y exists", pointing at code whose fallback
+  exists for a missing dependency rather than a failed operation.
+- Source: one CLI-rename PR whose fallback existed for a missing binary rather
+  than a failed command.

package/assets/skills/poteto-mode/scripts/check-plan.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import process from "node:process";
+//#region .runtime-sources/skills/poteto-mode/scripts/check-plan.mjs
+const RULE = "Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked.";
+const LANES = /Ten lanes on `[^`<>]+` at the PR head/;
+const SUB_BLOCKS = [
+	"Depends on.",
+	"Files.",
+	"Build.",
+	"You see.",
+	"Verify, unit.",
+	"Verify, live.",
+	"Verify, perf.",
+	"Review gate.",
+	"Merge."
+];
+const PROGRAM_H3 = [
+	"Arm the program",
+	"Spawn owners",
+	"PR mechanics",
+	"Verdict and merge",
+	"Boot recipe"
+];
+const PROGRAM_MARKERS = [
+	"create_goal",
+	"schedule_create",
+	"status message"
+];
+const HOW_TO_READ_MARKERS = [
+	"One box is one unit of work",
+	"names the evidence",
+	"Check a box only when its evidence exists",
+	"playbooks/",
+	RULE
+];
+const PERF_ITEMS = [
+	"Metric.",
+	"Probe.",
+	"Baseline.",
+	"Rule."
+];
+const BOX = /^\s*- \[[ x]\] (.*)$/;
+const file = process.argv[2];
+if (!file) {
+	console.error("Usage: node check-plan.mjs <plan.md>");
+	process.exit(2);
+}
+const raw = fs.readFileSync(file, "utf8").split(/\r?\n/);
+const problems = [];
+const fail = (line, message) => problems.push(`${file}:${line}: ${message}`);
+let start = 0;
+if (raw[0] === "---") start = raw.indexOf("---", 1) + 1;
+const lines = [];
+let fence = null;
+const openingFence = (text) => {
+	const match = text.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+	if (!match || match[1][0] === "`" && match[2].includes("`")) return null;
+	return {
+		char: match[1][0],
+		length: match[1].length
+	};
+};
+const closingFence = (text, opening) => {
+	const match = text.match(/^ {0,3}(`+|~+)[ \t]*$/);
+	return Boolean(match && match[1][0] === opening.char && match[1].length >= opening.length);
+};
+for (let i = start; i < raw.length; i++) {
+	const text = raw[i];
+	const n = i + 1;
+	let code = Boolean(fence);
+	if (fence && closingFence(text, fence)) {
+		code = false;
+		fence = null;
+	} else if (!fence) {
+		fence = openingFence(text);
+		code = Boolean(fence);
+	}
+	lines.push({
+		n,
+		text,
+		code
+	});
+	if (code) continue;
+	const prose = text.replace(/`[^`]*`/g, "`").replace(/!\[[^\]]*\]\([^)]*\)/g, "").replace(/\]\([^)]*\)/g, "]");
+	if (/[\u2013\u2014]/.test(prose)) fail(n, "long dash");
+	if (/[\u2018\u2019\u201c\u201d]/.test(prose)) fail(n, "curly quote");
+	if (/: \S/.test(prose)) fail(n, "mid-sentence colon");
+}
+const h2 = (l) => !l.code && l.text.startsWith("## ") ? l.text.slice(3).trim() : null;
+const sections = [];
+for (const l of lines) {
+	const title = h2(l);
+	if (title !== null) sections.push({
+		title,
+		n: l.n,
+		body: []
+	});
+	else if (sections.length) sections.at(-1).body.push(l);
+}
+const find = (title) => sections.find((s) => s.title === title);
+const bodyText = (s) => s.body.map((l) => l.text).join("\n");
+const boxes = (ls) => ls.filter((l) => !l.code && BOX.test(l.text)).map((l) => ({
+	n: l.n,
+	text: l.text.match(BOX)[1]
+}));
+const h1 = lines.findIndex((l) => !l.code && l.text.startsWith("# "));
+if (h1 === -1) fail(1, "no H1 title");
+const howToRead = find("How to read this");
+if (!howToRead) fail(1, "no \"## How to read this\" section");
+if (h1 !== -1 && howToRead) {
+	const intro = lines.slice(h1 + 1).filter((l) => l.n < howToRead.n && l.text.trim() !== "");
+	if (intro.length >= 10) fail(lines[h1].n, `intro is ${intro.length} lines, under ten required`);
+	for (const marker of HOW_TO_READ_MARKERS) if (!bodyText(howToRead).includes(marker)) fail(howToRead.n, `How to read this lacks "${marker}"`);
+}
+const program = find("Program checklist");
+if (!program) fail(1, "no \"## Program checklist\" section");
+else {
+	const h3s = program.body.filter((l) => !l.code && l.text.startsWith("### ")).map((l) => l.text.slice(4).trim());
+	let cursor = 0;
+	for (const name of PROGRAM_H3) {
+		const at = h3s.findIndex((t, i) => i >= cursor && t.startsWith(name));
+		if (at === -1) fail(program.n, `Program checklist lacks "### ${name}" in order`);
+		else cursor = at + 1;
+	}
+	for (const marker of PROGRAM_MARKERS) if (!bodyText(program).includes(marker)) fail(program.n, `Program checklist lacks "${marker}"`);
+}
+const close = find("Close the program");
+if (!close) fail(1, "no \"## Close the program\" section");
+const programIndex = sections.indexOf(program);
+const closeIndex = sections.indexOf(close);
+const prSections = programIndex === -1 || closeIndex === -1 ? [] : sections.slice(programIndex + 1, closeIndex);
+if (prSections.length === 0) fail(1, "no PR sections between Program checklist and Close the program");
+const report = [];
+for (const pr of prSections) {
+	const heads = [];
+	for (const l of pr.body) {
+		if (l.code) continue;
+		const m = l.text.match(/^\*\*([^*]+)\*\*(.*)$/);
+		if (m && SUB_BLOCKS.includes(m[1])) heads.push({
+			name: m[1],
+			n: l.n,
+			rest: m[2].trim(),
+			lines: []
+		});
+		else if (heads.length) heads.at(-1).lines.push(l);
+	}
+	const names = heads.map((h) => h.name);
+	if (names.join("|") !== SUB_BLOCKS.join("|")) fail(pr.n, `${pr.title}: sub-blocks are [${names.join(", ")}], expected [${SUB_BLOCKS.join(", ")}]`);
+	const block = (name) => heads.find((h) => h.name === name);
+	const counts = {};
+	for (const h of heads) counts[h.name] = boxes(h.lines).length;
+	const depends = block("Depends on.");
+	if (depends && depends.rest === "") fail(depends.n, `${pr.title}: Depends on names nothing`);
+	for (const name of [
+		"Files.",
+		"Build.",
+		"You see.",
+		"Verify, unit.",
+		"Merge."
+	]) {
+		const b = block(name);
+		if (b && boxes(b.lines).length === 0) fail(b.n, `${pr.title}: ${name} has no box`);
+	}
+	for (const name of [
+		"Verify, unit.",
+		"Verify, live.",
+		"Verify, perf."
+	]) {
+		const b = block(name);
+		if (b && !b.rest.startsWith(RULE)) fail(b.n, `${pr.title}: ${name} does not open with the rule`);
+	}
+	const live = block("Verify, live.");
+	if (live) {
+		if (!LANES.test(live.rest)) fail(live.n, `${pr.title}: Verify, live lacks "Ten lanes on \`<swarm workers model>\` at the PR head" with the model filled in`);
+		const lanes = boxes(live.lines).map((b) => ({
+			...b,
+			m: b.text.match(/^Lane (\d+)\. /)
+		}));
+		const numbers = lanes.filter((b) => b.m).map((b) => Number(b.m[1])).sort((a, b) => a - b);
+		if (numbers.join(",") !== "1,2,3,4,5,6,7,8,9,10") fail(live.n, `${pr.title}: lanes are [${numbers.join(",")}], expected 1 to 10`);
+		for (const lane of lanes) if (!lane.m) fail(lane.n, `${pr.title}: live box is not a lane`);
+		else if (!/Save `[^`]+`/.test(lane.text)) fail(lane.n, `${pr.title}: lane ${lane.m[1]} names no screenshot`);
+		else if (!lane.text.includes("Pass when")) fail(lane.n, `${pr.title}: lane ${lane.m[1]} has no pass predicate`);
+	}
+	const perf = block("Verify, perf.");
+	if (perf) {
+		const items = boxes(perf.lines).map((b) => b.text.split(" ")[0]);
+		if (items.join("|") !== PERF_ITEMS.join("|")) fail(perf.n, `${pr.title}: perf boxes are [${items.join(", ")}], expected [${PERF_ITEMS.join(", ")}]`);
+	}
+	const gate = block("Review gate.");
+	if (gate) {
+		const gateBoxes = boxes(gate.lines);
+		if (gate.rest.startsWith("None.")) {
+			if (gateBoxes.length) fail(gate.n, `${pr.title}: Review gate says None but has boxes`);
+		} else {
+			const text = gate.lines.map((l) => l.text).join("\n");
+			if (gateBoxes.length === 0) fail(gate.n, `${pr.title}: Review gate has no box`);
+			for (const word of [
+				"screenshot",
+				"video",
+				"operator"
+			]) if (!text.includes(word)) fail(gate.n, `${pr.title}: Review gate lacks "${word}"`);
+		}
+	}
+	const total = boxes(pr.body).length;
+	const cells = SUB_BLOCKS.filter((s) => s !== "Depends on.").map((s) => `${s.replace(/[ ,.]+/g, "-").replace(/-$/, "").toLowerCase()}=${counts[s] ?? 0}`);
+	report.push(`${pr.title}  boxes=${total}  ${cells.join(" ")}`);
+}
+if (closeIndex !== -1) {
+	const tail = sections.slice(closeIndex + 1);
+	for (const s of tail) if (!s.title.startsWith("Appendix")) fail(s.n, `"## ${s.title}" after Close the program is not an appendix`);
+	if (!tail.some((s) => s.title.includes("Prototype evidence"))) fail(close.n, "no \"## Appendix ... Prototype evidence\" section");
+}
+for (const line of report) console.log(line);
+console.log(`${prSections.length} PR sections, ${problems.length} problems`);
+for (const p of problems) console.error(p);
+process.exit(problems.length ? 1 : 0);
+//#endregion
+export {};