@research-engineering/agentic-proofkit 0.1.146 → 0.1.147

package/ADOPTION.md

@@ -30,6 +30,19 @@ Publisher and post-publish registry identity are admitted. GitHub Release
 assets are archive and provenance lookup, not package-manager dependency
 authority.
 
+Consumers may choose npm or Bun for installation. Both consume the same npm
+registry package identity:
+
+```bash
+npm install -D @research-engineering/agentic-proofkit
+bun add -d @research-engineering/agentic-proofkit
+```
+
+Release evidence still uses npm as the registry-authority CLI because Proofkit
+records npm-specific package identity, `dist.integrity`, `dist.shasum`, `npm
+pack`, and root-only registry install proof. Bun is not used as a substitute
+for those release-authority facts.
+
 Stable authority channel ids:
 
 | Channel | Authority owner | Non-claims |
@@ -120,6 +133,52 @@ Candidate boundaries in `observe` and `warn` are advisory. Enforcement modes
 fail closed while candidate boundaries remain unresolved because enforcement
 requires owner-admitted requirements and proof bindings.
 
+Pre-spec trust modes:
+
+| Trust mode | Use case | Proofkit role | Required next owner step |
+|---|---|---|---|
+| `code_baseline` | no specs exist and maintainers intentionally freeze current behavior | admit caller-owned capability observations and emit bounded candidate requirement/proof-binding seeds only when scenarios have candidate ids and executable anchors | review seeds, materialize accepted `requirements.v1.json` and proof bindings, then run source, binding, inventory, and coverage gates |
+| `audit_from_code` | no specs exist and maintainers do not trust current behavior | admit caller-owned observations as hypotheses, keep missing anchors as owner actions, and emit questions without failing solely on missing anchors | answer owner questions, add falsification witnesses, then materialize only accepted requirements |
+
+`capability-map-admission` owns this pre-spec transition artifact. It does not
+replace `requirement-authoring-plan`: capability maps produce seeds from
+observed capabilities, while authoring plans compose owner-reviewed candidate
+updates into a non-authoritative requirement-source preview and transition
+check. Durable truth still starts only after the consumer commits and admits
+`requirements.v1.json`.
+
+## First Adoption Loop
+
+Proofkit can reduce initial adoption glue, but it must not turn observation into
+truth. The first loop is:
+
+```text
+caller-owned capability or test observations
+  -> candidate-only Proofkit reports
+  -> owner review and materialization
+  -> strict requirement source, proof binding, and test inventory admission
+  -> coverage view from explicit admitted facts
+```
+
+Use `test-evidence-inventory --projection discovery-draft` only for explicit
+caller-owned test discovery facts. The command does not scan repositories,
+execute tests, emit `semantic_falsifier` evidence, or close coverage. It emits
+candidate inventory guidance with a non-strict candidate authority so an agent
+can ask the right owner questions and materialize strict inventory rows later.
+Candidate inventory diagnostics are rejected by strict inventory admission until
+the consumer rewrites them into owner-reviewed `caller_owned_inventory`.
+
+Use `requirement-coverage-input-compose` when the consumer already has explicit
+requirement source, proof binding, test inventory, coverage universe, and local
+environment policy records. The command may compose from direct child records
+or from previously normalized records, but it must reject failed child reports
+instead of repairing semantics.
+
+Use `witness-plan` with a `projection: "requirement-bindings"` input only when
+the proof binding already contains safe witness command facts and the caller
+provides witness command vocabulary. The projection avoids duplicated command
+identity; native execution and command freshness remain caller-owned.
+
 ## Requirement, Contract, And Test Order
 
 The durable semantic source is the repository-owned requirement package:

package/AGENTS.md

@@ -19,7 +19,7 @@ Use this order when instructions or evidence conflict:
 4. nearest scoped `AGENTS.md`;
 5. this repository authority model;
 6. `README.md` as a human overview only;
-7. `BACKLOG.md` for current completion criteria, open work, and blocked claims;
+7. `BACKLOG.md` for active work, blocked claims, and deferred work;
 8. `ADOPTION.md`, `NON_CLAIMS.md`, `docs/proofkit-contract-map.md`, and
    `docs/specs/*` as owner surfaces for their stated boundaries;
 9. imported source files, tests, package metadata, workflows, and
