agentic-proofkit 0.1.91

package/docs/producer-policy-self-proof-design.md

@@ -0,0 +1,142 @@
+# Producer Policy Self-Proof Design
+
+Status: accepted; implemented as a generic report primitive.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Producer admission policy is a protected repository contract. A pull request
+that expands that policy must not satisfy its own merge obligations with
+receipts that become merge-satisfying only because of the same policy change.
+This design adds a generic self-proof guard for that cycle.
+
+Formal goal:
+
+```text
+caller-owned producer-policy change facts
+  + caller-owned merge-obligation receipt refs
+  -> proofkit producer-policy self-proof report
+  -> caller-owned invalid_producer / merge decision
+```
+
+## Authority Boundary
+
+Proofkit owns:
+
+- exact input schema admission;
+- digest grammar for caller-provided policy digests;
+- safe repository-relative policy and evidence refs;
+- deterministic tuple-level self-proof detection;
+- deterministic reports and boundary non-claims.
+
+The consuming repository owns:
+
+- producer authentication;
+- producer-policy protection and ownership;
+- policy-diff discovery;
+- receipt freshness;
+- current obligation matching;
+- migration exception approval;
+- merge, release, rollout, and production policy.
+
+Formal rule:
+
+```text
+Proofkit can detect that a merge-obligation receipt uses a producer tuple newly
+admitted by the same policy change.
+Proofkit cannot decide whether the policy change is allowed to merge.
+```
+
+## Model
+
+The guard input describes one producer-policy change:
+
+1. Policy identity, protected policy surface refs, and baseline/proposed/change
+   digests.
+2. Admission changes as explicit trust tuples:
+   `producerId + producerClass + proofClass + receiptKind + environmentClass
+   + provenanceRuleRef + artifactRetentionRuleRef + toAdmissionLevel`.
+3. Receipt refs that cite an admitted proof-receipt record by ref and digest and
+   that the caller says are used for the same policy change's merge obligations.
+4. Structured non-claim refs that point at caller-owned proof-scope or
+   spec-owned non-claim IDs instead of making this report a second semantic
+   non-claim owner.
+
+The self-proof unit is a tuple, not only a producer id:
+
+```text
+producerId
+  | producerClass
+  | proofClass
+  | receiptKind
+  | environmentClass
+  | provenanceRuleRef
+  | artifactRetentionRuleRef
+  | admissionLevel
+```
+
+This is required because a producer can be preexisting and safe for one proof
+class while newly admitted for another proof class or environment. Promotions
+from `advisory` to `merge_satisfying` are newly admitted merge-satisfying
+tuples. Expanding receipt kind or environment class can also create a newly
+admitted merge-satisfying tuple. Relaxing provenance or artifact-retention
+requirements for the same producer, proof class, receipt kind, and environment
+also creates a newly admitted trust tuple.
+
+## Failure Rules
+
+The report fails when:
+
+- an unchanged policy digest declares admission changes;
+- an `add_producer` change starts from an existing admission level;
+- a `promote_to_merge_satisfying` change does not target `merge_satisfying`;
+- a `promote_to_merge_satisfying` change does not change admission level;
+- a merge-obligation receipt is not `passed`;
+- a merge-obligation receipt is not declared `merge_satisfying`;
+- a merge-obligation receipt uses a tuple newly admitted by the same
+  `policyChangeId`.
+
+`usedForPolicyChangeId` must match the report `policyChangeId`; mismatches are
+schema admission errors, not soft diagnostics.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Detect only newly admitted producer ids | Too coarse: the same producer may have old safe tuples and new unsafe tuples. |
+| Detect only producer, receipt kind, environment, and admission level | Too weak: provenance and artifact-retention relaxations can newly admit trust for the same visible tuple. |
+| Put self-proof detection into proof receipt admission | Receipt shape validation and producer-policy change validation are different failure classes. |
+| Put self-proof detection into receipt producer admission | Matching receipts to current policy is not the same as proving that a policy change did not admit its own evidence. |
+| Let proofkit discover policy diffs from git | That would make proofkit an implicit repository scanner and policy-diff owner. |
+| Add migration-exception approval to the report | Migration approval is repository-owned policy, not a generic proofkit decision. |
+
+## Proof Obligations
+
+- report builder test for preexisting merge-satisfying tuple success;
+- negative tests for newly added producer tuple, advisory-to-merge promotion,
+  receipt-kind/environment tuple expansion, and provenance or retention
+  relaxation;
+- positive tests for newly admitted tuples that are not used for merge
+  obligations and old tuples from a producer that also gets a new tuple;
+- negative tests for non-passed or advisory merge-obligation receipts;
+- schema tests for malformed digests, unsafe paths, duplicate ids, unsupported
+  fields, and mismatched `policyChangeId`;
+- CLI test for `producer-policy-self-proof`;
+- package artifact test proving the primitive ships in the published package.
+
+## Non-Claims
+
+Producer policy self-proof does not claim:
+
+- producer authentication;
+- receipt freshness;
+- policy digest provenance;
+- policy-diff discovery;
+- command execution;
+- CI state;
+- migration exception approval;
+- merge approval;
+- release approval;
+- rollout approval;
+- production readiness.

