feat(engine): improve agent interface efficiency

Author: MrScripty

.agents/skills/standards-engine/SKILL.md

@@ -22,8 +22,9 @@ Tool-name prefixes vary by client; operation names match the Engine contract
 (for example, `route`, `read`, and `propose`).
 
 Use `routing_facts` when the registered fact vocabulary is unknown. Use
-`route` with explicit engineering facts, then `read_many` for the selected
-exact policies in one call. Use `read` for one item and `related` for relationships.
+`route` with explicit engineering facts and `content: {}` to receive selected
+exact policies immediately. Follow `content.next` when more remain. Use `read_many`
+for an explicit subset, `read` for one item, and `related` for relationships.
 Omit `snapshot` on the first call to capture
 accepted authority; reuse the returned snapshot on subsequent calls. Omission
 always captures a new snapshot, so carry the handle when continuing a task.
@@ -87,6 +88,12 @@ accepted-snapshot Analysis, verification preflight, and evidence maintenance
 remain available through the explicit advanced catalog; see
 [references/environment.md](references/environment.md).
 
+Repeated exact evidence references in `propose`, `revise`, `resolve_workflow`,
+`resolve_many`, or `review` may use a request-local `evidence` table. Every typed
+`{"evidence_ref":"name"}` explicitly selects one complete reference from that
+same request. Normal inline references remain valid. Supply real evidence and
+retain each decision's own rationale and authorization; names confer neither.
+
 ## Choose The Workflow
 
 - For routing, reading, relationship discovery, or accepted-snapshot Analysis,

.agents/skills/standards-engine/references/authoring.md

@@ -82,6 +82,33 @@ a later round. `workflow_status` stays summary-only; full diagnostic results
 retain their native fields and omit inline work. Neither presentation choice
 changes review, approval, publication or recovery authority.
 
+## Request-Local Evidence Reuse
+
+The five focused authoring calls `propose`, `revise`, `resolve_workflow`,
+`resolve_many`, and `review` accept an optional top-level `evidence` map. A map
+entry binds a caller-selected name to one complete, real `EvidenceReference`.
+In a typed evidence-reference position, `{"evidence_ref":"review_record"}`
+selects that request's `evidence.review_record`. Inline references and local
+uses may be mixed. Use sharing when references repeat; a single use can be
+smaller inline.
+
+The table supports at most 128 entries. Every entry must be explicitly used;
+missing names, unused entries, references inside the table, and malformed fields
+reject before domain dispatch. Local names cannot refer to a previous call or
+another agent's table. Authored text and arbitrary JSON values are not interpreted
+as local references.
+
+Expansion produces the original native request. Each operation's native evidence
+uniqueness rules are checked after expansion. `resolve_many` checks its 256 KiB
+serialized-submissions bound after expansion too. Actual provider, digest, live
+bytes, exact work identity and per-decision authorization are still validated by
+the existing owners. Sharing bytes does not share decisions or approvals, and
+creates no persisted registry, new evidence or implicit acceptance.
+
+Advanced native operations keep their complete-reference input contracts. The
+canonical examples include inline and request-local forms; the installed tool
+schema determines the exact supported positions.
+
 ## Edit Selection
 
 Use the installed `propose` schema as the authority for edit variants and fields.

.agents/skills/standards-engine/references/environment.md

@@ -51,7 +51,7 @@ configured purpose.
 
 The local server remains synchronous MCP stdio with protocol `2025-11-25`;
 requests execute serially and immutable Engine handles survive reconnection.
-The current implementation is 0.2.0 and Engine interface 38. No network listener,
+The current implementation is 0.2.0 and Engine interface 39. No network listener,
 paid model turn, remote publication or extra server dependency is introduced.
 The existing local authoring authorization adapter is owner-operated and
 always-allow; explicit user authorization still governs requested changes.
@@ -102,3 +102,24 @@ MCP SDK harness requires the SDK in a separate client environment and the locked
 Engine Python supplied through `--engine-python`. The optional Codex test uses
 `--server standards-authoring` (or the actual configured authoring name) and does
 not start a model turn. These checks do not certify the content's editorial quality.
