principal-pi-skills 2.4.0 → 3.0.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
@@ -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,7 +119,11 @@ 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.1` — the immutable install
123
+ coordinate for this source tree's `3.0.1` release candidate. The remote `v3.0.1` tag is pending
124
+ and npm `latest` remains `3.0.0`; verify both before installing. After publication they must
125
+ resolve this same version. `standard` is the default assurance
126
+ profile, so a v2 invocation keeps working unchanged. It registers the
111
127
  skills and the `/principal-feature` + `/principal-bugfix` commands via the `pi`
112
128
  manifest. Install a tag, not a branch.
113
129
  2. Subagents need pi-mono's subagent extension (`examples/extensions/subagent`, which ships
package/CHANGELOG.md CHANGED
@@ -6,6 +6,143 @@ Where review revealed a prior claim or design decision didn't hold up under clos
6
6
 
7
7
  ---
8
8
 
9
+ ## [3.0.1] — 2026-09-04
10
+
11
+ **Added — assurance ledgers have a read-only evidence projection.**
12
+ `principal-pi-assurance report --run-id <id>` renders authority, packets, changed paths, receipts,
13
+ reviews, recorded gate outcomes, findings/adjudications, and finish identity in deterministic human
14
+ sections, with absent facts and assumptions labelled rather than inferred. It also emits an unsigned
15
+ in-toto Statement v1 using the test-result v0.1 predicate; final head/tree subjects, receipt-derived
16
+ configuration and pass/fail lists, and the ledger hash-chain head bind the output to facts already in
17
+ the validated log. `--format in-toto` emits only Statement JSON. The command does not append events,
18
+ sign output, or claim a signature.
19
+
20
+ **Added — gate outcomes are recorded, not just printed.** `principal-pi-assurance gate` now appends a
21
+ `gate_evaluated {gate, code, missing_count, task_id?, action?}` event for every evaluation it performs,
22
+ pass or block. The gate was a pure read, which is precisely why no downstream observer could prove that
23
+ a gate ran or how it answered; a completion claim and an unexamined run were indistinguishable in the
24
+ ledger. Because the workflows already invoke the gate at each control point, recording inside the
25
+ command required no workflow or skill text change. The event is an observation: it mutates no derived
26
+ state, so it cannot advance `last_change_seq` or `last_authority_seq` and can never make a receipt
27
+ stale, and it is accepted after `finalization_completed` so the `finish` gate can record its own
28
+ outcome. `missing_count` is recorded rather than the missing-control strings, which are human
29
+ diagnostics and not a machine contract. A ledger containing this event requires this version or newer
30
+ to replay. Rationale and the downstream assertion mapping: `docs/handoff/2026-09-event-vocabulary-decision.md`.
31
+
32
+ **Fixed — fail-closed measurement classification.** A closed machine-readable manifest now
33
+ classifies all 205 committed `results.yaml` files exactly once and binds each entry to its
34
+ raw SHA-256. The Terra-high control, unpinned-executor infrastructure failure, and
35
+ subprocess-pinned delivery-unproven run are explicitly excluded from efficacy, stability,
36
+ release, and v3 scoring. Historical result payloads are unchanged.
37
+
38
+ **Added — external per-observation attestation verification.** A development-only verifier
39
+ accepts canonical Ed25519 attestations only from explicitly configured operator-trusted
40
+ production keys. A closed arm policy and canonical strict future-result contract bind one
41
+ accepted attempt to one result/scenario/repetition; complete trust stores are eagerly checked,
42
+ and an in-memory validation-session registry atomically rejects replay across all evidence sets.
43
+ Missing, extra, stale, future, replayed, mismatched, refusal-only, incomplete, capability-only,
44
+ or invalidly signed evidence fails closed. Durable operational replay prevention remains the
45
+ external producer/controller's responsibility. No private production key is stored here. The external producer
46
+ remains responsible for signing-key protection, ledger authenticity, runtime identity,
47
+ loaded-definition and artifact/module confinement, process-tree containment, and any OS
48
+ sandbox.
49
+
50
+ **Fixed — Critical Plan task definitions are concrete and attributable.** Critical plans now
51
+ keep authority/scope before tasks, require named tests and literal targeted Done commands,
52
+ separate Plan definitions from controller-owned canonical packet identity/digest fields, and
53
+ forbid assurance-only delivery slices. With no repository context they propose concrete values
54
+ as assumptions and require discovery/validation before execution rather than emitting
55
+ placeholders or claiming guessed paths exist. `Done command` is explicitly declarative and untrusted:
56
+ this version provides no deterministic command or approval enforcement. Deterministic mutation
57
+ coverage is structural only; a fresh Wave A remains required for behavioral
58
+ validation. `docs/evidence/pr35-e1-repair-provenance-v1.json` hashes the E1-informed evidence,
59
+ including contextual D1/D2 diagnosis material; preserved measurements are unchanged.
60
+
61
+ **Changed — release evidence does not claim model measurement.** `3.0.1` contains three
62
+ generated Plan runtime prompt changes, the explicitly authorized assurance-state additions, and
63
+ Decide's approved P4 text; other shipped runtime schemas, scripts, skills, agents, and prompts remain
64
+ byte-identical to `3.0.0`. No 3.0.1 model score is claimed: deterministic/static checks are the
65
+ release evidence, while the required DeepSeek/GLM wave and live workflow cells remain unrun. At
66
+ release candidate cut, the remote `v3.0.1` tag is pending and npm `latest` remains `3.0.0`; neither external
67
+ publication result is claimed before verification.
68
+
69
+ ## [3.0.0] — 2026-08-20
70
+
71
+ **Added — risk-adaptive assurance profiles on the two existing workflow spines.** `standard`
72
+ remains the default Option B behavior; `lean` preserves the tiny/reversible path; explicit
73
+ `critical` (and `high`) activates selected Option C controls. `--critical-scope` accepts an
74
+ entire run, task IDs, or path globs. Natural-language critical/escalation requests map to the
75
+ same state. No skill or public agent name was added: the set remains decide, architect, plan,
76
+ build, review, debug, git-ops.
77
+
78
+ **Added — deterministic assurance state outside the product tree.**
79
+ `principal-pi-assurance` validates versioned run-state/task-packet/evidence-receipt schemas, appends a
80
+ SHA-256-linked JSONL event log, atomically derives a snapshot, enforces legal transitions and
81
+ explicit downgrade, matches critical scope, detects stale evidence after source changes, and
82
+ returns `BLOCKED_CRITICAL_ASSURANCE` with missing controls. State is under git's common
83
+ directory (XDG state outside git), so Plan/Review/Debug retain their read-only/disposable
84
+ workspace contracts and Build remains the only durable source writer.
85
+
86
+ **Changed — critical workflow controls.** Consequential design approval includes validation,
87
+ observability, rollback, abort, and one-way doors; plans carry authority and independently
88
+ verifiable task packets; an independent plan critique precedes Build; an owned isolated
89
+ branch worktree is mandatory; each task receives separate fresh specification and
90
+ quality/security reviews rooted at the canonical writer checkout; a final fresh whole-change review
91
+ follows all task evidence. Mid-run escalation freezes base/head/candidate-tree and backfills exact
92
+ matching receipts before more source writes. Approved replans explicitly supersede immutable stale
93
+ packets rather than silently rebinding them.
94
+ Irreversible/external effects require just-in-time user approval. Critical never degrades to
95
+ inline self-review when fresh-context infrastructure is absent.
96
+
97
+ **Changed — standard and repair/finish discipline.** Standard remains the normal spine with
98
+ vertical slices, dependency/interface preflight, one writer, milestone/final review,
99
+ evidence-based finding adjudication, fresh verification, and an explicit finish choice.
100
+ Build repair mode consumes accepted finding IDs one at a time. Git-Ops finish mode offers
101
+ merge locally, push/open PR, or keep, runs a pre-operation readiness gate, and persists final
102
+ branch/head/tree before the completion gate; discard remains explicit. Tiny work does not acquire
103
+ architecture machinery unless the user explicitly selected critical.
104
+
105
+ **Changed — workflow and dual-use generation.** Both namespaced prompts now render from
106
+ `contracts/workflows.md.tmpl`, with a test proving their assurance rules are identical.
107
+ Plan/Review/Debug continue to render skill, namespaced agent, and generic alias from their
108
+ existing templates. All capability ceilings are unchanged.
109
+
110
+ **Added — free assurance coverage.** Unit tests cover parsing/defaults, policy escalation,
111
+ explicit downgrade, scope matching, legal events, missing-control blocks, evidence freshness,
112
+ review-context/workspace/tree independence, JIT approval, readiness/finalization, event-log
113
+ integrity, Draft 2020-12/runtime schema parity, and branch-attached workspaces. The E2E harness now defines standard/critical ×
114
+ feature/bugfix × subagents present/absent; critical/absent asserts a clean block. Seven `E1`
115
+ skill-harness scenarios plus a Git-Ops stale-receipt negative are prepared but deliberately not
116
+ model-run; no skill-harness/live E2E validation was authorized, so v2.4 measurements are historical
117
+ and v3 publishes no model score yet.
118
+
119
+ **Fixed — npm 12 pack metadata compatibility.** npm 12 changed `npm pack --json` from an
120
+ array to a package-keyed object, which made seven clean-home install tests fail before this
121
+ work began. Pack checks, install tests, and E2E now normalize both shapes and still fail on
122
+ empty/malformed metadata.
123
+
124
+ **Fixed — the `v2.4.0` git tag never existed.** 2.4.0 was published to npm on 2026-08-16, but
125
+ no tag was cut, so `pi install git:github.com/mojomanyana/principal-pi-skills@v2.4.0` — the
126
+ immutable install command README and AGENTS.md both printed, and the one thing this project
127
+ tells users to prefer over a moving branch — resolved to nothing for four days. The tag is
128
+ backfilled at the release commit it always belonged to (`4dece8c`), and tagging now precedes
129
+ publishing. It is the same failure as 2.3.1's 404'ing npx invocations: a documented command
130
+ nothing executed.
131
+
132
+ **Changed — released with the measurement gap stated, not closed.** `3.0.0` ships statically
133
+ verified and unmeasured, and every document that could be read as a claim now says so at the
134
+ point of reading: the README install step, `docs/ASSURANCE.md`, `docs/validation/VALIDATION.md`,
135
+ and the handoff verdict. All 101 skill-harness findings are exempt-stale against the v3 text —
136
+ that is the honest state of a v3 cell, not a passing one. The authorized two-model wave and the
137
+ live eight-cell E2E remain the work that would replace the historical v2.4 board with a v3 one.
138
+
139
+ **Changed — `ajv`/`ajv-formats` are the first devDependencies.** The Draft 2020-12 parity test
140
+ needs a real validator. Runtime install stays dependency-free — they are not in the pack
141
+ allowlist — but `npm test` in a fresh checkout now requires `npm ci` first, where before it ran
142
+ on a bare clone.
143
+
144
+ ---
145
+
9
146
  ## [2.4.0] — 2026-08-17
10
147
 
11
148
  **Added** — every skill now declares an `allowed-tools` capability ceiling, which
package/README.md CHANGED
@@ -8,11 +8,19 @@ to isolated contexts (`plan`, `review`, `debug` — single-shot variants in `age
8
8
  generated from the same contract as the skill). The files follow the [Agent Skills](https://agentskills.io/specification)
9
9
  standard, so other harnesses can consume the skills, but pi is the supported target.
10
10
 
11
+ **Version:** `3.0.1` release candidate. The remote `v3.0.1` tag is pending and npm `latest`
12
+ remains `3.0.0` until both publication results are independently verified. Release coordinates
13
+ are npm `principal-pi-skills@3.0.1` and the immutable git tag `v3.0.1`. This version strengthens the generated Critical Plan skill/agent
14
+ prompts, assurance-ledger evidence, and development-only measurement verification. It carries no
15
+ new model score; the committed board remains a historical v2.4 baseline.
16
+
11
17
  The set is built for **one principal engineer steering at a high level while skills and
12
18
  subagents do the work.** Two properties follow, and every design choice below serves them:
13
19
  **delegable trust** — an output carries the evidence needed to verify it without redoing
14
20
  the work — and **cheap iteration** — a defect found is a defect fixed, not documented
15
- around.
21
+ around. v3 adds risk-adaptive assurance to the two workflows: `standard` stays the default,
22
+ while explicit `critical` activates selected isolation, independent-review, evidence, and
23
+ approval controls without creating another skill suite.
16
24
 
17
25
  ## Three constraints
18
26
 
@@ -26,33 +34,37 @@ around.
26
34
  plain-text tags (`[ONE-WAY]`, `[BLOCKER]`) instead of an emoji schema, no aphorisms
27
35
  doing load-bearing work, no personas, no required reading in reference files.
28
36
  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
37
+ ≤ ~1400 words**, with **`git-ops` an accepted exception at ~2000** — the safety-critical
30
38
  operator carries the most arming, and validated behavior outweighs a budget.
31
39
  Both ceilings have moved once, each buying a fix rather than more prose. `git-ops` went
32
40
  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
41
+ findings, then 1900 → 2000 for v3 finish mode's fresh-evidence gate and explicit
42
+ merge/PR/keep choice. No safety playbook was trimmed to make room. The skill budget went
43
+ 1100 → 1250 → 1400 for a lesson this framework
34
44
  paid for: *every arming needs its governor in the same breath*. An absolute is cheap to
35
45
  write — "one caller → inline it", "every catch logs and changes state" — and wrong in real
36
46
  cases, and each wrong absolute produced a measured over-refusal. A rule plus the cases it
37
47
  must not eat costs more words than an absolute; that is the trade. **When a fix and the
38
48
  ceiling conflict, the ceiling moves** — trimming to fit was quietly deleting reasons a weak
39
- model needed, which is a worse outcome than a longer file. **Agents
40
- get their own budget, ≤ ~1500**: a single-shot definition carries its output template
41
- *and* the BLOCKED form *and* the no-questions mechanics, none of which a loaded skill
42
- needs. Every count in the table below is checkable with `wc -w`. Nothing loads anything
49
+ model needed, which is a worse outcome than a longer file. Plan is the local exception at
50
+ ≤ ~1700 (agent ≤ ~1900): its Critical contract keeps packet ownership, concrete verification,
51
+ no-context discovery, and vertical-slice governors together after those omissions failed across
52
+ models. **Other agents get their own budget, ≤ ~1500**: a single-shot definition carries its
53
+ output template *and* the BLOCKED form *and* the no-questions mechanics, none of which a loaded
54
+ skill needs. Every count in the table below is checkable with `wc -w`. Nothing loads anything
43
55
  else — a subagent reads one file and has the whole contract.
44
56
 
45
57
  ## The set
46
58
 
47
59
  | Skill | What it does | How it runs | Words |
48
60
  |---|---|---|---|
49
- | `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline | 852 |
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 | 1093 |
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`, 1365) or inline | 1155 |
52
- | `build` | Test-first implementation — code proven by a test you watched fail | inline | 976 |
53
- | `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1323) or inline | 1295 |
54
- | `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1347) or inline | 1214 |
55
- | `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 1898 |
61
+ | `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline | 1055 |
62
+ | `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 |
63
+ | `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`, 1812) or inline | 1602 |
64
+ | `build` | Test-first implementation — code proven by a test you watched fail | inline | 1162 |
65
+ | `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1392) or inline | 1364 |
66
+ | `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 |
67
+ | `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
68
 
