agentic-proofkit 0.1.91

package/docs/agent-guidance-envelope-design.md

@@ -0,0 +1,550 @@
+# Agent Guidance Envelope Design
+
+Status: accepted; implemented for the generic envelope model and bounded
+report-specific `--agent-envelope` projections. The v1 input contract admits
+legacy packets that omit boundedness and receipt-boundary fields, but the
+normalized output always emits the target envelope fields.
+
+Owner: `proofkit`.
+
+## Purpose
+
+Proofkit emits deterministic reports, proof slices, witness plans, rendered
+views, and adoption guidance. The reusable improvement is a common
+agent-facing envelope that gives coding agents the smallest safe work packet:
+what to load, what question to answer, what command to run, what remains a
+non-claim, and when to ask a human instead of guessing.
+
+Formal goal:
+
+```text
+consumer-owned evidence + proofkit generic report
+  -> deterministic agent guidance envelope
+  -> bounded agent action
+  -> caller-owned native proof
+```
+
+The envelope improves agent usability without making proofkit an agent
+orchestrator, repository scanner, policy owner, or proof freshness authority.
+That sentence is a boundary rule, not a capability limit. Proofkit may still be
+the reusable "one dependency" toolkit for parsing, validation, rendering,
+scaffolding plans, migration plans, selective proof planning, and agent
+instructions. The forbidden part is hidden authority: proofkit must not infer
+repository truth from ambient state, silently execute native witnesses, approve
+edits, decide merge policy, or treat generated guidance as proof freshness.
+
+## Architecture Fit
+
+Agent guidance envelopes are one output mode of proofkit's reference
+infrastructure role. Proofkit receives caller-owned structured records and
+reports, then projects bounded work packets for agents. The consuming repository
+still owns requirement meaning, proof bindings, command and environment policy,
+native witness execution, receipts, and rollout decisions.
+
+The intended flow is:
+
+```text
+consumer structured records
+  -> proofkit validation and reports
+  -> bounded slice
+  -> agent guidance envelope
+  -> caller-owned native proof and receipt
+```
+
+A slice is the selected proof subgraph relevant to a task. An envelope is that
+slice plus context refs, commands, blocked preconditions, fanout class,
+non-claims, budgets, omitted counts, cost contract, escalation rule, and
+clarification questions. The envelope must be generated on demand; it is not a routine
+tracked repository artifact and never becomes
+canonical proof source.
+
+## Swiss-Army-Knife Boundary
+
+The intended proofkit product shape is broad but still generic:
+
+```text
+agentic-proofkit parses caller-provided contracts
+  -> validates schemas and generic invariants
+  -> renders human views
+  -> builds selective plans and agent envelopes
+  -> emits scaffolding or migration instructions
+  -> caller materializes repository-specific files and runs native witnesses
+```
+
+Proofkit may provide CLI commands that generate starter structures, templates,
+repo-local script plans, migration plans, rendered views, and agent work
+packets. Those commands must be deterministic, explicit-input driven, and
+safe by default. If a future materializer writes files, it must be a separate
+explicit mode with preview/dry-run semantics and caller-provided target paths;
+the generated files become consumer-owned repository truth only after caller
+review and commit.
+
+Formal boundary:
+
+```text
+Proofkit may guide, validate, render, scaffold, and plan.
+The consuming repository approves, materializes, executes, and owns truth.
+```
+
+## Acceptance Criteria
+
+Every proofkit improvement in this track must satisfy all criteria below.
+
+1. Genericity: the mechanism must be reusable across consumer repositories and
+   must not encode product row ids, local paths, CI policy, deployment policy,
+   harness names, or rollout decisions.
+2. Determinism: identical input must produce byte-stable output after stable
+   JSON serialization.
+3. Progressive disclosure: output must prefer exact context refs and compact
+   next actions over broad prose.
+4. Agent safety: output must distinguish actions, commands, clarification
+   questions, blockers, invalid inputs, and non-claims.
+5. Non-authority: proofkit must never convert guidance, scaffolding, rendering,
+   or planning into native witness execution, proof freshness, product
+   approval, rollout approval, merge approval, or edit approval.
+6. Fail-closed shape: malformed guidance input, duplicate ids, unknown phases,
+   missing owners, or unbound commands must be visible as report failures.
+7. Token efficiency: the envelope must reference large evidence surfaces by
+   path, id, selector, hash, or rule id instead of embedding copied evidence.
+8. Backward compatibility: existing report commands must keep their current
+   JSON shape unless a caller explicitly asks for the envelope.
+9. Human reviewability: every generated action must answer why it exists, who
+   owns the decision, what proof can falsify it, and what is not claimed.
+10. Runtime independence: proof and envelope commands may build reports,
+    envelopes, and plans only; they must not execute native witnesses, read
+    implicit repository state, invoke an LLM, publish artifacts, or call
+    external services. Scaffolding or materialization belongs to explicit future
+    modes with caller-provided targets and dry-run review; it must not be
+    hidden inside proof or envelope commands.
+11. Primary payload placement: agent-facing commands must expose the envelope
+    as top-level output when requested, not hide the main work packet inside
+    diagnostics.
+12. Boundedness: the envelope must declare fanout, item/file/token budgets,
+    omitted counts, stop reason, sufficiency basis, and an escalation rule
+    instead of silently expanding into a full proof graph.
+13. Command identity: actions must reference declared caller-owned command ids
+    or structured command refs; raw command text is display metadata only and
+    must not be treated as command admission.
+14. Receipt boundary: the envelope may cite receipts or receipt requirements,
+    but only admitted producers can satisfy merge proof obligations in the
+    consuming repository.
+
+## Solution Space
+
+| Option | Description | Strength | Failure Mode | Verdict |
+|---|---|---|---|---|
+| Free-form prompt text | CLI emits long prose prompts for agents. | Easy to read. | Token-heavy, hard to validate, easy to confuse with authority, hard to diff. | Reject. |
+| Structured guidance envelope | CLI emits typed JSON fields for context refs, questions, actions, commands, blockers, and non-claims. | Deterministic, parseable, compact, safe to route through agents and CI. | Requires schema discipline and tests. | Choose. |
+| Explicit workflow toolkit | CLI validates caller-provided inputs, renders views, emits plans, scaffolding manifests, and agent instructions. | Gives one-dependency adoption without hiding authority. | Needs strict dry-run/materialization boundaries. | Choose as the broader proofkit direction. |
+| Implicit executable orchestrator | CLI scans repo ambiently, runs commands, asks LLM, writes specs, or approves edits. | Convenient for one repository. | Violates proofkit boundary and creates hidden authority. | Reject. |
+
+For agent guidance, the structured envelope is the only option that satisfies
+determinism, genericity, token efficiency, and non-authority at the same time.
+
+## Chosen Model
+
+Add a reusable `ProofkitAgentGuidanceEnvelope` model and an opt-in CLI output
+mode. The model wraps an existing proofkit report or plan without changing the
+underlying report authority. The implemented v1 model normalizes legacy v1
+inputs into the target shape below, so downstream agents can consume one
+bounded packet shape.
+
+Target shape:
+
+```ts
+interface ProofkitAgentGuidanceEnvelope {
+  readonly schemaVersion: 1;
+  readonly envelopeId: string;
+  readonly sourceReport: ProofkitAgentGuidanceSourceRef;
+  readonly bounds: ProofkitAgentGuidanceBounds;
+  readonly costContract: ProofkitAgentGuidanceCostContract;
+  readonly contextRefs: readonly ProofkitAgentContextRef[];
+  readonly routeQuestions: readonly ProofkitAgentRouteQuestion[];
+  readonly clarificationQuestions: readonly ProofkitAgentClarificationQuestion[];
+  readonly actionPlan: readonly ProofkitAgentAction[];
+  readonly commands: readonly ProofkitAgentCommandRef[];
+  readonly blockedPreconditions: readonly ProofkitAgentBlockedPrecondition[];
+  readonly omitted: readonly ProofkitAgentGuidanceOmission[];
+  readonly receiptRefs: readonly ProofkitAgentReceiptRef[];
+  readonly nonClaims: readonly string[];
+}
+```
+
+Required semantics:
+
+- `sourceReport` binds the envelope to the report kind, report id, state, and
+  stable hash or caller-provided artifact ref. It does not prove report
+  authenticity, freshness, or native witness success.
+- `bounds` declares `fanout`, item/file/token budgets, omitted counts, and the
+  escalation route when the selected graph cannot stay bounded.
+- `costContract` declares the concrete cost and sufficiency boundary for the
+  emitted packet: loaded ref count, graph query count, receipt record count,
+  affected requirement count when known, omitted edge count, explicit omitted
+  edge accounting, stop reason, sufficiency basis, escalation, and non-claim.
+  The contract must not undercount emitted context or receipt refs. It may only
+  use `bounded_selection_complete` when the source report passed, fanout is
+  bounded, omitted count is zero, and no blocked precondition is present.
+- `contextRefs` identify exact files, selectors, ids, hashes, or JSON pointers
+  an agent should load. Each ref also has a role, so agents can distinguish
+  spec sources, proof bindings, generated lookups, receipt sources, routers,
+  restore surfaces, owner surfaces, command registries, evidence, local
+  context, and supporting refs without loading every nearby file.
+- `routeQuestions` are universal orientation questions, such as "what changed",
+  "what proves it", and "who owns it".
+- `clarificationQuestions` are machine-readable questions for missing authority
+  or ambiguous evidence. They must include `askWhen`, `owner`, `blocking`, and
+  `nonClaim`.
+- `actionPlan` gives deterministic route, bind, verify, candidate-change, and
+  promote routing labels. Each step must include owner, rationale, evidence
+  refs, commands, and non-claims. `candidate-change` never implies edit
+  approval or autofix safety; `promote` never implies rollout, readiness, or
+  policy approval.
+- `commands` reference caller-owned native commands by stable command id or
+  structured command ref. Proofkit may show display command text, but command
+  text alone is never command admission.
+- `blockedPreconditions` make missing external inputs explicit.
+- `omitted` records intentionally omitted wide graph sections by count, reason,
+  and escalation route.
+- `receiptRefs` may point at caller-provided receipts or required receipt
+  classes. They do not prove receipt freshness, producer admission, or merge
+  satisfaction unless the consuming repository admits the producer.
+- `nonClaims` prevent agents from treating guidance as proof truth.
+
+The current implementation always emits `bounds`, `costContract`, `omitted`,
+and `receiptRefs` in normalized output. Compatibility defaults are allowed only
+for old v1 input packets and must be conservative: they can describe item
+counts and missing token-budget authority, but they must not claim
+tokenizer-specific coverage, bounded sufficiency, or proof completeness.
+
+## Related Infrastructure Contracts
+
+The envelope design relies on these generic proofkit contracts without making
+the envelope itself responsible for all of them.
+
+### Deterministic Reports
+
+Machine reports may authoritatively describe one proofkit validation or planner
+output, but they must not own requirement meaning, proof routes, run facts, or
+merge approval. Every machine-consumed report must have stable rule ids,
+severity, source artifact, message, remediation or next-step hint, sorted lists
+unless order-sensitive, and non-secret diagnostics. Timestamps belong only in
+runtime-observation records.
+
+### Receipt Admission
+
+A receipt records observed proof. It is not created by an envelope. A
+merge-satisfying receipt must bind source revision, plan, proof binding,
+command, environment or precondition digest, witness selectors, toolchain or
+lockfile digest, admitted producer identity, result, and artifact or log
+hashes. Local receipts are advisory unless the consumer admits their producer
+for the proof class.
+
+### Witness Commands
+
+Proofkit command guidance must prefer stable command ids and structured command
+metadata. Prefix-only command admission is rejected because it cannot encode
+cwd, argv shape, environment allowlist, timeout, network policy, credential
+class, cache policy, expected artifacts, exit-code policy, or parallel group.
+
+### Cache And Scheduler
+
+Cache and scheduler output may accelerate proof planning, but cached witness
+success is evidence-adjacent, not proof authority. Cache keys must be
+engine/schema/profile/input/command/env/credential/platform sensitive. Live,
+credentialed, attended, or production witness success must never be reused as
+ordinary local proof. Scheduler output must be deterministic and respect
+parallel groups and shared-resource classes.
+
+### Consumer Profiles And Custom Rules
+
+Consumer profiles are the adapter between proofkit and repository topology.
+Custom rules may add deterministic findings, but they must never suppress or
+downgrade generic proofkit failures. If a custom rule becomes the main way to
+implement an invariant, the invariant should move into proofkit or back into
+repository-local tooling.
+
+### Parity Migration
+
+When proof infrastructure is extracted into proofkit or replaced by a proofkit
+primitive, parity is a temporary migration oracle. It proves extraction
+equivalence, not correctness. Accepted defects need stable ids, owners, expiry
+or review conditions, and removal tests.
+
+## CLI Contract
+
+Add opt-in flags instead of changing existing commands:
+
+```bash
+agentic-proofkit <command> --input <path> --agent-envelope
+agentic-proofkit <command> --input <path> --agent-envelope --format json
+```
+
+Shipped agent-envelope commands:
+
+- `adoption-workflow-plan`
+- `changed-path-set`
+- `gradual-adoption-bootstrap`
+- `gradual-adoption-guidance`
+- `obligation-decision`
+- `scaffold-project-structure`
+- `selective-gate-plan`
+- `selective-gate-evidence`
+- `workspace-changed-package-plan`
+- `workspace-shard-partition`
+
+Later workflow-helper candidates:
+
+- `scaffold-profile-plan` to emit a caller-reviewed repository profile plan;
+- `migration-plan` to emit parity snapshots and old-proof-owner retirement
+  steps;
+- `requirement-source-view` and `requirement-proof-view` to emit bounded
+  presentation envelopes over already-renderable source/proof views when a
+  future use case proves that view output needs additional agent routing beyond
+  the existing JSON, Markdown, and HTML renderers.
+
+Future envelope support should still not be added to every command by default.
+It should follow the same admission logic as the shipped projections:
+
+1. `gradual-adoption-guidance`, because it already owns agent action phases and
+   guidance payloads.
+2. `selective-gate-plan`, because it already emits required commands and
+   skipped-gate reasons.
+3. `requirement-bindings` or `proof-slice`, if a future use case proves that
+   their requirement-to-witness routing needs an agent envelope instead of the
+   existing JSON report or slice output.
+
+`changed-path-set` is admitted only as a bounded JSON-pointer projection over
+an existing report: it routes caller-supplied path facts, keeps commands and
+receipt refs empty, and does not prove source freshness or completeness.
+Commands such as `impact` and API-only helpers such as `readiness-closeout`
+remain later candidates only after a deterministic mapping is proved.
+`readiness-closeout` needs an additional fence because it is adjacent to product
+readiness. If supported later, the envelope may project only caller-provided
+rows, rules, and actions, and every readiness meaning must be marked
+caller-owned.
+
+Invalid input for agent-envelope mode should return deterministic JSON when it
+can do so without hiding parse failure. Plain stderr is acceptable for ordinary
+human CLI misuse, but machine-facing agent workflows should receive a stable
+invalid-input envelope with exit code `1`, no native-proof implication, and a
+non-claim.
+
+Scaffolding and migration helpers should follow a stricter default: emit plans,
+templates, or dry-run manifests first. Any future write mode must be explicit,
+idempotent, target-scoped, and separate from proof or envelope commands.
+
+## Clarification Questions
+
+Clarification questions are useful, but they must be structured questions, not
+free-form prompts. A safe question record answers:
+
+```ts
+interface ProofkitAgentClarificationQuestion {
+  readonly questionId: string;
+  readonly askWhen: string;
+  readonly owner: "consumer_repository" | string;
+  readonly blocking: boolean;
+  readonly question: string;
+  readonly expectedAnswerKind:
+    | "owner_decision"
+    | "missing_context_ref"
+    | "missing_witness"
+    | "blocked_external_input"
+    | "policy_choice";
+  readonly evidenceRefs: readonly string[];
+  readonly nonClaim: string;
+}
+```
+
+This gives agents enough direction to ask a precise human question while
+keeping answer authority outside proofkit.
+
+## Spec Invariant Extraction Guidance
+
+It is useful to add a proofkit mechanism that guides agents through invariant
+extraction from design documents and code, but proofkit must not run the LLM,
+read the repository, or decide the final requirements. The admissible owner is
+a deterministic guidance/report schema, not an extraction engine with hidden
+semantic authority.
+
+Two modes are justified.
+
+### Retrospective Baseline Mode
+
+Use when a repository already has implemented code on `master` and wants to
+construct or improve specifications after the fact.
+
+Inputs are caller-provided:
+
+- implemented surface refs;
+- existing tests and proof refs;
+- existing specs, if any;
+- caller-provided code summaries or extracted candidate invariants;
+- explicit non-claims and confidence class.
+
+Output:
+
+- candidate requirement records;
+- evidence refs that support or contradict each candidate;
+- missing witness obligations;
+- clarification questions for ambiguous behavior;
+- non-claims that prevent retrospective inference from becoming authority.
+
+Formal constraint:
+
+```text
+implemented behavior can suggest candidate requirements
+but only caller review can promote candidates to specification authority
+```
+
+### Pull Request Design Mode
+
+Use while a PR is open and the design document, implementation, and tests are
+still current.
+
+Inputs are caller-provided:
+
+- design document refs;
+- implementation plan refs;
+- changed paths;
+- candidate requirement ids;
+- witness commands and receipts;
+- open clarification answers, if any.
+
+Output:
+
+- proposed requirement additions or changes;
+- proof binding obligations for the changed requirements;
+- caller-reported possible stale-route warnings if implementation changed
+  without matching spec routes;
+- clarification questions before merge;
+- PR closeout guidance that says which caller-owned files may need review or
+  update.
+
+Formal constraint:
+
+```text
+open PR design docs are current evidence only inside the PR review window;
+merged stable specs become the durable authority after caller approval
+```
+
+## Extraction Guidance Non-Claims
+
+Spec invariant extraction guidance must not claim:
+
+- the extracted invariant is true;
+- the design document is current after merge;
+- the implementation is correct;
+- the tests are sufficient;
+- the candidate requirement is approved;
+- the candidate proof binding is fresh;
+- the repository may skip caller-owned review.
+
+## API Boundary
+
+The generic envelope module is:
+
+- `internal/kernel/agentenvelope/agentenvelope.go`
+- exported builder/admission functions from package root;
+- Go tests that exercise agent-envelope CLI projections;
+- CLI support behind `--agent-envelope`;
+- README and `NON_CLAIMS.md` updates.
+
+Public functions:
+
+```ts
+buildProofkitAgentGuidanceEnvelope(input)
+admitProofkitAgentGuidanceEnvelope(input)
+```
+
+The builder should be report-family agnostic and accept caller-provided mapping
+rules. A helper named as if a report alone can determine a complete action plan
+is rejected: a report usually lacks enough semantic context to own route,
+owner, or edit guidance. Report-specific projectors can be added only when a
+repeated generic mapping is proven.
+
+## Extension Rule
+
+Envelope support is shipped for report families that already own enough
+structured routing data to produce a bounded packet without inventing
+repository policy. New report-specific envelope projectors are admitted only
+when all of these predicates hold:
+
+1. The source report already contains stable selectors, omitted counts, command
+   refs or explicit non-command reasons, and consumer-owned context refs.
+2. The projector can preserve all non-claims from the source report.
+3. The envelope stays bounded by selector references and summary counts rather
+   than embedding full graphs or rendered documents.
+4. The output does not approve edits, satisfy merge obligations, authenticate
+   receipts, infer commands, or decide proof freshness.
+5. A test proves the exact JSON shape, invalid-input behavior, and one
+   overclaim rejection.
+
+## Proof Obligations
+
+Required proof for implementation:
+
+- stable JSON snapshot tests for envelope output;
+- negative tests for duplicate ids, missing owners, unknown phases, and empty
+  non-claims;
+- negative tests for invalid roles, bounds that understate emitted items,
+  omitted-count mismatches, invalid omission counts, unsafe receipt artifacts,
+  and receipt refs bound to undeclared command ids;
+- CLI tests proving existing commands keep old output unless
+  `--agent-envelope` is used;
+- tests proving clarification questions are emitted only as structured data;
+- tests proving top-level agent payload placement for agent-envelope mode;
+- tests proving invalid-input agent-envelope mode emits deterministic JSON when
+  parsing succeeds far enough to classify the failure;
+- a guidance-mode truth table for mode, checked scope, source report state,
+  missing bindings, and blocked preconditions;
+- command-binding tests proving action commands reference declared caller-owned
+  commands;
+- tests proving extraction guidance emits candidates, not approved
+  requirements;
+- package artifact test proving the new public module is included;
+- consumer proof in one repository before declaring the envelope useful.
+
+## Rejected Alternatives
+
+### Put Long Prompts In CLI Output
+
+Rejected because long prompts are hard to validate, inflate context, and blur
+the line between guidance and authority. Structured questions and action
+records give the same information with less ambiguity.
+
+### Let Proofkit Inspect The Repository Implicitly
+
+Rejected because implicit scanning would make proofkit own consumer topology and
+proof freshness. Consumers must provide facts, profiles, paths, or explicit
+input files; proofkit validates and projects them. Explicit parsing of
+caller-provided files is allowed, but ambient repository discovery is not proof
+authority.
+
+### Let Proofkit Generate Specs Directly As Authority
+
+Rejected for the first implementation because it would make candidate
+requirements look authoritative. The correct first step is candidate extraction
+guidance plus caller-owned promotion.
+
+### Hide Scaffolding Inside Proof Commands
+
+Rejected because a command that both validates proof and writes repository
+files would blur planning, materialization, and authority. Scaffolding belongs
+to explicit plan or dry-run materialization commands, with caller-owned review
+before commit.
+
+## Completion Definition
+
+This design is complete when proofkit can emit one common, deterministic,
+parseable agent guidance envelope for selected reports; when consumers can use
+that envelope to decide what to load, ask, run, and update; and when every
+output clearly states that proofkit guidance is not native proof execution,
+repository policy, product approval, merge approval, edit approval, proof
+freshness, or rollout authority.
+
+Full architecture alignment additionally requires structured command identity,
+deterministic report hygiene, cache/scheduler safety, monotone custom-rule
+boundaries, and defect-aware parity migration contracts. Envelope families
+beyond `gradual-adoption-guidance` must emit the same boundedness and
+receipt-boundary fields before they can claim target-shape support.

