@research-engineering/agentic-proofkit 0.1.146 → 0.1.147

package/docs/proofkit-contract-map.md

@@ -33,16 +33,17 @@ No command may infer ambient repository truth from the current directory.
 
 | Family | Main commands | Caller provides | Proofkit owns | Consumer owns | Output authority |
 |---|---|---|---|---|---|
-| Adoption and scaffolding | `adoption-contract-envelope`, `adoption-workflow-plan`, `adoption-doctor`, `gradual-adoption`, `gradual-adoption-bootstrap`, `gradual-adoption-guidance`, `scaffold-profile-plan`, `scaffold-project-structure`, `stack-preset` | adoption intent, aggregate adoption contract envelope, target paths, owner routes, caller-extracted stale authority vocabulary facts, stack preset id | aggregate contract-envelope admission, deterministic starter plans, bounded guidance envelopes, dry-run manifests, adoption gap and stale-authority classification | final files, final requirements, rollout policy, text extraction from files | selected child output, plan, report, or agent envelope |
-| Requirement source | `requirement-authoring-plan`, `requirement-source-admission`, `requirement-source-transition`, `spec-overview-claims`, `requirement-spec-tree`, `requirement-spec-tree-view`, `requirement-source-view`, `requirement-browser-server` | `requirements.v1.json`, caller-owned authoring facts, overview claim extraction, explicit spec hierarchy, view options | candidate-only authoring packets, source-shape admission, lifecycle checks, explicit tree topology/source-ref admission, shared safe renderer fragments, presentation-only views | requirement meaning, extraction completeness, Markdown extraction completeness, hierarchy ownership, proof adequacy, file materialization | authoring packet, source report, spec-tree report, rendered view, or browser presentation |
-| Requirement proof binding | `requirement-bindings`, `proof-slice`, `evidence-graph`, `requirement-proof-resolver`, `requirement-proof-source-set`, `requirement-proof-view`, `spec-proof-bundle-admission` | requirement records, bindings, witness commands, source-set facts, receipt reports | graph validation, compact slices, typed compact proof contract projections, resolver projections, bundle linkage checks | test semantics, witness execution, proof freshness, merge policy | proof report, slice, lookup graph, or view |
-| Test inventory and coverage | `test-evidence-inventory`, `test-evidence-inventory --normalized-inventory`, `requirement-coverage-input-compose`, `requirement-coverage-view`, `requirement-browser-server --view coverage` | caller-owned direct or source-set test inventory, declared quality findings, requirement source, proof binding or compact proof contract, coverage universe, optional owner-invariant registry | strict inventory/source-set admission, fail-closed normalized inventory projection, deterministic coverage-view input composition from explicit facts, weak-oracle and declared-quality classification, bounded agent action guidance, requirement/test/command/owner-invariant joins, nonsemantic command-evidence classification, stable coverage failure/warning classifications, presentation-only coverage view | inventory completeness, weak-test truth, native test execution, receipt freshness, producer trust, merge policy | inventory report, normalized inventory data product, coverage-view input, coverage view, or browser presentation |
-| Selective planning | `changed-path-set`, `requirement-impact-input-compose`, `impact`, `selective-gate-plan`, `selective-gate-evidence`, `selective-gate-obligation-decision-input`, `obligation-decision` | changed paths, base/current requirement sources, base/current single-binding-per-requirement proof contracts, generated-artifact policy, local environment policy, proof-like path policy, planned receipts, obligation routes | fail-closed impact input composition, fail-closed planning, receipt comparison, bounded agent packets | git diff truth, repository scanning, command execution, producer trust, final admission | composed impact input, plan, evidence report, or obligation input |
+| Adoption and scaffolding | `adoption-contract-envelope`, `adoption-workflow-plan`, `adoption-checklist`, `adoption-doctor`, `gradual-adoption`, `gradual-adoption-bootstrap`, `gradual-adoption-guidance`, `capability-map-admission`, `pilot-admission`, `scaffold-profile-plan`, `scaffold-project-structure`, `stack-preset` | adoption intent, aggregate adoption contract envelope, checklist facts, target paths, owner routes, caller-extracted stale authority vocabulary facts, explicit pre-spec capability observations, pilot records, stack preset id | aggregate contract-envelope admission, deterministic starter plans, checklist/report admission, bounded guidance envelopes, dry-run manifests, pre-spec trust-mode admission, adoption gap and stale-authority classification, pilot shape admission | final files, final requirements, rollout policy, text extraction from files, code observation extraction, pilot truth | selected child output, plan, report, seed packet, or agent envelope |
+| Requirement source | `capability-map-admission`, `requirement-authoring-plan`, `requirement-source-admission`, `requirement-source-transition`, `spec-overview-claims`, `requirement-spec-tree`, `requirement-spec-tree-view`, `requirement-source-view`, `requirement-browser-server` | `requirements.v1.json`, caller-owned capability maps, caller-owned authoring facts, overview claim extraction, explicit spec hierarchy, view options | candidate seed admission, candidate-only authoring packets, source-shape admission, lifecycle checks, explicit tree topology/source-ref admission, shared safe renderer fragments, presentation-only views | requirement meaning, extraction completeness, Markdown extraction completeness, hierarchy ownership, proof adequacy, file materialization | capability map report, authoring packet, source report, spec-tree report, rendered view, or browser presentation |
+| Requirement proof binding | `requirement-bindings`, `binding-partition`, `proof-slice`, `evidence-graph`, `requirement-proof-resolver`, `requirement-proof-source-set`, `requirement-proof-view`, `spec-proof-bundle-admission` | requirement records, bindings, witness commands, source-set facts, receipt reports, partition policy | graph validation, binding partition projection, compact slices, typed compact proof contract projections, resolver projections, bundle linkage checks | test semantics, witness execution, proof freshness, merge policy | proof report, partition report, slice, lookup graph, or view |
+| Test inventory and coverage | `test-evidence-inventory`, `test-evidence-inventory --projection discovery-draft`, `test-evidence-inventory --normalized-inventory`, `requirement-coverage-input-compose`, `requirement-coverage-view`, `requirement-browser-server --view coverage` | caller-owned direct or source-set test inventory, caller-owned explicit test discovery facts, declared quality findings, requirement source, proof binding or compact proof contract, coverage universe, optional owner-invariant registry, aggregate coverage compose input | strict inventory/source-set admission, candidate-only discovery draft projection, fail-closed normalized inventory projection, deterministic coverage-view input composition from explicit facts, weak-oracle and declared-quality classification, bounded agent action guidance, requirement/test/command/owner-invariant joins, nonsemantic command-evidence classification, stable coverage failure/warning classifications, presentation-only coverage view | inventory completeness, weak-test truth, test discovery extraction, native test execution, receipt freshness, producer trust, merge policy | candidate inventory guidance, inventory report, normalized inventory data product, coverage-view input, coverage view, or browser presentation |
+| Selective planning | `changed-path-set`, `requirement-impact-input-compose`, `impact`, `selective-gate-plan`, `selective-gate-evidence`, `selective-gate-obligation-decision-input`, `proof-obligation-algebra`, `obligation-decision` | changed paths, base/current requirement sources, base/current single-binding-per-requirement proof contracts, generated-artifact policy, local environment policy, proof-like path policy, planned receipts, obligation routes, obligation algebra records | fail-closed impact input composition, fail-closed planning, receipt comparison, obligation algebra admission, bounded agent packets | git diff truth, repository scanning, command execution, producer trust, final admission | composed impact input, plan, evidence report, obligation algebra report, or obligation input |
 | Receipts and producers | `proof-receipt-admission`, `receipt-producer-admission`, `receipt-currentness-scope`, `receipt-trust-class`, `producer-policy-self-proof` | receipt sets, producer policy, scope/currentness facts, trust classes | receipt shape, producer/receipt compatibility, self-proof diagnostics | producer authentication, freshness policy, CI trust roots | receipt/provenance report |
 | Release and deployment | `release-authority`, `external-consumer`, `registry-consumer-proof-input-compose`, `registry-consumer`, `deployment-evidence-admission`, `completion-criteria`, `branch-authority`, `readiness-closeout` | package facts, tarball/registry facts, explicit primitive registry/install/smoke facts, deployment evidence, criteria, branch facts | artifact/channel boundary checks, registry-consumer input composition, release diagnostics, falsifiable criteria shape | package publication, registry fetch, package-manager execution, deployment, rollback, approval | composed input, release/deployment/readiness report |