57
69
  Routing between them belongs to the orchestrator, not to a skill — there is deliberately no
58
70
  routing skill spending context to say "pick a skill". [AGENTS.md](./AGENTS.md) is that
@@ -65,10 +77,13 @@ you; point your orchestrator at it deliberately.
65
77
  <skill>/SKILL.md the interactive contract — nothing else is required reading
66
78
  agents/principal-{plan,review,debug}.md subagent definitions the workflows delegate to
67
79
  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)
80
+ contracts/{plan,review,debug}.md.tmpl source for dual-use contracts — edit here, run `npm run generate`
81
+ contracts/workflows.md.tmpl source for namespaced spines and full deprecated aliases
82
+ prompts/{principal-,}{feature,bugfix}.md generated workflows; bare names are deprecated
83
+ schemas/ portable v1 run-state, task-packet, and evidence schemas
84
+ scripts/assurance-state.mjs append-only assurance state, transitions, and gates
85
+ scripts/ generator, installers, and checks behind `npm test`
86
+ tests/{unit,install}/ unit + clean-home install tests (node:test; ajv dev-only, schema parity)
72
87
  tests/e2e/run-e2e.sh live workflow cells: both spines, with and without subagents
73
88
  <skill>/tests/specification.yaml skill-harness scenarios (ship bar, critical gates)