@@ -51,7 +51,7 @@ own release, provider, or deployment evidence.
 2. If the request is clear, do not ask whether to resume previous work.
 3. If the request is ambiguous and strong unfinished-work signals exist,
    inspect the worktree state and ask whether to resume.
-4. Use `BACKLOG.md` for current completion state and open work.
+4. Use `BACKLOG.md` for active work, blocked claims, and deferred work.
 5. Load one primary owner surface for the task. Load a second owner surface only
    when the task clearly crosses another boundary.
 6. Stop context loading once the owner boundary, allowed mutation, proof path,

package/BACKLOG.md

@@ -1,203 +1,56 @@
 # Proofkit Backlog
 
-This file is the canonical work ledger for completing the public
-`research-engineering/agentic-proofkit` cutover. It tracks open work and blocked
-claims. It is not a CLI manual, proof registry, or historical release log.
+This file is the canonical active-work ledger for
+`research-engineering/agentic-proofkit`.
 
-## Completion Criteria
+It tracks only current `NEXT`, `BLOCKED`, or `DEFERRED` work. It is not a
+roadmap, release log, proof registry, architecture document, CLI manual, or
+historical completion archive.
 
-Proofkit can be called complete as an organization-neutral reusable toolkit
-only when these criteria are satisfied or explicitly retired by owner decision:
+## Current State
 
-1. **Public source provenance is admitted.** A release is produced from this
-   public source repository and records source, tag, package, registry, and
-   release evidence.
-2. **Public npm release is admitted.** A versioned release publishes or
-   exact-byte-matches the root package, records post-publish npm identity,
-   verifies root-only installation, proves JSON CLI ABI from the installed
-   package, and documents rollback.
-3. **Optional PyPI channel is admitted before it is claimed.** Python/uv wheels
-   are candidate evidence until PyPI Trusted Publisher and post-publish PyPI
-   registry identity are proven.
-4. **Browser rendering is released.** Requirement source, proof, coverage, and
-   spec-tree views are consumable through CLI rendering and loopback-only
-   serving without requiring generated HTML in consumer repositories.
-5. **Repository identity is organization-neutral.** Package metadata, README,
-   agent entrypoint, docs, workflows, tests, and examples avoid organization-
-   or consumer-specific authority.
-6. **At least one consumer migration is proven from the public package.** A
-   consuming repository replaces local or vendored Proofkit access with the
-   public package, smokes the installed binary, records rollback, and keeps
-   product semantics local.
-7. **Second-consumer reuse is proven before broad reuse claims.** A second
-   topology adopts one stable module in observe or warn mode with explicit
-   caller-owned inputs.
-8. **Agent guidance is usable.** Reports provide bounded envelopes that name
-   what to inspect, who owns the decision, which proof route applies, what is
-   omitted, and what escalation is required.
-9. **Gradual adoption is usable for imperfect repositories.** A repository can
-   scaffold starter records, define owner-reviewed requirements, bind proofs,
-   run selective checks, and promote enforcement only after explicit owner
-   approval.
-10. **Self-hosting avoids circular proof.** Current-build Proofkit output may
-    provide advisory self-consistency, but merge-critical proof must rely on
-    native package gates, admitted CI producer policy, a prior release, or a
-    minimal bootstrap verifier.
-11. **Release-size changes are evidence-gated.** Platform-binary splitting,
-    OCI, Homebrew, or Go module distribution is admitted only when measured
-    consumer need outweighs added registry and adoption complexity.
-12. **Generic authority invariants are upstream-owned.** Requirement-binding
-    identity, test-inventory identity, report-shape admission, and other
-    cross-repository mechanics live in Proofkit before consumers retire
-    duplicate local checks.
-13. **Hierarchical spec rendering is explicit-input and presentation-only.**
-    Meta, module, and submodule spec chains can be rendered or exported from a
-    caller-owned tree without implicit repository scanning or generated-output
-    authority.
+Active work is limited to the rows below.
 
