principal-pi-skills 2.3.0 → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -107,11 +107,11 @@ to every output.
107
107
 
108
108
  ## Setup (pi)
109
109
 
110
- 1. `pi install git:github.com/mojomanyana/principal-pi-skills@v2.3.0` — registers the
110
+ 1. `pi install git:github.com/mojomanyana/principal-pi-skills@v2.3.1` — registers the
111
111
  skills and the `/principal-feature` + `/principal-bugfix` commands via the `pi`
112
112
  manifest. Install a tag, not a branch.
113
113
  2. Subagents need pi-mono's subagent extension (`examples/extensions/subagent`) and the
114
- agent definitions installed once: `npx principal-pi-agents install`. It copies real
114
+ agent definitions installed once: `npx -p principal-pi-skills principal-pi-agents install`. It copies real
115
115
  files into `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents` and refuses to overwrite
116
116
  anything it did not install.
117
117
  3. Without the extension, everything runs inline via the skills; the How column above
package/CHANGELOG.md CHANGED
@@ -6,6 +6,53 @@ Where review revealed a prior claim or design decision didn't hold up under clos
6
6
 
7
7
  ---
8
8
 
9
+ ## [2.3.1] — 2026-08-10
10
+
11
+ A defect-fix release. 2.3.0 shipped three defects that a second independent review found,
12
+ all of which made a documented command either do nothing or do damage. **If you installed
13
+ 2.3.0, upgrade** — its `principal-pi-workspace remove` can delete a directory you hand it.
14
+
15
+ **Fixed** — `principal-pi-workspace remove` deleted any path it was given. `git worktree
16
+ remove` fails for anything that is not a linked worktree — including your main checkout —
17
+ and the fallback was an unguarded recursive delete that printed `removed` and exited 0.
18
+ Verified destroying a directory of uncommitted work. The path comes from an LLM following a
19
+ contract, so "the caller passes a sane argument" was never a safe assumption. It now refuses
20
+ anything that is neither a worktree of the repository nor a `ppw-*` snapshot under the temp
21
+ directory.
22
+
23
+ **Fixed** — both documented `npx` invocations resolved to nonexistent packages.
24
+ `npx principal-pi-agents install` and `npx principal-pi-workspace create` ask npm for a
25
+ *package* of that name; the bins belong to `principal-pi-skills`. Both returned E404. The
26
+ consequence was silent rather than loud: the agent install wrote nothing, so workflows
27
+ degraded to inline self-review with no attributable error, and every review/debug agent got
28
+ E404 where a disposable workspace should have been — leaving the workspace-isolation feature
29
+ inert for every installed user while the contracts forbade verifying in the caller's tree.
30
+ The correct form is `npx -p principal-pi-skills <bin>`, now used in all 14 files that carried
31
+ it.
32
+
33
+ **Fixed** — the agent installer's ownership record. Files that were already byte-identical
34
+ were skipped without being recorded in the manifest, so `uninstall` was a permanent no-op for
35
+ them. `check` also verified only what the current invocation would install, reporting green
36
+ while previously-installed generic aliases rotted.
37
+
38
+ **Fixed** — two `debug` fixtures shipped already-fixed code. D1's `reduce` had gained an
39
+ initial value and an empty-cart test, so the **critical** D1 scenario could not reproduce the
40
+ failure its checklist grades; A5's parser had gained the guard its scenario asks the model to
41
+ add, so it could not fail. Both restored. The corruption reached git through a blanket
42
+ `git add -A` that swept up fixtures a local `vitest` run had rewritten — which also tracked
43
+ two `node_modules/.vite` caches that churn the fixture source hash. Those are untracked and
44
+ `node_modules/` is now ignored.
45
+
46
+ **Changed** — `debug` and `review` scorecard cells are **withdrawn** pending a re-run.
47
+ debug's were measured against the corrupted fixtures; review's contract changed in this
48
+ release. A withdrawn cell publishes nothing rather than a number that measured something
49
+ else.
50
+
51
+ **Note on verification.** 2.3.0's bins were reported as "verified working from the published
52
+ artifact". That check invoked `./node_modules/.bin/<name>`, which is a different resolution
53
+ path from the documented command — the same class of error as testing a CLI by importing its
54
+ module. The install tests now exercise the documented invocation.
55
+
9
56
  ## [2.3.0] — 2026-08-09