74
89
  <skill>/tests/fixtures/<ID>/ seeded repo for one scenario (git-ops, build, debug)
@@ -86,9 +101,17 @@ docs/demos/ the chains running end to end, repo-verifi
86
101
  1. **Skills + prompts** — install an immutable tag, not a branch:
87
102
 
88
103
  ```
89
- pi install git:github.com/mojomanyana/principal-pi-skills@v2.3.1
104
+ pi install git:github.com/mojomanyana/principal-pi-skills@v3.0.1
90
105
  ```
91
106
 
107
+ `3.0.1` is the release represented by this source tree. The immutable tag must match its
108
+ manifest before publication, and npm `latest` must resolve the same version afterward. v3 adds
109
+ the risk-adaptive assurance profiles; `standard` is the default and preserves v2 invocation,
110
+ so upgrading from `2.4.0` changes no command you already type.
111
+ Read [Validation](#validation) first: v3 ships with **no model score of its own** — the
112
+ committed board is a historical v2.4 baseline. Do not turn a moving branch into
113
+ production install guidance.
114
+
92
115
  **Do not install `2.3.0`** — it is deprecated on npm for a destructive defect: its
93
116
  `principal-pi-workspace remove` deletes any path handed to it, including your checkout,
94
117
  and reports success. `2.3.1` is the lowest safe version.
@@ -96,7 +119,7 @@ docs/demos/ the chains running end to end, repo-verifi
96
119
  The `pi` manifest registers the seven skills and the `/principal-feature` and
97
120
  `/principal-bugfix` commands (plus the deprecated `/feature` and `/bugfix` aliases).
98
121
  Unpinned `main` moves under you: the skills' behavior is what the committed scorecard
99
- measured, and a tag is what keeps those two the same thing. Drop the `@v2.3.1` only if
122
+ measured, and a tag is what keeps those two the same thing. Drop the version pin only if
100
123
  you want whatever `main` currently holds, measured or not.
101
124
  2. **Subagents (optional).** The extension ships **inside pi itself**, so there is nothing
102
125
  to clone. Copy its `index.ts` and `agents.ts` into `~/.pi/agent/extensions/subagent/`
@@ -125,23 +148,26 @@ docs/demos/ the chains running end to end, repo-verifi
125
148
  `--with-generic-aliases`.
126
149
 
127
150
  Tool restriction is structural, in the agents' frontmatter: `plan` is read-only;
128
- `review` adds `bash` only to run tests; `debug` gets the full toolset.
151
+ `review` adds `bash` to run tests; `debug` has the same bash-enabled surface (and pi-daddy
152
+ correctly treats bash as write-capable authority).
129
153
 
130
154
  The extension steps were last run end to end against **pi 0.83.0** (2026-08-11), by the
131
- live workflow E2E cells in `tests/e2e/run-e2e.sh` — both `× subagents present` cells
132
- delegate to `principal-plan`/`principal-review`/`principal-debug` and pass. Upstream is
133
- someone else's repo, so if the file names move, that copy step is the thing to re-check.
155
+ historical workflow E2E cells in `tests/e2e/run-e2e.sh`. v3 defines four `× subagents
156
+ present` cells (standard/critical × both spines); they are prepared but not model-run here.
157
+ The v2 cells delegated to `principal-plan`/`principal-review`/`principal-debug` and passed.
158
+ Upstream is someone else's repo, so if the file names move, that copy step is the thing to
159
+ re-check.
134
160
 
135
161
  One trap worth knowing if you run subagents on a non-default provider: the extension
136
162
  passes `--model` to the child `pi` only when an agent's frontmatter names one. Ours
137
163
  deliberately do not, so a delegated agent uses your pi config's `defaultProvider` /
138
164
  `defaultModel` — **not** whatever `--provider`/`--model` you passed the parent. If
139
165
  delegations fail to authenticate while the parent is fine, that mismatch is why.
140
- 3. **Without the extension everything still works.** The workflows detect that delegation is
141
- unavailable and run each phase inline instead. That is a supported configuration, not a
142
- degraded one — with one honest caveat: inline review is *self-review*. It sees the
143
- session's own reasoning, so it cannot be surprised by it the way a cold subagent read can.
144
- Treat an inline APPROVE as weaker evidence than a delegated one.
166
+ 3. **Without the extension, lean and standard still work completely inline.** That remains a
167
+ supported baseline. Inline review is self-review and weaker than a cold read. Critical
168
+ assurance does not pretend otherwise: if no governed fresh-context executor exists for its
169
+ critique and independent reviews, it returns `BLOCKED_CRITICAL_ASSURANCE` rather than
170
+ silently degrading to inline self-review.
145
171
  4. **`AGENTS.md` is not installed as routing context.** pi packages register skills and
146
172
  prompts; they do not load a routing file into every session. It ships in the package and
147
173
  is worth reading, but nothing loads it for you — if you want the orchestrator to route by
@@ -150,10 +176,12 @@ docs/demos/ the chains running end to end, repo-verifi
150
176
 
151
177
  ### What a clean install actually gives you
152
178
 
153
- - The seven skills and both workflow commands, running **inline**. That is the baseline
154
- product, and it is complete.
155
- - Subagents only if you did step 2 — they are an improvement in context isolation and cold
156
- judgment, not a requirement.
179
+ - The seven skills and both workflow commands, with lean/standard running **inline** as a
180
+ complete baseline.
181
+ - Subagents only if you did step 2 — optional for lean/standard, but one way to satisfy the
182
+ fresh-context controls explicit critical assurance requires.
183
+ - `principal-pi-assurance`, a parent/controller CLI that stores a hash-chained event log and
184
+ derived snapshot outside the product tree. It adds no public skill name.
157
185
  - `/principal-feature` and `/principal-bugfix` as the supported commands. `/feature` and
158
186
  `/bugfix` still work but are **deprecated aliases**: a bare name is a slot any installed
159
187
  package can claim, and the last one loaded wins silently.
@@ -185,6 +213,33 @@ verify both files had been *touched*, never that they still agreed.
185
213
  and carries no template: it runs inline and terminates a chain, so a handoff token would
186
214
  have nothing to hand to. Its delegated block was removed in 2.3.0 as dead ceremony.
187
215
 
216
+ The two namespaced workflows and deprecated aliases are generated as complete prompts from
217
+ `contracts/workflows.md.tmpl`; aliases do not depend on recursive slash-command expansion, and the
218
+ shared assurance section is byte-identical by construction. Workflow state is not prose:
219
+ `principal-pi-assurance` validates the v1 schemas, appends hash-chained JSONL events, derives
220
+ `snapshot.json`, rejects illegal downgrades/transitions, and gates stale evidence or missing
221
+ critical controls. In git it stores under the common directory
222
+ (`.git/principal-pi-skills/assurance-v1`), otherwise under XDG state. Build remains the only
223
+ durable source writer. See [docs/ASSURANCE.md](./docs/ASSURANCE.md).
224
+
225
+ ## Assurance profiles
226
+
227
+ Both namespaced workflows accept:
228
+
229
+ ```
230
+ --assurance lean|standard|critical
231
+ --critical-scope "entire-run|task-2,task-4|db/migrations/**,src/auth/**"
232
+ ```
233
+
234
+ `standard` is the compatible default and `high` aliases `critical`. “Treat this as critical”
235
+ and “escalate this run to critical” persist the same state. Lean keeps the tiny/reversible
236
+ path. Standard keeps Option B. Critical adds approved design for consequential work,
237
+ independent plan critique before task packets, an owned branch worktree, per-task specification
238
+ and quality reviews in separate fresh contexts rooted at that writer checkout, a final whole-change
239
+ review after task evidence, fresh full evidence, and just-in-time approval for external effects.
240
+ Git-Ops records final branch/head/tree between readiness and completion gates. Critical never silently falls back;
241
+ unavailable isolation or fresh contexts returns `BLOCKED_CRITICAL_ASSURANCE`.
242
+
188
243
  ## See it run
189
244
 
190
245
  Three end-to-end runs, verified against the repository afterwards rather than taken from
@@ -201,41 +256,35 @@ the model's own account:
201
256
 
202
257
  ## Validation
203
258
 
204
- Every skill carries a `tests/specification.yaml` of scenarios with pass criteria, and the
205
- results are committed. The measurement: **98 scenarios across the seven skills, every
206
- scenario run three times** on DeepSeek v4-pro and GLM 5.2, judged by `claude-code:opus`, with
207
- objective gates (vitest runs, diff assertions) decided before the judge is consulted. A
208
- scenario passes at a majority of its clean reps, so a cell is a pass-rate rather than a
209
- single draw. The scored deployment is skill-as-system-prompt (`--mode force`) — the delivery
210
- modern pi makes deterministic, and the way the `agents/` variants already run.
211
- **kimi-k3 was never tuned against** — it is the control for overfitting, and is an optional
212
- follow-up rather than a published column in the current round.
213
-
214
- | Skill | DeepSeek v4-pro | GLM 5.2 | kimi-k3 |
215
- |---|---|---|---|
216
- | architect | 13/14 · 93% | **14/14 · 100% SHIP** | — *(deferred)* |
217
- | build | **9/9 · 100% SHIP** | **9/9 · 100% SHIP** | — *(deferred)* |
218
- | debug | 9/11 · 82% | **11/11 · 100% SHIP** | — *(deferred)* |
219
- | decide | **12/12 · 100% SHIP** | **12/12 · 100% SHIP** | — *(deferred)* |
220
- | git-ops | 18/19 · 95% | **19/19 · 100% SHIP** | — *(deferred)* |
221
- | plan | 8/12 · 67% | **12/12 · 100% SHIP** | — *(deferred)* |
222
- | review | **21/21 · 100% SHIP** | **21/21 · 100% SHIP** | — *(deferred)* |
223
-
224
- **All seven skills ship on at least one model.** `decide` is new to that list — it
225
- previously held at 92% on every model, failing exactly one boundary scenario each, and shipped
226
- nowhere; it is now 12/12 on both. `build` went 7/9 → 9/9 on DeepSeek.
227
-
228
- `plan` is the one to read carefully: **12/12 on GLM against 8/12 on DeepSeek**, on identical
229
- text. The skill is not weak, it is weak on one model — and its boundary cells move between
230
- runs, so treat a single `plan`/DeepSeek cell as one draw rather than a measurement.
231
-
232
- **kimi-k3 is deferred, not dropped.** It is the untuned control for overfitting, so until it
233
- runs there is no evidence about generalization beyond the two models these skills were tuned
234
- against — the two most likely to flatter them. Its cells are tracked in
235
- [unpublished-cells.txt](docs/validation/unpublished-cells.txt), and CI fails if an entry there
236
- outlives its reason, so it cannot be quietly forgotten.
237
- [VALIDATION.md](docs/validation/VALIDATION.md) has the failing cells and why each is published
238
- at rate rather than tuned away.
259
+ The exploratory Terra-high Wave 0 contains a control, an unpinned-executor infrastructure
260
+ failure, and a subprocess-pinned run whose treatment delivery is unproven. None participates
261
+ in efficacy, stability, release, or v3 scoring. No committed pi-daddy observation has the
262
+ required externally produced per-observation attestation, so its current valid-treatment
263
+ count is **zero**. Future treatment requires a closed arm policy, strict canonical result,
264
+ eagerly validated arm-bound trust store, exact observation/attestation bijection, and atomic
265
+ corpus-level replay check. Durable operational replay prevention remains external. The
266
+ DeepSeek/GLM v3 wave and live workflow cells remain unrun.
267
+
268
+ `principal-pi-skills` is only a classifier, evidence-policy consumer, and verifier of
269
+ operator-trusted external attestations. It does not securely execute subjects, protect
270
+ signing keys, authenticate producer ledgers, confine modules or process trees, or provide an
271
+ OS sandbox/same-UID boundary. A valid signature proves that the configured producer made the
272
+ attestation; it does not prove that producer is securely implemented. See
273
+ [`docs/validation/VALIDATION.md`](docs/validation/VALIDATION.md).
274
+
275
+ v3 changes model-visible contract text, adds one `E1` assurance scenario to each skill, and adds
276
+ a Git-Ops stale-receipt negative, taking the static specification from 98 to **106 scenarios**.
277
+ Those eight scenarios are prepared but
278
+ have **not** been model-run; no paid skill-harness or live E2E validation was authorized, and
279
+ `3.0.0` was released on that basis deliberately rather than by oversight.
280
+ Consequently v3 publishes no model score yet. The committed DeepSeek/GLM board remains a
281
+ historical v2.4 baseline, not evidence for the v3 prompts. `docs/validation/VALIDATION.md`
282
+ records that boundary and the commands for a future measured wave.
283
+
284
+ The free gate is `npm test`: generated-contract/workflow drift, state-machine and schema
285
+ transitions, install/packed-artifact behavior, worktree isolation, word budgets, and
286
+ skill-harness lint. Live workflow E2E now defines standard/critical × feature/bugfix ×
287
+ subagents present/absent; it is prepared but not run here because it spends model tokens.
239
288
 
240
289
  ## Deliberate design rules
241
290
 
package/agents/debug.md CHANGED
@@ -11,7 +11,7 @@ allowed-tools: read, grep, find, ls, bash
11
11
 
12
12
  # Debug — Hypothesis Before Fix
13
13
 
14
- 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
15
15
  final message.** Work across as many tool calls and intermediate messages as the bug
16
16
  needs — none of that reaches anyone. Your last message must therefore BE the complete
17
17
  debugging note, every field, as one block — restated in full even if you already wrote
@@ -41,7 +41,9 @@ unknown one; the harder the bug, the stricter the loop.
41
41
  5. **Prove the fix at the root cause — still in the workspace.** The stack trace points at
42
42
  the symptom; trace the wrong value upstream and fix there. The regression test fails
43
43
  before the fix and passes after; re-run the full suite and the original reproduction.
44
- 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.
45
47
  **In a workflow you report the fix and do not leave it behind** — `build` implements it
46
48
  once, in the caller's checkout, where they can watch it land. **Asked directly to fix it,
47
49
  fix it.** "Diagnose this and fix it" is a request, not a handoff; withholding a repair the
@@ -101,6 +103,8 @@ speculative edits with no traction, you are in a hard bug: return to step 1.
101
103
  Reproduction: <command or test that triggers it, or "NOT REPRODUCED: <why>">
102
104
  Isolated to: <smallest input / commit range>
103
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
104
108
  Root cause: <file:line + why>
105
109
  Fix: <the minimal change, at the cause not the symptom — proposed, not applied>
106
110
  Regression test: <name; failed before fix, passes after>
package/agents/plan.md CHANGED
@@ -33,8 +33,8 @@ A plan that bottoms out in "add validation" is not a plan; each step names files
33
33
  behavior, and the test that proves it.
34
34
 
35
35
  ## Process
36
- 1. **State the outcome** in one measurable sentence ("users can reset passwords without
37
- 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.
38
38
  2. **Read the code before planning it.** Open every file you will name, the callers of
39
39
  anything that changes, the nearest test. Note the codebase's conventions — naming,
40
40
  error style, test layout — the plan follows them, not your defaults. Never present a
@@ -64,6 +64,37 @@ behavior, and the test that proves it.
64
64
  [ONE-WAY] step (schema migration, public API change, data deletion) with a rollback note
65
65
  and a kill criterion.
66
66
 
67
+ ## Critical plan contract
68
+ These rules apply only to Critical scope; non-Critical plans keep the right-sized forms below.
69
+ Critical plans never abbreviate. Before `Steps:`, emit concrete `Authority:`, `Global constraints:`,
70
+ `Out of scope:`, and a `Critical scope:` summary, then `Assumptions:` and `Task-packet handoff:`.
71
+ Every task repeats its concrete `Critical scope:` match and emits `Task ID:`, `Files:`,
72
+ `Dependencies:`, `Change:`, `Test:`, `Done command:`, `Expected result:`, `Review risk:`, and
73
+ `Ripples:` values.
74
+
75
+ Every Critical task names a stable test file and test name; test level and edge cases remain explicit.
76
+ `Done command:` is one literal, targeted, proposed repository-local verification invocation selecting
77
+ that file or test name, with the expected result in its separate field. It is declarative, untrusted
78
+ Plan output—not execution authorization—and is never automatically executed by Plan or packet
79
+ persistence. Downstream Build must inspect it against the repository before choosing whether to
80
+ execute it; this version provides no deterministic command or approval enforcement. Do not emit `TBD`, angle-bracket tokens, bare `node --test`, generic
81
+ “run tests” prose, or another broad untargeted command.
82
+
83
+ When repository context supplies real paths, tests, and commands, use those exact observed values.
84
+ When context is absent, propose concrete paths, names, and commands under clearly labelled
85
+ Assumptions requiring validation; never claim they were observed. Runtime enforcement of command
86
+ syntax, discovery identity, authority digests, and event-log migration is deferred to a future
87
+ versioned runtime contract and is not claimed here.
88
+
89
+ The controller—not Plan—owns packet persistence. Plan defines task content and stable `task_id`;
90
+ the controller supplies `schema_version`, `run_id`, `workspace_id`, `plan_digest`, and
91
+ `definition_digests`. Include that distinction in `Task-packet handoff:` without inventing
92
+ controller-owned identities or digests.
93
+
94
+ Every task remains a vertical behavioral slice delivering an independently testable user or system
95
+ outcome. Critique, packet persistence, review, handoff, and test-only ceremony are controller work,
96
+ not delivery slices; never add one as a final task.
97
+
67
98
  ## Right-sizing
68
99
  A one-file, clearly-specified change (a config value, a small flag): reply in three lines —
69
100
  the change, its test, done. Literally this shape, and nothing after it:
@@ -87,22 +118,43 @@ per slice is fine: `1. Skeleton: real request→store→respond path, primitive
87
118
  the one output this agent never produces.
88
119
 
89
120
  ## Output — plan
90
- This template is for multi-step work. A trivial reversible change never gets it — its
91
- entire plan is three lines: the change, the test, done. Small clear work (one flag, one
92
- helper, one endpoint) gets the middle form: two or three slices with a done-signal each,
93
- and nothing else — no Risks block, no spike, no [after:]/parallel annotations; the step
94
- numbers are the order. Not knowing the codebase is an Assumptions line, not a risk. A
95
- real [ONE-WAY] is the one field that always survives.
121
+ Output **task definitions**: authority/constraints/scope, files/dependencies, behavior/test, done
122
+ command, and review risk. The controller adds run/workspace IDs and current digests, validates the
123
+ task-packet schema, and persists; Plan never invents them. Critical always emits a task definition
124
+ but omits unrelated ceremony.
125
+
126
+ Critical work follows the exact Critical contract above and does not copy the generic template.
127
+ For non-Critical multi-step work, use the template below. Trivial reversible work gets three lines:
128
+ change, test, done. Small clear work gets two or three slices with a done-signal; omit Risks, spikes,
129
+ and dependency annotations because step order suffices. Unknown codebase facts are Assumptions. A
130
+ real [ONE-WAY] always survives.
96
131
  ```
97
132
  ## Plan: <outcome, one sentence>
133
+ Authority: <requirement IDs, approved design, or exact user request>
134
+ Global constraints: <limits every task must preserve>
135
+ Out of scope: <explicit exclusions> | none
98
136
  Conventions observed: <naming / error / test patterns found in the codebase>
99
137
  Risks: <risk → mitigation or spike step>
100
138
  Steps:
101
139
  1. Walking skeleton — <thinnest real path through every named seam> — proves: <each seam, exercised for real>
140
+ Task ID: task-1
141
+ Critical scope: <why this task matches> | not critical
142
+ Files: <paths>
143
+ Dependencies: none
144
+ Change: <signatures + exact behavior>
145
+ Test: <name, level, edge cases>
146
+ Done command: <exact command + expected result>
147
+ Review risk: <highest-risk behavior reviewers must attack>
148
+ Ripples: <callers, config, migrations> | none
102
149
  2. <step name> [after: 1] [ONE-WAY: <rollback + kill criterion>]
150
+ Task ID: <stable ID>
151
+ Critical scope: <matched task/path selector> | not critical
103
152
  Files: <paths>
153
+ Dependencies: <task IDs> | none
104
154
  Change: <signatures + exact behavior>
105
155
  Test: <name, level, edge cases>
156
+ Done command: <exact command + expected result>
157
+ Review risk: <risk or boundary>
106
158
  Ripples: <callers, config, migrations> | none
107
159
  3. …
108
160
  Parallel-safe: <which steps> | none
@@ -128,4 +180,5 @@ Have: <what the material did establish — one line>
128
180
  | Accept "plan it as one step" for multi-part work | Decompose anyway and say why: one giant step blocks parallel work, hides risk, and has no honest done-signal. |
129
181
  | Write a step like "add validation" or "handle errors" | Make it a contract: files, exact behavior, the test. If you can't name the test, it's too vague. |
130
182
  | Spec a file you haven't opened | Open it. A spec for a fiction wastes everyone's time. |
131
- | Leave the tests as the builder's homework | Name each test, its level, and its edge cases in the step. |
183
+ | Leave a Critical task's tests as the builder's homework | Name each test file and test case, its level, edge cases, and safe literal targeted command. |
184
+ | Add an assurance-only Critical task or final review/test/handoff slice | Keep behavioral delivery vertical; the controller owns discovery, critique, packet persistence, review, and handoff. |