-| Supply-chain and quality | release workflow, `npm run release:sbom`, `npm run self:coverage`, `npm run go:actionlint`, `npm run go:bench` | release artifacts, source workflows, specs, bindings, witness plans, explicit benchmark invocation | deterministic SBOM candidate evidence, coverage metrics, workflow lint routing, benchmark entrypoints | public-source provenance, vulnerability triage, license approval, CI run admission, release approval | SBOM, metrics report, CI signal, or benchmark output |
+| Supply-chain and quality | `self-check`, release workflow, `npm run release:sbom`, `npm run self:coverage`, `npm run go:actionlint`, `npm run go:bench` | release artifacts, source workflows, specs, bindings, witness plans, explicit benchmark invocation | deterministic self-check report shape, SBOM candidate evidence, coverage metrics, workflow lint routing, benchmark entrypoints | public-source provenance, vulnerability triage, license approval, CI run admission, release approval | self-check report, SBOM, metrics report, CI signal, or benchmark output |
 | Repository structure | `repo-profile-admission`, `workspace-manifest-facts`, `workspace-registry`, `workspace-changed-package-plan`, `workspace-shard-partition`, `typescript-public-api-surfaces`, `text-policy`, `package-runtime-dependency-admission` | explicit repo/profile facts, caller-owned manifest records, caller-owned roots, and caller-owned text file inventories | structural admission, manifest-to-workspace fact projection, workspace graph projections, TypeScript package public API checks, text policy admission, shard plans | repository freshness, git/file discovery, command policy, package manager truth | structural, fact, policy, or planning report |
 | Custom and generated artifacts | `custom-rule-boundary`, `document-lifecycle-boundary`, `rendered-artifact-freshness`, `conformance-profile`, `json-report-cli-adapter-source`, `witness-plan`, `witness-scheduler-plan` | custom rule metadata, document lifecycle records, artifact digests, profile manifests, command metadata, adapter language | boundary checks, generated-view freshness shape, deterministic adapter source generation, scheduler metadata checks | rule execution, document meaning, cache contents, CI scheduling, committed generated-source freshness | boundary report, generated source artifact, or scheduler report |