-## Current Cutover State
-
-| Status | ID | Scope | Completion condition |
-|---|---|---|---|
-| DONE | IMPORT-01 | Public project contract | Initial public README, license, contribution, security, and source-hygiene boundaries were admitted. |
-| DONE | IMPORT-02 | Deterministic kernel primitives | Core Go admission, stable JSON, digest, report, path, release-platform, and package helper primitives were imported with tests. |
-| DONE | IMPORT-03 | CLI command and release proof surface | CLI registry, command families, package/release tools, npm/PyPI wrapper surfaces, specs, proofkit JSON, and workflows were imported with local `npm run check`. Provider CI, protected-branch, registry, and release evidence remain separate open proof classes. |
-| DONE | IMPORT-04 | Adoption and backlog owner surfaces | Public-ready adoption and backlog routing were added without stale private release facts or consumer-specific claims. |
-| DONE | IMPORT-05 | Historical design and plan cleanup | Durable claims from pre-cutover design and implementation-plan work are represented by deterministic specs, proof bindings, tests, package-public docs, or open backlog rows. No source-repository design documents or implementation plans are retained as current authority. |
-| DONE | IMPORT-06 | Remaining source-local code delta audit | Non-document source comparison found no old source file missing from the public source tree. Old source bytes remain candidate evidence only and are not imported over current hardening. |
-| DONE | RELEASE-01 | Public source release | A public-source npm release path was admitted through Trusted Publisher, post-publish registry identity capture, root-only installed-package proof, and GitHub Release assets. PyPI publication and GitHub artifact attestations were skipped by explicit optional-channel policy and are not claimed. |
-| DONE | RELEASE-02 | Scoped npm package identity | The organization-scoped npm package identity is the preferred release channel and is admitted through the scoped npm Trusted Publisher path, post-publish registry capture, root-only installed-package JSON CLI ABI proof, and GitHub Release assets. The `agentic-proofkit` CLI binary and Python package identities remain unchanged. The previous unscoped npm package remains a compatibility artifact, not the preferred dependency identity. |
-| BLOCKED | RELEASE-03 | PyPI registry publication | The release workflow has a dedicated PyPI Trusted Publisher job and the GitHub repository has the `pypi` environment required by that workflow identity, but PyPI registry publication is blocked until the PyPI account has a normal or pending Trusted Publisher for project `agentic-proofkit`, repository `research-engineering/agentic-proofkit`, workflow `release.yml`, and environment `pypi`. `PROOFKIT_ENABLE_PYPI_PUBLISH` must stay disabled until that PyPI-side publisher exists. Completion requires enabling the variable, publishing a new version or recording exact existing-byte match, capturing PyPI registry identity, and proving the package through the release workflow. Workflow-published or mixed publication modes must bind the PyPI Trusted Publisher tuple in the release manifest; existing-byte-match mode must retain exact-byte registry proof without inventing publisher provenance. Wheel files in GitHub Release assets remain candidate artifacts, not PyPI dependency authority. |
-| DONE | SECURITY-01 | Provider security settings | Repository is public with collaborator-only PR creation, public issues, squash-only merges, branch protection on `main`, strict required CI, CodeQL, OSV source advisory scanning, Scorecard, Dependabot security updates, secret scanning, and push protection. Non-provider secret patterns and validity checks remain unavailable or disabled under the current provider plan and are not claimed. |
-| DONE | CONSUMER-01 | Public-package consumer proof | A private first consumer repository consumed the public npm package through its repository-owned external-consumer gate. The proof installed the package into an isolated temporary consumer, matched the admitted package identity, proved lockfile resolution was not workspace based, ran installed CLI `self-check`, `witness-plan`, and `release-authority`, proved rollback by removing the dependency from the temporary lockfile, and preserved consumer-owned native witness authority. |
-| DONE | CONSUMER-02 | Second-consumer pilot | A private topology-distinct Python/FastAPI consumer module was run through explicit-input warn-mode `gradual-adoption-guidance` and `--agent-envelope` pilot records. Proofkit admitted the caller-owned route, reported one advisory candidate boundary, reported two missing proof-binding rule IDs as warnings, emitted route/bind/modernize/verify/promote agent actions, and kept enforcement blocked until consumer owners admit stable requirements and proof bindings. No generic Proofkit blocker was confirmed. |
-
-## Release Evidence Model
-
-This backlog records release-channel completion state, not immutable per-version
-provider facts. Exact package versions, source refs, workflow run identities,
-tarball URLs, integrity strings, shasums, release assets, and registry
-post-publish facts are owned by npm registry records, GitHub Release artifacts,
-and generated release manifests for each tag.
-
-Do not copy exact post-publish provider facts into package-public source docs:
-package bytes are immutable, while those facts are known only after the package
-candidate has been built and published. The package verifier rejects shipped
-Markdown that reintroduces exact release versions, provider run URLs, registry
-tarball URLs, or raw release hash evidence.
-
-PyPI publication is not claimed unless the release workflow enables the PyPI
-channel and records post-publish PyPI registry identity. GitHub artifact
-attestations are not claimed unless the release workflow records provider
-attestation evidence for the published assets.
-
-## Consumer Evidence
-
-`CONSUMER-01` was admitted from a private first consumer repository using these
-consumer-owned gates:
-
-```bash
-bun run verify:proofkit-external-consumer
-bun scripts/report-proofkit-external-consumer.selftest.ts
-bun scripts/lib/proofkit-runtime.selftest.ts
-bun scripts/verify-workspace-script-registry.selftest.ts
-bun run verify:proofkit-pilot
-bun run verify:proofkit-requirement-source
-bun run verify:proofkit-requirement-coverage
-```
-
-The machine report for `bun scripts/report-proofkit-external-consumer.ts
---format json` emitted `reportKind: proofkit.registry-consumer`, `state:
-passed`, a public npm registry URL, non-workspace lockfile resolution,
-`releaseAuthorityReportKind: proofkit.release-authority`,
-`releaseAuthorityState: passed`, and `rollbackLockContainsPackage: false`.
-
-This evidence does not claim npm publication from this public source
-repository, Trusted Publisher configuration, public-source release provenance,
-provider-side security ingestion, PyPI publication, second-consumer reuse,
-native consumer test execution by Proofkit, rollout readiness, production
-readiness, or retirement of consumer-owned product semantics.
-
-`CONSUMER-02` was admitted on 2026-07-03 from a private topology-distinct
-consumer module using explicit caller-owned warn-mode adoption facts. The
-Proofkit guidance report emitted `reportKind:
-proofkit.gradual-adoption-guidance`, `state: passed`, `guidanceMode: warn`,
-`candidateBoundaryCount: 1`, `proofBindingMissingCount: 2`, and warning rules
-for `proofkit.gradual-adoption-guidance.missing-proof-bindings` and
-`proofkit.gradual-adoption-guidance.candidate-boundaries`. The companion agent
-envelope emitted `route`, `bind`, `modernize-boundary`, `verify`, and
-`promote` actions, with candidate-boundary context refs and explicit
-instructions to keep native witness execution outside Proofkit.
-
-Gap classification:
-
-- Generic Proofkit work: no confirmed blocker. The current CLI accepted
-  explicit caller facts, preserved advisory candidate-boundary semantics, kept
-  missing binding records as warnings in warn mode, and emitted bounded agent
-  guidance without scanning repository state.
-- Consumer-local adapter work: the consumer still needs owner-reviewed
-  `requirements.v1.json` records, requirement-to-proof bindings, native witness
-  command records, and a repository-local environment that can run its existing
-  coverage-map and backend test commands. Native witness attempts were blocked
-  by consumer-local dependency/bootstrap preconditions, not by Proofkit command
-  semantics.
-
-This evidence does not claim second-consumer enforcement, native witness
-success, consumer rollout, production readiness, public package publication
-from this source repository, provider-side registry evidence, or retirement of
-consumer-owned coverage-map and test authority.
-
-## Import Discipline
-
-Old local repository content is not automatically authoritative. A transfer
-batch is admissible only when:
+The public source cutover, scoped npm channel, optional PyPI channel, provider
+security setup, first-consumer proof, and second-consumer pilot have all been
+closed. Durable rules and reusable architecture now live in their owner
+surfaces:
 
