agentic-proofkit 0.1.91

package/docs/receipt-currentness-scope-admission-design.md

@@ -0,0 +1,103 @@
+# Receipt Currentness-Scope Admission Design
+
+Status: accepted; implemented as a generic report primitive.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Proof receipt shape and trust-class compatibility are not enough for proof
+satisfaction. A receipt can be structurally valid and emitted by an admitted
+producer while still referencing old bindings, old command digests, old
+toolchains, or a scope that no longer covers the current obligation.
+
+Formal goal:
+
+```text
+caller-provided receipt currentness checks + caller-provided scope checks
+  -> proofkit currentness/scope admission report
+  -> caller-owned obligation decision composition
+```
+
+## Authority Boundary
+
+Proofkit owns:
+
+- exact schema admission;
+- safe evidence refs, rule ids, digest grammar, and sorted unique arrays;
+- deterministic comparison of recorded/current digest checks;
+- deterministic projection of scope admission states;
+- deterministic diagnostics with `stale_receipt`, `unknown_scope`, or
+  `not_applicable` candidate-state hints.
+
+The consuming repository owns:
+
+- computing current source, binding, command, environment, dependency,
+  lockfile, toolchain, and scope digests;
+- changed-scope discovery;
+- unknown-edge analysis;
+- producer authentication;
+- time-window freshness policy;
+- witness execution;
+- merge, release, rollout, and production policy.
+
+Formal rule:
+
+```text
+Proofkit may compare supplied recorded/current facts.
+Proofkit must not discover or certify those facts.
+```
+
+## Model
+
+The input has one row per obligation receipt:
+
+1. `currentnessChecks`: caller-owned digest comparisons. Any recorded/current
+   digest mismatch emits `stale_receipt`.
+2. `scopeChecks`: caller-owned scope admission decisions. `unknown_current_scope`
+   or `not_admitted_current_scope` emits `unknown_scope`; all
+   `not_applicable` scope checks emit `not_applicable` when there is no failure.
+
+No finding emits `satisfied`. Satisfaction remains a later composition step in
+`obligation-decision` after receipt shape, producer/trust, currentness/scope,
+and caller policy facts are supplied.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Merge this into proof receipt admission | Receipt shape and current/current-scope matching answer different questions. |
+| Merge this into receipt trust-class admission | Trust compatibility does not know current repository facts or obligation applicability. |
+| Read git, files, lockfiles, or clocks inside Proofkit | Current facts and time-window policy are consuming-repository authority. |
+| Emit `satisfied` for current in-scope receipts | A current receipt still needs producer, trust, native-result, and merge-policy composition. |
+| Add an agent envelope to this command | Obligation-decision envelopes already route unsatisfied states without duplicating presentation layers. |
+
+## Proof Obligations
+
+- unit tests prove current/in-scope receipts produce no candidate-state hint;
+- unit tests prove digest drift emits `stale_receipt`;
+- unit tests prove unknown or unadmitted current scope emits `unknown_scope`;
+- unit tests prove not-applicable scope stays separate from stale receipt
+  failures;
+- selective evidence tests prove optional currentness/scope diagnostics compose
+  into obligation-decision candidate states and fail closed when unscoped or
+  missing;
+- CLI tests prove file/stdin parity and unsupported presentation flags fail
+  closed;
+- package artifact tests prove package binary, packed files, installed-bin
+  behavior, version, and published design note.
+
+## Non-Claims
+
+Receipt currentness-scope admission does not claim:
+
+- current fact discovery;
+- changed-scope discovery;
+- producer authentication;
+- time-based receipt freshness;
+- native command execution;
+- command result correctness;
+- proof satisfaction;
+- merge approval;
+- release approval;
+- rollout approval.

package/docs/receipt-producer-admission-design.md

