@research-engineering/agentic-proofkit 0.1.136

package/NON_CLAIMS.md

@@ -0,0 +1,45 @@
+# Non-Claims
+
+Proofkit owns reusable proof infrastructure primitives only after the relevant
+source, contracts, tests, and release evidence are imported and reviewed.
+
+This repository state does not claim:
+
+- runtime implementation readiness;
+- package publication readiness;
+- public-source provenance for any existing package version;
+- source-code completeness;
+- production readiness;
+- vulnerability absence;
+- license approval for future dependencies;
+- consumer repository security coverage;
+- consuming repository requirement meaning;
+- consuming repository proof-binding adequacy;
+- consuming repository command policy;
+- native witness execution;
+- command pass evidence;
+- receipt authenticity;
+- proof freshness;
+- merge approval;
+- rollout approval;
+- deployment approval;
+- package-registry access-control proof;
+- provider-side CodeQL, OSV, Scorecard, secret-scanning, or dependency-scanning
+  ingestion;
+- GitHub branch-protection proof;
+- Trusted Publisher or OIDC publication proof;
+- generated HTML, Markdown, reports, lookup graphs, or agent envelopes as
+  canonical repository source.
+
+Consuming repositories must keep their own specifications, proof bindings,
+native witnesses, CI gates, rollback policy, and rollout decisions.
+
+Reference infrastructure boundary:
+
+```text
+Proofkit may own reusable grammar, algorithms, reports, rendering/view-model
+machinery, selective planning, impact routing, receipt validation, and agent
+guidance when those capabilities are generic.
+Consuming repositories provide the requirement sentences, policies, witnesses,
+receipts, and rollout decisions.
+```

package/README.md

@@ -0,0 +1,50 @@
+# agentic-proofkit
+
+Reusable CLI and JSON proof infrastructure for spec-to-proof workflows in
+software repositories.
+
+`agentic-proofkit` helps repositories validate structured requirements, bind
+requirements to proof routes, plan selective checks, admit receipt-shaped
+evidence, render human views, and give coding agents bounded next-action
+packets without copying verifier logic between projects.
+
+## Current Repository State
+
+| Surface | State |
+|---|---|
+| Source visibility | Public |
+| Current layer | Public source with admitted unscoped npm release evidence; scoped npm identity is staged for the next release |
+| Runtime implementation | Go CLI with npm and Python wrapper packaging |
+| Package release | `agentic-proofkit@0.1.135` is admitted; `@research-engineering/agentic-proofkit@0.1.136` is pending release evidence |
+| Public-source provenance | Admitted for `v0.1.135`; scoped package provenance is pending a reviewed scoped release |
+| License | MIT |
+
+## Project Boundary
+
+`agentic-proofkit` is intended to provide reusable proof-workflow mechanics for
+repositories that want explicit requirements, proof bindings, deterministic
+reports, and bounded guidance for coding agents.
+
+Proofkit does not own a consuming repository's product requirements, native
+witness execution, receipt authenticity, proof freshness, merge admission,
+rollout, deployment, or production readiness.
+
+## Start Here
+
+| Need | Owner |
+|---|---|
+| Human orientation | This README |
+| Coding-agent startup | `AGENTS.md` |
+| Adoption and release-channel model | `ADOPTION.md` |
+| Completion criteria and remaining work | `BACKLOG.md` |
+| Contribution rules | `CONTRIBUTING.md` |
+| Vulnerability reporting boundary | `SECURITY.md` |
+| Explicit boundary denials | `NON_CLAIMS.md` |
+| `LICENSE` | MIT license |
+
+## Non-Claims
+
+This README is a human landing page. It is not a CLI contract, release proof,
+package publication claim, security audit, or consumer readiness claim. CLI and
+package behavior are owned by their source, tests, machine-readable contracts,
+and release evidence, not by this overview.

package/SECURITY.md