+| CLI metadata | `help` | optional command name or help flag | built-in command catalog and help text routing | command selection, semantic proof, freshness, merge policy | text help only |
 
 ## Migrating Repository Route
 
@@ -63,6 +64,8 @@ Route ambiguous modernization work through the smallest matching family:
 
 | Question | First route | Why |
 |---|---|---|
+| No specs exist and current code should be frozen as the first baseline. | `capability-map-admission` with `trustMode: "code_baseline"` | It admits caller-owned capability observations and emits bounded candidate requirement/proof-binding seeds only when scenarios have candidate ids and executable anchors. |
+| No specs exist and current code is not trusted. | `capability-map-admission` with `trustMode: "audit_from_code"` | It treats code observations as hypotheses, keeps missing anchors as owner actions, and prevents code from becoming stable requirement truth without owner review. |
 | Where should adoption start? | `adoption-workflow-plan` or `scaffold-project-structure`; use `adoption-contract-envelope` when one caller-owned aggregate adoption file already exists. | They route scenario steps and first-module starter records without scanning the repository; the aggregate route removes consumer-local root-key projection scripts without owning rollout policy. |
 | Is a candidate module ready for gradual enforcement? | `gradual-adoption-guidance` | It reports missing source, binding, witness, blocked-precondition, and advisory candidate-boundary facts by adoption mode. |
 | What still blocks an imperfect repository from enforcement? | `adoption-doctor` | It classifies caller-provided owner routes, candidate boundaries, child reports, blocked preconditions, and stale current authority vocabulary facts without scanning repository state or owning semantic boundary decisions. |
@@ -71,6 +74,7 @@ Route ambiguous modernization work through the smallest matching family:
 | Did a requirement move, split, or retire correctly? | `requirement-source-transition` | Requirement lifecycle and replacement ids belong to source transition, not proof binding. |
 | Should temporary external design or PR facts become candidate requirements? | `requirement-authoring-plan` | It packages caller-owned extracted facts into candidate-only updates and owner-review questions without writing source files, retaining design documents, or approving meaning. |
 | Does a `REQ-*` have a route to execution? | `requirement-bindings` or `proof-slice` | Proof bindings own route closure, while tests own executable behavior. |
