principal-pi-skills 2.3.1 → 3.0.0

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
@@ -72,9 +72,9 @@ up with a transition that silently does nothing.
72
72
  Typical spines (available as prompt templates):
73
73
 
74
74
  - Feature (`/principal-feature <task>`): plan → build (inline) → review → git-ops
75
- (inline). Enter `architect`/`decide` first when the call is architectural or still
75
+ finish (inline). Enter `architect`/`decide` first when the call is architectural or still
76
76
  contested.
77
- - Bug (`/principal-bugfix <symptom>`): debug → build (inline) → review → git-ops (inline).
77
+ - Bug (`/principal-bugfix <symptom>`): debug → build (inline) → review → git-ops finish (inline).
78
78
  If debug's note says design flaw, stop and surface it.
79
79
  - Either spine, when the subagent tool is missing or reports an unknown agent: run that
80
80
  phase's skill inline instead and say so in the digest. Fall back on *absence* only —
@@ -83,6 +83,17 @@ Typical spines (available as prompt templates):
83
83
  - Tiny change: build → git-ops, both inline — every contract carries a Right-sizing
84
84
  rule; don't add ceremony the file itself would refuse.
85
85
 
86
+ ### Workflow assurance (v3)
87
+
88
+ Both namespaced prompts parse and persist `lean|standard|critical`; standard is the default,
89
+ and omitted flags preserve v2 invocation. Routing still belongs here/the prompt, never a new
90
+ skill. The shared controller contract is generated from `contracts/workflows.md.tmpl`; the
91
+ hash-chained state and gates live in `scripts/assurance-state.mjs`, outside the product tree.
92
+ Lean/standard retain the complete inline baseline. Critical requires owned isolation and
93
+ fresh plan/review contexts; absence returns `BLOCKED_CRITICAL_ASSURANCE`, never inline
94
+ self-review presented as independent. Build remains the sole source writer and Git-Ops offers
95
+ merge locally, push/open PR, or keep the branch after fresh evidence.
96
+
86
97
  A delegated step returning `BLOCKED` stops the chain: surface its one question to the
87
98
  user; don't answer it yourself and keep going.
88
99
 
@@ -94,7 +105,8 @@ user; don't answer it yourself and keep going.
94
105
  copies — but 74–84% of each pair is identical, and that shared majority is where they used
95
106
  to drift.
96
107
 
97
- All three are generated from `contracts/<name>.md.tmpl`. Change shared behavior ONCE, there,
108
+ All three are generated from `contracts/<name>.md.tmpl`. The two namespaced workflows are
109
+ likewise generated from `contracts/workflows.md.tmpl`. Change shared behavior ONCE, there,
98
110
  then `npm run generate`. Editing a generated file directly is reverted by the next run and
99
111
  fails `npm run generate:check` in CI. Hand-mirroring used to be a reviewer's job and was
100
112
  never reliably done — which is how the D-scenarios once measured a contract no subagent had
@@ -107,12 +119,19 @@ to every output.
107
119
 
108
120
  ## Setup (pi)
109
121
 
110
- 1. `pi install git:github.com/mojomanyana/principal-pi-skills@v2.3.1` — registers the
122
+ 1. `pi install git:github.com/mojomanyana/principal-pi-skills@v3.0.0` — the current
123
+ published release, and the tag this source tree's manifest matches. `standard` is the
124
+ default assurance profile, so a v2 invocation keeps working unchanged. It registers the
111
125
  skills and the `/principal-feature` + `/principal-bugfix` commands via the `pi`
112
126
  manifest. Install a tag, not a branch.
113
- 2. Subagents need pi-mono's subagent extension (`examples/extensions/subagent`) and the
114
- agent definitions installed once: `npx -p principal-pi-skills principal-pi-agents install`. It copies real
127
+ 2. Subagents need pi-mono's subagent extension (`examples/extensions/subagent`, which ships
128
+ inside pi itself — nothing to vendor) and the agent definitions installed once:
129
+ `npx -p principal-pi-skills principal-pi-agents install`. It copies real
115
130
  files into `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents` and refuses to overwrite
116
131
  anything it did not install.
132
+ A delegated agent runs on the pi config's `defaultProvider`/`defaultModel`, **not** the
133
+ `--provider`/`--model` you gave the parent: the extension forwards `--model` only when an
134
+ agent's frontmatter names one, and these deliberately do not. If delegations fail to
135
+ authenticate while the parent session is fine, that mismatch is the reason.
117
136
  3. Without the extension, everything runs inline via the skills; the How column above
118
137
  simply collapses to "inline".
package/CHANGELOG.md CHANGED
@@ -6,6 +6,135 @@ Where review revealed a prior claim or design decision didn't hold up under clos
6
6
 
7
7
  ---
8
8
 