package/docs/binding-partition-admission-design.md

@@ -0,0 +1,127 @@
+# Binding Partition Admission Design
+
+## Decision
+
+Proofkit provides a `binding-partition` primitive that validates
+caller-provided proof-route ownership partition facts.
+
+The primitive owns generic consistency checks only:
+
+```text
+declared proof routes
+  -> one canonical route owner
+  -> declared binding surface
+  -> declared selector space
+  -> exact cross-owner or cross-surface delegation when referenced externally
+```
+
+It does not infer owners from paths, globs, packages, names, or generated
+graphs. It does not evaluate requirement meaning, proof adequacy, native witness
+results, receipt freshness, or merge readiness.
+
+## Problem
+
+Spec-first proof bindings need more than route existence. They need a reviewable
+partition:
+
+- every proof route has exactly one canonical owner;
+- binding surfaces own explicit selector space;
+- cross-owner and cross-surface references are deliberate, not accidental;
+- oversized or unrelated binding surfaces are evaluated only against
+  caller-owned thresholds.
+
+Without this layer, a generated graph can show route refs while hiding duplicate
+route owners, selector overlap, or cross-owner references with no admitted
+delegation.
+
+## Boundary
+
+Proofkit owns:
+
+- exact input admission for binding partition records;
+- one-owner-per-route checks over caller-declared `proofRouteRefs`;
+- route owner to surface owner consistency;
+- route selector to surface selector consistency;
+- duplicate selector ownership detection;
+- route reference source-surface and source-owner consistency;
+- route reference resolution to canonical route owners;
+- exact delegation matching for cross-owner or cross-surface references;
+- optional surface threshold checks when thresholds are caller-provided;
+- deterministic report output, summaries, diagnostics, and failed ids.
+
+The consuming repository owns:
+
+- requirement meaning;
+- which proof routes exist;
+- surface taxonomy and owners;
+- selector semantics;
+- threshold values and cohesion-group meaning;
+- delegation policy;
+- evidence authenticity;
+- witness execution and proof adequacy;
+- receipt freshness;
+- merge, release, rollout, and production readiness decisions.
+
+## Input Model
+
+The caller provides:
+
+- `proofRouteRefs`: the closed universe of proof routes to admit;
+- `bindingSurfaces`: owner and selector-space declarations;
+- `routeOwners`: canonical owner records for proof routes;
+- `routeReferences`: places where one owner or surface references a route;
+- `delegations`: exact source-to-target delegation records;
+- `surfaceThresholds`: optional caller-owned size/cohesion limits.
+
+Proofkit does not provide default thresholds. A surface is oversized only when
+the caller provided the corresponding threshold.
+
+## Delegation Rule
+
+Non-empty `delegationRefs` are not enough.
+
+A cross-owner or cross-surface route reference is admitted only when at least
+one referenced delegation exactly matches:
+
+```text
+fromOwnerId/fromSurfaceId == referrerOwnerId/referrerSurfaceId
+toOwnerId/toSurfaceId     == canonical route owner/surface
+proofRouteRefs            contains referenced proofRouteRef
+```
+
+This prevents a broad or unrelated delegation from masking route ownership
+drift.
+
+## Invariants
+
+- Every declared proof route has exactly one route owner.
+- Route owners cannot claim a surface owned by another owner.
+- Route owner selectors must be declared by that same surface.
+- A selector cannot be owned by multiple surfaces.
+- Route references must start from a declared surface owned by the referrer.
+- Route references must resolve to one canonical route owner.
+- Cross-owner or cross-surface route references require exact delegation.
+- Route owners and references outside `proofRouteRefs` fail closed.
+- Threshold findings are produced only from caller-provided thresholds.
+- Input order and host locale do not affect output order or stable JSON.
+
+## Rejected Alternatives
+
+| Alternative | Rejection |
+|---|---|
+| Infer owners from file paths or package names | That would put repository topology policy inside Proofkit. |
+| Treat any non-empty `delegationRefs` as sufficient | That allows unrelated delegation records to hide ownership drift. |
+| Bake in maximum route or selector counts | Surface size is repository policy; Proofkit may only enforce caller-provided thresholds. |
+| Merge this into `requirement-bindings` | Flat binding validation and partition authority are different review questions. |
+| Merge this into `proof-obligation-algebra` | Algebra validates proof composition; partition admission validates proof-route ownership. |
+
+## Proof Obligations
+
+- Unit tests prove admitted ownership, exact delegation, threshold behavior,
+  selector ownership, closed route universe, and stable JSON.
+- Negative tests prove missing owners, duplicate owners, undeclared routes,
+  unmatched delegations, owner/surface drift, selector overlap, unsafe evidence
+  refs, and malformed records fail closed.
+- CLI tests prove file/stdin parity and unsupported flags.
+- Package artifact tests prove package binary, packed files, installed-bin
+  behavior, version, and published design note.