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 +25 -6
- package/CHANGELOG.md +135 -2
- package/README.md +115 -74
- package/agents/debug.md +8 -2
- package/agents/plan.md +29 -8
- package/agents/principal-debug.md +8 -2
- package/agents/principal-plan.md +29 -8
- package/agents/principal-review.md +34 -21
- package/agents/review.md +34 -21
- package/architect/SKILL.md +6 -1
- package/build/SKILL.md +21 -3
- package/debug/SKILL.md +6 -1
- package/decide/SKILL.md +2 -0
- package/git-ops/SKILL.md +11 -0
- package/package.json +11 -4
- package/plan/SKILL.md +29 -8
- package/prompts/bugfix.md +141 -10
- package/prompts/feature.md +141 -10
- package/prompts/principal-bugfix.md +140 -43
- package/prompts/principal-feature.md +140 -45
- package/review/SKILL.md +34 -21
- package/schemas/assurance-evidence-receipt-v1.schema.json +48 -0
- package/schemas/assurance-run-state-v1.schema.json +307 -0
- package/schemas/assurance-task-packet-v1.schema.json +91 -0
- package/scripts/assurance-state.mjs +1840 -0
- package/scripts/snapshot-workspace.mjs +96 -32
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`.
|
|
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@
|
|
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
|
|
114
|
-
|
|
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
|
|
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 ~
|
|
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
|
|
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 |
|
|
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 |
|
|
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`,
|
|
52
|
-
| `build` | Test-first implementation — code proven by a test you watched fail | inline |
|
|
53
|
-
| `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`,
|
|
54
|
-
| `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`,
|
|
55
|
-
| `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated |
|
|
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
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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@
|
|
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
|
|
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).**
|
|
96
|
-
|
|
97
|
-
|
|
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`
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
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
|
|
132
|
-
|
|
133
|
-
- Subagents only if you did step 2 —
|
|
134
|
-
|
|
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
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
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
|
|
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
|
|
36
|
-
|
|
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
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
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
|
|
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>
|