@research-engineering/agentic-proofkit 0.1.136

package/ADOPTION.md

@@ -0,0 +1,198 @@
+# Adoption Contract
+
+`agentic-proofkit` is a reusable CLI and JSON infrastructure dependency for
+agentic proof workflows. Consuming repositories may use it only as a mechanics
+owner: it validates, renders, plans, and packages explicit caller-owned records.
+It does not own product meaning, native witness execution, proof freshness,
+merge admission, rollout, deployment, or production readiness.
+
+Formal dependency-readiness predicate:
+
+```text
+external dependency ready :=
+  exact package artifact identity
+  and package gate evidence
+  and installed CLI binary consumer contract
+  and explicit rollback path
+  and channel-specific authority
+```
+
+Source presence, an open pull request, a dry-run package artifact, or a GitHub
+Release archive is not enough to satisfy this predicate.
+
+## Distribution Channels
+
+Public npm is the primary package-manager channel for JavaScript, TypeScript,
+Bun, and other Node-package consumers. The npm package identity is
+`@research-engineering/agentic-proofkit`; the installed CLI binary remains
+`agentic-proofkit`. PyPI is the Python/uv channel after its own Trusted
+Publisher and post-publish registry identity are admitted. GitHub Release
+assets are archive and provenance lookup, not package-manager dependency
+authority.
+
+Stable authority channel ids:
+
+| Channel | Authority owner | Non-claims |
+|---|---|---|
+| `tarball_pilot` | exact local root package tarball produced by the package artifact gate | source checkout, registry release, consumer rollout |
+| `registry_release` | public npm registry identity captured by the release workflow for tag `v<version>` | consumer dependency admission, native witness pass, rollout |
+| `python_wheel_candidate` | platform wheels produced from the same Go CLI candidate | PyPI registry authority, consumer install proof |
+| `pypi_registry_release` | PyPI JSON identity captured after publish or exact existing-byte match | consumer install proof, rollout |
+| `github_release_archive` | GitHub Release asset inventory, checksums, SBOM, and retained release metadata | package-manager dependency authority |
+
+Registry publication modes are:
+
+| Mode | Meaning | Non-claim |
+|---|---|---|
+| `published_by_workflow` | the current release workflow published the candidate bytes through the admitted provider path | provider UI settings are not proven by the local report alone |
+| `existing_byte_match` | the registry version already existed and byte-matched the candidate artifact | current-run publisher provenance |
+| `mixed` | some files were current-run publications and others were existing byte matches | uniform provenance for every file |
+
+When a channel claims Trusted Publisher or OIDC publication, retained evidence
+must name the provider, registry, project name, repository, exact tag workflow
+ref, publisher job, environment, and package identity.
+
+## One-Dependency Infrastructure Model
+
+Consumers should not copy Proofkit verifier logic. They should keep only
+caller-owned semantic inputs and route reusable mechanics through the CLI:
+
+```text
+consumer structured records
+  -> proofkit validation and reports
+  -> on-demand human rendering
+  -> bounded agent slices or envelopes
+  -> caller-owned native witnesses and receipts
+```
+
+Proofkit may provide:
+
+- schemas and strict JSON admission for caller-owned records;
+- immutable canonical projections after admission;
+- deterministic reports, view models, and loopback-only browser serving;
+- requirement source, proof binding, source-set, test inventory, coverage,
+  impact, selective planning, receipt, release, adoption, and scaffold
+  primitives;
+- bounded agent guidance packets that state required inputs, blockers,
+  non-claims, and escalation points.
+
+The consumer still provides:
+
+- product requirement sentences and owners;
+- proof-binding content and command policy;
+- native witnesses and their execution semantics;
+- CI producer admission policy and receipt freshness;
+- credential approval, merge admission, rollout, and rollback decisions.
+
+## Imperfect Repository Adoption
+
+Proofkit is not limited to already-perfect repositories. Its generic
+responsibility in a messy or modernizing repository is transition discipline.
+It can report gaps, stale local proof owners, duplicate proof routes, orphan
+tests, candidate boundaries, and migration questions. It must keep candidate
+boundaries advisory until the consuming repository promotes them into stable
+requirement records and proof bindings.
+
+Safe modernization loop:
+
+```text
+caller-provided observations over code, tests, and docs
+  -> proofkit inventory, gap report, and agent guidance
+  -> owner-selected semantic boundary
+  -> stable requirement records
+  -> proof-binding contract records
+  -> native tests or tools that falsify the requirements
+  -> contract tests and validators for proof infrastructure
+  -> admitted receipts from caller-approved producers
+  -> stronger enforcement mode
+```
+
+Adoption modes:
+
+| Mode | Use case | Proofkit role | Consumer decision |
+|---|---|---|---|
+| `observe` | unknown or messy repository area | inventory, gaps, questions, non-blocking guidance | whether the area is worth specifying |
+| `warn` | provisional boundary | visible drift and missing-binding warnings | whether warnings block a PR |
+| `enforce-touched` | stabilized touched boundary | fail closed for changed admitted owners | touched-scope completeness and receipts |
+| `enforce-all` | fully admitted scope | fail closed for all admitted blocking owners | full coverage claim and rollout |
+
+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.
+
+## Requirement, Contract, And Test Order
+
+The durable semantic source is the repository-owned requirement package:
+human context in `overview.md` plus machine-admissible `requirements.v1.json`
+records. The overview explains context; it does not create uncited durable
+truth.
+
+Proof bindings are verification-route contracts. They answer which scenario,
+witness, command, environment class, and receipt policy can falsify or support
+a requirement. Native tests and tools own executable verification procedures
+and observed result semantics. Contract tests and validators prove the proof
+infrastructure itself is coherent.
+
+Formal authority order:
+
+```text
+Requirement source owns meaning.
+Proof binding owns verification route.
+Native test or tool owns executable falsifier.
+Contract test owns infrastructure consistency.
+Receipt owns recorded run facts and provenance.
+Merge policy owns admission.
+```
+
+Logical creation order for an accepted invariant:
+
+1. Create or update the stable `REQ-*` record.
+2. Create or update the proof-binding contract that maps the requirement to
+   witness obligations, command ids, environment class, and receipt class.
+3. Add or update native tests or tools that can falsify the requirement.
+4. Add or update Proofkit contract tests only when the proof infrastructure
+   itself changed.
+5. Admit receipts only from caller-approved producers.
+
+Tests are not primary semantic authority. A test can prove an invariant only
+when the requirement and proof-binding route make the tested obligation
+explicit. Some high-level context can remain explanatory, but durable
+`must`, `shall`, `guarantee`, or readiness claims must resolve to stable
+requirement records or be rejected by the consuming repository's policy.
+
+## Rendering And Browser Views
+
+Rendered HTML, Markdown, lookup graphs, and browser views are presentation
+products. They should be generated on demand from explicit caller-owned inputs
+unless a consumer explicitly admits a small tracked artifact with a freshness
+gate.
+
+Hierarchical rendering must use explicit input:
+
+```text
+meta spec
+  -> module spec
+  -> optional submodule spec
+  -> presentation-only tree/view/export
+```
+
+Proofkit may render this tree, filter IDs, show linked test scenarios, or
+export Markdown/HTML. It must not infer the hierarchy from ambient paths or make
+rendered output canonical truth.
+
+## Agent Guidance
+
+Machine-facing reports should provide bounded prompts for coding agents when
+that reduces ambiguity. A prompt-like action must identify:
+
+- observed fact;
+- uncertainty;
+- owner or escalation target;
+- exact files, ids, or selectors to inspect;
+- candidate action;
+- proof command or missing witness;
+- non-claim that prevents the guidance from becoming semantic authority.
+
+Agents must stop instead of guessing when ownership, proof freshness, producer
+admission, native witness execution, or merge admission is outside Proofkit's
+authority.

