principal-pi-skills 4.7.2 → 4.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -4,7 +4,7 @@ Instructions for the [pi coding agent](https://github.com/badlogic/pi-mono) oper
4
4
  with this set installed. Read this once at session start.
5
5
 
6
6
  The bootstrap extension (`extensions/bootstrap.ts`) injects this file's routing table,
7
- compressed, from `bootstrap/BOOTSTRAP.md` at session start and after compaction — you do
7
+ compressed, from `bootstrap/BOOTSTRAP.md` into each applicable converted request — you do
8
8
  not need to read this file for the framework to route. This file is the long-form
9
9
  **routing layer**: full rationale per row, the complete `Next:` set, and the maintenance
10
10
  rule. The framework deliberately has no routing skill — routing belongs to the
@@ -13,7 +13,7 @@ orchestrator (you), and each other file is self-contained: no required reading b
13
13
  ## Two forms, one rule
14
14
 
15
15
  A **skill** runs inline in this session: it shares your context, can dialogue with the
16
- user, and its work stays in your window. A **subagent** (via the subagent tool) runs in
16
+ user, and its work stays in your window. A **subagent** (via native delegation or the configured legacy runner) runs in
17
17
  its own context with its own tools, cannot ask questions, and returns only its output
18
18
  template. The rule: dialogue and session state stay inline; heavy reading, cold judgment,
19
19
  and noisy loops get delegated.
@@ -21,10 +21,26 @@ and noisy loops get delegated.
21
21
  The set:
22
22
 
23
23
  - Skills (inline only): `decide`, `architect`, `git-ops`.
24
- - Agents (delegate when the subagent tool is available): `principal-plan`,
25
- `principal-build`, `principal-review`, `principal-debug`, `principal-investigate` — defined in `agents/`. Each
26
- contract also has a SKILL.md for interactive use when delegation is unavailable or the
27
- user wants to work through it conversationally.
24
+ - Delegated phases: `plan`, `build`, `review`, `debug`, `investigate`, bound to their
25
+ generated `agents/principal-*.md` contract through `principal-agents.json`. Each also has
26
+ a SKILL.md for deliberately chosen inline work. Legacy principal-* names are only for an
27
+ explicitly configured runner when native tools are genuinely absent.
28
+
29
+ For native delegation, call `delegate_describe({agent:"phase"})`, require binding package
30
+ `principal-pi-skills` and exact phase. Native names are `plan`, `build`, `review`, `debug`,
31
+ `investigate`. Pass the corresponding captured `definitionId` to every `delegate` call,
32
+ `delegate_all` child and `delegate_chain` step. The runtime verifies enabled selected source and
33
+ both generated file hashes. Missing/wrong/disabled bindings, stale reload, unqualified backend,
34
+ permission/context refusal, timeout, report gap or uncertain cleanup stops dependent work;
35
+ never substitute legacy, foreign or inline execution after failure. Follow authored model/effort
36
+ policy without phase-tier overrides. Inline is a workflow choice, not a fallback.
37
+
38
+ For approved independent batches, use one `delegate_all({children:[...]})` call; every child
39
+ carries its native phase name and described `definitionId`. Do not overlap single `delegate`
40
+ calls: each conservatively reserves available subtree capacity. Writers need distinct
41
+ precreated registered Git worktrees, declared scopes/dependencies and unused full-report paths.
42
+ Read every result, retain completed siblings after failures, review candidates and integrate
43
+ serially with merged checks. A refusal stops dependent work, never triggers a runner switch.
28
44
 
29
45
  ## Routing — pick by what the input looks like
30
46
 
@@ -33,7 +49,7 @@ The set:
33
49
  | Choice and rationale ("should I…", "Postgres or DynamoDB", "what are my options") | `decide` | inline — the dialogue is the value |
34
50
  | System structure, components, boundaries or data ("design X", "review our architecture") | `architect` | inline — drivers come from asking |
35
51
  | 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
- | 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 |
52
+ | Code to write ("implement", "fix this known bug", "make the test pass") | `build` | inline, or native `build` with its captured `definitionId` per approved plan step — never fan parallel writers into one working tree |
37
53
  | 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 |
38
54
  | An unknown failure to diagnose ("why is this failing", "find the bug") | `debug` | **subagent** when reproduction is noisy (flaky loops, bisects); inline when the user is driving |
39
55
  | 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 |
@@ -82,18 +98,26 @@ Typical spines (available as prompt templates):
82
98
  - Bug (`/principal-bugfix <symptom>`): debug → approval stop → build → review → git-ops
83
99
  finish. If debug's note says design flaw, stop and surface it.
84
100
  - Refactor (`/principal-refactor <scope>`): the feature spine with a no-behavior-change
85
- frame — existing tests pass unchanged, uncovered behavior gets a characterization test first.
86
- - Review a branch (`/principal-review-branch [base]`): cold `principal-review` of
101
+ frame — behavior and coverage stay equivalent; test maintenance is allowed, and uncovered
102
+ behavior gets a characterization test first.
103
+ - Review a branch (`/principal-review-branch [base]`): cold native `review` with its captured `definitionId` of
87
104
  `merge-base <base> HEAD..HEAD`, then git-ops finish mode on APPROVE; findings stop for the
88
105
  user otherwise. No plan, no build.
89
- - Any spine, when the subagent tool is missing or reports an unknown agent: run that
90
- phase's skill inline instead and say so in the digest. Fall back on *absence* only —
91
- any other agent failure stops the workflow. Build↔review repair loops stop after two
92
- rounds; a third means the plan or the diagnosis was wrong, not the code.
106
+ - Every spine uses the bound native or explicitly configured legacy interface above.
107
+ Build↔review repair loops stop after two rounds; a third means the plan or diagnosis was
108
+ wrong. A missing full report blocks dependent review; preserve independent completed work.
93
109
  - Multi-step plans are written to `.principal/plans/<slug>.md` (git-ignored) so a delegated
94
110
  build reads its step from the file and a compacted or fresh session resumes from it.
95
- - Tiny change: build → git-ops, both inline — every contract carries a Right-sizing
96
- rule; don't add ceremony the file itself would refuse.
111
+ - Tiny change: build → git-ops only when finish is requested. Clear, reversible, localized
112
+ low-risk direct work may finish inline with actual checks and caveats, without `Next:`.
113
+ Honor requested review and existing approvals; a tiny security or normative edit is
114
+ consequential. Delegated status/report protocols and explicit spine approval stops remain.
115
+ - Review scope is task, integrated or scoped repair. Task approval covers only its candidate
116
+ and interfaces; only final integrated approval supports Git-Ops finish. Keep original
117
+ whole-change obligations and gates through repairs.
118
+ - Progress records are optional coordinator evidence indexes, never approval or execution.
119
+ Reconcile actual authority, work and current report/candidate references; commit, review,
120
+ integration and verification are separate facts. Incomplete/stale records stay unresolved.
97
121
 
98
122
  Before any orchestrator artifact write (including planless Review, inline Build or optional
99
123
  Investigate persistence), create an absent `.principal/.gitignore` containing `*`, never
@@ -121,7 +145,9 @@ where they used to drift.
121
145
 
122
146
  Both are generated from `contracts/<name>.md.tmpl`. The three spine workflows are
123
147
  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).
