@unbrained/pm-cli 2026.10.10 → 2026.10.11

package/docs/RELEASE_LEDGER_RECONCILIATION.md

@@ -0,0 +1,148 @@
+# Full-history release reconciliation
+
+Owner: [pm-q91qyd](../.agents/pm/issues/pm-q91qyd.toon).
+Upstream trigger evidence: [pm-prrlce](../.agents/pm/issues/pm-prrlce.toon).
+
+The Release Reliability workflow compares every dated section in the
+package-generated changelog, every release tag advertised by `origin`, and
+every version in anonymous public npm metadata. It runs on the existing daily
+schedule and completion triggers, even when a rolling reliability report fails.
+Its separate `release-ledgers-<run>-<attempt>` artifact contains the complete
+input inventories, counts, findings and exception dispositions for offline replay.
+
+Missing public registry versions are declared-but-undelivered releases. Missing
+changelog sections are delivered-but-undocumented releases. A tag missing its
+section is tagged-but-unsectioned; an identity can belong to several classes.
+Every missing ledger appears explicitly in the report, without counting one
+identity several times or dropping overlapping classes.
+The `classes` object names these three populations separately; `findings`
+retains one row per discrepant identity.
+
+The first complete census on 2026-10-10 found 14 discrepant identities among
+143 sections, 151 tags and 143 public versions. The exact historical signatures
+and their individual dispositions are recorded in
+[the reviewed exception policy](../config/release-ledger-exceptions.json).
+Unpublished historical preparations are retained as abandoned publications;
+historical documentation gaps remain visible without inventing shipped content.
+These are explicit exceptions, not claims that the three historical sets agree.
+No tag is deleted and no old artifact is published by this reporting path.
+
+An exception matches one identity and one exact missing-ledger signature.
+Additional missing evidence invalidates it. Correcting a historical gap makes
+its exception stale and requires removing or revising that policy entry in a
+reviewed change. A new discrepancy or stale exception fails the report.
+Empty total inventories, incomplete populations, duplicate identities, malformed
+remote output, registry failures and missing exception evidence refuse evaluation.
+
+The registry request uses the same public npm metadata surface as release
+acceptance, with explicit public registry selection, empty user/global
+configuration and a fresh temporary cache. It runs outside the checkout and
+removes inherited npm authentication/configuration. The report never archives
+credentials, command output or environment values.
+On Windows the collector invokes `cmd.exe` explicitly for npm's `.cmd` launcher.
+The package name must satisfy the restricted registry identity grammar before
+any child starts; the remaining arguments are fixed. Required Windows acceptance
+executes real Git and public npm requests from paths containing spaces and `&`,
+first proves that direct `npm.cmd` execution fails, then verifies the complete
+inventory and temporary-directory cleanup through the repaired launcher.
+No `shell: true` argument-array fallback or resource ceiling increase is used.
+The parser supports npm 11's object and npm 12's single-result array, with
+[captured public npm 12 metadata](../tests/fixtures/release-ledgers/npm-view-12.json)
+as its format regression. Multiple package results refuse evaluation.
+
+To run the actual collector after building:
+
+```bash
+RELEASE_LEDGERS_OUTPUT=/absolute/report.json node --input-type=module -e '
+  import { main } from "./scripts/release/collect-release-ledgers.mjs";
+  const report = main();
+  console.log(JSON.stringify({ok:report.ok,counts:report.counts,findings:report.findings}));
+  process.exitCode = report.ok ? 0 : 1;
+'
+```
+
+Packages and non-release projects can use the same pure SDK primitive with
+their own named artifact inventories and decision references:
+
+```ts
+import { reconcileArtifactLedgers } from "@unbrained/pm-cli/sdk/governance";
+
+const report = reconcileArtifactLedgers([
+  { name: "declared", complete: true, identities: ["artifact-1"] },
+  { name: "delivered", complete: true, identities: ["artifact-1"] },
+]);
+```
+
+`ArtifactLedgerSnapshot`, `ArtifactLedgerException`, `ArtifactLedgerFinding`
+and `ArtifactLedgerReport` describe this harness-independent contract.
+The evaluator performs no filesystem, clock or network operations and preserves
+caller inputs. For offline replay, feed the saved `snapshots` and `exceptions`
+back into `reconcileArtifactLedgers`.
+
+## Tag-carried trigger declarations
+
+New preparations create annotated tags whose bounded JSON message binds the
+declared upstream event/origin, repository, run/attempt, reviewed source commit
+and prepared target commit. Before publication, the Release workflow checks
+the tag's peeled commit and source ancestry and compares the source declaration
+with the exact GitHub run attempt, including repository, event, source SHA,
+the producer workflow path and declared Auto Release run name. It independently
+fetches the repository's default branch and requires the source run's branch to
+match it. Auto Release uploads an immutable producer binding before pushing;
+publication independently downloads that run attempt's artifact and compares
+the exact tag name, target commit, tag object and canonical declaration. Missing,
+expired, ambiguous or mismatched evidence stops publication; the artifact is
+retained for 90 days. The verifier never assumes the default branch is named
+`main`.
+
+The separate `release-publication-origin-<run>-<attempt>` artifact retains the
+tag-object SHA, upstream declaration, independent verification result and the
+current publication/recovery trigger. An operator recovering a dispatcher
+release therefore retains both origins. A rejected atomic push after sealing
+refuses to rebase into a different target; a new preparation must establish a
+new independent binding. Local preparation remains supported without pushing;
+local `--push` refuses before Git inspection or release-asset mutation.
+
+Historical lightweight tags and unrelated legacy annotations stay explicitly
+unattributed only when publication matches the repository, tag name and exact
+content-addressed object in the
+[frozen pre-rollout inventory](../config/release-tag-legacy.json). That reviewed
+inventory identifies all 152 origin tag objects observed before this rollout;
+it is not extended automatically. Unknown lightweight tags, unrelated new
+annotations and rewritten historical objects stop before publication, including
+operator recovery. A missing or unreadable inventory fails closed. No origin is
+inferred from a tag-push event or actor. Local preparation records an operator
+declaration but hosted publication refuses it without a hosted producer.
+Tag objects are content-addressed evidence; this does not assert that GitHub
+release/tag immutability policy has been enabled.
+
+The downstream tag-push workflow's run name still names `tag_push`; its verified
+upstream origin lives in the summary and artifact. The remaining run-name and
+operator-only manual follow-up contracts retain their existing owners
+[pm-prrlce](../.agents/pm/issues/pm-prrlce.toon) and
+[pm-uenmu9](../.agents/pm/issues/pm-uenmu9.toon). The one-automatic-release-per-UTC-day
+guard and exact-tag recovery semantics are unchanged.
+
+## Installed acceptance path cost
+
+Owner: [pm-release-acceptance-path-cost](../.agents/pm/issues/pm-release-acceptance-path-cost.toon).
+
+The disposable installed-consumer layout uses concise directory names because
+`init` repeats its workspace path throughout its complete JSON guidance. Long
+macOS temporary ancestry previously made an otherwise valid public artifact
+exceed the raw 12,000-character init ceiling. Shorter private paths retain every
+output field, lifecycle assertion, deadline and ceiling. The
+[captured public output regression](../tests/fixtures/release-acceptance/README.md)
+checks the raw cost for independent control/candidate local npm, global npm and
+Bun layouts; actual installed sessions remain separate acceptance evidence.
+
+## Publication metadata weight
+
+Owner: [pm-998juj](../.agents/pm/tasks/pm-998juj.toon).
+
+The publication stage compacts first-party JSON while leaving checkout files
+readable and third-party runtime files unchanged. Every parsed value must survive
+serialization exactly; invalid JSON and lossy representations, including negative
+zero or overflowing numbers, stop packing. Real tarball regressions verify nested
+extension data, Unicode, escaped text and the runtime ledger. Both committed size
+profiles, required files and source-map exclusions remain enforced.

