principal-pi-skills 3.0.0 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +7 -3
- package/CHANGELOG.md +86 -0
- package/README.md +39 -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 +360 -26
package/AGENTS.md
CHANGED
|
@@ -119,9 +119,13 @@ to every output.
|
|
|
119
119
|
|
|
120
120
|
## Setup (pi)
|
|
121
121
|
|
|
122
|
-
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v3.
|
|
123
|
-
|
|
124
|
-
|
|
122
|
+
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v3.1.0` — the immutable install
|
|
123
|
+
coordinate for source version `3.1.0`. Publication status is external to these package bytes:
|
|
124
|
+
run `npm view principal-pi-skills version dist-tags --json` and check the
|
|
125
|
+
[GitHub release](https://github.com/mojomanyana/principal-pi-skills/releases/tag/v3.1.0) before
|
|
126
|
+
installing. Preparation evidence (2026-09-11): `v3.1.0` was pending and npm `latest` was `3.0.1`;
|
|
127
|
+
this dated fact is not current registry guidance. `standard` is the default assurance
|
|
128
|
+
profile, so a v2 invocation keeps working unchanged. It registers the
|
|
125
129
|
skills and the `/principal-feature` + `/principal-bugfix` commands via the `pi`
|
|
126
130
|
manifest. Install a tag, not a branch.
|
|
127
131
|
2. Subagents need pi-mono's subagent extension (`examples/extensions/subagent`, which ships
|
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,92 @@ Where review revealed a prior claim or design decision didn't hold up under clos
|
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
+
## [3.1.0] — 2026-09-11
|
|
10
|
+
|
|
11
|
+
**Added — opt-in current evidence applicability projection.** The shipped assurance CLI now supports
|
|
12
|
+
`report --format current-v1`, a deterministic read-only projection that distinguishes current,
|
|
13
|
+
failed, missing, stale, and superseded evidence for cross-repository consumers. Bounded descriptor
|
|
14
|
+
reads protect the opt-in replay path. Existing default human and in-toto report bytes, native gates,
|
|
15
|
+
acceptance semantics, and ordinary ledger loading remain unchanged.
|
|
16
|
+
|
|
17
|
+
**Validated — explicit cross-repository compatibility without expanding this package.** Source-only
|
|
18
|
+
host adapters, native-reference journals, generic lifecycle envelopes, and pinned compatibility
|
|
19
|
+
fixtures prove structural association with existing work views, receipt claims, check lifecycle, and
|
|
20
|
+
caller-owned payload archive seams. They do not authenticate approval, grant execution authority, or
|
|
21
|
+
package peer implementations. Those helper scripts and contracts are deliberately not shipped in the
|
|
22
|
+
npm artifact; the package remains exactly 28 files and ships Principal's assurance projection only.
|
|
23
|
+
|
|
24
|
+
**Fixed — Principal journal diagnostics remain attributable.** Journal/context failures retain their
|
|
25
|
+
specific `REFERENCE_*` codes through the reader, projector, and CLI instead of blaming the native
|
|
26
|
+
ledger. Well-formed noncanonical journal entries are distinct from invalid JSON. Validation remains
|
|
27
|
+
fail-closed and historical journals are never rewritten.
|
|
28
|
+
|
|
29
|
+
**Changed — release evidence remains static and model-free.** No skill, prompt, or agent text changed
|
|
30
|
+
from `3.0.1`, and no 3.1.0 model score is claimed. Deterministic unit, generated-contract, clean-install,
|
|
31
|
+
pack, and lint checks are the release evidence. Preparation evidence (2026-09-11): the remote
|
|
32
|
+
`v3.1.0` tag was pending and npm `latest` was `3.0.1`; this records preparation, not current
|
|
33
|
+
publication state. Check live status with `npm view principal-pi-skills version dist-tags --json` and
|
|
34
|
+
the [GitHub release](https://github.com/mojomanyana/principal-pi-skills/releases/tag/v3.1.0).
|
|
35
|
+
|
|
36
|
+
## [3.0.1] — 2026-09-04
|
|
37
|
+
|
|
38
|
+
**Added — assurance ledgers have a read-only evidence projection.**
|
|
39
|
+
`principal-pi-assurance report --run-id <id>` renders authority, packets, changed paths, receipts,
|
|
40
|
+
reviews, recorded gate outcomes, findings/adjudications, and finish identity in deterministic human
|
|
41
|
+
sections, with absent facts and assumptions labelled rather than inferred. It also emits an unsigned
|
|
42
|
+
in-toto Statement v1 using the test-result v0.1 predicate; final head/tree subjects, receipt-derived
|
|
43
|
+
configuration and pass/fail lists, and the ledger hash-chain head bind the output to facts already in
|
|
44
|
+
the validated log. `--format in-toto` emits only Statement JSON. The command does not append events,
|
|
45
|
+
sign output, or claim a signature.
|
|
46
|
+
|
|
47
|
+
**Added — gate outcomes are recorded, not just printed.** `principal-pi-assurance gate` now appends a
|
|
48
|
+
`gate_evaluated {gate, code, missing_count, task_id?, action?}` event for every evaluation it performs,
|
|
49
|
+
pass or block. The gate was a pure read, which is precisely why no downstream observer could prove that
|
|
50
|
+
a gate ran or how it answered; a completion claim and an unexamined run were indistinguishable in the
|
|
51
|
+
ledger. Because the workflows already invoke the gate at each control point, recording inside the
|
|
52
|
+
command required no workflow or skill text change. The event is an observation: it mutates no derived
|
|
53
|
+
state, so it cannot advance `last_change_seq` or `last_authority_seq` and can never make a receipt
|
|
54
|
+
stale, and it is accepted after `finalization_completed` so the `finish` gate can record its own
|
|
55
|
+
outcome. `missing_count` is recorded rather than the missing-control strings, which are human
|
|
56
|
+
diagnostics and not a machine contract. A ledger containing this event requires this version or newer
|
|
57
|
+
to replay. Rationale and the downstream assertion mapping: `docs/handoff/2026-09-event-vocabulary-decision.md`.
|
|
58
|
+
|
|
59
|
+
**Fixed — fail-closed measurement classification.** A closed machine-readable manifest now
|
|
60
|
+
classifies all 205 committed `results.yaml` files exactly once and binds each entry to its
|
|
61
|
+
raw SHA-256. The Terra-high control, unpinned-executor infrastructure failure, and
|
|
62
|
+
subprocess-pinned delivery-unproven run are explicitly excluded from efficacy, stability,
|
|
63
|
+
release, and v3 scoring. Historical result payloads are unchanged.
|
|
64
|
+
|
|
65
|
+
**Added — external per-observation attestation verification.** A development-only verifier
|
|
66
|
+
accepts canonical Ed25519 attestations only from explicitly configured operator-trusted
|
|
67
|
+
production keys. A closed arm policy and canonical strict future-result contract bind one
|
|
68
|
+
accepted attempt to one result/scenario/repetition; complete trust stores are eagerly checked,
|
|
69
|
+
and an in-memory validation-session registry atomically rejects replay across all evidence sets.
|
|
70
|
+
Missing, extra, stale, future, replayed, mismatched, refusal-only, incomplete, capability-only,
|
|
71
|
+
or invalidly signed evidence fails closed. Durable operational replay prevention remains the
|
|
72
|
+
external producer/controller's responsibility. No private production key is stored here. The external producer
|
|
73
|
+
remains responsible for signing-key protection, ledger authenticity, runtime identity,
|
|
74
|
+
loaded-definition and artifact/module confinement, process-tree containment, and any OS
|
|
75
|
+
sandbox.
|
|
76
|
+
|
|
77
|
+
**Fixed — Critical Plan task definitions are concrete and attributable.** Critical plans now
|
|
78
|
+
keep authority/scope before tasks, require named tests and literal targeted Done commands,
|
|
79
|
+
separate Plan definitions from controller-owned canonical packet identity/digest fields, and
|
|
80
|
+
forbid assurance-only delivery slices. With no repository context they propose concrete values
|
|
81
|
+
as assumptions and require discovery/validation before execution rather than emitting
|
|
82
|
+
placeholders or claiming guessed paths exist. `Done command` is explicitly declarative and untrusted:
|
|
83
|
+
this version provides no deterministic command or approval enforcement. Deterministic mutation
|
|
84
|
+
coverage is structural only; a fresh Wave A remains required for behavioral
|
|
85
|
+
validation. `docs/evidence/pr35-e1-repair-provenance-v1.json` hashes the E1-informed evidence,
|
|
86
|
+
including contextual D1/D2 diagnosis material; preserved measurements are unchanged.
|
|
87
|
+
|
|
88
|
+
**Changed — release evidence does not claim model measurement.** `3.0.1` contains three
|
|
89
|
+
generated Plan runtime prompt changes, the explicitly authorized assurance-state additions, and
|
|
90
|
+
Decide's approved P4 text; other shipped runtime schemas, scripts, skills, agents, and prompts remain
|
|
91
|
+
byte-identical to `3.0.0`. No 3.0.1 model score is claimed: deterministic/static checks are the
|
|
92
|
+
release evidence, while the required DeepSeek/GLM wave and live workflow cells remain unrun. The
|
|
93
|
+
remote `v3.0.1` tag and npm `latest` were independently verified after publication.
|
|
94
|
+
|
|
9
95
|
## [3.0.0] — 2026-08-20
|
|
10
96
|
|
|
11
97
|
**Added — risk-adaptive assurance profiles on the two existing workflow spines.** `standard`
|
package/README.md
CHANGED
|
@@ -8,6 +8,16 @@ 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
|
+
**Source version:** `3.1.0`. Release coordinates are npm `principal-pi-skills@3.1.0` and the
|
|
12
|
+
immutable git tag `v3.1.0`. Publication status lives outside these immutable package bytes: run
|
|
13
|
+
`npm view principal-pi-skills version dist-tags --json` and check the
|
|
14
|
+
[GitHub release](https://github.com/mojomanyana/principal-pi-skills/releases/tag/v3.1.0) before
|
|
15
|
+
installing. Preparation evidence (2026-09-11): the `v3.1.0` tag was pending and npm `latest` was
|
|
16
|
+
`3.0.1`; this dated fact is not a claim about current registry state. This version adds the opt-in
|
|
17
|
+
`current-v1` assurance evidence projection and validates cross-repository compatibility without
|
|
18
|
+
shipping the source-only host adapters. It carries no new model score; the committed board remains
|
|
19
|
+
a historical v2.4 baseline.
|
|
20
|
+
|
|
11
21
|
The set is built for **one principal engineer steering at a high level while skills and
|
|
12
22
|
subagents do the work.** Two properties follow, and every design choice below serves them:
|
|
13
23
|
**delegable trust** — an output carries the evidence needed to verify it without redoing
|
|
@@ -40,19 +50,21 @@ approval controls without creating another skill suite.
|
|
|
40
50
|
cases, and each wrong absolute produced a measured over-refusal. A rule plus the cases it
|
|
41
51
|
must not eat costs more words than an absolute; that is the trade. **When a fix and the
|
|
42
52
|
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
|
-
|
|
53
|
+
model needed, which is a worse outcome than a longer file. Plan is the local exception at
|
|
54
|
+
≤ ~1700 (agent ≤ ~1900): its Critical contract keeps packet ownership, concrete verification,
|
|
55
|
+
no-context discovery, and vertical-slice governors together after those omissions failed across
|
|
56
|
+
models. **Other agents get their own budget, ≤ ~1500**: a single-shot definition carries its
|
|
57
|
+
output template *and* the BLOCKED form *and* the no-questions mechanics, none of which a loaded
|
|
58
|
+
skill needs. Every count in the table below is checkable with `wc -w`. Nothing loads anything
|
|
47
59
|
else — a subagent reads one file and has the whole contract.
|
|
48
60
|
|
|
49
61
|
## The set
|
|
50
62
|
|
|
51
63
|
| Skill | What it does | How it runs | Words |
|
|
52
64
|
|---|---|---|---|
|
|
53
|
-
| `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline |
|
|
65
|
+
| `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline | 1055 |
|
|
54
66
|
| `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`,
|
|
67
|
+
| `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
68
|
| `build` | Test-first implementation — code proven by a test you watched fail | inline | 1162 |
|
|
57
69
|
| `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1392) or inline | 1364 |
|
|
58
70
|
| `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 +105,13 @@ docs/demos/ the chains running end to end, repo-verifi
|
|
|
93
105
|
1. **Skills + prompts** — install an immutable tag, not a branch:
|
|
94
106
|
|
|
95
107
|
```
|
|
96
|
-
pi install git:github.com/mojomanyana/principal-pi-skills@v3.
|
|
108
|
+
pi install git:github.com/mojomanyana/principal-pi-skills@v3.1.0
|
|
97
109
|
```
|
|
98
110
|
|
|
99
|
-
`3.
|
|
100
|
-
|
|
101
|
-
|
|
111
|
+
This source tree represents `3.1.0`. Before installing, use the live npm and GitHub checks above
|
|
112
|
+
to confirm publication; do not infer registry state from immutable README text. v3 adds the
|
|
113
|
+
risk-adaptive assurance profiles; `standard` is the default and preserves v2 invocation,
|
|
114
|
+
so upgrading from `2.4.0` changes no command you already type.
|
|
102
115
|
Read [Validation](#validation) first: v3 ships with **no model score of its own** — the
|
|
103
116
|
committed board is a historical v2.4 baseline. Do not turn a moving branch into
|
|
104
117
|
production install guidance.
|
|
@@ -247,6 +260,22 @@ the model's own account:
|
|
|
247
260
|
|
|
248
261
|
## Validation
|
|
249
262
|
|
|
263
|
+
The exploratory Terra-high Wave 0 contains a control, an unpinned-executor infrastructure
|
|
264
|
+
failure, and a subprocess-pinned run whose treatment delivery is unproven. None participates
|
|
265
|
+
in efficacy, stability, release, or v3 scoring. No committed pi-daddy observation has the
|
|
266
|
+
required externally produced per-observation attestation, so its current valid-treatment
|
|
267
|
+
count is **zero**. Future treatment requires a closed arm policy, strict canonical result,
|
|
268
|
+
eagerly validated arm-bound trust store, exact observation/attestation bijection, and atomic
|
|
269
|
+
corpus-level replay check. Durable operational replay prevention remains external. The
|
|
270
|
+
DeepSeek/GLM v3 wave and live workflow cells remain unrun.
|
|
271
|
+
|
|
272
|
+
`principal-pi-skills` is only a classifier, evidence-policy consumer, and verifier of
|
|
273
|
+
operator-trusted external attestations. It does not securely execute subjects, protect
|
|
274
|
+
signing keys, authenticate producer ledgers, confine modules or process trees, or provide an
|
|
275
|
+
OS sandbox/same-UID boundary. A valid signature proves that the configured producer made the
|
|
276
|
+
attestation; it does not prove that producer is securely implemented. See
|
|
277
|
+
[`docs/validation/VALIDATION.md`](docs/validation/VALIDATION.md).
|
|
278
|
+
|
|
250
279
|
v3 changes model-visible contract text, adds one `E1` assurance scenario to each skill, and adds
|
|
251
280
|
a Git-Ops stale-receipt negative, taking the static specification from 98 to **106 scenarios**.
|
|
252
281
|
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.
|
|
3
|
+
"version": "3.1.0",
|
|
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. |
|
|
@@ -12,9 +12,14 @@
|
|
|
12
12
|
|
|
13
13
|
import {
|
|
14
14
|
appendFileSync,
|
|
15
|
+
closeSync,
|
|
16
|
+
constants,
|
|
15
17
|
existsSync,
|
|
18
|
+
fstatSync,
|
|
16
19
|
mkdirSync,
|
|
20
|
+
openSync,
|
|
17
21
|
readFileSync,
|
|
22
|
+
readSync,
|
|
18
23
|
renameSync,
|
|
19
24
|
realpathSync,
|
|
20
25
|
rmSync,
|
|
@@ -67,11 +72,14 @@ const SIDE_EFFECTS = new Set([
|
|
|
67
72
|
]);
|
|
68
73
|
const BACKFILL_CONTROLS = ["frozen-diff-review", "requirements-trace", "risk-specific"];
|
|
69
74
|
const ASSURANCE_SOURCES = new Set(["default", "flag", "alias", "natural-language", "policy", "user", "user-downgrade"]);
|
|
75
|
+
const GATES = ["pre-build", "task-complete", "finalize", "finish", "repair", "side-effect"];
|
|
76
|
+
const GATE_CODES = new Set(["OK", "BLOCKED_ASSURANCE", "BLOCKED_CRITICAL_ASSURANCE"]);
|
|
70
77
|
const ISO_TIMESTAMP_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|([+-])(\d{2}):(\d{2}))$/;
|
|
71
78
|
|
|
72
79
|
export const EVENT_CONTRACT = `# principal-pi-assurance event contract v1
|
|
73
80
|
Append: principal-pi-assurance event --run-id ID <<<'{"type":"...",...}'
|
|
74
81
|
Inspect: principal-pi-assurance show --run-id ID
|
|
82
|
+
Report: principal-pi-assurance report --run-id ID [--format human|in-toto]
|
|
75
83
|
Gate: principal-pi-assurance gate --run-id ID --gate pre-build|task-complete|finalize|finish|repair|side-effect [--task-id ID] [--action ACTION]
|
|
76
84
|
The CLI supplies at, seq, run_id and hash-chain fields. Payload shapes:
|
|
77
85
|
risk_classified {type, level:tiny|substantive|consequential, reason; level is monotonic}
|
|
@@ -98,6 +106,7 @@ The CLI supplies at, seq, run_id and hash-chain fields. Payload shapes:
|
|
|
98
106
|
side_effect_approved {type, action:migration|push|publish|deletion|credential-rotation|production-access, approved_by:"user", reason}
|
|
99
107
|
finish_selected {type, choice:merge|pr|keep|discard, explicit_request:true only for discard}
|
|
100
108
|
finalization_completed {type, final_branch, head_sha, tree_sha; only after gate finalize and the Git operation}
|
|
109
|
+
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
110
|
Never edit events.jsonl/snapshot.json. A failed critical gate prints BLOCKED_CRITICAL_ASSURANCE.`;
|
|
102
111
|
|
|
103
112
|
const fail = (message) => {
|
|
@@ -188,12 +197,12 @@ function shellWords(text) {
|
|
|
188
197
|
const POLICY_TRIGGERS = [
|
|
189
198
|
["database/schema migration", /\b(migrat(?:e|ion|ing)|schema change|drop(?:ping)? (?:a )?(?:production\s+)?(?:table|column))\b/i],
|
|
190
199
|
["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],
|
|
200
|
+
["billing or payments", /\b(billing|payments?|invoices?|charges?|refunds?)\b/i],
|
|
201
|
+
["destructive data operation", /\b(truncate|destructive data|delete (?:all\s+)?(?:(?:production|customer)\s+)?data|data purge|wipe (?:all\s+)?(?:customer\s+)?records?)\b/i],
|
|
202
|
+
["public API break", /\b(breaking (?:api|change)|public api break|backwards-incompatible (?:api )?change|remove (?:a )?public endpoint)\b/i],
|
|
194
203
|
["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],
|
|
204
|
+
["protected history", /\b(force[- ]push|rewrite (?:main|master|develop)|rewrite history[^.\n]{0,60}protected (?:[a-z0-9._/-]+ )?branch|protected history)\b/i],
|
|
205
|
+
["production side effect", /\b(production (?:deploy|access|change|operation)|run in prod|roll out[^.\n]{0,60}to production)\b/i],
|
|
197
206
|
];
|
|
198
207
|
|
|
199
208
|
function flagValue(words, name) {
|
|
@@ -212,7 +221,7 @@ function flagValue(words, name) {
|
|
|
212
221
|
return values.at(-1) ?? null;
|
|
213
222
|
}
|
|
214
223
|
|
|
215
|
-
/** Parse command flags and the
|
|
224
|
+
/** Parse command flags and the bounded natural-language critical request patterns. */
|
|
216
225
|
export function parseWorkflowRequest(request) {
|
|
217
226
|
if (!nonEmpty(request)) fail("workflow request must be a non-empty string");
|
|
218
227
|
const words = shellWords(request);
|
|
@@ -224,6 +233,19 @@ export function parseWorkflowRequest(request) {
|
|
|
224
233
|
let requested = "standard";
|
|
225
234
|
let source = "default";
|
|
226
235
|
let reason = "No assurance profile was requested; standard is the default.";
|
|
236
|
+
// Interpret explicit assurance intent per clause so a local negation does not veto a later,
|
|
237
|
+
// affirmative escalation in the same request.
|
|
238
|
+
const naturalCriticalRequest = request.split(/\bthen\b|[,.;\n]/i).some((clause) => {
|
|
239
|
+
const affirmative =
|
|
240
|
+
/\btreat (?:this|the (?:run|task)|this work) as (?:a )?critical(?:[- ]assurance)?\b/i.test(clause) ||
|
|
241
|
+
/\b(?:escalate|elevate|raise) (?:this|the)?\s*(?:run|task)?\s*(?:to|into) critical(?: assurance| mode)?\b/i.test(clause) ||
|
|
242
|
+
/\b(?:use\s+)?critical assurance\b/i.test(clause) ||
|
|
243
|
+
/\bhigh assurance\b/i.test(clause);
|
|
244
|
+
const negated =
|
|
245
|
+
/\b(?:do not|don't|no need to|not)\b[^.\n]{0,40}\b(?:critical assurance|critical[- ]assurance|critical mode)\b/i.test(clause) ||
|
|
246
|
+
/\bcritical assurance\b[^.\n]{0,30}\b(?:is |seems )?(?:unnecessary|not needed)\b/i.test(clause);
|
|
247
|
+
return affirmative && !negated;
|
|
248
|
+
});
|
|
227
249
|
|
|
228
250
|
if (rawProfile) {
|
|
229
251
|
const normalized = rawProfile.toLowerCase();
|
|
@@ -240,12 +262,7 @@ export function parseWorkflowRequest(request) {
|
|
|
240
262
|
requested = "critical";
|
|
241
263
|
source = "flag";
|
|
242
264
|
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
|
-
) {
|
|
265
|
+
} else if (naturalCriticalRequest) {
|
|
249
266
|
requested = "critical";
|
|
250
267
|
source = "natural-language";
|
|
251
268
|
reason = "The user requested critical assurance in natural language.";
|
|
@@ -271,16 +288,19 @@ export function parseWorkflowRequest(request) {
|
|
|
271
288
|
// The policy elevation is deliberately standard -> critical. An explicit lean request is
|
|
272
289
|
// not silently rewritten; one-way operations still retain their existing approval gates.
|
|
273
290
|
if (requested === "standard") {
|
|
291
|
+
// A risk word in the artifact being edited is not itself a risky operation. This narrow
|
|
292
|
+
// exemption covers explicit docs/comment corrections and test-only renames; coordinated or
|
|
293
|
+
// operational work below still wins and elevates.
|
|
274
294
|
const tinyDocumentation =
|
|
275
|
-
/\b(typo|spelling|
|
|
295
|
+
/\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
296
|
!/\b(execute|apply|run (?:the )?migration|rotate|delete data|deploy|push|publish)\b/i.test(request);
|
|
277
297
|
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
298
|
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(
|
|
299
|
+
const riskImplementation =
|
|
300
|
+
/\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) ||
|
|
301
|
+
/\b(?:delete (?:all )?(?:production |customer )?data|remove (?:a )?public endpoint|force[- ]push|rewrite history|roll out)\b/i.test(request);
|
|
282
302
|
const candidate = POLICY_TRIGGERS.find(([, pattern]) => pattern.test(request))?.[0] ?? null;
|
|
283
|
-
riskTrigger = tinyDocumentation && !
|
|
303
|
+
riskTrigger = tinyDocumentation && !coordinatedWork && !riskImplementation ? null : candidate;
|
|
284
304
|
if (riskTrigger) {
|
|
285
305
|
effective = "critical";
|
|
286
306
|
source = "policy";
|
|
@@ -1056,7 +1076,9 @@ export function applyEvent(input, rawEvent) {
|
|
|
1056
1076
|
const event = clone(rawEvent);
|
|
1057
1077
|
if (!nonEmpty(event.type)) fail("event.type is required");
|
|
1058
1078
|
if (!validTimestamp(event.at)) fail("event.at must be an ISO date-time");
|
|
1059
|
-
|
|
1079
|
+
// `gate_evaluated` observes and never mutates the derived state, so the `finish` gate can still
|
|
1080
|
+
// record its own outcome after `finalization_completed` has already finished the run.
|
|
1081
|
+
if (state.status === "finished" && event.type !== "gate_evaluated") fail("finished run state is immutable");
|
|
1060
1082
|
const seq = event.seq ?? state.event_seq + 1;
|
|
1061
1083
|
if (!Number.isInteger(seq) || seq !== state.event_seq + 1) fail(`event sequence must be ${state.event_seq + 1}`);
|
|
1062
1084
|
for (const field of ["task_id", "workspace_id", "context_id", "finding_id"]) {
|
|
@@ -1579,6 +1601,17 @@ export function applyEvent(input, rawEvent) {
|
|
|
1579
1601
|
if (event.approved_by !== "user" || !nonEmpty(event.reason)) fail("side-effect approval requires the user and a consequence-aware reason");
|
|
1580
1602
|
state.approvals.push({ action: event.action, approved_by: "user", reason: event.reason, approved_at: event.at, seq });
|
|
1581
1603
|
break;
|
|
1604
|
+
case "gate_evaluated":
|
|
1605
|
+
// Observation only. The log records that a gate ran and how it answered; the derived state is
|
|
1606
|
+
// deliberately unchanged, which is what lets this event exist without a snapshot schema change
|
|
1607
|
+
// and without disturbing the freshness floors (`last_change_seq`, `last_authority_seq`).
|
|
1608
|
+
if (!GATES.includes(event.gate)) fail(`gate_evaluated gate ${JSON.stringify(event.gate)} is invalid`);
|
|
1609
|
+
if (!GATE_CODES.has(event.code)) fail("gate_evaluated code must be OK, BLOCKED_ASSURANCE, or BLOCKED_CRITICAL_ASSURANCE");
|
|
1610
|
+
if (!Number.isInteger(event.missing_count) || event.missing_count < 0) {
|
|
1611
|
+
fail("gate_evaluated missing_count must be a non-negative integer");
|
|
1612
|
+
}
|
|
1613
|
+
if ((event.code === "OK") !== (event.missing_count === 0)) fail("gate_evaluated code and missing_count disagree");
|
|
1614
|
+
break;
|
|
1582
1615
|
default:
|
|
1583
1616
|
fail(`unknown event type ${JSON.stringify(event.type)}`);
|
|
1584
1617
|
}
|
|
@@ -1614,6 +1647,25 @@ function atomicJson(path, value) {
|
|
|
1614
1647
|
renameSync(temp, path);
|
|
1615
1648
|
}
|
|
1616
1649
|
|
|
1650
|
+
/** Optional bounded descriptor snapshot for read-only host integrations; default CLI loading is unchanged. */
|
|
1651
|
+
export function readBoundedAssuranceText(path, maxBytes) {
|
|
1652
|
+
if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 16 * 1024 * 1024) fail("bounded assurance input limit is invalid");
|
|
1653
|
+
let fd;
|
|
1654
|
+
try {
|
|
1655
|
+
fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
|
|
1656
|
+
const before = fstatSync(fd);
|
|
1657
|
+
if (!before.isFile() || before.size > maxBytes) fail("bounded assurance input exceeds limit or is not a regular file");
|
|
1658
|
+
const bytes = Buffer.alloc(before.size + 1);
|
|
1659
|
+
let length = 0, n;
|
|
1660
|
+
while (length < bytes.length && (n = readSync(fd, bytes, length, bytes.length - length, null)) > 0) length += n;
|
|
1661
|
+
const after = fstatSync(fd);
|
|
1662
|
+
if (length !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) {
|
|
1663
|
+
fail("bounded assurance input changed during read");
|
|
1664
|
+
}
|
|
1665
|
+
return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes.subarray(0, length));
|
|
1666
|
+
} finally { if (fd !== undefined) closeSync(fd); }
|
|
1667
|
+
}
|
|
1668
|
+
|
|
1617
1669
|
/** Append-only store with a derived, replaceable snapshot. */
|
|
1618
1670
|
export class AssuranceStore {
|
|
1619
1671
|
constructor({ baseDir = defaultStateDir(), now = () => new Date().toISOString() } = {}) {
|
|
@@ -1667,15 +1719,19 @@ export class AssuranceStore {
|
|
|
1667
1719
|
});
|
|
1668
1720
|
}
|
|
1669
1721
|
|
|
1670
|
-
load(runId) {
|
|
1722
|
+
load(runId, { withEvents = false, maxBytes = null, maxEvents = null } = {}) {
|
|
1671
1723
|
const paths = this.paths(runId);
|
|
1672
1724
|
if (!existsSync(paths.log)) fail(`unknown run ${runId}`);
|
|
1673
|
-
const lines = readFileSync(paths.log, "utf8")
|
|
1725
|
+
const lines = (maxBytes === null ? readFileSync(paths.log, "utf8") : readBoundedAssuranceText(paths.log, maxBytes))
|
|
1674
1726
|
.split("\n")
|
|
1675
1727
|
.filter(Boolean);
|
|
1728
|
+
if (maxEvents !== null && (!Number.isSafeInteger(maxEvents) || maxEvents < 1 || maxEvents > 10000 || lines.length > maxEvents)) {
|
|
1729
|
+
fail("bounded assurance event limit exceeded or invalid");
|
|
1730
|
+
}
|
|
1676
1731
|
if (lines.length === 0) fail("event-log integrity failure: log is empty");
|
|
1677
1732
|
let state = null;
|
|
1678
1733
|
let previous = null;
|
|
1734
|
+
const events = [];
|
|
1679
1735
|
for (let index = 0; index < lines.length; index++) {
|
|
1680
1736
|
let event;
|
|
1681
1737
|
try {
|
|
@@ -1706,8 +1762,9 @@ export class AssuranceStore {
|
|
|
1706
1762
|
state.event_digest = event.event_digest;
|
|
1707
1763
|
}
|
|
1708
1764
|
previous = event.event_digest;
|
|
1765
|
+
events.push(event);
|
|
1709
1766
|
}
|
|
1710
|
-
return state;
|
|
1767
|
+
return withEvents ? { state, events } : state;
|
|
1711
1768
|
}
|
|
1712
1769
|
|
|
1713
1770
|
append(runId, payload) {
|
|
@@ -1757,6 +1814,251 @@ function stdin() {
|
|
|
1757
1814
|
return readFileSync(0, "utf8");
|
|
1758
1815
|
}
|
|
1759
1816
|
|
|
1817
|
+
const quoted = (value) => JSON.stringify(value);
|
|
1818
|
+
const receiptName = (event) => `${event.kind} (seq ${event.seq}): ${event.command}`;
|
|
1819
|
+
|
|
1820
|
+
/**
|
|
1821
|
+
* Versioned evidence-only projection of a replayed state, NOT a gate evaluation.
|
|
1822
|
+
* Keep the legacy Statement renderer below byte-compatible. In particular, do not
|
|
1823
|
+
* reuse freshEvidence here: it searches for ANY zero, hiding a later failure.
|
|
1824
|
+
*/
|
|
1825
|
+
export function buildCurrentApplicabilityProjection(state) {
|
|
1826
|
+
const valid = validateRunState(state);
|
|
1827
|
+
if (!valid.ok) fail(`cannot project invalid state: ${valid.errors.join("; ")}`);
|
|
1828
|
+
const candidate = assuredIdentity(state);
|
|
1829
|
+
const floor = freshnessFloor(state);
|
|
1830
|
+
const tasks = Object.entries(state.tasks).map(([task_id, task]) => {
|
|
1831
|
+
const packet = task.packet;
|
|
1832
|
+
const reasons = [];
|
|
1833
|
+
if (packet.plan_digest !== state.plan_digest) reasons.push("changed-plan");
|
|
1834
|
+
if (Object.entries(packet.definition_digests).some(([name, value]) => state.definition_digests[name] !== value)) {
|
|
1835
|
+
reasons.push("changed-definitions");
|
|
1836
|
+
}
|
|
1837
|
+
if (!ownValue(state.workspaces, packet.workspace_id) || packet.workspace_id !== state.active_workspace_id) {
|
|
1838
|
+
reasons.push("inactive-workspace");
|
|
1839
|
+
}
|
|
1840
|
+
return {
|
|
1841
|
+
task_id, task_digest: task.task_digest, workspace_id: packet.workspace_id,
|
|
1842
|
+
status: task.status, completed_seq: task.completed_seq,
|
|
1843
|
+
applicability: task.status === "superseded" ? "superseded" : reasons.length ? "stale" : "current",
|
|
1844
|
+
reasons,
|
|
1845
|
+
};
|
|
1846
|
+
});
|
|
1847
|
+
const taskById = new Map(tasks.map((task) => [task.task_id, task]));
|
|
1848
|
+
// Only red/green form a declared TDD pair. A different command, kind, or task
|
|
1849
|
+
// never replaces another check. Exact-target remains independently required.
|
|
1850
|
+
const keyFor = (receipt) => canonicalJson([receipt.task_id, receipt.kind === "red" ? "green" : receipt.kind, receipt.command]);
|
|
1851
|
+
const groups = new Map();
|
|
1852
|
+
const receipts = state.evidence.map((receipt) => {
|
|
1853
|
+
const task = taskById.get(receipt.task_id);
|
|
1854
|
+
const reasons = [];
|
|
1855
|
+
if (receipt.task_id !== null && !task) reasons.push("unknown-task");
|
|
1856
|
+
if (task?.applicability === "stale") reasons.push("stale-task");
|
|
1857
|
+
if (!candidate.head_sha || !candidate.tree_sha) reasons.push("missing-candidate");
|
|
1858
|
+
else if (receipt.head_sha !== candidate.head_sha || receipt.tree_sha !== candidate.tree_sha) reasons.push("changed-artifact");
|
|
1859
|
+
if (receipt.seq <= floor) reasons.push("before-freshness-floor");
|
|
1860
|
+
const workspaceId = task?.workspace_id ?? state.active_workspace_id;
|
|
1861
|
+
if (receipt.workspace_id !== workspaceId || workspaceId !== state.active_workspace_id) reasons.push("inactive-workspace");
|
|
1862
|
+
if (task && receipt.kind === "exact-target" &&
|
|
1863
|
+
(task.status !== "completed" || receipt.seq <= (task.completed_seq ?? 0))) reasons.push("before-task-completion");
|
|
1864
|
+
const projected = { ...receipt, disposition: task?.applicability === "superseded" ? "superseded-task" : reasons.length ? "stale" : "current", reasons };
|
|
1865
|
+
if (projected.disposition !== "superseded-task") {
|
|
1866
|
+
const key = keyFor(receipt);
|
|
1867
|
+
if (!groups.has(key)) groups.set(key, []);
|
|
1868
|
+
groups.get(key).push(projected);
|
|
1869
|
+
}
|
|
1870
|
+
return projected;
|
|
1871
|
+
});
|
|
1872
|
+
const checks = [...groups.values()].map((group) => {
|
|
1873
|
+
const latest = group.findLast((receipt) => receipt.disposition === "current");
|
|
1874
|
+
const execution = group.findLast((receipt) => receipt.disposition === "current" && receipt.kind !== "red");
|
|
1875
|
+
// Expected-red is not qualifying evidence and cannot clear a green failure.
|
|
1876
|
+
const selected = latest?.kind === "red" && execution?.exit_code !== undefined && execution.exit_code !== 0
|
|
1877
|
+
? execution : latest;
|
|
1878
|
+
const last = selected ?? group.at(-1);
|
|
1879
|
+
if (selected) {
|
|
1880
|
+
for (const receipt of group) {
|
|
1881
|
+
// An inapplicable later receipt cannot erase a current failure (or pass).
|
|
1882
|
+
if (receipt.seq < selected.seq) receipt.disposition = "superseded";
|
|
1883
|
+
}
|
|
1884
|
+
for (const receipt of group) {
|
|
1885
|
+
if (receipt.kind === "red" && receipt.disposition === "current") receipt.disposition = "expected-red";
|
|
1886
|
+
}
|
|
1887
|
+
}
|
|
1888
|
+
return {
|
|
1889
|
+
kind: last.kind === "red" ? "green" : last.kind, command: last.command,
|
|
1890
|
+
task_id: last.task_id, workspace_id: taskById.get(last.task_id)?.workspace_id ?? state.active_workspace_id,
|
|
1891
|
+
status: !selected ? "STALE" : selected.kind === "red" ? "MISSING" : selected.exit_code === 0 ? "PASSED" : "FAILED",
|
|
1892
|
+
selected_seq: selected?.seq ?? null, receipt_seqs: group.map((receipt) => receipt.seq),
|
|
1893
|
+
};
|
|
1894
|
+
});
|
|
1895
|
+
const requirements = [];
|
|
1896
|
+
const requireEvidence = (kind, task_id = null, command = null) => {
|
|
1897
|
+
const matching = checks.filter((check) => check.kind === kind && check.task_id === task_id &&
|
|
1898
|
+
(command === null || check.command === command));
|
|
1899
|
+
// Every observed command is independent; a passing command cannot conceal
|
|
1900
|
+
// another failure. A fresh match may replace stale historical candidates.
|
|
1901
|
+
const statuses = matching.map((check) => check.status);
|
|
1902
|
+
const task = taskById.get(task_id);
|
|
1903
|
+
const status = task?.applicability === "stale" ? "STALE"
|
|
1904
|
+
: task && task.status !== "completed" ? "MISSING"
|
|
1905
|
+
: statuses.includes("FAILED") ? "FAILED"
|
|
1906
|
+
: statuses.includes("PASSED") ? "PASSED"
|
|
1907
|
+
: statuses.includes("STALE") ? "STALE" : "MISSING";
|
|
1908
|
+
requirements.push({ kind, task_id, command, status });
|
|
1909
|
+
};
|
|
1910
|
+
requireEvidence("exact-target");
|
|
1911
|
+
if (state.assurance.effective === "critical") {
|
|
1912
|
+
for (const kind of ["full-suite", "requirements-trace", "risk-specific"]) requireEvidence(kind);
|
|
1913
|
+
}
|
|
1914
|
+
for (const task of tasks) {
|
|
1915
|
+
if (task.applicability !== "superseded") requireEvidence("exact-target", task.task_id, state.tasks[task.task_id].packet.done_command);
|
|
1916
|
+
}
|
|
1917
|
+
const statuses = [...checks, ...requirements].map((check) => check.status);
|
|
1918
|
+
const result = ["FAILED", "STALE", "MISSING"].find((status) => statuses.includes(status)) ?? "PASSED";
|
|
1919
|
+
return {
|
|
1920
|
+
format_version: "current-v1",
|
|
1921
|
+
kind: "current-applicability-projection",
|
|
1922
|
+
notice: "Evidence-only ledger projection; not a fresh gate or attestation, native acceptance, or execution authorization.",
|
|
1923
|
+
result,
|
|
1924
|
+
candidate,
|
|
1925
|
+
finalization: clone(state.finalization),
|
|
1926
|
+
authority: {
|
|
1927
|
+
assurance: clone(state.assurance), plan_digest: state.plan_digest,
|
|
1928
|
+
definition_digests: clone(state.definition_digests), active_workspace_id: state.active_workspace_id,
|
|
1929
|
+
last_change_seq: state.last_change_seq, last_authority_seq: state.last_authority_seq, freshness_floor: floor,
|
|
1930
|
+
},
|
|
1931
|
+
tasks, checks, requirements, receipts,
|
|
1932
|
+
ledger: { runId: state.run_id, schemaVersion: state.schema_version, eventCount: state.event_seq, hashChainHead: state.event_digest },
|
|
1933
|
+
};
|
|
1934
|
+
}
|
|
1935
|
+
|
|
1936
|
+
/** Project validated ledger events into an unsigned in-toto test-result Statement (legacy semantics). */
|
|
1937
|
+
export function buildAssuranceStatement(events) {
|
|
1938
|
+
const evidence = events.filter((event) => event.type === "evidence_recorded");
|
|
1939
|
+
const finalization = events.findLast((event) => event.type === "finalization_completed") ?? null;
|
|
1940
|
+
const subject = finalization
|
|
1941
|
+
? [
|
|
1942
|
+
{ name: "head_sha", digest: { gitCommit: finalization.head_sha } },
|
|
1943
|
+
{ name: "tree_sha", digest: { gitTree: finalization.tree_sha } },
|
|
1944
|
+
]
|
|
1945
|
+
: [];
|
|
1946
|
+
return {
|
|
1947
|
+
_type: "https://in-toto.io/Statement/v1",
|
|
1948
|
+
subject,
|
|
1949
|
+
predicateType: "https://in-toto.io/attestation/test-result/v0.1",
|
|
1950
|
+
predicate: {
|
|
1951
|
+
result: evidence.length > 0 && evidence.every((receipt) => receipt.exit_code === 0) ? "PASSED" : "FAILED",
|
|
1952
|
+
configuration: evidence.map((receipt) => ({ name: receipt.command })),
|
|
1953
|
+
passedTests: evidence.filter((receipt) => receipt.exit_code === 0).map(receiptName),
|
|
1954
|
+
warnedTests: [],
|
|
1955
|
+
failedTests: evidence.filter((receipt) => receipt.exit_code !== 0).map(receiptName),
|
|
1956
|
+
ledger: {
|
|
1957
|
+
runId: events[0]?.run_id ?? null,
|
|
1958
|
+
schemaVersion: events[0]?.schema_version ?? null,
|
|
1959
|
+
eventCount: events.length,
|
|
1960
|
+
hashChainHead: events.at(-1)?.event_digest ?? null,
|
|
1961
|
+
},
|
|
1962
|
+
},
|
|
1963
|
+
};
|
|
1964
|
+
}
|
|
1965
|
+
|
|
1966
|
+
/** Render only facts carried by a validated ledger; absent categories stay explicitly absent. */
|
|
1967
|
+
export function renderAssuranceReport(state, events) {
|
|
1968
|
+
const taskEvents = events.filter((event) => event.type === "task_packet_recorded");
|
|
1969
|
+
const changes = events.filter((event) => event.type === "code_changed");
|
|
1970
|
+
const evidence = events.filter((event) => event.type === "evidence_recorded");
|
|
1971
|
+
const reviews = events.filter((event) => event.type === "review_recorded");
|
|
1972
|
+
const gates = events.filter((event) => event.type === "gate_evaluated");
|
|
1973
|
+
const findingEvents = events.filter((event) => event.type === "finding_recorded");
|
|
1974
|
+
const adjudications = new Map(events
|
|
1975
|
+
.filter((event) => event.type === "finding_adjudicated")
|
|
1976
|
+
.map((event) => [event.finding_id, event]));
|
|
1977
|
+
const finish = events.find((event) => event.type === "finish_selected") ?? null;
|
|
1978
|
+
const finalization = events.find((event) => event.type === "finalization_completed") ?? null;
|
|
1979
|
+
const lines = [
|
|
1980
|
+
`# Assurance report: ${state.run_id}`,
|
|
1981
|
+
"",
|
|
1982
|
+
"## Authority",
|
|
1983
|
+
`- Request: ${quoted(state.request)}`,
|
|
1984
|
+
`- Effective assurance: ${state.assurance.effective}`,
|
|
1985
|
+
`- Assurance source: ${state.assurance.source}`,
|
|
1986
|
+
`- Risk level: ${state.risk.level}`,
|
|
1987
|
+
"",
|
|
1988
|
+
"## Tasks and their packets",
|
|
1989
|
+
...(taskEvents.length
|
|
1990
|
+
? taskEvents.map((event) => `- ${event.packet.task_id}: ${JSON.stringify(event.packet)}`)
|
|
1991
|
+
: ["- Absent."]),
|
|
1992
|
+
"",
|
|
1993
|
+
"## Changed paths",
|
|
1994
|
+
...(changes.length
|
|
1995
|
+
? changes.map((event) => `- seq ${event.seq}: ${event.changed_paths.join(", ")}`)
|
|
1996
|
+
: ["- Absent."]),
|
|
1997
|
+
"",
|
|
1998
|
+
"## Evidence receipts",
|
|
1999
|
+
...(evidence.length
|
|
2000
|
+
? evidence.map((event) =>
|
|
2001
|
+
`- 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}`)
|
|
2002
|
+
: ["- Absent."]),
|
|
2003
|
+
"",
|
|
2004
|
+
"## Review verdicts by axis",
|
|
2005
|
+
...(reviews.length
|
|
2006
|
+
? reviews.map((event) => `- seq ${event.seq}: axis=${event.axis}; verdict=${event.verdict}; context_id=${event.context_id}`)
|
|
2007
|
+
: ["- Absent."]),
|
|
2008
|
+
"",
|
|
2009
|
+
"## Gate evaluations",
|
|
2010
|
+
...(gates.length
|
|
2011
|
+
? gates.map((event) =>
|
|
2012
|
+
`- seq ${event.seq}: gate=${event.gate}; code=${event.code}; missing_count=${event.missing_count}` +
|
|
2013
|
+
`${event.task_id ? `; task_id=${event.task_id}` : ""}${event.action ? `; action=${event.action}` : ""}`)
|
|
2014
|
+
: ["- Absent."]),
|
|
2015
|
+
"",
|
|
2016
|
+
"## Findings and their adjudications",
|
|
2017
|
+
...(findingEvents.length
|
|
2018
|
+
? findingEvents.map((event) => {
|
|
2019
|
+
const adjudication = adjudications.get(event.finding_id);
|
|
2020
|
+
return `- ${event.finding_id}: summary=${quoted(event.summary)}; evidence=${event.evidence == null ? "Absent." : quoted(event.evidence)}; ` +
|
|
2021
|
+
`disposition=${adjudication?.disposition ?? "Absent."}; reason=${adjudication ? quoted(adjudication.reason) : "Absent."}`;
|
|
2022
|
+
})
|
|
2023
|
+
: ["- Absent."]),
|
|
2024
|
+
"",
|
|
2025
|
+
"## Finish and finalization",
|
|
2026
|
+
`- Finish choice: ${finish?.choice ?? "Absent."}`,
|
|
2027
|
+
finalization
|
|
2028
|
+
? `- Finalization: branch=${quoted(finalization.final_branch)}; head_sha=${finalization.head_sha}; tree_sha=${finalization.tree_sha}`
|
|
2029
|
+
: "- Finalization: Absent.",
|
|
2030
|
+
];
|
|
2031
|
+
const gaps = [
|
|
2032
|
+
...(state.risk.level === "unknown" ? ["Risk classification is absent."] : []),
|
|
2033
|
+
...(taskEvents.length === 0 ? ["Task packets are absent."] : []),
|
|
2034
|
+
...(changes.length === 0 ? ["Changed paths are absent."] : []),
|
|
2035
|
+
...(evidence.length === 0 ? ["Evidence receipts are absent."] : []),
|
|
2036
|
+
...(reviews.length === 0 ? ["Review verdicts are absent."] : []),
|
|
2037
|
+
...(gates.length === 0 ? ["Gate evaluations are absent."] : []),
|
|
2038
|
+
...(findingEvents.length === 0 ? ["Findings are absent."] : []),
|
|
2039
|
+
...findingEvents.filter((event) => !adjudications.has(event.finding_id))
|
|
2040
|
+
.map((event) => `Adjudication for ${event.finding_id} is absent.`),
|
|
2041
|
+
...(!finish ? ["Finish choice is absent."] : []),
|
|
2042
|
+
...(!finalization ? ["Finalization identity is absent."] : []),
|
|
2043
|
+
];
|
|
2044
|
+
lines.push(
|
|
2045
|
+
"",
|
|
2046
|
+
"## Evidence gaps",
|
|
2047
|
+
...(gaps.length ? gaps.map((gap) => `- ${gap}`) : ["- None among the reportable ledger sections."]),
|
|
2048
|
+
"",
|
|
2049
|
+
"## Assumptions",
|
|
2050
|
+
"- None. Absent ledger facts are not inferred.",
|
|
2051
|
+
"",
|
|
2052
|
+
"## Machine section — unsigned in-toto Statement",
|
|
2053
|
+
"No signature is produced by this projection.",
|
|
2054
|
+
"",
|
|
2055
|
+
"```json",
|
|
2056
|
+
JSON.stringify(buildAssuranceStatement(events), null, 2),
|
|
2057
|
+
"```",
|
|
2058
|
+
);
|
|
2059
|
+
return lines.join("\n");
|
|
2060
|
+
}
|
|
2061
|
+
|
|
1760
2062
|
export function runCli(argv, { cwd = process.cwd(), env = process.env, out = console.log, err = console.error, input = stdin } = {}) {
|
|
1761
2063
|
try {
|
|
1762
2064
|
const [command] = argv;
|
|
@@ -1780,6 +2082,20 @@ export function runCli(argv, { cwd = process.cwd(), env = process.env, out = con
|
|
|
1780
2082
|
out(JSON.stringify(store.load(cliFlag(argv, "--run-id")), null, 2));
|
|
1781
2083
|
return 0;
|
|
1782
2084
|
}
|
|
2085
|
+
if (command === "report") {
|
|
2086
|
+
const runId = cliFlag(argv, "--run-id");
|
|
2087
|
+
const format = cliFlag(argv, "--format", "human");
|
|
2088
|
+
if (!["human", "in-toto", "human-legacy", "in-toto-legacy", "current-v1"].includes(format)) {
|
|
2089
|
+
fail("--format must be human, in-toto, human-legacy, in-toto-legacy, or current-v1");
|
|
2090
|
+
}
|
|
2091
|
+
const { state, events } = store.load(runId, { withEvents: true });
|
|
2092
|
+
out(format === "current-v1"
|
|
2093
|
+
? JSON.stringify(buildCurrentApplicabilityProjection(state), null, 2)
|
|
2094
|
+
: ["in-toto", "in-toto-legacy"].includes(format)
|
|
2095
|
+
? JSON.stringify(buildAssuranceStatement(events), null, 2)
|
|
2096
|
+
: renderAssuranceReport(state, events));
|
|
2097
|
+
return 0;
|
|
2098
|
+
}
|
|
1783
2099
|
if (command === "event") {
|
|
1784
2100
|
const runId = cliFlag(argv, "--run-id");
|
|
1785
2101
|
const raw = cliFlag(argv, "--json", null) ?? stdin();
|
|
@@ -1789,14 +2105,32 @@ export function runCli(argv, { cwd = process.cwd(), env = process.env, out = con
|
|
|
1789
2105
|
}
|
|
1790
2106
|
if (command === "gate") {
|
|
1791
2107
|
const runId = cliFlag(argv, "--run-id");
|
|
1792
|
-
const
|
|
1793
|
-
|
|
1794
|
-
|
|
1795
|
-
});
|
|
2108
|
+
const gate = cliFlag(argv, "--gate");
|
|
2109
|
+
const taskId = cliFlag(argv, "--task-id");
|
|
2110
|
+
const action = cliFlag(argv, "--action");
|
|
2111
|
+
const result = evaluateGate(store.load(runId), gate, { task_id: taskId, action });
|
|
2112
|
+
// A gate outcome nobody can produce as evidence is the hole this event closes, so recording
|
|
2113
|
+
// failure is an error rather than a silent pass. A blocked gate still returns 3: the block is
|
|
2114
|
+
// the more important fact, and swallowing it to report a logging problem would invert them.
|
|
2115
|
+
let recorded = true;
|
|
2116
|
+
try {
|
|
2117
|
+
store.append(runId, {
|
|
2118
|
+
type: "gate_evaluated",
|
|
2119
|
+
gate,
|
|
2120
|
+
code: result.code,
|
|
2121
|
+
missing_count: result.missing.length,
|
|
2122
|
+
...(taskId ? { task_id: taskId } : {}),
|
|
2123
|
+
...(action ? { action } : {}),
|
|
2124
|
+
});
|
|
2125
|
+
} catch (error) {
|
|
2126
|
+
recorded = false;
|
|
2127
|
+
err(`gate outcome could not be recorded: ${error.message}`);
|
|
2128
|
+
}
|
|
1796
2129
|
if (!result.ok) {
|
|
1797
2130
|
err(`${result.code}\nMissing controls:\n${result.missing.map((item) => `- ${item}`).join("\n")}`);
|
|
1798
2131
|
return 3;
|
|
1799
2132
|
}
|
|
2133
|
+
if (!recorded) return 1;
|
|
1800
2134
|
out("OK");
|
|
1801
2135
|
return 0;
|
|
1802
2136
|
}
|
|
@@ -1821,7 +2155,7 @@ export function runCli(argv, { cwd = process.cwd(), env = process.env, out = con
|
|
|
1821
2155
|
return 0;
|
|
1822
2156
|
}
|
|
1823
2157
|
|
|
1824
|
-
err("usage: principal-pi-assurance <contract|init|show|event|gate|validate-task|digest|where> [options]");
|
|
2158
|
+
err("usage: principal-pi-assurance <contract|init|show|report|event|gate|validate-task|digest|where> [options]");
|
|
1825
2159
|
return 2;
|
|
1826
2160
|
} catch (error) {
|
|
1827
2161
|
err(`✗ ${error instanceof Error ? error.message : String(error)}`);
|