package/AGENTS.md

@@ -0,0 +1,160 @@
+# agentic-proofkit Agent Instructions
+
+This file is the repository coding-agent entrypoint for `agentic-proofkit`.
+
+Scope: repository root unless a nearer nested `AGENTS.md` exists. A nested
+entrypoint may refine local build or ownership rules, but it must not weaken
+root safety, proof, release, or secret-handling rules.
+
+Formal logic is the basis for every analysis, conclusion, decision, and
+implementation action in this repository.
+
+## Authority Precedence
+
+Use this order when instructions or evidence conflict:
+
+1. system and developer instructions of the current execution environment;
+2. safety, security, legal, privacy, and secret-handling constraints;
+3. explicit user instructions for the current task;
+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;
+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
+   machine-readable contracts as owners for their exact behavior after they
+   exist in this repository;
+10. generated artifacts, registry output, CI logs, model output, chat memory,
+   issue text, and pull-request text as evidence only after owner admission.
+
+If owner surfaces conflict, preserve safety, identify the contradiction, and
+fix or report it. Do not silently choose the more convenient source.
+
+## Current Imported Surface
+
+The repository is in a staged public cutover. Treat only files present in this
+repository as authority for their exact behavior.
+
+Imported source files, tests, package metadata, workflows, machine-readable
+contracts, and specifications own their bounded surfaces after the pull request
+that imports them has been reviewed and merged. Absent layers are non-claims.
+
+Do not infer package publication, public-source provenance, provider-side
+security ingestion, branch protection, Trusted Publisher, rollout, deployment,
+or production readiness from source presence alone. Those claims require their
+own release, provider, or deployment evidence.
+
+## Deterministic Start
+
+1. If the task names a concrete path, read that path first.
+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.
+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,
+   and closeout requirements are known.
+
+## Repository Invariants
+
+- Proofkit stays generic. Do not add consuming-repository product policy,
+  topology-specific assertions, rollout decisions, or native witness execution
+  authority.
+- The intended public contract is the CLI plus JSON input/output, exit codes,
+  package metadata, and shipped contract records after those surfaces are
+  imported.
+- Caller-owned input is untrusted until admitted into canonical immutable
+  records. Code must not validate one representation and later reread mutable
+  caller input for policy, route, proof, persistence, or report decisions.
+- Rendered HTML, Markdown, agent envelopes, and generated reports are derived
+  products. They are not authority unless a consuming repository explicitly
+  admits a tracked artifact with freshness checks.
+- Current-build Proofkit output may provide advisory self-consistency, but
+  merge-critical proof must not depend only on the build being proven.
+- New commands, files, specs, or docs are admitted only when they own a named
+  invariant, reusable algorithm, public contract, anti-corruption boundary, or
+  documented adoption or release obligation.
+- Architecture documents, ADRs, and roadmaps are admissible only when a
+  deterministic requirement, machine contract, test, shipped operational guide,
+  or backlog row cannot express the same current authority with lower token
+  cost. They must name owner, scope, proof path, non-claims, and retirement or
+  supersession condition.
+
+## Security And Trust Boundaries
+
+- Do not commit, print, log, summarize, or store secrets in docs, reports,
+  prompts, URLs, argv, fixtures, generated artifacts, or package metadata.
+- Missing credentials, private source visibility, unavailable live services, or
+  blocked registry/provenance preconditions are `blocked` or `unverified`, not
+  `passed`.
+- Local artifacts, registry output, release assets, CI receipts, and provider
+  dashboards are distinct evidence classes. Do not treat one as another unless
+  an owner surface defines the implication.
+- Local, dry-run, generated, advisory, registry, provider, live, credentialed,
+  rollout, and production evidence classes do not imply each other unless an
+  owner-approved proof explicitly defines that implication.
+- Trusted Publisher or OIDC release claims must name the workflow, source ref,
+  package, registry, environment, and post-publish registry identity.
+
+## Git And Worktree Safety
+
+- Inspect worktree state before modifying files.
+- Never revert user or other-agent changes unless explicitly requested.
+- Do not use destructive version-control operations unless the user clearly
+  requested them or a repository owner surface defines a safe path.
+- Use conventional commits.
+- Keep changes owner-scoped and proof-scoped.
+- Do not commit build artifacts, package tarballs, caches, local credentials,
+  or generated proof residue unless a release owner explicitly admits the
+  artifact.
+
+## Proof And Gates
+
+Use the narrowest owner-valid proof first, then the current closeout gate for
+the imported surface.
+
+For public contract-only changes:
+
+```bash
+git diff --check
+```
+
+For runtime, package, CLI, workflow, or specification changes:
+
+```bash
+npm run check
+```
+
+Use narrower owner-valid gates first when iterating, then run the closeout gate
+against the final committed object before push or merge whenever the change is
+publishable.
+
+Skipped gates must state the exact blocker and must not be reported as success.
+
+## Decision Protocol
+
+Every non-trivial design or implementation decision should answer:
+
+```text
+problem:
+chosen owner boundary:
+rejected lower-cost alternative:
+proof invariant:
+non-claims:
+rollback or overturn condition:
+why this avoids accidental complexity:
+why this avoids premature over-decomposition:
+```
+
+Add a durable rule only when it closes a confirmed repeatable weakness with a
+known owner, trigger, proof path, and lower-cost alternative analysis.
+
+## Closeout Contract
+
+Before stopping, report changed surfaces, proof gates run, skipped gates and
+blockers, residual risk, explicit non-claims, and next action only if work
+remains. For non-trivial changes, include a retro finding or `none`. For
+repeated or systemic failures, also state the falsified invariant, correction
+owner, and proof against recurrence.