148
+ template produce five agents, five dual-use `SKILL.md` files and three prompts, plus the
149
+ root `principal-agents.json` binding manifest (14 outputs). The manifest hashes full generated
150
+ UTF-8 skill/agent bytes in the same pass; never hand-edit its identities.
125
151
  `prompts/principal-review-branch.md` is handwritten. Change shared behavior ONCE, there, then `npm run generate`. Editing a
126
152
  generated file directly is reverted by the next run and fails `npm run generate:check` in
127
153
  CI.
@@ -137,23 +163,29 @@ Behavioural measurement—including the fidelity corpus and skill-harness eviden
137
163
 
138
164
  ## Setup (pi)
139
165
 
140
- 1. `pi install git:github.com/mojomanyana/principal-pi-skills@v4.7.2` installs the eight
141
- skills, the four `/principal-*` commands, and the bootstrap
142
- extension, which loads automatically with the package. Install a tag, not a branch.
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
166
+ 1. Install the stable tag:
167
+ `pi install git:github.com/mojomanyana/principal-pi-skills@v4.8.0` installs the eight
168
+ skills, the four `/principal-*` commands, and the bootstrap extension, which loads
169
+ automatically with the package. This release is stable 4.8.0. Native delegation
170
+ requires companion pi-daddy 0.44.0 and exactly the qualified Pi 1.0.4 setup; generated
171
+ skill/agent bindings and captured definition IDs must match the selected package.
172
+ 2. Legacy subagents (optional): native delegation does not need this separate installation.
173
+ A configured legacy runner is available only when native tools are genuinely absent;
174
+ native refusal or failure cannot fall back to it. Npm publication is separate from this
175
+ prerelease. Use the installed tagged package's `scripts/install-agents.mjs` with Node
145
176
  (`install`, then `check`), locating its actual path rather than assuming a universal Pi