-```text
-candidate file set
-  and owner boundary
-  and stale/private fact scan
-  and lower-cost alternative review
-  and proof gate
-  and non-claims
-```
+- `README.md` for human orientation;
+- `ADOPTION.md` for adoption, distribution, rendering, requirement, contract,
+  test, and agent-guidance models;
+- `NON_CLAIMS.md` for boundary denials;
+- `docs/proofkit-contract-map.md` for command-family routing and agent
+  decision procedure;
+- `docs/release-process.md` for release-channel evidence and publication
+  process;
+- `docs/specs/**/requirements.v1.json` for durable machine requirements;
+- `proofkit/*.json` for shipped machine contracts and proof routes;
+- source, tests, package metadata, and workflows for executable behavior.
 
-Code from the old local repository is rejected when it would delete current
-hardening, weaken package verification, remove non-disclosure tests, reduce
-semantic-route proof, or replace current public-source wording with private
-repository facts.
+## Admission Rules
 
-## Historical Import Discipline
+Add a row only when new work is accepted and cannot be represented more
+precisely by an existing owner surface.
 
-Pre-cutover design documents and implementation plans are not retained in this
-repository as current authority. Stable claims must move into deterministic
-surfaces:
+Every row must be falsifiable and include:
 
-- `docs/specs/**/requirements.v1.json` for durable requirements;
-- `proofkit/requirement-bindings.json` and `proofkit/witness-plan.json` for
-  proof routes;
-- source code and tests for executable behavior;
-- package-public docs only when consumers need stable operational guidance;
-- this backlog only for open, falsifiable work.
+- `Status`: `NEXT`, `BLOCKED`, or `DEFERRED`;
+- `ID`: stable owner-scoped identifier;
+- `Scope`: one bounded reason to change;
+- `Completion condition`: objective proof or explicit retirement condition.
 
