agentic-proofkit 0.1.91

package/docs/selective-evidence-obligation-decision-design.md

@@ -0,0 +1,139 @@
+# Selective Evidence Obligation Decision Design
+
+## Decision
+
+Proofkit provides an API and CLI projection from selective gate evidence into
+the generic obligation-decision input model.
+
+The projection requires caller-owned command routes. It does not infer
+requirement identity, proof route identity, obligation class, producer trust,
+receipt freshness, changed scope, live availability, or merge approval.
+When supplied, it can compose caller-provided receipt currentness/scope and
+trust-class admission diagnostics into candidate states.
+
+## Problem
+
+Selective gate evidence already classifies planned command receipts as missing,
+failed, blocked, not-run, duplicate, unexpected, or passed. The generic
+obligation-decision primitive owns the closed decision lattice used by agents
+and gates.
+
+Those two layers need a narrow bridge:
+
+```text
+selective evidence command facts
+  + optional caller currentness/scope diagnostics
+  + optional caller trust-class diagnostics
+  + caller route map
+  -> obligation decision input
+```
+
+Without a bridge, each consuming repository must translate selective receipt
+diagnostics into obligation states by hand. With a bridge that infers too much,
+Proofkit would accidentally own repository-specific proof routes and producer
+trust. Therefore the bridge must be explicit-input and fail-closed.
+
+## Boundary
+
+Proofkit owns:
+
+- exact command-route admission;
+- command-scoped mapping from selective receipt facts to candidate obligation
+  states;
+- fail-closed anchoring of optional currentness/scope and trust-class
+  diagnostics to exactly one planned receipt and one caller route;
+- deterministic obligation-decision input output.
+
+The consuming repository owns:
+
+- which requirement a planned command proves;
+- the proof route reference and obligation class;
+- producer admission and authentication;
+- receipt freshness and scope classification;
+- proof-class risk policy and trust-class policy;
+- handling of unscoped selective evidence failures;
+- merge, release, rollout, and production readiness decisions.
+
+## Mapping
+
+The projection maps only command-scoped facts:
+
+| Selective evidence fact | Candidate obligation state |
+|---|---|
+| No receipt for planned command | `missing_receipt` |
+| More than one receipt for planned command | `invalid_receipt` |
+| One failed receipt | `failed` |
+| One blocked receipt | `blocked_missing_precondition` |
+| One not-run receipt | `missing_receipt` |
+| One passed receipt | `satisfied` |
+
+Optional typed diagnostics add stronger candidate states:
+
+| Optional diagnostic fact | Candidate obligation state |
+|---|---|
+| Currentness digest drift | `stale_receipt` |
+| Unknown or unadmitted current scope | `unknown_scope` |
+| Not applicable current scope | `not_applicable` |
+| Trust-class producer/rank failure | `invalid_producer` |
+| Trust-class receipt shape failure | `invalid_receipt` |
+
+The final selected state is still owned by `obligation-decision`; this
+projection only supplies candidate states.
+
+The projection refuses to map unscoped facts:
+
+- selective plan `fail_closed`;
+- preexisting evidence failures;
+- unexpected receipts;
+- producer admission failures.
+
+Those facts need an explicit caller-authored obligation-decision input or a
+future typed route that can bind them to one obligation without string parsing.
+
+## CLI Composition
+
+The CLI command is intentionally a projection step:
+
+```bash
+agentic-proofkit selective-gate-obligation-decision-input --input proofkit/selective-gate-obligation-decision.json
+```
+
+It emits deterministic `ProofkitObligationDecisionInput` and exits `0` when the
+projection is valid, even if the projected candidate states include unsatisfied
+proof states. The obligation-decision owner remains the only CLI route that
+turns those candidates into a decision report or agent envelope:
+
+```bash
+agentic-proofkit selective-gate-obligation-decision-input --input proofkit/selective-gate-obligation-decision.json \
+  | proofkit obligation-decision --input -
+
+agentic-proofkit selective-gate-obligation-decision-input --input proofkit/selective-gate-obligation-decision.json \
+  | proofkit obligation-decision --input - --agent-envelope
+```
+
+## Rejected Alternatives
+
+| Alternative | Rejection |
+|---|---|
+| Change `selective-gate-evidence` output to include decisions | That would alter existing report semantics and exit-code expectations. |
+| Infer routes from command ids | Command ids alone are not globally enough when command/source-path keys differ. |
+| Map producer-admission failures from strings | String diagnostics are not a stable typed authority boundary. |
+| Treat passed receipts as full merge satisfaction | The projection only satisfies the selective-evidence obligation scope; freshness and producer trust remain caller-owned. |
+| Compute currentness or scope inside this projection | Current facts and changed-scope analysis are caller-owned and must be supplied through typed diagnostics. |
+| Emit an obligation-decision report directly from the projection command | That would make the projection command a second report/envelope owner and would blur the exit-code boundary between valid translation and proof satisfaction. |
+
+## Proof Obligations
+
+- Unit tests prove passed, missing, failed, blocked, not-run, and duplicate
+  receipt mappings.
+- Unit tests prove route map omissions and extras fail closed.
+- Unit tests prove unscoped failures fail closed instead of being guessed.
+- Unit tests prove optional receipt currentness/scope diagnostics can add
+  `stale_receipt`, `unknown_scope`, and fail-closed anchoring.
+- Unit tests prove optional trust-class diagnostics can add
+  `invalid_producer` and `invalid_receipt` and fail-closed anchoring.
+- CLI tests prove the projection command emits only obligation-decision input,
+  preserves stdin/file parity, and rejects `--agent-envelope`.
+- Package artifact tests prove the public API remains root-exported and packed.
+- Full package checks prove the additive projection does not regress existing
+  report behavior.