146
177
  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`.
178
+ recipe in [README Install](README.md#install-pi). Pin both npm commands:
179
+ `npx -p principal-pi-skills@4.8.0 principal-pi-agents install` and
180
+ `npx -p principal-pi-skills@4.8.0 principal-pi-agents check`.
150
181
  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,
182
+ are refused. These files serve a configured legacy runner; they do not override native selection.
183
+ Version 4.8.0 adds native bindings, request-local routing, workflow and installer
184
+ safety changes, and manual progress records. Behavioral measurement remains in
185
+ `principal-pi-skills-evals` while routing checks remain here. To validate the tagged release,
154
186
  validate the actual candidate's skills and installer
155
187
  in isolation. Recorded model/evidence limitations remain; a release tag does not erase them.
156
- 3. Context handoff (pi-daddy 0.33.0+): each skill's `allowed-tools` sets how much of this
188
+ 3. Context handoff (matching pi-daddy candidate): each skill's `allowed-tools` sets how much of this
157
189
  session a delegated child may receive. `architect`, `decide` and `plan` allow
158
190
  `context:summary`. `build`, `debug`, `review` and `investigate` allow `context:files`: review
159
191
  stays low so it judges cold; investigate receives named evidence, not reasoning.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,73 @@ Where review revealed a prior claim or design decision didn't hold up under clos
6
6
 
7
7
  ---
8
8
 
9
+ ## [4.8.0] — 2026-10-07
10
+
11
+ **Fixed — installer compatibility without ownership bypass.** Symlinked directory ancestors
12
+ resolve to canonical anchors before ownership checks; agent/manifest leaf links still refuse.
13
+ Installed agents use `0644` and ownership metadata uses `0600`. Explicit `adopt` recovers a
14
+ missing manifest only for a complete byte-identical current agent set. `install` never
15
+ silently adopts; deprecated `--force` now explains that it cannot bypass ownership.
16
+
17
+ **Fixed — selected routing and parallel dispatch.** A stale foreign skill path cannot latch
18
+ all Principal routing off. Native workflows name `build`/`review`/other phases with captured
19
+ `definitionId` values and dispatch independent batches through `delegate_all`, with isolated
20
+ writer worktrees and serial integration. Compatibility is qualified for exactly Pi 1.0.4
21
+ and the companion pi-daddy 0.44.0 release, not unknown runtime versions.
22
+
23
+ ## [4.8.0-rc.1] — 2026-10-07
24
+
25
+ **Added — native phase identity and request-local routing.** Generated
26
+ `principal-agents.json` binds all five delegated phases to their skill and agent hashes.
27
+ The bootstrap keeps Principal package identity, uses the selected native definition ID,
28
+ and refreshes routing after resource discovery, reloads and compaction. It deduplicates
29
+ its own request-local messages without treating quoted markers as routing state, and
30
+ retains read failures rather than silently selecting a different contract.
31
+
32
+ **Changed — concrete workflow contracts.** Planning records interfaces and checks where
33
+ needed; Decide and Architect avoid invented options or patterns. Build preserves behavior
34
+ and coverage during refactors, Review supports scoped review and repair, and diagnosis
35
+ hands implementation and verification back to Build. Eligible small changes can stay inline.
36
+
37
+ **Added — manual progress and complete reports.** `principal-pi-progress` stores ignored,
38
+ candidate-bound full reports and a strict evidence index. Exact metadata validation prevents
39
+ report redirection. Stale or incomplete records remain explicit; the helper neither grants
40
+ approval nor resumes work automatically.
41
+
42
+ **Fixed — installer ownership and recovery.** The installer validates the entire ownership
43
+ manifest before mutation and refuses malformed, foreign, edited or symlink targets, including
44
+ with `--force`. Git recovery instructions preserve staged, unstaged, untracked and ignored
45
+ content rather than assuming a patch alone captures the working state.
46
+
47
+ **Compatibility.** This prerelease targets stable 4.8.0. Native delegation requires the
48
+ companion pi-daddy 0.44.0-rc.1 candidate's `delegate_describe`/`definitionId` protocol and the
49
+ qualified Pi 1.0.4 setup. A configured legacy runner is available only when native tools are
50
+ genuinely absent; native failure cannot silently fall back. Existing installs require explicit
51
+ activation. Tag creation and npm publication are separate; this entry does not assert either.
52
+
53
+ **Validation.** `npm test` covers 168 unit and 33 install tests, generated outputs, word
54
+ budgets, package contents and skill lint. Companion runtime qualification exercises the
55
+ actual Pi 1.0.4 SDK/bootstrap and all five native phases with a local scripted provider.
56
+ These checks establish behavior and wiring, not model quality; behavioral measurement
57
+ remains in `principal-pi-skills-evals`.
58
+
59
+ ## [4.7.3] — 2026-10-06
60
+
61
+ **Changed — current release and measurement documentation.** Installation examples and
62
+ subagent pins now target the immutable `v4.7.3` release; before npm publication, the documented
63
+ registry latest is 4.7.2 and npm `@4.7.3` remains unavailable. Previously the documentation
64
+ still described 4.7.2 as unpublished after it became npm `latest`.
65
+
66
+ **Documented — external frozen-rubric baseline.** The README now links the current
67
+ [principal-pi-skills-evals baseline](https://github.com/mojomanyana/principal-pi-skills-evals/blob/main/BASELINE.md),
68
+ which records DeepSeek V4.1 Flash at 56/158 (35%) with 2 infrastructure-error scenarios
69
+ and Nemotron Lightning at 28/158 (18%) with 12. Infrastructure errors are retained as
70
+ non-passes, both subjects remain NOT READY across all eight skills, and the observations
71
+ include disclosed infrastructure gaps; they do not change or qualify the runtime package.
72
+
73
+ **Compatibility.** No skill, agent, prompt, bootstrap, generated contract, tool ceiling, or
74
+ runtime behavior changed from 4.7.2. Tag creation and npm publication remain separate.
75
+
9
76
  ## [4.7.2] — 2026-10-01
10
77
 
11
78
  **Changed — behavioral measurement moved out (#59).** The requirement-fidelity corpus,
package/README.md CHANGED
@@ -30,7 +30,7 @@ around.
30
30
  plain-text tags (`[ONE-WAY]`, `[BLOCKER]`) instead of an emoji schema, no aphorisms
31
31
  doing load-bearing work, no personas, no required reading in reference files.
32
32
  3. **Token economics.** Budgets stated as decisions rather than aspirations: **skills
33
- ≤ 1400 words**, **agents ≤ 1500**, and **`git-ops` an accepted exception at ≤ 2150** —
33
+ ≤ 1400 words**, **agents ≤ 1500**, and **`git-ops` an accepted exception at ≤ 2550** (including operation-specific preservation and verified restoration) —
34
34
  the safety-critical operator carries the most arming, and validated behavior outweighs
35
35
  a budget. Ceilings move only to buy a fix rather than more prose: an absolute is cheap to write and wrong in real cases, and a rule plus the cases
36
36
  it must not eat costs more words than the absolute it replaced. **When a fix and the
@@ -38,46 +38,62 @@ 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.
41
+ Individual contract exceptions (skill/agent words): Plan 2000/2050 preserves complete
42
+ source/requirement maps and adds exact connected interfaces and shared-resource checks.
43
+ Build 2000/2000 retains authority, full evidence and immutable repair provenance while adding
44
+ meaningful test maintenance and a guarded inline path. Review 1800/1850 retains candidate-bound
45
+ gates and distinguishes task, integrated and repair scope. Debug 1450/1600 preserves honest
46
+ disposable/applied states while making diagnosis sufficient for handoff and protecting
47
+ boundary evidence. These narrow increases retain the existing safeguards; they are not
48
+ claims of measured model compliance. Common ceilings remain unchanged.
53
49
 
54
50
  ## The set
55
51
 
56
52
  | Skill | What it does | How it runs | Words |
57
53
  |---|---|---|---|
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 |
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 |
54
+ | `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline | 975 |
55
+ | `architect` | System structure from measurable drivers; components, boundaries and data. The decision record is a section of the output, not a separate artifact | inline | 1270 |
56
+ | `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`, 2024) or inline | 1963 |
57
+ | `build` | Test-first implementation — code proven by a test you watched fail | subagent (`agents/principal-build.md`, 1970) or inline | 1960 |
58
+ | `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1841) or inline | 1777 |
59
+ | `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1587) or inline | 1451 |
60
+ | `investigate` | A factual report of how code, data, runtime, or history currently behaves, with file-and-line citations | subagent (`agents/principal-investigate.md`, 494) or inline | 495 |
61
+ | `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 2507 |
66
62
 
67
63
  Routing between them belongs to the orchestrator, not to a skill — there is deliberately no
68
64
  routing skill spending context to say "pick a skill". [AGENTS.md](./AGENTS.md) is the
69
65
  long-form routing reference, and the bootstrap extension below injects its routing table
70
- automatically at session start, so nothing needs to point pi at it by hand.
66
+ into applicable requests, so nothing needs to point pi at it by hand.
71
67
 
72
68
  ## Bootstrap and workflows
73
69
 
74
- A pi extension (`extensions/bootstrap.ts`) injects `bootstrap/BOOTSTRAP.md` — under 300
75
- words — as a leading message at session start and again after compaction, so the routing
76
- context survives a context reset instead of depending on someone re-reading a file. It
77
- carries the routing table compressed to input shape → skill → inline/subagent, the closed
78
- `Next:` vocabulary the phases hand off with, and model tiering: the cheapest model for a
79
- build agent working a complete step spec, the session default for plan and debug, the
80
- strongest available for review and architect.
70
+ The extension (`extensions/bootstrap.ts`) discovers this package's enabled selected skills
71
+ through public `pi.getCommands()` at `before_agent_start`, after resource discovery. It
72
+ adds the under-300-word `bootstrap/BOOTSTRAP.md` once to each converted request, preserving
73
+ leading compaction/system/tool state and durable history. Tool iterations and later ordinary
74
+ requests receive routing too. Only extension-owned inserted objects are replaced; a quoted
75
+ marker cannot suppress injection. Disabled or shadowed package resources stay inactive.
76
+ Principal read/discovery failure is visible and latched until deliberate `/reload` reinstantiates the
77
+ extension; stale foreign command paths are ignored independently without disabling valid Principal skills; each registration owns its content cache and selected-resource state.
78
+
79
+ Native handoffs use `delegate_describe({agent:"phase"})`, require binding package
80
+ `principal-pi-skills` and exact phase. Native names are `plan`, `build`, `review`, `debug`,
81
+ `investigate`; pass the corresponding captured `definitionId` to every `delegate` call,
82
+ `delegate_all` child and `delegate_chain` step. The root `principal-agents.json` manifest binds exactly five phases to generated
83
+ inline/delegated paths and full-file SHA-256 hashes from the same generation pass. The
84
+ runtime must verify enabled selected source, package identity and both hashes. Missing,
85
+ wrong or disabled bindings and operational failures stop dependent work; they never trigger
86
+ legacy/foreign/inline substitution. Only genuinely absent native tools permit an explicitly
87
+ configured legacy principal-* runner. Inline is a workflow choice. Authored model/effort
88
+ policy governs; phase labels do not silently override it. This contract alone does not qualify
89
+ live native execution; the actual installed runtime/candidate still needs integration evidence.
90
+
91
+ Use one `delegate_all({children:[...]})` call for an approved independent parallel batch,
92
+ with the exact native phase name and captured `definitionId` on each child. Single `delegate`
93
+ calls conservatively reserve the available subtree capacity; overlapping single calls can
94
+ be refused. Writers need distinct precreated registered Git worktrees and declared scopes,
95
+ dependencies, shared resources and full-report destinations. Read every outcome, preserve
96
+ completed siblings after failure, review candidates, integrate serially and check the merged whole.
81
97
 
82
98
  The three spines (`/principal-feature <task>`, `/principal-bugfix <symptom>`,
83
99
  `/principal-refactor <scope>`) stop for your approval after the planning phase or the debug
@@ -86,7 +102,7 @@ before building — presenting the artifact and starting to build in the same tu
86
102
  failure the rule exists to catch. The artifact scales with the change (three lines for a
87
103
  config tweak, full slices for a feature); the stop does not.
88
104
 
89
- Delegated phases hand artifacts to each other as files, not pasted text. A `principal-build`
105
+ Delegated phases hand artifacts to each other as files, not pasted text. A native `build` child
90
106
  writes its full report to an unused task/run/candidate-scoped path under `.principal/reports/`
91
107
  (or a valid unused caller-chosen path) and returns five status lines;
92
108
  review receives governing source/definition references, the complete plan/map when present,
@@ -107,10 +123,10 @@ alongside it only if absent, never overwritten. The complete executable artifact
107
123
  stay in the file; chat gives a short summary and approval cue. Without persistence, the full
108
124
  artifact is returned in chat, explicitly not saved. Tiny normative changes retain source/ID,
109
125
  step and test without full machinery. Delegated
110
- `principal-build` agents read their assigned step from that file, and a fresh or compacted
111
- session that finds a matching plan resumes from it: read the file and `git log`, mark done
112
- whatever already has a commit, continue at the first undone step, and never re-plan without
113
- being asked.
126
+ `build` children read their assigned step from that file, and a fresh or compacted
127
+ session locates matching plans, then reconciles actual approval, current work and candidate-bound
128
+ reports. A commit does not establish review, integration or verification. Resume manually at
129
+ what the evidence shows remains; do not repeat completed work or infer approval from a title.
114
130
 
115
131
  ## Layout
116
132
 
@@ -122,7 +138,7 @@ contracts/workflows.md.tmpl source for the three namespaced spines
122
138
  prompts/principal-{feature,bugfix,refactor}.md generated workflows
123
139
  prompts/principal-review-branch.md handwritten planless/buildless review entry
124
140
  bootstrap/BOOTSTRAP.md routing table + Next: vocabulary + model tiering, injected by the extension
125
- extensions/bootstrap.ts pi extension: injects BOOTSTRAP.md at session start and after compaction
141
+ extensions/bootstrap.ts pi extension: request-local routing after selected-resource discovery
126
142
  scripts/ generator, installers, and checks behind `npm test`
127
143
  tests/{unit,install}/ current product/contract + clean-home install tests (node:test)
128
144
  evals/{triggers.json,adversarial-triggers.json,baseline/} routing checks and baselines
@@ -132,13 +148,14 @@ CHANGELOG.md release history
132
148
 
133
149
  ## Install (pi)
134
150
 
135
- 1. **Skills + prompts** — install an immutable tag, not a branch:
151
+ 1. **Skills + prompts** — this prerelease targets stable 4.8.0. Once the immutable tag
152
+ exists, install it rather than a branch:
136
153
 
137
154
  ```