10
57
 
11
58
  The release that made the installed product real: namespaced commands and agents, generated
@@ -59,8 +106,8 @@ documented command silently do nothing or do damage:
59
106
 
60
107
  - **Both CLIs were no-ops when installed.** The main-module guard compared
61
108
  `import.meta.url` against an unresolved `process.argv[1]`. npm links bins as symlinks, so
62
- for every real user the comparison was false: `npx principal-pi-agents install` printed
63
- nothing and exited 0, and so did `npx principal-pi-workspace create`. Exit 0 with no output
109
+ for every real user the comparison was false: `npx -p principal-pi-skills principal-pi-agents install` printed
110
+ nothing and exited 0, and so did `npx -p principal-pi-skills principal-pi-workspace create`. Exit 0 with no output
64
111
  reads as success, so the agents never installed and debug/review got an empty path where a
65
112
  worktree should be — silently losing the isolation this release is built around.
66
113
  - **`snapshot-workspace` dropped its own subcommand** whenever `--repo` was absent: the
@@ -89,7 +136,7 @@ in every developer test and broken for every user.
89
136
  **Fixed** — the workspace helper is reachable from an installed package. The contracts said
90
137
  `node scripts/snapshot-workspace.mjs`, a relative path that resolves in this checkout and
91
138
  nowhere else; debug and review would have found no helper and fallen back to a read-only
92
- diagnosis for the wrong reason. It is now a bin entry, `npx principal-pi-workspace`. The
139
+ diagnosis for the wrong reason. It is now a bin entry, `npx -p principal-pi-skills principal-pi-workspace`. The
93
140
  packaging step is what surfaced it.
94
141
 
95
142
  **Removed** — `docs/superpowers/` (a completed cleanup plan and its design spec, referenced
package/README.md CHANGED
@@ -50,8 +50,8 @@ around.
50
50
  | `architect` | System design from measurable drivers; significant or irreversible technical choices. The decision record is a section of the output, not a separate artifact | inline | 1088 |
51
51
  | `plan` | A task turned into ordered steps and per-step specs a builder can execute without making load-bearing decisions. Writes no code | subagent (`agents/principal-plan.md`, 1360) or inline | 1150 |
52
52
  | `build` | Test-first implementation — code proven by a test you watched fail | inline | 968 |
53
- | `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1315) or inline | 1287 |
54
- | `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1333) or inline | 1206 |
53
+ | `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1317) or inline | 1289 |
54
+ | `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1335) or inline | 1208 |
55
55
  | `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 1895 |
56
56
 
57
57
  Routing between them belongs to the orchestrator, not to a skill — there is deliberately no
@@ -97,8 +97,8 @@ docs/demos/ the chains running end to end, repo-verifi
97
97
  `agents.ts` into `~/.pi/agent/extensions/subagent/`), then install the agent definitions:
98
98
 
99
99
  ```