package/docs/RELEASE_RELIABILITY.md

@@ -34,6 +34,10 @@ by release preparation, not the inferred cron occurrence. A delayed run cannot
 backdate a tag. Reporting never creates, retargets, retries, or publishes a tag.
 The unchanged [release recovery rules](RELEASING.md#failure-handling) apply.
 
+The independent [full-history ledger report](RELEASE_LEDGER_RECONCILIATION.md)
+also reconciles public registry versions, release tags and generated sections.
+It preserves every historical exception and fails on new or changed drift.
+
 ## Evidence and denominator
 
 The collector paginates Auto Release runs over an explicit half-open UTC window

package/docs/RELEASING.md

@@ -172,6 +172,17 @@ Pipeline entrypoint:
 node scripts/release/run-release-pipeline.mjs
 ```
 
+Tracked by [pm-prrlce](../.agents/pm/issues/pm-prrlce.toon): hosted preparation
+uses `--push --defer-push` to write an exact producer binding. Auto Release uploads
+`release-producer-binding-<attempt>` before verifying and atomically pushing its
+prepared refs. Publication independently fetches the verified run's artifact and
+compares the tag name, target commit, tag object and declaration. Missing, expired,
+ambiguous or mismatched evidence fails closed; artifact retention is 90 days.
+A branch advance after sealing refuses publication rather than rebasing into a
+different target. Local `--push` refuses before Git inspection or asset mutation;
+local preparation without pushing remains supported. Historical admission remains
+limited to the reviewed exact-object inventory.
+
 The pipeline performs:
 
 1. change detection + one-release-per-day guard
@@ -421,14 +432,28 @@ maintainer supplies
 pair that acknowledgement with migration guidance, compatible extension
 version bounds where applicable, and the next eligible date-based release.
 
-5. Push branch and tag after local green.
+5. Land the implementation through a reviewed pull request, then use hosted
+   preparation for publication.
+
+Local preparation without `--push` is a diagnostic preview. Its local producer
+declaration cannot authorize publication. Once the reviewed implementation is on
+`main`, dispatch the existing Auto Release workflow from that default branch:
 
 ```bash
-git push origin main
-git tag v<version>
-git push origin v<version>
+gh workflow run auto-release.yml --ref main \
+  -f push=true -f dry_run=false -f telemetry_mode=off -f trigger_origin=operator
 ```
 
+Hosted preparation runs the mandatory gates, creates the version commit and
+annotated tag, and seals their exact producer binding in an immutable artifact
+before verifying and atomically pushing either ref. It waits for the single
+tag-driven Release workflow to publish and accept that exact package. Do not push
+locally prepared tags or invoke `npm publish` separately.
+
+If today's immutable tag already exists, use the exact-tag recovery procedure
+below. A local diagnostic tag does not prove hosted preparation or publication;
+never move a published tag or mint a second automatic version for the same UTC day.
+
 ## GitHub Workflow
 
 `.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
@@ -454,7 +479,11 @@ git push origin v<version>
 - a base npm pack dry run, optional Sentry debug-ID injection, a second
   `sentry-injected` packlist budget over the exact publishable bytes, and only
   then optional Sentry release metadata/upload/finalization and the npx tarball
-  smoke test
+  smoke test. Sentry release metadata and sourcemaps are uploaded only from
+  tag sources. Recovery of an already-published version from reviewed `main`
+  preserves that version's existing Sentry commits and sourcemaps; local debug-ID
+  injection still validates the candidate artifact budget without changing the
+  published release's symbolication data.
 - generated release notes from changelog plus sanitized tracker metadata. The
   tracker read projects only release-relevant fields and explicitly removes row
   and token limits. The generator validates the completeness receipt before

package/docs/agent-task-token-baseline.json

@@ -1,292 +1 @@
-{
-  "version": 5,
-  "transcript_version": 2,
-  "transcript_digest": "sha256:6d4041acfaa4075dde1972d6127a74f18916f7661738b4f5d5fd47a61c179a78",
-  "estimator": "ceil(utf8_bytes / 4)",
-  "comparison_scope": "plan_recovery_tracker_root_canonicalized",
-  "measurement_scope": "output_before_token_accounting",
-  "published_with_release": true,
-  "orientation": {
-    "canonical_task_id": "orientation-context-intent",
-    "required_capabilities": [
-      "actionable_work",
-      "active_ownership",
-      "workspace_state"
-    ],
-    "measured_winner_tokens": 1087,
-    "protocols": [
-      {
-        "task_id": "orientation-context-intent",
-        "command_count": 1,
-        "estimated_tokens": 1087,
-        "capabilities": [
-          "actionable_work",
-          "active_ownership",
-          "workspace_state"
-        ],
-        "capability_evidence": {
-          "actionable_work": [
-            {
-              "step_id": "context",
-              "field_path": "hierarchy"
-            }
-          ],
-          "active_ownership": [
-            {
-              "step_id": "context",
-              "field_path": "activity"
-            }
-          ],
-          "workspace_state": [
-            {
-              "step_id": "context",
-              "field_path": "summary.active_items"
-            }
-          ]
-        }
-      },
-      {
-        "task_id": "orientation-operating-rules",
-        "command_count": 4,
-        "estimated_tokens": 2325,
-        "capabilities": [
-          "actionable_work",
-          "active_ownership",
-          "workspace_state"
-        ],
-        "capability_evidence": {
-          "actionable_work": [
-            {
-              "step_id": "open",
-              "field_path": "items"
-            }
-          ],
-          "active_ownership": [
-            {
-              "step_id": "in-progress",
-              "field_path": "items"
-            }
-          ],
-          "workspace_state": [
-            {
-              "step_id": "context",
-              "field_path": "summary.active_items"
-            }
-          ]
-        }
-      },
-      {
-        "task_id": "orientation-contracts-next",
-        "command_count": 2,
-        "estimated_tokens": 5203,
-        "capabilities": [
-          "actionable_work",
-          "active_ownership",
-          "workspace_state"
-        ],
-        "capability_evidence": {
-          "actionable_work": [
-            {
-              "step_id": "next",
-              "field_path": "recommended.id"
-            }
-          ],
-          "active_ownership": [
-            {
-              "step_id": "next",
-              "field_path": "held_by_others"
-            }
-          ],
-          "workspace_state": [
-            {
-              "step_id": "next",
-              "field_path": "summary.in_progress"
-            }
-          ]
-        }
-      }
-    ]
-  },
-  "tasks": [
-    {
-      "id": "orientation-context-intent",
-      "max_estimated_tokens": 1087,
-      "steps": [
-        {
-          "id": "context",
-          "max_estimated_tokens": 1087,
-          "accounting_mode": "self_reported"
-        }
-      ]
-    },
-    {
-      "id": "orientation-contracts-next",
-      "max_estimated_tokens": 5203,
-      "steps": [
-        {
-          "id": "contracts",
-          "max_estimated_tokens": 4481,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "next",
-          "max_estimated_tokens": 722,
-          "accounting_mode": "self_reported"
-        }
-      ]
-    },
-    {
-      "id": "orientation-operating-rules",
-      "max_estimated_tokens": 2325,
-      "steps": [
-        {
-          "id": "context",
-          "max_estimated_tokens": 1087,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "search",
-          "max_estimated_tokens": 164,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "open",
-          "max_estimated_tokens": 878,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "in-progress",
-          "max_estimated_tokens": 196,
-          "accounting_mode": "self_reported"
-        }
-      ]
-    },
-    {
-      "id": "context-bootstrap",
-      "max_estimated_tokens": 2010,
-      "steps": [
-        {
-          "id": "triage",
-          "max_estimated_tokens": 552,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "orient",
-          "max_estimated_tokens": 1087,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "inspect",
-          "max_estimated_tokens": 371,
-          "accounting_mode": "self_reported"
-        }
-      ]
-    },
-    {
-      "id": "closed-domain-recovery",
-      "max_estimated_tokens": 630,
-      "steps": [
-        {
-          "id": "refuse-intent",
-          "max_estimated_tokens": 259,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "retry-intent",
-          "max_estimated_tokens": 371,
-          "accounting_mode": "self_reported"
-        }
-      ]
-    },
-    {
-      "id": "unknown-option-recovery",
-      "max_estimated_tokens": 596,
-      "steps": [
-        {
-          "id": "refuse-option",
-          "max_estimated_tokens": 433,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "retry-option",
-          "max_estimated_tokens": 163,
-          "accounting_mode": "self_reported"
-        }
-      ]
-    },
-    {
-      "id": "lifecycle-mutation",
-      "max_estimated_tokens": 812,
-      "steps": [
-        {
-          "id": "create",
-          "max_estimated_tokens": 20,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "inspect-open",
-          "max_estimated_tokens": 363,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "close",
-          "max_estimated_tokens": 31,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "inspect-closed",
-          "max_estimated_tokens": 398,
-          "accounting_mode": "self_reported"
-        }
-      ]
-    },
-    {
-      "id": "bulk-effect-outcomes",
-      "max_estimated_tokens": 326,
-      "steps": [
-        {
-          "id": "create-bulk-target",
-          "max_estimated_tokens": 20,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "partial-effect",
-          "max_estimated_tokens": 174,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "no-effect",
-          "max_estimated_tokens": 132,
-          "accounting_mode": "self_reported"
-        }
-      ]
-    },
-    {
-      "id": "plan-execution-mutations",
-      "max_estimated_tokens": 806,
-      "steps": [
-        {
-          "id": "create-plan",
-          "max_estimated_tokens": 21,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "add-step",
-          "max_estimated_tokens": 254,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "complete-step",
-          "max_estimated_tokens": 253,
-          "accounting_mode": "self_reported"
-        },
-        {
-          "id": "inspect-plan",
-          "max_estimated_tokens": 278,
-          "accounting_mode": "self_reported"
-        }
-      ]
-    }
-  ],
-  "composite_max_estimated_tokens": 13795
-}
+{"version":5,"transcript_version":2,"transcript_digest":"sha256:6d4041acfaa4075dde1972d6127a74f18916f7661738b4f5d5fd47a61c179a78","estimator":"ceil(utf8_bytes / 4)","comparison_scope":"plan_recovery_tracker_root_canonicalized","measurement_scope":"output_before_token_accounting","published_with_release":true,"orientation":{"canonical_task_id":"orientation-context-intent","required_capabilities":["actionable_work","active_ownership","workspace_state"],"measured_winner_tokens":1087,"protocols":[{"task_id":"orientation-context-intent","command_count":1,"estimated_tokens":1087,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"context","field_path":"hierarchy"}],"active_ownership":[{"step_id":"context","field_path":"activity"}],"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}]}},{"task_id":"orientation-operating-rules","command_count":4,"estimated_tokens":2325,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"open","field_path":"items"}],"active_ownership":[{"step_id":"in-progress","field_path":"items"}],"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}]}},{"task_id":"orientation-contracts-next","command_count":2,"estimated_tokens":5203,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"next","field_path":"recommended.id"}],"active_ownership":[{"step_id":"next","field_path":"held_by_others"}],"workspace_state":[{"step_id":"next","field_path":"summary.in_progress"}]}}]},"tasks":[{"id":"orientation-context-intent","max_estimated_tokens":1087,"steps":[{"id":"context","max_estimated_tokens":1087,"accounting_mode":"self_reported"}]},{"id":"orientation-contracts-next","max_estimated_tokens":5203,"steps":[{"id":"contracts","max_estimated_tokens":4481,"accounting_mode":"self_reported"},{"id":"next","max_estimated_tokens":722,"accounting_mode":"self_reported"}]},{"id":"orientation-operating-rules","max_estimated_tokens":2325,"steps":[{"id":"context","max_estimated_tokens":1087,"accounting_mode":"self_reported"},{"id":"search","max_estimated_tokens":164,"accounting_mode":"self_reported"},{"id":"open","max_estimated_tokens":878,"accounting_mode":"self_reported"},{"id":"in-progress","max_estimated_tokens":196,"accounting_mode":"self_reported"}]},{"id":"context-bootstrap","max_estimated_tokens":2010,"steps":[{"id":"triage","max_estimated_tokens":552,"accounting_mode":"self_reported"},{"id":"orient","max_estimated_tokens":1087,"accounting_mode":"self_reported"},{"id":"inspect","max_estimated_tokens":371,"accounting_mode":"self_reported"}]},{"id":"closed-domain-recovery","max_estimated_tokens":630,"steps":[{"id":"refuse-intent","max_estimated_tokens":259,"accounting_mode":"self_reported"},{"id":"retry-intent","max_estimated_tokens":371,"accounting_mode":"self_reported"}]},{"id":"unknown-option-recovery","max_estimated_tokens":596,"steps":[{"id":"refuse-option","max_estimated_tokens":433,"accounting_mode":"self_reported"},{"id":"retry-option","max_estimated_tokens":163,"accounting_mode":"self_reported"}]},{"id":"lifecycle-mutation","max_estimated_tokens":812,"steps":[{"id":"create","max_estimated_tokens":20,"accounting_mode":"self_reported"},{"id":"inspect-open","max_estimated_tokens":363,"accounting_mode":"self_reported"},{"id":"close","max_estimated_tokens":31,"accounting_mode":"self_reported"},{"id":"inspect-closed","max_estimated_tokens":398,"accounting_mode":"self_reported"}]},{"id":"bulk-effect-outcomes","max_estimated_tokens":326,"steps":[{"id":"create-bulk-target","max_estimated_tokens":20,"accounting_mode":"self_reported"},{"id":"partial-effect","max_estimated_tokens":174,"accounting_mode":"self_reported"},{"id":"no-effect","max_estimated_tokens":132,"accounting_mode":"self_reported"}]},{"id":"plan-execution-mutations","max_estimated_tokens":806,"steps":[{"id":"create-plan","max_estimated_tokens":21,"accounting_mode":"self_reported"},{"id":"add-step","max_estimated_tokens":254,"accounting_mode":"self_reported"},{"id":"complete-step","max_estimated_tokens":253,"accounting_mode":"self_reported"},{"id":"inspect-plan","max_estimated_tokens":278,"accounting_mode":"self_reported"}]}],"composite_max_estimated_tokens":13795}