package/docs/selective-evidence-producer-admission-design.md

@@ -0,0 +1,106 @@
+# Selective Evidence Producer Admission Design
+
+Status: accepted; implemented as an optional selective-evidence strengthening
+layer.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Selective gate evidence already verifies that every planned command has one
+caller-provided receipt. That proves coverage of the plan, but it does not
+prove that a passed receipt is compatible with an admitted producer. This design
+adds an optional bridge from selective command receipts to producer-admission
+receipts without making proofkit read CI, authenticate runners, execute
+commands, or decide merge approval.
+
+Formal goal:
+
+```text
+selective gate plan + command receipts + optional producer-admission input
+  -> proofkit selective evidence report
+  -> caller-owned merge/proof decision
+```
+
+## Authority Boundary
+
+Proofkit owns:
+
+- exact schema admission for the optional producer-admission field;
+- deterministic rebuilding of the producer-admission report from caller input;
+- cross-checks from passed command receipts to producer-admission receipt ids;
+- evidence-ref, status, subject, and merge-satisfaction consistency checks;
+- deterministic report diagnostics and non-claims.
+
+The consuming repository owns:
+
+- producer trust roots;
+- CI runner identity and authentication;
+- receipt freshness;
+- native command execution;
+- whether selective evidence is required for merge;
+- rollout or deployment approval.
+
+Formal rule:
+
+```text
+Without producerAdmission, selective evidence keeps legacy behavior.
+With producerAdmission, passed planned receipts must bind to merge-satisfying
+producer-admission receipts.
+```
+
+## Model
+
+`ProofkitSelectiveGateCommandReceipt` may declare `producerReceiptId`. The id
+points at a receipt inside the caller-provided `producerAdmission` input.
+
+When `producerAdmission` is absent:
+
+- existing selective evidence behavior is preserved;
+- the producer-admission rule is skipped;
+- the report still does not claim producer authenticity or freshness.
+
+When `producerAdmission` is present:
+
+1. Proofkit rebuilds the producer-admission report from the supplied input.
+2. Producer-admission failures become selective-evidence failures.
+3. Every passed receipt for a planned command must declare `producerReceiptId`.
+4. The referenced producer-admission receipt must exist.
+5. The referenced producer-admission receipt must match command id, status,
+   evidence ref, and merge-satisfaction intent.
+
+The command id is the generic subject ref because it is the stable planned
+command identity available to every consumer. Consumers that need richer subject
+identity must encode that in their own producer policy or command ids.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Accept only a producer-admission report | The report lacks full receipt metadata, so it cannot bind a selective receipt to a producer receipt without a second hidden source. |
+| Make producer admission mandatory | Existing consumers can have valid selective coverage before adopting producer policy. Mandatory admission would be a breaking change. |
+| Trust any passed selective receipt | It preserves legacy behavior but cannot distinguish local advisory proof from admitted merge proof. |
+| Let proofkit infer producer ids from CI environment | It would turn proofkit into a CI trust-root owner and require ambient state reads. |
+
+## Proof Obligations
+
+- existing selective-evidence tests must pass without `producerAdmission`;
+- positive test for passed receipts bound to merge-satisfying producer receipts;
+- negative tests for missing producer receipt ids, non-merge-satisfying producer
+  receipts, evidence-ref drift, and producer-admission failures;
+- CLI tests must keep deterministic report behavior because the CLI passes the
+  input through the same report builder;
+- package checks must prove the published artifact still exposes the selective
+  evidence and producer admission contracts.
+
+## Non-Claims
+
+Selective evidence with producer admission does not claim:
+
+- CI runner authentication;
+- receipt freshness;
+- command execution;
+- command result correctness beyond caller-provided status metadata;
+- merge approval;
+- rollout approval;
+- repository policy ownership.

