@jiroamato/pstack 0.15.15 → 0.16.0

package/README.md

@@ -51,6 +51,7 @@ pstack's skills are written in the Agent Skills format, so they load on both har
 - Every skill that had `disable-model-invocation: true` also has an `agents/openai.yaml` with `allow_implicit_invocation: false`, so Codex treats it as user-invoked too.
 - [`deslop`](./pstack/skills/deslop/SKILL.md), [`control-cli`](./pstack/skills/control-cli/SKILL.md), and [`control-ui`](./pstack/skills/control-ui/SKILL.md) are bundled from Cursor's team kit and adapted for both harnesses. Code-writing workflows load `deslop`; web/IDE/Electron workflows load `control-ui`, and CLI/TUI workflows load `control-cli`. Project `verify-<app>` skills supply app-specific commands and selectors alongside those drivers. There is no separate `control` skill. They use available terminal/browser tools; no separate team-kit plugin is needed.
 - `make-bot-ui` lost its Cursor Grok Bot webhook. It now wakes a Claude Code session over a channel, Claude Code with the reply on Telegram, or a ChatGPT Dot through Slack. Cloud subagents became git worktrees.
+- [`kiss`](./pstack/skills/kiss/SKILL.md) is the port's own addition. It assesses a repo against the principles behind Dune, Lauren Tan's agent-friendly framework, and reports what to improve, in what order, and what to leave alone. It then lands the findings through `correct` and the Refactoring playbook. See the [plugin README](./pstack/README.md#kiss).
 
 Upstream version at the time of the port: 0.15.15.
 

package/lib/install.js

@@ -24,6 +24,24 @@ export function listAgents(target, pluginRoot = PLUGIN_ROOT) {
 		.sort();
 }
 
+/**
+ * mkdir -p that explains itself when a file sits where the directory should be,
+ * such as a git symlink checked out on Windows without core.symlinks.
+ */
+function ensureDir(dir) {
+	let stat;
+	try {
+		stat = fs.statSync(dir);
+	} catch {
+		fs.mkdirSync(dir, { recursive: true });
+		return;
+	}
+	if (stat.isDirectory()) return;
+	const text = fs.readFileSync(dir, "utf8").trim();
+	const hint = /^[^\n]{1,200}$/.test(text) && !text.includes("\0") ? ` It is a file containing "${text}".` : "";
+	throw new Error(`${dir} exists but is not a directory.${hint} Move it aside, or make it a real directory or symlink, then re-run.`);
+}
+
 export function readManifest(target) {
 	if (!fs.existsSync(target.manifest)) return null;
 	return JSON.parse(fs.readFileSync(target.manifest, "utf8"));
@@ -69,14 +87,14 @@ export function install(options) {
 		if (!agents.includes(name)) fs.rmSync(path.join(target.agentsRoot, name + target.agentExt), { force: true });
 	}
 
-	fs.mkdirSync(target.skillsRoot, { recursive: true });
+	ensureDir(target.skillsRoot);
+	ensureDir(target.agentsRoot);
 	for (const name of skills) {
 		const dest = path.join(target.skillsRoot, name);
 		fs.rmSync(dest, { recursive: true, force: true });
 		fs.cpSync(path.join(pluginRoot, "skills", name), dest, { recursive: true });
 	}
 
-	fs.mkdirSync(target.agentsRoot, { recursive: true });
 	for (const name of agents) {
 		const file = name + target.agentExt;
 		const text = fs.readFileSync(path.join(pluginRoot, target.agentSource, file), "utf8");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jiroamato/pstack",
-	"version": "0.15.15",
+	"version": "0.16.0",
 	"description": "poteto's pstack for Claude Code and Codex. npx installer: copies the skills and agents into your project or your home directory.",
 	"keywords": [
 		"pstack",

package/pstack/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
 	"name": "pstack",
 	"displayName": "pstack",
-	"version": "0.15.15",
+	"version": "0.16.0",
 	"description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.",
 	"author": {
 		"name": "Lauren Tan"

package/pstack/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "pstack",
-	"version": "0.15.15",
+	"version": "0.16.0",
 	"description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.",
 	"author": {
 		"name": "Lauren Tan"

package/pstack/README.md

@@ -149,6 +149,7 @@ to keep [`/poteto-mode`](./skills/poteto-mode/SKILL.md) on across turns, follow
 | [`/setup-pstack`](./skills/setup-pstack/SKILL.md) | you want to pick which models pstack uses per role. detects your models and writes `~/.pstack/models.md`. on codex it also installs the two pstack agents. |
 | [`/reflect`](./skills/reflect/SKILL.md) | a long task landed and you want the recipe captured as a skill edit. |
 | [`/correct`](./skills/correct/SKILL.md) | you keep correcting agents for the same mistakes. mines history for mistake classes, fixes each at the highest level that works (architecture, then types, lint, and ci, then tests, with docs last), and keeps a table pairing each rule with what enforces it. |
+| [`/kiss`](./skills/kiss/SKILL.md) | you want to know how agent-friendly a repo is. assesses it against the principles behind dune (one writer per value, discovery over registries, forbidden imports fail mechanically), writes `.kiss/assessment.md` with what to improve, in what order, and what to leave alone, then lands the findings one pr at a time through `correct` and the refactoring playbook. |
 | [`/teach`](./skills/teach/SKILL.md) | you want to actually understand a change or subsystem, not just have it summarized. runs how + why and weaves one plain explanation, built up diagram by diagram. |
 | [`/tdd`](./skills/tdd/SKILL.md) | you're fixing a bug and there's a cheap local test path. write the failing test first, then the fix. |
 | [`/benchmark-checklist`](./skills/benchmark-checklist/SKILL.md) | you ran a benchmark or measured a speedup or regression. vets the number (limiter, tuning, errors, repeat runs, end-to-end relevance) before you report or act on it. |
@@ -266,6 +267,12 @@ twenty-four short skills, one principle each. `poteto-mode` indexes them inline
 
 `poteto-mode` and the relevant standalone skills explicitly load them: `deslop` for kept code, `control-ui` for web/IDE/Electron, and `control-cli` for CLI/TUI. there is no separate `control` skill. a project's `verify-<app>` skill supplies app-specific commands, selectors, and feature coverage alongside the bundled driver. the drivers use terminal and browser tools already available in the session; installing pstack does not install those tools.
 
+## kiss
+
+[`/kiss`](./skills/kiss/SKILL.md) is the port's own addition, not from upstream. it is an assessment skill built on the principles behind dune, the framework lauren tan built so agents could ship thousands of prs a month to grok bot: a correct open-file edit should preserve the whole app's invariants. `assess` reads a repo and writes `.kiss/assessment.md`: the repo's shape as a noun table, what is already right, what to improve in the order it will be landed, and what to leave alone and why. `apply` lands the findings one pr at a time, gate first.
+
+kiss adds no machinery of its own. it links the pstack skills as siblings: `how` and `why` while assessing, `correct` for a repeated mistake class, the refactoring and opening a pr playbooks for each change, `create-verification-skill` for a repo with no scripted way to prove itself. its ladder is numbered the way `correct` numbers its levels, so a finding and a fix name the same number. on claude code, invoke `/pstack:kiss`; on codex, `$kiss`.
+
 ## harness differences
 
 a few things upstream `poteto-mode` leaned on were cursor-only. the [`pstack-harness`](./skills/pstack-harness/SKILL.md) skill says what the port does instead:

package/pstack/skills/deslop/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: deslop
 description: Remove AI-generated code slop from a branch or working diff before committing. Use for /deslop, code cleanup, unnecessary comments, redundant guards, type escape hatches, or patterns that do not fit the surrounding code.
-disable-model-invocation: true
+disable-model-invocation: false
 ---
 
 # Remove AI code slop

package/pstack/skills/deslop/agents/openai.yaml

@@ -1,2 +1,2 @@
 policy:
-  allow_implicit_invocation: false
+  allow_implicit_invocation: true

package/pstack/skills/kiss/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: kiss
+description: "Assess a codebase against the principles behind Dune, the framework agents extend correctly by default, and report what to improve, in what order, and what to leave alone. Then apply the findings one PR at a time through pstack. Use for /kiss, 'assess this repo', 'is this repo agent-friendly', 'refactor toward KISS', or when agents keep making the same mistakes in a repo."
+disable-model-invocation: true
+---
+
+# KISS
+
+Keep It Simple, Stupid. A codebase is agent-friendly when a correct open-file edit preserves the whole app's invariants. KISS tells you how far a repo is from that and what to change first.
+
+KISS assumes every contributor is an agent that sees only the files it opened, copies the nearest pattern, and takes the shortest path that compiles. The question behind every finding is the same: does this repo turn that behavior into good code, or into a mistake?
+
+KISS lives in the same skills directory as pstack and links its skills as siblings (`../correct/SKILL.md`). Read [`pstack-harness`](../pstack-harness/SKILL.md) first for how to load a sibling skill (the **skill** row) and how to spawn a subagent. Where this file names a pstack skill, load its `SKILL.md` in full and follow it, with the one exception the `correct` row names.
+
+## Modes
+
+| Mode | When | Reads | Produces |
+| --- | --- | --- | --- |
+| `assess` | Any repo. The default. | `pstack-harness`, [`references/principles.md`](references/principles.md), [`references/assess.md`](references/assess.md) | `.kiss/assessment.md` |
+| `apply` | After an assessment, on request | `pstack-harness`, the assessment, `references/principles.md` | One PR per finding, in the report's order |
+
+`assess` is read-only. It never fixes. Re-running it regenerates the report and marks each finding new, unchanged, or resolved. The previous report is in git.
+
+## Assess
+
+Follow `references/assess.md`. In short: derive the repo's shape from four questions (what runs where, what outlives a run and who writes it, how two sides talk, what grows per contribution), answer the question list with file evidence, sort every answer, and write the report in the shape it gives. Every finding names the rule or anti-pattern it breaks, the contributor behavior that produces it, and the fix at the strongest level of the ladder that works.
+
+The report has a **Leave alone** section. A principle that presumes a shape the repo does not have, something a stronger mechanism already enforces, a cost that exceeds the benefit, and a constraint the repo does not own all go there, with the reason. That section matters as much as the findings. It stops the next agent from churning. A redesign the operator has not asked for is not a Leave alone reason. It stays in Improve, marked "needs a decision", with its evidence.
+
+pstack skills used while assessing:
+
+| Need | Skill |
+| --- | --- |
+| Trace how a subsystem works, where a feature lives, who writes a value | [`how`](../how/SKILL.md) |
+| Know why a shape exists before calling it debt | [`why`](../why/SKILL.md) |
+| More than one package, or more than about twenty thousand lines | [`swarm`](../swarm/SKILL.md): one read-only worker per package or side, the same question list, one report. Explain the cost and ask the operator before spawning. |
+| Write the report | [`technical-writing`](../technical-writing/SKILL.md), every layer except Diátaxis, then [`unslop`](../unslop/SKILL.md) |
+
+## Apply
+
+Only on request, only from an existing assessment. Small PRs on the main branch, the app shippable after each one. No big-bang branch. The report's Improve list is the plan and its order is the PR order.
+
+0. **Confirm the list.** Show the operator the Improve list and ask which findings to land. Findings marked "needs a decision" wait for a yes. The rest proceed.
+1. **Gate first, report-only.** One command, checked in, that runs what the repo already has in report mode plus one named check per Improve finding whose fix is level 2 or 3. Each check prints its count and nothing fails yet. The counts match the report's Count fields. This PR adds no cleanup.
+2. **Delete debt.** The Improve findings that are deletions: copy-and-modify files, dead code, legacy paths. Agents copy what exists; remove it before they do (the **subtract-before-you-add** and **migrate-callers-then-delete-legacy-apis** principle skills). A deletion that migrates callers is a reshape and goes through the Refactoring playbook, pin first.
+3. **Mechanical changes.** A formatter and one package manager. No behavior change. Strict compiler flags are not mechanical on a real repo. They are a ratcheted finding in step 4.
+4. **One finding per PR, in report order.** Each PR does the cleanup and then flips that finding's check to blocking when its count is zero. If zero is far off, ratchet: fail on net-new instances above the baseline. Never flip with open violations and no exceptions. Never weaken a check to land a PR. Each finding's check was written in step 1, so no PR here adds a check.
+5. **Re-assess.** Run `assess` again. The new report marks each finding new, unchanged, or resolved. New findings go through step 0.
+
+After the last PR the repo needs a gardener. Delete debt as it appears. Keep one paved path per pattern. Lint against an anti-pattern the moment it shows up. Re-assess on a schedule and read the whole batch before fixing anything, because a single fix hides the pattern. Sample landed PRs. When a sample shows a shortcut, fix the environment, not the PR.
+
+pstack skills used while applying:
+
+| Step | Skill |
+| --- | --- |
+| A finding that is a repeated mistake class | [`correct`](../correct/SKILL.md). Skip its "Find the mistake classes" step. The finding is the class; pass it the evidence lines and the report's level. Follow "Fix each class at the highest level", "Fix and prove", and "Keep the rule table" for that one class. One class per PR. `correct` owns the rule table in the agent instruction file and drops a row once the mistake cannot happen. |
+| A reshape: move, extract, split a god file, change ownership, migrate callers | the Refactoring playbook in [`poteto-mode`](../poteto-mode/SKILL.md). Pin the behavior, subtract, move in steps, prove equivalence. |
+| A fix that crosses a module boundary | [`architect`](../architect/SKILL.md) before code |
+| Before each PR | [`blast-radius`](../blast-radius/SKILL.md) for the one fact the change is safe because of |
+| Each PR | the Opening a PR playbook in `poteto-mode`, which runs [`deslop`](../deslop/SKILL.md) and [`no-comments`](../no-comments/SKILL.md). Run [`interrogate`](../interrogate/SKILL.md) on the diff yourself; the playbook only runs it for subagents. |
+| A program that spans days or many stacked PRs | the Multi-phase plan playbook in `poteto-mode`, seeded with the Improve list in report order, or [`figure-it-out`](../figure-it-out/SKILL.md) for a migration |
+| No verification skill in the repo | [`create-verification-skill`](../create-verification-skill/SKILL.md) |
+| A verification map that drifted | [`maintain-verification-skill`](../maintain-verification-skill/SKILL.md) |
+| A run longer than one sitting | [`show-me-your-work`](../show-me-your-work/SKILL.md) for the decision trail |
+| After the last PR | [`reflect`](../reflect/SKILL.md), to turn what the refactor taught into skill edits |
+
+## Principle skills by rule
+
+Read the leaf skill in full when a finding falls in its class. `references/principles.md` holds the rules. These hold the reasoning an agent applies while fixing. An anti-pattern id without a row uses the row of the rule it breaks.
+
+| Rule or anti-pattern | Principle skills |
+| --- | --- |
+| Rule 1, fewest decisions | [**laziness-protocol**](../principle-laziness-protocol/SKILL.md), [**minimize-reader-load**](../principle-minimize-reader-load/SKILL.md) |
+| Rule 2, forbidden dependencies fail | [**encode-lessons-in-structure**](../principle-encode-lessons-in-structure/SKILL.md) |
+| Rule 3, one writer | [**separate-before-serializing-shared-state**](../principle-separate-before-serializing-shared-state/SKILL.md), [**model-the-domain**](../principle-model-the-domain/SKILL.md) |
+| Rule 4, isolated files, not shared roots | [**separate-before-serializing-shared-state**](../principle-separate-before-serializing-shared-state/SKILL.md), [**model-the-domain**](../principle-model-the-domain/SKILL.md), [**type-system-discipline**](../principle-type-system-discipline/SKILL.md) for closed sets |
+| Rule 5, narrow exceptions | [**encode-lessons-in-structure**](../principle-encode-lessons-in-structure/SKILL.md) |
+| `raw-transport` | [**boundary-discipline**](../principle-boundary-discipline/SKILL.md) |
+| `god-file` | [**minimize-reader-load**](../principle-minimize-reader-load/SKILL.md) |
+| `type-escape-hatch` | [**type-system-discipline**](../principle-type-system-discipline/SKILL.md) |
+| `tautological-test` | [**test-behavior-not-implementation**](../principle-test-behavior-not-implementation/SKILL.md) |
+| `comments-as-bandaids` | [**fix-root-causes**](../principle-fix-root-causes/SKILL.md) |
+| `copy-and-modify` | [**migrate-callers-then-delete-legacy-apis**](../principle-migrate-callers-then-delete-legacy-apis/SKILL.md) |
+| Ordering the PRs | [**sequence-verifiable-units**](../principle-sequence-verifiable-units/SKILL.md), [**prove-it-works**](../principle-prove-it-works/SKILL.md) |
+
+## Rules that hold in both modes
+
+- Prose is the last resort. If a rule can be a type, a build failure, a lint, or a test, it is not a sentence in the agent instruction file. A rule that lives only in a doc is unenforced and the report says so.
+- An exception lives on the offending line as `kiss-allow(<finding id>): <why>. <issue link>. expires <date>. approved: <who>`. The issue link is what lets it survive `no-comments`, whose reviewer keeps issue links that explain a constraint. If the reviewer still kills it, follow `no-comments` step 5: encode the constraint or report it open. Never restore the comment. An agent never approves its own exception. A third live exception on one rule means the rule or the design is wrong.
+- Every operator correction that names a repo mistake is a signal. In `apply`, route it through `correct`. In `assess`, record it as a finding with evidence and a proposed level. A correction about scope goes under Not checked; one that names a deliberate design goes under Leave alone.

package/pstack/skills/kiss/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pstack/skills/kiss/references/assess.md

@@ -0,0 +1,110 @@
+# Assess
+
+Produce `.kiss/assessment.md`. Read-only. Every finding has `path:line` evidence, or for an absence, the location searched. No fixes.
+
+When the target is a folder inside a larger repository, say which one you assessed, put `.kiss/` at that folder's root, and scope git history to that path. When that history is a bulk import, widen to the git root and say so.
+
+If `.kiss/assessment.md` already exists, read it first. The new report replaces it; git keeps the old one. Each finding carries a stable id, `<rule or anti-pattern id>:<path>`, so the new report can mark it new, unchanged, or resolved.
+
+## Before the questions
+
+Read `principles.md`. Then build the model the questions need:
+
+- For a repo you can hold in context, read the tree, the package manifests, the CI config, and the agent instruction files. Pick the most recent unit of product work from git history and read its diff.
+- For a subsystem you cannot judge from the tree, run the **how** skill on it. Its Where Things Live section is the start of the noun table.
+- When a shape looks wrong but deliberate, run the **why** skill before calling it debt. A constraint the repo does not own goes under Leave alone, not Improve.
+- For more than one package, or more than about twenty thousand lines, run the **swarm** skill: one read-only worker per package or side, each answering the full question list for its slice, one report back. Explain the cost and ask the operator first. Merge the noun tables yourself.
+
+## Questions
+
+Answer in order. Status is `pass`, `fail`, `partial`, `n/a (<the shape the question presumes>)`, or `unknown (<what you could not see>)`. One answer may yield several entries in the report.
+
+**Shape** (principles.md section 3)
+
+1. Where does code run, and can an agent tell from the open file which boundary it is in and what it may import? Does a wrong import fail?
+2. Which values outlive a request or a run? For each, name every writer. Where a value lives on two sides, which side is authoritative?
+3. Where two boundaries talk, is there one typed contract both sides import or generate from, so a change on one side fails the build on the other?
+4. Which sets grow when someone contributes? For each, open or closed, and how it is populated today. For a closed set, does every runtime switch over it fail the build on a missing variant?
+
+Write the noun table from these answers before going on. The table is the target. Each row where today differs becomes a finding.
+
+**Rules** (principles.md section 2)
+
+5. Rule 1. From git history, list the files the most recent unit of product work changed. Which were shared files? Is the blessed path the shortest one?
+6. Rule 2. Which boundaries does the repo claim, in docs, folder names, or comments? Which are enforced mechanically, by what, and does the error name the owner?
+7. Rule 3. From question 2, which values have more than one writer? Include specs restated in code.
+8. Rule 4. From question 4, which open sets are hand-edited lists?
+9. Rule 5. Every suppression, disabled rule, `TODO`, and workaround comment. Which carry a reason, an issue link, an expiry, and a human's approval? Expect-error directives that assert rejection are tests, not suppressions.
+
+**Guardrails** (principles.md section 4)
+
+10. What runs before merge, and is it one command or several? Formatter, linter, type checker, import guard, tests. What is missing, and what would each missing one catch in this repo? If CI lives outside the checkout, say so and answer `unknown`.
+11. Type strictness: compiler flags, checker mode, which files they cover, and what they ignore.
+12. For each anti-pattern id in principles.md section 5: present or absent, count, sanctioned hits excluded, enforced today or not.
+
+**Verification** (principles.md section 6)
+
+13. Is there a project verification skill? Look for `verify-*` under `.claude/skills/` or `.agents/skills/` at the project root. Does its feature map cover every entrypoint the repo has: routes, commands, jobs? Name any drift.
+
+**Debt**
+
+14. Files over the size budget, with line counts and, from git log, how many distinct units of work edited each. Use the repo's budget if it has one, else 400. Tests count.
+15. Legacy paths, dead code, and copy-and-modify files an agent would copy. For dead code use an unused-export check or the compiler's unused flags; a grep for callers is the fallback and say so.
+
+## Sorting the answers
+
+Sort every answer. A passing answer may go under Already right. Any other answer goes under Improve or Leave alone, and one answer may produce entries in both.
+
+**Improve** holds three kinds of finding.
+
+- A rule or anti-pattern finding: one of the five contributor behaviors produces the mistake, the repo owns the code, and a fix exists at level 1, 2, or 3 of the ladder. One label per finding. When a rule and an id describe the same evidence, use the id and name the rule in the title.
+- A guardrail gap from questions 10 or 11: a missing formatter, linter, type checker, import guard, or strict mode. The fix is level 2. No behavior needed.
+- A verification gap from question 13: no skill, or drift. The fix is level 3. No behavior needed.
+
+A redesign the operator has not asked for stays here with all fields and "needs a decision" after the title. `apply` skips it until the operator says yes.
+
+Order Improve the way `apply` will land it: deletions first, then mechanical changes, then everything else by risk, then by effort. Risk is how likely an agent is to copy the pattern: `high` when it sits on the path every new unit of work takes, `medium` when it is in a module agents touch sometimes, `low` when it is isolated. Effort is `S` for one PR under an hour, `M` for one PR, `L` for several PRs.
+
+**Leave alone** when any of these holds. Say which one.
+
+- The question presumes a shape the repo does not have. The `n/a` answers land here with the presumed shape as the reason.
+- Something stronger already enforces it. A doc rule that a type also makes impossible is fine as a doc.
+- The cost exceeds the benefit. A single-writer module over the size budget whose every section is about one thing. A three-entry registry that has not grown in a year.
+- An external constraint owns it: a vendor API, a platform, a file the framework requires, polling a service that offers no events.
+
+**Already right** when the answer passes and agents are likely to copy it. Name it so the next agent protects it.
+
+## Report shape
+
+```markdown
+# KISS assessment: <repo> <date>
+
+## Shape
+<Three to six lines: what runs where, which durable values exist and who writes them, how the sides talk, which sets grow per contribution.>
+
+| Noun | Job | Lives at | May import | Found by |
+| --- | --- | --- | --- | --- |
+
+## Already right
+- <what> (<path>). <Why it matters that agents copy it.>
+
+## Improve
+### <n>. <title> (<id>, <new | unchanged | resolved>)
+Rule or anti-pattern: <rule 1 to 5, an id, guardrail gap, or verification gap>
+Behavior: <1 to 5, or none for a gap>
+Evidence:
+- <path:line> <what>
+Count: <number of hits, or 1>
+Enforcement today: <none, or the tool>
+Fix: <what> at level <1 to 3>. <Why a stronger level does not work.>
+Risk: <high | medium | low>
+Effort: <S | M | L>
+
+## Leave alone
+- <what> (<path>): <which reason above>
+
+## Not checked
+- Q<n>: <what you could not answer, and why>
+```
+
+Write it with every technical-writing layer except Diátaxis, then **unslop**. Keep it under 300 lines. A finding that needs a paragraph is two findings.

package/pstack/skills/kiss/references/principles.md

@@ -0,0 +1,138 @@
+# Principles
+
+The ideas behind Dune, the framework Lauren Tan built so agents could ship thousands of PRs a month to Grok Bot. Stack-agnostic. Nothing here names a tool. The assessment names the tool a given repo should use.
+
+## 1. The contributor model
+
+A coding agent optimizes for what fits in its context. It will, predictably:
+
+1. copy the nearest working pattern;
+2. edit the file already open;
+3. choose the shortest path that compiles;
+4. avoid deleting code whose callers are not visible;
+5. follow the requested implementation even when it conflicts with a system invariant.
+
+These are inputs to the design, not faults to prompt away. The codebase is the agent's memory. Whatever pattern exists will be copied, including workarounds, and each copy makes the next copy likelier. Keep the repo in a state where you would be happy for any file to be copied. Human friction is not a cost here. A repo this constrained is annoying for humans to write in, and agents absorb the annoyance.
+
+Every rule and anti-pattern finding names which of the five behaviors produces the mistake. A guardrail or verification gap (sections 4 and 6) does not need one.
+
+## 2. The five rules
+
+Dune's rules, verbatim. Each has the behavior it addresses, the test question the assessment asks, and one example.
+
+### Rule 1. The conventional path requires fewer decisions than a shortcut
+
+Behavior 3. If the shortcut is easier, the shortcut wins.
+
+Test: how many files must change to add one unit of product work, and how many of them are shared? A unit of product work is one merged change that adds user-visible behavior: a page, a command, an endpoint, a job. A shared file is one that two or more such units changed.
+
+Violating: to add a page, create the view, then add a route to `routes.ts`, a key to `keys.ts`, a type to `types.ts`, a nav item to `nav.ts`, and a permission to `permissions.ts`. Six decisions, five shared files. An agent skips two and the page half-works.
+
+Conforming: create `features/reports/entrypoint.*` and `features/reports/view.*`. The build discovers both. Two files, zero shared edits.
+
+### Rule 2. Forbidden dependencies fail mechanically
+
+Behaviors 1 and 3. A rule that lives only in a doc is unenforced.
+
+Test: for each boundary the repo claims, what rejects a crossing, and does the error name what to use instead?
+
+Violating: the agent instruction file says views do not call the API. `view.tsx` imports `api/client` and compiles.
+
+Conforming: the same import fails with `features/* may not import api/*. Read data through client/reports.`
+
+### Rule 3. Every durable value has one obvious writer
+
+Behaviors 1 and 2. Three writers mean three sets of rules that drift apart.
+
+Test: for each value that outlives a request or a run, name every writer. A spec restated in code (a template, rule text, a name list that another file also holds) is a durable value too, and one copy is the writer.
+
+Violating: `view.tsx`, `nav.tsx`, and `url-sync.ts` each write `selectedReportId`.
+
+Conforming: one module owns it and exposes `useSelectedReport()` and `selectReport(id)`. Everyone else calls the command.
+
+### Rule 4. New product work adds isolated files rather than branches in shared roots
+
+Behaviors 1 and 2. Two agents adding two features must never touch the same file.
+
+Test: does any shared file grow when a unit of work is added?
+
+Violating: `registry.ts` with one line per feature, which every feature edits.
+
+Conforming: one folder per feature with a reserved filename. A build step collects them into a catalog that is derived, never hand-edited.
+
+### Rule 5. Exceptions are narrow, explicit, and reviewed as architecture changes
+
+Behavior 5. Every guard has an escape hatch, and the hatch has a cost.
+
+Test: does every suppression, disabled rule, and workaround carry a reason, an issue link, an expiry, and a human's approval, on the offending line? An approval an agent wrote is a fail. An expect-error directive whose purpose is to assert that a type rejects a value is a test, not a suppression.
+
+Format, in whatever comment syntax the language has: `kiss-allow(<finding id>): <why>. <issue link>. expires <date>. approved: <who>`. A third live exception on one rule means the rule or the design is wrong. Fix one of them.
+
+## 3. Deriving the shape
+
+Dune names its nouns for an Electron app: Feature, Entrypoint, Client, Host, and a typed edge between processes. Those names fit a UI with durable local state and an always-on backend. They do not fit a CLI or a library, and forcing them onto one is invention. What is universal is the four questions the nouns answer. Ask them of any repo:
+
+1. **Where does code run, and can an agent tell from the open file?** Each process, deployable, package, or layer is a boundary. The folder, the filename, or a directive in the file (`"use client"`, `server-only`) must tell an agent which boundary the code is in and what it may import, and a wrong import must fail. Shared code is a leaf: it imports nothing above it.
+2. **Which values outlive a request or a run, and who writes each one?** Stores, caches, tables, files on disk, config. One writer per value, behind a named interface. Where a value lives on two sides (a server row and a client cache), one side is authoritative and the other writes only through one named command.
+3. **Where two boundaries talk, is there one typed contract both sides import or generate from?** A change to the contract on one side must fail the build on the other. Not applicable to a single-process repo.
+4. **Which sets grow when someone contributes?** Routes, commands, jobs, registries, type mirrors, test lists. See open and closed sets below.
+
+The answers are the repo's own noun table: noun, its one job at runtime, where it lives, what it may import, how it is found. A web app's table looks like Dune's. A CLI's table has commands, one state store, and one adapter per external tool. Write the table the repo needs, not the one Dune had. The table describes the target. Each row where today's repo differs is a finding that cites the row.
+
+Two properties every table keeps:
+
+- **Reserved filenames make a folder a complete contribution.** Dropping a folder with the right filenames into the tree is the whole change. The build discovers it, startup validates it, nothing shared is edited. For a CLI: one file per command group that exports a register function, collected by a glob, or by a hand list plus a check that every file in the folder is in it.
+- **The side that owns durable state imports no presentation code.** Whatever accepts a write knows nothing about views or output formatting.
+
+### Open sets are discovered, closed sets are unions
+
+Two kinds of "list of things" exist.
+
+- An **open set** has independent contributors who should never collide: features, routes, commands, jobs. Discover them from reserved filenames. No shared edit, validated at build or start.
+- A **closed set** belongs to one owner and must be handled exhaustively: a feature's states, its commands, its event kinds. A discriminated union in one file, so the compiler forces every consumer to handle every variant. The shared edit is the point. Every runtime list or switch over a closed set fails the build when a variant is missing, through a `never` check or a `satisfies Record` check, never a default branch.
+
+Ask: can two agents add to this set in parallel without talking? If yes, discover it. If adding a variant must break every consumer that forgot it, union it.
+
+## 4. The ladder
+
+When an agent makes a mistake, encode the correction at the strongest level that works. These are the four levels pstack's `correct` skill climbs, numbered the same way, so a KISS finding and a `correct` fix name the same number.
+
+| Level | Mechanism | What happens when an agent skips it |
+| --- | --- | --- |
+| 1 | Architecture and ownership. One owner per value, one supported way per task, internals hidden so the wrong import fails, one source of truth, old ways deleted | It cannot be written |
+| 2 | Types that make the bad state unwritable. If bad code still compiles, a compiler flag, lint, or build check whose error names the file, type, or function to use instead | The check goes red |
+| 3 | A test of the behavior that fails when the behavior breaks. A project verification skill that drives the real app counts here | CI goes red |
+| 4 | Docs, agent rules, skills, review | Nothing. Agents forget them and busy humans skip them |
+
+Rules of use:
+
+- A human catching the same thing in review is the signal that a level is missing. The fix is a check or a redesign, not another comment on the PR.
+- Write the check before the cleanup. It stops the bleeding while the debt stays. If the pattern is already common, fail only on net-new instances.
+- Prefer the stack's own strictness first. Strict compiler flags are level 2 for free, but turning them on in a live repo is a ratchet, not a mechanical change.
+- Operator corrections during `apply`: a mistake class counts once it has happened twice. Record the first, act on the second. Assessment findings are already evidence of a pattern and do not wait for a second instance.
+
+## 5. Anti-patterns
+
+Things agents are reliably bad at. Each has a stable id that findings cite. The replacement is a shape, not a tool. The assessment names the tool for the repo in hand. When counting, a hit that is the replacement pattern itself (a cast right after a runtime check, an expect-error that asserts rejection, polling a vendor with backoff) is sanctioned; say how you decided.
+
+| Id | Pattern | Behavior | Replacement |
+| --- | --- | --- | --- |
+| `comments-as-bandaids` | A comment that justifies a workaround, or cites review feedback as the reason the code is shaped this way. A constraint the code cannot show may stay. A reference to a past PR or bug alone moves to the commit message | 5 | A better name, a type, a test, or an issue link in the commit. Enforced by a lint that allows license headers, public API docs, and `kiss-allow` lines, with `no-comments` on top for judgment |
+| `hand-edited-registry` | A list, switch, or registry file that grows per feature | 1 | Discovery for open sets, a union for closed sets |
+| `cross-boundary-import` | An import across a process or layer boundary the repo claims | 3 | Shared code, or the typed contract between sides |
+| `raw-transport` | HTTP, RPC, or subprocess calls scattered outside one adapter | 3 | One adapter per external system, behind named functions |
+| `second-writer` | A durable value written from more than one module | 2 | The owner's named command |
+| `god-file` | A file past the size budget (400 lines unless the repo sets its own; tests count) that several units of work edit or that no agent reads fully | 2 | A split along the repo's nouns, behind one writer if the file was one |
+| `timer-as-sync` | A sleep or timer used to wait for state the code could observe | 3 | Explicit events, readiness checks, request keys |
+| `type-escape-hatch` | `any`, double casts, `type: ignore`, untyped contracts | 3 | A real type, a branded id, a parse at the boundary |
+| `suppression-without-reason` | A disabled rule or suppression with no reason, issue link, expiry, or approval | 3 | Fix the code, or a Rule 5 exception |
+| `copy-and-modify` | `thing_v2`, `thing-new`, a parallel old and new path, a helper pasted into several files | 4 | Migrate callers, then delete the old copy in the same wave |
+| `tautological-test` | A test that would still pass if every function it calls returned nothing: no assertion on a literal result, only mock-call assertions, a constant restated, a fixture asserting itself | 3 | A test that calls the public surface and asserts a literal result |
+
+Dune also bans React's `useEffect` and fails CI on it. That ban belongs in a web repo's rule table, not in this list.
+
+## 6. Verification
+
+Guardrails prove the code is shaped right. Verification proves it works. Every serious project ships a verification skill: a CLI that launches the real app, drives it the way a user would, and captures evidence, plus a feature map that says what exists and how a user reaches it. Deterministic work lives in the CLI so no agent rebuilds it per session. The map is kept current by an automation, not by memory.
+
+Drift is an entrypoint (a route, a command, a job) with no map entry, or a map entry whose route, selector, or command no longer exists. Drift is a finding. The fix is pstack's `create-verification-skill` when no skill exists and `maintain-verification-skill` when one does. Both count as level 3.