@@ -0,0 +1,106 @@
+# Receipt Producer Admission Design
+
+Status: accepted; implemented as a generic report primitive.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Proofkit validates many caller-provided receipts, but a receipt is useful only
+when a consuming repository can distinguish an advisory local run from evidence
+created by a producer admitted for a merge obligation. This design adds a
+generic producer-admission contract without making proofkit authenticate CI,
+read logs, execute commands, or decide merge policy.
+
+Formal goal:
+
+```text
+caller-owned producer policy + caller-owned receipt metadata
+  -> proofkit producer-admission report
+  -> caller-owned merge/proof decision
+```
+
+## Authority Boundary
+
+Proofkit owns:
+
+- exact schema admission;
+- sorted deterministic normalization;
+- producer, receipt-kind, and environment-class cross-field checks;
+- advisory vs merge-satisfying producer boundary checks;
+- deterministic reports and non-claims.
+
+The consuming repository owns:
+
+- producer trust roots;
+- CI runner identity and authentication;
+- receipt freshness;
+- command execution truth;
+- merge policy;
+- rollout policy.
+
+Formal rule:
+
+```text
+Proofkit can validate that a receipt matches a declared producer policy.
+Proofkit cannot prove that the producer actually produced the receipt.
+```
+
+## Model
+
+The input has three layers:
+
+1. `receiptKinds` and `environmentClasses`: caller-owned vocabulary.
+2. `producers`: producer records with admission level, allowed receipt kinds,
+   allowed environment classes, evidence refs, owner, and non-claim.
+3. `receipts`: receipt metadata with producer id, kind, environment, status,
+   subject ref, evidence artifact refs, and whether the caller wants it to
+   satisfy a merge obligation.
+
+Admission levels:
+
+| Level | Meaning | Proofkit may validate | Proofkit must not claim |
+|---|---|---|---|
+| `advisory` | Useful for local navigation or debugging. | Receipts may reference the producer. | Merge satisfaction. |
+| `merge_satisfying` | Consumer policy says this producer may satisfy merge obligations. | Merge-obligation receipts may reference the producer if status is `passed`. | CI authenticity, freshness, or merge approval. |
+
+Receipt statuses:
+
+- `passed`
+- `failed`
+- `blocked`
+- `not_run`
+
+Only a `passed` receipt from a `merge_satisfying` producer may be marked as
+`satisfiesMergeObligation: true`.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Add producer fields directly to selective-gate evidence first | It would couple producer trust policy to one report family before the generic contract is stable. |
+| Let proofkit infer producer trust from GitHub Actions or local environment | It would require ambient CI reads and would make proofkit a trust-root owner. |
+| Treat every passed receipt as merge-satisfying | It collapses advisory local proof and admitted CI proof. |
+| Store producer policy in proofkit defaults | Producer trust is repository-specific and must stay caller-owned. |
+
+## Proof Obligations
+
+- report builder tests for valid advisory and merge-satisfying producers;
+- negative tests for unknown producers, disallowed receipt kinds, disallowed
+  environments, advisory merge claims, non-passing merge claims, duplicate ids,
+  unsafe paths, unsupported fields, and unsorted vocabulary;
+- CLI test for `receipt-producer-admission`;
+- package artifact test proving the primitive ships in the published package.
+
+## Non-Claims
+
+Receipt producer admission does not claim:
+
+- producer authentication;
+- receipt freshness;
+- command execution;
+- command result correctness;
+- CI log authority;
+- merge approval;
+- rollout approval;
+- repository policy ownership.

package/docs/receipt-trust-class-admission-design.md