9
+ ## [3.0.0] — 2026-08-20
10
+
11
+ **Added — risk-adaptive assurance profiles on the two existing workflow spines.** `standard`
12
+ remains the default Option B behavior; `lean` preserves the tiny/reversible path; explicit
13
+ `critical` (and `high`) activates selected Option C controls. `--critical-scope` accepts an
14
+ entire run, task IDs, or path globs. Natural-language critical/escalation requests map to the
15
+ same state. No skill or public agent name was added: the set remains decide, architect, plan,
16
+ build, review, debug, git-ops.
17
+
18
+ **Added — deterministic assurance state outside the product tree.**
19
+ `principal-pi-assurance` validates versioned run-state/task-packet/evidence-receipt schemas, appends a
20
+ SHA-256-linked JSONL event log, atomically derives a snapshot, enforces legal transitions and
21
+ explicit downgrade, matches critical scope, detects stale evidence after source changes, and
22
+ returns `BLOCKED_CRITICAL_ASSURANCE` with missing controls. State is under git's common
23
+ directory (XDG state outside git), so Plan/Review/Debug retain their read-only/disposable
24
+ workspace contracts and Build remains the only durable source writer.
25
+
26
+ **Changed — critical workflow controls.** Consequential design approval includes validation,
27
+ observability, rollback, abort, and one-way doors; plans carry authority and independently
28
+ verifiable task packets; an independent plan critique precedes Build; an owned isolated
29
+ branch worktree is mandatory; each task receives separate fresh specification and
30
+ quality/security reviews rooted at the canonical writer checkout; a final fresh whole-change review
31
+ follows all task evidence. Mid-run escalation freezes base/head/candidate-tree and backfills exact
32
+ matching receipts before more source writes. Approved replans explicitly supersede immutable stale
33
+ packets rather than silently rebinding them.
34
+ Irreversible/external effects require just-in-time user approval. Critical never degrades to
35
+ inline self-review when fresh-context infrastructure is absent.
36
+
37
+ **Changed — standard and repair/finish discipline.** Standard remains the normal spine with
38
+ vertical slices, dependency/interface preflight, one writer, milestone/final review,
39
+ evidence-based finding adjudication, fresh verification, and an explicit finish choice.
40
+ Build repair mode consumes accepted finding IDs one at a time. Git-Ops finish mode offers
41
+ merge locally, push/open PR, or keep, runs a pre-operation readiness gate, and persists final
42
+ branch/head/tree before the completion gate; discard remains explicit. Tiny work does not acquire
43
+ architecture machinery unless the user explicitly selected critical.
44
+
45
+ **Changed — workflow and dual-use generation.** Both namespaced prompts now render from
46
+ `contracts/workflows.md.tmpl`, with a test proving their assurance rules are identical.
47
+ Plan/Review/Debug continue to render skill, namespaced agent, and generic alias from their
48
+ existing templates. All capability ceilings are unchanged.
49
+
50
+ **Added — free assurance coverage.** Unit tests cover parsing/defaults, policy escalation,
51
+ explicit downgrade, scope matching, legal events, missing-control blocks, evidence freshness,
52
+ review-context/workspace/tree independence, JIT approval, readiness/finalization, event-log
53
+ integrity, Draft 2020-12/runtime schema parity, and branch-attached workspaces. The E2E harness now defines standard/critical ×
54
+ feature/bugfix × subagents present/absent; critical/absent asserts a clean block. Seven `E1`
55
+ skill-harness scenarios plus a Git-Ops stale-receipt negative are prepared but deliberately not
56
+ model-run; no skill-harness/live E2E validation was authorized, so v2.4 measurements are historical
57
+ and v3 publishes no model score yet.
58
+
59
+ **Fixed — npm 12 pack metadata compatibility.** npm 12 changed `npm pack --json` from an
60
+ array to a package-keyed object, which made seven clean-home install tests fail before this
61
+ work began. Pack checks, install tests, and E2E now normalize both shapes and still fail on
62
+ empty/malformed metadata.
63
+
64
+ **Fixed — the `v2.4.0` git tag never existed.** 2.4.0 was published to npm on 2026-08-16, but
65
+ no tag was cut, so `pi install git:github.com/mojomanyana/principal-pi-skills@v2.4.0` — the
66
+ immutable install command README and AGENTS.md both printed, and the one thing this project
67
+ tells users to prefer over a moving branch — resolved to nothing for four days. The tag is
68
+ backfilled at the release commit it always belonged to (`4dece8c`), and tagging now precedes
69
+ publishing. It is the same failure as 2.3.1's 404'ing npx invocations: a documented command
70
+ nothing executed.
71
+
72
+ **Changed — released with the measurement gap stated, not closed.** `3.0.0` ships statically
73
+ verified and unmeasured, and every document that could be read as a claim now says so at the
74
+ point of reading: the README install step, `docs/ASSURANCE.md`, `docs/validation/VALIDATION.md`,
75
+ and the handoff verdict. All 101 skill-harness findings are exempt-stale against the v3 text —
76
+ that is the honest state of a v3 cell, not a passing one. The authorized two-model wave and the
77
+ live eight-cell E2E remain the work that would replace the historical v2.4 board with a v3 one.
78
+
79
+ **Changed — `ajv`/`ajv-formats` are the first devDependencies.** The Draft 2020-12 parity test
80
+ needs a real validator. Runtime install stays dependency-free — they are not in the pack
81
+ allowlist — but `npm test` in a fresh checkout now requires `npm ci` first, where before it ran
82
+ on a bare clone.
83
+
84
+ ---
85
+
86
+ ## [2.4.0] — 2026-08-17
87
+
88
+ **Added** — every skill now declares an `allowed-tools` capability ceiling, which
89
+ [pi-daddy](https://github.com/mojomanyana/pi-daddy) enforces as a real `--tools` allowlist in a
90
+ separate OS process. Four are read-only (`decide`, `architect`, `plan`, plus nothing else that can
91
+ modify anything); three hold `bash` (`review`, `debug`, `git-ops`); `build` alone holds `edit` and
92
+ `write`. Reasoning and the rejected alternative: [docs/DECISION-capability-ceilings.md](docs/DECISION-capability-ceilings.md).
93
+
94
+ **Decided** — `decide`, `architect` and `plan` return their document as text rather than writing a
95
+ file. pi-daddy governs tools and never paths, so `Write(docs/**)` is not expressible — verified in
96
+ its source, where a path-scoped entry yields *zero* capabilities plus a refusal flag rather than a
97
+ broad write. Granting these three a real `write` would have meant unrestricted filesystem access in
98
+ order to produce a document their own bodies already define as a message, and would have emptied the
99
+ read-only tier entirely. `build/SKILL.md` already said this: *"You are the only phase that writes
100
+ durably. Plan reads."*
101
+
102
+ **Fixed** — `agents/debug.md` declared no `tools:` key, and in pi-subagents an absent `tools:` means
103
+ the *full default toolset*. The debug twin was silently the most powerful of the three while `plan`
104
+ and `review` declared theirs. It now declares `read, grep, find, ls, bash` in both spellings.
105
+
106
+ **Corrected** — the integration handoff proposed `Read, Grep, Glob` for `review` on the grounds that
107
+ its description says *"Reports findings; never edits"*. That string appears nowhere in this
108
+ repository, and `review/SKILL.md:58-68` requires the opposite: it creates a disposable worktree and
109
+ runs the tests in it. Denying `bash` would have made every review return `UNVERIFIED` — which
110
+ review's own body calls "not a soft approve". The handoff's `Glob` is also unknown to pi, whose
111
+ built-ins are `bash, edit, edit-diff, find, grep, ls, parallel, read, write`; six of the seven
112
+ proposed ceilings carried it, and would have been refused as written.
113
+
114
+ **Fixed upstream** — declaring `allowed-tools` initially took `npm run lint:skills` from 2 stale
115
+ findings to 22, because skill-harness hashed the whole `SKILL.md` and so charged a paid re-wave for
116
+ a frontmatter key no graded run can observe. Reported and fixed in skill-harness 0.8.0, which
117
+ digests a prompt document as body plus model-visible frontmatter. `restamp` then upgraded the
118
+ committed runs — 202 examined, 18 upgraded, 122 correctly unprovable — bringing this branch back to
119
+ the pre-change baseline of 57 findings, 2 stale.
120
+
121
+ **Added** — a fourth severity in `scripts/lint-skills.mjs`, declared in
122
+ `docs/validation/record-artifacts.txt`: a staleness finding whose *record* cannot be proven but
123
+ whose *stimulus* is vouched for by a checkable assertion. It covers the two remaining `debug/A6`
124
+ findings, which predate this work and fail on `main` today: a `vitest` cache left by a hand
125
+ authoring run was hashed into the 2026-08-10 fixture digests and no longer exists, so no digest of
126
+ those runs can be proven — while `git diff` shows the tracked stimulus byte-identical and `rescore`
127
+ reproduces the published grades exactly, 0 verdicts moved.
128
+
129
+ Deliberately not folded into `unpublished-cells.txt`: that file covers cells with no claim to
130
+ protect, and these publish. Entries here match on three tokens (cell, model, and the source vouched
131
+ for) rather than two, so one cannot swallow a different kind of drift on the same cell — verified: a
132
+ one-word body edit to `debug/SKILL.md` still blocks. Dead entries fail the build, so a re-run
133
+ retires the exemption rather than quietly extending it. It is the weakest of the four severities and
134
+ says so: a human standing where a measurement used to.
135
+
136
+ ---
137
+
9
138
  ## [2.3.1] — 2026-08-10
10
139
 
11
140
  A defect-fix release. 2.3.0 shipped three defects that a second independent review found,
@@ -43,10 +172,14 @@ add, so it could not fail. Both restored. The corruption reached git through a b
43
172
  two `node_modules/.vite` caches that churn the fixture source hash. Those are untracked and
44
173
  `node_modules/` is now ignored.
45
174
 
46
- **Changed** — `debug` and `review` scorecard cells are **withdrawn** pending a re-run.
175
+ **Changed** — `debug` and `review` scorecard cells were **withdrawn** pending a re-run.
47
176
  debug's were measured against the corrupted fixtures; review's contract changed in this
48
177
  release. A withdrawn cell publishes nothing rather than a number that measured something
49
- else.
178
+ else. **That re-run has since landed** (`release-3c`, after this version was published):
179
+ `debug` 9/11 on DeepSeek and 11/11 · SHIP on GLM, `review` 21/21 · SHIP on both. Both cells
180
+ are published again, which takes the board to all seven skills shipping on at least one
181
+ model — see `docs/validation/VALIDATION.md` for the current numbers, which this entry does
182
+ not restate.
50
183
 
51
184
  **Note on verification.** 2.3.0's bins were reported as "verified working from the published
52
185
  artifact". That check invoked `./node_modules/.bin/<name>`, which is a different resolution
package/README.md CHANGED
@@ -12,7 +12,9 @@ The set is built for **one principal engineer steering at a high level while ski
12
12
  subagents do the work.** Two properties follow, and every design choice below serves them:
13
13
  **delegable trust** — an output carries the evidence needed to verify it without redoing
14
14
  the work — and **cheap iteration** — a defect found is a defect fixed, not documented
15
- around.
15
+ around. v3 adds risk-adaptive assurance to the two workflows: `standard` stays the default,
16
+ while explicit `critical` activates selected isolation, independent-review, evidence, and
17
+ approval controls without creating another skill suite.
16
18
 
17
19
  ## Three constraints
18
20
 
@@ -26,11 +28,13 @@ around.
26
28
  plain-text tags (`[ONE-WAY]`, `[BLOCKER]`) instead of an emoji schema, no aphorisms
27
29
  doing load-bearing work, no personas, no required reading in reference files.
28
30
  3. **Token economics.** Budgets stated as decisions rather than aspirations: **skills
29
- ≤ ~1400 words**, with **`git-ops` an accepted exception at ~1900** — the safety-critical
31
+ ≤ ~1400 words**, with **`git-ops` an accepted exception at ~2000** — the safety-critical
30
32
  operator carries the most arming, and validated behavior outweighs a budget.
31
33
  Both ceilings have moved once, each buying a fix rather than more prose. `git-ops` went
32
34
  1320 → 1900 to reconcile the protected-branch and secret-purge policies and redact secret
33
- findings. The skill budget went 1100 → 1250 → 1400 for a lesson this framework
35
+ findings, then 1900 → 2000 for v3 finish mode's fresh-evidence gate and explicit
36
+ merge/PR/keep choice. No safety playbook was trimmed to make room. The skill budget went
37
+ 1100 → 1250 → 1400 for a lesson this framework
34
38
  paid for: *every arming needs its governor in the same breath*. An absolute is cheap to
35
39
  write — "one caller → inline it", "every catch logs and changes state" — and wrong in real
36
40
  cases, and each wrong absolute produced a measured over-refusal. A rule plus the cases it
@@ -46,13 +50,13 @@ around.
46
50
 
47
51
  | Skill | What it does | How it runs | Words |
48
52
  |---|---|---|---|
49
- | `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline | 847 |
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
- | `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
- | `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`, 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
- | `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 1895 |
53
+ | `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline | 860 |
54
+ | `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 | 1142 |
55
+ | `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`, 1467) or inline | 1257 |
56
+ | `build` | Test-first implementation — code proven by a test you watched fail | inline | 1162 |
57
+ | `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1392) or inline | 1364 |
58
+ | `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1395) or inline | 1261 |
59
+ | `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 1997 |
56
60
 