+| Tests were discovered from an existing repository but are not yet admitted proof evidence. | `test-evidence-inventory --projection discovery-draft` | It accepts explicit caller-owned discovery facts and emits candidate-only inventory guidance with a non-strict candidate authority. Stop before treating candidates as semantic coverage; the consumer must materialize strict test inventory rows. |
 | Which checks should run for a change? | `selective-gate-plan` then `selective-gate-evidence` | Planning and receipt comparison stay separate from command execution. |
 
 ## Agent Decision Procedure
@@ -98,17 +102,18 @@ Decision tree:
 
 | State or goal | Next Proofkit route | Stop or escalation condition |
 |---|---|---|
-| No admitted spec/profile exists. | `scaffold-project-structure`, `adoption-workflow-plan`, or `stack-preset` | Stop before writing files; the consumer owns materialization, overwrite policy, and final requirement text. |
+| No admitted spec/profile exists and the caller has explicit capability observations. | `capability-map-admission`; use `trustMode: "code_baseline"` only when maintainers intentionally freeze current code, otherwise use `trustMode: "audit_from_code"`. | Stop before treating seeds as stable requirements. The consumer owns observation extraction, materialization, requirement meaning, and proof adequacy. |
+| No admitted spec/profile exists and no capability observations exist. | `scaffold-project-structure`, `adoption-workflow-plan`, or `stack-preset` | Stop before writing files; the consumer owns materialization, overwrite policy, and final requirement text. |
 | Candidate boundary is uncertain. | `adoption-doctor` or `gradual-adoption-guidance --agent-envelope` | Escalate to owner review when the boundary is advisory, ambiguous, or missing native witnesses. |
 | Temporary external design, implementation-plan, PR, code, or test observations may contain durable requirements. | `requirement-authoring-plan` | Treat output as candidate-only; stop before writing `requirements.v1.json`, retaining temporary documents, or claiming requirement meaning. |
 | Requirement records exist. | `requirement-source-admission`; use `requirement-source-transition` for lifecycle changes. | Escalate when blocking requirements lack proof routes or lifecycle replacement ids are incomplete. |
 | Humans or agents need meta/module/submodule navigation. | `requirement-spec-tree`, then `requirement-spec-tree-view` or `requirement-browser-server --view spec-tree` from the same caller-owned tree input. | Stop before inferring hierarchy from paths. The consumer owns source hierarchy; CLI/browser outputs remain presentation only and are not committed by default. |
 | Overview prose may contain durable claims. | `spec-overview-claims` | Escalate when normative claims are not tied to `REQ-*` records. |
-| Requirements have no verified proof route. | `requirement-bindings`, `witness-plan`, `proof-slice`, or `requirement-proof-resolver` | Stop before claiming proof adequacy; native witness semantics stay with the consumer. |
-| Tests or proof evidence need inventory. | `test-evidence-inventory`, optionally `requirement-coverage-input-compose`, then `requirement-coverage-view` | Compose only from explicit caller-owned facts. Use `failureClassifications[]`, `warningClassifications[]`, and `agentActionPlan[]` for machine routing. Escalate when tests are route-only, weak-oracle, unbound, or outside the caller-owned coverage universe. |
+| Requirements have no verified proof route. | `requirement-bindings`, `witness-plan` from either an explicit `witness_command_catalog` or a complete `binding_witness_plan_input`, `proof-slice`, or `requirement-proof-resolver` | Stop before claiming proof adequacy; native witness semantics stay with the consumer. A binding-derived witness plan still needs caller-owned vocabulary and conservative command policy. |
+| Tests or proof evidence need inventory. | `test-evidence-inventory`; use `--projection discovery-draft` only for explicit discovered-test facts, then `requirement-coverage-input-compose` when an aggregate `coverage_compose_input` exists, then `requirement-coverage-view` when a `coverage_view_input` exists | Compose only from explicit caller-owned facts. Discovery drafts are candidate-only and cannot close coverage. Use `failureClassifications[]`, `warningClassifications[]`, and `agentActionPlan[]` for machine routing. Escalate when tests are route-only, weak-oracle, unbound, or outside the caller-owned coverage universe. |
 | A change set is known. | `changed-path-set`, optionally `requirement-impact-input-compose`, `impact`, then `selective-gate-plan --agent-envelope` | Raw `knownChangedPaths` in `agent-route` are diagnostic only. Materialize a caller-owned `changed_path_set`, compose a caller-owned `impact_input` before `impact`, and compose a caller-owned `selective_gate_plan_input` before `selective-gate-plan`. Fail closed on unknown scope, dynamic edges, missing owner routes, unbound proof-like paths, or full-gate escalation. |
 | Does a TypeScript package public API match a caller-owned manifest? | `agent-route` with `goal: "verify_typescript_public_api"` and explicit `typescript_public_api_manifest` plus `typescript_public_api_repo_root`, then `typescript-public-api-surfaces --repo-root <caller-selected-root>` | This is an explicit filesystem scanner. Stop before guessing `repo-root`, claiming checkout freshness, package-manager truth, or merge readiness. |
