principal-pi-skills 4.6.0 → 4.7.2

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
@@ -30,8 +30,8 @@ The set:
30
30
 
31
31
  | Input shape | Route to | How |
32
32
  |---|---|---|
33
- | Exploring a decision, not executing one ("should I…", "what are my options", "I'm stuck") | `decide` | inline — the dialogue is the value |
34
- | A system to design or a significant/irreversible choice ("design X", "Postgres or DynamoDB", "review our architecture") | `architect` | inline — drivers come from asking |
33
+ | Choice and rationale ("should I…", "Postgres or DynamoDB", "what are my options") | `decide` | inline — the dialogue is the value |
34
+ | System structure, components, boundaries or data ("design X", "review our architecture") | `architect` | inline — drivers come from asking |
35
35
  | A task needing order of work and code-level specs ("plan this", "break this down") | `plan` | **subagent** — it opens every file it names; keep that out of this context |
36
36
  | Code to write ("implement", "fix this known bug", "make the test pass") | `build` | inline, or `principal-build` per approved plan step when the subagent tool exists — never fan parallel writers into one working tree |
37
37
  | A change to judge before landing ("review this", "ready to merge?") | `review` | **subagent, always when available** — a fresh context judging the diff cold beats self-review; inline review of code you just wrote is anchored on its own reasoning |
@@ -39,21 +39,25 @@ The set:
39
39
  | Facts about current code, data, runtime, or history ("how does", "where is", "map", "what changed between") | `investigate` | **subagent** for heavy reading; inline when dialogue is needed |
40
40
  | A git or GitHub operation ("commit", "push", "open a PR", "I leaked a secret") | `git-ops` | inline, never delegated — needs this session's working-tree state, and destructive ops require user consequence-acceptance no subagent can obtain |
41
41
 
42
- **When more than one applies**, route by altitude: the highest-altitude match for the
43
- *actual* request, not the surface phrasing. "Redis or Memcached?" is `architect`; "how do
44
- I commit this" is `git-ops`, not `build`; "why is this test red" is `debug`, not `build`.
42
+ **When more than one applies**, route by requested output: choice/rationale → `decide`,
43
+ structure → `architect`, executable sequence → `plan`. "Redis or Memcached?" is `decide`;
44
+ "how do I commit this" is `git-ops`, not `build`; "why is this test red" is `debug`, not `build`.
45
+ Use only needed phases, not a mandatory chain. Optional read-only Investigate can locate
46
+ sources/definitions before Plan or substantial Review; pass original sources too, and leave
47
+ the verdict to Review.
45
48
 
46
49
  **When no skill fits**, don't force one. Everyday Q&A doesn't need the framework.
47
50
 
48
51
  ## The handoff contract
49
52
 
50
53
  The phases that hand off end with a `Next:` line naming the follow-on. That plus the fixed
51
- template fields *is* the handoff. You read the `Next:` line and route — a subagent never
52
- invokes another agent; inline, continuing into the named skill in this same context is
53
- orchestration, not a skill invoking another.
54
+ template fields *is* the handoff. Read Review Verdict before Next: UNVERIFIED means
55
+ evidence/access repair or a caller question, not automatic implementation, even with
56
+ `Next: build`. Otherwise read the `Next:` line and route — a subagent never invokes
57
+ another agent; inline continuation is orchestration, not a skill invoking another.
54
58
 
55
- `Next:` carries exactly one bare word from a closed set, so routing is a lookup rather than
56
- an interpretation. The complete set:
59
+ `Next:` carries exactly one bare word from a closed set; after that verdict check,
60
+ routing is a lookup rather than an interpretation. The complete set:
57
61
 
58
62
  | Phase | Allowed `Next:` values |
59
63
  |---|---|
@@ -74,7 +78,7 @@ Typical spines (available as prompt templates):
74
78
 
75
79
  - Feature (`/principal-feature <task>`): plan → approval stop → build (inline or
76
80
  delegated) → review → git-ops finish. Enter `architect`/`decide` first when the call is
77
- architectural or still contested.
81
+ requesting structure or a choice respectively, and approve that output first.
78
82
  - Bug (`/principal-bugfix <symptom>`): debug → approval stop → build → review → git-ops
79
83
  finish. If debug's note says design flaw, stop and surface it.
80
84
  - Refactor (`/principal-refactor <scope>`): the feature spine with a no-behavior-change
@@ -91,6 +95,20 @@ Typical spines (available as prompt templates):
91
95
  - Tiny change: build → git-ops, both inline — every contract carries a Right-sizing
92
96
  rule; don't add ceremony the file itself would refuse.
93
97
 
98
+ Before any orchestrator artifact write (including planless Review, inline Build or optional
99
+ Investigate persistence), create an absent `.principal/.gitignore` containing `*`, never
100
+ overwrite an existing ignore file, and verify repository report destinations are ignored;
101
+ otherwise stop for caller policy repair. Plan retains its restricted writes; Investigate
102
+ remains read-only. Scope reports by task/run/candidate in new unused directories, preserving
103
+ prior files and original review path/candidate/baseline through repairs and resume.
104
+
105
+ Handoffs carry accessible source/definition references, applicable map rows/global gates,
106
+ and full report paths, not summaries or bare finding IDs. Collect caveats even on success;
107
+ a commit or green suite alone is not full requirement coverage. Review validates candidate-bound
108
+ evidence independently. Plans persist completely with short chat summaries. Debug's sandbox
109
+ proof is not applied work; a direct diagnose-and-fix request continues through an announced
110
+ switch to Build, while the bugfix workflow retains its approval stop.
111
+
94
112
  A delegated step returning `BLOCKED` stops the chain: surface its one question to the