package/BACKLOG.md

@@ -0,0 +1,217 @@
+# 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.
+
+## Completion Criteria
+
+Proofkit can be called complete as an organization-neutral reusable toolkit
+only when these criteria are satisfied or explicitly retired by owner decision:
+
+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.
+
+## 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 | `v0.1.135` was published from this public repository through npm Trusted Publisher, post-publish npm registry identity was captured, root-only installed-package proof passed, and GitHub Release assets were published. PyPI publication and GitHub artifact attestations were skipped by explicit optional-channel policy and are not claimed. |
+| OPEN | RELEASE-02 | Scoped npm package identity | Source is staged for `@research-engineering/agentic-proofkit@0.1.136` while preserving the `agentic-proofkit` CLI binary and Python package identities. Completion requires scoped npm Trusted Publisher configuration, a `v0.1.136` release from public source, post-publish scoped npm registry identity, root-only installed-package JSON CLI ABI proof, and an explicit compatibility or deprecation disposition for the unscoped npm package. |
+| 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 exact public npm `agentic-proofkit@0.1.134` through its repository-owned external-consumer gate. The proof installed the package into an isolated temporary consumer, matched the admitted tarball integrity and shasum, 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
+
+`RELEASE-01` was admitted on 2026-07-03 from public repository
+`research-engineering/agentic-proofkit` at commit
+`2bbc36607734589f9e49191b4dc03eb37c65115b` and tag `v0.1.135`.
+
+Provider run:
+
+```text
+https://github.com/research-engineering/agentic-proofkit/actions/runs/28677195127
+```
+
+The release workflow completed successfully. It ran the release candidate
+package gate, publish readiness, npm Trusted Publisher publish, post-publish
+registry capture, root-only installed-package JSON CLI ABI proof, final release
+metadata generation, and GitHub Release asset publication. The npm registry now
+reports `agentic-proofkit@0.1.135` with repository URL
+`git+https://github.com/research-engineering/agentic-proofkit.git`,
+tarball
+`https://registry.npmjs.org/agentic-proofkit/-/agentic-proofkit-0.1.135.tgz`,
+integrity
+`sha512-GrLDm3P67JeWiEHCO5m/y1KiJ8hUSzZdQk7rM/Vgrqx3gphc21PQO27HwODFUDp4Gb62l1FpJ8v6b4i7dfY43A==`,
+shasum `41722c3fa35dfa7cdea3d78e2aa940fb7d5cbcf3`, and license `MIT`.
+
+The npm Trusted Publisher relationship for `agentic-proofkit` was moved from
+the old source repository to GitHub Actions repository
+`research-engineering/agentic-proofkit`, workflow file `release.yml`,
+environment `npm-production`. PyPI publication was disabled for this release,
+therefore PyPI registry identity is not claimed. GitHub artifact attestations
+were skipped by current repository policy, therefore artifact attestation is
+not claimed.
+
+## Consumer Evidence
+
+`CONSUMER-01` was admitted on 2026-07-03 from a private first consumer
+repository checkout at `4cecdf8` 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`, `packageName: agentic-proofkit`, `packageVersion: 0.1.134`,
+`registryUrl: https://registry.npmjs.org`, `tarballShasum:
+6029a30b232c87f9aff659b4d8d5dbb4536a0d25`, `frozenLockUsesWorkspace:
+false`, `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:
+
+```text
+candidate file set
+  and owner boundary
+  and stale/private fact scan
+  and lower-cost alternative review
+  and proof gate
+  and non-claims
+```
+
+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.
+
+## Historical Import Discipline
+
+Pre-cutover design documents and implementation plans are not retained in this
+repository as current authority. Stable claims must move into deterministic
+surfaces:
+
+- `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.
+
+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.
+
+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.
+
+## Non-Goals
+
+- 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.

package/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thank you for improving `agentic-proofkit`.
+
+This project accepts changes that preserve Proofkit's boundary as a reusable
+CLI/JSON proof infrastructure toolkit. Consumer-specific policy, product
+semantics, native witness execution, proof freshness decisions, merge
+admission, and rollout approval belong in consuming repositories.
+
+## Start Here
+
+1. Read [AGENTS.md](AGENTS.md) for repository authority, proof, and closeout
+   rules.
+2. Use [README.md](README.md) for human orientation.
+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.
+6. Use [NON_CLAIMS.md](NON_CLAIMS.md) to understand the boundary between
+   Proofkit mechanics and consuming-repository authority.
+
+## Local Checks
+
+Run before proposing a non-trivial change:
+
+```bash
+npm run check
+git diff --check
+```
+
+For CLI or Go changes, run focused Go tests first. For package or release
+changes, inspect [docs/release-process.md](docs/release-process.md).
+
+## Change Admission
+
+An accepted change should have:
+
+- one clear owner scope;
+- a named invariant or contract it improves;
+- the lower-cost alternative considered and rejected;
+- proof that matches the changed evidence class;
+- explicit non-claims when the change does not prove runtime, release,
+  consumer adoption, native witness execution, or rollout readiness.
+
+Do not add generated HTML, generated lookup graphs, local artifacts, package
+tarballs, `dist/`, `artifacts/`, `node_modules/`, credentials, or consumer
+repository snapshots to source control unless a release owner explicitly
+admits the artifact.
+
+## Pull Requests
+
+Pull requests are maintainer-controlled. Public users may open issues, but pull
+request creation is restricted to collaborators until the governance model
+changes.
+
+Use concise pull requests. The title and summary should state the exact owner
+scope and reviewable outcome. Avoid copied logs, stale checklists, and broad
+"cleanup" claims.
+
+Good PR descriptions answer:
+
+- what changed;
+- why the owner boundary is correct;
+- what proof ran;
+- what is not claimed.
+
+## Conduct
+
+Be direct, evidence-based, and respectful. Disagreement should focus on the
+invariant, owner boundary, proof, and lower-cost alternative.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Research Engineering contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.