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 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.0` — the current
123
- published release, and the tag this source tree's manifest matches. `standard` is the
124
- default assurance profile, so a v2 invocation keeps working unchanged. It registers the
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. **Agents
44
- get their own budget, ≤ ~1500**: a single-shot definition carries its output template
45
- *and* the BLOCKED form *and* the no-questions mechanics, none of which a loaded skill
46
- needs. Every count in the table below is checkable with `wc -w`. Nothing loads anything
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 | 860 |
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`, 1467) or inline | 1257 |
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.0
104
+ pi install git:github.com/mojomanyana/principal-pi-skills@v3.0.1
97
105
  ```
98
106
 
99
- `3.0.0` is the current published npm release, and the tag matches this checkout's
100
- manifest. It adds the risk-adaptive assurance profiles; `standard` is the default and
101
- preserves v2 invocation, so upgrading from `2.4.0` changes no command you already type.
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
- Use this template for multi-step work. Trivial reversible work gets three lines: change, test, done.
96
- Small clear work gets two or three slices with a done-signal; omit Risks, spikes, and dependency
97
- annotations because step order suffices. Unknown codebase facts are Assumptions. A real [ONE-WAY]
98
- always survives.
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 the tests as the builder's homework | Name each test, its level, and its edge cases in the step. |
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. |
@@ -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
- Use this template for multi-step work. Trivial reversible work gets three lines: change, test, done.
96
- Small clear work gets two or three slices with a done-signal; omit Risks, spikes, and dependency
97
- annotations because step order suffices. Unknown codebase facts are Assumptions. A real [ONE-WAY]
98
- always survives.
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 the tests as the builder's homework | Name each test, its level, and its edge cases in the step. |
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.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
- Use this template for multi-step work. Trivial reversible work gets three lines: change, test, done.
87
- Small clear work gets two or three slices with a done-signal; omit Risks, spikes, and dependency
88
- annotations because step order suffices. Unknown codebase facts are Assumptions. A real [ONE-WAY]
89
- always survives.
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 the tests as the builder's homework | Name each test, its level, and its edge cases in the step. |
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|payment|invoice|charge|refund)\b/i],
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 two documented natural-language critical requests. */
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|comment|readme|docs?|documentation|runbook wording)\b/i.test(request) &&
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 mixedRiskImplementation = coordinatedWork ||
280
- /\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[^.\n]{0,100}\b(auth(?:entication|orization)?|authn|authz|authoriz(?:e|ation)|billing|payment|invoice|refund|charge|credential|secret|production|schema|migration|table|column|public api|customer data)\b/i.test(request) ||
281
- /\b(auth(?:entication|orization)?|authn|authz|authoriz(?:e|ation)|billing|payment|invoice|refund|charge|credential|secret|production|schema|migration|table|column|public api|customer data)\b[^.\n]{0,100}\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.test(request);
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 && !mixedRiskImplementation ? null : candidate;
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
- if (state.status === "finished") fail("finished run state is immutable");
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 result = evaluateGate(store.load(runId), cliFlag(argv, "--gate"), {
1793
- task_id: cliFlag(argv, "--task-id"),
1794
- action: cliFlag(argv, "--action"),
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)}`);