package/docs/selective-evidence-receipt-trust-class-design.md

@@ -0,0 +1,100 @@
+# Selective Evidence Receipt Trust-Class Projection Design
+
+Status: accepted; implemented as a generic projection bridge.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Selective gate evidence already maps command-scoped receipts into obligation
+decision records. Receipt trust-class admission separately validates whether a
+caller-provided receipt is strong enough for a caller-provided proof class. This
+design connects those two primitives without making selective evidence own risk
+policy, trust policy, producer authentication, freshness, or merge approval.
+
+Formal goal:
+
+```text
+selective evidence + command routes + optional receipt trust-class report input
+  -> obligation-decision input with invalid_producer/invalid_receipt candidates
+  -> caller-owned merge/proof decision
+```
+
+## Boundary
+
+Proofkit owns:
+
+- exact optional input admission;
+- exact coverage checks between command-route obligations with one selective
+  receipt and trust-class diagnostics;
+- route and receipt alignment checks for requirement id, proof-route ref,
+  producer receipt id, and receipt status;
+- fail-closed rejection of unscoped or missing trust-class diagnostics;
+- deterministic projection of `invalid_producer` and `invalid_receipt`
+  candidate states into obligation-decision inputs;
+- deterministic evidence-ref aggregation from selective receipts and trust
+  diagnostics.
+
+The consuming repository owns:
+
+- proof-class meaning and risk taxonomy;
+- trust-class values and rank policy;
+- producer authentication;
+- receipt freshness;
+- attestation verification;
+- command execution truth;
+- merge, release, and rollout policy.
+
+## Invariants
+
+- If `receiptTrustClassAdmission` is omitted, existing selective evidence
+  projection semantics remain unchanged.
+- If `receiptTrustClassAdmission` is supplied, every projected command route
+  obligation that has exactly one selective receipt must have exactly one
+  trust-class diagnostic.
+- Trust-class diagnostics outside projected command-route obligations, or for
+  obligations without exactly one selective receipt, fail closed.
+- Trust-class diagnostics must match the route `requirementId` and
+  `proofRouteRef`.
+- Trust-class diagnostics must match the selective receipt `producerReceiptId`
+  and `status`.
+- Selective receipts without `producerReceiptId` cannot be anchored to
+  trust-class diagnostics and fail closed when trust-class projection is
+  requested.
+- Trust-class findings do not replace selective receipt findings; candidate
+  states are combined and ordered by the closed obligation-decision lattice.
+- A passed selective receipt can still project `invalid_producer` or
+  `invalid_receipt` when the caller-provided trust-class report says it is too
+  weak for the obligation risk class.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Add trust classes to the selective gate evidence report | Trust compatibility is obligation/risk-level, not command coverage. |
+| Duplicate trust-class validation inside selective evidence | That would create two owners for the same compatibility rule. |
+| Treat trust-class failures as unscoped report failures | That would lose per-obligation decision states. |
+| Make trust-class admission mandatory | Existing consumers may not have adopted receipt trust classes yet. |
+
+## Proof Obligations
+
+- tests prove omitted trust-class input preserves existing projection behavior;
+- tests prove low-trust evidence projects `invalid_producer` even when the
+  command receipt passed;
+- tests prove missing provenance/artifacts project `invalid_receipt`;
+- tests prove missing, unscoped, route-mismatched, receipt-mismatched, and
+  unanchored trust-class diagnostics fail closed.
+
+## Non-Claims
+
+Selective evidence receipt trust-class projection does not claim:
+
+- producer authentication;
+- receipt freshness;
+- attestation verification;
+- risk-policy ownership;
+- trust-policy ownership;
+- native command execution;
+- merge approval;
+- release approval;
+- rollout approval.