-| Receipts are available for planned checks. | `selective-gate-evidence --agent-envelope`, then `obligation-decision --agent-envelope` | Escalate on missing, stale, invalid, untrusted, blocked, unavailable, or unknown-scope evidence. |
+| Receipts are available for planned checks. | `selective-gate-evidence --agent-envelope`; then materialize a caller-owned `obligation_decision_input` from the evidence output plus command routes, currentness, and trust facts; then run `selective-gate-obligation-decision-input`; then materialize the resulting `obligation_decision` input and run `obligation-decision --agent-envelope` | Escalate on missing, stale, invalid, untrusted, blocked, unavailable, or unknown-scope evidence. |
 | Human inspection is needed. | `requirement-source-view`, `requirement-proof-view`, `requirement-coverage-view`, `requirement-spec-tree-view`, or `requirement-browser-server` | `agent-route` emits browser commands as plan-only by default. Use `browserMode: "serve_local_view"` for `--serve` and `openBrowser: true` for `--open`. Rendered HTML and Markdown are presentation only unless the consumer admits a tracked artifact freshness gate. |
 | Temporary external document lifecycle facts, generated views, or rendered views need authority classification. | `document-lifecycle-boundary` | Treat lifecycle records as caller-owned metadata. Temporary design docs and implementation plans are not retained repository authority unless rewritten into deterministic specs, proof bindings, tests, package-public docs, or backlog rows. |
 | A JavaScript/TypeScript consumer needs less wrapper code. | `json-report-cli-adapter-source --language typescript` | Generated adapter source is caller-owned after materialization. The consumer still owns package pin, binary path, repo paths, local policy, and freshness proof. |

package/docs/release-process.md

@@ -47,7 +47,10 @@ The repository-owned `release:manifest` tool creates `release-manifest.json`,
 release notes, and deterministic SBOM candidate evidence from explicit package,
 registry, and release evidence. `checksums.sha256` covers distributable archive
 assets, including the SBOM file itself. `metadata-checksums.sha256` covers
-release metadata files such as `release-manifest.json` and release notes.
+public release metadata assets such as `release-manifest.json` and release
+notes. Post-create workflow evidence such as `github-release.json` and
+attestation records is retained under `retained-evidence-checksums.sha256`
+instead of being treated as public release assets.
 `sbom-subjects.sha256` covers only the package and wheel subjects described by
 that SBOM, so SBOM attestations do not make the SBOM file describe itself.
 Workflow-local scripts must not own a divergent release manifest or SBOM
@@ -148,13 +151,15 @@ The `release` workflow must:
 12. when `PROOFKIT_ENABLE_GITHUB_ATTESTATIONS=true` and the repository is
     public, publish GitHub artifact provenance and SBOM attestations for the
     checksum-bound release artifacts;
-13. create GitHub Release assets with checksums, metadata checksums, SBOM, and
-    a release manifest;
-14. retain normalized GitHub Release metadata as
+13. create GitHub Release assets with checksums, metadata checksums, release
+    notes, SBOM, and a release manifest;
+14. retain normalized GitHub Release metadata as workflow release evidence at
     `artifacts/release/github-release.json` after byte-for-byte asset