+
+## Schema presentation (interface 39)
+
+`--schema-mode compatibility` is the default. It retains inline input schemas and
+schema text for the established nested-rendering workaround. Hosts with verified
+support for local JSON Schema references may explicitly select `--schema-mode native`.
+Native mode omits the duplicate description text and chooses the smaller complete
+inline/reference input projection per tool. It is a lossless catalog presentation;
+validation, output schemas, purpose, permissions and domain behavior are unchanged.
+
+Select the mode in host configuration, then restart/reconnect. There is no guessed
+client-name policy, automatic downgrade, or transport-session state. The existing
+catalog digest reflects the actual tool definitions (identical projections share
+a digest even across mode names); use `runtime_info` to detect a
+stale client catalog. Preserve all stores, proposals, readiness and recovery handles.
+
+Qualify the actual configured client before choosing native mode. The optional
+`codex_navigation_client.py --schema-mode native` checks the already configured
+registration; it does not reconfigure Codex or start a model turn. Passing schema
+validation alone does not establish successful model-visible rendering. Retain
+compatibility mode while that client qualification is unavailable.

.agents/skills/standards-engine/references/navigation.md

@@ -13,7 +13,9 @@ MCP tool definitions supplied by the client; invoke the tools directly.
 3. `route` selects applicable standards and required closure from explicit facts;
    `read` returns exact policy by canonical ID; `related` traverses explicitly
    selected permitted relationship groups and directions.
-4. After routing, group the selected policies into `read_many` with the returned
+4. Request `content: {}` on `route` to receive the selected exact policies directly
+   (see the bounded-content contract below). For an explicit subset instead,
+   group the selected policies into `read_many` with the returned
    snapshot and ordered `items` such as `[{"target":"core"}]`. Select up to 32
    unique read items per call. The complete result is bounded to 2 MiB and any
    unavailable item rejects the whole group; narrow the selection on a limit.
@@ -35,6 +37,29 @@ Use `find_snapshots` to resume a known lifecycle. Delete or undelete a snapshot
 only when the user requested that lifecycle change; deletion does not authorize
 standards mutation.
 
+## Bounded Content With Routing
+
+Focused `route` accepts optional `content: {"limit": 8, "offset": 0}` in both
+purposes. Omission preserves selection-only behavior; `{}` requests the first
+page with defaults. A page contains up to 32 exact compact reads in the route's
+selected, deduplicated target order. `content.total` counts all selected targets;
+`content.offset` identifies this page. Follow `content.next` as the entire next
+`route` request, preserving its facts and snapshot. Nonzero offsets require an
+explicit snapshot. Changing facts intentionally starts a different selection.
+
+The complete route result, including its plan, questions, items and continuation,
+is limited to 2 MiB. Byte pressure returns fewer whole reads. A first record that
+cannot fit returns a typed limit rejection, never clipped policy text. Request a
+selection-only route and explicitly `read` that target when the client can receive
+it. An unavailable selected dependency or a failed read rejects the result;
+partial prefixes are not returned as success. An offset equal to the selected
+count returns an empty final page; a larger offset is invalid.
+
+All content uses the same captured authority and ordinary read/qualification
+rules. Missing facts remain unresolved even when selected text is returned.
+Only the selected content is paged; the reading plan and questions remain complete.
+Native `query` and candidate previews keep their existing request contracts.
+
 ## Explicit Facts And Routing Explanations
 
 Call `routing_facts` to discover fact IDs, aliases, types, allowed values,

docs/plans/README.md

@@ -18,3 +18,13 @@ Completed prerequisites do not close the parent objective. See the
 [Standards Agent Interface](standards-agent-interface/plan.md) delivers focused
 navigation, explicit-fact discovery and routing explanations, and bound authoring
 contexts over the Engine. It is `Accepted`; all three milestones and their acceptance checks are complete. It does not replace the active Standards Library Effectiveness effort.
+
+## Engine Interface Efficiency Verification
+
+[Agent Interface Efficiency](agent-interface-efficiency/plan.md) implements the
+user-authorized continuation of the interface-38 workflow simplification: schema
+presentation, bounded routed content and request-local evidence reuse. It is
+`Verifying`; local implementation evidence and remaining environment/client/review
+gates are recorded in its [verification](agent-interface-efficiency/verification.md)
+and [findings](agent-interface-efficiency/issues.md). This bounded code-maintenance
+slice does not close or replace Standards Library Effectiveness acceptance.