95
113
  user; don't answer it yourself and keep going.
96
114
 
@@ -101,10 +119,10 @@ and `agents/principal-<name>.md` (the single-shot contract subagents get) — di
101
119
  artifacts, not copies, but most of each pair is identical, and that shared majority is
102
120
  where they used to drift.
103
121
 
104
- Both are generated from `contracts/<name>.md.tmpl`. The two namespaced workflows are
105
- likewise generated from `contracts/workflows.md.tmpl` — five contracts plus the workflows
106
- template are the source of everything under `agents/`, `prompts/`, and the five dual-use
107
- `SKILL.md` files. Change shared behavior ONCE, there, then `npm run generate`. Editing a
122
+ Both are generated from `contracts/<name>.md.tmpl`. The three spine workflows are
123
+ likewise generated from `contracts/workflows.md.tmpl` — five contracts plus one workflows
124
+ template produce five agents, five dual-use `SKILL.md` files and three prompts (13 outputs).
125
+ `prompts/principal-review-branch.md` is handwritten. Change shared behavior ONCE, there, then `npm run generate`. Editing a
108
126
  generated file directly is reverted by the next run and fails `npm run generate:check` in
109
127
  CI.
110
128
 
@@ -113,15 +131,28 @@ rules, `{{#agent}}` for single-shot mechanics — the BLOCKED form, the
113
131
  assumptions-not-questions rule, the final-message-only rule. Anything outside a block goes
114
132
  to every output.
115
133
 