57
61
  Routing between them belongs to the orchestrator, not to a skill — there is deliberately no
58
62
  routing skill spending context to say "pick a skill". [AGENTS.md](./AGENTS.md) is that
@@ -65,15 +69,20 @@ you; point your orchestrator at it deliberately.
65
69
  <skill>/SKILL.md the interactive contract — nothing else is required reading
66
70
  agents/principal-{plan,review,debug}.md subagent definitions the workflows delegate to
67
71
  agents/{plan,review,debug}.md deprecated generic-name aliases
68
- contracts/{plan,review,debug}.md.tmpl the SOURCE for all of the above — edit here, run `npm run generate`
69
- prompts/principal-{feature,bugfix}.md the two workflow spines (/feature, /bugfix are aliases)
70
- scripts/ generator, agent installer, and the checks behind `npm test`
71
- tests/{unit,install}/ unit + clean-home install tests (node:test, no dependencies)
72
+ contracts/{plan,review,debug}.md.tmpl source for dual-use contracts — edit here, run `npm run generate`
73
+ contracts/workflows.md.tmpl source for namespaced spines and full deprecated aliases
74
+ prompts/{principal-,}{feature,bugfix}.md generated workflows; bare names are deprecated
75
+ schemas/ portable v1 run-state, task-packet, and evidence schemas
76
+ scripts/assurance-state.mjs append-only assurance state, transitions, and gates
77
+ scripts/ generator, installers, and checks behind `npm test`
78
+ tests/{unit,install}/ unit + clean-home install tests (node:test; ajv dev-only, schema parity)
79
+ tests/e2e/run-e2e.sh live workflow cells: both spines, with and without subagents
72
80
  <skill>/tests/specification.yaml skill-harness scenarios (ship bar, critical gates)
