agentic-proofkit 0.1.91

package/ADOPTION.md

@@ -0,0 +1,464 @@
+# Adoption Contract
+
+`agentic-proofkit` targets public npm release. Consumers may still pilot exact
+tarball artifacts, but a consumer may treat the package as an organization-wide
+dependency only after public release evidence, exact install proof, parity
+proof, and rollback path are recorded for that consumer.
+
+Formal channel invariant:
+
+```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
+```
+
+For the current `tarball_pilot` channel, channel-specific authority is the exact
+root tarball produced by `npm run package:artifact`. It is not a source checkout,
+not a Git URL, not a registry release, and not a consumer rollout approval.
+
+For the `registry_release` channel, channel-specific authority is a published
+root package produced by the `release` workflow from tag `v<version>`. A
+publish-ready PR alone is not registry publication.
+
+## One-Dependency Infrastructure Model
+
+Consumers should treat agentic-proofkit as a reusable infrastructure dependency, not as a
+repository policy owner. One dependency may provide schemas, validators,
+scaffolding, migration helpers, renderers, selective planners, impact resolvers,
+receipt validators, agent envelope builders, CI helper commands, and optional
+presentation adapters. The consumer still provides product specifications,
+requirement records, concrete proof bindings, command and environment policy,
+native witnesses, CI admission policy, credential approval, and rollout
+decisions.
+
+Consumer adoption should therefore create or maintain caller-owned structured
+records, then use proofkit to validate, render, slice, and plan around those
+records:
+
+```text
+consumer structured records
+  -> proofkit validation and reports
+  -> on-demand human rendering
+  -> bounded agent slices/envelopes
+  -> caller-owned native witnesses and receipts
+```
+
+Routine rendered HTML or Markdown views, agent envelopes, and validation reports
+should not be committed by default. They are derived products unless a consumer
+proves that a small tracked artifact improves review or offline operation and is
+protected by freshness checks.
+
+## Proofkit Self-Hosting Convergence
+
+Proofkit is also a consumer of the spec-first machine-proof architecture it
+implements. It may dogfood its current CLI for advisory self-consistency and
+developer feedback, but the current build must not be the sole merge-critical
+authority for admitting itself.
+
+Target state:
+
+```text
+Proofkit human specs
+  -> structured REQ-* records
+  -> proof bindings
+  -> witness plans over existing package commands
+  -> admitted CI or release receipts
+```
+
+Convergence must proceed in owner-scoped slices:
+
+| Slice | Owner boundary | Required trust anchor | Non-claims |
+|---|---|---|---|
+| Package boundary | Public binary, CLI boundary, and package artifact requirements | Existing `npm run check`, `npm run package:artifact`, publish dry-run evidence from the `release` workflow, and outside-consumer binary smoke proof | Does not claim consumer adoption, registry publication, or proof freshness |
+| Requirement records | Human-readable specs plus structured requirement records for Proofkit-owned primitives | Schema admission from the previous released Proofkit, a minimal bootstrap verifier, or admitted CI producer policy | Does not infer requirements from prose, tests, or generated views |
+| Proof bindings | REQ-* to witness-command mappings for existing native package checks | Existing native witness commands and admitted producer policy | Does not execute commands inside Proofkit validators or replace native pass/fail truth |
+| Receipts | Release and CI receipts for package gates | Admitted CI runner or signed/attested producer policy | Does not make local advisory receipts merge-satisfying evidence |
+| Generated views | On-demand human rendering and agent envelopes | Freshness validation against structured source when a view is tracked | Generated views are lookup-only and are not authority |
+
+First implementation slice:
+
+1. Add a package-boundary spec package for Proofkit-owned public API, CLI, and
+   package artifact requirements.
+2. Add structured requirement records for that package-boundary slice.
+3. Bind those requirements to existing witness commands such as typecheck,
+   tests, package artifact checks, and outside-consumer binary smoke proof.
+4. Keep rendered views and agent envelopes generated on demand, not tracked by
+   default.
+5. Promote enforcement from advisory to blocking only after the external trust
+   anchor proves parity.
+
+Second implementation slice:
+
+1. Add a spec-proof-core spec package for Proofkit-owned requirement source,
+   proof binding, witness planning, selective proof, rendered view, and agent
+   envelope primitives.
+2. Add structured requirement records for that spec-proof-core slice.
+3. Bind those records to existing native tests for requirement source
+   admission, requirement proof bindings, witness planning, selective planning,
+   selective evidence, requirement proof views, and bounded agent envelopes.
+4. Keep consumer requirement meaning, command policy, receipts, CI admission,
+   and rollout decisions outside Proofkit.
+5. Treat rendered views and agent envelopes as generated presentation only, not
+   tracked authority.
+6. Close self-hosting linkage through generated `spec-proof-bundle-admission`
+   artifacts, not tracked generated views.
+
+Third implementation slice:
+
+1. Add a receipt-authority spec package for Proofkit-owned proof receipt shape,
+   receipt producer linkage, producer-policy self-proof, and spec-proof bundle
+   linkage primitives.
+2. Add structured requirement records for that receipt-authority slice.
+3. Bind those records to existing native tests for proof receipt admission,
+   receipt producer admission, producer-policy self-proof, and spec-proof
+   bundle admission.
+4. Keep producer authentication, receipt freshness, native witness execution,
+   current-obligation matching, and merge/release/rollout decisions outside
+   Proofkit.
+5. Use the receipt-authority slice as a trust-boundary prerequisite for later
+   consumer helper-retirement claims, not as a claim that any consumer evidence
+   is fresh or merge-satisfying.
+
+Fourth implementation slice:
+
+1. Add a consumer-infrastructure-retirement spec package for Proofkit-owned
+   migration planning, installed package dependency admission, workspace
+   registry admission, repo-profile admission, and adoption workflow routing.
+2. Add structured requirement records for that consumer-retirement slice.
+3. Bind those records to existing native tests for migration plans, package
+   runtime dependency admission, workspace registry admission, repo-profile
+   structural admission, and adoption workflow routing.
+4. Keep old proof surfaces, parity evidence, native witness execution, command
+   policy, receipts, CI admission, file deletion, merge approval, release
+   approval, and rollout decisions inside each consuming repository.
+5. Use the consumer-retirement slice as an auditable prerequisite for later
+   consumer helper deletion, not as a claim that any consumer repository is
+   ready to delete local infrastructure.
+
+This section is a convergence plan, not proof evidence. Package behavior remains
+owned by source, tests, build output, package metadata, CI, and release
+artifacts. Consumer repositories still own their own requirement sentences,
+proof bindings, command policy, receipts, and rollout decisions.
+
+## Current Channels
+
+The supported pilot channel is an exact npm tarball set produced by the package
+gate. The default long-lived dependency channel is the public npm registry. The
+default archive/provenance channel is a GitHub Release attached to the same
+version tag. GitHub Packages remains a supported registry kind only for
+consumers that intentionally choose a GitHub-scoped private or internal package
+channel.
+
+Normal consumers declare only the root `agentic-proofkit` package. The package
+contains the supported platform binaries and selects the current OS/CPU tuple at
+runtime. Pilot proofs therefore pin one root tarball instead of a root/platform
+tarball pair.
+
+Local producer command:
+
+```bash
+npm run check
+npm run package:artifact
+```
+
+CI producer:
+
+- workflow: `ci`;
+- artifact name: `agentic-proofkit-npm-package-<git-sha>`;
+- contents: root package tarball, `npm-pack.json`, and self-hosting proof
+  receipts;
+- retention: 14 days.
+
+Consumers must pin the exact tarball source and keep their own lockfile
+integrity. The tarball is suitable for pilot integration and CI proof, not for
+long-lived release management.
+
+Registry producer workflow:
+
+- workflow: `release`;
+- trigger: version tag `v<package.json version>` or manual dispatch on that tag;
+- packages: the single `agentic-proofkit` root package;
+- registry: `https://registry.npmjs.org`;
+- authority: npm Trusted Publisher through GitHub Actions OIDC with
+  `id-token: write`;
+- archive authority: GitHub Release on the same version tag.
+
+Registry publication also requires npm account security. The package owner
+account must have verified email and write-protective 2FA, and release
+publication must run through an admitted npm Trusted Publisher configuration
+for GitHub Actions OIDC. The publisher is scoped to `release.yml`, the
+`npm-production` environment, and the `agentic-proofkit` package.
+
+The workflow runs the package gate and `npm publish --dry-run --json` in a
+read-only candidate job. Only the publish job receives `id-token: write`; it
+publishes the root package through npm Trusted Publishing, records post-publish
+registry artifact identity, verifies a root-only registry install, and verifies
+registry signatures. Only the release-assets job receives `contents: write`;
+it creates the GitHub Release containing the package tarball, SHA-256 checksum
+file, and release manifest. The workflow does not migrate any consumer
+repository.
+
+The same boundary is machine-checkable through:
+
+```bash
+agentic-proofkit release-authority --input proofkit/release-authority.json
+```
+
+Consumer-provided registry install evidence can be normalized through:
+
+```bash
+agentic-proofkit registry-consumer --input proofkit/registry-consumer.json
+```
+
+Gradual adoption can also emit deterministic agent guidance:
+
+```bash
+agentic-proofkit adoption-workflow-plan --input proofkit/adoption-workflow-plan.json
+agentic-proofkit adoption-workflow-plan --input proofkit/adoption-workflow-envelope.json --contract-envelope
+agentic-proofkit adoption-workflow-plan --input proofkit/adoption-workflow-plan.json --agent-envelope
+agentic-proofkit adoption-checklist --input proofkit/adoption-checklist.json
+agentic-proofkit branch-authority --input proofkit/branch-authority.json
+agentic-proofkit deployment-evidence-admission --input proofkit/deployment-evidence-admission.json
+agentic-proofkit stack-preset --preset typescript_workspace
+agentic-proofkit workspace-changed-package-plan --input proofkit/workspace-changed-package-plan.json
+agentic-proofkit workspace-shard-partition --input proofkit/workspace-shard-partition.json
+agentic-proofkit scaffold-profile-plan --input proofkit/scaffold-profile-plan.json
+agentic-proofkit scaffold-project-structure --input proofkit/project-structure-scaffold.json
+agentic-proofkit scaffold-project-structure --input proofkit/project-structure-scaffold.json --agent-envelope
+agentic-proofkit gradual-adoption-bootstrap --input proofkit/bootstrap.json
+agentic-proofkit gradual-adoption-bootstrap --input proofkit/bootstrap.json --agent-envelope
+agentic-proofkit gradual-adoption-bootstrap --input proofkit/bootstrap.json --materialization-manifest
+agentic-proofkit gradual-adoption-guidance --input proofkit/adoption-guidance.json
+agentic-proofkit requirement-bindings --input proofkit/requirement-bindings.json
+agentic-proofkit requirement-proof-source-set --input proofkit/requirement-proof-source-set.json
+agentic-proofkit proof-slice --input proofkit/requirement-bindings.json
+agentic-proofkit requirement-proof-view --input proofkit/requirement-bindings.json --scope slice --format markdown
+agentic-proofkit requirement-proof-view --input proofkit/requirement-bindings.json --scope slice --format html > /tmp/proofkit-proof-view.html
+agentic-proofkit typescript-public-api-surfaces --input proofkit/typescript-public-api-surfaces.json --repo-root .
+agentic-proofkit spec-proof-bundle-admission --input proofkit/spec-proof-bundle.json
+agentic-proofkit migration-parity-admission --input proofkit/migration-parity-admission.json
+agentic-proofkit migration-plan --input proofkit/migration-plan.json
+agentic-proofkit package-runtime-dependency-admission --input proofkit/package-runtime-dependency-admission.json
+agentic-proofkit selective-gate-evidence --input proofkit/selective-gate-evidence.json
+agentic-proofkit selective-gate-plan --input proofkit/selective-gate-plan.json
+```
+
+Adoption workflow plans are the scenario-level entrypoint. They route
+caller-selected scenarios such as new repository adoption, existing gradual
+adoption, legacy proof migration, and release-channel checks to existing
+Proofkit primitives. They use structured argv command refs and missing-input
+blockers, but they do not scan the repository, execute commands, authenticate
+receipts, decide proof freshness, or choose whether the scenario is appropriate
+for the consumer.
+HTML requirement views are self-contained browser documents with search,
+filters, and ID visibility controls. Generate them on demand for review rather
+than committing them as source truth; if a repository chooses to track a
+rendered view, it owns a rendered-artifact freshness gate.
+When the caller declares `adoption_checklist` or `branch_authority` input refs,
+the same workflow can also route to `adoption-checklist` and
+`branch-authority`. Those refs are optional routes, not global adoption
+preconditions; checklist requiredness and expected branch policy stay in the
+consuming repository.
+Workflow agent envelopes are opt-in bounded presentations over the same plan.
+They preserve structured `argv` command refs for agents and omit primitive
+input payload bodies.
+
+Adoption checklist reports summarize caller-owned adoption evidence after a
+scenario has been selected. The consumer provides checklist items, required
+item ids, evidence refs, command refs, blockers, and non-claims. Proofkit
+deterministically classifies required items as satisfied, missing, blocked, or
+not applicable. It does not scan repositories, execute commands, authenticate
+evidence refs, prove freshness, infer requiredness policy, or approve merge,
+release, or rollout.
+
+Branch authority reports summarize caller-owned branch-setting and workflow
+branch-ref evidence. The consumer provides observed branch refs, expected
+branch refs, requiredness, evidence refs, and non-claims. Proofkit compares
+those facts deterministically and exposes required versus advisory drift. It
+does not query GitHub, parse workflow files, mutate branch settings, prove
+branch protection, execute CI or publish workflows, or choose branch policy.
+
+Bootstrap reports produce starter payload plans for the first non-blocking
+module adoption. They list caller-owned files, emit JSON payloads for
+`gradual-adoption`, `gradual-adoption-guidance`, starter
+requirement-to-witness proof binding, and `witness-plan`, and include a
+structured `agentActionPlan`. They do not write files, scan implicit repository
+state, execute native witnesses, or choose rollout policy.
+
+Bootstrap agent envelopes are opt-in compact projections over bootstrap
+reports. They include planned file refs, observe-mode command refs, route
+questions, and bind/verify/promote actions, but intentionally omit full starter
+payloads. They are for agent routing, not file transport or proof evidence.
+
+Bootstrap materialization manifests are opt-in dry-run projections over
+bootstrap reports. They list planned files, payload-backed JSON content,
+`sha256:` content refs, and caller-owned content gaps. They help a developer or
+agent review first-adoption file changes, but they do not write files, inspect
+existing files, resolve conflicts, or prove that files exist after review.
+
+Project-structure scaffolds compose profile scaffold, bootstrap, materialized
+starter payloads, and workflow routing into one first-adoption review packet.
+Their agent envelopes are opt-in bounded routing packets over that review
+packet. They include candidate file refs, blocked caller-content preconditions,
+command refs, route questions, and action items, but intentionally omit starter
+payload bodies. They are for agent routing, not file transport, overwrite
+approval, or proof evidence.
+
+Guidance reports are routing artifacts. They may tell an agent which owner,
+spec, proof binding, command, blocked precondition, or next action to inspect
+next. Their `agentActionPlan` entries carry phase, caller-owned evidence refs,
+caller-owned commands, and non-claims, but they do not execute native
+witnesses, create proof truth, or approve rollout.
+`callerSuggestedAutofixCandidates` entries are caller-owned suggestions; their
+safety remains owned by the consuming repository.
+
+Stack preset reports are starter shapes. They can suggest initial files,
+environment classes, proof-like paths, witness kinds, and commands for common
+repository classes, but they are not mandatory CI policy and they do not inspect
+the consumer repository.
+
+Repo-profile scaffold plans bridge stack presets to caller-owned profile
+authoring. They emit a deterministic draft shape, provenance, caller-required
+gaps, and follow-up validation commands from explicit caller input. They do not
+scan the repository, write `repo-profile.v1.json`, admit profile correctness,
+or decide command/environment policy.
+
+Migration plans bridge local proof infrastructure to Proofkit primitives for
+existing repositories. They order baseline, parallel-proof, parity-check,
+old-owner retirement, and post-retirement validation phases. They block
+retirement candidates that lack caller-provided parity evidence or
+post-retirement validation commands, but they do not delete files, execute
+commands, authenticate parity, or approve retirement.
+
+Migration parity admission validates the structured parity evidence that a
+consumer may later reference from a migration plan. It checks declared
+source-owner and target-ref closure, typed equivalence kinds, caller-provided
+digest equality for `matched` records, and fail-closed parity statuses. It does
+not compute digests, execute native witnesses, authenticate receipts, prove
+semantic correctness, compute freshness, or approve old-owner retirement.
+
+Requirement-binding reports validate caller-provided `REQ-*` to witness-command
+records, emit lookup-only evidence graphs, and emit compact proof slices for
+agent work packets. They do not own requirement meaning, execute native
+witnesses, decide proof freshness, or approve proof coverage.
+
+Requirement-proof views render the same caller-owned structured records as
+lookup-only JSON, Markdown, or HTML. They are human presentation products, not
+canonical proof truth, and they should normally be generated on demand instead
+of committed.
+
+Selective gate plans are caller-input projections. A consumer supplies changed
+paths, generated-artifact ownership rules, proof-like path coverage,
+package-gate commands, dependency-freshness inputs, private prefixes, and
+artifact-integrity policies. The report returns mandatory commands, skipped
+gate reasons, generated artifact obligations, and fail-closed diagnostics. It
+does not read git state, prove changed-path completeness, execute commands,
+prove command success, choose repository policy, approve proof coverage, pass a
+secret scan, or decide proof freshness.
+
+Workspace changed-package and shard-partition reports expose the reusable
+workspace planning primitives directly through the CLI for non-TypeScript or
+thin-adapter consumers. The caller provides changed paths, package nodes,
+escalation rules, selected roots, and shard totals; Proofkit returns
+deterministic package roots, escalation reasons, dependency closures, and
+matrix rows. It does not discover git changes, scan repositories, choose CI
+commands, schedule runners, or approve gate skipping.
+
+Selective gate evidence reports compare a caller-provided selective gate plan
+with caller-provided execution receipts. The report verifies that every planned
+command has exactly one receipt, that unexpected receipts are rejected, and
+that failed, blocked, or not-run receipts are visible in deterministic output.
+It does not execute planned commands, read CI logs, prove log freshness, prove
+receipt authenticity, or decide whether a consuming repository may skip any
+caller-owned gate.
+
+Gradual guidance modes:
+
+| Mode | Meaning |
+|---|---|
+| `observe` | Emit agent routing without blocking on caller proof state. |
+| `warn` | Preserve a passing guidance report while surfacing source gaps as warnings. |
+| `enforce-touched` | Fail closed for touched failed rules or reported missing proof bindings in the checked scope. |
+| `enforce-all` | Fail or block on any caller-owned source report failure, blocked precondition, or missing proof binding. |
+
+Recommended consumer rollout:
+
+1. Start with `observe` for one bounded module and a caller-owned native witness.
+2. Move to `warn` after the report route is stable and visible in CI logs.
+3. Move to `enforce-touched` for changed modules after proof bindings cover touched work.
+4. Move to `enforce-all` only after the repository owner admits full coverage.
+
+`tarball_pilot` reports must keep `manifestPrivate=true`, must not declare a
+registry authority, must use a `file_tarball` dependency pin, and must bind the
+declared artifact and rollback pin to the package name and version.
+Strict `registry_release` reports use `schemaVersion=3` and fail closed unless
+the input declares registry kind, registry URL, package scope, visibility,
+publish authority mode, publish workflow, source repository, consumer migration
+path, rollback policy, and publish dry-run proof. Legacy `schemaVersion=1`
+registry inputs remain accepted for compatibility, but they do not carry
+source-repository proof.
+GitHub Packages releases must use the GitHub source owner as the npm package
+scope and `github_actions_github_token` as the publish authority. Public npm
+registry provenance releases require both public source repository visibility
+and public package visibility.
+
+Consumer dependency shape:
+
+```json
+{
+  "devDependencies": {
+    "agentic-proofkit": "file:vendor/agentic-proofkit/agentic-proofkit-<version>.tgz"
+  }
+}
+```
+
+Registry dependency shape:
+
+```json
+{
+  "devDependencies": {
+    "agentic-proofkit": "<version>"
+  }
+}
+```
+
+Consumers must not depend on a sibling source checkout, a Git URL, `src/`,
+`dist/`, or any deep import path.
+
+## Consumer Obligations
+
+A CLI consumer must:
+
+- commit the package-manager lockfile change;
+- run an installed `agentic-proofkit` binary smoke test after installation;
+- keep product specifications, requirement bindings, native witnesses, CI gates,
+  and rollout policy in the consuming repository;
+- keep custom proof rules outside this package unless they generalize across
+  repositories;
+- avoid copying proofkit source files into the consumer.
+
+Proofkit does not publish a package-root SDK contract. Consumers that need a
+language-native wrapper should keep that wrapper in their own repository and
+drive the installed CLI/JSON contract instead of importing `src/`, `dist/`, or
+any deep package path.
+
+Rollback is deletion of the file dependency, tarball reference, and lockfile
+entry. No registry state is created by this pilot channel.
+
+## Registry Promotion Gate
+
+Registry publication remains a separate action even after this repository is
+publish-ready. A promotion must prove:
+
+- source repository owner, name, URL, and visibility;
+- registry package visibility for the selected channel;
+- exact package version and immutable install evidence;
+- consumer migration path from tarball pilots to versioned dependency pins.
+- rollback path to the prior admitted dependency version.
+
+Only a consumer migration PR may remove a consumer's local fallback or tarball
+dependency after exact registry install and parity evidence pass.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Pereverziev
+
+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.