134
+ When maintaining this package, put lasting regressions in existing behavior/domain suites,
135
+ not PR-named files. `npm test` checks current contracts and product behavior.
136
+ Behavioural measurement—including the fidelity corpus and skill-harness evidence—lives in [principal-pi-skills-evals](https://github.com/mojomanyana/principal-pi-skills-evals); routing checks live here.
137
+
116
138
  ## Setup (pi)
117
139
 
118
- 1. `pi install git:github.com/mojomanyana/principal-pi-skills@v4.6.0` installs the eight
140
+ 1. `pi install git:github.com/mojomanyana/principal-pi-skills@v4.7.2` installs the eight
119
141
  skills, the four `/principal-*` commands, and the bootstrap
120
142
  extension, which loads automatically with the package. Install a tag, not a branch.
121
- 2. Subagents (optional): `npx -p principal-pi-skills principal-pi-agents install` copies
122
- the five agent definitions into `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents` and refuses
123
- to overwrite anything it did not install. Without it, everything in the routing table
124
- above still runs; the How column just collapses to "inline".
143
+ 2. Subagents (optional): before npm publication, latest is 4.7.1 and npm @4.7.2 is not
144
+ yet available. Use the installed tagged package's `scripts/install-agents.mjs` with Node
145
+ (`install`, then `check`), locating its actual path rather than assuming a universal Pi
146
+ install directory. Alternatively follow the concrete verified-tag disposable checkout
147
+ recipe in [README Install](README.md#install-pi). After npm publication, pin both:
148
+ `npx -p principal-pi-skills@4.7.2 principal-pi-agents install` and
149
+ `npx -p principal-pi-skills@4.7.2 principal-pi-agents check`.
150
+ The five definitions go to `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents`; foreign files
151
+ are refused. Without them, the routing table still runs inline.
152
+ Version 4.7.2 moves behavioral measurement to `principal-pi-skills-evals` while routing
153
+ checks remain here. Tag creation and npm publication are separate: before the new tag exists,
154
+ validate the actual candidate's skills and installer
155
+ in isolation. Recorded model/evidence limitations remain; a release tag does not erase them.
125
156
  3. Context handoff (pi-daddy 0.33.0+): each skill's `allowed-tools` sets how much of this
126
157
  session a delegated child may receive. `architect`, `decide` and `plan` allow
127
158
  `context:summary`. `build`, `debug`, `review` and `investigate` allow `context:files`: review
package/CHANGELOG.md CHANGED
@@ -6,6 +6,99 @@ Where review revealed a prior claim or design decision didn't hold up under clos
6
6
 
7
7
  ---
8
8
 
9
+ ## [4.7.2] — 2026-10-01
10
+
11
+ **Changed — behavioral measurement moved out (#59).** The requirement-fidelity corpus,
12
+ skill-harness specifications and results, retained evidence, replay tooling, and their
13
+ repository tests now live in
14
+ [principal-pi-skills-evals](https://github.com/mojomanyana/principal-pi-skills-evals).
15
+ Routing inputs and baselines remain here, and `npm test` now covers only current product and
16
+ contract behavior; previously this repository also retained the behavioral corpus and
17
+ historical evidence checks.
18
+
19
+ **Reaffirmed — the 4.0.1 boundary.** Behavioral measurement belongs in the external
20
+ measurement repository rather than this runtime package. PR #59 applies that original 4.0.1
21
+ decision to the later requirement-fidelity material instead of maintaining a local exception.
22
+ No skill, agent, prompt, bootstrap, or generated contract text changed.
23
+
24
+ ## [4.7.1] — 2026-10-01
25
+
26
+ **Combined release candidate — all requirement-fidelity work and repairs (#58).** This
27
+ version contains the complete PR #58 feature described under 4.7.0 below, plus all subsequent
28
+ review and handoff repairs. The early `v4.7.0` tag at `448ac76` remains an immutable historical
29
+ candidate; it excludes later repairs. One new annotated `v4.7.1` tag identifies the final merged
30
+ tree, with package metadata and installation pins aligned. GitHub/npm publication is separate.
31
+
32
+ **Changed — safe, retrievable handoffs (#58).** Build now requires complete saved candidate
33
+ patches with private collision-safe paths, byte hashes and source identities; previously a
34
+ printed diff hash could leave the actual tested patch unavailable. Inherited material caveats
35
+ now survive or receive explicit disposition, and evidence references use current per-file
36
+ ranges. Safely saved complete inline reports now support concise summaries with visible
37
+ unresolved caveats; previously inline field requirements conflicted with short file-backed
38
+ replies. The delegated five-line return remains distinct and unchanged.
39
+
40
+ **Fixed — authority, artifact and workflow boundaries (#58).** Complete explicitly authorized
41
+ amendments now differ from guessed missing definitions; report writes now verify ignore policy
42
+ without overwriting existing rules; artifact namespaces avoid replacing prior findings; and
43
+ routing checks Review verdict before Next. Previously those boundaries could permit guessed
44
+ semantics, exposed/overwritten reports or improper repair routing. Captured read ordering and
45
+ replay lifecycle checks now reject the reviewed false-success cases. Tagged skills and agent
46
+ installation now use matching sources instead of an unpinned older npm package.
47
+
48
+ **Changed — evidence scope and honest validation (#58).** Evidence requests now prefer existing
49
+ checks/disposable probes rather than implicitly authorizing permanent infrastructure; ordinary
50
+ bugfixes still include enduring regressions. Product/install checks and opt-in archive checks
51
+ are separate. Historical raw failures, provider errors, source identities and old rubrics remain
52
+ unchanged; the current corpus has 46 cases, not a retroactive regrade of the earlier inventory.
53
+
54
+ **Validation — accepted bounded improvement, not full behavioral qualification.** Local checks
55
+ pass 153 unit and 24 install tests, plus 86 separate evidence checks. Latest Build force is
56
+ **4/9 NOT READY**. Three full captures verify actual red/green execution and saved patches, but
57
+ F11 still omits material caveats from its short reply and misses the literal persistence-stop
58
+ rule; collision robustness and F04 runtime reporting remain limited. Independent reviews approve
59
+ this documented increment, not a reliability guarantee. See
60
+ `evals/requirement-fidelity/evidence/build-handoff/README.md`. No release combines these results
61
+ into an all-PASS claim or proves normal loading/delegation, deployment or lower-cost robustness.
62
+
63
+ ## [4.7.0] — 2026-09-30
64
+
65
+ **Changed — preserve requirements across skill handoffs (#58).** Plan now reads original
66
+ specifications and referenced definitions, preserves requirement identities separately from
67
+ implementation steps, and maps numbered requirements, unnumbered MUSTs and qualification
68
+ gates to steps and tests. Missing normative definitions now require handoff repair;
69
+ previously the assumption and no-stalling rules could permit guessed meanings. Complete
70
+ multi-step plans now live in files with short chat summaries; previously the contract
71
+ required duplicating the full plan in chat.
72
+
73
+ **Changed — source-bound implementation and review (#58).** Build and Review now carry
74
+ source references, requirement/gate status and tested-candidate identity. Workflows persist
75
+ complete inline Build reports as well as delegated reports and carry finding definitions
76
+ into repair; previously summaries, bare finding IDs and unbound test totals could lose
77
+ requirements or evidence gaps. Compression now preserves applicable evidence and caveats.
78
+
79
+ **Changed — selective skill composition (#58).** Investigate can supply optional factual
80
+ source discovery without choosing authority or replacing the source. Routing now consistently
81
+ sends choices to Decide, structure to Architect, and implementation order to Plan;
82
+ previously some workflow/bootstrap examples sent bare technology choices to Architect.
83
+ Decide and Architect now preserve binding constraints and expose load-bearing unknowns;
84
+ Debug distinguishes proposed fixes, disposable proofs and changes actually applied by Build.
85
+ Git-Ops safeguards and all tool/context ceilings are unchanged.
86
+
87
+ **Added — durable, opt-in regression evidence (#58).** A focused local corpus now retains
88
+ 42 behavioral cases, a 76 KB specification with 51 obligation/gate entries, original model
89
+ results and captured artifacts. Previously focused harness scenarios were excluded from
90
+ this repository and the initial Plan checks were deleted. Model calls remain outside
91
+ `npm test`; fixtures and evidence remain outside the npm package.
92
+
93
+ **Validation — implementation reviewed, behavioral qualification incomplete.** The full
94
+ suite passes 128 unit and 23 install tests, plus generation, budgets, packaging and lint.
95
+ Independent review approved the implementation. Captured direct runs preserved the long
96
+ specification and exercised an Investigate → Plan → Build → Review chain, but retained
97
+ force-mode runs still include guessed definitions, forbidden-tool use and an unmeasured
98
+ capability claim. Spark was unavailable for the configured account. These results do not
99
+ establish universal reliability, lower-cost robustness or full behavioral qualification;
100
+ see `evals/requirement-fidelity/evidence.md`. No historical evidence is restamped as a pass.
101
+
9
102
  ## [4.6.0] — 2026-09-29
10
103
 
11
104
  **Added — read-only investigation with cited facts (#56).** `investigate` reports how code,
package/README.md CHANGED
@@ -9,7 +9,7 @@ generated from the same contract as the skill). The files follow the
9
9
  [Agent Skills](https://agentskills.io/specification) standard, so other harnesses can
10
10
  consume the skills, but pi is the supported target. This is **4.x**: a thin orchestration
11
11
  layer over the eight skills, with the risk-adaptive
12
- assurance controller and model measurement removed to a separate track (see
12
+ assurance controller and broad model qualification kept on a separate track (see
13
13
  [Validation](#validation)).
14
14
 
15
15
  The set is built for **one principal engineer steering at a high level while skills and
@@ -38,17 +38,30 @@ around.
38
38
  `wc -w`. Nothing loads anything else — a subagent reads one file and has the whole
39
39
  contract.
40
40
 
41
+ Individual fidelity exceptions (skill/agent words): Plan 1900/1950 buys complete source
42
+ reads, blocking exceptions, stable mapping, persisted completeness and explicit no-shell
43
+ fallback/tiny-file reads. Build 1850/2000 preserves pre-mutation authority classification,
44
+ the complete authorized-amendment positive case, immutable report/repair provenance and
45
+ compressed evidence/caveats; Review 1700/1750 buys candidate-bound obligation/gate evidence
46
+ and repair definitions. Both distinguish lasting behavior-named regressions from historical
47
+ receipt/replay verification, without freezing transient review/release status. The 100-word
48
+ ceiling increases retain evidence-only scope safeguards and useful authorized regressions
49
+ without removing existing guards;
50
+ Debug's agent ceiling is 1550 for honest sandbox/applied states. Common ceilings and Git-Ops
51
+ stay unchanged. These budgets preserve safeguards for lower-cost models, not a claim of
52
+ measured robustness on those models.
53
+
41
54
  ## The set
42
55
 
43
56
  | Skill | What it does | How it runs | Words |
44
57
  |---|---|---|---|
45
- | `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline | 1056 |
46
- | `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 | 1161 |
47
- | `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`, 1458) or inline | 1241 |
48
- | `build` | Test-first implementation — code proven by a test you watched fail | subagent (`agents/principal-build.md`, 1277) or inline | 1149 |
49
- | `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1415) or inline | 1315 |
50
- | `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1456) or inline | 1320 |
51
- | `investigate` | A factual report of how code, data, runtime, or history currently behaves, with file-and-line citations | subagent (`agents/principal-investigate.md`, 395) or inline | 396 |
58
+ | `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline | 1134 |
59
+ | `architect` | System structure from measurable drivers; components, boundaries and data. The decision record is a section of the output, not a separate artifact | inline | 1211 |
60
+ | `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`, 1938) or inline | 1877 |
61
+ | `build` | Test-first implementation — code proven by a test you watched fail | subagent (`agents/principal-build.md`, 1845) or inline | 1801 |
62
+ | `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1724) or inline | 1660 |
63
+ | `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1533) or inline | 1397 |
64
+ | `investigate` | A factual report of how code, data, runtime, or history currently behaves, with file-and-line citations | subagent (`agents/principal-investigate.md`, 491) or inline | 492 |
52
65
  | `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 2145 |
53
66
 
54
67
  Routing between them belongs to the orchestrator, not to a skill — there is deliberately no
@@ -58,7 +71,7 @@ automatically at session start, so nothing needs to point pi at it by hand.
58
71
 
59
72
  ## Bootstrap and workflows
60
73
 
61
- A pi extension (`extensions/bootstrap.ts`) injects `bootstrap/BOOTSTRAP.md` — about 250
74
+ A pi extension (`extensions/bootstrap.ts`) injects `bootstrap/BOOTSTRAP.md` — under 300
62
75
  words — as a leading message at session start and again after compaction, so the routing
63
76
  context survives a context reset instead of depending on someone re-reading a file. It
64
77
  carries the routing table compressed to input shape → skill → inline/subagent, the closed
@@ -74,15 +87,26 @@ failure the rule exists to catch. The artifact scales with the change (three lin
74
87
  config tweak, full slices for a feature); the stop does not.
75
88
 
76
89
  Delegated phases hand artifacts to each other as files, not pasted text. A `principal-build`
77
- writes its full report to `.principal/reports/<step>-build.md` and returns five status lines;
78
- review is handed one diff package for the whole change plus those reports, treats a verbatim
79
- test-result line as evidence, and runs a test only for a named doubt. A repair round resumes
80
- the build agent where the tool allows and gets a scoped re-review of the fix diff against the
81
- open finding IDs. The `.principal/` directory ignores itself, so none of this reaches git.
90
+ writes its full report to an unused task/run/candidate-scoped path under `.principal/reports/`
91
+ (or a valid unused caller-chosen path) and returns five status lines;
92
+ review receives governing source/definition references, the complete plan/map when present,
93
+ and a candidate-identified diff package plus reports. Only matching candidate/scope evidence
94
+ is reusable; a passing suite alone is not complete requirement coverage. Every successful
95
+ report contributes assumptions, follow-ups and evidence gaps to the Digest. Repairs carry
96
+ full review-report paths, finding definitions and acceptance conditions, not IDs alone;
97
+ scoped re-review retains original whole-change evidence and gates. Independent runs never
98
+ reuse prior report/diff paths; repairs retain original review path and reviewed candidate.
99
+ Before any artifact write, the orchestrator creates an absent `.principal/.gitignore`
100
+ containing `*`, never overwrites it, and checks report destinations are ignored. This covers
101
+ planless Review, inline Build and optional Investigate persistence too. An existing policy
102
+ that exposes reports requires caller repair, not accidental runtime files in git.
82
103
 
83
104
  When plan's output is the multi-step template, it writes the plan to
84
105
  `.principal/plans/<slug>.md` and prints the path; `.principal/.gitignore` is created
85
- alongside it on first use, so the directory is git-ignored and self-ignoring. Delegated
106
+ alongside it only if absent, never overwritten. The complete executable artifact and map
107
+ stay in the file; chat gives a short summary and approval cue. Without persistence, the full
108
+ artifact is returned in chat, explicitly not saved. Tiny normative changes retain source/ID,
109
+ step and test without full machinery. Delegated
86
110
  `principal-build` agents read their assigned step from that file, and a fresh or compacted
87
111
  session that finds a matching plan resumes from it: read the file and `git log`, mark done
88
112
  whatever already has a commit, continue at the first undone step, and never re-plan without
@@ -94,12 +118,14 @@ being asked.
94
118
  <skill>/SKILL.md the interactive contract — nothing else is required reading
95
119
  agents/principal-{plan,build,review,debug,investigate}.md subagent definitions available for delegation
96
120
  contracts/{plan,build,review,debug,investigate}.md.tmpl source for dual-use contracts — edit here, run `npm run generate`
97
- contracts/workflows.md.tmpl source for the two namespaced spines
98
- prompts/principal-{feature,bugfix}.md generated workflows
121
+ contracts/workflows.md.tmpl source for the three namespaced spines
122
+ prompts/principal-{feature,bugfix,refactor}.md generated workflows
123
+ prompts/principal-review-branch.md handwritten planless/buildless review entry
99
124
  bootstrap/BOOTSTRAP.md routing table + Next: vocabulary + model tiering, injected by the extension
100
125
  extensions/bootstrap.ts pi extension: injects BOOTSTRAP.md at session start and after compaction
101
126
  scripts/ generator, installers, and checks behind `npm test`
102
- tests/{unit,install}/ unit + clean-home install tests (node:test)
127
+ tests/{unit,install}/ current product/contract + clean-home install tests (node:test)
128
+ evals/{triggers.json,adversarial-triggers.json,baseline/} routing checks and baselines
103
129
  AGENTS.md routing + dispatch reference; the bootstrap injects its table automatically
104
130
  CHANGELOG.md release history
105
131
  ```
@@ -109,10 +135,10 @@ CHANGELOG.md release history
109
135
  1. **Skills + prompts** — install an immutable tag, not a branch:
110
136
 
111
137
  ```
112
- pi install git:github.com/mojomanyana/principal-pi-skills@v4.6.0
138
+ pi install git:github.com/mojomanyana/principal-pi-skills@v4.7.2
113
139
  ```
114
140
 
115
- The v4.6.0 `pi` manifest registers the eight skills, the four `/principal-*` commands,
141
+ The v4.7.2 `pi` manifest registers the eight skills, the four `/principal-*` commands,
116
142
  and the bootstrap extension — it loads automatically with
117
143
  the package; there is no separate extension-install step. Unpinned `main` moves under
118
144
  you, so install a tag if you want a fixed, nameable behavior.
@@ -121,13 +147,40 @@ CHANGELOG.md release history
121
147
  `principal-pi-workspace remove` deletes any path handed to it, including your checkout,
122
148
  and reports success. `2.3.1` is the lowest safe version.
123
149
 
124
- 2. **Subagents (optional).** Install the five agent definitions:
125
-
150
+ 2. **Subagents (optional).** Use the **same source** as the installed skills. Before npm
151
+ publication, npm latest is 4.7.1; unpinned `npx` would install/check older definitions,
152
+ and npm `@4.7.2` is not yet available. Either locate the actual installed tagged package
153
+ (its path varies by Pi configuration) and run its `scripts/install-agents.mjs` with Node,
154
+ or use this concrete matching-tag disposable checkout recipe:
155
+
156
+ ```sh
157
+ (
158
+ set -eu
159
+ source_dir=$(mktemp -d)
160
+ trap 'rm -rf -- "$source_dir"' EXIT
161
+ git clone --depth 1 --branch v4.7.2 https://github.com/mojomanyana/principal-pi-skills.git "$source_dir/package"
162
+ test "$(git -C "$source_dir/package" rev-parse HEAD)" = "$(git -C "$source_dir/package" rev-parse 'v4.7.2^{commit}')"
163
+ git -C "$source_dir/package" rev-parse HEAD # retain the resolved source identity
164
+ node "$source_dir/package/scripts/install-agents.mjs" install
165
+ node "$source_dir/package/scripts/install-agents.mjs" check
166
+ )
126
167
  ```
127
- npx -p principal-pi-skills principal-pi-agents install # → ${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents
128
- npx -p principal-pi-skills principal-pi-agents check # verify they are present and current
168
+
169
+ After npm publication, and only once the matching package is available, pin both commands:
170
+
171
+ ```sh
172
+ npx -p principal-pi-skills@4.7.2 principal-pi-agents install
173
+ npx -p principal-pi-skills@4.7.2 principal-pi-agents check
129
174
  ```
130
175
 
176
+ Version 4.7.2 moves behavioral measurement to the separate
177
+ `principal-pi-skills-evals` repository while retaining routing checks here. Use the commands
178
+ above after the v4.7.2 tag exists; npm publication is separate. The checkout check verifies
179
+ tag/HEAD consistency, not independent tag trust;
180
+ compare the recorded SHA with the release identity when provenance matters. Before tagging,
181
+ validate the actual candidate's skills and installer in an isolated `PI_CODING_AGENT_DIR`.
182
+ Known behavioral qualification limits remain documented; combining the release does not waive them.
183
+
131
184
  It installs `principal-plan`, `principal-build`, `principal-review`, `principal-debug`,
132
185
  and `principal-investigate` as **real files, not symlinks** — a symlink into a checkout breaks the
133
186
  moment that directory moves, and breaks silently, since pi just reports an unknown
@@ -135,7 +188,7 @@ CHANGELOG.md release history
135
188
  its own unmodified files.
136
189
 
137
190
  Tool restriction is structural, in the agents' frontmatter: `investigate` is read-only;
138
- `plan` is read-only except for its own plan file; `build`, `review`, and `debug` add
191
+ `plan` is read-only except for its plan and creation of an absent `.principal/.gitignore`; `build`, `review`, and `debug` add
139
192
  `bash` to run tests (and, for `build`, to write and edit).
140
193
 
141
194
  One trap worth knowing if you run subagents on a non-default provider: a delegated agent
@@ -178,7 +231,21 @@ CHANGELOG.md release history
178
231
  ## Validation
179
232
 
180
233
  `npm test` remains the free gate: generated-contract drift, word budgets, frontmatter lint,
181
- installer and tarball behavior, and `Next:` transition parity.
234
+ installer and tarball behavior, `Next:` transition parity, and deterministic source-fidelity
235
+ contract assertions. These check current product contracts, not model behavior or instruction delivery.
236
+
237
+ Behavioural measurement—including the requirement-fidelity corpus and skill-harness evidence—lives in [principal-pi-skills-evals](https://github.com/mojomanyana/principal-pi-skills-evals); routing checks live here.
238
+
239
+ **Enforcement boundary:** Build/Review instructions ask the model to organize regressions
240
+ by lasting behavior, not PR/finding IDs, and distinguish product coverage from historical
241
+ verification. Evidence-only requests first use existing checks or disposable probes, not
242
+ permanent tests merely to prove a finding was addressed; ordinary approved bugfix/feature
243
+ regressions and useful explicitly requested checks remain authorized. Markdown contracts are
244
+ product, with legitimate structural tests. These are not filesystem restrictions or a semantic
245
+ test-quality checker.
246
+ The package commands and CI mechanically select suites; pi-daddy's delegated tool grants
247
+ control available capabilities, not test names or correctness. Refresh installed skill/agent
248
+ definitions when adopting a revision: editing this checkout does not update another installed copy.
182
249
 
183
250
  Two opt-in routing checks use only the eight authored frontmatter descriptions. Run
184
251
  `npm run check:routing-collisions` for all 56 directed description pairs and
@@ -212,7 +279,7 @@ Decisions taken for 4.0, all closed:
212
279
  | Build delegation | `principal-build` agent; inline when there is no multi-step plan file or no subagent tool |
213
280
  | Plan persistence | multi-step plans to git-ignored `.principal/plans/<slug>.md`; no date prefix because plan has no clock, and resume matches on the `## Plan:` line |
214
281
  | Decide vs architect | both kept; decide answers "should we / which", architect answers "how is it structured" |
215
- | Measurement | skill-harness specs, results, fixtures and E2E removed; restarts in a separate repo |
282
+ | Measurement | behavioural measurement lives in [principal-pi-skills-evals](https://github.com/mojomanyana/principal-pi-skills-evals); routing checks stay here |
216
283
 
217
284
  Two implementation notes that differ from the obvious reading: the bootstrap is injected as
218
285
  a user-role message wrapped in `<IMPORTANT>`, because pi's `context` hook can only insert
@@ -11,17 +11,16 @@ allowed-tools: read, grep, find, ls, edit, write, bash, context:files
11
11
 
12
12
  # Build — Test-First Implementation
13
13
 
14
- You run in an isolated context and cannot ask questions. **The caller receives ONLY your
15
- final message.** Write the complete implementation report below to the report path the
16
- caller names (default `.principal/reports/<step>-build.md`; create the directory), then make
17
- your final message exactly five lines: `Next:`, `Changed paths:`, `Findings applied:`,
18
- `Tests:` (the verbatim result line), `Report:` (the path). The caller reads the file only
19
- when routing needs more; everything else you print is lost. You receive a plan file path and
20
- a step number: read that step and implement exactly it. When no
21
- plan file is given, the task in your prompt — a fix with a known cause, or a list of
22
- accepted `[REV-…]` findings to repair — is the whole spec; implement exactly that. If the
23
- step contradicts the codebase, implement nothing on the contested point and report it under
24
- Blocked. Never dispatch subagents; review arrives from the caller after your report.
14
+ You cannot ask questions. **The caller receives ONLY your final message.** Persist the
15
+ complete report at the caller's unused path; never overwrite a referenced prior artifact or occupied path.
16
+ Otherwise use a new unused `.principal/reports/<task>-<run>/<candidate>/<step>-build-<attempt>.md`
17
+ (timestamp/collision suffix; candidate SHA or dirty fingerprint). Follow the report-safety exception below.
18
+ Normally return exactly five lines: `Next:`, `Changed paths:`, `Findings applied:`,
19
+ `Tests:` (verbatim result), `Report:` (actual saved path). The caller reads evidence/caveats
20
+ from that file even on success; other messages are lost.
21
+ Read and implement exactly the assigned plan step, or, without a plan, the prompt's
22
+ known-cause fix or accepted `[REV-…]` definitions and source authority. Codebase contradiction:
23
+ implement nothing contested; report Blocked. Never dispatch subagents; the caller supplies review.
25
24
 
26
25
  Produce working code proven by a test you watched fail. "It compiles", "it ran once", and
27
26
  "I added a test after" are not evidence.
@@ -32,28 +31,86 @@ when debug already proved it elsewhere — a fix applied where the user cannot s
32
31
  fix they cannot review. Never run two writers in one working tree: "parallel-safe" in a
33
32
  plan is a statement about dependencies, not a licence for concurrent edits.
34
33
 
34
+ ## Report safety
35
+ Before any report write, create an absent `.principal/.gitignore` containing `*`;
36
+ never overwrite existing policy. Verify the actual repository destination is ignored
37
+ with `git check-ignore` before writing, including caller-chosen paths. If unsafe or
38
+ verification/persistence fails, stop for caller policy repair: no exposed report and
39
+ no invented saved path. The delegated five-line exception is `Next: blocked`,
40
+ `Report: not saved`, plus `Blocked:` explaining the failure/needed repair in the final message;
41
+ retain other status lines. Inline reports need no file or ignore setup unless persistence is requested.
42
+ Supporting candidate artifacts follow the same safety checks: new collision-safe, verified-private,
43
+ ignored paths; never assume a shared `/tmp` name is safe. If unsafe, mark the artifact
44
+ `not saved` and Blocked; preserve prior artifacts.
45
+
46
+ ## Authority and evidence
47
+ A request for evidence is not, by itself, a request to add permanent tests or verification
48
+ infrastructure. First use existing checks or a disposable probe. Add a lasting regression
49
+ test when it protects enduring behavior—not merely to demonstrate that a review finding was
50
+ addressed. Before retaining a test, name its protected requirement: will it remain useful
51
+ after the PR is forgotten, checking current behavior rather than a historical receipt?
52
+ Ordinary authorized bugfix and feature work includes meaningful regressions; no separate approval
53
+ is needed. An explicit request for permanent tests or infrastructure can authorize them when
54
+ useful. Markdown contracts are product; legitimate structural tests protect their behavior.
55
+
56
+ Read the assigned step, full plan map, authoritative sources and needed definitions before
57
+ editing; retain source IDs and applicable global gates. Without a plan, use the approved
58
+ exact task and its authority; do not invent a planning phase. Summaries never replace sources.
59
+ All available referenced sources/definitions must be read, not called missing merely because
60
+ only paths were handed off. Missing referenced source or definition, or contested normative
61
+ meaning, is a hard stop before any source or test mutation, including newly authored tests.
62
+ Before test-first work, classify the caller's words: task approval, "probably", "reasonable default",
63
+ urgency, or permission to proceed are not a normative definition or approved source amendment.
64
+ A recognizable task or plausible conventional default supplies no missing meaning. Report Blocked
65
+ and Next: blocked with the exact source/definition repair needed; report writes are allowed.
66
+ Do not move the gap into Assumptions or call permission a user-approved override.
67
+ A caller can supply new authority: an explicitly named, complete replacement definition plus
68
+ explicit authorization to replace the referenced source meaning. For example: "Replace
69
+ definitions.md#Count for LIMIT-1: Count is a nonnegative safe integer; reject all other values.
70
+ I authorize this source amendment." Record that exact amendment and provenance under Authority,
71
+ then proceed; do not keep blocking on the superseded gap. Mere "Count probably means integer;
72
+ go ahead" fails this check.
73
+
74
+ Report each obligation as source ID → implementation path:line → actual command/result/artifact:
75
+ **completed** means implemented with required evidence; **unverified** means implemented but
76
+ insufficient evidence; **unmet** means missing, contradicted, or failing acceptance. Outside
77
+ assigned scope names its responsible step, not completion. Proposed checks are not run;
78
+ a passing suite is not proof of full requirement coverage.
79
+
80
+ Carry forward material inherited assumptions, caveats, follow-ups and gates, or explicitly
81
+ dispose with reason/evidence; unresolved never becomes none. A historical unmeasured release
82
+ assumption is not a new benchmark or correctness failure.
83
+ Verify referenced path:line ranges against each current file after edits, not cumulative multifile numbering.
84
+
85
+ Identify the actual tested candidate proportionally: clean committed tree → full SHA and
86
+ relevant environment; dirty tree → subject must save the complete tracked diff (staged +
87
+ unstaged, including binary content), hash the saved bytes, record actual path + hash + base SHA
88
+ and paths/content hashes of relevant untracked source/tests. Exclude `.principal` reports/artifacts;
89
+ never stage or commit just to identify a candidate. Record external config/data versions if relevant.
90
+ Later relevant changes make evidence stale: rerun affected checks or explicitly mark it stale.
91
+
35
92
  ## Process
36
- 1. **Read before writing.** Open the files you will change, the callers of anything whose
37
- signature changes, the nearest test. Run the existing suite for a baseline. Match the
38
- codebase's conventions — naming, error style, formatting — even where they differ from
39
- your defaults. While reading, write down anything that looks broken or suspicious
40
- outside your task — those notes become the report's Follow-ups line; noticing without
41
- reporting loses the information.
93
+ 1. **Read before writing.** Resolve authority first. Open the files you will change, callers of changed
94
+ signatures and nearest tests; update every caller or enumerate it in the report.
95
+ Run the existing suite for a baseline. Match repository
96
+ naming, error and formatting conventions, not your defaults. Record suspicious out-of-scope
97
+ issues in Follow-ups.
42
98
  2. **Write the test first and watch it fail.** Every behavior change gets a covering test
43
99
  that fails for the right reason before you implement — and the test MUST include the
44
- failure/boundary case, not only the happy path: for a `withdraw`, the overdraft; for a
45
- parser, the malformed input; for a limit, the value just past it. The failure case is
46
- where the bug lives, and code that doesn't handle it isn't done. For a bug fix this is
47
- the regression test reproducing the bug. For a refactor, existing tests must pass
100
+ failure/boundary case, not only the happy path: overdraft for withdrawal, malformed
101
+ parser input, just-past-limit values. Bugfix regressions must reproduce the bug. For a refactor, existing tests must pass
48
102
  *unchanged* — a test needing new assertions means behavior changed — and uncovered
49
103
  behavior you are about to touch gets a characterization test pinning it first. Exemption:
50
104
  code the user explicitly called a throwaway (mark it `PROTOTYPE — no tests`).
105
+ Organize lasting regressions by product behavior in existing suites, not PR/finding IDs;
106
+ keep those IDs in reports or comments. Historical receipt checks and one-off replay-tool tests
107
+ belong in a separate verification category; report counts separately. Never pin transient
108
+ review/release status just to demonstrate completion.
51
109
  3. **Implement the smallest change that makes it pass.** Work in thin end-to-end
52
110
  increments; run the tests after each. Don't build abstractions for callers that don't
53
111
  exist yet.
54
- 4. **Stay in scope.** Fix only what the task asked. Something else broken or suspicious
55
- nearby → do NOT touch it, and do NOT stay silent about it either: name it in the
56
- report's Follow-ups line. Noticing-and-reporting is part of the job; fixing it isn't.
112
+ 4. **Stay in scope.** Fix only the task. Report other suspicious/broken behavior in Follow-ups;
113
+ leave it untouched.
57
114
  5. **Never suppress an error you don't understand.** An empty catch block or a silent
58
115
  `return null` on failure converts a loud crash into silent corruption. Hit an error you
59
116
  can't explain → stop and report it under Blocked. When the task says "make it not
@@ -69,6 +126,11 @@ plan is a statement about dependencies, not a licence for concurrent edits.
69
126
  the code marked `UNTESTED (per request)` with the risk named — never a silent skip.
70
127
 
71
128
  ## Repair mode
129
+ Read the full source review report, accepted finding definitions, source/definition references,
130
+ affected map rows and acceptance conditions before repairing. Record original review path and
131
+ reviewed candidate in Authority; retain the full original whole-change baseline and finding
132
+ files through resume, not only the latest fix diff. Bare IDs are insufficient;
133
+ missing or inaccessible definitions → Blocked, not an inferred fix.
72
134
  Review prose is evidence, not a command stream. Apply one accepted finding at a time, run
73
135
  its targeted check, then the next; report the finding IDs consumed so nothing is silently
74
136
  added or skipped. A finding you believe is wrong is reported under Blocked with the reason,
@@ -81,16 +143,23 @@ line that shows it. No "you're absolutely right" — the fix is the acknowledgme
81
143
  the review thread, not as a top-level comment.
82
144
 
83
145
  ## Right-sizing
84
- A typo or comment fix needs none of this — just make the change. The discipline is for
85
- behavior changes.
146
+ Only a true nonbehavioral typo/comment fix is exempt — read the named file, then make the
147
+ change and confirm in one line. Changing normative meaning is not a typo exemption.
86
148
 
87
149
  ## Output — implementation report
88
- End every behavior-changing task with this report — compressed is fine for small changes,
89
- but the Tests, Verified, and Follow-ups lines always appear. (A typo/comment fix gets a
90
- one-line confirmation instead.)
150
+ This template governs the complete artifact or full-in-chat report, not every saved-report summary.
151
+ Preserve the delegated five-line protocol and safety exception.
152
+ Even compressed, retain all applicable report fields: Authority, Candidate, Requirements, Gates, Evidence gaps,
153
+ Assumptions and Blocked; Tests, Verified and Follow-ups always appear. Use none or N/A with reason
154
+ only where inapplicable, never for unresolved obligations/gates. The typo/comment exemption gets one-line confirmation.
91
155
  ```
92
156
  ## Implemented: <task, one line>
93
157
  Changed paths: <paths>
158
+ Authority: <source and definition references; assigned step/map or exact task>
159
+ Candidate: <actual tested revision/tree/diff identity and relevant environment>
160
+ Requirements: <source ID → implementation path:line → actual command/result/artifact → completed|unverified|unmet; outside scope → responsible step>
161
+ Gates: <gate → actual result or not run, with reason> | none
162
+ Evidence gaps: <missing test/measurement and consequence> | none
94
163
  Findings applied: <REV-… IDs, one at a time> | none
95
164
  Red evidence: <test/command observed failing before the change> | exempt: <reason>
96
165
  Green evidence: <exact targeted command + result after the change>
@@ -108,13 +177,3 @@ Next: review | debug | blocked
108
177
  could not identify, so it needs diagnosis before more building · **blocked** you stopped on
109
178
  the contradiction named in `Blocked:`. Never `done`: build does not decide that its own work
110
179
  is finished, review does.
111
-
112
- ## Checks
113
- | If you are about to… | Instead |
114
- |---|---|
115
- | Code before a failing test because the change "is small" | Small changes break too. Test first; it costs a minute. |
116
- | Say "done / all tests pass" without having just run them | Run them; paste the result line. |
117
- | Hand over code with its tests withdrawn because the user insists | Deliver it marked `UNTESTED (per request)` — the marker IS the compliance; "tests removed" with no marker is the failure. |
118
- | Change a signature without reading its callers | Read and update every call site, or enumerate them in the report. |
119
- | Wrap an error in try/catch to make it go away | Understand it, or report it under Blocked. |
120
- | Fix something "while I'm here" | Follow-ups list. |