73
81
  <skill>/tests/fixtures/<ID>/ seeded repo for one scenario (git-ops, build, debug)
74
82
  <skill>/tests/results/…/results.yaml committed run evidence (Opus-judged)
75
83
  AGENTS.md routing + dispatch reference (ships, but pi does not auto-load it)
76
84
  CHANGELOG.md release history
85
+ docs/HANDOFF.md current state, what is open, standing hazards — read first
77
86
  docs/validation/ how the skills are measured — scorecard, run manifest
78
87
  docs/evidence/ per-judgment and per-rep records behind the scorecard
79
88
  docs/demos/ the chains running end to end, repo-verified
@@ -84,17 +93,38 @@ docs/demos/ the chains running end to end, repo-verifi
84
93
  1. **Skills + prompts** — install an immutable tag, not a branch:
85
94
 
86
95
  ```
87
- pi install git:github.com/mojomanyana/principal-pi-skills@v2.3.0
96
+ pi install git:github.com/mojomanyana/principal-pi-skills@v3.0.0
88
97
  ```
89
98
 
99
+ `3.0.0` is the current published npm release, and the tag matches this checkout's
100
+ manifest. It adds the risk-adaptive assurance profiles; `standard` is the default and
101
+ preserves v2 invocation, so upgrading from `2.4.0` changes no command you already type.
102
+ Read [Validation](#validation) first: v3 ships with **no model score of its own** — the
103
+ committed board is a historical v2.4 baseline. Do not turn a moving branch into
104
+ production install guidance.
105
+
106
+ **Do not install `2.3.0`** — it is deprecated on npm for a destructive defect: its
107
+ `principal-pi-workspace remove` deletes any path handed to it, including your checkout,
108
+ and reports success. `2.3.1` is the lowest safe version.
109
+
90
110
  The `pi` manifest registers the seven skills and the `/principal-feature` and
91
111
  `/principal-bugfix` commands (plus the deprecated `/feature` and `/bugfix` aliases).
92
112
  Unpinned `main` moves under you: the skills' behavior is what the committed scorecard
93
- measured, and a tag is what keeps those two the same thing. Drop the `@v2.3.0` only if
113
+ measured, and a tag is what keeps those two the same thing. Drop the version pin only if
94
114
  you want whatever `main` currently holds, measured or not.
95
- 2. **Subagents (optional).** Install pi-mono's subagent extension
96
- (`packages/coding-agent/examples/extensions/subagent` — symlink its `index.ts` and
97
- `agents.ts` into `~/.pi/agent/extensions/subagent/`), then install the agent definitions:
115
+ 2. **Subagents (optional).** The extension ships **inside pi itself**, so there is nothing
116
+ to clone. Copy its `index.ts` and `agents.ts` into `~/.pi/agent/extensions/subagent/`
117
+ from wherever your pi lives:
118
+
119
+ ```
120
+ # installed from npm — the path that applies to most people:
121
+ EXT="$(dirname "$(readlink -f "$(command -v pi)")")/../examples/extensions/subagent"
122
+ mkdir -p ~/.pi/agent/extensions/subagent
123
+ cp "$EXT/index.ts" "$EXT/agents.ts" ~/.pi/agent/extensions/subagent/
124
+ ```
125
+
126
+ In a pi-mono *source* checkout the same files are at
127
+ `packages/coding-agent/examples/extensions/subagent`. Then install the agent definitions:
98
128
 
99
129
  ```
100
130
  npx -p principal-pi-skills principal-pi-agents install # → ${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents
@@ -109,17 +139,26 @@ docs/demos/ the chains running end to end, repo-verifi
109
139
  `--with-generic-aliases`.
110
140
 
111
141
  Tool restriction is structural, in the agents' frontmatter: `plan` is read-only;
112
- `review` adds `bash` only to run tests; `debug` gets the full toolset.
113
-
114
- The extension steps were last run end to end against **pi 0.80.2** and pi-mono
115
- [`008c76f`](https://github.com/badlogic/pi-mono/commit/008c76f955ae) — the newest commit
116
- touching that extension path, so the layout has been stable since 2026-06-18. Upstream is
117
- someone else's repo: if the file names move, check out that commit.
118
- 3. **Without the extension everything still works.** The workflows detect that delegation is
119
- unavailable and run each phase inline instead. That is a supported configuration, not a
120
- degraded one — with one honest caveat: inline review is *self-review*. It sees the
121
- session's own reasoning, so it cannot be surprised by it the way a cold subagent read can.
122
- Treat an inline APPROVE as weaker evidence than a delegated one.
142
+ `review` adds `bash` to run tests; `debug` has the same bash-enabled surface (and pi-daddy
143
+ correctly treats bash as write-capable authority).
144
+
145
+ The extension steps were last run end to end against **pi 0.83.0** (2026-08-11), by the
146
+ historical workflow E2E cells in `tests/e2e/run-e2e.sh`. v3 defines four `× subagents
147
+ present` cells (standard/critical × both spines); they are prepared but not model-run here.
148
+ The v2 cells delegated to `principal-plan`/`principal-review`/`principal-debug` and passed.
149
+ Upstream is someone else's repo, so if the file names move, that copy step is the thing to
150
+ re-check.
151
+
152
+ One trap worth knowing if you run subagents on a non-default provider: the extension
153
+ passes `--model` to the child `pi` only when an agent's frontmatter names one. Ours
154
+ deliberately do not, so a delegated agent uses your pi config's `defaultProvider` /
155
+ `defaultModel` — **not** whatever `--provider`/`--model` you passed the parent. If
156
+ delegations fail to authenticate while the parent is fine, that mismatch is why.
157
+ 3. **Without the extension, lean and standard still work completely inline.** That remains a
158
+ supported baseline. Inline review is self-review and weaker than a cold read. Critical
159
+ assurance does not pretend otherwise: if no governed fresh-context executor exists for its
160
+ critique and independent reviews, it returns `BLOCKED_CRITICAL_ASSURANCE` rather than
161
+ silently degrading to inline self-review.
123
162
  4. **`AGENTS.md` is not installed as routing context.** pi packages register skills and
124
163
  prompts; they do not load a routing file into every session. It ships in the package and
125
164
  is worth reading, but nothing loads it for you — if you want the orchestrator to route by
@@ -128,10 +167,12 @@ docs/demos/ the chains running end to end, repo-verifi
128
167
 
129
168
  ### What a clean install actually gives you
130
169
 
131
- - The seven skills and both workflow commands, running **inline**. That is the baseline
132
- product, and it is complete.
133
- - Subagents only if you did step 2 — they are an improvement in context isolation and cold
134
- judgment, not a requirement.
170
+ - The seven skills and both workflow commands, with lean/standard running **inline** as a
171
+ complete baseline.
172
+ - Subagents only if you did step 2 — optional for lean/standard, but one way to satisfy the
173
+ fresh-context controls explicit critical assurance requires.
174
+ - `principal-pi-assurance`, a parent/controller CLI that stores a hash-chained event log and
175
+ derived snapshot outside the product tree. It adds no public skill name.
135
176
  - `/principal-feature` and `/principal-bugfix` as the supported commands. `/feature` and
136
177
  `/bugfix` still work but are **deprecated aliases**: a bare name is a slot any installed
137
178
  package can claim, and the last one loaded wins silently.
@@ -163,6 +204,33 @@ verify both files had been *touched*, never that they still agreed.
163
204
  and carries no template: it runs inline and terminates a chain, so a handoff token would
164
205
  have nothing to hand to. Its delegated block was removed in 2.3.0 as dead ceremony.
165
206
 
207
+ The two namespaced workflows and deprecated aliases are generated as complete prompts from
208
+ `contracts/workflows.md.tmpl`; aliases do not depend on recursive slash-command expansion, and the
209
+ shared assurance section is byte-identical by construction. Workflow state is not prose:
210
+ `principal-pi-assurance` validates the v1 schemas, appends hash-chained JSONL events, derives
211
+ `snapshot.json`, rejects illegal downgrades/transitions, and gates stale evidence or missing
212
+ critical controls. In git it stores under the common directory
213
+ (`.git/principal-pi-skills/assurance-v1`), otherwise under XDG state. Build remains the only
214
+ durable source writer. See [docs/ASSURANCE.md](./docs/ASSURANCE.md).
215
+
216
+ ## Assurance profiles
217
+
218
+ Both namespaced workflows accept:
219
+
220
+ ```
221
+ --assurance lean|standard|critical
222
+ --critical-scope "entire-run|task-2,task-4|db/migrations/**,src/auth/**"
223
+ ```
224
+
225
+ `standard` is the compatible default and `high` aliases `critical`. “Treat this as critical”
226
+ and “escalate this run to critical” persist the same state. Lean keeps the tiny/reversible
227
+ path. Standard keeps Option B. Critical adds approved design for consequential work,
228
+ independent plan critique before task packets, an owned branch worktree, per-task specification
229
+ and quality reviews in separate fresh contexts rooted at that writer checkout, a final whole-change
230
+ review after task evidence, fresh full evidence, and just-in-time approval for external effects.
231
+ Git-Ops records final branch/head/tree between readiness and completion gates. Critical never silently falls back;
232
+ unavailable isolation or fresh contexts returns `BLOCKED_CRITICAL_ASSURANCE`.
233
+
166
234
  ## See it run
167
235
 
168
236
  Three end-to-end runs, verified against the repository afterwards rather than taken from
@@ -179,46 +247,19 @@ the model's own account:
179
247
 
180
248
  ## Validation
181
249
 
182
- Every skill carries a `tests/specification.yaml` of scenarios with pass criteria, and the
183
- results are committed. The measurement: **98 scenarios across the seven skills, every
184
- scenario run three times** on DeepSeek v4-pro and GLM 5.2, judged by `claude-code:opus`, with
185
- objective gates (vitest runs, diff assertions) decided before the judge is consulted. A
186
- scenario passes at a majority of its clean reps, so a cell is a pass-rate rather than a
187
- single draw. The scored deployment is skill-as-system-prompt (`--mode force`) — the delivery
188
- modern pi makes deterministic, and the way the `agents/` variants already run.
189
- **kimi-k3 was never tuned against** — it is the control for overfitting, and is an optional
190
- follow-up rather than a published column in the current round.
191
-
192
- | Skill | DeepSeek v4-pro | GLM 5.2 | kimi-k3 |
193
- |---|---|---|---|
194
- | architect | 13/14 · 93% | **14/14 · 100% SHIP** | — *(deferred)* |
195
- | build | **9/9 · 100% SHIP** | **9/9 · 100% SHIP** | — *(deferred)* |
196
- | debug ✗ | — *(withdrawn)* | — *(withdrawn)* | — *(deferred)* |
197
- | decide | **12/12 · 100% SHIP** | **12/12 · 100% SHIP** | — *(deferred)* |
198
- | git-ops | 18/19 · 95% | **19/19 · 100% SHIP** | — *(deferred)* |
199
- | plan | 8/12 · 67% | **12/12 · 100% SHIP** | — *(deferred)* |
200
- | review ✗ | — *(withdrawn)* | — *(withdrawn)* | — *(deferred)* |
201
-
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
208
- previously held at 92% on every model, failing exactly one boundary scenario each, and shipped
209
- nowhere; it is now 12/12 on both. `build` went 7/9 → 9/9 on DeepSeek.
210
-
211
- `plan` is the one to read carefully: **12/12 on GLM against 8/12 on DeepSeek**, on identical
212
- text. The skill is not weak, it is weak on one model — and its boundary cells move between
213
- runs, so treat a single `plan`/DeepSeek cell as one draw rather than a measurement.
214
-
215
- **kimi-k3 is deferred, not dropped.** It is the untuned control for overfitting, so until it
216
- runs there is no evidence about generalization beyond the two models these skills were tuned
217
- against — the two most likely to flatter them. Its cells are tracked in
218
- [unpublished-cells.txt](docs/validation/unpublished-cells.txt), and CI fails if an entry there
219
- outlives its reason, so it cannot be quietly forgotten.
220
- [VALIDATION.md](docs/validation/VALIDATION.md) has the failing cells and why each is published
221
- at rate rather than tuned away.
250
+ v3 changes model-visible contract text, adds one `E1` assurance scenario to each skill, and adds
251
+ a Git-Ops stale-receipt negative, taking the static specification from 98 to **106 scenarios**.
252
+ Those eight scenarios are prepared but
253
+ have **not** been model-run; no paid skill-harness or live E2E validation was authorized, and
254
+ `3.0.0` was released on that basis deliberately rather than by oversight.
255
+ Consequently v3 publishes no model score yet. The committed DeepSeek/GLM board remains a
256
+ historical v2.4 baseline, not evidence for the v3 prompts. `docs/validation/VALIDATION.md`
257
+ records that boundary and the commands for a future measured wave.
258
+
259
+ The free gate is `npm test`: generated-contract/workflow drift, state-machine and schema
260
+ transitions, install/packed-artifact behavior, worktree isolation, word budgets, and
261
+ skill-harness lint. Live workflow E2E now defines standard/critical × feature/bugfix ×
262
+ subagents present/absent; it is prepared but not run here because it spends model tokens.
222
263
 
223
264
  ## Deliberate design rules
224
265
 
package/agents/debug.md CHANGED
@@ -5,11 +5,13 @@ description: >
5
5
  a crash, a CI or lint error — "why is this failing", "find the bug", "debug this", "it
6
6
  crashes when", "works on my machine". Not for writing new features or fixing a bug
7
7
  whose cause is already known (build).
8
+ tools: read, grep, find, ls, bash
9
+ allowed-tools: read, grep, find, ls, bash
8
10
  ---
9
11
 
10
12
  # Debug — Hypothesis Before Fix
11
13
 
12
- You run in an isolated context with the full toolset. **The caller receives ONLY your
14
+ You run in an isolated context with a bash-enabled tool surface. **The caller receives ONLY your
13
15
  final message.** Work across as many tool calls and intermediate messages as the bug
14
16
  needs — none of that reaches anyone. Your last message must therefore BE the complete
15
17
  debugging note, every field, as one block — restated in full even if you already wrote
@@ -39,7 +41,9 @@ unknown one; the harder the bug, the stricter the loop.
39
41
  5. **Prove the fix at the root cause — still in the workspace.** The stack trace points at
40
42
  the symptom; trace the wrong value upstream and fix there. The regression test fails
41
43
  before the fix and passes after; re-run the full suite and the original reproduction.
42
- Intermittent bug → loop the test (e.g. 100×) before declaring victory.
44
+ Intermittent bug → loop the test (e.g. 100×) before declaring victory. For async or
45
+ eventually-consistent behavior, wait on the observable condition with a deadline; a fixed
46
+ sleep is not condition-based evidence and only moves the race.
43
47
  **In a workflow you report the fix and do not leave it behind** — `build` implements it
44
48
  once, in the caller's checkout, where they can watch it land. **Asked directly to fix it,
45
49
  fix it.** "Diagnose this and fix it" is a request, not a handoff; withholding a repair the
@@ -99,6 +103,8 @@ speculative edits with no traction, you are in a hard bug: return to step 1.
99
103
  Reproduction: <command or test that triggers it, or "NOT REPRODUCED: <why>">
100
104
  Isolated to: <smallest input / commit range>
101
105
  Hypotheses tested: <each → confirmed / rejected, with evidence>
106
+ Boundary evidence: <smallest input + system boundary where the bad value first appears>
107
+ Wait condition: <observable condition + deadline> | not applicable
102
108
  Root cause: <file:line + why>
103
109
  Fix: <the minimal change, at the cause not the symptom — proposed, not applied>
104
110
  Regression test: <name; failed before fix, passes after>
package/agents/plan.md CHANGED
@@ -7,6 +7,7 @@ description: >
7
7
  the plan and per-step specs; writes no code. Not for system-level design (architect)
8
8
  or diagnosing failures (debug).
9
9
  tools: read, grep, find, ls
10
+ allowed-tools: read, grep, find, ls
10
11
  ---
11
12
 
12
13
  # Plan — Slices and Specs
@@ -32,8 +33,8 @@ A plan that bottoms out in "add validation" is not a plan; each step names files
32
33
  behavior, and the test that proves it.
33
34
 
34
35
  ## Process
35
- 1. **State the outcome** in one measurable sentence ("users can reset passwords without
36
- filing a support ticket"), not a feature list.
36
+ 1. **State the outcome and authority**: the measurable result, governing requirements,
37
+ global constraints, and what is explicitly out of scope — not a feature list.
37
38
  2. **Read the code before planning it.** Open every file you will name, the callers of
38
39
  anything that changes, the nearest test. Note the codebase's conventions — naming,
39
40
  error style, test layout — the plan follows them, not your defaults. Never present a
@@ -86,22 +87,42 @@ per slice is fine: `1. Skeleton: real request→store→respond path, primitive
86
87
  the one output this agent never produces.
87
88
 
88
89
  ## Output — plan
89
- This template is for multi-step work. A trivial reversible change never gets it — its
90
- entire plan is three lines: the change, the test, done. Small clear work (one flag, one
91
- helper, one endpoint) gets the middle form: two or three slices with a done-signal each,
92
- and nothing else — no Risks block, no spike, no [after:]/parallel annotations; the step
93
- numbers are the order. Not knowing the codebase is an Assumptions line, not a risk. A
94
- real [ONE-WAY] is the one field that always survives.
90
+ Output **task definitions**: authority/constraints/scope, files/dependencies, behavior/test, done
91
+ command, and review risk. The controller adds run/workspace IDs and current digests, validates the
92
+ task-packet schema, and persists; Plan never invents them. Critical always emits a task definition
93
+ but omits unrelated ceremony.
94
+
95
+ Use this template for multi-step work. Trivial reversible work gets three lines: change, test, done.
96
+ Small clear work gets two or three slices with a done-signal; omit Risks, spikes, and dependency
97
+ annotations because step order suffices. Unknown codebase facts are Assumptions. A real [ONE-WAY]
98
+ always survives.
95
99
  ```
96
100
  ## Plan: <outcome, one sentence>
101
+ Authority: <requirement IDs, approved design, or exact user request>
102
+ Global constraints: <limits every task must preserve>
103
+ Out of scope: <explicit exclusions> | none
97
104
  Conventions observed: <naming / error / test patterns found in the codebase>
98
105
  Risks: <risk → mitigation or spike step>
99
106
  Steps:
100
107
  1. Walking skeleton — <thinnest real path through every named seam> — proves: <each seam, exercised for real>
108
+ Task ID: task-1
109
+ Critical scope: <why this task matches> | not critical
110
+ Files: <paths>
111
+ Dependencies: none
112
+ Change: <signatures + exact behavior>
113
+ Test: <name, level, edge cases>
114
+ Done command: <exact command + expected result>
115
+ Review risk: <highest-risk behavior reviewers must attack>
116
+ Ripples: <callers, config, migrations> | none
101
117
  2. <step name> [after: 1] [ONE-WAY: <rollback + kill criterion>]
118
+ Task ID: <stable ID>
119
+ Critical scope: <matched task/path selector> | not critical
102
120
  Files: <paths>
121
+ Dependencies: <task IDs> | none
103
122
  Change: <signatures + exact behavior>
104
123
  Test: <name, level, edge cases>
124
+ Done command: <exact command + expected result>
125
+ Review risk: <risk or boundary>
105
126
  Ripples: <callers, config, migrations> | none
106
127
  3. …
107
128
  Parallel-safe: <which steps> | none
@@ -5,11 +5,13 @@ description: >
5
5
  a crash, a CI or lint error — "why is this failing", "find the bug", "debug this", "it
6
6
  crashes when", "works on my machine". Not for writing new features or fixing a bug
7
7
  whose cause is already known (build).
8
+ tools: read, grep, find, ls, bash
9
+ allowed-tools: read, grep, find, ls, bash
8
10
  ---
9
11
 
10
12
  # Debug — Hypothesis Before Fix
11
13
 
12
- You run in an isolated context with the full toolset. **The caller receives ONLY your
14
+ You run in an isolated context with a bash-enabled tool surface. **The caller receives ONLY your
13
15
  final message.** Work across as many tool calls and intermediate messages as the bug
14
16
  needs — none of that reaches anyone. Your last message must therefore BE the complete
15
17
  debugging note, every field, as one block — restated in full even if you already wrote
@@ -39,7 +41,9 @@ unknown one; the harder the bug, the stricter the loop.
39
41
  5. **Prove the fix at the root cause — still in the workspace.** The stack trace points at
40
42
  the symptom; trace the wrong value upstream and fix there. The regression test fails
41
43
  before the fix and passes after; re-run the full suite and the original reproduction.
42
- Intermittent bug → loop the test (e.g. 100×) before declaring victory.
44
+ Intermittent bug → loop the test (e.g. 100×) before declaring victory. For async or
45
+ eventually-consistent behavior, wait on the observable condition with a deadline; a fixed
46
+ sleep is not condition-based evidence and only moves the race.
43
47
  **In a workflow you report the fix and do not leave it behind** — `build` implements it
44
48
  once, in the caller's checkout, where they can watch it land. **Asked directly to fix it,
45
49
  fix it.** "Diagnose this and fix it" is a request, not a handoff; withholding a repair the
@@ -99,6 +103,8 @@ speculative edits with no traction, you are in a hard bug: return to step 1.
99
103
  Reproduction: <command or test that triggers it, or "NOT REPRODUCED: <why>">
100
104
  Isolated to: <smallest input / commit range>
101
105
  Hypotheses tested: <each → confirmed / rejected, with evidence>
106
+ Boundary evidence: <smallest input + system boundary where the bad value first appears>
107
+ Wait condition: <observable condition + deadline> | not applicable
102
108
  Root cause: <file:line + why>
103
109
  Fix: <the minimal change, at the cause not the symptom — proposed, not applied>
104
110
  Regression test: <name; failed before fix, passes after>