package/docs/project-structure-agent-envelope-design.md

@@ -0,0 +1,121 @@
+# Project Structure Agent Envelope Design
+
+## Decision
+
+Proofkit provides an opt-in project-structure scaffold agent envelope that
+projects a project-structure scaffold result into a bounded work packet for a
+coding agent.
+
+## Problem
+
+`scaffold-project-structure` emits a dry-run materialization manifest with
+starter JSON payloads and caller-owned content gaps. That is the correct
+authority surface for human review, but it is too large and too payload-heavy
+for the first agent routing step.
+
+The missing invariant is:
+
+```text
+project-structure scaffold result
+  -> bounded agent envelope
+  -> caller-owned file materialization and native proof
+```
+
+## Boundary
+
+Proofkit owns:
+
+- deterministic projection from a project-structure scaffold result;
+- context refs for candidate file paths without embedding file payload bodies;
+- action items for review, materialization, caller-authored content, and
+  verification;
+- deterministic command refs for next proofkit command text already emitted by
+  the scaffold;
+- omitted-count records when the manifest is larger than the envelope bounds;
+- non-claims denying file writes, payload transport, native execution,
+  freshness, merge, release, and rollout authority.
+
+The consuming repository owns:
+
+- whether to create, overwrite, merge, or ignore candidate files;
+- final module specification content;
+- final repository profile content and repository profile admission;
+- native witness execution and receipt production;
+- CI freshness, merge, enforcement, release, and rollout decisions.
+
+Formal rule:
+
+```text
+The scaffold manifest carries payload review data.
+The scaffold agent envelope carries bounded routing data.
+The consuming repository owns materialization and proof.
+```
+
+## Model
+
+The projection emits:
+
+- `envelopeId = <scaffold report id>.agent-envelope`;
+- source report identity from the project-structure scaffold report;
+- explicit `bounds` covering context refs, action items, command refs, omitted
+  records, receipt refs, and omitted counts;
+- context refs for each candidate file path up to a bounded limit;
+- route questions for what changed, what proves it, and who owns it;
+- clarification questions for caller-owned content and review preconditions;
+- command refs for the scaffold manifest next command text up to a bounded
+  limit;
+- action items for route, candidate-change, bind, and verify phases;
+- blocked preconditions for each `caller_content_required` file and each
+  starter repository-profile draft that still requires caller review;
+- omissions for truncated context refs or command refs;
+- empty receipt refs, because the scaffold step has not executed native
+  witnesses;
+- no starter file payload bodies.
+
+Payload files remain available only in the full scaffold result. The agent
+envelope deliberately names them as paths and content-hash refs so an agent can
+route work without loading every generated payload into context.
+Content-hash refs are metadata for review and drift detection only; they are
+not recoverable payload transport and do not prove file existence or caller
+approval.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Put full starter payloads into the envelope | Payload bodies defeat the token-efficiency purpose of agent envelopes. |
+| Make `scaffold-project-structure` write files | File writes require consumer-owned overwrite and review policy. |
+| Infer `argv` by splitting command text | Shell text is display/routing metadata unless the source primitive owns structured argv. |
+| Reuse the bootstrap envelope | Project-structure scaffolds include repo-profile scaffold and workflow inputs, so bootstrap-only roles lose owner context. |
+| Emit an envelope for every manifest by default | Machine callers may need the full result; envelope mode must be explicit. |
+
+## Proof Obligations
+
+- Unit tests prove envelope bounds, context refs, command refs, omitted counts,
+  caller-content blocked preconditions, and payload-body exclusion.
+- CLI tests prove `scaffold-project-structure --agent-envelope`, file input and
+  stdin parity, and invalid-input envelope behavior.
+- CLI tests prove unrelated materialization flags remain fail-closed.
+- Package artifact tests prove the package binary, packed CLI smoke path, and
+  design note are shipped to outside consumers.
+- Full package check proves ordinary scaffold output remains unchanged without
+  `--agent-envelope`.
+
+## Non-Claims
+
+Project-structure scaffold agent envelopes do not claim:
+
+- repository-state discovery;
+- file writes;
+- starter payload transport;
+- file existence;
+- overwrite safety;
+- final specification or repository profile content;
+- native witness execution;
+- command pass evidence;
+- receipt authenticity or freshness;
+- merge approval;
+- enforcement promotion approval;
+- release approval;
+- rollout approval;
+- consumer policy authority.