100
- npx principal-pi-agents install # → ${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents
101
- npx principal-pi-agents check # verify they are present and current
100
+ npx -p principal-pi-skills principal-pi-agents install # → ${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents
101
+ npx -p principal-pi-skills principal-pi-agents check # verify they are present and current
102
102
  ```
103
103
 
104
104
  It installs `principal-plan`, `principal-review` and `principal-debug` as **real files,
@@ -193,13 +193,18 @@ follow-up rather than a published column in the current round.
193
193
  |---|---|---|---|
194
194
  | architect | 13/14 · 93% | **14/14 · 100% SHIP** | — *(deferred)* |
195
195
  | build | **9/9 · 100% SHIP** | **9/9 · 100% SHIP** | — *(deferred)* |
196
- | debug | 9/11 · 82% | 10/11 · 91% | — *(deferred)* |
196
+ | debug ✗ | — *(withdrawn)* | — *(withdrawn)* | — *(deferred)* |
197
197
  | decide | **12/12 · 100% SHIP** | **12/12 · 100% SHIP** | — *(deferred)* |
198
198
  | git-ops | 18/19 · 95% | **19/19 · 100% SHIP** | — *(deferred)* |
199
199
  | plan | 8/12 · 67% | **12/12 · 100% SHIP** | — *(deferred)* |
200
- | review | 20/21 · 95% | 19/21 · 90% | — *(deferred)* |
200
+ | review ✗ | — *(withdrawn)* | — *(withdrawn)* | — *(deferred)* |
201
201
 
202
- **Five of seven skills ship on at least one model.** `decide` is new to that list — it
202
+ ✗ `debug`'s cells are **withdrawn**: a review found its D1 and A5 fixtures shipped
203
+ already-fixed code, so a critical scenario could not reproduce its own failure and another
204
+ could not fail. The fixtures are restored and a re-run is pending; the previous 9/11 and
205
+ 10/11 were measured against them and should not be quoted.
206
+
207
+ **Four of the six remaining skills ship on at least one model.** `decide` is new to that list — it
203
208
  previously held at 92% on every model, failing exactly one boundary scenario each, and shipped
204
209
  nowhere; it is now 12/12 on both. `build` went 7/9 → 9/9 on DeepSeek.
205
210
 
package/agents/debug.md CHANGED
@@ -32,7 +32,7 @@ unknown one; the harder the bug, the stricter the loop.
32
32
  file:line because <observed evidence> implies <cause>"; test the cheapest first.
33
33
  4. **Probe — in a workspace you own.** One smallest experiment per hypothesis: a log line,
34
34
  an assertion, a narrowed test. One change at a time. Probing edits code, so do it in a
35
- disposable copy, never the caller's checkout: `npx principal-pi-workspace create`
35
+ disposable copy, never the caller's checkout: `npx -p principal-pi-skills principal-pi-workspace create`
36
36
  prints a throwaway worktree holding their exact working state (minus anything git
37
37
  ignores). Work there, then `remove` it. That keeps "probes are temporary" structurally,
38
38
  which nobody manages by hand under a failing build.
@@ -32,7 +32,7 @@ unknown one; the harder the bug, the stricter the loop.
32
32
  file:line because <observed evidence> implies <cause>"; test the cheapest first.
33
33
  4. **Probe — in a workspace you own.** One smallest experiment per hypothesis: a log line,
34
34
  an assertion, a narrowed test. One change at a time. Probing edits code, so do it in a
35
- disposable copy, never the caller's checkout: `npx principal-pi-workspace create`
35
+ disposable copy, never the caller's checkout: `npx -p principal-pi-skills principal-pi-workspace create`
36
36
  prints a throwaway worktree holding their exact working state (minus anything git
37
37
  ignores). Work there, then `remove` it. That keeps "probes are temporary" structurally,
38
38
  which nobody manages by hand under a failing build.
@@ -66,7 +66,7 @@ ships is a failed review.
66
66
  path. The strongest check is often destructive — revert the fix and confirm the
67
67
  regression test goes red, break an input and watch the guard fire — so do all of it in a
68
68
  disposable copy, never in the caller's checkout:
69
- `npx principal-pi-workspace create` prints a throwaway worktree carrying their
69
+ `npx -p principal-pi-skills principal-pi-workspace create` prints a throwaway worktree carrying their
70
70
  exact working state (staged, unstaged, untracked, minus anything git ignores). Work
71
71
  there, then `remove` it. The caller must find their tree byte-for-byte as they left it —
72
72
  they are still working in it, and a file you "just" reverted is one they may be editing.
package/agents/review.md CHANGED
@@ -66,7 +66,7 @@ ships is a failed review.
66
66
  path. The strongest check is often destructive — revert the fix and confirm the
67
67
  regression test goes red, break an input and watch the guard fire — so do all of it in a
68
68
  disposable copy, never in the caller's checkout:
69
- `npx principal-pi-workspace create` prints a throwaway worktree carrying their
69
+ `npx -p principal-pi-skills principal-pi-workspace create` prints a throwaway worktree carrying their
70
70
  exact working state (staged, unstaged, untracked, minus anything git ignores). Work
71
71
  there, then `remove` it. The caller must find their tree byte-for-byte as they left it —
72
72
  they are still working in it, and a file you "just" reverted is one they may be editing.
package/debug/SKILL.md CHANGED
@@ -23,7 +23,7 @@ unknown one; the harder the bug, the stricter the loop.
23
23
  file:line because <observed evidence> implies <cause>"; test the cheapest first.
24
24
  4. **Probe — in a workspace you own.** One smallest experiment per hypothesis: a log line,
25
25
  an assertion, a narrowed test. One change at a time. Probing edits code, so do it in a
26
- disposable copy, never the caller's checkout: `npx principal-pi-workspace create`
26
+ disposable copy, never the caller's checkout: `npx -p principal-pi-skills principal-pi-workspace create`
27
27
  prints a throwaway worktree holding their exact working state (minus anything git
28
28
  ignores). Work there, then `remove` it. That keeps "probes are temporary" structurally,
29
29
  which nobody manages by hand under a failing build.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "principal-pi-skills",
3
- "version": "2.3.0",
3
+ "version": "2.3.1",
4
4
  "description": "Skill framework for principal-level software engineering: seven dual-use skills (decide, architect, plan, build, review, debug, git-ops) that work unedited as loaded skills or as subagent system prompts.",
5
5
  "license": "MIT",
6
6
  "author": "Nemanja Alavanja",
@@ -30,7 +30,7 @@ reasoning, so it cannot be surprised by it. When review runs inline, say so in t
30
30
  confident the diagnosis was.
31
31
  4. **Review** — `principal-review` agent, or the `review` skill inline. It verifies the
32
32
  regression test fails before the fix and passes after — a destructive check, so it
33
- belongs in a disposable workspace (`npx principal-pi-workspace`), never in this
33
+ belongs in a disposable workspace (`npx -p principal-pi-skills principal-pi-workspace`), never in this
34
34
  checkout. A verdict without that check is UNVERIFIED, and UNVERIFIED is not an approval;
35
35
  when review reports `Workspace: none`, treat it as a gap to close rather than a verdict
36
36
  to accept.
@@ -27,7 +27,7 @@ reasoning, so it cannot be surprised by it. When review runs inline, say so in t
27
27
  4. **Review** — `principal-review` agent, or the `review` skill inline. Pass the
28
28
  implementation report. Review runs the tests before any verdict; a verdict without a test
29
29
  run is UNVERIFIED, and UNVERIFIED is not an approval. Review's destructive checks belong
30
- in a disposable workspace (`npx principal-pi-workspace`), never in this checkout —
30
+ in a disposable workspace (`npx -p principal-pi-skills principal-pi-workspace`), never in this checkout —
31
31
  when it reports `Workspace: none`, expect UNVERIFIED and treat that as a gap to close,
32
32
  not a verdict to accept.
33
33
  5. **Repair loop** — if the verdict is CHANGES-REQUESTED, return to Build with the findings,
package/review/SKILL.md CHANGED
@@ -59,7 +59,7 @@ ships is a failed review.
59
59
  path. The strongest check is often destructive — revert the fix and confirm the
60
60
  regression test goes red, break an input and watch the guard fire — so do all of it in a
61
61
  disposable copy, never in the caller's checkout:
62
- `npx principal-pi-workspace create` prints a throwaway worktree carrying their
62
+ `npx -p principal-pi-skills principal-pi-workspace create` prints a throwaway worktree carrying their
63
63
  exact working state (staged, unstaged, untracked, minus anything git ignores). Work
64
64
  there, then `remove` it. The caller must find their tree byte-for-byte as they left it —
65
65
  they are still working in it, and a file you "just" reverted is one they may be editing.
@@ -108,7 +108,13 @@ function install({ dir, wanted, force }) {
108
108
 
109
109
  let wrote = 0;
110
110
  for (const a of actions) {
111
- if (a.kind === "current") continue;
111
+ if (a.kind === "current") {
112
+ // Record it anyway. Ownership is what `uninstall` removes by, and a file that was
113
+ // already byte-identical (a re-install, or a user who copied it in by hand) would
114
+ // otherwise never enter the manifest — making uninstall a permanent no-op for it.
115
+ manifest.files[a.file] ??= sha(readFileSync(join(dir, a.file), "utf8"));
116
+ continue;
117
+ }
112
118
  if (a.kind === "refuse" && !force) continue;
113
119
  // Remove first. Writing to a path that is a symlink writes THROUGH it, editing whatever
114
120
  // it points at — which is why plan() refuses links at all. --force means "replace the
@@ -131,7 +137,12 @@ function check({ dir, wanted }) {
131
137
  console.error(`✗ ${dir} does not exist — run \`principal-pi-agents install\``);