-Temporary design, implementation-plan, PR, code, or test observations may be
-caller-owned inputs to authoring commands, but they must not become tracked
-repository authority unless rewritten into one of the deterministic surfaces
-above.
+When a row is completed, remove it from this active backlog after its durable
+rule, evidence, or behavior is represented by the owning source, test,
+contract, release artifact, provider record, or documentation surface. Do not
+retain completed rows here as history.
 
-Architecture documents, ADRs, or roadmap documents are not banned by type. They
-are admitted only when they are the lowest-cost current authority for a real
-architecture decision, migration sequence, release obligation, or adoption
-contract. An admitted architecture document must state its owner, scope, proof
-path, non-claims, and retirement or supersession condition; otherwise the claim
-belongs in `requirements.v1.json`, machine contracts, executable tests,
-package-public operational docs, or this backlog.
+Historical evidence belongs in pull requests, release artifacts, registry
+records, generated release manifests, or the owning docs named above.
 
-## Non-Goals
+## Open Rows
 
-- Proofkit does not own product semantics for consuming repositories.
-- Proofkit does not become a CI runner, repository scanner, policy owner, or
-  proof freshness authority.
-- Proofkit does not require generated HTML, generated Markdown, or generated
-  lookup graphs to be committed by default.
-- Proofkit does not require a rewrite in another language without measured
-  evidence that the current Go CLI is the limiting factor.
+| Status | ID | Scope | Completion condition |
+|---|---|---|---|
+| BLOCKED | RELEASE-01 | Decide whether normalized post-create GitHub Release facts need durable public evidence beyond retained workflow artifacts under immutable GitHub Releases. | Either keep `github-release.json` as retained workflow evidence with explicit non-claims, or design a provider-compatible public evidence channel that does not require post-create Release asset mutation. Completion requires a release-proof design and live provider proof; direct backfill/upload is blocked by immutable Release upload rejection. |
+| BLOCKED | RELEASE-02 | Resolve or explicitly retire the immutable historical GitHub Release asset-closure gap where release metadata references a notes asset that the published release does not contain. | Either attach the exact checksum-matching notes asset if provider policy allows, or record the provider-impossible closure in the release evidence model and prove future releases cannot repeat the gap. Completion requires live provider proof; direct backfill is currently blocked by immutable Release upload rejection. |

package/CONTRIBUTING.md