package/docs/project-structure-scaffold-design.md

@@ -0,0 +1,89 @@
+# Project Structure Scaffold Design
+
+## Decision
+
+Proofkit provides a deterministic `scaffold-project-structure` primitive that
+composes existing starter primitives into one dry-run review packet for a new
+or first-module consumer adoption.
+
+## Problem
+
+Consumers can already run `scaffold-profile-plan`, `gradual-adoption-bootstrap`,
+`adoption-workflow-plan`, and materialization manifest projections separately.
+That is correct for ownership, but inconvenient as the first adoption step:
+agents must assemble the same starter file set by hand and can drift path
+relationships between the repository profile, proof binding, bootstrap input,
+and workflow input.
+
+The missing invariant is:
+
+```text
+caller-owned project scaffold input
+  -> existing proofkit starter primitives
+  -> one dry-run file review packet
+  -> caller-owned materialization and native proof
+```
+
+## Boundary
+
+Proofkit owns:
+
+- deterministic composition of existing starter primitives;
+- path consistency checks across the profile scaffold, bootstrap input, and
+  workflow input;
+- stable JSON starter payloads and `sha256:` content refs;
+- explicit caller-owned file gaps;
+- non-claims denying scanning, writes, native execution, freshness, merge,
+  release, and rollout authority.
+
+The consuming repository owns:
+
+- final file writes and overwrite policy;
+- final module specification text;
+- final repository profile review;
+- native witness execution;
+- receipt production and producer admission;
+- CI freshness, merge, enforcement, release, and rollout decisions.
+
+## Chosen Model
+
+The primitive accepts one explicit input containing:
+
+- the target paths for the scaffold input, bootstrap input, and workflow input;
+- a `repoProfileScaffold` input;
+- a `bootstrap` input;
+- workflow metadata and non-claims.
+
+It builds:
+
+- a repository profile scaffold plan;
+- a bootstrap report and bootstrap materialization manifest;
+- an adoption workflow input and workflow plan;
+- one project-structure materialization manifest containing only dry-run file
+  entries.
+
+The manifest may include starter JSON payloads for inputs and generated
+starter records. Module specifications remain `caller_content_required`.
+Repository profile content is a starter draft from the profile scaffold plan
+and remains caller-reviewed, not authoritative.
+
+## Rejected Alternatives
+
+| Alternative | Rejection |
+|---|---|
+| Add file writes | File materialization requires conflict and overwrite policy owned by the consumer repository. |
+| Fold this into bootstrap | Bootstrap owns one module's adoption payloads; it does not own repo-profile authoring or workflow input composition. |
+| Fold this into workflow plan | Workflow plans own command routing, not payload construction or materialization review. |
+| Embed product specification text | Product/module specs carry durable repository meaning and must be authored or reviewed by the consuming repository. |
+| Infer paths from repository layout | Ambient discovery would make Proofkit a repository-state authority. |
+
+## Proof Obligations
+
+- Unit tests prove deterministic file entries, source report refs, stable
+  hashes, caller-owned gaps, path mismatch failures, and non-claims.
+- CLI tests prove file input and stdin parity, stable JSON, and unsafe path
+  rejection.
+- Package artifact tests prove the package binary, CLI smoke path, and design note
+  are shipped to outside consumers.
+- Full package check proves existing profile, bootstrap, workflow, and package
+  artifact behavior remains compatible.

