principal-pi-skills 3.0.1 → 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 CHANGED
@@ -119,10 +119,12 @@ to every output.
119
119
 
120
120
  ## Setup (pi)
121
121
 
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
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
126
128
  profile, so a v2 invocation keeps working unchanged. It registers the
127
129
  skills and the `/principal-feature` + `/principal-bugfix` commands via the `pi`
128
130
  manifest. Install a tag, not a branch.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,33 @@ 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
+
9
36
  ## [3.0.1] — 2026-09-04
10
37
 
11
38
  **Added — assurance ledgers have a read-only evidence projection.**
@@ -62,9 +89,8 @@ including contextual D1/D2 diagnosis material; preserved measurements are unchan
62
89
  generated Plan runtime prompt changes, the explicitly authorized assurance-state additions, and
63
90
  Decide's approved P4 text; other shipped runtime schemas, scripts, skills, agents, and prompts remain
64
91
  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.
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.
68
94
 
69
95
  ## [3.0.0] — 2026-08-20
70
96
 
package/README.md CHANGED
@@ -8,11 +8,15 @@ 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.
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.
16
20
 
17
21
  The set is built for **one principal engineer steering at a high level while skills and
18
22
  subagents do the work.** Two properties follow, and every design choice below serves them:
@@ -101,12 +105,12 @@ docs/demos/ the chains running end to end, repo-verifi
101
105
  1. **Skills + prompts** — install an immutable tag, not a branch:
102
106
 
103
107
  ```
104
- pi install git:github.com/mojomanyana/principal-pi-skills@v3.0.1
108
+ pi install git:github.com/mojomanyana/principal-pi-skills@v3.1.0
105
109
  ```
106
110
 
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,
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,
110
114
  so upgrading from `2.4.0` changes no command you already type.
111
115
  Read [Validation](#validation) first: v3 ships with **no model score of its own** — the
112
116
  committed board is a historical v2.4 baseline. Do not turn a moving branch into
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "principal-pi-skills",
3
- "version": "3.0.1",
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",
@@ -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,
@@ -1642,6 +1647,25 @@ function atomicJson(path, value) {
1642
1647
  renameSync(temp, path);
1643
1648
  }
1644
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
+
1645
1669
  /** Append-only store with a derived, replaceable snapshot. */
1646
1670
  export class AssuranceStore {
1647
1671
  constructor({ baseDir = defaultStateDir(), now = () => new Date().toISOString() } = {}) {
@@ -1695,12 +1719,15 @@ export class AssuranceStore {
1695
1719
  });
1696
1720
  }
1697
1721
 
1698
- load(runId, { withEvents = false } = {}) {
1722
+ load(runId, { withEvents = false, maxBytes = null, maxEvents = null } = {}) {
1699
1723
  const paths = this.paths(runId);
1700
1724
  if (!existsSync(paths.log)) fail(`unknown run ${runId}`);
1701
- const lines = readFileSync(paths.log, "utf8")
1725
+ const lines = (maxBytes === null ? readFileSync(paths.log, "utf8") : readBoundedAssuranceText(paths.log, maxBytes))
1702
1726
  .split("\n")
1703
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
+ }
1704
1731
  if (lines.length === 0) fail("event-log integrity failure: log is empty");
1705
1732
  let state = null;
1706
1733
  let previous = null;
@@ -1790,7 +1817,123 @@ function stdin() {
1790
1817
  const quoted = (value) => JSON.stringify(value);
1791
1818
  const receiptName = (event) => `${event.kind} (seq ${event.seq}): ${event.command}`;
1792
1819
 
1793
- /** Project validated ledger events into an unsigned in-toto test-result Statement. */
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). */
1794
1937
  export function buildAssuranceStatement(events) {
1795
1938
  const evidence = events.filter((event) => event.type === "evidence_recorded");
1796
1939
  const finalization = events.findLast((event) => event.type === "finalization_completed") ?? null;
@@ -1942,11 +2085,15 @@ export function runCli(argv, { cwd = process.cwd(), env = process.env, out = con
1942
2085
  if (command === "report") {
1943
2086
  const runId = cliFlag(argv, "--run-id");
1944
2087
  const format = cliFlag(argv, "--format", "human");
1945
- if (!["human", "in-toto"].includes(format)) fail("--format must be human or in-toto");
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
+ }
1946
2091
  const { state, events } = store.load(runId, { withEvents: true });
1947
- out(format === "in-toto"
1948
- ? JSON.stringify(buildAssuranceStatement(events), null, 2)
1949
- : renderAssuranceReport(state, events));
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));
1950
2097
  return 0;
1951
2098
  }
1952
2099
  if (command === "event") {