@@ -15,7 +15,8 @@ admission, and rollout approval belong in consuming repositories.
 3. Use [docs/proofkit-contract-map.md](docs/proofkit-contract-map.md) to find
    the owner command or primitive.
 4. Use [ADOPTION.md](ADOPTION.md) for dependency and channel authority.
-5. Use [BACKLOG.md](BACKLOG.md) to check completion criteria and open work.
+5. Use [BACKLOG.md](BACKLOG.md) to check active work, blocked claims, and
+   deferred work.
 6. Use [NON_CLAIMS.md](NON_CLAIMS.md) to understand the boundary between
    Proofkit mechanics and consuming-repository authority.
 
@@ -28,6 +29,10 @@ npm run check
 git diff --check
 ```
 
+If your local project uses Bun, `bun run check` is acceptable as a convenience
+runner only when it invokes the same scripts and leaves `npm run check`
+equivalent. Release and package-authority proof remains npm-owned.
+
 For CLI or Go changes, run focused Go tests first. For package or release
 changes, inspect [docs/release-process.md](docs/release-process.md).
 

package/NON_CLAIMS.md

@@ -7,7 +7,8 @@ This repository state does not claim:
 
 - runtime implementation readiness;
 - package publication readiness;
-- public-source provenance for any existing package version;
+- public-source provenance for a package version unless that version's release
+  assets, registry identity, and checksum manifests are artifact-closed;
 - source-code completeness;
 - production readiness;
 - vulnerability absence;
@@ -25,7 +26,7 @@ This repository state does not claim:
 - deployment approval;
 - package-registry access-control proof;
 - provider-side CodeQL, OSV, Scorecard, secret-scanning, or dependency-scanning
-  ingestion;
+  absence-of-findings, ingestion freshness, or dashboard processing success;
 - GitHub branch-protection proof;
 - Trusted Publisher or OIDC publication proof;
 - generated HTML, Markdown, reports, lookup graphs, or agent envelopes as

package/README.md

@@ -13,12 +13,31 @@ packets without copying verifier logic between projects.
 | Surface | State |
 |---|---|
 | Source visibility | Public |
-| Current layer | Public source with admitted scoped npm release evidence |
+| Current layer | Public source; release evidence is version-specific |
 | Runtime implementation | Go CLI with npm and Python wrapper packaging |
-| Package release | Scoped npm release channel admitted; exact version and registry identity are owned by npm and GitHub Release artifacts |
-| Public-source provenance | Admitted through release artifacts and registry evidence, not by this overview |
+| Package release | Scoped npm release channel configured; exact version and registry identity are owned by npm and GitHub Release artifacts |
+| Public-source provenance | Claimed only for a version whose release assets, registry identity, and checksum manifests are artifact-closed |
 | License | MIT |
 
+## Install
+
+The canonical registry identity is npm:
+
+```bash
+npm install -D @research-engineering/agentic-proofkit
+```
+
+Bun consumers may install the same npm registry package with Bun:
+
+```bash
+bun add -d @research-engineering/agentic-proofkit
+```
+
+npm remains the release-authority toolchain because release proof records npm
+registry identity, `dist.integrity`, `dist.shasum`, `npm pack`, and root-only
+registry install evidence. Bun is a supported consumer/developer package
+manager path, not a replacement for npm release evidence.
+
 ## Project Boundary
 
 `agentic-proofkit` is intended to provide reusable proof-workflow mechanics for
@@ -29,6 +48,95 @@ Proofkit does not own a consuming repository's product requirements, native
 witness execution, receipt authenticity, proof freshness, merge admission,
 rollout, deployment, or production readiness.
 
+## How It Works
+
+Proofkit has two related but separate loops:
+
+- an **authoring loop** for turning observations into candidate invariants and
+  repo-owned specifications;
+- a **proof loop** for admitting those specifications, binding them to evidence,
+  and producing derived views or bounded next actions.
+
+The loops are separate because generated observations are not product truth.
+Only the consuming repository can promote a candidate invariant into an
+admitted requirement.
+
+### Proof Loop
+
+```mermaid
+flowchart TB
+    subgraph Repo["Consumer repository authority"]
+        Requirements["Requirements and invariants"]
+        Bindings["Proof bindings and witness commands"]
+        Execution["Native test and CI execution"]
+        Decision["Owner decision"]
+    end
+
+    subgraph Proofkit["Proofkit reusable mechanics"]
+        Admission["Admit and normalize JSON"]
+        Graph["Build proof graph"]
+        Planning["Plan selected checks"]
+        Receipts["Admit receipt-shaped evidence"]
+        Views["Render derived views"]
+        Packets["Emit bounded agent packets"]
+    end
+
+    Requirements --> Admission
+    Bindings --> Admission
+    Admission --> Graph
+    Graph --> Planning
+    Planning --> Execution
+    Execution --> Receipts
+    Receipts --> Decision
+    Graph --> Views
+    Graph --> Packets
+    Views --> Decision
+    Packets --> Decision
+```
+
+The core invariant is separation of authority. The consuming repository owns
+what the product must do and which native checks prove it. Proofkit owns the
+reusable mechanics: admitting structured inputs, preserving provenance,
+checking proof-binding shape, planning bounded verification, rendering derived
+views, and returning agent-readable next-action packets.
+
+The diagram keeps the rendering syntax intentionally simple for GitHub README
+compatibility. Requirements, bindings, witness commands, native execution, and
+final decisions stay in the consumer repository. Proofkit outputs are admitted
+reports, plans, views, receipts, or agent packets; they do not become product
+truth unless the consumer explicitly admits them.
+
+### Invariant Authoring Loop
+
+For a repository with no specification, Proofkit can guide an agent through two
+different starting modes:
+
+```mermaid
+flowchart TB
+    Start["Code, docs, tests, issues, and maintainer intent"] --> Mode["Choose trust mode"]
+    Mode --> Baseline["Code baseline mode"]
+    Mode --> Audit["Code audit mode"]
+    Baseline --> Observations["Caller-owned capability observations"]
+    Audit --> Observations
+    Observations --> Seeds["Candidate invariants and requirement seeds"]
+    Seeds --> Review["Owner review and promotion"]
+    Review --> Specs["Repo-owned requirements.v1.json"]
+    Specs --> Obligations["Proof obligations"]
+    Obligations --> Evidence["Proof bindings and test inventory"]
+    Evidence --> Admission["Proofkit admission and coverage"]
+```
+
+| Mode | Use when | Result |
+|---|---|---|
+| Code baseline | Current behavior is accepted as the starting contract | Candidate requirements and bindings that preserve current behavior until owners review them |
+| Code audit | Current behavior may be wrong or incomplete | Untrusted observations and questions that must be promoted by a repository owner before becoming requirements |
+
+In both modes, generated records remain candidates until the consuming
+repository admits them as repo-owned requirements, proof bindings, and witness
+plans. Proofkit can structure and validate candidate packets, but it does not
+extract complete behavior from arbitrary source code, invent product policy, or
+make generated invariants authoritative by itself.
+
 ## Start Here
 
 | Need | Owner |
@@ -36,7 +144,7 @@ rollout, deployment, or production readiness.
 | Human orientation | This README |
 | Coding-agent startup | `AGENTS.md` |
 | Adoption and release-channel model | `ADOPTION.md` |
-| Completion criteria and remaining work | `BACKLOG.md` |
+| Active work ledger | `BACKLOG.md` |
 | Contribution rules | `CONTRIBUTING.md` |
 | Vulnerability reporting boundary | `SECURITY.md` |
 | Explicit boundary denials | `NON_CLAIMS.md` |

package/SECURITY.md

@@ -2,17 +2,20 @@
 
 ## 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.
+Supported versions are named only after a reviewed public release has
+artifact-closed release assets, registry identity, and checksum manifests.
+The current source tree may be ahead of the latest supported package version.
 
 ## 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.
+Use GitHub Private Vulnerability Reporting for this repository:
+https://github.com/research-engineering/agentic-proofkit/security/advisories/new
 
-Until a private channel is available, do not open a public issue with exploit
-details.
+If GitHub returns an unavailable route, open a public issue that requests a
+private security contact path and includes no exploit details, credentials,
+private data, or step-by-step reproduction.
+
+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