132
138
  return 1;
133
139
  }
134
- const { actions } = plan(dir, wanted);
140
+ // Check everything we own, not just what this invocation would install. Otherwise a
141
+ // `check` without --with-generic-aliases reports green while previously-installed generic
142
+ // aliases sit stale — the drift check missing exactly the files it is responsible for.
143
+ const owned = Object.keys(readManifest(dir).files);
144
+ const all = [...new Set([...wanted, ...owned])].filter((f) => existsSync(join(ROOT, "agents", f)));
145
+ const { actions } = plan(dir, all);
135
146
  const bad = actions.filter((a) => a.kind !== "current");
136
147
  for (const a of bad) {
137
148
  console.error(`✗ ${a.file}: ${a.kind === "install" ? "not installed" : a.kind === "update" ? "out of date" : a.why}`);
@@ -39,12 +39,14 @@
39
39
  import { execFileSync } from "node:child_process";
40
40
  import { mkdtempSync, mkdirSync, copyFileSync, symlinkSync, readlinkSync, lstatSync, existsSync, rmSync, writeFileSync, realpathSync } from "node:fs";
41
41
  import { tmpdir } from "node:os";
42
- import { join, dirname, resolve } from "node:path";
42
+ import { join, dirname, resolve, basename } from "node:path";
43
43
  import { fileURLToPath } from "node:url";
44
44
 
45
45
  const git = (args, cwd, opts = {}) =>
46
46
  execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, ...opts });