@@ -0,0 +1,52 @@
+# Security Policy
+
+## Supported Versions
+
+No public source-based release is claimed by this repository state yet.
+Supported versions will be named after a reviewed public release exists.
+
+## Reporting A Vulnerability
+
+Private vulnerability intake is not claimed by this repository layer. Before a
+public release, maintainers must enable GitHub private vulnerability reporting
+or publish another private reporting channel.
+
+Until a private channel is available, do not open a public issue with exploit
+details.
+
+Do not include live credentials, private keys, access tokens, or third-party
+secrets in reports. Use redacted examples and describe how to reproduce the
+issue with synthetic data.
+
+## Security Boundary
+
+Proofkit is intended to validate and render caller-owned inputs after those
+runtime surfaces are imported. It does not execute native witnesses,
+authenticate receipt producers, read implicit repository state, publish
+artifacts, approve merge, approve rollout, or decide proof freshness.
+
+Security-sensitive findings usually belong to one of these classes:
+
+- command or argument injection in a Proofkit CLI path;
+- unsafe file path, JSON, or JSON Pointer admission;
+- secret leakage in reports, rendered views, logs, package metadata, or
+  diagnostics;
+- incorrect trust-boundary wording that could make consumers treat advisory
+  evidence as merge-satisfying proof;
+- package artifact or release workflow behavior that changes installed bytes or
+  provenance claims.
+
+## Disclosure And Fix Process
+
+1. Maintainers acknowledge the report and identify the affected surface.
+2. The fix is developed with a targeted regression proof.
+3. A patched version is released only through the documented release process
+   after that process exists in this repository.
+4. The advisory or release notes state impact, affected versions, fixed
+   version, and any required consumer action.
+
+## Non-Claims
+
+This policy does not guarantee a response SLA, third-party dependency support,
+consumer repository security coverage, or production readiness of any consuming
+system.

package/dist/agentic-proofkit