package/docs/selective-gate-evidence-agent-envelope-design.md

@@ -0,0 +1,100 @@
+# Selective Gate Evidence Agent Envelope Design
+
+Status: accepted; implemented as an internal builder and opt-in CLI projection.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Selective gate evidence reports classify whether planned commands have
+caller-provided receipts. Agents need a bounded failure packet that answers:
+which commands are missing evidence, which receipts failed or were blocked, and
+which producer-admission metadata needs caller review.
+This design adds `buildProofkitSelectiveGateEvidenceAgentEnvelope` and
+`selective-gate-evidence --agent-envelope` as bounded projections over an
+already-built selective evidence result.
+
+Formal goal:
+
+```text
+caller-owned selective evidence report
+  -> bounded agent guidance envelope
+  -> caller-owned rerun, repair, or receipt-admission action
+```
+
+## Authority Boundary
+
+Proofkit owns:
+
+- deterministic envelope construction from the selective evidence result;
+- a reusable internal builder owned by the selective gate evidence module;
+- bounded command refs for missing, failed, not-run, and blocked evidence;
+- required receipt-class refs for missing receipts;
+- receipt-artifact refs for failed, not-run, and blocked receipts;
+- blocked preconditions for blocked receipts and producer-admission failures;
+- invalid-input envelope reporting for parsed agent-envelope failures.
+
+The consuming repository owns:
+
+- native command execution;
+- receipt production and storage;
+- producer admission policy;
+- CI authenticity and freshness;
+- proof adequacy, merge approval, and rollout decisions.
+
+Formal rule:
+
+```text
+The evidence envelope routes remediation.
+The evidence report owns observed metadata classification.
+Caller-owned commands and receipts own proof execution facts.
+```
+
+## Model
+
+The projection emits:
+
+- one evidence-report context ref with a stable hash;
+- one selective-plan hash context ref;
+- command refs for actionable command gaps;
+- required receipt-class refs for missing receipts;
+- receipt-artifact refs for failed, not-run, and blocked receipts;
+- route and verify actions;
+- blocked preconditions for blocked receipts and producer-admission failures;
+- omitted records when failure lists exceed envelope limits.
+
+The envelope does not include passed receipts by default because passed receipts
+are already non-actionable for remediation. Consumers that need a full receipt
+audit should inspect the selective evidence report or producer-admission report.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Emit every receipt into the envelope | Passed receipts can dominate token budget without adding remediation value. |
+| Treat failed receipts as required receipt classes | Failed/not-run/blocked receipts are observed artifacts, not missing classes. |
+| Resolve producer-admission failures automatically | Producer policy and trust roots are consumer-owned. |
+| Add merge recommendations | Proofkit does not own merge policy or proof adequacy. |
+
+## Proof Obligations
+
+- module test for `buildProofkitSelectiveGateEvidenceAgentEnvelope`;
+- CLI test for `selective-gate-evidence --agent-envelope`;
+- unsupported command test proving unrelated report families still reject
+  `--agent-envelope`;
+- invalid-input envelope test for selective evidence parsing failures;
+- full package check proving ordinary selective evidence output is unchanged
+  without `--agent-envelope`.
+
+## Non-Claims
+
+Selective gate evidence envelopes do not claim:
+
+- native command execution;
+- receipt freshness;
+- producer authentication;
+- proof adequacy;
+- changed-path completeness;
+- merge approval;
+- rollout approval;
+- repository policy ownership.