docs/plans/agent-interface-efficiency/issues.md

@@ -0,0 +1,10 @@
+# Findings
+
+- E1 — qualification: local Python is outside the supported locked environment.
+  Owner: integration. Run the unchanged locked CI checks before accepted integration.
+- E2 — client qualification: configured Codex/MCP SDK clients are not present locally.
+  Owner: host operator. Retain default compatibility mode; run the optional client
+  harness before selecting native presentation for that deployment. Raw stdio tests
+  prove protocol consumption, not client rendering or model behavior.
+- E3 — acceptance: independent external review is not available in this execution.
+  Owner: integration. Review the base-pinned diff and evidence before acceptance.

docs/plans/agent-interface-efficiency/ledger.md

@@ -0,0 +1,38 @@
+# Ledger
+
+## Admission
+
+Pinned the newly pushed `34c2dcba` using its exact GitHub source bundle. Working tree
+was clean; work is on a private local feature branch. Read Core, routed actual task
+facts and relevant contract/implementation guidance. The current environment provides
+Python 3.13.5 and rpds-py 2026.5.1, not the locked supported 3.11/3.12 environment.
+No supported-runtime or live model-client acceptance is inferred from local checks.
+
+The compatibility mode retains the existing supported-client workaround; native
+presentation is an explicit new selection rather than an unqualified default change.
+
+## Implementation and review
+
+- Added host-selected compatibility/native catalog presentation. Native chooses the
+  smaller equivalent projection per input; application schemas gain no artificial
+  reference overhead. Kept structuredContent and matching JSON text unchanged.
+- Added focused route-content paging over the existing read owner, with qualified
+  closure, one snapshot/input, whole-item byte bounds and explicit continuations.
+- Added generated agent input variants and request-local typed evidence expansion;
+  domain inputs and persisted evidence remain native. Table-less requests keep the
+  original decoding path. Added sibling-equivalence and negative-boundary tests.
+- Corrected the new expander's Python/wire field-name mapping before qualification.
+  Preserved native operation-specific uniqueness instead of inventing blanket rules.
+- Review found JSON Schema whole-number floats were valid but not Python indices.
+  Normalized already-validated route counts, matching the existing workflow detail
+  convention, and added a focused regression for both purposes and fractional rejects.
+- Updated affected generated-facade expectations and interface-version assertions.
+  The existing main-advancement fixture mixed uncommitted new contracts with an old
+  accepted tree and a new manifest; changed that one fixture to commit a coherent
+  candidate before testing advancement. The Engine's rejection was correct.
+- Expanded the write set to those directly affected test consumers and the active
+  plan index. No normative policy, approval, provenance, lock or stored-state change.
+- Local full coverage, targeted reruns, cold stdio measurements, retained interface-38
+  contexts, generated freshness and structural checks are recorded in verification.
+  Supported locked runtime, configured-client rendering and independent review remain
+  distinct acceptance gates; none is inferred from local schema/unit success.

docs/plans/agent-interface-efficiency/plan.md