@@ -0,0 +1,113 @@
+# Receipt Trust-Class Admission Design
+
+Status: accepted; implemented as a generic report primitive.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Proof receipts can have valid shape and admitted producer metadata while still
+being too weak for a specific proof obligation. A local advisory run may be
+useful for navigation, but a high-risk merge obligation may require an admitted
+CI-class receipt with provenance and retained artifacts. This design adds the
+generic compatibility layer between caller-owned proof classes and
+caller-owned receipt trust classes.
+
+Formal goal:
+
+```text
+caller-owned proof class + caller-owned receipt trust class + receipt facts
+  -> proofkit trust-class compatibility report
+  -> caller-owned merge/proof decision
+```
+
+## Authority Boundary
+
+Proofkit owns:
+
+- exact schema admission;
+- sorted deterministic normalization;
+- proof-class to minimum-trust-class compatibility checks;
+- trust-rank comparison over caller-owned ranks;
+- declared receipt-kind and environment-class compatibility;
+- declared producer-admission-level and receipt-status compatibility;
+- declared provenance and artifact-ref presence checks;
+- deterministic diagnostics with obligation-decision candidate-state hints.
+
+The consuming repository owns:
+
+- proof-class meaning and risk taxonomy;
+- trust-class definitions and rank values;
+- producer authentication;
+- receipt freshness;
+- attestation verification;
+- command execution truth;
+- merge policy;
+- rollout policy.
+
+Formal rule:
+
+```text
+Proofkit can say whether caller-provided receipt facts satisfy caller-provided
+trust-class compatibility rules.
+Proofkit cannot say that the producer is authentic, the receipt is fresh, or
+the merge obligation is satisfied.
+```
+
+## Model
+
+The input has three layers:
+
+1. `trustClasses`: caller-owned trust tiers with ranks, admitted producer
+   admission levels, admitted receipt statuses, and required provenance or
+   artifact refs.
+2. `proofClasses`: caller-owned proof/risk classes with a minimum trust class
+   and admitted receipt kind/environment vocabulary.
+3. `obligationReceipts`: caller-observed receipt facts for concrete proof
+   obligations.
+
+Findings are mapped to obligation-decision candidate states:
+
+| Finding class | Candidate state | Rationale |
+|---|---|---|
+| unknown proof class, unknown trust class, disallowed producer admission, or rank below minimum | `invalid_producer` | The receipt cannot satisfy the caller-owned trust requirements. |
+| disallowed receipt kind/environment/status, missing provenance ref, or missing artifact refs | `invalid_receipt` | The receipt facts do not match the proof-class or trust-class evidence shape. |
+
+The report does not emit `satisfied`; callers compose this compatibility report
+with freshness, producer-authentication, current-obligation, and native-test
+evidence before deciding merge satisfaction.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Merge this into proof receipt admission | Receipt shape and proof-class compatibility answer different questions. |
+| Merge this into receipt producer admission | Producer policy compatibility does not know proof-class risk requirements. |
+| Let Proofkit define global trust levels | Trust taxonomy and risk meaning are repository policy. |
+| Treat `passed` as enough for high-risk obligations | This collapses advisory local evidence and admitted merge evidence. |
+| Emit final merge decisions | Merge satisfaction requires producer auth, freshness, current-obligation matching, and consumer policy. |
+
+## Proof Obligations
+
+- unit tests prove admitted local and CI-class compatibility;
+- negative tests prove insufficient trust rank, missing provenance/artifacts,
+  disallowed receipt kind/environment/status, disallowed producer class,
+  duplicate trust ranks, unknown minimum trust class, unsafe paths, and
+  unsupported fields fail closed;
+- CLI tests prove file/stdin parity and unsupported flag rejection;
+- package artifact tests prove package binary, packed files, installed-bin
+  behavior, version, and published design note.
+
+## Non-Claims
+
+Receipt trust-class admission does not claim:
+
+- producer authentication;
+- receipt freshness;
+- attestation verification;
+- command execution;
+- command result correctness;
+- proof-class or risk-policy ownership;
+- merge approval;
+- release approval;
+- rollout approval.

package/docs/rendered-artifact-freshness-design.md

@@ -0,0 +1,55 @@
+# Rendered Artifact Freshness Design
+
+Status: implemented.
+
+Owner: `proofkit`.
+
+## Problem
+
+Rendered Markdown, rendered HTML, and generated lookup views are useful for
+humans and agents, but they are derived products. They must not become source
+truth, and a repository needs a deterministic way to prove that a tracked or
+published view still matches the structured source, renderer identity, and
+generation scope that produced it.
+
+Without a freshness boundary, a stale rendered view can look authoritative even
+when the underlying requirement records, proof bindings, or renderer changed.
+
+## Decision
+
+Add `rendered-artifact-freshness`, a deterministic report over caller-provided
+artifact freshness records.
+
+The primitive validates:
+
+- generated artifacts declare lookup-only authority;
+- rendered artifacts declare presentation-only authority;
+- source refs and current source digest are explicit;
+- renderer id, renderer version, and renderer digest are explicit;
+- generation scope id and recorded/current scope digests are explicit;
+- recorded source, renderer, generation scope, and artifact digests match current
+  caller observations;
+- artifact paths are unique, safe repository-relative paths;
+- every artifact declares freshness check refs and non-claims.
+
+## Authority Boundary
+
+Proofkit compares caller-provided digest facts and emits deterministic
+diagnostics. It does not read source files, read rendered artifacts, execute
+renderers, infer generation scope, decide source meaning, prove native witness
+execution, publish artifacts, or approve merge.
+
+## Rejected Alternatives
+
+| Alternative | Rejected Because |
+|---|---|
+| Read files and compute digests inside Proofkit. | That would make Proofkit a repository-state scanner instead of a pure reusable validator. |
+| Fold this into `document-lifecycle-boundary`. | Lifecycle authority and digest freshness are separate proof questions. |
+| Treat rendered views as canonical when hashes match. | Hash freshness proves derivation only; structured records still own meaning. |
+| Require one global generated-artifact manifest. | Owner-scoped freshness sets are more reviewable and token-efficient. |
+
+## Follow-Up
+
+Consumer repositories can feed this report into selective gates or documentation
+freshness checks. A separate caller-owned witness can compute the digests and
+provide this primitive with explicit facts.