package/docs/selective-gate-plan-agent-envelope-design.md

@@ -0,0 +1,95 @@
+# Selective Gate Plan Agent Envelope Design
+
+Status: accepted; implemented as an internal builder and opt-in CLI projection.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Selective gate plans can be large. Agents need the smallest actionable packet:
+what changed, which commands are required, which receipts are expected, and
+what was omitted. This design adds
+`buildProofkitSelectiveGatePlanAgentEnvelope` and
+`selective-gate-plan --agent-envelope` as bounded projections over an
+already-built plan.
+
+Formal goal:
+
+```text
+caller-owned selective gate plan
+  -> bounded agent guidance envelope
+  -> caller-owned command execution and receipts
+```
+
+## Authority Boundary
+
+Proofkit owns:
+
+- deterministic envelope construction from the caller-provided plan;
+- a reusable internal builder owned by the selective gate plan module;
+- bounded context, command, receipt-class, omission, and action records;
+- source plan hash and source state projection;
+- invalid-input envelope reporting for parsed agent-envelope failures.
+
+The consuming repository owns:
+
+- changed-path completeness;
+- command registry truth;
+- native command execution;
+- receipt production and producer admission;
+- proof freshness;
+- merge or rollout decisions.
+
+Formal rule:
+
+```text
+The envelope routes agent work.
+The selective gate plan owns planned command metadata.
+Native tools and caller receipts own observed execution.
+```
+
+## Model
+
+The projection emits:
+
+- one source-plan context ref with a stable hash;
+- bounded changed-path, generated-artifact, and touched-witness context refs;
+- bounded command refs from `requiredCommands`;
+- required receipt-class refs for emitted commands;
+- route and verify action items;
+- omitted records when context or commands exceed envelope limits;
+- blocked preconditions for fail-closed plan failures.
+
+The envelope is intentionally not a complete proof ledger. When omitted records
+exist, the caller must inspect the full plan or run a wider/full gate.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Emit the full selective plan as an agent packet | It duplicates large input and defeats token efficiency. |
+| Execute required commands from the envelope command | It would violate the CLI boundary and turn proofkit into a runner. |
+| Treat required receipt classes as receipt artifacts | Required classes describe needed evidence; they are not observed receipts. |
+| Add envelopes for every report family now | Each family needs a separate mapping proof to avoid generic but misleading actions. |
+
+## Proof Obligations
+
+- module test for `buildProofkitSelectiveGatePlanAgentEnvelope`;
+- CLI test for `selective-gate-plan --agent-envelope`;
+- unsupported command test proving other report families still reject
+  `--agent-envelope`;
+- invalid-input envelope test for selective plan parsing failures;
+- full package check proving the projection does not break existing CLI output.
+
+## Non-Claims
+
+Selective gate plan envelopes do not claim:
+
+- command execution;
+- command pass evidence;
+- receipt freshness;
+- producer admission;
+- changed-path completeness;
+- merge approval;
+- rollout approval;
+- repository policy ownership.

package/docs/selective-planner-edge-coverage-design.md