-    verification. The release manifest records GitHub Release channel data as
-    candidate/archive inventory; `github-release.json` owns post-create GitHub
-    Release facts.
+    verification, and bind it plus any attestation record with
+    `artifacts/release/retained-evidence-checksums.sha256`. The release
+    manifest records GitHub Release channel data as candidate/archive inventory;
+    `github-release.json` owns post-create GitHub Release facts only inside
+    retained workflow evidence, not as a public release asset.
 
 When `PROOFKIT_REQUIRE_VERIFIED_RELEASE_TAG=true`, the readiness gate also
 requires `GITHUB_REF_PROTECTED=true` and a GitHub-verified signed annotated tag.
@@ -183,7 +188,10 @@ The evidence must distinguish:
 - post-publish npm registry facts;
 - optional post-publish PyPI registry facts;
 - Trusted Publisher identity tuples for workflow-published npm/PyPI channels;
-- GitHub Release archive publication facts from retained `github-release.json`;
+- GitHub Release archive publication facts from retained workflow evidence
+  `github-release.json`;
+- retained workflow evidence checksum closure from
+  `retained-evidence-checksums.sha256`;
 - GitHub Release candidate asset inventory from `release-manifest.json`;
 - SBOM inventory facts;
 - optional GitHub artifact attestation facts;

package/docs/specs/proofkit-spec-proof-core/overview.md

@@ -23,8 +23,10 @@ execution receipts, and merge policy.
   commands, environment classes, conformance facts, and falsification routes
   without executing witnesses or deciding proof freshness.
 - `REQ-PROOFKIT-SPEC-003`: witness planning accepts caller-owned structured
-  command metadata, scheduler constraints, and environment classes without
-  executing commands or selecting repository policy.
+  command metadata, scheduler constraints, environment classes, and
+  binding-derived command projections only through admitted witness vocabulary
+  and conservative safe argv policy, without executing commands or selecting
+  repository policy.
 - `REQ-PROOFKIT-SPEC-004`: selective planning and selective evidence reports
   keep changed-path facts, planned commands, receipts, evidence class,
   producer-admission state, and obligation candidates explicit, keep merge
@@ -33,17 +35,18 @@ execution receipts, and merge policy.
 - `REQ-PROOFKIT-SPEC-005`: rendered proof views and agent envelopes remain
   bounded, derived presentations over structured source and never become
   canonical proof or requirement authority.
-- `REQ-PROOFKIT-SPEC-006`: test evidence inventory, proof-binding-derived
-  inventory projections, normalized inventory projections, coverage-view input
-  composition, and requirement coverage views classify or assemble
-  caller-owned test-to-requirement, command, witness, owner-invariant,
-  quality-finding, and declared-surface routes, preserve source-set entry
-  provenance, fail closed on structured selector/sourcePath drift, command-ref
-  collisions, missing requirement owners, scope widening, fabricated normalized
-  inventory, nonsemantic command evidence, and declared dead zones in
-  selected-owner or full-repository scopes, and do not treat proof routes,
-  nonsemantic command evidence, normalized projections, composed inputs, or
-  rendered views as semantic test coverage.
+- `REQ-PROOFKIT-SPEC-006`: test evidence inventory, explicit test-discovery
+  draft projections, proof-binding-derived inventory projections, normalized
+  inventory projections, coverage-view input composition, and requirement
+  coverage views classify or assemble caller-owned test-to-requirement,
+  command, witness, owner-invariant, quality-finding, and declared-surface
+  routes, preserve source-set entry provenance, fail closed on structured
+  selector/sourcePath drift, command-ref collisions, missing requirement
+  owners, scope widening, fabricated normalized inventory, non-strict
+  discovery candidate inventory, nonsemantic command evidence, and declared
+  dead zones in selected-owner or full-repository scopes, and do not treat
+  proof routes, discovery drafts, nonsemantic command evidence, normalized
+  projections, composed inputs, or rendered views as semantic test coverage.
 - `REQ-PROOFKIT-SPEC-007`: caller-owned inputs are admitted into canonical
   immutable records before any proof, policy, route, rendering, or report
   decision consumes them.