package/docs/proof-obligation-algebra-design.md

@@ -0,0 +1,108 @@
+# Proof Obligation Algebra Design
+
+## Decision
+
+Proofkit provides a `proof-obligation-algebra` primitive that validates
+caller-provided proof obligation graph shape.
+
+The primitive owns generic obligation operator grammar only:
+
+```text
+atomic | all_of | any_of | conditional | deferred | waived_until
+```
+
+It does not execute witnesses, authenticate receipts, compute freshness, decide
+proof satisfaction, or approve merge, release, rollout, or production readiness.
+
+## Problem
+
+Requirement proof bindings can describe direct witness routes, but large
+requirements often need explicit composition:
+
+```text
+requirement
+  -> all required proof routes
+  -> one of several admitted alternatives
+  -> conditionally applicable proof routes
+  -> deferred or waived proof obligations that must stay visible
+```
+
+If this composition stays in prose, agents and CI cannot reliably distinguish a
+real proof route from an admitted deferral, a waiver, a missing child, or a
+cross-requirement dependency.
+
+The reusable layer is therefore:
+
+```text
+caller-owned obligation graph -> algebra admission -> deterministic graph report
+```
+
+## Boundary
+
+Proofkit owns:
+
+- exact input admission for obligation algebra records;
+- operator-specific shape checks;
+- cycle detection;
+- unknown-child rejection;
+- cross-requirement child checks that require explicit delegation refs;
+- rejection of `deferred` or `waived_until` children as proof-bearing routes;
+- deterministic report output, root ids, graph depth, and diagnostics.
+
+The consuming repository owns:
+
+- requirement meaning;
+- proof-route content and adequacy;
+- deferral and waiver policy;
+- evidence authenticity;
+- receipt freshness;
+- native witness execution;
+- merge, release, rollout, and production readiness decisions.
+
+## Operator Rules
+
+| Operator | Required | Forbidden |
+|---|---|---|
+| `atomic` | one or more `proofRouteRefs` | children, conditions, delegation refs, expiry, review condition |
+| `all_of` | at least two `childObligationIds` | direct proof route refs, conditions, expiry, review condition |
+| `any_of` | at least two `childObligationIds` | direct proof route refs, conditions, expiry, review condition |
+| `conditional` | one or more children and one or more `conditionRefs` | direct proof route refs, expiry, review condition |
+| `deferred` | evidence refs, expiry ref, review-condition ref | direct proof route refs, children, conditions, delegation refs |
+| `waived_until` | evidence refs, expiry ref, review-condition ref | direct proof route refs, children, conditions, delegation refs |
+
+`deferred` and `waived_until` require both `expiryRef` and
+`reviewConditionRef`. This is a generic boundedness minimum, not a consumer
+deferral policy: expiry bounds time, while review condition bounds the event
+that reopens the obligation. Consumers still own the policy that decides whether
+the deferral or waiver is acceptable.
+
+## Invariants
+
+- Every obligation id is stable, sorted, and unique.
+- Every child obligation id must resolve inside the same caller-provided graph.
+- Cycles fail the report.
+- Cross-requirement child composition requires explicit `delegationRefs`.
+- `deferred` and `waived_until` obligations are visible graph nodes, not
+  proof-bearing children.
+- Input order and host locale do not affect output order or stable JSON.
+
+## Rejected Alternatives
+
+| Alternative | Rejection |
+|---|---|
+| Extend `requirement-bindings` in the same batch | The existing flat binding contract is already consumed by other reports; an additive primitive avoids behavior drift. |
+| Put algebra into `obligation-decision` | That would mix pre-evidence proof structure with observed evidence state classification. |
+| Let consumers express composition in prose only | Prose cannot fail closed on cycles, missing children, or deferred proof counted as proof. |
+| Execute child proof routes from this primitive | Proofkit CLI must emit deterministic reports and plans only; native execution remains consumer-owned. |
+| Let deferred obligations satisfy `any_of` alternatives | Deferral and waiver visibility is useful, but they are not proof-bearing routes. |
+
+## Proof Obligations
+
+- Unit tests prove admitted graph normalization, root detection, graph depth,
+  transitive child projection, deterministic JSON, and non-claim boundaries.
+- Negative tests prove unary composites, non-proof-bearing proof children,
+  cross-requirement children without delegation, cycles, unknown children, and
+  malformed records fail closed.
+- CLI tests prove file/stdin parity and unsupported presentation flags.
+- Package artifact tests prove package binary, packed files, installed-bin behavior,
+  version, and published design note.

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