@@ -0,0 +1,89 @@
+# Selective Planner Edge Coverage Design
+
+Status: maintained design note for selective planner soundness.
+
+Owner: `proofkit`.
+
+## Problem
+
+Selective plans are safe only when every relevant changed edge is either covered
+by a planned proof route or fails closed. A wide command is not a valid fallback
+by name alone: it must declare coverage for the edge class that caused
+escalation.
+
+Without typed edge coverage, a consumer can provide a full-workspace command
+while Proofkit cannot prove whether that command covers dynamic imports,
+generated-source drift, reverse dependencies, command/environment registry
+changes, or other unknown edge classes.
+
+## Decision
+
+`buildProofkitSelectiveGatePlan` accepts caller-provided `unknownEdges` and
+caller-provided `fallbackCoverage` declarations.
+
+Proofkit validates and reports:
+
+- stable edge classes;
+- each unknown edge path and reason;
+- which declared fallback command ids cover each edge;
+- `fail_closed` when an unknown edge has no fallback that covers its edge class.
+
+Proofkit adds a fallback command to `requiredCommands` only when the fallback
+declares the unknown edge class. A full workspace command without matching edge
+coverage is not treated as proof coverage.
+
+## Authority
+
+Proofkit owns:
+
+- generic edge-class vocabulary;
+- fallback coverage declaration shape;
+- deterministic normalization and sorting;
+- fail-closed diagnostics for uncovered unknown edges.
+
+The consuming repository owns:
+
+- discovering changed edges;
+- deciding whether an edge is unknown or relevant;
+- mapping real repository topology and dependency closure;
+- declaring which command covers which edge class;
+- executing fallback commands;
+- producer admission, receipt freshness, and merge policy.
+
+## Non-Claims
+
+This design does not make Proofkit a repository scanner, dependency graph
+resolver, command executor, CI authority, receipt freshness engine, or merge
+approval authority.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Treat `fullWorkspaceCommand` as universal fallback | Unsafe because the command does not prove coverage for the edge class that caused escalation. |
+| Parse failure strings to infer `unknown_scope` | Brittle and not machine-stable enough for agent routing or obligation decisions. |
+| Implement repository graph scanning in Proofkit | Violates Proofkit's generic boundary and duplicates consumer-owned topology policy. |
+
+## Invariants
+
+1. Unknown edge coverage is explicit by edge class.
+2. An uncovered unknown edge makes the plan `fail_closed`.
+3. Covered unknown edges add only their declared fallback commands.
+4. Fallback command ids are unique inside one plan input.
+5. Evidence admission rejects a covered unknown edge when the referenced
+   fallback declaration is missing or no longer covers the edge class.
+6. Plan evidence hashes include edge/fallback diagnostics.
+7. Agent envelopes may route unknown-edge context but do not prove fallback
+   execution.
+
+## Proof Gates
+
+Required closeout for this surface:
+
+```bash
+go test ./...
+go vet ./...
+npm run build
+npm run check
+git diff --check
+```

package/docs/spec-overview-claim-boundary-design.md

@@ -0,0 +1,50 @@
+# Spec Overview Claim Boundary Design
+
+Status: implemented.
+
+Owner: `proofkit`.
+
+## Problem
+
+Human spec overviews are useful for context, examples, diagrams, and rationale,
+but durable requirement meaning must live in structured `REQ-*` records. If an
+overview sentence says a system `must`, `shall`, `guarantees`, or `always` does
+something without citing a `REQ-*`, the overview becomes a second source of
+truth.
+
+## Decision
+
+Add `spec-overview-claims`, a deterministic report over caller-provided overview
+claim extraction facts.
+
+The primitive validates:
+
+- `overviewPath` equals `specPackagePath/overview.md`;
+- `requirementsPath` equals `specPackagePath/requirements.v1.json`;
+- every durable overview claim cites at least one known `REQ-*`;
+- every cited `REQ-*` is declared by the caller-provided requirement id set;
+- non-durable claims do not carry requirement citations;
+- extraction refs, line digests, detected markers, rationale, and non-claims are
+  explicit and deterministic.
+
+## Authority Boundary
+
+Proofkit validates extracted claim facts. It does not read Markdown, detect
+claims from source text, prove extractor completeness, decide whether a cited
+`REQ-*` semantically supports the sentence, validate requirement source records,
+or approve merge.
+
+## Rejected Alternatives
+
+| Alternative | Rejected Because |
+|---|---|
+| Fold this into requirement-source admission. | Structured requirement records and overview prose extraction have different authority boundaries. |
+| Parse Markdown inside Proofkit. | Consumer repositories own extraction witnesses, ignored-region policy, and Markdown provenance. |
+| Allow overview durable claims without citations when wording is obvious. | That reintroduces duplicate durable truth and breaks fail-closed traceability. |
+| Let non-durable lines cite `REQ-*`. | It makes examples and rationale look normative and blurs the citation contract. |
+
+## Follow-Up
+
+Consumer repositories should pair this primitive with a native extractor witness
+that turns `overview.md` into claim records, including ignored regions and line
+digests. Proofkit validates the resulting facts only.