138
- pi install git:github.com/mojomanyana/principal-pi-skills@v4.7.2
155
+ pi install git:github.com/mojomanyana/principal-pi-skills@v4.8.0
139
156
  ```
140
157
 
141
- The v4.7.2 `pi` manifest registers the eight skills, the four `/principal-*` commands,
158
+ The v4.8.0 `pi` manifest registers the eight skills, the four `/principal-*` commands,
142
159
  and the bootstrap extension — it loads automatically with
143
160
  the package; there is no separate extension-install step. Unpinned `main` moves under
144
161
  you, so install a tag if you want a fixed, nameable behavior.
@@ -147,36 +164,45 @@ CHANGELOG.md release history
147
164
  `principal-pi-workspace remove` deletes any path handed to it, including your checkout,
148
165
  and reports success. `2.3.1` is the lowest safe version.
149
166
 
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:
167
+ Native delegation requires the companion pi-daddy 0.44.0 release and **exactly
168
+ Pi 1.0.4**, the qualified version. This is not a claim of compatibility with every Pi 1.x
169
+ release; other or unknown versions require separate qualification before use. The selected package's generated `principal-agents.json`
170
+ binds each delegated phase to its skill and agent bytes. Native routing uses
171
+ `delegate_describe` and a captured `definitionId`; a native refusal or failure does
172
+ not fall back to a legacy runner or inline execution.
173
+
174
+ 2. **Legacy subagents (optional).** A configured legacy runner can use the five agent
175
+ definitions when native tools are genuinely absent. Native delegation does not need
176
+ this separate agent installation. Use the **same source** as the installed skills:
177
+ locate the actual installed tagged package (its path varies by Pi configuration) and
178
+ run its `scripts/install-agents.mjs` with Node, or use this matching-tag disposable
179
+ checkout recipe after the tag exists. This prerelease does not imply npm publication.
155
180
 
156
181
  ```sh