@@ -0,0 +1,108 @@
+# Proof Receipt Admission Design
+
+Status: accepted; implemented as a generic report primitive.
+
+Owner: `proofkit`.
+
+## Purpose
+
+A proof command describes intended work. A command exit code is not enough to
+decide whether a proof obligation is satisfied because it does not bind the run
+to a proof plan, requirement binding, command digest, environment digest,
+witness selectors, toolchain state, runner, producer, provenance, or artifact
+hashes. This design adds a generic receipt-shape admission contract before
+producer trust, freshness, and obligation-decision layers.
+
+Formal goal:
+
+```text
+caller-owned observed receipt records
+  -> proofkit proof-receipt admission report
+  -> caller-owned producer admission, freshness, and obligation decision
+```
+
+## Authority Boundary
+
+Proofkit owns:
+
+- exact receipt schema admission;
+- digest grammar;
+- repository-relative evidence and artifact refs;
+- timestamp ordering;
+- status, exit-code, artifact, provenance-ref, and non-claim consistency;
+- deterministic report output and boundary non-claims.
+
+The consuming repository owns:
+
+- producer authentication and attestation verification;
+- producer admission policy;
+- receipt freshness;
+- command execution truth;
+- current-obligation matching;
+- merge, release, rollout, and production policy.
+
+Formal rule:
+
+```text
+Proofkit can admit receipt shape and provenance fields.
+Proofkit cannot prove that the producer is authentic, fresh, or merge-satisfying.
+```
+
+## Model
+
+Each receipt records:
+
+- receipt identity and kind;
+- source revision;
+- proof plan id;
+- proof-binding, command, environment, precondition, witness-selector,
+  toolchain, dependency, and lockfile digests;
+- environment class;
+- witness selectors;
+- runner identity and class;
+- producer id and producer admission class;
+- optional provenance ref;
+- start and finish timestamps;
+- normalized status and exit code;
+- evidence refs;
+- artifact refs with kind, path, and sha256;
+- proof-scope non-claims.
+
+`merge_satisfying` receipts must include a provenance ref. This is only a
+shape requirement: proofkit does not authenticate that provenance. Advisory
+local receipts may omit provenance refs because consumers may still use them
+for navigation and debugging.
+
+## Rejected Alternatives
+
+| Alternative | Rejection reason |
+|---|---|
+| Extend selective-gate evidence receipts directly | It would couple the generic receipt contract to one planner family and duplicate fields later. |
+| Put producer authentication in this primitive | It would make proofkit a trust-root owner instead of a reusable validator. |
+| Treat producer admission and receipt shape as one report | It would blur independent failure classes: malformed receipt vs non-admitted producer. |
+| Compute freshness in receipt admission | Freshness depends on caller-owned invalidation rules, current obligations, dependency state, and producer policy. |
+
+## Proof Obligations
+
+- report builder test for deterministic valid receipt admission;
+- negative tests for duplicate ids, malformed digests, unsafe paths, unsupported
+  fields, unsorted selectors, timestamp order, exit/status mismatch, missing
+  artifacts, missing blocked non-claims, and merge-satisfying receipt without
+  provenance;
+- CLI test for `proof-receipt-admission`;
+- package artifact test proving the primitive ships in the published package.
+
+## Non-Claims
+
+Proof receipt admission does not claim:
+
+- producer authentication;
+- producer policy admission;
+- receipt freshness;
+- native command execution;
+- command result correctness;
+- current-obligation matching;
+- merge approval;
+- release approval;
+- rollout approval;
+- production readiness.