@@ -0,0 +1,96 @@
+# Agent Interface Efficiency
+
+Status: Verifying
+Acceptance: pending
+Base: `34c2dcbaf9aa7ade5589ae5c88383719dda81200`
+Operation: implement this plan; user-authorized continuation of the MCP simplification.
+
+## Objective and admission
+
+Reduce repeated schema descriptions, route/read round trips, and repeated evidence
+references without changing policy, exact authority, review or publication meaning.
+The first workflow simplification is already integrated; retain its immutable
+contexts, bounded work pages, explicit decisions and lightweight status reads.
+
+The executable Router was run against the base with explicit task facts and no
+unresolved conditions. Selected concerns: implementation, verification, planning,
+documentation, build, development proportionality; library; generated-contract and
+IPC boundaries; contracts, architecture, dependencies, security, diagnostics and
+performance; code design, replay, schemas, protocol adapters, evolution and test
+oracles. No dependency, normative-policy or persistence-format change is planned.
+
+The existing schema/compiler, facade, navigation projection and MCP transport own
+this work. No workflow store, evidence registry, model evaluator, session pointer,
+new authorization mechanism or general-purpose orchestration language is admitted.
+The composed design has three independent presentation concerns; existing domain
+operations still own routing, reads, evidence verification and decisions.
+
+## Decisions
+
+1. Host-selected MCP schema presentation: compatibility remains the default for
+   known clients with incomplete nested-schema rendering. Native presentation uses
+   the smaller complete inline/reference projection without schema text in descriptions.
+   Both modes validate exactly the same inputs. No client-name heuristic or hidden
+   downgrade; a restart chooses another catalog and its existing digest identifies it.
+2. Optional `route.content` requests a bounded page of selected exact compact reads.
+   Route and reads share one snapshot and compiled input. Page count is bounded;
+   byte pressure returns fewer whole items with an exact snapshot/facts continuation.
+   Unknown facts, full dependency qualification and purpose filtering are unchanged.
+   An oversized first record returns a bounded typed limit rejection, never a
+   truncated policy. Plain route and explicit single/grouped reads remain supported.
+3. Authoring agent inputs may supply a request-local `evidence` table and typed
+   `evidence_ref` uses. Generated agent input variants preserve native domain input
+   types; the facade validates and expands only typed reference positions, then
+   validates the native call before dispatch. Every use explicitly selects evidence.
+   Missing/unused entries reject before effects; native evidence uniqueness is enforced after expansion.
+   Provider/digest/current-authorization checks and expanded batch limits are unchanged.
+
+## Compatibility and state
+
+Interface 39 is an additive request capability and coordinated catalog update.
+Native authoring request types, Analysis request/state versions, all handles, SQLite,
+readiness, application and recovery representations stay unchanged. Application
+catalogs contain no authoring evidence variants. Native schema mode is opt-in until
+actual configured-client qualification is available. Restart/reconnect clients;
+preserve stores, proposals and exact contexts. No automatic retries or publication.
+
+## Write set
+
+- Engine canonical schema/interface and generated model/tool projections.
+- `tools.py`, `mcp.py`, `agent_navigation.py`, `context_projection.py`, plus one
+  request-local evidence normalization module if required by its separate concern.
+- Focused contract, navigation, evidence and MCP tests; affected catalog consumers,
+  examples and optional configured-client harness.
+- Engine READMEs/PURPOSE-SEPARATION and authoring/navigation/environment skill references.
+- This plan, ledger, issues and verification; generated suite-input manifest.
+
+Directly affected consumers inside these owners may be added in the ledger.
+Normative content, approvals, provenance, locks and user stores are outside the write set.
+
+## Acceptance
+
+- Canonical native/agent schema validation and independent Draft 2020-12 validation
+  agree for valid and malformed fixtures in both presentation modes; generated
+  outputs are fresh. Input fields, omissions, recursion and extra-field rejection
+  retain meaning. Runtime catalog identity tracks actual definitions; equivalent catalogs share an identity.
+- Route-content equals ordinary exact reads, including all pages; known missing
+  facts stay unresolved; partial pages, oversized records, invalid selections,
+  unavailable qualifications and snapshot lifecycle changes are explicit.
+  One compiled input is used per call, without additional snapshot capture.
+- Shared and inline evidence produce identical exact native decisions/analysis and
+  review outcomes. Alias errors, stale evidence, unsupported providers, foreign work,
+  native uniqueness violations after expansion and expanded-size overflow publish nothing. Cold process
+  reconstruction needs no alias table. Caller inputs remain unchanged.
+- Real stdio traces compare call counts and serialized request/result/catalog bytes
+  against the base. Report tradeoffs; byte counts do not claim token/billing savings.
+- Focused and affected package suites, structural checkpoint and patch reconstruction
+  pass. Supported locked Python 3.11/3.12, configured-client qualification and
+  independent review remain separately named gates when unavailable locally.
+
+## Sequence and next slice
+
+Implement the three bounded concerns with tests, regenerate contracts, run integrated
+checks and measurements, then package changed files and review evidence. Current next
+slice: integration qualification and independent review after the local verification
+and base-pinned delivery. Implementation of the three admitted concerns is complete;
+remaining acceptance gates are tracked in issues.md and verification.md.