157
182
  (
158
183
  set -eu
159
184
  source_dir=$(mktemp -d)
160
185
  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}')"
186
+ git clone --depth 1 --branch v4.8.0 https://github.com/mojomanyana/principal-pi-skills.git "$source_dir/package"
187
+ test "$(git -C "$source_dir/package" rev-parse HEAD)" = "$(git -C "$source_dir/package" rev-parse 'v4.8.0^{commit}')"
163
188
  git -C "$source_dir/package" rev-parse HEAD # retain the resolved source identity
164
189
  node "$source_dir/package/scripts/install-agents.mjs" install
165
190
  node "$source_dir/package/scripts/install-agents.mjs" check
166
191
  )
167
192
  ```
168
193
 
169
- After npm publication, and only once the matching package is available, pin both commands:
194
+ Pin both npm commands:
170
195
 
171
196
  ```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
197
+ npx -p principal-pi-skills@4.8.0 principal-pi-agents install
198
+ npx -p principal-pi-skills@4.8.0 principal-pi-agents check
174
199
  ```
175
200
 
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;
201
+ Version 4.8.0 adds native phase bindings, request-local bootstrap routing, stricter
202
+ workflow contracts, manual progress records, and installer ownership checks. Behavioral
203
+ measurement remains in the separate `principal-pi-skills-evals` repository, while routing
204
+ checks remain here. The checkout check
205
+ verifies tag/HEAD consistency, not independent tag trust;
180
206
  compare the recorded SHA with the release identity when provenance matters. Before tagging,
181
207
  validate the actual candidate's skills and installer in an isolated `PI_CODING_AGENT_DIR`.
182
208
  Known behavioral qualification limits remain documented; combining the release does not waive them.
@@ -185,26 +211,36 @@ CHANGELOG.md release history
185
211
  and `principal-investigate` as **real files, not symlinks** — a symlink into a checkout breaks the
186
212
  moment that directory moves, and breaks silently, since pi just reports an unknown
187
213
  agent. It refuses to overwrite anything it did not install, and `uninstall` removes only
188
- its own unmodified files.
214
+ its own unmodified files. Symlinked home/config ancestors resolve once to a canonical
215
+ directory; agent and manifest leaf symlinks (including dangling links) still refuse.
216
+ Installed agent files are `0644`; the ownership manifest is `0600`. Re-running `install`
217
+ repairs the earlier `0600` agent mode only for unchanged owned files.
218
+
219
+ **Ownership migration/recovery:** `install` no longer silently adopts byte-identical
220
+ unowned files, and deprecated `--force` never bypasses validation or ownership. If only
221
+ the manifest was lost and all five agents exactly match this package version, explicitly
222
+ run `node <installed-package>/scripts/install-agents.mjs adopt`, then `install` (to repair
223
+ unchanged owned file modes), then `check`. `adopt`
224
+ creates only the absent manifest and leaves agent bytes/modes untouched; it refuses an
225
+ existing manifest, partial sets, modified/older content and leaf symlinks. Unrelated files
226
+ remain unclaimed. Keep any edited or older files and restore known-good metadata from
227
+ your own backup; do not delete them merely to make installation pass.
189
228
 
190
229
  Tool restriction is structural, in the agents' frontmatter: `investigate` is read-only;
191
230
  `plan` is read-only except for its plan and creation of an absent `.principal/.gitignore`; `build`, `review`, and `debug` add
192
231
  `bash` to run tests (and, for `build`, to write and edit).
193
232
 
194
- One trap worth knowing if you run subagents on a non-default provider: a delegated agent
195
- runs on the pi config's `defaultProvider`/`defaultModel`, **not** the
196
- `--provider`/`--model` you gave the parent session — the extension forwards `--model`
197
- only when an agent's frontmatter names one, and these deliberately do not. If
198
- delegations fail to authenticate while the parent session is fine, that mismatch is the
199
- reason.
233
+ Legacy runners differ in model forwarding. If a runner does not forward the parent's
234
+ provider/model, check that runner's defaults and agent-frontmatter rules when a child
235
+ cannot authenticate. Native delegation uses the matching pi-daddy runtime's resolved
236
+ model and effort policy.
200
237
 
201
- 3. **Without the subagent step, everything still runs completely inline** via the skills;
202
- the How column in [The set](#the-set) simply collapses to "inline". The routing table
203
- still reaches the session because the bootstrap extension injects it — installing the
204
- package is enough for that part; only delegation itself needs step 2.
238
+ 3. **Inline execution remains available when the workflow selects it.** The bootstrap
239
+ supplies routing with the installed skills. Skipping the legacy agent installation does
240
+ not disable native delegation, and a failed native handoff cannot silently become inline.
205
241
 
206
- 4. **Under pi-daddy (0.33.0+), each skill declares how much of the caller's session it may
207
- receive.** A child gets only the `context:` mode its own `allowed-tools` names (or a
242
+ 4. **With the matching pi-daddy candidate, each skill declares how much of the caller's
243
+ session it may receive.** A child gets only the `context:` mode its own `allowed-tools` names (or a
208
244
  weaker one: `none < files < pruned < summary < fork`). Asking for more is refused, not
209
245
  downgraded. The ceilings are decisions, and each one is explained in its frontmatter:
210
246
 
@@ -220,13 +256,69 @@ CHANGELOG.md release history
220
256
  Nothing declares `context:fork`. Write the prefix in lowercase: `Context:summary` turns
221
257
  into `tool:context:summary`, which grants no context mode.
222
258
 
223
- **Egress: know what `summary` enables.** `context:summary` also permits `pruned`. That
224
- mode carries the operator's own session turns (the last 20 by default, up to 32 KiB),
225
- not just the task. With a pi-daddy advisor enabled (`PI_DADDY_ADVISOR` plus
226
- `PI_DADDY_ADVISOR_KEY`), a `pruned` handoff sends those turns to that third party so it
227
- can choose which ones to keep. For `architect`, `decide` and `plan`, that is what you
228
- switch on by delegating with `pruned` while an advisor is on. Raising any other skill's
229
- ceiling extends that exposure to it.
259
+ **Egress: know what `summary` enables.** `context:summary` also permits `pruned`,
260
+ which can carry selected turns from the active parent branch to the delegated child's
261
+ provider. The matching pi-daddy candidate no longer uses an external advisor to choose
262
+ those turns. Forwarded context still reaches the child and its provider; raising another
263
+ skill's ceiling extends that exposure to it.
264
+
265
+ ## Reports and manual progress
266
+
267
+ Use the installed `principal-pi-progress` helper when a coordinator needs repeated report
268
+ allocation/persistence. It creates private unused candidate directories beneath ignored
269
+ `.principal/reports/`, writes complete `.md` reports exclusively, and appends a small
270
+ `progress.jsonl` index. It preserves an existing ignore policy and refuses an exposed path.
271
+ The helper is optional; Plan's write ceiling and Investigate's read-only ceiling do not grow.
272
+ Do not fetch/install it solely to write a report.
273
+
274
+ ```sh
275
+ principal-pi-progress create /path/to/repo task-name '<actual candidate identity>'
276
+ # Set RUN to the decoded returned path; use the same caller-established identity below.
277
+ principal-pi-progress report "$RUN" step-1-build.md < complete-report.md
278
+ principal-pi-progress reference /absolute/path/to/plan.md
279
+ principal-pi-progress append "$RUN" < record.json
280
+ principal-pi-progress read "$RUN" '<actual current candidate identity>'
281
+ ```
282
+
283
+ `report` and `reference` return `{ "path": "/absolute/path", "sha256": "<64 hex>" }`.
284
+ A version 1 record has exactly these fields (replace `REPORT_REF` with that returned object):
285
+
286
+ ```json
287
+ {
288
+ "version": 1,
289
+ "plan": null,
290
+ "step": "impl:S1",
291
+ "candidate": "<actual candidate identity>",
292
+ "facts": {
293
+ "planned": { "state": "unknown", "evidence": [], "note": "No separate plan" },
294
+ "implemented": { "state": "complete", "evidence": ["REPORT_REF"], "note": "Implementation saved; review pending" },
295
+ "reviewed": { "state": "unknown", "evidence": [], "note": "Not reviewed" },
296
+ "integrated": { "state": "unknown", "evidence": [], "note": "Not integrated" },
297
+ "verified": { "state": "unknown", "evidence": [], "note": "Qualification not run" }
298
+ },
299
+ "findings": [],
300
+ "nextAction": "Request task review"
301
+ }
302
+ ```
303
+
304
+ `plan` is null or a file reference. Every fact has `unknown`, `incomplete` or `complete`
305
+ state, evidence references and an honest note; complete needs evidence. A completed review
306
+ means the review occurred, and its note must retain the verdict, including CHANGES-REQUESTED.
307
+ Each finding has `id`, `source` reference and `status` (`open`, `addressed`, `verified`,
308
+ `accepted`, `disputed`, `duplicate`, `stale`); a duplicate also names `duplicateOf`. Preserve original
309
+ review baseline/definitions and PR comment URLs/IDs in the referenced complete reports.
310
+
311
+ The coordinator is the single writer. Save the report before appending progress; an append
312
+ failure preserves that report and leaves progress incomplete. Never force-clear a writer
313
+ lock. Reads return the original records plus independently assessed facts/issues: changed or
314
+ missing files, changed/unconfirmed candidates and malformed/incomplete records remain
315
+ unresolved. An incomplete final JSONL line is ignored/reported, never promoted to complete;
316
+ preserve its bytes and start a new run if needed. Reconcile records by step, not just the
317
+ last line. No helper claim proves its evidence's meaning, model judgment, approval or broad
318
+ candidate equivalence. It neither computes candidate identity nor resumes/runs tasks. Check
319
+ actual user authority/current work before choosing the next action; a title, role, commit or
320
+ self-authored boolean cannot grant approval. This is a trusted-coordinator filesystem helper,
321
+ not hostile-process containment or an atomic multi-file transaction.
230
322
 
231
323
  ## Validation
232
324
 
@@ -234,7 +326,7 @@ CHANGELOG.md release history
234
326
  installer and tarball behavior, `Next:` transition parity, and deterministic source-fidelity
235
327
  contract assertions. These check current product contracts, not model behavior or instruction delivery.
236
328
 
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.
329
+ 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. Its [current frozen-rubric baseline](https://github.com/mojomanyana/principal-pi-skills-evals/blob/main/BASELINE.md) reports DeepSeek V4.1 Flash at 56/158 (35%) with 2 infrastructure-error scenarios and Nemotron Lightning at 28/158 (18%) with 12; infrastructure errors are retained as non-passes, and both subjects remain NOT READY across all eight skills. These observations include disclosed infrastructure gaps and do not change this package's runtime contracts.
238
330
 
239
331
  **Enforcement boundary:** Build/Review instructions ask the model to organize regressions
240
332
  by lasting behavior, not PR/finding IDs, and distinguish product coverage from historical
@@ -275,9 +367,9 @@ Decisions taken for 4.0, all closed:
275
367
  | Target harness | pi only |
276
368
  | Assurance ledger and profiles | removed; per-skill right-sizing is the mechanism; the tool lives on the `v3.2.0` tag for porting to pi-daddy |
277
369
  | Human approval | always, after plan (feature) or after the debug note (bugfix); the artifact scales, the stop does not |
278
- | Routing delivery | a pi extension injects `bootstrap/BOOTSTRAP.md` at session start and after compaction |
279
- | Build delegation | `principal-build` agent; inline when there is no multi-step plan file or no subagent tool |
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 |
370
+ | Routing delivery | request-local bootstrap after selected-resource discovery; quoted markers do not suppress it |
371
+ | Build delegation | bound native phase, or explicitly configured legacy runner when native tools are absent; inline is a workflow choice |
372
+ | Plan persistence | multi-step plans to git-ignored `.principal/plans/<slug>.md`; titles locate candidates, while manual resume checks actual authority, current work and evidence |
281
373
  | Decide vs architect | both kept; decide answers "should we / which", architect answers "how is it structured" |
282
374
  | Measurement | behavioural measurement lives in [principal-pi-skills-evals](https://github.com/mojomanyana/principal-pi-skills-evals); routing checks stay here |
283
375
 
@@ -316,3 +408,5 @@ Why the files look the way they do. Each of these was learned by measuring the a
316
408
  ## License
317
409
 
318
410
  MIT © 2026 Nemanja Alavanja. See [LICENSE](./LICENSE).
411
+
412
+ The Debug inline budget includes three generated frontmatter words that mark Principal package identity; missing or replaced package metadata must refuse native binding rather than downgrade to inline instructions.