47
47
 
48
+ export const SNAPSHOT_PREFIX = "ppw-";
49
+
48
50
  export class SnapshotError extends Error {}
49
51
 
50
52
  /**
@@ -70,7 +72,7 @@ export function createSnapshot(repo = process.cwd()) {
70
72
  throw new SnapshotError("repository has no commits yet — nothing to snapshot");
71
73
  }
72
74
 
73
- const path = mkdtempSync(join(tmpdir(), "ppw-"));
75
+ const path = mkdtempSync(join(tmpdir(), SNAPSHOT_PREFIX));
74
76
  rmSync(path, { recursive: true, force: true }); // git worktree add wants a non-existent path
75
77
 
76
78
  const cleanup = () => {
@@ -147,13 +149,38 @@ function main(argv) {
147
149
  return 2;
148
150
  }
149
151
  const root = git(["rev-parse", "--show-toplevel"], repo).trim();
152
+ const target = resolve(arg);
153
+
154
+ // Refuse anything this tool did not create. The previous version fell back to an
155
+ // unguarded recursive delete whenever `git worktree remove` failed — and it fails for
156
+ // ANY path that is not a linked worktree, including the user's main checkout. A stale
157
+ // or mistyped path therefore destroyed uncommitted work and printed "removed".
158
+ // An LLM following a contract supplies these paths, so "the caller passes a sane
159
+ // argument" is not an assumption this can make.
160
+ const isOurs = basename(target).startsWith(SNAPSHOT_PREFIX) && target.startsWith(realpathSync(tmpdir()));
161
+ let registered = false;
162
+ try {
163
+ registered = git(["worktree", "list", "--porcelain"], root)
164
+ .split("\n")
165
+ .some((l) => l.startsWith("worktree ") && resolve(l.slice(9)) === target);
166
+ } catch {
167
+ /* not a repo we can query; fall through to the ownership check */
168
+ }
169
+ if (!registered && !isOurs) {
170
+ console.error(`✗ refusing to remove ${target}`);
171
+ console.error(` It is neither a worktree of this repository nor a snapshot this tool created`);
172
+ console.error(` (${SNAPSHOT_PREFIX}* under ${tmpdir()}). Delete it yourself if that is what you meant.`);
173
+ return 1;
174
+ }
175
+
150
176
  try {
151
- git(["worktree", "remove", "--force", arg], root, { stdio: "ignore" });
177
+ git(["worktree", "remove", "--force", target], root, { stdio: "ignore" });
152
178
  } catch {
153
- if (existsSync(arg)) rmSync(arg, { recursive: true, force: true });
179
+ // Only reachable for a path we have already proven we own.
180
+ if (existsSync(target)) rmSync(target, { recursive: true, force: true });
154
181
  }
155
182
  git(["worktree", "prune"], root, { stdio: "ignore" });
156
- console.log(`removed ${arg}`);
183
+ console.log(`removed ${target}`);
157
184
  return 0;
158
185
  }
159
186
  if (cmd === "prune") {