@@ -0,0 +1,36 @@
+#!/usr/bin/env sh
+set -eu
+
+script="$0"
+while [ -L "$script" ]; do
+  link=$(readlink "$script")
+  case "$link" in
+    /*) script="$link" ;;
+    *) script=$(CDPATH= cd -- "$(dirname -- "$script")" && pwd)/"$link" ;;
+  esac
+done
+
+dir=$(CDPATH= cd -- "$(dirname -- "$script")" && pwd)
+package_dir=$(CDPATH= cd -- "$dir/.." && pwd)
+
+case "$(uname -s)/$(uname -m)" in
+  Darwin/aarch64) platform="darwin-arm64" ;;
+  Darwin/amd64) platform="darwin-x64" ;;
+  Darwin/arm64) platform="darwin-arm64" ;;
+  Darwin/x86_64) platform="darwin-x64" ;;
+  Linux/aarch64) platform="linux-arm64" ;;
+  Linux/amd64) platform="linux-x64" ;;
+  Linux/arm64) platform="linux-arm64" ;;
+  Linux/x86_64) platform="linux-x64" ;;
+  *) echo "agentic-proofkit: unsupported platform: $(uname -s)/$(uname -m)" >&2; exit 1 ;;
+esac
+
+binary="$package_dir/dist/platform/$platform/agentic-proofkit"
+
+if [ ! -x "$binary" ]; then
+  echo "agentic-proofkit: missing embedded platform binary for $platform" >&2
+  echo "agentic-proofkit: reinstall agentic-proofkit from the published package artifact" >&2
+  exit 1
+fi
+
+exec "$binary" "$@"

package/docs/proofkit-contract-map.md

@@ -0,0 +1,148 @@
+# Proofkit Contract Map
+
+Status: maintained consumer routing surface.
+
+Owner: `proofkit`.
+
+## Purpose
+
+This map helps consuming repositories choose the smallest Proofkit CLI command
+or JSON contract without loading the full README or source tree. It is not an
+exhaustive schema reference. The canonical command inventory is
+`proofkit/cli-contract.v1.json`.
+
+Formal rule:
+
+```text
+Contract map routes humans and agents.
+CLI/JSON records own cross-language behavior.
+Go packages implement the shipped executable.
+Consumer repositories own product truth, local policy, and native witnesses.
+```
+
+Scope-class rule:
+
+```text
+Most commands consume explicit caller-owned JSON/input refs.
+Explicit filesystem scanners must be named in the CLI contract.
+Scanner commands require caller-selected roots or scopes.
+No command may infer ambient repository truth from the current directory.
+```
+
+## Families
+
+| Family | Main commands | Caller provides | Proofkit owns | Consumer owns | Output authority |
+|---|---|---|---|---|---|
+| Adoption and scaffolding | `adoption-contract-envelope`, `adoption-workflow-plan`, `adoption-doctor`, `gradual-adoption`, `gradual-adoption-bootstrap`, `gradual-adoption-guidance`, `scaffold-profile-plan`, `scaffold-project-structure`, `stack-preset` | adoption intent, aggregate adoption contract envelope, target paths, owner routes, caller-extracted stale authority vocabulary facts, stack preset id | aggregate contract-envelope admission, deterministic starter plans, bounded guidance envelopes, dry-run manifests, adoption gap and stale-authority classification | final files, final requirements, rollout policy, text extraction from files | selected child output, plan, report, or agent envelope |
+| Requirement source | `requirement-authoring-plan`, `requirement-source-admission`, `requirement-source-transition`, `spec-overview-claims`, `requirement-spec-tree`, `requirement-spec-tree-view`, `requirement-source-view`, `requirement-browser-server` | `requirements.v1.json`, caller-owned authoring facts, overview claim extraction, explicit spec hierarchy, view options | candidate-only authoring packets, source-shape admission, lifecycle checks, explicit tree topology/source-ref admission, shared safe renderer fragments, presentation-only views | requirement meaning, extraction completeness, Markdown extraction completeness, hierarchy ownership, proof adequacy, file materialization | authoring packet, source report, spec-tree report, rendered view, or browser presentation |
+| Requirement proof binding | `requirement-bindings`, `proof-slice`, `evidence-graph`, `requirement-proof-resolver`, `requirement-proof-source-set`, `requirement-proof-view`, `spec-proof-bundle-admission` | requirement records, bindings, witness commands, source-set facts, receipt reports | graph validation, compact slices, typed compact proof contract projections, resolver projections, bundle linkage checks | test semantics, witness execution, proof freshness, merge policy | proof report, slice, lookup graph, or view |
+| Test inventory and coverage | `test-evidence-inventory`, `test-evidence-inventory --normalized-inventory`, `requirement-coverage-input-compose`, `requirement-coverage-view`, `requirement-browser-server --view coverage` | caller-owned direct or source-set test inventory, declared quality findings, requirement source, proof binding or compact proof contract, coverage universe, optional owner-invariant registry | strict inventory/source-set admission, fail-closed normalized inventory projection, deterministic coverage-view input composition from explicit facts, weak-oracle and declared-quality classification, requirement/test/command/owner-invariant joins, nonsemantic command-evidence classification, stable coverage failure/warning classifications, presentation-only coverage view | inventory completeness, weak-test truth, native test execution, receipt freshness, producer trust, merge policy | inventory report, normalized inventory data product, coverage-view input, coverage view, or browser presentation |
+| Selective planning | `changed-path-set`, `requirement-impact-input-compose`, `impact`, `selective-gate-plan`, `selective-gate-evidence`, `selective-gate-obligation-decision-input`, `obligation-decision` | changed paths, base/current requirement sources, base/current single-binding-per-requirement proof contracts, generated-artifact policy, local environment policy, proof-like path policy, planned receipts, obligation routes | fail-closed impact input composition, fail-closed planning, receipt comparison, bounded agent packets | git diff truth, repository scanning, command execution, producer trust, final admission | composed impact input, plan, evidence report, or obligation input |
+| Receipts and producers | `proof-receipt-admission`, `receipt-producer-admission`, `receipt-currentness-scope`, `receipt-trust-class`, `producer-policy-self-proof` | receipt sets, producer policy, scope/currentness facts, trust classes | receipt shape, producer/receipt compatibility, self-proof diagnostics | producer authentication, freshness policy, CI trust roots | receipt/provenance report |
+| Release and deployment | `release-authority`, `external-consumer`, `registry-consumer-proof-input-compose`, `registry-consumer`, `deployment-evidence-admission`, `completion-criteria`, `branch-authority`, `readiness-closeout` | package facts, tarball/registry facts, explicit primitive registry/install/smoke facts, deployment evidence, criteria, branch facts | artifact/channel boundary checks, registry-consumer input composition, release diagnostics, falsifiable criteria shape | package publication, registry fetch, package-manager execution, deployment, rollback, approval | composed input, release/deployment/readiness report |
+| Supply-chain and quality | release workflow, `npm run release:sbom`, `npm run self:coverage`, `npm run go:actionlint`, `npm run go:bench` | release artifacts, source workflows, specs, bindings, witness plans, explicit benchmark invocation | deterministic SBOM candidate evidence, coverage metrics, workflow lint routing, benchmark entrypoints | public-source provenance, vulnerability triage, license approval, CI run admission, release approval | SBOM, metrics report, CI signal, or benchmark output |
+| Repository structure | `repo-profile-admission`, `workspace-manifest-facts`, `workspace-registry`, `workspace-changed-package-plan`, `workspace-shard-partition`, `typescript-public-api-surfaces`, `text-policy`, `package-runtime-dependency-admission` | explicit repo/profile facts, caller-owned manifest records, caller-owned roots, and caller-owned text file inventories | structural admission, manifest-to-workspace fact projection, workspace graph projections, TypeScript package public API checks, text policy admission, shard plans | repository freshness, git/file discovery, command policy, package manager truth | structural, fact, policy, or planning report |
+| Custom and generated artifacts | `custom-rule-boundary`, `document-lifecycle-boundary`, `rendered-artifact-freshness`, `conformance-profile`, `json-report-cli-adapter-source`, `witness-plan`, `witness-scheduler-plan` | custom rule metadata, document lifecycle records, artifact digests, profile manifests, command metadata, adapter language | boundary checks, generated-view freshness shape, deterministic adapter source generation, scheduler metadata checks | rule execution, document meaning, cache contents, CI scheduling, committed generated-source freshness | boundary report, generated source artifact, or scheduler report |
+
+## Migrating Repository Route
+
+For imperfect repositories, use Proofkit as a transition toolkit rather than a
+semantic judge.
+
+```text
+inventory facts from caller
+  -> adoption workflow or bootstrap guidance
+  -> owner-selected boundary
+  -> requirement source admission
+  -> proof-binding validation
+  -> native witnesses plus contract tests
+  -> selective plan and admitted receipts
+```
+
+Route ambiguous modernization work through the smallest matching family:
+
+| Question | First route | Why |
+|---|---|---|
+| Where should adoption start? | `adoption-workflow-plan` or `scaffold-project-structure`; use `adoption-contract-envelope` when one caller-owned aggregate adoption file already exists. | They route scenario steps and first-module starter records without scanning the repository; the aggregate route removes consumer-local root-key projection scripts without owning rollout policy. |
+| Is a candidate module ready for gradual enforcement? | `gradual-adoption-guidance` | It reports missing source, binding, witness, blocked-precondition, and advisory candidate-boundary facts by adoption mode. |
+| What still blocks an imperfect repository from enforcement? | `adoption-doctor` | It classifies caller-provided owner routes, candidate boundaries, child reports, blocked preconditions, and stale current authority vocabulary facts without scanning repository state or owning semantic boundary decisions. |
+| Does current documentation still name a retired proof package or proof owner? | `adoption-doctor --agent-envelope` with caller-extracted `staleAuthority` facts | It fails current authority surfaces, admits only explicitly scoped historical vocabulary, and emits bounded repair actions without substring-scanning files itself. |
+| Can old local proof infrastructure be retired? | `migration-parity-admission` then `migration-plan` | Parity evidence and post-retirement validation are required before retirement actions appear. |
+| Did a requirement move, split, or retire correctly? | `requirement-source-transition` | Requirement lifecycle and replacement ids belong to source transition, not proof binding. |
+| Should temporary external design or PR facts become candidate requirements? | `requirement-authoring-plan` | It packages caller-owned extracted facts into candidate-only updates and owner-review questions without writing source files, retaining design documents, or approving meaning. |
+| Does a `REQ-*` have a route to execution? | `requirement-bindings` or `proof-slice` | Proof bindings own route closure, while tests own executable behavior. |
+| Which checks should run for a change? | `selective-gate-plan` then `selective-gate-evidence` | Planning and receipt comparison stay separate from command execution. |
+
+## Agent Decision Procedure
+
+Agents should use `agent-route` for executable routing and
+`agent-route --agent-envelope` when a bounded work packet is needed. The command
+returns deterministic JSON from explicit caller-owned facts; the envelope is an
+opt-in derived projection over the same report. This map explains the route
+families without becoming an execution, freshness, or merge decision.
+The exact route input vocabulary is machine-readable in
+`proofkit/cli-contract.v1.json` under `agent-route.inputContract`; the Go
+admission implementation and shipped CLI contract are parity-tested.
+
+Formal rule:
+
+```text
+goal plus caller-owned state
+  -> smallest matching command family
+  -> explicit required input
+  -> deterministic report or bounded envelope
+  -> caller-owned execution, proof freshness, and merge decision
+```
+
+Decision tree:
+
+| State or goal | Next Proofkit route | Stop or escalation condition |
+|---|---|---|
+| No admitted spec/profile exists. | `scaffold-project-structure`, `adoption-workflow-plan`, or `stack-preset` | Stop before writing files; the consumer owns materialization, overwrite policy, and final requirement text. |
+| Candidate boundary is uncertain. | `adoption-doctor` or `gradual-adoption-guidance --agent-envelope` | Escalate to owner review when the boundary is advisory, ambiguous, or missing native witnesses. |
+| Temporary external design, implementation-plan, PR, code, or test observations may contain durable requirements. | `requirement-authoring-plan` | Treat output as candidate-only; stop before writing `requirements.v1.json`, retaining temporary documents, or claiming requirement meaning. |
+| Requirement records exist. | `requirement-source-admission`; use `requirement-source-transition` for lifecycle changes. | Escalate when blocking requirements lack proof routes or lifecycle replacement ids are incomplete. |
+| Humans or agents need meta/module/submodule navigation. | `requirement-spec-tree`, then `requirement-spec-tree-view` or `requirement-browser-server --view spec-tree` from the same caller-owned tree input. | Stop before inferring hierarchy from paths. The consumer owns source hierarchy; CLI/browser outputs remain presentation only and are not committed by default. |
+| Overview prose may contain durable claims. | `spec-overview-claims` | Escalate when normative claims are not tied to `REQ-*` records. |
+| Requirements have no verified proof route. | `requirement-bindings`, `witness-plan`, `proof-slice`, or `requirement-proof-resolver` | Stop before claiming proof adequacy; native witness semantics stay with the consumer. |
+| Tests or proof evidence need inventory. | `test-evidence-inventory`, optionally `requirement-coverage-input-compose`, then `requirement-coverage-view` | Compose only from explicit caller-owned facts. Use `failureClassifications[]` and `warningClassifications[]` for machine routing. Escalate when tests are route-only, weak-oracle, unbound, or outside the caller-owned coverage universe. |
+| A change set is known. | `changed-path-set`, optionally `requirement-impact-input-compose`, `impact`, then `selective-gate-plan --agent-envelope` | Raw `knownChangedPaths` in `agent-route` are diagnostic only. Materialize a caller-owned `changed_path_set`, compose a caller-owned `impact_input` before `impact`, and compose a caller-owned `selective_gate_plan_input` before `selective-gate-plan`. Fail closed on unknown scope, dynamic edges, missing owner routes, unbound proof-like paths, or full-gate escalation. |
+| Does a TypeScript package public API match a caller-owned manifest? | `agent-route` with `goal: "verify_typescript_public_api"` and explicit `typescript_public_api_manifest` plus `typescript_public_api_repo_root`, then `typescript-public-api-surfaces --repo-root <caller-selected-root>` | This is an explicit filesystem scanner. Stop before guessing `repo-root`, claiming checkout freshness, package-manager truth, or merge readiness. |
+| Receipts are available for planned checks. | `selective-gate-evidence --agent-envelope`, then `obligation-decision --agent-envelope` | Escalate on missing, stale, invalid, untrusted, blocked, unavailable, or unknown-scope evidence. |
+| Human inspection is needed. | `requirement-source-view`, `requirement-proof-view`, `requirement-coverage-view`, `requirement-spec-tree-view`, or `requirement-browser-server` | `agent-route` emits browser commands as plan-only by default. Use `browserMode: "serve_local_view"` for `--serve` and `openBrowser: true` for `--open`. Rendered HTML and Markdown are presentation only unless the consumer admits a tracked artifact freshness gate. |
+| Temporary external document lifecycle facts, generated views, or rendered views need authority classification. | `document-lifecycle-boundary` | Treat lifecycle records as caller-owned metadata. Temporary design docs and implementation plans are not retained repository authority unless rewritten into deterministic specs, proof bindings, tests, package-public docs, or backlog rows. |
+| A JavaScript/TypeScript consumer needs less wrapper code. | `json-report-cli-adapter-source --language typescript` | Generated adapter source is caller-owned after materialization. The consumer still owns package pin, binary path, repo paths, local policy, and freshness proof. |
+| Local proof infrastructure may be retired. | `migration-parity-admission`, then `migration-plan` | Stop before deleting local owners unless parity and post-retirement validation are caller-approved. |
+| Release, package, or deploy evidence is in scope. | `release-authority`, `registry-consumer-proof-input-compose`, `registry-consumer`, `external-consumer`, `deployment-evidence-admission`, or `readiness-closeout` | Compose registry-consumer input from explicit primitive facts first when needed; final registry-consumer validation remains separate. Treat registry, release, CI, deployment, and readiness evidence as separate classes. |
+| The agent does not know which route applies. | `agent-route` with a known goal, or this map when no route input exists yet. | Escalate to the consumer owner instead of guessing, scanning ambient state, or executing commands. |
+
+## Routing Rules
+
+1. Start from `proofkit/cli-contract.v1.json` when a machine needs the exact
+   command, flags, input mode, output mode, scope class, or `agent-route` input
+   contract.
+2. Start from this map when a human or agent only needs the correct command
+   family.
+3. Use `agent-route` when a coding agent needs a deterministic next-command
+   packet from explicit current state. Use `agent-route --agent-envelope` when
+   the agent needs compact context refs, blockers, command refs, and non-claims
+   instead of a plain route report. Treat `blocked_*` states as stop signals,
+   not as permission to guess missing inputs. `knownChangedPaths` are
+   diagnostic-only until the caller supplies a `changed_path_set`; browser
+   server startup requires explicit `browserMode: "serve_local_view"`.
+4. Use agent-envelope output only when a coding agent needs bounded context;
+   do not expand whole proof graphs into chat.
+5. Treat generated views and rendered HTML as presentation only. They never
+   replace the structured source record.
+6. Escalate to the consuming repository's owner policy whenever Proofkit reports
+   unknown scope, missing receipts, unavailable preconditions, or command
+   execution requirements.
+7. Treat candidate boundaries from imperfect repositories as advisory until the
+   consuming repository commits stable requirement records and proof bindings.
+
+## Omitted Surfaces
+
+This map intentionally omits exhaustive per-field schema documentation,
+generated view instances, generated graph instances, receipt instances, and
+language-specific wrapper APIs. Those surfaces are either generated on demand,
+owned by the caller, or derived from the CLI/JSON contracts.

package/docs/release-process.md

@@ -0,0 +1,228 @@
+# Release Process
+
+This is the release how-to for `agentic-proofkit`. It owns the package release
+procedure and evidence requirements. It does not own product semantics for
+consuming repositories.
+
+## Release Model
+
+```text
+reviewed source
+  -> version tag
+  -> release workflow
+  -> candidate package evidence
+  -> deterministic SBOM, release manifest, and checksums
+  -> public npm publish or exact existing-byte match
+  -> optional PyPI publish or exact existing-byte match
+  -> post-publish npm registry identity with publication mode
+  -> optional post-publish PyPI registry identity with publication mode
+  -> root-only npm registry install and JSON CLI ABI proof
+  -> optional checksum-bound GitHub artifact attestations
+  -> GitHub Release archive assets and release evidence
+```
+
+Public npm is the primary dependency authority. The npm package identity is
+`@research-engineering/agentic-proofkit`; the installed executable name remains
+`agentic-proofkit`. The Python package identity remains `agentic-proofkit`.
+GitHub Release assets are archive and provenance lookup. Consumer repositories
+still own whether a released version becomes an admitted dependency.
+
+Release and adoption evidence uses canonical `authorityChannel` ids:
+`tarball_pilot`, `registry_release`, `python_wheel_candidate`,
+`pypi_registry_release`, and `github_release_archive`. Labels such as
+`public-npm`, `pypi`, and `github-release` are display projections, not
+authority ids.
+
+The target distribution model is multi-channel but single-source:
+
+```text
+Go source
+  -> npm package for JavaScript/TypeScript/Bun consumers
+  -> PyPI wheels for Python/uv consumers
+  -> GitHub Release assets with checksums and SBOM for provenance lookup
+```
+
+The repository-owned `release:manifest` tool creates `release-manifest.json`,
+`checksums.sha256`, `metadata-checksums.sha256`, `sbom-subjects.sha256`,
+release notes, and deterministic SBOM candidate evidence from explicit package,
+registry, and release evidence. `checksums.sha256` covers distributable archive
+assets, including the SBOM file itself. `metadata-checksums.sha256` covers
+release metadata files such as `release-manifest.json` and release notes.
+`sbom-subjects.sha256` covers only the package and wheel subjects described by
+that SBOM, so SBOM attestations do not make the SBOM file describe itself.
+Workflow-local scripts must not own a divergent release manifest or SBOM
+algorithm. PyPI wheels may be built and archived as candidate artifacts before
+PyPI publication. PyPI publication is enabled only when
+`PROOFKIT_ENABLE_PYPI_PUBLISH=true` and the PyPI Trusted Publisher is admitted.
+Wheels become PyPI dependency authority only after the dedicated PyPI job either
+publishes them through Trusted Publisher or records an exact existing-byte
+match, the repository-owned PyPI registry capture tool verifies filename, tag,
+URL, and SHA-256 identity against the candidate wheel set, and the release
+manifest binds that registry identity to the retained publication-mode sidecar.
+When a registry channel records `published_by_workflow` or `mixed`, the release
+manifest must also retain the Trusted Publisher identity tuple: provider,
+registry, project name, repository, exact `refs/tags/v<version>` workflow ref,
+publisher job, and
+environment. That tuple is retained provenance evidence for this workflow path;
+it does not prove provider UI configuration or provider-side OIDC acceptance by
+itself. `existing_byte_match` channels must not invent Trusted Publisher
+provenance for bytes that already existed in the registry.
+
+## Preconditions
+
+Before publishing a version:
+
+1. The source tree is clean.
+2. `package.json` contains the exact new version.
+3. `package.json` repository, license, bin, exports, files, and publishConfig
+   match the intended public package contract.
+4. The npm account has verified email and write-protective 2FA, or the package
+   uses an admitted Trusted Publisher configuration.
+5. When `PROOFKIT_ENABLE_PYPI_PUBLISH=true`, the PyPI account has a normal or
+   pending Trusted Publisher configured for project `agentic-proofkit`,
+   repository `research-engineering/agentic-proofkit`, workflow `release.yml`, and
+   environment `pypi`.
+6. The release workflow is configured for the package, public npm registry, and
+   release environments. PyPI release configuration is required only when the
+   PyPI channel is explicitly enabled.
+7. `npm run check` passes locally or the release candidate workflow provides
+   equivalent current-head evidence.
+
+## Candidate Proof
+
+Run locally before tagging when practical:
+
+```bash
+npm run check
+npm pack --dry-run --json
+git diff --check
+```
+
+`npm run check` verifies text policy admission, Go formatting, tests, vet,
+static analysis, workflow linting, vulnerability checks, npm package artifact
+creation, package artifact verification, Python wheel artifact creation, Python
+wheel verification, release SBOM, release manifest and checksum generation,
+outside-consumer binary smoke proof, self-hosting receipt validation, and
+coverage metrics generation.
+
+The dry-run package identity proves candidate tarball shape only. It does not
+prove the bytes served by the registry after publish.
+
+## Publish
+
+Create and push an exact version tag:
+
+```bash
+git tag v<version>
+git push origin v<version>
+```
+
+The `release` workflow must:
+
+1. verify source package identity;
+2. run the package gate;
+3. build publish dry-run evidence;
+4. build Python wheel candidates for the same embedded Go CLI;
+5. prove publish readiness before any registry side effect: the tag must equal
+   `v<package.json version>`, target a commit reachable from `main`, and have
+   npm dry-run evidence plus PyPI wheel candidates;
+6. publish to public npm through the admitted trusted path, or record
+   `existing_byte_match` when the same version already exists with exact
+   candidate bytes;
+7. when `PROOFKIT_ENABLE_PYPI_PUBLISH=true`, publish to PyPI through the
+   admitted trusted path, or record `existing_byte_match` when the same wheel
+   set already exists with exact candidate bytes;
+8. capture post-publish npm registry identity with package name, version, filename,
+   shasum, and integrity;
+9. when PyPI publication is enabled, capture post-publish PyPI registry identity
+   with package name, version, filename, wheel tags, URL, SHA-256, and retained
+   publication mode;
+10. verify a root-only npm registry install, signature audit, successful JSON
+    report command, and failed-report JSON command with stdout/stderr/exit-code
+    discipline;
+11. install and verify the pinned Node/npm toolchain before final metadata
+    generation, then run the repository-owned release manifest tool against the
+    candidate SBOM plus candidate and registry evidence, retaining Trusted
+    Publisher identity tuples for workflow-published registry channels;
+12. when `PROOFKIT_ENABLE_GITHUB_ATTESTATIONS=true` and the repository is
+    public, publish GitHub artifact provenance and SBOM attestations for the
+    checksum-bound release artifacts;
+13. create GitHub Release assets with checksums, metadata checksums, SBOM, and
+    a release manifest;
+14. retain normalized GitHub Release metadata as
+    `artifacts/release/github-release.json` after byte-for-byte asset
+    verification. The release manifest records GitHub Release channel data as
+    candidate/archive inventory; `github-release.json` owns post-create GitHub
+    Release facts.
+
+When `PROOFKIT_REQUIRE_VERIFIED_RELEASE_TAG=true`, the readiness gate also
+requires `GITHUB_REF_PROTECTED=true` and a GitHub-verified signed annotated tag.
+That hardening mode is enabled only after the repository has an admitted tag
+protection and signing-key policy; otherwise it would be an unreachable release
+precondition rather than a proof.
+
+## Post-Publish Evidence
+
+After publish, record the registry identity from npm:
+
+```bash
+npm view @research-engineering/agentic-proofkit@<version> version dist.tarball dist.integrity dist.shasum repository.url license --json
+```
+
+The release workflow records PyPI identity through:
+
+```bash
+npm run pypi:registry
+```
+
+The evidence must distinguish:
+
+- local candidate tarball facts;
+- local candidate wheel facts;
+- post-publish npm registry facts;
+- optional post-publish PyPI registry facts;
+- Trusted Publisher identity tuples for workflow-published npm/PyPI channels;
+- GitHub Release archive publication facts from retained `github-release.json`;
+- GitHub Release candidate asset inventory from `release-manifest.json`;
+- SBOM inventory facts;
+- optional GitHub artifact attestation facts;
+- planned but unpublished channel facts;
+- consumer install facts.
+
+These evidence classes are not interchangeable.
+
+## Rollback
+
+Published npm versions are immutable. Rollback means pinning consumers back to
+the previous admitted version and recording that consumer migration evidence.
+It does not delete the published package or mutate release assets.
+
+## Public Source Provenance
+
+Public-source provenance may be claimed only when the source repository is
+intentionally public and the release workflow publishes a later version from
+that public source. A release from a private source repository may be a valid
+package release, but it is not public-source provenance.
+
+Artifact attestation workflow wiring is not the same as completed provenance.
+When attestation storage is enabled and the repository visibility supports
+provider attestations, the release workflow must complete the attestation job
+before the GitHub Release asset job can publish archive assets. Provider-side
+attestation evidence becomes release evidence only after that job runs with
+attestation storage enabled and records the result. User-owned private
+repositories currently cannot store GitHub artifact attestations; in that state
+the release may still publish package and archive evidence, but it must not
+claim provider artifact attestation or public-source provenance.
+
+## Non-Claims
+
+This process does not:
+
+- approve adoption in a consuming repository;
+- execute consumer-native witnesses;
+- prove consumer proof freshness;
+- approve merge, rollout, deployment, or production readiness;
+- make GitHub Release assets package-manager dependency authority;
+- make SBOM inventory vulnerability absence or license approval;
+- make optional attestation wiring public-source provenance before a qualifying
+  public-source tag release exists.

package/docs/specs/proofkit-consumer-infra-retirement/overview.md

@@ -0,0 +1,62 @@
+# Proofkit Consumer Infrastructure Retirement Spec
+
+This spec owns Proofkit's reusable primitives for retiring duplicated
+consumer-side proof infrastructure. It covers migration planning, installed
+package runtime dependency admission, workspace registry admission,
+repo-profile admission, and adoption workflow routing.
+It also covers structured parity evidence admission for repositories that need
+machine-checkable preconditions before local proof-owner retirement review.
+
+It is intentionally infrastructure-only. Consumers own old proof surfaces, new
+Proofkit inputs, parity evidence, native witness execution, command policy,
+receipt freshness, file deletion, CI admission, merge approval, release
+approval, rollout approval, and production decisions.
+
+## Requirements
+
+- `REQ-PROOFKIT-RETIRE-001`: migration plans keep old and new proof owners
+  explicit and block retirement unless caller-provided parity evidence and
+  post-retirement validation commands exist.
+- `REQ-PROOFKIT-RETIRE-002`: package runtime dependency admission validates
+  caller-provided installed package identity and location facts without reading
+  package manager state or resolving packages.
+- `REQ-PROOFKIT-RETIRE-003`: workspace registry admission validates
+  caller-provided script, dependency, and lockfile facts against caller policy
+  without owning repository command policy or lockfile freshness.
+- `REQ-PROOFKIT-RETIRE-004`: repo-profile structural and command admission
+  validates caller-owned profile, path, command, and environment facts without
+  scanning repositories or approving native proof coverage.
+- `REQ-PROOFKIT-RETIRE-005`: adoption workflow plans route legacy migration,
+  gradual adoption, and release-channel scenarios to existing Proofkit
+  primitives through bounded structured command refs.
+- `REQ-PROOFKIT-RETIRE-006`: migration parity admission validates
+  caller-provided parity evidence shape, source/target closure, typed
+  equivalence dimensions, and matched digest equality without owning evidence
+  authenticity, freshness, semantic correctness, or retirement approval.
+- `REQ-PROOFKIT-RETIRE-007`: gradual adoption guidance keeps caller-provided
+  candidate boundaries advisory, exposes owner-review questions, routes mode
+  and checked-scope semantics through one private owner, and fails closed for
+  enforcement modes until the consumer admits stable requirements and proof
+  bindings.
+- `REQ-PROOFKIT-RETIRE-008`: adoption doctor reports classify caller-provided
+  imperfect-repository migration gaps and non-passing child reports into
+  advisory, failed, or blocked states and emit bounded owner-specific guidance
+  without scanning repositories or owning semantic boundary decisions.
+- `REQ-PROOFKIT-RETIRE-009`: workspace manifest fact projection turns explicit
+  caller-owned manifest records into registry-compatible workspace facts and
+  planning inputs without reading manifests from disk or owning package-manager
+  policy.
+- `REQ-PROOFKIT-RETIRE-010`: registry consumer proof input composition turns
+  explicit caller-owned registry metadata, registry pack comparison, lock,
+  smoke, rollback, precondition, and release-authority facts into a
+  `registry-consumer` input only when those facts are complete and aligned,
+  while preserving `registry-consumer` as the final proof-schema owner.
+
+## Non-Claims
+
+- This spec does not authorize deletion of consumer files or local proof owners.
+- This spec does not execute commands, authenticate parity evidence, compute
+  proof freshness, or approve merge.
+- This spec does not make Proofkit a repository scanner, command-policy owner,
+  CI authority, release authority, rollout authority, or production-readiness
+  authority for consumers.