@@ -84,6 +87,11 @@ execution receipts, and merge policy.
 - `REQ-PROOFKIT-SPEC-016`: requirement source transition reports validate
   caller-provided previous and next source snapshots so lifecycle changes are
   monotonic, evidence-backed, package-boundary-stable, and repository-neutral.
+- `REQ-PROOFKIT-SPEC-017`: test evidence inventory discovery-draft reports
+  convert explicit caller-owned repository and test discovery facts into
+  candidate-only inventory guidance with strict nested test title admission,
+  source guidance, and non-claims that prevent draft guidance from becoming
+  semantic coverage.
 
 ## Non-Claims
 

package/docs/specs/proofkit-spec-proof-core/requirements.v1.json

@@ -62,7 +62,7 @@
     {
       "requirementId": "REQ-PROOFKIT-SPEC-003",
       "ownerId": "proofkit.spec-proof-core",
-      "invariant": "Witness planning accepts caller-owned structured command metadata, scheduler constraints, and environment classes without executing commands or selecting repository policy.",
+      "invariant": "Witness planning accepts caller-owned structured command metadata, scheduler constraints, environment classes, and binding-derived command projections only through admitted witness vocabulary and conservative safe argv policy, without executing commands or selecting repository policy.",
       "claimLevel": "blocking",
       "riskClass": "high",
       "proofBindingRefs": [
@@ -143,7 +143,7 @@
     {
       "requirementId": "REQ-PROOFKIT-SPEC-006",
       "ownerId": "proofkit.spec-proof-core",
-      "invariant": "Test evidence inventory, proof-binding-derived inventory projections, normalized inventory projections, coverage-view input composition, and requirement coverage views classify or assemble caller-owned test-to-requirement, command, witness, owner-invariant, quality-finding, and declared-surface routes with stable machine-readable failure and warning classifications plus bounded agent action guidance while preserving source-set entry provenance, failing closed on structured selector/sourcePath drift, command-ref collisions, missing requirement owners, scope widening, fabricated normalized inventory, nonsemantic command evidence, and declared dead zones in selected-owner or full-repository scopes, and without treating proof routes, nonsemantic command evidence, normalized projections, composed inputs, generated guidance, or rendered views as semantic test coverage.",
+      "invariant": "Test evidence inventory, explicit test-discovery draft projections, proof-binding-derived inventory projections, normalized inventory projections, coverage-view input composition, and requirement coverage views classify or assemble caller-owned test-to-requirement, command, witness, owner-invariant, quality-finding, and declared-surface routes with stable machine-readable failure and warning classifications plus bounded agent action guidance while preserving source-set entry provenance, failing closed on structured selector/sourcePath drift, command-ref collisions, missing requirement owners, scope widening, fabricated normalized inventory, non-strict discovery candidate inventory, nonsemantic command evidence, and declared dead zones in selected-owner or full-repository scopes, and without treating proof routes, discovery drafts, nonsemantic command evidence, normalized projections, composed inputs, generated guidance, or rendered views as semantic test coverage.",
       "claimLevel": "blocking",
       "riskClass": "high",
       "proofBindingRefs": [
@@ -436,6 +436,33 @@
         "requiresImpactDeclaration": true,
         "requiresProofBindingReview": true
       }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-017",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Capability map admission validates caller-owned pre-spec observations from code, tests, and documents with explicit trustMode semantics so code_baseline emits bounded candidate requirement and proof-binding seeds only when scenarios have candidate requirement ids and executable anchors, audit_from_code emits owner-review guidance for untrusted observations without failing solely on missing anchors, and neither mode scans repositories, writes files, executes witnesses, replaces requirement-authoring-plan, or makes stable requirement source truth.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-017"
+      ],
+      "nonClaims": [
+        "This requirement does not claim repository scanning, code correctness, extraction completeness, final requirement meaning, proof-binding adequacy, native witness execution, proof freshness, merge approval, release approval, rollout approval, or production readiness."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
     }
   ],
   "nonClaims": [
@@ -443,6 +470,7 @@
     "Proofkit spec-proof core requirements describe reusable infrastructure primitives only.",
     "Proofkit spec-proof core requirements do not approve document deletion or infer document meaning from Markdown prose.",
     "Proofkit spec-proof core requirements do not discover source diffs or approve requirement deletion.",
+    "Proofkit spec-proof core requirements do not make capability-map seeds stable requirement truth.",
     "Proofkit spec-proof core requirements do not prove overview-claim extractor completeness."
   ]
 }