package/docs/proofkit-contract-map.md

@@ -0,0 +1,55 @@
+# Proofkit Contract Map
+
+Status: maintained consumer routing surface.
+
+Owner: `proofkit`.
+
+## Purpose
+
+This map helps consuming repositories choose the smallest Proofkit CLI command
+or JSON contract without loading the full README or source tree. It is not an
+exhaustive schema reference. The canonical command inventory is
+`proofkit/cli-contract.v1.json`.
+
+Formal rule:
+
+```text
+Contract map routes humans and agents.
+CLI/JSON records own cross-language behavior.
+Go packages implement the shipped executable.
+Consumer repositories own product truth, local policy, and native witnesses.
+```
+
+## Families
+
+| Family | Main commands | Caller provides | Proofkit owns | Consumer owns | Output authority |
+|---|---|---|---|---|---|
+| Adoption and scaffolding | `adoption-workflow-plan`, `gradual-adoption`, `gradual-adoption-bootstrap`, `gradual-adoption-guidance`, `scaffold-profile-plan`, `scaffold-project-structure`, `stack-preset` | adoption intent, target paths, owner routes, stack preset id | deterministic starter plans, bounded guidance envelopes, dry-run manifests | final files, final requirements, rollout policy | plan or agent envelope |
+| Requirement source | `requirement-source-admission`, `requirement-source-transition`, `spec-overview-claims`, `requirement-source-view`, `requirement-browser-server` | `requirements.v1.json`, overview claim extraction, view options | source-shape admission, lifecycle checks, presentation-only views | requirement meaning, Markdown extraction completeness, proof adequacy | source report or rendered view |
+| 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, resolver projections, bundle linkage checks | test semantics, witness execution, proof freshness, merge policy | proof report, slice, lookup graph, or view |
+| Selective planning | `changed-path-set`, `impact`, `selective-gate-plan`, `selective-gate-evidence`, `selective-gate-obligation-decision-input`, `obligation-decision` | changed paths, impact facts, planned receipts, obligation routes | fail-closed planning, receipt comparison, bounded agent packets | git diff truth, command execution, producer trust, final admission | plan, evidence 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`, `deployment-evidence-admission`, `completion-criteria`, `branch-authority`, `readiness-closeout` | package facts, tarball/registry facts, deployment evidence, criteria, branch facts | artifact/channel boundary checks, release diagnostics, falsifiable criteria shape | package publication, registry fetch, deployment, rollback, approval | release/deployment/readiness report |
+| Repository structure | `repo-profile-admission`, `workspace-registry`, `workspace-changed-package-plan`, `workspace-shard-partition`, `typescript-public-api-surfaces`, `package-runtime-dependency-admission` | explicit repo/profile facts and caller-owned roots | structural admission, workspace graph projections, TypeScript package public API checks, shard plans | repository freshness, command policy, package manager truth | structural or planning report |
+| Custom and generated artifacts | `custom-rule-boundary`, `document-lifecycle-boundary`, `rendered-artifact-freshness`, `conformance-profile`, `witness-plan`, `witness-scheduler-plan` | custom rule metadata, document lifecycle records, artifact digests, profile manifests, command metadata | boundary checks, generated-view freshness shape, scheduler metadata checks | rule execution, document meaning, cache contents, CI scheduling | boundary or scheduler report |
+
+## Routing Rules
+
+1. Start from `proofkit/cli-contract.v1.json` when a machine needs the exact
+   command, flags, input mode, or output mode.
+2. Start from this map when a human or agent only needs the correct command
+   family.
+3. Use agent-envelope output only when a coding agent needs bounded context;
+   do not expand whole proof graphs into chat.
+4. Treat generated views and rendered HTML as presentation only. They never
+   replace the structured source record.
+5. Escalate to the consuming repository's owner policy whenever Proofkit reports
+   unknown scope, missing receipts, unavailable preconditions, or command
+   execution requirements.
+
+## Omitted Surfaces
+
+This map intentionally omits exhaustive per-field schema documentation,
+generated view instances, generated graph instances, receipt instances, and
+language-specific wrapper APIs. Those surfaces are either generated on demand,
+owned by the caller, or derived from the CLI/JSON contracts.