@research-engineering/agentic-proofkit 0.1.136

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

@@ -0,0 +1,98 @@
+# Proofkit Spec-Proof Core Spec
+
+This spec owns Proofkit's reusable spec-to-proof primitives: requirement source
+admission, requirement proof bindings, witness planning, selective proof
+planning, selective evidence admission, rendered proof views, and bounded agent
+envelopes.
+
+It is intentionally infrastructure-only. Consumers provide requirement
+sentences, proof bindings, changed-path facts, command policy, native witnesses,
+execution receipts, and merge policy.
+
+## Requirements
+
+- `REQ-PROOFKIT-SPEC-001`: requirement source admission validates structured
+  `REQ-*` records and source-package shape without owning requirement meaning
+  or scanning overview prose as authority.
+- `REQ-PROOFKIT-SPEC-002`: requirement proof binding reports validate
+  caller-owned requirement-to-witness mappings, require compact scenarios to be
+  admitted `surface_id::stable_anchor` identities, require compact witness
+  selectors to use `repo/path::stable_anchor` identities, admit caller-owned
+  source-set fragments and selected-source resolver projections, and derive
+  typed compact proof contract projections for surfaces, scenarios, witnesses,
+  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.
+- `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
+  approval consumer-owned, and fail closed for unknown or unmatched proof
+  inputs.
+- `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-007`: caller-owned inputs are admitted into canonical
+  immutable records before any proof, policy, route, rendering, or report
+  decision consumes them.
+- `REQ-PROOFKIT-SPEC-008`: requirement spec tree admission validates explicit
+  caller-owned spec hierarchy, source-reference modes, digest facts, overlay
+  refs, deterministic output, and tree topology without scanning repositories,
+  reading sources, rendering views, or owning requirement/proof semantics.
+- `REQ-PROOFKIT-SPEC-009`: requirement spec tree views render admitted
+  caller-owned hierarchy through shared safe browser document fragments,
+  deterministic CLI JSON, Markdown, HTML, explicit output paths, and loopback
+  browser serving without accepting caller-owned raw HTML or making rendered
+  output authoritative.
+- `REQ-PROOFKIT-SPEC-010`: requirement impact input composition converts
+  caller-owned base/current requirement sources, single-current-binding compact
+  proof contracts, changed-path facts, generated-artifact policy, local
+  environment policy, and proof-like path policy into a direct `impact` input
+  without scanning repositories, executing witnesses, or becoming a second
+  impact evaluator.
+- `REQ-PROOFKIT-SPEC-011`: adoption contract envelope admission validates a
+  complete caller-owned aggregate adoption envelope, selects one child route
+  through orthogonal CLI flags, and delegates to existing child command
+  contracts without becoming a second adoption readiness policy.
+- `REQ-PROOFKIT-SPEC-012`: requirement authoring plans package caller-provided
+  design, implementation, PR, code, test, and clarification facts into
+  candidate-only requirement updates, delegate structural checks to requirement
+  source admission and transition, and keep owner review/materialization outside
+  Proofkit.
+- `REQ-PROOFKIT-SPEC-013`: repeated cross-command proof vocabulary has one
+  private owner for proof and selective-edge state while command-local and
+  caller-owned vocabularies stay outside the shared owner.
+- `REQ-PROOFKIT-SPEC-014`: document lifecycle boundary reports classify
+  caller-owned document lifecycle metadata so temporary, historical, generated,
+  rendered, router, work-ledger, and durable documents cannot silently retain
+  the wrong authority role.
+- `REQ-PROOFKIT-SPEC-015`: spec overview claim reports validate
+  caller-provided overview claim extraction facts so durable overview claims
+  cite known requirement records and non-durable claims remain non-normative.
+- `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.
+
+## Non-Claims
+
+- This spec does not claim consumer repository adoption.
+- This spec does not claim native witness execution.
+- This spec does not authenticate receipt producers or compute proof freshness.
+- This spec does not approve merge, release, registry publication, rollout, or
+  production readiness.
+- This spec does not approve document deletion or infer document meaning from
+  Markdown prose.
+- This spec does not prove overview-claim extractor completeness.
+- This spec does not discover source diffs or approve requirement deletion.

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