package/docs/specs/proofkit-supply-chain-quality/overview.md

@@ -49,8 +49,9 @@ vulnerability absence, or consumer rollout safety by itself.
   semantic command evidence without claiming line coverage or exhaustive test
   semantic completeness.
 - `REQ-PROOFKIT-QUALITY-011`: CI separates the OS-independent full
-  source/package gate from macOS platform smoke so parallel runners do not
-  duplicate proof classes while preserving platform execution evidence.
+  source/package gate from macOS platform smoke, uses explicit hosted runner
+  labels instead of floating latest labels, and exposes one fail-closed
+  aggregate gate that requires every required leaf check to finish with success.
 - `REQ-PROOFKIT-QUALITY-012`: release and adoption channel identifiers use one
   canonical authority vocabulary that separates durable authority channels from
   display labels, publisher environments, statuses, and candidate evidence.

package/docs/specs/proofkit-supply-chain-quality/requirements.v1.json

@@ -142,12 +142,12 @@
     {
       "requirementId": "REQ-PROOFKIT-QUALITY-011",
       "ownerId": "proofkit.supply-chain-quality",
-      "invariant": "CI separates the OS-independent full source/package gate from the platform-specific macOS execution smoke so parallel runners do not duplicate proof classes while preserving release-relevant platform evidence.",
+      "invariant": "CI separates the OS-independent full source/package gate from the platform-specific macOS execution smoke, uses explicit hosted runner labels instead of floating latest labels, and exposes one fail-closed aggregate quality gate that requires every required leaf check to finish with success so skipped, failed, or cancelled leaf jobs cannot satisfy branch-protection evidence.",
       "claimLevel": "blocking",
       "riskClass": "medium",
       "proofBindingRefs": ["proofkit/requirement-bindings.json"],
       "nonClaimRefs": ["NC-PROOFKIT-QUALITY-011"],
-      "nonClaims": ["This requirement does not claim provider-run success, Windows support, performance budget enforcement, or release approval."],
+      "nonClaims": ["This requirement does not claim provider-run success, branch-protection settings, Windows support, performance budget enforcement, or release approval."],
       "lifecycle": {"state": "active", "replacementRequirementIds": [], "evidenceRefs": []},
       "deferral": null,
       "updatePolicy": {"reviewOwnerId": "proofkit.supply-chain-quality", "requiresImpactDeclaration": true, "requiresProofBindingReview": true}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@research-engineering/agentic-proofkit",
   "description": "Reusable proof profile, report, graph, and witness-planning primitives.",
-  "version": "0.1.146",
+  "version": "0.1.147",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,
@@ -37,7 +37,7 @@
   ],
   "scripts": {
     "build": "go run ./internal/tools/packagebuild",
-    "check": "npm run npm:version && npm run source-hygiene && npm run text-policy && npm run go:check && npm run package:artifact && npm run self:receipt && npm run self:coverage && npm run release:closeout",
+    "check": "npm run npm:version && npm run source-hygiene && npm run text-policy && npm run mermaid:check && npm run go:check && npm run package:artifact && npm run self:receipt && npm run self:coverage && npm run release:closeout",
     "go:actionlint": "go tool actionlint",
     "go:bench": "go test ./internal/kernel/admission ./internal/kernel/stablejson -run '^$' -bench . -benchmem -count=10",
     "go:check": "npm run go:fmt && npm run go:test && npm run go:vet && npm run go:staticcheck && npm run go:actionlint && npm run go:vulncheck",
@@ -57,6 +57,7 @@
     "self:coverage": "go run ./internal/tools/coveragemetrics",
     "source-hygiene": "node scripts/source-hygiene.mjs",
     "text-policy": "go run ./internal/tools/textpolicyinput | go run ./cmd/agentic-proofkit text-policy --input -",
+    "mermaid:check": "go run ./internal/tools/mermaidcheck",
     "go:staticcheck": "go tool staticcheck ./...",
     "go:vulncheck": "go tool govulncheck ./..."
   },