principal-pi-skills 3.0.0 → 3.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +5 -3
- package/CHANGELOG.md +60 -0
- package/README.md +35 -10
- package/agents/plan.md +38 -5
- package/agents/principal-plan.md +38 -5
- package/decide/SKILL.md +22 -0
- package/package.json +1 -1
- package/plan/SKILL.md +38 -5
- package/scripts/assurance-state.mjs +212 -25
package/AGENTS.md
CHANGED
|
@@ -119,9 +119,11 @@ to every output.
|
|
|
119
119
|
|
|
120
120
|
## Setup (pi)
|
|
121
121
|
|
|
122
|
-
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v3.0.
|
|
123
|
-
|
|
124
|
-
|
|
122
|
+
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v3.0.1` — the immutable install
|
|
123
|
+
coordinate for this source tree's `3.0.1` release candidate. The remote `v3.0.1` tag is pending
|
|
124
|
+
and npm `latest` remains `3.0.0`; verify both before installing. After publication they must
|
|
125
|
+
resolve this same version. `standard` is the default assurance
|
|
126
|
+
profile, so a v2 invocation keeps working unchanged. It registers the
|
|
125
127
|
skills and the `/principal-feature` + `/principal-bugfix` commands via the `pi`
|
|
126
128
|
manifest. Install a tag, not a branch.
|
|
127
129
|
2. Subagents need pi-mono's subagent extension (`examples/extensions/subagent`, which ships
|
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,66 @@ Where review revealed a prior claim or design decision didn't hold up under clos
|
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
+
## [3.0.1] — 2026-09-04
|
|
10
|
+
|
|
11
|
+
**Added — assurance ledgers have a read-only evidence projection.**
|
|
12
|
+
`principal-pi-assurance report --run-id <id>` renders authority, packets, changed paths, receipts,
|
|
13
|
+
reviews, recorded gate outcomes, findings/adjudications, and finish identity in deterministic human
|
|
14
|
+
sections, with absent facts and assumptions labelled rather than inferred. It also emits an unsigned
|
|
15
|
+
in-toto Statement v1 using the test-result v0.1 predicate; final head/tree subjects, receipt-derived
|
|
16
|
+
configuration and pass/fail lists, and the ledger hash-chain head bind the output to facts already in
|
|
17
|
+
the validated log. `--format in-toto` emits only Statement JSON. The command does not append events,
|
|
18
|
+
sign output, or claim a signature.
|
|
19
|
+
|
|
20
|
+
**Added — gate outcomes are recorded, not just printed.** `principal-pi-assurance gate` now appends a
|
|
21
|
+
`gate_evaluated {gate, code, missing_count, task_id?, action?}` event for every evaluation it performs,
|
|
22
|
+
pass or block. The gate was a pure read, which is precisely why no downstream observer could prove that
|
|
23
|
+
a gate ran or how it answered; a completion claim and an unexamined run were indistinguishable in the
|
|
24
|
+
ledger. Because the workflows already invoke the gate at each control point, recording inside the
|
|
25
|
+
command required no workflow or skill text change. The event is an observation: it mutates no derived
|
|
26
|
+
state, so it cannot advance `last_change_seq` or `last_authority_seq` and can never make a receipt
|
|
27
|
+
stale, and it is accepted after `finalization_completed` so the `finish` gate can record its own
|
|
28
|
+
outcome. `missing_count` is recorded rather than the missing-control strings, which are human
|
|
29
|
+
diagnostics and not a machine contract. A ledger containing this event requires this version or newer
|
|
30
|
+
to replay. Rationale and the downstream assertion mapping: `docs/handoff/2026-09-event-vocabulary-decision.md`.
|
|
31
|
+
|
|
32
|
+
**Fixed — fail-closed measurement classification.** A closed machine-readable manifest now
|
|
33
|
+
classifies all 205 committed `results.yaml` files exactly once and binds each entry to its
|
|
34
|
+
raw SHA-256. The Terra-high control, unpinned-executor infrastructure failure, and
|
|
35
|
+
subprocess-pinned delivery-unproven run are explicitly excluded from efficacy, stability,
|
|
36
|
+
release, and v3 scoring. Historical result payloads are unchanged.
|
|
37
|
+
|
|
38
|
+
**Added — external per-observation attestation verification.** A development-only verifier
|
|
39
|
+
accepts canonical Ed25519 attestations only from explicitly configured operator-trusted
|
|
40
|
+
production keys. A closed arm policy and canonical strict future-result contract bind one
|
|
41
|
+
accepted attempt to one result/scenario/repetition; complete trust stores are eagerly checked,
|
|
42
|
+
and an in-memory validation-session registry atomically rejects replay across all evidence sets.
|
|
43
|
+
Missing, extra, stale, future, replayed, mismatched, refusal-only, incomplete, capability-only,
|
|
44
|
+
or invalidly signed evidence fails closed. Durable operational replay prevention remains the
|
|
45
|
+
external producer/controller's responsibility. No private production key is stored here. The external producer
|
|
46
|
+
remains responsible for signing-key protection, ledger authenticity, runtime identity,
|
|
47
|
+
loaded-definition and artifact/module confinement, process-tree containment, and any OS
|
|
48
|
+
sandbox.
|
|
49
|
+
|
|
50
|
+
**Fixed — Critical Plan task definitions are concrete and attributable.** Critical plans now
|
|
51
|
+
keep authority/scope before tasks, require named tests and literal targeted Done commands,
|
|
52
|
+
separate Plan definitions from controller-owned canonical packet identity/digest fields, and
|
|
53
|
+
forbid assurance-only delivery slices. With no repository context they propose concrete values
|
|
54
|
+
as assumptions and require discovery/validation before execution rather than emitting
|
|
55
|
+
placeholders or claiming guessed paths exist. `Done command` is explicitly declarative and untrusted:
|
|
56
|
+
this version provides no deterministic command or approval enforcement. Deterministic mutation
|
|
57
|
+
coverage is structural only; a fresh Wave A remains required for behavioral
|
|
58
|
+
validation. `docs/evidence/pr35-e1-repair-provenance-v1.json` hashes the E1-informed evidence,
|
|
59
|
+
including contextual D1/D2 diagnosis material; preserved measurements are unchanged.
|
|
60
|
+
|
|
61
|
+
**Changed — release evidence does not claim model measurement.** `3.0.1` contains three
|
|
62
|
+
generated Plan runtime prompt changes, the explicitly authorized assurance-state additions, and
|
|
63
|
+
Decide's approved P4 text; other shipped runtime schemas, scripts, skills, agents, and prompts remain
|
|
64
|
+
byte-identical to `3.0.0`. No 3.0.1 model score is claimed: deterministic/static checks are the
|
|
65
|
+
release evidence, while the required DeepSeek/GLM wave and live workflow cells remain unrun. At
|
|
66
|
+
release candidate cut, the remote `v3.0.1` tag is pending and npm `latest` remains `3.0.0`; neither external
|
|
67
|
+
publication result is claimed before verification.
|
|
68
|
+
|
|
9
69
|
## [3.0.0] — 2026-08-20
|
|
10
70
|
|
|
11
71
|
**Added — risk-adaptive assurance profiles on the two existing workflow spines.** `standard`
|
package/README.md
CHANGED
|
@@ -8,6 +8,12 @@ to isolated contexts (`plan`, `review`, `debug` — single-shot variants in `age
|
|
|
8
8
|
generated from the same contract as the skill). The files follow the [Agent Skills](https://agentskills.io/specification)
|
|
9
9
|
standard, so other harnesses can consume the skills, but pi is the supported target.
|
|
10
10
|
|
|
11
|
+
**Version:** `3.0.1` release candidate. The remote `v3.0.1` tag is pending and npm `latest`
|
|
12
|
+
remains `3.0.0` until both publication results are independently verified. Release coordinates
|
|
13
|
+
are npm `principal-pi-skills@3.0.1` and the immutable git tag `v3.0.1`. This version strengthens the generated Critical Plan skill/agent
|
|
14
|
+
prompts, assurance-ledger evidence, and development-only measurement verification. It carries no
|
|
15
|
+
new model score; the committed board remains a historical v2.4 baseline.
|
|
16
|
+
|
|
11
17
|
The set is built for **one principal engineer steering at a high level while skills and
|
|
12
18
|
subagents do the work.** Two properties follow, and every design choice below serves them:
|
|
13
19
|
**delegable trust** — an output carries the evidence needed to verify it without redoing
|
|
@@ -40,19 +46,21 @@ approval controls without creating another skill suite.
|
|
|
40
46
|
cases, and each wrong absolute produced a measured over-refusal. A rule plus the cases it
|
|
41
47
|
must not eat costs more words than an absolute; that is the trade. **When a fix and the
|
|
42
48
|
ceiling conflict, the ceiling moves** — trimming to fit was quietly deleting reasons a weak
|
|
43
|
-
model needed, which is a worse outcome than a longer file.
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
49
|
+
model needed, which is a worse outcome than a longer file. Plan is the local exception at
|
|
50
|
+
≤ ~1700 (agent ≤ ~1900): its Critical contract keeps packet ownership, concrete verification,
|
|
51
|
+
no-context discovery, and vertical-slice governors together after those omissions failed across
|
|
52
|
+
models. **Other agents get their own budget, ≤ ~1500**: a single-shot definition carries its
|
|
53
|
+
output template *and* the BLOCKED form *and* the no-questions mechanics, none of which a loaded
|
|
54
|
+
skill needs. Every count in the table below is checkable with `wc -w`. Nothing loads anything
|
|
47
55
|
else — a subagent reads one file and has the whole contract.
|
|
48
56
|
|
|
49
57
|
## The set
|
|
50
58
|
|
|
51
59
|
| Skill | What it does | How it runs | Words |
|
|
52
60
|
|---|---|---|---|
|
|
53
|
-
| `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline |
|
|
61
|
+
| `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline | 1055 |
|
|
54
62
|
| `architect` | System design from measurable drivers; significant or irreversible technical choices. The decision record is a section of the output, not a separate artifact | inline | 1142 |
|
|
55
|
-
| `plan` | A task turned into ordered steps and per-step specs a builder can execute without making load-bearing decisions. Writes no code | subagent (`agents/principal-plan.md`,
|
|
63
|
+
| `plan` | A task turned into ordered steps and per-step specs a builder can execute without making load-bearing decisions. Writes no code | subagent (`agents/principal-plan.md`, 1812) or inline | 1602 |
|
|
56
64
|
| `build` | Test-first implementation — code proven by a test you watched fail | inline | 1162 |
|
|
57
65
|
| `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1392) or inline | 1364 |
|
|
58
66
|
| `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1395) or inline | 1261 |
|
|
@@ -93,12 +101,13 @@ docs/demos/ the chains running end to end, repo-verifi
|
|
|
93
101
|
1. **Skills + prompts** — install an immutable tag, not a branch:
|
|
94
102
|
|
|
95
103
|
```
|
|
96
|
-
pi install git:github.com/mojomanyana/principal-pi-skills@v3.0.
|
|
104
|
+
pi install git:github.com/mojomanyana/principal-pi-skills@v3.0.1
|
|
97
105
|
```
|
|
98
106
|
|
|
99
|
-
`3.0.
|
|
100
|
-
manifest
|
|
101
|
-
|
|
107
|
+
`3.0.1` is the release represented by this source tree. The immutable tag must match its
|
|
108
|
+
manifest before publication, and npm `latest` must resolve the same version afterward. v3 adds
|
|
109
|
+
the risk-adaptive assurance profiles; `standard` is the default and preserves v2 invocation,
|
|
110
|
+
so upgrading from `2.4.0` changes no command you already type.
|
|
102
111
|
Read [Validation](#validation) first: v3 ships with **no model score of its own** — the
|
|
103
112
|
committed board is a historical v2.4 baseline. Do not turn a moving branch into
|
|
104
113
|
production install guidance.
|
|
@@ -247,6 +256,22 @@ the model's own account:
|
|
|
247
256
|
|
|
248
257
|
## Validation
|
|
249
258
|
|
|
259
|
+
The exploratory Terra-high Wave 0 contains a control, an unpinned-executor infrastructure
|
|
260
|
+
failure, and a subprocess-pinned run whose treatment delivery is unproven. None participates
|
|
261
|
+
in efficacy, stability, release, or v3 scoring. No committed pi-daddy observation has the
|
|
262
|
+
required externally produced per-observation attestation, so its current valid-treatment
|
|
263
|
+
count is **zero**. Future treatment requires a closed arm policy, strict canonical result,
|
|
264
|
+
eagerly validated arm-bound trust store, exact observation/attestation bijection, and atomic
|
|
265
|
+
corpus-level replay check. Durable operational replay prevention remains external. The
|
|
266
|
+
DeepSeek/GLM v3 wave and live workflow cells remain unrun.
|
|
267
|
+
|
|
268
|
+
`principal-pi-skills` is only a classifier, evidence-policy consumer, and verifier of
|
|
269
|
+
operator-trusted external attestations. It does not securely execute subjects, protect
|
|
270
|
+
signing keys, authenticate producer ledgers, confine modules or process trees, or provide an
|
|
271
|
+
OS sandbox/same-UID boundary. A valid signature proves that the configured producer made the
|
|
272
|
+
attestation; it does not prove that producer is securely implemented. See
|
|
273
|
+
[`docs/validation/VALIDATION.md`](docs/validation/VALIDATION.md).
|
|
274
|
+
|
|
250
275
|
v3 changes model-visible contract text, adds one `E1` assurance scenario to each skill, and adds
|
|
251
276
|
a Git-Ops stale-receipt negative, taking the static specification from 98 to **106 scenarios**.
|
|
252
277
|
Those eight scenarios are prepared but
|
package/agents/plan.md
CHANGED
|
@@ -64,6 +64,37 @@ behavior, and the test that proves it.
|
|
|
64
64
|
[ONE-WAY] step (schema migration, public API change, data deletion) with a rollback note
|
|
65
65
|
and a kill criterion.
|
|
66
66
|
|
|
67
|
+
## Critical plan contract
|
|
68
|
+
These rules apply only to Critical scope; non-Critical plans keep the right-sized forms below.
|
|
69
|
+
Critical plans never abbreviate. Before `Steps:`, emit concrete `Authority:`, `Global constraints:`,
|
|
70
|
+
`Out of scope:`, and a `Critical scope:` summary, then `Assumptions:` and `Task-packet handoff:`.
|
|
71
|
+
Every task repeats its concrete `Critical scope:` match and emits `Task ID:`, `Files:`,
|
|
72
|
+
`Dependencies:`, `Change:`, `Test:`, `Done command:`, `Expected result:`, `Review risk:`, and
|
|
73
|
+
`Ripples:` values.
|
|
74
|
+
|
|
75
|
+
Every Critical task names a stable test file and test name; test level and edge cases remain explicit.
|
|
76
|
+
`Done command:` is one literal, targeted, proposed repository-local verification invocation selecting
|
|
77
|
+
that file or test name, with the expected result in its separate field. It is declarative, untrusted
|
|
78
|
+
Plan output—not execution authorization—and is never automatically executed by Plan or packet
|
|
79
|
+
persistence. Downstream Build must inspect it against the repository before choosing whether to
|
|
80
|
+
execute it; this version provides no deterministic command or approval enforcement. Do not emit `TBD`, angle-bracket tokens, bare `node --test`, generic
|
|
81
|
+
“run tests” prose, or another broad untargeted command.
|
|
82
|
+
|
|
83
|
+
When repository context supplies real paths, tests, and commands, use those exact observed values.
|
|
84
|
+
When context is absent, propose concrete paths, names, and commands under clearly labelled
|
|
85
|
+
Assumptions requiring validation; never claim they were observed. Runtime enforcement of command
|
|
86
|
+
syntax, discovery identity, authority digests, and event-log migration is deferred to a future
|
|
87
|
+
versioned runtime contract and is not claimed here.
|
|
88
|
+
|
|
89
|
+
The controller—not Plan—owns packet persistence. Plan defines task content and stable `task_id`;
|
|
90
|
+
the controller supplies `schema_version`, `run_id`, `workspace_id`, `plan_digest`, and
|
|
91
|
+
`definition_digests`. Include that distinction in `Task-packet handoff:` without inventing
|
|
92
|
+
controller-owned identities or digests.
|
|
93
|
+
|
|
94
|
+
Every task remains a vertical behavioral slice delivering an independently testable user or system
|
|
95
|
+
outcome. Critique, packet persistence, review, handoff, and test-only ceremony are controller work,
|
|
96
|
+
not delivery slices; never add one as a final task.
|
|
97
|
+
|
|
67
98
|
## Right-sizing
|
|
68
99
|
A one-file, clearly-specified change (a config value, a small flag): reply in three lines —
|
|
69
100
|
the change, its test, done. Literally this shape, and nothing after it:
|
|
@@ -92,10 +123,11 @@ command, and review risk. The controller adds run/workspace IDs and current dige
|
|
|
92
123
|
task-packet schema, and persists; Plan never invents them. Critical always emits a task definition
|
|
93
124
|
but omits unrelated ceremony.
|
|
94
125
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
126
|
+
Critical work follows the exact Critical contract above and does not copy the generic template.
|
|
127
|
+
For non-Critical multi-step work, use the template below. Trivial reversible work gets three lines:
|
|
128
|
+
change, test, done. Small clear work gets two or three slices with a done-signal; omit Risks, spikes,
|
|
129
|
+
and dependency annotations because step order suffices. Unknown codebase facts are Assumptions. A
|
|
130
|
+
real [ONE-WAY] always survives.
|
|
99
131
|
```
|
|
100
132
|
## Plan: <outcome, one sentence>
|
|
101
133
|
Authority: <requirement IDs, approved design, or exact user request>
|
|
@@ -148,4 +180,5 @@ Have: <what the material did establish — one line>
|
|
|
148
180
|
| Accept "plan it as one step" for multi-part work | Decompose anyway and say why: one giant step blocks parallel work, hides risk, and has no honest done-signal. |
|
|
149
181
|
| Write a step like "add validation" or "handle errors" | Make it a contract: files, exact behavior, the test. If you can't name the test, it's too vague. |
|
|
150
182
|
| Spec a file you haven't opened | Open it. A spec for a fiction wastes everyone's time. |
|
|
151
|
-
| Leave
|
|
183
|
+
| Leave a Critical task's tests as the builder's homework | Name each test file and test case, its level, edge cases, and safe literal targeted command. |
|
|
184
|
+
| Add an assurance-only Critical task or final review/test/handoff slice | Keep behavioral delivery vertical; the controller owns discovery, critique, packet persistence, review, and handoff. |
|
package/agents/principal-plan.md
CHANGED
|
@@ -64,6 +64,37 @@ behavior, and the test that proves it.
|
|
|
64
64
|
[ONE-WAY] step (schema migration, public API change, data deletion) with a rollback note
|
|
65
65
|
and a kill criterion.
|
|
66
66
|
|
|
67
|
+
## Critical plan contract
|
|
68
|
+
These rules apply only to Critical scope; non-Critical plans keep the right-sized forms below.
|
|
69
|
+
Critical plans never abbreviate. Before `Steps:`, emit concrete `Authority:`, `Global constraints:`,
|
|
70
|
+
`Out of scope:`, and a `Critical scope:` summary, then `Assumptions:` and `Task-packet handoff:`.
|
|
71
|
+
Every task repeats its concrete `Critical scope:` match and emits `Task ID:`, `Files:`,
|
|
72
|
+
`Dependencies:`, `Change:`, `Test:`, `Done command:`, `Expected result:`, `Review risk:`, and
|
|
73
|
+
`Ripples:` values.
|
|
74
|
+
|
|
75
|
+
Every Critical task names a stable test file and test name; test level and edge cases remain explicit.
|
|
76
|
+
`Done command:` is one literal, targeted, proposed repository-local verification invocation selecting
|
|
77
|
+
that file or test name, with the expected result in its separate field. It is declarative, untrusted
|
|
78
|
+
Plan output—not execution authorization—and is never automatically executed by Plan or packet
|
|
79
|
+
persistence. Downstream Build must inspect it against the repository before choosing whether to
|
|
80
|
+
execute it; this version provides no deterministic command or approval enforcement. Do not emit `TBD`, angle-bracket tokens, bare `node --test`, generic
|
|
81
|
+
“run tests” prose, or another broad untargeted command.
|
|
82
|
+
|
|
83
|
+
When repository context supplies real paths, tests, and commands, use those exact observed values.
|
|
84
|
+
When context is absent, propose concrete paths, names, and commands under clearly labelled
|
|
85
|
+
Assumptions requiring validation; never claim they were observed. Runtime enforcement of command
|
|
86
|
+
syntax, discovery identity, authority digests, and event-log migration is deferred to a future
|
|
87
|
+
versioned runtime contract and is not claimed here.
|
|
88
|
+
|
|
89
|
+
The controller—not Plan—owns packet persistence. Plan defines task content and stable `task_id`;
|
|
90
|
+
the controller supplies `schema_version`, `run_id`, `workspace_id`, `plan_digest`, and
|
|
91
|
+
`definition_digests`. Include that distinction in `Task-packet handoff:` without inventing
|
|
92
|
+
controller-owned identities or digests.
|
|
93
|
+
|
|
94
|
+
Every task remains a vertical behavioral slice delivering an independently testable user or system
|
|
95
|
+
outcome. Critique, packet persistence, review, handoff, and test-only ceremony are controller work,
|
|
96
|
+
not delivery slices; never add one as a final task.
|
|
97
|
+
|
|
67
98
|
## Right-sizing
|
|
68
99
|
A one-file, clearly-specified change (a config value, a small flag): reply in three lines —
|
|
69
100
|
the change, its test, done. Literally this shape, and nothing after it:
|
|
@@ -92,10 +123,11 @@ command, and review risk. The controller adds run/workspace IDs and current dige
|
|
|
92
123
|
task-packet schema, and persists; Plan never invents them. Critical always emits a task definition
|
|
93
124
|
but omits unrelated ceremony.
|
|
94
125
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
126
|
+
Critical work follows the exact Critical contract above and does not copy the generic template.
|
|
127
|
+
For non-Critical multi-step work, use the template below. Trivial reversible work gets three lines:
|
|
128
|
+
change, test, done. Small clear work gets two or three slices with a done-signal; omit Risks, spikes,
|
|
129
|
+
and dependency annotations because step order suffices. Unknown codebase facts are Assumptions. A
|
|
130
|
+
real [ONE-WAY] always survives.
|
|
99
131
|
```
|
|
100
132
|
## Plan: <outcome, one sentence>
|
|
101
133
|
Authority: <requirement IDs, approved design, or exact user request>
|
|
@@ -148,4 +180,5 @@ Have: <what the material did establish — one line>
|
|
|
148
180
|
| Accept "plan it as one step" for multi-part work | Decompose anyway and say why: one giant step blocks parallel work, hides risk, and has no honest done-signal. |
|
|
149
181
|
| Write a step like "add validation" or "handle errors" | Make it a contract: files, exact behavior, the test. If you can't name the test, it's too vague. |
|
|
150
182
|
| Spec a file you haven't opened | Open it. A spec for a fiction wastes everyone's time. |
|
|
151
|
-
| Leave
|
|
183
|
+
| Leave a Critical task's tests as the builder's homework | Name each test file and test case, its level, edge cases, and safe literal targeted command. |
|
|
184
|
+
| Add an assurance-only Critical task or final review/test/handoff slice | Keep behavioral delivery vertical; the controller owns discovery, critique, packet persistence, review, and handoff. |
|
package/decide/SKILL.md
CHANGED
|
@@ -16,6 +16,22 @@ Help the user reach a decision they can defend in eighteen months. Your value is
|
|
|
16
16
|
what they cannot see alone, which you cannot do while agreeing with them. Two failure modes,
|
|
17
17
|
equally bad: rubber-stamping an untested idea, and manufacturing objections to look rigorous.
|
|
18
18
|
|
|
19
|
+
## Classification — announce before questions
|
|
20
|
+
Begin every response with `Path: spike | bounded | architectural — <why>` before asking a
|
|
21
|
+
question or giving analysis. This is advisory context for the orchestrator, not routing: it
|
|
22
|
+
neither chooses a successor nor changes how another phase runs.
|
|
23
|
+
|
|
24
|
+
- `spike` — use for a tiny reversible request or uncertainty where one cheap probe can supply
|
|
25
|
+
the missing fact.
|
|
26
|
+
- `bounded` — use for a contained decision with known edges, limited blast radius, and no
|
|
27
|
+
system-shaping commitment.
|
|
28
|
+
- `architectural` — use when the decision shapes system boundaries, carries broad or durable
|
|
29
|
+
consequences, or crosses a one-way door.
|
|
30
|
+
|
|
31
|
+
The path is a one-way ratchet: hidden complexity discovered mid-task upgrades it; nothing
|
|
32
|
+
downgrades it. Mark every unknown that blocks the decision as
|
|
33
|
+
`[NEEDS CLARIFICATION: <question>]` rather than answering it by assumption.
|
|
34
|
+
|
|
19
35
|
## Process
|
|
20
36
|
1. **Problem first.** Write the problem in one sentence and confirm it is the real problem.
|
|
21
37
|
If the user opened with a solution ("should I use X or Y?"), ask what problem X solves
|
|
@@ -54,6 +70,7 @@ opening move. Delegated, you cannot ask, so you always conclude: state the assum
|
|
|
54
70
|
would otherwise have asked about and produce the brief.
|
|
55
71
|
|
|
56
72
|
```
|
|
73
|
+
Path: spike | bounded | architectural — <why>
|
|
57
74
|
## Decision brief: <one-line question>
|
|
58
75
|
Problem: <one sentence>
|
|
59
76
|
Constraints: <hard limits, budgets, deadlines>
|
|
@@ -65,8 +82,13 @@ Pre-mortem (leading option): <the most likely failure story>
|
|
|
65
82
|
Decision: <choice + why, traceable to a constraint> | HOLD until <trigger>
|
|
66
83
|
Revisit when: <condition that would change the decision>
|
|
67
84
|
Reversibility: TWO-WAY | ONE-WAY — <why>
|
|
85
|
+
Confirmation: <review, check, or test that will later confirm compliance>
|
|
68
86
|
Open questions: <what would change this decision>
|
|
69
87
|
```
|
|
88
|
+
For an architectural conclusion, `Confirmation:` is required and names the review, check,
|
|
89
|
+
or test that will later show the decision was followed. Below architectural it is optional:
|
|
90
|
+
include it when later compliance needs proof, not when it would add ceremony without signal.
|
|
91
|
+
|
|
70
92
|
No `Next:` line. `decide` ends in a decision the user acts on, not a handoff a workflow
|
|
71
93
|
routes: whether that decision becomes a plan, an architecture, or nothing at all is theirs
|
|
72
94
|
to make. A skill that names its own successor is guessing at an intent it was not given.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "principal-pi-skills",
|
|
3
|
-
"version": "3.0.
|
|
3
|
+
"version": "3.0.1",
|
|
4
4
|
"description": "Skill framework for principal-level software engineering: seven dual-use skills (decide, architect, plan, build, review, debug, git-ops) that work unedited as loaded skills or as subagent system prompts.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Nemanja Alavanja",
|
package/plan/SKILL.md
CHANGED
|
@@ -48,6 +48,37 @@ behavior, and the test that proves it.
|
|
|
48
48
|
[ONE-WAY] step (schema migration, public API change, data deletion) with a rollback note
|
|
49
49
|
and a kill criterion.
|
|
50
50
|
|
|
51
|
+
## Critical plan contract
|
|
52
|
+
These rules apply only to Critical scope; non-Critical plans keep the right-sized forms below.
|
|
53
|
+
Critical plans never abbreviate. Before `Steps:`, emit concrete `Authority:`, `Global constraints:`,
|
|
54
|
+
`Out of scope:`, and a `Critical scope:` summary, then `Assumptions:` and `Task-packet handoff:`.
|
|
55
|
+
Every task repeats its concrete `Critical scope:` match and emits `Task ID:`, `Files:`,
|
|
56
|
+
`Dependencies:`, `Change:`, `Test:`, `Done command:`, `Expected result:`, `Review risk:`, and
|
|
57
|
+
`Ripples:` values.
|
|
58
|
+
|
|
59
|
+
Every Critical task names a stable test file and test name; test level and edge cases remain explicit.
|
|
60
|
+
`Done command:` is one literal, targeted, proposed repository-local verification invocation selecting
|
|
61
|
+
that file or test name, with the expected result in its separate field. It is declarative, untrusted
|
|
62
|
+
Plan output—not execution authorization—and is never automatically executed by Plan or packet
|
|
63
|
+
persistence. Downstream Build must inspect it against the repository before choosing whether to
|
|
64
|
+
execute it; this version provides no deterministic command or approval enforcement. Do not emit `TBD`, angle-bracket tokens, bare `node --test`, generic
|
|
65
|
+
“run tests” prose, or another broad untargeted command.
|
|
66
|
+
|
|
67
|
+
When repository context supplies real paths, tests, and commands, use those exact observed values.
|
|
68
|
+
When context is absent, propose concrete paths, names, and commands under clearly labelled
|
|
69
|
+
Assumptions requiring validation; never claim they were observed. Runtime enforcement of command
|
|
70
|
+
syntax, discovery identity, authority digests, and event-log migration is deferred to a future
|
|
71
|
+
versioned runtime contract and is not claimed here.
|
|
72
|
+
|
|
73
|
+
The controller—not Plan—owns packet persistence. Plan defines task content and stable `task_id`;
|
|
74
|
+
the controller supplies `schema_version`, `run_id`, `workspace_id`, `plan_digest`, and
|
|
75
|
+
`definition_digests`. Include that distinction in `Task-packet handoff:` without inventing
|
|
76
|
+
controller-owned identities or digests.
|
|
77
|
+
|
|
78
|
+
Every task remains a vertical behavioral slice delivering an independently testable user or system
|
|
79
|
+
outcome. Critique, packet persistence, review, handoff, and test-only ceremony are controller work,
|
|
80
|
+
not delivery slices; never add one as a final task.
|
|
81
|
+
|
|
51
82
|
## Right-sizing
|
|
52
83
|
A one-file, clearly-specified change (a config value, a small flag): reply in three lines —
|
|
53
84
|
the change, its test, done. Literally this shape, and nothing after it:
|
|
@@ -83,10 +114,11 @@ command, and review risk. The controller adds run/workspace IDs and current dige
|
|
|
83
114
|
task-packet schema, and persists; Plan never invents them. Critical always emits a task definition
|
|
84
115
|
but omits unrelated ceremony.
|
|
85
116
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
117
|
+
Critical work follows the exact Critical contract above and does not copy the generic template.
|
|
118
|
+
For non-Critical multi-step work, use the template below. Trivial reversible work gets three lines:
|
|
119
|
+
change, test, done. Small clear work gets two or three slices with a done-signal; omit Risks, spikes,
|
|
120
|
+
and dependency annotations because step order suffices. Unknown codebase facts are Assumptions. A
|
|
121
|
+
real [ONE-WAY] always survives.
|
|
90
122
|
```
|
|
91
123
|
## Plan: <outcome, one sentence>
|
|
92
124
|
Authority: <requirement IDs, approved design, or exact user request>
|
|
@@ -129,4 +161,5 @@ Next: build
|
|
|
129
161
|
| Accept "plan it as one step" for multi-part work | Decompose anyway and say why: one giant step blocks parallel work, hides risk, and has no honest done-signal. |
|
|
130
162
|
| Write a step like "add validation" or "handle errors" | Make it a contract: files, exact behavior, the test. If you can't name the test, it's too vague. |
|
|
131
163
|
| Spec a file you haven't opened | Open it. A spec for a fiction wastes everyone's time. |
|
|
132
|
-
| Leave
|
|
164
|
+
| Leave a Critical task's tests as the builder's homework | Name each test file and test case, its level, edge cases, and safe literal targeted command. |
|
|
165
|
+
| Add an assurance-only Critical task or final review/test/handoff slice | Keep behavioral delivery vertical; the controller owns discovery, critique, packet persistence, review, and handoff. |
|
|
@@ -67,11 +67,14 @@ const SIDE_EFFECTS = new Set([
|
|
|
67
67
|
]);
|
|
68
68
|
const BACKFILL_CONTROLS = ["frozen-diff-review", "requirements-trace", "risk-specific"];
|
|
69
69
|
const ASSURANCE_SOURCES = new Set(["default", "flag", "alias", "natural-language", "policy", "user", "user-downgrade"]);
|
|
70
|
+
const GATES = ["pre-build", "task-complete", "finalize", "finish", "repair", "side-effect"];
|
|
71
|
+
const GATE_CODES = new Set(["OK", "BLOCKED_ASSURANCE", "BLOCKED_CRITICAL_ASSURANCE"]);
|
|
70
72
|
const ISO_TIMESTAMP_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|([+-])(\d{2}):(\d{2}))$/;
|
|
71
73
|
|
|
72
74
|
export const EVENT_CONTRACT = `# principal-pi-assurance event contract v1
|
|
73
75
|
Append: principal-pi-assurance event --run-id ID <<<'{"type":"...",...}'
|
|
74
76
|
Inspect: principal-pi-assurance show --run-id ID
|
|
77
|
+
Report: principal-pi-assurance report --run-id ID [--format human|in-toto]
|
|
75
78
|
Gate: principal-pi-assurance gate --run-id ID --gate pre-build|task-complete|finalize|finish|repair|side-effect [--task-id ID] [--action ACTION]
|
|
76
79
|
The CLI supplies at, seq, run_id and hash-chain fields. Payload shapes:
|
|
77
80
|
risk_classified {type, level:tiny|substantive|consequential, reason; level is monotonic}
|
|
@@ -98,6 +101,7 @@ The CLI supplies at, seq, run_id and hash-chain fields. Payload shapes:
|
|
|
98
101
|
side_effect_approved {type, action:migration|push|publish|deletion|credential-rotation|production-access, approved_by:"user", reason}
|
|
99
102
|
finish_selected {type, choice:merge|pr|keep|discard, explicit_request:true only for discard}
|
|
100
103
|
finalization_completed {type, final_branch, head_sha, tree_sha; only after gate finalize and the Git operation}
|
|
104
|
+
gate_evaluated {type, gate, code:OK|BLOCKED_ASSURANCE|BLOCKED_CRITICAL_ASSURANCE, missing_count, task_id?, action?; the gate command appends this itself — never append it by hand}
|
|
101
105
|
Never edit events.jsonl/snapshot.json. A failed critical gate prints BLOCKED_CRITICAL_ASSURANCE.`;
|
|
102
106
|
|
|
103
107
|
const fail = (message) => {
|
|
@@ -188,12 +192,12 @@ function shellWords(text) {
|
|
|
188
192
|
const POLICY_TRIGGERS = [
|
|
189
193
|
["database/schema migration", /\b(migrat(?:e|ion|ing)|schema change|drop(?:ping)? (?:a )?(?:production\s+)?(?:table|column))\b/i],
|
|
190
194
|
["authentication or authorization", /\b(auth(?:entication|orization)?|authn|authz|authoriz(?:e|ation|ing)|oauth|permission boundary|access control)\b/i],
|
|
191
|
-
["billing or payments", /\b(billing|
|
|
192
|
-
["destructive data operation", /\b(truncate|destructive data|delete (?:all\s+)?(?:(?:production|customer)\s+)?data|data purge)\b/i],
|
|
193
|
-
["public API break", /\b(breaking (?:api|change)|public api break|remove public endpoint)\b/i],
|
|
195
|
+
["billing or payments", /\b(billing|payments?|invoices?|charges?|refunds?)\b/i],
|
|
196
|
+
["destructive data operation", /\b(truncate|destructive data|delete (?:all\s+)?(?:(?:production|customer)\s+)?data|data purge|wipe (?:all\s+)?(?:customer\s+)?records?)\b/i],
|
|
197
|
+
["public API break", /\b(breaking (?:api|change)|public api break|backwards-incompatible (?:api )?change|remove (?:a )?public endpoint)\b/i],
|
|
194
198
|
["credential or secrets work", /\b(credentials?|secrets?|api key|token rotation|private key)\b/i],
|
|
195
|
-
["protected history", /\b(force[- ]push|rewrite (?:main|master|develop)|protected history)\b/i],
|
|
196
|
-
["production side effect", /\b(production (?:deploy|access|change|operation)|run in prod)\b/i],
|
|
199
|
+
["protected history", /\b(force[- ]push|rewrite (?:main|master|develop)|rewrite history[^.\n]{0,60}protected (?:[a-z0-9._/-]+ )?branch|protected history)\b/i],
|
|
200
|
+
["production side effect", /\b(production (?:deploy|access|change|operation)|run in prod|roll out[^.\n]{0,60}to production)\b/i],
|
|
197
201
|
];
|
|
198
202
|
|
|
199
203
|
function flagValue(words, name) {
|
|
@@ -212,7 +216,7 @@ function flagValue(words, name) {
|
|
|
212
216
|
return values.at(-1) ?? null;
|
|
213
217
|
}
|
|
214
218
|
|
|
215
|
-
/** Parse command flags and the
|
|
219
|
+
/** Parse command flags and the bounded natural-language critical request patterns. */
|
|
216
220
|
export function parseWorkflowRequest(request) {
|
|
217
221
|
if (!nonEmpty(request)) fail("workflow request must be a non-empty string");
|
|
218
222
|
const words = shellWords(request);
|
|
@@ -224,6 +228,19 @@ export function parseWorkflowRequest(request) {
|
|
|
224
228
|
let requested = "standard";
|
|
225
229
|
let source = "default";
|
|
226
230
|
let reason = "No assurance profile was requested; standard is the default.";
|
|
231
|
+
// Interpret explicit assurance intent per clause so a local negation does not veto a later,
|
|
232
|
+
// affirmative escalation in the same request.
|
|
233
|
+
const naturalCriticalRequest = request.split(/\bthen\b|[,.;\n]/i).some((clause) => {
|
|
234
|
+
const affirmative =
|
|
235
|
+
/\btreat (?:this|the (?:run|task)|this work) as (?:a )?critical(?:[- ]assurance)?\b/i.test(clause) ||
|
|
236
|
+
/\b(?:escalate|elevate|raise) (?:this|the)?\s*(?:run|task)?\s*(?:to|into) critical(?: assurance| mode)?\b/i.test(clause) ||
|
|
237
|
+
/\b(?:use\s+)?critical assurance\b/i.test(clause) ||
|
|
238
|
+
/\bhigh assurance\b/i.test(clause);
|
|
239
|
+
const negated =
|
|
240
|
+
/\b(?:do not|don't|no need to|not)\b[^.\n]{0,40}\b(?:critical assurance|critical[- ]assurance|critical mode)\b/i.test(clause) ||
|
|
241
|
+
/\bcritical assurance\b[^.\n]{0,30}\b(?:is |seems )?(?:unnecessary|not needed)\b/i.test(clause);
|
|
242
|
+
return affirmative && !negated;
|
|
243
|
+
});
|
|
227
244
|
|
|
228
245
|
if (rawProfile) {
|
|
229
246
|
const normalized = rawProfile.toLowerCase();
|
|
@@ -240,12 +257,7 @@ export function parseWorkflowRequest(request) {
|
|
|
240
257
|
requested = "critical";
|
|
241
258
|
source = "flag";
|
|
242
259
|
reason = "A critical scope was supplied, which explicitly requests critical assurance.";
|
|
243
|
-
} else if (
|
|
244
|
-
/\btreat (?:this|the (?:run|task)) as critical\b/i.test(request) ||
|
|
245
|
-
/\b(?:escalate|elevate) (?:this|the)?\s*(?:run|task)?\s*to critical\b/i.test(request) ||
|
|
246
|
-
/\b(?:use\s+)?critical assurance\b/i.test(request) ||
|
|
247
|
-
/\bhigh assurance\b/i.test(request)
|
|
248
|
-
) {
|
|
260
|
+
} else if (naturalCriticalRequest) {
|
|
249
261
|
requested = "critical";
|
|
250
262
|
source = "natural-language";
|
|
251
263
|
reason = "The user requested critical assurance in natural language.";
|
|
@@ -271,16 +283,19 @@ export function parseWorkflowRequest(request) {
|
|
|
271
283
|
// The policy elevation is deliberately standard -> critical. An explicit lean request is
|
|
272
284
|
// not silently rewritten; one-way operations still retain their existing approval gates.
|
|
273
285
|
if (requested === "standard") {
|
|
286
|
+
// A risk word in the artifact being edited is not itself a risky operation. This narrow
|
|
287
|
+
// exemption covers explicit docs/comment corrections and test-only renames; coordinated or
|
|
288
|
+
// operational work below still wins and elevates.
|
|
274
289
|
const tinyDocumentation =
|
|
275
|
-
/\b(typo|spelling|
|
|
290
|
+
/\b(?:fix|correct|clarify|reword|rewrap|reformat|rename|update|remove)\b[^.\n]{0,80}\b(?:typo|spelling|comments?|readme|docs?|documentation|runbook wording|tests?[/\\][^\s]*|test (?:file|helper|utility|title))\b/i.test(request) &&
|
|
276
291
|
!/\b(execute|apply|run (?:the )?migration|rotate|delete data|deploy|push|publish)\b/i.test(request);
|
|
277
292
|
const riskAction = /\b(add|implement|enable|introduce|wire|change|modify|migrate|execute|apply|rotate|delete|deploy|integrate|drop|truncate|remove|break|refund|charge|revoke|purge|force|run|access|process|authorize)\b/i;
|
|
278
293
|
const coordinatedWork = /\b(and|plus|then|also)\b|[,;]/i.test(request) && riskAction.test(request);
|
|
279
|
-
const
|
|
280
|
-
/\b(add|implement|enable|introduce|wire|
|
|
281
|
-
/\b(
|
|
294
|
+
const riskImplementation =
|
|
295
|
+
/\b(?:add|implement|enable|introduce|wire|migrate|execute|apply|rotate|deploy|integrate|drop|truncate|refund|charge|revoke|purge|process|authorize)\b[^.\n]{0,100}\b(?:auth(?:entication|orization)?|authn|authz|billing|payments?|invoices?|charges?|refunds?|credentials?|secrets?|production|schema|migration|table|column|public api|customer data)\b/i.test(request) ||
|
|
296
|
+
/\b(?:delete (?:all )?(?:production |customer )?data|remove (?:a )?public endpoint|force[- ]push|rewrite history|roll out)\b/i.test(request);
|
|
282
297
|
const candidate = POLICY_TRIGGERS.find(([, pattern]) => pattern.test(request))?.[0] ?? null;
|
|
283
|
-
riskTrigger = tinyDocumentation && !
|
|
298
|
+
riskTrigger = tinyDocumentation && !coordinatedWork && !riskImplementation ? null : candidate;
|
|
284
299
|
if (riskTrigger) {
|
|
285
300
|
effective = "critical";
|
|
286
301
|
source = "policy";
|
|
@@ -1056,7 +1071,9 @@ export function applyEvent(input, rawEvent) {
|
|
|
1056
1071
|
const event = clone(rawEvent);
|
|
1057
1072
|
if (!nonEmpty(event.type)) fail("event.type is required");
|
|
1058
1073
|
if (!validTimestamp(event.at)) fail("event.at must be an ISO date-time");
|
|
1059
|
-
|
|
1074
|
+
// `gate_evaluated` observes and never mutates the derived state, so the `finish` gate can still
|
|
1075
|
+
// record its own outcome after `finalization_completed` has already finished the run.
|
|
1076
|
+
if (state.status === "finished" && event.type !== "gate_evaluated") fail("finished run state is immutable");
|
|
1060
1077
|
const seq = event.seq ?? state.event_seq + 1;
|
|
1061
1078
|
if (!Number.isInteger(seq) || seq !== state.event_seq + 1) fail(`event sequence must be ${state.event_seq + 1}`);
|
|
1062
1079
|
for (const field of ["task_id", "workspace_id", "context_id", "finding_id"]) {
|
|
@@ -1579,6 +1596,17 @@ export function applyEvent(input, rawEvent) {
|
|
|
1579
1596
|
if (event.approved_by !== "user" || !nonEmpty(event.reason)) fail("side-effect approval requires the user and a consequence-aware reason");
|
|
1580
1597
|
state.approvals.push({ action: event.action, approved_by: "user", reason: event.reason, approved_at: event.at, seq });
|
|
1581
1598
|
break;
|
|
1599
|
+
case "gate_evaluated":
|
|
1600
|
+
// Observation only. The log records that a gate ran and how it answered; the derived state is
|
|
1601
|
+
// deliberately unchanged, which is what lets this event exist without a snapshot schema change
|
|
1602
|
+
// and without disturbing the freshness floors (`last_change_seq`, `last_authority_seq`).
|
|
1603
|
+
if (!GATES.includes(event.gate)) fail(`gate_evaluated gate ${JSON.stringify(event.gate)} is invalid`);
|
|
1604
|
+
if (!GATE_CODES.has(event.code)) fail("gate_evaluated code must be OK, BLOCKED_ASSURANCE, or BLOCKED_CRITICAL_ASSURANCE");
|
|
1605
|
+
if (!Number.isInteger(event.missing_count) || event.missing_count < 0) {
|
|
1606
|
+
fail("gate_evaluated missing_count must be a non-negative integer");
|
|
1607
|
+
}
|
|
1608
|
+
if ((event.code === "OK") !== (event.missing_count === 0)) fail("gate_evaluated code and missing_count disagree");
|
|
1609
|
+
break;
|
|
1582
1610
|
default:
|
|
1583
1611
|
fail(`unknown event type ${JSON.stringify(event.type)}`);
|
|
1584
1612
|
}
|
|
@@ -1667,7 +1695,7 @@ export class AssuranceStore {
|
|
|
1667
1695
|
});
|
|
1668
1696
|
}
|
|
1669
1697
|
|
|
1670
|
-
load(runId) {
|
|
1698
|
+
load(runId, { withEvents = false } = {}) {
|
|
1671
1699
|
const paths = this.paths(runId);
|
|
1672
1700
|
if (!existsSync(paths.log)) fail(`unknown run ${runId}`);
|
|
1673
1701
|
const lines = readFileSync(paths.log, "utf8")
|
|
@@ -1676,6 +1704,7 @@ export class AssuranceStore {
|
|
|
1676
1704
|
if (lines.length === 0) fail("event-log integrity failure: log is empty");
|
|
1677
1705
|
let state = null;
|
|
1678
1706
|
let previous = null;
|
|
1707
|
+
const events = [];
|
|
1679
1708
|
for (let index = 0; index < lines.length; index++) {
|
|
1680
1709
|
let event;
|
|
1681
1710
|
try {
|
|
@@ -1706,8 +1735,9 @@ export class AssuranceStore {
|
|
|
1706
1735
|
state.event_digest = event.event_digest;
|
|
1707
1736
|
}
|
|
1708
1737
|
previous = event.event_digest;
|
|
1738
|
+
events.push(event);
|
|
1709
1739
|
}
|
|
1710
|
-
return state;
|
|
1740
|
+
return withEvents ? { state, events } : state;
|
|
1711
1741
|
}
|
|
1712
1742
|
|
|
1713
1743
|
append(runId, payload) {
|
|
@@ -1757,6 +1787,135 @@ function stdin() {
|
|
|
1757
1787
|
return readFileSync(0, "utf8");
|
|
1758
1788
|
}
|
|
1759
1789
|
|
|
1790
|
+
const quoted = (value) => JSON.stringify(value);
|
|
1791
|
+
const receiptName = (event) => `${event.kind} (seq ${event.seq}): ${event.command}`;
|
|
1792
|
+
|
|
1793
|
+
/** Project validated ledger events into an unsigned in-toto test-result Statement. */
|
|
1794
|
+
export function buildAssuranceStatement(events) {
|
|
1795
|
+
const evidence = events.filter((event) => event.type === "evidence_recorded");
|
|
1796
|
+
const finalization = events.findLast((event) => event.type === "finalization_completed") ?? null;
|
|
1797
|
+
const subject = finalization
|
|
1798
|
+
? [
|
|
1799
|
+
{ name: "head_sha", digest: { gitCommit: finalization.head_sha } },
|
|
1800
|
+
{ name: "tree_sha", digest: { gitTree: finalization.tree_sha } },
|
|
1801
|
+
]
|
|
1802
|
+
: [];
|
|
1803
|
+
return {
|
|
1804
|
+
_type: "https://in-toto.io/Statement/v1",
|
|
1805
|
+
subject,
|
|
1806
|
+
predicateType: "https://in-toto.io/attestation/test-result/v0.1",
|
|
1807
|
+
predicate: {
|
|
1808
|
+
result: evidence.length > 0 && evidence.every((receipt) => receipt.exit_code === 0) ? "PASSED" : "FAILED",
|
|
1809
|
+
configuration: evidence.map((receipt) => ({ name: receipt.command })),
|
|
1810
|
+
passedTests: evidence.filter((receipt) => receipt.exit_code === 0).map(receiptName),
|
|
1811
|
+
warnedTests: [],
|
|
1812
|
+
failedTests: evidence.filter((receipt) => receipt.exit_code !== 0).map(receiptName),
|
|
1813
|
+
ledger: {
|
|
1814
|
+
runId: events[0]?.run_id ?? null,
|
|
1815
|
+
schemaVersion: events[0]?.schema_version ?? null,
|
|
1816
|
+
eventCount: events.length,
|
|
1817
|
+
hashChainHead: events.at(-1)?.event_digest ?? null,
|
|
1818
|
+
},
|
|
1819
|
+
},
|
|
1820
|
+
};
|
|
1821
|
+
}
|
|
1822
|
+
|
|
1823
|
+
/** Render only facts carried by a validated ledger; absent categories stay explicitly absent. */
|
|
1824
|
+
export function renderAssuranceReport(state, events) {
|
|
1825
|
+
const taskEvents = events.filter((event) => event.type === "task_packet_recorded");
|
|
1826
|
+
const changes = events.filter((event) => event.type === "code_changed");
|
|
1827
|
+
const evidence = events.filter((event) => event.type === "evidence_recorded");
|
|
1828
|
+
const reviews = events.filter((event) => event.type === "review_recorded");
|
|
1829
|
+
const gates = events.filter((event) => event.type === "gate_evaluated");
|
|
1830
|
+
const findingEvents = events.filter((event) => event.type === "finding_recorded");
|
|
1831
|
+
const adjudications = new Map(events
|
|
1832
|
+
.filter((event) => event.type === "finding_adjudicated")
|
|
1833
|
+
.map((event) => [event.finding_id, event]));
|
|
1834
|
+
const finish = events.find((event) => event.type === "finish_selected") ?? null;
|
|
1835
|
+
const finalization = events.find((event) => event.type === "finalization_completed") ?? null;
|
|
1836
|
+
const lines = [
|
|
1837
|
+
`# Assurance report: ${state.run_id}`,
|
|
1838
|
+
"",
|
|
1839
|
+
"## Authority",
|
|
1840
|
+
`- Request: ${quoted(state.request)}`,
|
|
1841
|
+
`- Effective assurance: ${state.assurance.effective}`,
|
|
1842
|
+
`- Assurance source: ${state.assurance.source}`,
|
|
1843
|
+
`- Risk level: ${state.risk.level}`,
|
|
1844
|
+
"",
|
|
1845
|
+
"## Tasks and their packets",
|
|
1846
|
+
...(taskEvents.length
|
|
1847
|
+
? taskEvents.map((event) => `- ${event.packet.task_id}: ${JSON.stringify(event.packet)}`)
|
|
1848
|
+
: ["- Absent."]),
|
|
1849
|
+
"",
|
|
1850
|
+
"## Changed paths",
|
|
1851
|
+
...(changes.length
|
|
1852
|
+
? changes.map((event) => `- seq ${event.seq}: ${event.changed_paths.join(", ")}`)
|
|
1853
|
+
: ["- Absent."]),
|
|
1854
|
+
"",
|
|
1855
|
+
"## Evidence receipts",
|
|
1856
|
+
...(evidence.length
|
|
1857
|
+
? evidence.map((event) =>
|
|
1858
|
+
`- seq ${event.seq}: kind=${event.kind}; command=${quoted(event.command)}; exit_code=${event.exit_code}; head_sha=${event.head_sha}; tree_sha=${event.tree_sha}`)
|
|
1859
|
+
: ["- Absent."]),
|
|
1860
|
+
"",
|
|
1861
|
+
"## Review verdicts by axis",
|
|
1862
|
+
...(reviews.length
|
|
1863
|
+
? reviews.map((event) => `- seq ${event.seq}: axis=${event.axis}; verdict=${event.verdict}; context_id=${event.context_id}`)
|
|
1864
|
+
: ["- Absent."]),
|
|
1865
|
+
"",
|
|
1866
|
+
"## Gate evaluations",
|
|
1867
|
+
...(gates.length
|
|
1868
|
+
? gates.map((event) =>
|
|
1869
|
+
`- seq ${event.seq}: gate=${event.gate}; code=${event.code}; missing_count=${event.missing_count}` +
|
|
1870
|
+
`${event.task_id ? `; task_id=${event.task_id}` : ""}${event.action ? `; action=${event.action}` : ""}`)
|
|
1871
|
+
: ["- Absent."]),
|
|
1872
|
+
"",
|
|
1873
|
+
"## Findings and their adjudications",
|
|
1874
|
+
...(findingEvents.length
|
|
1875
|
+
? findingEvents.map((event) => {
|
|
1876
|
+
const adjudication = adjudications.get(event.finding_id);
|
|
1877
|
+
return `- ${event.finding_id}: summary=${quoted(event.summary)}; evidence=${event.evidence == null ? "Absent." : quoted(event.evidence)}; ` +
|
|
1878
|
+
`disposition=${adjudication?.disposition ?? "Absent."}; reason=${adjudication ? quoted(adjudication.reason) : "Absent."}`;
|
|
1879
|
+
})
|
|
1880
|
+
: ["- Absent."]),
|
|
1881
|
+
"",
|
|
1882
|
+
"## Finish and finalization",
|
|
1883
|
+
`- Finish choice: ${finish?.choice ?? "Absent."}`,
|
|
1884
|
+
finalization
|
|
1885
|
+
? `- Finalization: branch=${quoted(finalization.final_branch)}; head_sha=${finalization.head_sha}; tree_sha=${finalization.tree_sha}`
|
|
1886
|
+
: "- Finalization: Absent.",
|
|
1887
|
+
];
|
|
1888
|
+
const gaps = [
|
|
1889
|
+
...(state.risk.level === "unknown" ? ["Risk classification is absent."] : []),
|
|
1890
|
+
...(taskEvents.length === 0 ? ["Task packets are absent."] : []),
|
|
1891
|
+
...(changes.length === 0 ? ["Changed paths are absent."] : []),
|
|
1892
|
+
...(evidence.length === 0 ? ["Evidence receipts are absent."] : []),
|
|
1893
|
+
...(reviews.length === 0 ? ["Review verdicts are absent."] : []),
|
|
1894
|
+
...(gates.length === 0 ? ["Gate evaluations are absent."] : []),
|
|
1895
|
+
...(findingEvents.length === 0 ? ["Findings are absent."] : []),
|
|
1896
|
+
...findingEvents.filter((event) => !adjudications.has(event.finding_id))
|
|
1897
|
+
.map((event) => `Adjudication for ${event.finding_id} is absent.`),
|
|
1898
|
+
...(!finish ? ["Finish choice is absent."] : []),
|
|
1899
|
+
...(!finalization ? ["Finalization identity is absent."] : []),
|
|
1900
|
+
];
|
|
1901
|
+
lines.push(
|
|
1902
|
+
"",
|
|
1903
|
+
"## Evidence gaps",
|
|
1904
|
+
...(gaps.length ? gaps.map((gap) => `- ${gap}`) : ["- None among the reportable ledger sections."]),
|
|
1905
|
+
"",
|
|
1906
|
+
"## Assumptions",
|
|
1907
|
+
"- None. Absent ledger facts are not inferred.",
|
|
1908
|
+
"",
|
|
1909
|
+
"## Machine section — unsigned in-toto Statement",
|
|
1910
|
+
"No signature is produced by this projection.",
|
|
1911
|
+
"",
|
|
1912
|
+
"```json",
|
|
1913
|
+
JSON.stringify(buildAssuranceStatement(events), null, 2),
|
|
1914
|
+
"```",
|
|
1915
|
+
);
|
|
1916
|
+
return lines.join("\n");
|
|
1917
|
+
}
|
|
1918
|
+
|
|
1760
1919
|
export function runCli(argv, { cwd = process.cwd(), env = process.env, out = console.log, err = console.error, input = stdin } = {}) {
|
|
1761
1920
|
try {
|
|
1762
1921
|
const [command] = argv;
|
|
@@ -1780,6 +1939,16 @@ export function runCli(argv, { cwd = process.cwd(), env = process.env, out = con
|
|
|
1780
1939
|
out(JSON.stringify(store.load(cliFlag(argv, "--run-id")), null, 2));
|
|
1781
1940
|
return 0;
|
|
1782
1941
|
}
|
|
1942
|
+
if (command === "report") {
|
|
1943
|
+
const runId = cliFlag(argv, "--run-id");
|
|
1944
|
+
const format = cliFlag(argv, "--format", "human");
|
|
1945
|
+
if (!["human", "in-toto"].includes(format)) fail("--format must be human or in-toto");
|
|
1946
|
+
const { state, events } = store.load(runId, { withEvents: true });
|
|
1947
|
+
out(format === "in-toto"
|
|
1948
|
+
? JSON.stringify(buildAssuranceStatement(events), null, 2)
|
|
1949
|
+
: renderAssuranceReport(state, events));
|
|
1950
|
+
return 0;
|
|
1951
|
+
}
|
|
1783
1952
|
if (command === "event") {
|
|
1784
1953
|
const runId = cliFlag(argv, "--run-id");
|
|
1785
1954
|
const raw = cliFlag(argv, "--json", null) ?? stdin();
|
|
@@ -1789,14 +1958,32 @@ export function runCli(argv, { cwd = process.cwd(), env = process.env, out = con
|
|
|
1789
1958
|
}
|
|
1790
1959
|
if (command === "gate") {
|
|
1791
1960
|
const runId = cliFlag(argv, "--run-id");
|
|
1792
|
-
const
|
|
1793
|
-
|
|
1794
|
-
|
|
1795
|
-
});
|
|
1961
|
+
const gate = cliFlag(argv, "--gate");
|
|
1962
|
+
const taskId = cliFlag(argv, "--task-id");
|
|
1963
|
+
const action = cliFlag(argv, "--action");
|
|
1964
|
+
const result = evaluateGate(store.load(runId), gate, { task_id: taskId, action });
|
|
1965
|
+
// A gate outcome nobody can produce as evidence is the hole this event closes, so recording
|
|
1966
|
+
// failure is an error rather than a silent pass. A blocked gate still returns 3: the block is
|
|
1967
|
+
// the more important fact, and swallowing it to report a logging problem would invert them.
|
|
1968
|
+
let recorded = true;
|
|
1969
|
+
try {
|
|
1970
|
+
store.append(runId, {
|
|
1971
|
+
type: "gate_evaluated",
|
|
1972
|
+
gate,
|
|
1973
|
+
code: result.code,
|
|
1974
|
+
missing_count: result.missing.length,
|
|
1975
|
+
...(taskId ? { task_id: taskId } : {}),
|
|
1976
|
+
...(action ? { action } : {}),
|
|
1977
|
+
});
|
|
1978
|
+
} catch (error) {
|
|
1979
|
+
recorded = false;
|
|
1980
|
+
err(`gate outcome could not be recorded: ${error.message}`);
|
|
1981
|
+
}
|
|
1796
1982
|
if (!result.ok) {
|
|
1797
1983
|
err(`${result.code}\nMissing controls:\n${result.missing.map((item) => `- ${item}`).join("\n")}`);
|
|
1798
1984
|
return 3;
|
|
1799
1985
|
}
|
|
1986
|
+
if (!recorded) return 1;
|
|
1800
1987
|
out("OK");
|
|
1801
1988
|
return 0;
|
|
1802
1989
|
}
|
|
@@ -1821,7 +2008,7 @@ export function runCli(argv, { cwd = process.cwd(), env = process.env, out = con
|
|
|
1821
2008
|
return 0;
|
|
1822
2009
|
}
|
|
1823
2010
|
|
|
1824
|
-
err("usage: principal-pi-assurance <contract|init|show|event|gate|validate-task|digest|where> [options]");
|
|
2011
|
+
err("usage: principal-pi-assurance <contract|init|show|report|event|gate|validate-task|digest|where> [options]");
|
|
1825
2012
|
return 2;
|
|
1826
2013
|
} catch (error) {
|
|
1827
2014
|
err(`✗ ${error instanceof Error ? error.message : String(error)}`);
|