@@ -0,0 +1,448 @@
+{
+  "schemaVersion": 1,
+  "sourceId": "proofkit.spec-proof-core.requirements",
+  "specPackagePath": "docs/specs/proofkit-spec-proof-core",
+  "overviewPath": "docs/specs/proofkit-spec-proof-core/overview.md",
+  "requirementsPath": "docs/specs/proofkit-spec-proof-core/requirements.v1.json",
+  "requirements": [
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-001",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Requirement source admission validates structured REQ-* records and source-package shape without owning requirement meaning or scanning overview prose as authority.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-001"
+      ],
+      "nonClaims": [
+        "This requirement does not claim product requirement meaning, proof freshness, native witness execution, or overview prose authority."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-002",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Requirement proof binding reports validate caller-owned requirement-to-witness mappings, require compact scenarios to use admitted surface_id::stable_anchor identities, require compact witness selectors to use admitted repo/path::stable_anchor identities, admit caller-owned source-set fragments and selected-source resolver projections, and derive typed compact proof contract projections for surfaces, scenarios, witnesses, commands, environment classes, conformance facts, and falsification routes without executing witnesses or deciding proof freshness.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-002"
+      ],
+      "nonClaims": [
+        "This requirement does not claim native witness pass evidence, proof freshness, receipt authenticity, or merge approval."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    },
+    {
+      "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.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-003"
+      ],
+      "nonClaims": [
+        "This requirement does not claim command execution, CI scheduling authority, credential approval, or repository-specific command policy."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-004",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Selective planning and selective evidence reports keep changed-path facts, planned commands, receipts, evidence class, producer-admission state, and obligation candidates explicit, keep merge approval consumer-owned, and fail closed for unknown or unmatched proof inputs.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-004"
+      ],
+      "nonClaims": [
+        "This requirement does not claim changed-path completeness, command success, receipt authenticity, proof freshness, or approval to skip caller-owned gates."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-005",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Rendered proof views and agent envelopes remain bounded, derived presentations over structured source and never become canonical proof or requirement authority.",
+      "claimLevel": "blocking",
+      "riskClass": "medium",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-005"
+      ],
+      "nonClaims": [
+        "This requirement does not claim generated view authority, full graph context emission, proof freshness, or agent edit approval."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    },
+    {
+      "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 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, or rendered views as semantic test coverage.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-006"
+      ],
+      "nonClaims": [
+        "This requirement does not claim repository scanning, native test execution, proof freshness, receipt authenticity, merge approval, or global coverage completeness outside the caller-provided universe."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-007",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Proofkit commands admit caller-owned inputs into canonical immutable records before proof, policy, route, rendering, or report decisions consume them.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-007"
+      ],
+      "nonClaims": [
+        "This requirement does not claim consumer repository input authenticity, producer trust, native witness execution, proof freshness, merge approval, or mutable source control outside caller-provided Proofkit inputs."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-008",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Requirement spec tree admission validates caller-owned meta, module, submodule, and capability spec hierarchy, source-reference modes, digest facts, overlay refs, deterministic output, and tree topology without scanning repositories, reading requirement sources, rendering views, or owning requirement/proof semantics.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-008"
+      ],
+      "nonClaims": [
+        "This requirement does not claim repository scanning, requirement meaning, source freshness computation, rendered output authority, native witness execution, proof adequacy, 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
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-009",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Requirement spec tree views render admitted caller-owned spec-tree hierarchy through shared safe browser document fragments, deterministic CLI JSON, Markdown, HTML, explicit output paths, and loopback browser serving without accepting caller-owned raw HTML or making rendered output authoritative.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-009"
+      ],
+      "nonClaims": [
+        "This requirement does not claim repository scanning, source freshness computation from files, requirement meaning, native witness execution, committed generated HTML, 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
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-010",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Requirement impact input composition converts caller-owned base and current requirement sources, single-current-binding compact proof contracts, changed-path facts, generated-artifact policy, local environment policy, and proof-like path policy into a direct impact command input while preserving downstream impact semantics and without scanning repositories, executing witnesses, deciding freshness, or becoming a second impact evaluator.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-010"
+      ],
+      "nonClaims": [
+        "This requirement does not claim changed-path completeness, generated-artifact verifier completeness, native witness execution, proof freshness, receipt authenticity, 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
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-011",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Adoption contract envelope admission validates a complete caller-owned aggregate adoption envelope, selects one child adoption, bootstrap, guidance, workflow, or pilot route through orthogonal CLI flags, and delegates to existing child command contracts without scanning repositories, writing files, executing witnesses, or creating a second adoption readiness policy.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-011"
+      ],
+      "nonClaims": [
+        "This requirement does not claim consumer file materialization, native witness execution, proof freshness, receipt authenticity, 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
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-012",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Requirement authoring plans admit caller-provided design, implementation, pull request, code, test, and clarification facts into candidate-only requirement updates, delegate candidate source and lifecycle checks to requirement-source admission and transition, and emit owner-review plans without reading repositories, writing files, inferring requirement meaning, or approving promotion.",
+      "claimLevel": "blocking",
+      "riskClass": "high",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-012"
+      ],
+      "nonClaims": [
+        "This requirement does not claim extraction completeness, requirement meaning, file materialization, 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
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-013",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Repeated cross-command proof vocabulary has one private owner for receipt statuses, merge-satisfaction classes, obligation classes, obligation decision states, selective unknown-edge classes, and selective unknown-edge coverage states, while command-local and caller-owned vocabularies remain outside the shared owner.",
+      "claimLevel": "blocking",
+      "riskClass": "medium",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-013"
+      ],
+      "nonClaims": [
+        "This requirement does not claim public SDK vocabulary, consumer policy ownership, merge approval, receipt freshness, producer authentication, native witness execution, or ownership of one-command local vocabularies."
+      ],
+      "lifecycle": {
+        "state": "active",
+        "replacementRequirementIds": [],
+        "evidenceRefs": []
+      },
+      "deferral": null,
+      "updatePolicy": {
+        "reviewOwnerId": "proofkit.spec-proof-core",
+        "requiresImpactDeclaration": true,
+        "requiresProofBindingReview": true
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-014",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Document lifecycle boundary reports validate caller-owned lifecycle metadata so active PR-local temporary documents, retained temporary documents, archived documents, generated lookup documents, rendered views, primary routers, work ledgers, and current durable documents keep the admitted authority role, routing role, source refs, freshness refs, forbidden payload boundaries, and non-claims for their lifecycle state without reading Markdown, approving deletion, proving generated freshness, or deciding document meaning.",
+      "claimLevel": "blocking",
+      "riskClass": "medium",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-014"
+      ],
+      "nonClaims": [
+        "This requirement does not claim Markdown semantic extraction, generated artifact freshness, document deletion approval, 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
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-015",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Spec overview claim reports validate caller-provided overview claim extraction facts so overviewPath and requirementsPath match the spec package, durable overview claims cite at least one known requirement id, non-durable overview claims carry no requirement citations, and extraction refs, line digests, detected markers, rationale, and non-claims are explicit without reading Markdown, proving extractor completeness, validating requirement source records, deciding semantic support, or approving merge.",
+      "claimLevel": "blocking",
+      "riskClass": "medium",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-015"
+      ],
+      "nonClaims": [
+        "This requirement does not claim Markdown reading, claim extractor completeness, requirement source validity, semantic support between overview prose and cited requirements, 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
+      }
+    },
+    {
+      "requirementId": "REQ-PROOFKIT-SPEC-016",
+      "ownerId": "proofkit.spec-proof-core",
+      "invariant": "Requirement source transition reports validate caller-provided previous and next requirement source snapshots so both snapshots pass requirement source admission, both snapshots describe the same sourceId, specPackagePath, overviewPath, and requirementsPath, previous durable requirement records remain present, new requirements start active, terminal removed or superseded states and terminal superseded replacement sets do not change, deprecation, removal, supersession, and reactivation carry new lifecycle evidence, replacement targets are active in the next admitted source, and prior lifecycle evidence and replacement refs are preserved without discovering diffs, proving replacement semantic equivalence, executing witnesses, computing freshness, approving deletion, or approving merge.",
+      "claimLevel": "blocking",
+      "riskClass": "medium",
+      "proofBindingRefs": [
+        "proofkit/requirement-bindings.json"
+      ],
+      "nonClaimRefs": [
+        "NC-PROOFKIT-SPEC-016"
+      ],
+      "nonClaims": [
+        "This requirement does not claim git diff discovery, replacement semantic equivalence, native witness execution, receipt freshness, requirement deletion approval, 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": [
+    "Consumers still own requirement meaning, command policy, native witness execution, receipts, CI admission, and rollout decisions.",
+    "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 prove overview-claim extractor completeness."
+  ]
+}

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

@@ -0,0 +1,95 @@
+# Proofkit Supply-Chain And Quality Spec
+
+This spec owns Proofkit's reusable supply-chain, release-provenance, CLI
+contract, property-test, performance-evidence, security-signal, and coverage
+metrics requirements.
+
+It is intentionally evidence-focused. Native tests, release workflows, advisory
+security workflows, and generated evidence files are distinct proof classes.
+No single green check proves release readiness, public-source provenance,
+vulnerability absence, or consumer rollout safety by itself.
+
+## Requirements
+
+- `REQ-PROOFKIT-QUALITY-001`: release artifacts carry deterministic digest
+  inventory and optional GitHub artifact attestations without claiming
+  public-source provenance before a public-source tag release exists.
+- `REQ-PROOFKIT-QUALITY-002`: release evidence includes a deterministic SBOM
+  for package, wheel, binary, and Go module inventory without claiming
+  vulnerability absence or license approval.
+- `REQ-PROOFKIT-QUALITY-003`: pure parser and canonicalization boundaries have
+  fuzz/property tests that prove no-panic and round-trip stability without
+  fuzzing side-effecting CLI or filesystem flows.
+- `REQ-PROOFKIT-QUALITY-004`: public CLI ABI has a small golden corpus and
+  canonical ABI hash covering command topology, exit code, stdout/stderr
+  channel discipline, JSON parseability, stable public diagnostics, and
+  descriptor/contract/help parity without making private descriptors public API.
+- `REQ-PROOFKIT-QUALITY-005`: CodeQL workflow source is admitted as an
+  independent semantic security analysis signal for Go source without replacing
+  native Go static gates.
+- `REQ-PROOFKIT-QUALITY-006`: OSV workflow source is admitted as an advisory
+  multi-ecosystem dependency signal without replacing `govulncheck`
+  reachable-code evidence.
+- `REQ-PROOFKIT-QUALITY-007`: Scorecard workflow source is admitted as an
+  advisory repository hygiene signal without claiming branch protection or
+  provider settings that the repository cannot prove from source.
+- `REQ-PROOFKIT-QUALITY-008`: GitHub Actions workflow syntax and expression
+  semantics are checked by actionlint in the local package gate.
+- `REQ-PROOFKIT-QUALITY-009`: performance-sensitive parser and serializer
+  paths expose benchmark entrypoints without making wall-clock budgets a
+  required PR gate before stable baselines exist.
+- `REQ-PROOFKIT-QUALITY-010`: coverage metrics report requirement, binding,
+  witness, CLI inventory linkage, and descriptor-owned command semantic-route
+  coverage from admitted test-evidence-inventory rows, failing closed on
+  explicit requirement/proof linkage dead zones, failed command-route
+  inventory admission, command semantic routes without owner-declared proof
+  identities, route-index-derived semantic proof identities, direct app
+  semantic routes outside the command-scoped app test, package-level semantic
+  routes outside the descriptor-owned command package, and missing matching
+  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.
+- `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.
+- `REQ-PROOFKIT-QUALITY-013`: self-hosting workflow package-gate evidence is
+  checked by a typed workflow oracle instead of text search, proving the
+  package gate is reachable, exact, advisory, success-gated for always-running
+  downstream jobs and required evidence-publication steps, and ordered before
+  evidence publication.
+- `REQ-PROOFKIT-QUALITY-014`: release authority consumers compare downstream
+  policy against the admitted typed release-authority projection and admitted
+  report digest instead of rereading caller-owned raw `releaseAuthorityInput`
+  fields after validation.
+- `REQ-PROOFKIT-QUALITY-015`: the package gate includes an admitted release
+  closeout completion-criteria report so unit tests alone cannot satisfy
+  release closeout.
+- `REQ-PROOFKIT-QUALITY-016`: release platform targets use one private owner
+  that projects platform suffixes, Go build targets, npm OS/CPU metadata,
+  package tar entries, Python wheel tags, PyPI candidate completeness, and
+  SBOM binary subjects without becoming public API.
+- `REQ-PROOFKIT-QUALITY-017`: report-visible secret-shaped JSON traversal
+  uses one private kernel owner for deterministic paths and finding kinds while
+  command packages only map findings to their local report policy.
+- `REQ-PROOFKIT-QUALITY-018`: release metadata retains a Trusted Publisher
+  identity tuple with the exact version-tag workflow ref for workflow-published
+  npm and PyPI channels and release closeout rejects publication claims without
+  that tuple.
+- `REQ-PROOFKIT-QUALITY-019`: installed package smoke proof verifies one
+  successful JSON report command and one failed-report command from the
+  package-managed binary, including report identity, state, exit code, stdout,
+  stderr discipline, and exact explicit-input counts despite an unlisted
+  poison file in the consumer working directory.
+
+## Non-Claims
+
+- This spec does not claim public-source provenance until a public-source tag
+  release records admitted attestation evidence.
+- This spec does not claim absence of vulnerabilities, license approval,
+  branch-protection enforcement, consumer adoption, merge approval, release
+  approval, rollout approval, or production readiness.
+- This spec does not make advisory security scans substitute for native tests,
+  parser fuzz/property tests, CLI ABI tests, release manifest generation, or
+  registry identity evidence.