package/docs/requirement-browser-view-design.md

@@ -0,0 +1,229 @@
+# Requirement Browser View Design
+
+Status: accepted; implemented as self-contained HTML rendering primitives,
+navigation/table controls, and local loopback presentation server.
+
+Owner: `proofkit`.
+
+## Problem
+
+Machine-admissible requirement records and proof bindings are reliable because
+they are structured. Raw structured files are poor human review surfaces,
+especially when a reviewer wants to scan by owner, claim level, proof state, or
+environment. Making Markdown or HTML the canonical source would improve human
+reading but would weaken deterministic validation.
+
+Formal inference:
+
+```text
+If prose or HTML owns requirement truth, parsing and diff semantics become weak.
+If structured records own truth, humans still need a readable projection.
+Therefore the correct boundary is structured source plus derived browser view.
+```
+
+## Decision
+
+Provide reusable browser-document rendering for requirement source and proof
+views.
+
+The browser document is:
+
+- self-contained HTML;
+- deterministic for the same view model;
+- searchable in the browser;
+- filterable by fields already admitted into the view model;
+- able to hide or show requirement IDs without changing source data;
+- able to switch between card and table presentation when table rows are
+  supplied by the view model;
+- grouped by owner, surface, or another caller-provided module key;
+- able to show a compact hierarchy of specs, owners, surfaces, and environment
+  classes;
+- able to show scenario and witness details already present in the proof view
+  model without executing tests;
+- presentation-only or lookup-only, matching the source view authority.
+
+The first implementation upgrades existing `--format html` outputs for
+`requirement-source-view` and `requirement-proof-view`. The second slice adds
+structured navigation, module grouping, optional table mode, and collapsible
+scenario/witness details. The third slice adds `requirement-browser-server`, a
+loopback presentation adapter over the same admitted view models.
+
+## Authority Boundary
+
+Proofkit owns:
+
+- browser document layout;
+- client-side search and filters over explicit view-model fields;
+- ID visibility toggling;
+- card/table presentation switching;
+- group and hierarchy navigation over explicit view-model fields;
+- collapsible details for already-admitted scenario, witness, command, and
+  environment facts;
+- HTML escaping;
+- shared renderer code used by source, structured proof, and compact proof
+  views.
+
+Proofkit does not own:
+
+- requirement meaning;
+- proof-binding adequacy;
+- witness execution;
+- local environment policy beyond caller-provided compact view input;
+- rendered-artifact freshness;
+- merge, release, rollout, or product-readiness decisions;
+- browser annotation, approval, or feedback transport.
+
+Formal rule:
+
+```text
+Structured records are authority.
+View models are deterministic projections.
+Browser HTML is presentation.
+Browser state is local convenience.
+```
+
+## Model
+
+`htmlProofkitBrowserViewDocument` receives:
+
+- title;
+- authority;
+- summary items;
+- optional hierarchy sections;
+- filter fields;
+- cards;
+- optional table columns and rows;
+- non-claims.
+
+Each card receives:
+
+- stable id;
+- title;
+- optional group id and group label;
+- already-rendered escaped body HTML;
+- normalized search text;
+- filter values keyed by declared filter fields.
+
+Each table row receives:
+
+- stable id;
+- cells keyed by declared table columns;
+- normalized search text;
+- the same filter values used by card mode.
+
+The hierarchy receives links only to anchors that are already created from
+explicit group ids. It does not infer repository topology or read files.
+
+The document contains no external assets and no network calls. It can be piped
+to a file and opened by a browser, or served later by a separate local
+presentation adapter.
+
+## Representation Rules
+
+The browser view uses progressive disclosure:
+
+1. Header and summary identify the view, authority class, counts, and local
+   environment policy.
+2. Hierarchy sections expose spec, owner, surface, and environment structure
+   without forcing a reader into every requirement.
+3. Controls allow search, field filters, card/table switching, ID visibility,
+   and details visibility.
+4. Card mode is the default reading mode for understanding one invariant at a
+   time.
+5. Table mode is the scanning mode for comparing many requirements.
+6. Scenario and witness details are collapsed by default because they are
+   useful for audit but too verbose for first-pass reading.
+
+Formal inference:
+
+```text
+If all proof detail is shown at once, the browser view becomes a wall of text.
+If proof detail is hidden permanently, auditability is weakened.
+Therefore proof detail must be available through local disclosure controls.
+```
+
+## Server Adapter
+
+A local browser server is useful, but it is a separate adapter from static HTML
+rendering. `requirement-browser-server` is implemented under these constraints:
+
+- it serves only explicit input files or explicit generated HTML supplied by the
+  caller;
+- it binds to loopback by default;
+- it rejects non-loopback hosts;
+- it does not scan the repository implicitly;
+- it does not execute native witnesses;
+- it does not compute proof freshness;
+- it does not publish artifacts;
+- it does not persist annotation feedback into source files;
+- it starts only when `--serve` is explicit;
+- it offers `--open` only with `--serve` as a local presentation convenience.
+
+The server is a presentation adapter, not a proof owner. Its proof covers
+loopback port binding, explicit input admission, no implicit repository state,
+deterministic rendered output, route handling, and shutdown behavior.
+
+## Implementation Plan
+
+1. Extend the shared browser document model with hierarchy sections, optional
+   card grouping, optional table rows, and details controls.
+2. Preserve current JSON and Markdown outputs unchanged.
+3. Render source views grouped by owner, with a specification hierarchy and a
+   table over requirement id, owner, invariant, claim level, risk, lifecycle,
+   and proof-binding refs.
+4. Render structured proof views grouped by owner, with spec-path hierarchy, a
+   table over requirement/proof fields, and collapsible scenario/test witness
+   details.
+5. Render compact proof views grouped by surface, with surface/environment
+   hierarchy, a table over requirement/surface/invariant/proof fields, and
+   collapsible positive/falsification witness details.
+6. Add renderer tests for hierarchy, table mode, grouping, escaped content, and
+   scenario/witness detail availability.
+7. Run targeted Go view tests, package artifact tests, and the full
+   package check before release or consumer pin changes.
+8. Implement `requirement-browser-server` as a loopback-only presentation
+   adapter over the same source/proof view models.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Make Markdown or HTML canonical | Reintroduces prose parsing ambiguity and weakens machine proof determinism. |
+| Track generated browser views by default | Adds drift-prone generated artifacts and token noise. |
+| Add a server before static views are stable | Server lifecycle, ports, and browser launch are a separate adapter concern and must not own rendering semantics. |
+| Add annotation and approval semantics now | Annotation feedback changes workflow authority and needs its own trust boundary. |
+| Filter over fields by parsing rendered text | Rendering would become accidental data authority; filters must use view-model fields. |
+| Render only card mode | Good for reading one requirement but poor for scanning large graphs. |
+| Render only table mode | Good for scanning but poor for understanding one invariant and its witnesses. |
+| Expand all witnesses by default | Improves audit detail but recreates the wall-of-text failure mode for large repositories. |
+
+## Proof Obligations
+
+- Source view HTML includes browser controls, filter metadata, and escaped
+  requirement text.
+- Structured proof view HTML includes browser controls and proof-state filters.
+- Compact proof view HTML includes browser controls and precondition filters.
+- HTML views include hierarchy sections when the view model supplies hierarchy
+  facts.
+- HTML views include table mode when the view model supplies table rows.
+- Proof views expose scenario and witness details without executing native
+  commands.
+- HTML rendering remains self-contained and deterministic.
+- Existing JSON and Markdown view outputs remain unchanged in authority.
+- Requirement browser server binds only to loopback hosts, serves explicit input,
+  exposes a health endpoint, rejects unsupported methods and unknown paths, and
+  shuts down cleanly.
+- Package artifact tests include the reusable browser document module and this
+  design document.
+
+## Non-Claims
+
+Requirement browser views do not claim:
+
+- source authority;
+- native witness execution;
+- receipt freshness;
+- generated-artifact freshness;
+- annotation feedback;
+- merge approval;
+- rollout approval.