principal-pi-skills 2.4.0 → 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,7 +119,9 @@ 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
127
  2. Subagents need pi-mono's subagent extension (`examples/extensions/subagent`, which ships
package/CHANGELOG.md CHANGED
@@ -6,6 +6,83 @@ 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
+
9
86
  ## [2.4.0] — 2026-08-17
10
87
 
11
88
  **Added** — every skill now declares an `allowed-tools` capability ceiling, which
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 | 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 |
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,10 +69,13 @@ 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)
72
79
  tests/e2e/run-e2e.sh live workflow cells: both spines, with and without subagents
73
80
  <skill>/tests/specification.yaml skill-harness scenarios (ship bar, critical gates)
74
81
  <skill>/tests/fixtures/<ID>/ seeded repo for one scenario (git-ops, build, debug)
@@ -86,9 +93,16 @@ docs/demos/ the chains running end to end, repo-verifi
86
93
  1. **Skills + prompts** — install an immutable tag, not a branch:
87
94
 
88
95
  ```
89
- pi install git:github.com/mojomanyana/principal-pi-skills@v2.3.1
96
+ pi install git:github.com/mojomanyana/principal-pi-skills@v3.0.0
90
97
  ```
91
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
+
92
106
  **Do not install `2.3.0`** — it is deprecated on npm for a destructive defect: its
93
107
  `principal-pi-workspace remove` deletes any path handed to it, including your checkout,
94
108
  and reports success. `2.3.1` is the lowest safe version.
@@ -96,7 +110,7 @@ docs/demos/ the chains running end to end, repo-verifi
96
110
  The `pi` manifest registers the seven skills and the `/principal-feature` and
97
111
  `/principal-bugfix` commands (plus the deprecated `/feature` and `/bugfix` aliases).
98
112
  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
113
+ measured, and a tag is what keeps those two the same thing. Drop the version pin only if
100
114
  you want whatever `main` currently holds, measured or not.
101
115
  2. **Subagents (optional).** The extension ships **inside pi itself**, so there is nothing
102
116
  to clone. Copy its `index.ts` and `agents.ts` into `~/.pi/agent/extensions/subagent/`
@@ -125,23 +139,26 @@ docs/demos/ the chains running end to end, repo-verifi
125
139
  `--with-generic-aliases`.
126
140
 
127
141
  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.
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).
129
144
 
130
145
  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.
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.
134
151
 
135
152
  One trap worth knowing if you run subagents on a non-default provider: the extension
136
153
  passes `--model` to the child `pi` only when an agent's frontmatter names one. Ours
137
154
  deliberately do not, so a delegated agent uses your pi config's `defaultProvider` /
138
155
  `defaultModel` — **not** whatever `--provider`/`--model` you passed the parent. If
139
156
  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.
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.
145
162
  4. **`AGENTS.md` is not installed as routing context.** pi packages register skills and
146
163
  prompts; they do not load a routing file into every session. It ships in the package and
147
164
  is worth reading, but nothing loads it for you — if you want the orchestrator to route by
@@ -150,10 +167,12 @@ docs/demos/ the chains running end to end, repo-verifi
150
167
 
151
168
  ### What a clean install actually gives you
152
169
 
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.
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.
157
176
  - `/principal-feature` and `/principal-bugfix` as the supported commands. `/feature` and
158
177
  `/bugfix` still work but are **deprecated aliases**: a bare name is a slot any installed
159
178
  package can claim, and the last one loaded wins silently.
@@ -185,6 +204,33 @@ verify both files had been *touched*, never that they still agreed.
185
204
  and carries no template: it runs inline and terminates a chain, so a handoff token would
186
205
  have nothing to hand to. Its delegated block was removed in 2.3.0 as dead ceremony.
187
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
+
188
234
  ## See it run
189
235
 
190
236
  Three end-to-end runs, verified against the repository afterwards rather than taken from
@@ -201,41 +247,19 @@ the model's own account:
201
247
 
202
248
  ## Validation
203
249
 
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.
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.
239
263
 
240
264
  ## Deliberate design rules
241
265
 
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
@@ -87,22 +87,42 @@ per slice is fine: `1. Skeleton: real request→store→respond path, primitive
87
87
  the one output this agent never produces.
88
88
 
89
89
  ## 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.
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.
96
99
  ```
97
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
98
104
  Conventions observed: <naming / error / test patterns found in the codebase>
99
105
  Risks: <risk → mitigation or spike step>
100
106
  Steps:
101
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
102
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
103
120
  Files: <paths>
121
+ Dependencies: <task IDs> | none
104
122
  Change: <signatures + exact behavior>
105
123
  Test: <name, level, edge cases>
124
+ Done command: <exact command + expected result>
125
+ Review risk: <risk or boundary>
106
126
  Ripples: <callers, config, migrations> | none
107
127
  3. …
108
128
  Parallel-safe: <which steps> | none
@@ -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>
@@ -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
@@ -87,22 +87,42 @@ per slice is fine: `1. Skeleton: real request→store→respond path, primitive
87
87
  the one output this agent never produces.
88
88
 
89
89
  ## 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.
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.
96
99
  ```
97
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
98
104
  Conventions observed: <naming / error / test patterns found in the codebase>
99
105
  Risks: <risk → mitigation or spike step>
100
106
  Steps:
101
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
102
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
103
120
  Files: <paths>
121
+ Dependencies: <task IDs> | none
104
122
  Change: <signatures + exact behavior>
105
123
  Test: <name, level, edge cases>
124
+ Done command: <exact command + expected result>
125
+ Review risk: <risk or boundary>
106
126
  Ripples: <callers, config, migrations> | none
107
127
  3. …
108
128
  Parallel-safe: <which steps> | none