agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/bundle/references/cli/hybrid-route-contract.yaml

@@ -0,0 +1,438 @@
+schema_version: agentera.hybrid_route_contract.v3
+status: normative
+purpose: >-
+  Define the portable, two-phase request-to-capability route contract. The CLI
+  implements deterministic resolution and receipt validation; the host supplies
+  open-ended semantic judgment only after deterministic abstention.
+ownership:
+  cli: >-
+    The CLI owns request validation, deterministic terminal selections, receipt
+    validation, and all startup authorization.
+  host: >-
+    The portable shared skill is the only host integration. A host may make a
+    semantic judgment only after semantic_required and must submit a receipt.
+  prohibited: [runtime_specific_adapter, host_bypasses_receipt_validation]
+  phrase_registry: skills/agentera/route-phrases.yaml
+  semantic_intent: references/cli/trigger-schema-enrichment.md
+  evaluation_corpus: fixtures/routing/hybrid-corpus.yaml
+
+protocol:
+  request:
+    version: agentera.route_request.v1
+    required_fields: [request]
+    request: >-
+      The transient, unmodified user message. It is accepted for routing and is
+       never persisted by this protocol.
+    cli_seam:
+      command: npx -y agentera@next route request --input PATH --format json
+      input: >-
+        A YAML or JSON mapping supplied by --input PATH or --input -. The request
+        field is never accepted in argv; --input - reads it from stdin.
+      output: >-
+        The versioned route response is emitted as JSON on stdout. Diagnostics do
+        not include request or topic text, and routing writes no state or report.
+      exit_codes: { ok: 0, invalid_input: 2, authority_conflict: 2 }
+  response:
+    version: agentera.route_response.v1
+    outcomes: [deterministic_selection, semantic_required]
+    deterministic_selection:
+      required_fields: [capability, tier, recognized_span, topic_span, provenance]
+      tiers: [bare, direct, phrase]
+    semantic_required:
+      required_fields: [request_sha256, semantic_capsule, semantic_capsule_sha256, receipt_contract, provenance]
+      semantic_capsule: >-
+        The active trigger intent documentation and contract version needed for
+        a host judgment. It contains no state-derived next_action and no raw
+        request text beyond the host's transient input.
+      semantic_capsule_sha256: >-
+        SHA-256 of the contract-owned canonical JSON representation of exactly
+        semantic_capsule. The host returns this value unchanged in its receipt.
+      semantic_capsule_canonicalization:
+        source: semantic_capsule
+        serialization: >-
+          UTF-8 JSON with recursively lexicographically sorted object keys and
+          no insignificant whitespace; array order is the order presented in
+          semantic_capsule.
+        included_inputs: [contract_version, capabilities, capability, triggers, id, description, priority, disambiguates_against, hint]
+        excluded_inputs: [request, request_sha256, provenance, diagnostics, next_action, phrase_registry, raw_trigger_matchers]
+        binding: >-
+          The digest binds the bounded classification inputs presented to the
+          host, not route diagnostics, state, private raw request duplication,
+          or any authority the host did not see.
+      receipt_contract:
+        schema_version: agentera.route_receipt_contract.v1
+        purpose: >-
+          A self-describing semantic-receipt guide returned only with deterministic
+          abstention. It contains the exact nullable receipt schema, legal outcomes,
+          nullability, compound and span rules, and one current stdin round trip.
+        stdin_command: npx -y agentera@next route receipt --input - --format json
+        input_schema:
+          type: object
+          additionalProperties: false
+          required: [request, receipt]
+          properties:
+            request: { type: string }
+            receipt: { $ref: '#/nullable_schema' }
+        stdin_example:
+          request: make implementation plan
+          receipt:
+            outcome: select
+            capability: plan
+            compound: none
+            question: null
+            remainder_span: null
+  receipt:
+    version: agentera.route_receipt.v1
+    required_fields: [version, request_sha256, semantic_capsule_sha256, outcome]
+    cli_seam:
+      command: npx -y agentera@next route receipt --input PATH --format json
+      input: >-
+        A YAML or JSON mapping supplied by --input PATH or --input -. It has the
+         transient original request in request and the complete nullable host output
+        in receipt. Neither field is accepted in argv or persisted.
+      output: >-
+        JSON startup authorization only: selected capability, one clarification,
+        or explicit status fallback. A preserved remainder includes its exact span
+        and transient text for the receiving host; diagnostics never echo input.
+      exit_codes: { ok: 0, invalid_input: 2, invalid_receipt: 64 }
+    outcomes: [select, clarify, no_match]
+    select:
+      required_fields: [capability, compound]
+      forbidden_fields: [question]
+    clarify:
+      required_fields: [question]
+      forbidden_fields: [capability, compound, remainder_span]
+    no_match:
+      forbidden_fields: [capability, question, compound, remainder_span]
+    validation_authority:
+      name: agentera.route_receipt_schema.v1
+      dialect: json_schema_draft_2020_12
+      canonical_capability_source: &canonical_capability_source skills/agentera/capability_schema_contract.yaml#route_aliases.primary_aliases
+      request_binding: sha256_of_original_utf8_request_bytes
+      semantic_capsule_binding: sha256_of_canonical_semantic_required.semantic_capsule
+      request_bound_fields:
+        remainder_span:
+          encoding: utf8_bytes
+          relation: 0 <= start < end = original_request_utf8_byte_length
+          exact_suffix: >-
+            start and end are UTF-8 code-point boundaries. The suffix bytes decode
+            with fatal UTF-8 handling and are returned unchanged, without
+            truncation or replacement characters.
+      schema: &agentera_route_receipt_schema
+        type: object
+        additionalProperties: false
+        required: [version, request_sha256, semantic_capsule_sha256, outcome]
+        properties:
+          version: { const: agentera.route_receipt.v1 }
+          request_sha256: { type: string, pattern: '^[a-f0-9]{64}$' }
+          semantic_capsule_sha256: { type: string, pattern: '^[a-f0-9]{64}$' }
+          outcome: { enum: [select, clarify, no_match] }
+          capability: { type: string }
+          compound: { enum: [none, preserve] }
+          question: { type: string, minLength: 1, maxLength: 280 }
+          remainder_span:
+            type: object
+            additionalProperties: false
+            required: [start, end]
+            properties:
+              start: { type: integer, minimum: 0 }
+              end: { type: integer, minimum: 0 }
+        allOf:
+          - if: { properties: { outcome: { const: select } }, required: [outcome] }
+            then:
+              required: [capability, compound]
+              not: { required: [question] }
+          - if: { properties: { outcome: { const: clarify } }, required: [outcome] }
+            then:
+              required: [question]
+              allOf:
+                - not: { required: [capability] }
+                - not: { required: [compound] }
+                - not: { required: [remainder_span] }
+          - if: { properties: { outcome: { const: no_match } }, required: [outcome] }
+            then:
+              allOf:
+                - not: { required: [capability] }
+                - not: { required: [question] }
+                - not: { required: [compound] }
+                - not: { required: [remainder_span] }
+          - if:
+              properties: { outcome: { const: select }, compound: { const: preserve } }
+              required: [outcome, compound]
+            then: { required: [remainder_span] }
+          - if:
+              properties: { outcome: { const: select }, compound: { const: none } }
+              required: [outcome, compound]
+            then: { not: { required: [remainder_span] } }
+      host_output_shape:
+        name: agentera_route_receipt
+        purpose: >-
+          The portable nullable host receipt shape. It validates the complete
+          receipt object only; the CLI receipt schema remains authoritative for
+          outcome relationships, request binding, and capability authorization.
+        canonical_capability_values_source: *canonical_capability_source
+        schema: &agentera_route_receipt_host_schema
+          type: object
+          additionalProperties: false
+          required: [version, request_sha256, semantic_capsule_sha256, outcome, capability, compound, question, remainder_span]
+          properties:
+            version: { type: string, enum: [agentera.route_receipt.v1] }
+            request_sha256: { type: string, pattern: '^[a-f0-9]{64}$' }
+            semantic_capsule_sha256: { type: string, pattern: '^[a-f0-9]{64}$' }
+            outcome: { type: string, enum: [select, clarify, no_match] }
+            capability:
+              type: [string, "null"]
+              enum: [status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, orchestrate, null]
+            compound:
+              type: [string, "null"]
+              enum: [none, preserve, null]
+            question: { type: [string, "null"], maxLength: 280 }
+            remainder_span:
+              type: [object, "null"]
+              additionalProperties: false
+              required: [start, end]
+              properties:
+                start: { type: integer }
+                end: { type: integer }
+      host_to_cli_normalization:
+        name: agentera.route_receipt_host_to_cli.v1
+        purpose: >-
+          Project the host-required nullable shape into the authoritative CLI
+          receipt shape without changing any non-null value.
+        input:
+          first_step: >-
+            Validate the unmodified host receipt against host_output_shape.schema.
+            Reject it on any host-shape failure before projecting any field.
+          accepted_keys: [version, request_sha256, semantic_capsule_sha256, outcome, capability, compound, question, remainder_span]
+        projection:
+          operation: >-
+            Copy every non-null field unchanged, including its exact string bytes
+            and numeric values; remove only a null field listed as inapplicable by
+            the matching outcome rule.
+          outcome_rules:
+            select:
+              required_non_null: [version, request_sha256, semantic_capsule_sha256, outcome, capability, compound]
+              removable_nulls:
+                question: always
+                remainder_span: when_compound_none
+            clarify:
+              required_non_null: [version, request_sha256, semantic_capsule_sha256, outcome, question]
+              removable_nulls:
+                capability: always
+                compound: always
+                remainder_span: always
+            no_match:
+              required_non_null: [version, request_sha256, semantic_capsule_sha256, outcome]
+              removable_nulls:
+                capability: always
+                compound: always
+                question: always
+                remainder_span: always
+        rejection:
+          unsupported_key: reject
+          unexpected_null: reject
+          projection_bypass: reject
+        downstream_validation: >-
+          Pass only the projected receipt to agentera.route_receipt_schema.v1, then
+          rerun deterministic routing against the supplied request and source
+           authority, require semantic_required with the same request digest and
+           semantic_capsule_sha256, then apply canonical-capability, request-digest,
+           semantic-capsule, span, and startup-authorization checks. Normalization
+           does not authorize startup and does not weaken any CLI cross-field rule.
+    request_binding: >-
+      The host sends the original request transiently beside the receipt. The
+      CLI recomputes SHA-256 over its UTF-8 bytes and requires an exact match to
+      request_sha256. No session, nonce, or receipt is stored.
+  validation_result:
+    terminal_outcomes: [selected, clarification, status_fallback, invalid_receipt]
+    startup_authorization:
+      selected: selected capability only
+      clarification: none
+      status_fallback: status only
+      invalid_receipt: none
+    invalid_receipt_exit: 64
+    result_schema:
+      version: agentera.route_receipt_result.v1
+      selected: >-
+        Emits the selected canonical capability, bounded semantic-receipt
+        provenance, and npx -y agentera@next prime --context <capability> --format json as
+        the existing startup path. It authorizes that capability only.
+      clarification: >-
+        Emits exactly one validated question and semantic-receipt provenance; it
+        authorizes no startup.
+      status_fallback: >-
+        Emits status with status_reason no_match and the existing status startup
+        path. It is not a readiness classification.
+
+precedence:
+  - order: 1
+    name: bare
+    condition: /agentera with no additional text
+    response: deterministic_selection
+    capability: status
+    tier: bare
+  - order: 2
+    name: direct
+    condition: >-
+      An explicit canonical capability name, or a primary alias, before any
+      topic under the existing direct-route grammar.
+    response: deterministic_selection
+    tier: direct
+  - order: 3
+    name: curated_phrase
+    condition: >-
+      A globally unique active phrase from the phrase registry exactly matches
+      the normalized leading token sequence.
+    response: deterministic_selection
+    tier: phrase
+  - order: 4
+    name: deterministic_abstention
+    condition: Any request not selected by orders 1 through 3.
+    response: semantic_required
+    rule: >-
+      The deterministic tier does not infer meaning, score candidates, match
+      substrings, or use regexes, thresholds, bands, state, or next_action.
+  - order: 5
+    name: semantic_receipt
+    condition: A valid receipt for a semantic_required response.
+    response: select, clarify, or no_match as validated below
+
+receipt_semantics:
+  select:
+    result: selected
+    startup: The selected capability starts after validation.
+  clarify:
+    result: clarification
+    startup: No capability starts; the host asks exactly the supplied question.
+  no_match:
+    result: status_fallback
+    startup: Status starts for orientation only, after validation.
+  invalid_receipt:
+    result: invalid_receipt
+    startup: No capability starts; return a bounded correction naming the invalid field.
+
+compound_intent:
+  principle: >-
+    A route selects at most one capability. Remainder is preserved and is never
+    silently chained, dispatched, or executed.
+  deterministic: >-
+    A direct or phrase route passes its exact topic_span to the selected
+    capability without classifying it as a follow-on request.
+  semantic:
+    dispositions: [none, preserve]
+    clarification: >-
+      clarify is a receipt outcome only, never a compound disposition. It is used
+      when one primary capability cannot safely be named.
+    preserve: >-
+      A select receipt with compound=preserve MUST include a non-empty
+      remainder_span inside the original request. The CLI carries that exact
+      original slice as deferred intent; it does not start another capability.
+    clarify: >-
+      Independent or consequential requests that cannot safely name one primary
+      capability require a clarify receipt, not a select receipt.
+
+phrase_matching:
+  comparison_view: >-
+    Decode the request as valid UTF-8, then split it into source tokens at
+    Unicode whitespace. Apply Unicode NFKC and locale-independent Unicode case
+    folding to each source-token comparison segment; join phrase segments with
+    one ASCII space. The final source token may be partitioned at its first
+    permitted separator; only its prefix participates in phrase comparison.
+  leading_only: >-
+    The registry phrase must equal the first normalized comparison-token
+    sequence. For every source token except the final phrase token, the whole
+    normalized token must match. The final phrase token either matches whole or
+    ends immediately before its first permitted separator. A permitted separator
+    is a source code point whose NFKC form is exactly `:`, `-`, or `—`; it is
+    not consumed and need not be followed by whitespace. No other attached
+    punctuation terminates a token. Quotation, negation, a phrase later in a
+    sentence, and a partial token abstain.
+  recognized_span: >-
+    Return half-open UTF-8 byte offsets from the first matched source token
+    through the final matched-token prefix. The exact original bytes between
+    source tokens, including whitespace, belong to this span; leading whitespace
+    and a separator do not. Decoding that byte slice reproduces the recognized
+    text exactly.
+  topic_span: >-
+    The topic is the exact original UTF-8 byte slice from recognized_span.end to
+    request_byte_length. It begins at the permitted separator when one ended the
+    final phrase token, otherwise at the end of that token. It preserves every
+    separator, whitespace character, and remainder byte; it is not normalized,
+    trimmed, or interpreted.
+  example:
+    request: "  HELP\tME decide: migrate the store"
+    normalized_leading_phrase: help me decide
+    recognized_span: { utf8_start: 2, utf8_end: 16, text: "HELP\tME decide" }
+    topic_span: { utf8_start: 16, utf8_end: 35, text: ": migrate the store" }
+
+phrase_ownership:
+  active_phrase_source: skills/agentera/route-phrases.yaml
+  collision_rule: >-
+    Every normalized phrase is globally unique across every registry entry,
+    including deprecated entries. A collision fails validation; precedence must
+    never choose a phrase owner.
+  direct_route_rule: >-
+    A phrase must not duplicate a canonical capability name or primary alias and
+    must not begin with one under the direct-route grammar. Direct routes always
+    retain order-2 precedence.
+  trigger_rule: >-
+    Trigger descriptions are semantic documentation only. They neither create
+    phrase ownership nor alter phrase precedence.
+
+privacy:
+  default_persistence: forbidden
+  transient_data: [request, topic, receipt, request_sha256, semantic_capsule_sha256]
+  retained_evaluation_evidence: >-
+    Retain only corpus version, case ID, partition, expected and observed
+    outcome, capability ID, tier, timing, model profile, and aggregate metrics.
+    Do not retain raw private request text, topic text, receipt question, or
+    semantic rationale by default.
+  permitted_corpus_text: >-
+    Frozen corpus text is synthetic or explicitly consented, and each corpus
+    declares its text provenance. Private production prompts are never imported.
+
+evaluation:
+  conformance_owner: packages/cli/test/registries/hybridRouteContract.test.ts
+  visible_corpus_entrypoint: npx -y agentera@next route evaluate --format json
+  visible_corpus_exit_codes: { pass: 0, failed_evaluation: 1, authority_conflict: 2 }
+  visible_corpus_output: >-
+    agentera.hybrid_route_evaluation.v1 reports only case IDs, partitions,
+    expected/observed outcomes, routing tier, capability ID, timings, authority
+    hashes, and aggregate metrics. It never writes a report or emits request,
+    topic, receipt-question, or rationale text.
+  corpus_partitions: { development: frozen, adversarial: frozen }
+  corpus_scope: >-
+    The frozen synthetic development and adversarial corpus is the sole
+    implementation conformance corpus. It has no hidden, sealed, or vendor-host
+    companion corpus.
+  semantic_host: >-
+    A host may make the semantic judgment and submit the portable nullable host
+    receipt shape. Host selection, model quality, and latency are host-dependent
+    and unmeasured by this offline evaluator; no host invocation is required.
+  local_latency_caveat: >-
+    Deterministic and receipt-validation p95 values are run-specific local
+    conformance measurements, not semantic-host or end-to-end latency claims.
+  target_gates:
+    deterministic_phase1_p95: 25_ms
+    receipt_validation_p95: 25_ms
+    harmful_misroutes: 0
+    deterministic_fixture_accuracy: 100_percent
+  harmful_misroute_taxonomy:
+    - wrong_capability_starts_a_state_changing_or_destructive_flow
+    - a_compound_remainder_is_executed_or_chained_without_user_consent
+    - a_no_match_or_clarify_request_starts_non_status_work
+    - private_request_text_is_persisted_or_exported
+  execution_status: >-
+    Offline implementation acceptance requires frozen deterministic and
+    receipt-validation conformance only. The visible corpus proves protocol
+    conformance, not semantic generalization. Semantic host quality and latency
+    are explicitly unmeasured and do not block implementation acceptance.
+
+deprecations:
+  decision_76: >-
+    Superseded by Decision mpulyomlyl only for the order-3 curated literal fast
+    path. Decision 76 continues to assign open-ended language and ambiguity
+    judgment to the LLM host; legacy trigger patterns, regexes, scores,
+    thresholds, and bands stay retired.
+  legacy_matchers: prohibited_from_active_routing
+  route_contract_changes: Require a new schema_version and a new frozen corpus version.

package/bundle/references/cli/routing-model.md

@@ -0,0 +1,155 @@
+# Hybrid routing model
+
+The portable shared skill and CLI use one hybrid cascade. Explicit routes and
+curated, globally unique literal phrases provide deterministic tiers; open-ended
+language remains host-owned. The normative protocol is
+[`hybrid-route-contract.yaml`](./hybrid-route-contract.yaml); this page is a
+reader-oriented model, not a second contract.
+
+Decision 76 remains in force for natural-language judgment. Decision mpulyomlyl supersedes it only for the curated literal fast path: there is still no scoring engine, no confidence threshold, and no borderline band. Legacy trigger patterns, regexes, thresholds, and bands do not route requests.
+
+## Cascade and precedence
+
+1. **Bare `/agentera`.** With no added text, select status deterministically.
+2. **Explicit direct route.** A canonical capability name or primary alias uses
+   the established direct-route grammar and passes its remaining text as topic.
+3. **Curated leading phrase.** Match one active phrase from
+   [`skills/agentera/route-phrases.yaml`](../../skills/agentera/route-phrases.yaml)
+   only when it is the exact normalized leading phrase. It selects that phrase's
+   sole owner and preserves the original remainder as topic.
+4. **Deterministic abstention.** Every other request returns
+   `semantic_required`. This tier never guesses from trigger prose, substrings,
+   regexes, scores, thresholds, bands, state, or `next_action`.
+5. **Validated semantic receipt.** The host makes an LLM-native semantic
+   judgment and submits `select`, `clarify`, or `no_match`; the CLI validates it
+   before capability startup. `select` starts one selected capability, `clarify` starts none, and `no_match` must route to status for orientation only after no capability matches.
+
+The direct grammar has precedence over phrase matching. A phrase collision is a
+registry validation error, not a tie to resolve at runtime.
+
+## Phase one: route request
+
+`agentera.route_request.v1` takes the transient original request. Its response
+is exactly one of:
+
+- `deterministic_selection`: a `bare`, `direct`, or `phrase` selection with
+  capability, provenance, recognized span, and topic span.
+- `semantic_required`: a request digest, semantic intent capsule, and canonical
+  capsule digest. It does not start a capability.
+
+The request itself is not persisted. The semantic capsule contains active
+trigger `description`, `priority`, and `disambiguates_against` documentation,
+not executable matcher inputs. Its digest is SHA-256 over contract-owned
+canonical JSON (recursively sorted object keys, no insignificant whitespace,
+and the presented array order) for exactly that capsule. It excludes private
+request text, request digests, diagnostics, state, and matcher authorities the
+host did not see.
+
+## Phase two: semantic receipt
+
+For `semantic_required`, the host sends the same transient original request and
+the complete nullable host receipt to
+`npx -y agentera@next route receipt --input - --format json`. The receipt binds
+to the SHA-256 of the request's UTF-8 bytes and the
+`semantic_capsule_sha256` returned in phase one. The CLI first validates the
+unmodified host shape, removes only contract-listed nulls, then reruns
+deterministic routing and accepts the receipt only when the same request still
+produces `semantic_required` with both bound digests. It then validates the
+projected CLI receipt with canonical-capability binding and request-bound span
+rules:
+
+Every `semantic_required` response includes a `receipt_contract` with the exact
+`agentera.route_receipt.v1` nullable schema, legal outcomes, outcome nullability,
+compound and `remainder_span` rules, and a current runnable stdin example. The
+same guide appears in `npx -y agentera@next route receipt --help`; a host does not need to
+inspect implementation or contract files to construct its receipt. The example
+uses a fixed public request, never the transient request being classified.
+
+| Receipt | Required result | Startup |
+| --- | --- | --- |
+| `select` | one canonical capability and `none` or `preserve` compound disposition | selected capability only |
+| `clarify` | one non-empty question | none |
+| `no_match` | no capability or question | status only |
+| invalid | bounded field-level correction, exit 64 | none |
+
+The resulting `selected` or `status_fallback` authorization contains bounded
+route provenance and the existing
+`npx -y agentera@next prime --context <capability> --format json` startup path.
+A `clarification` contains exactly one bounded
+question and no startup. This is intentionally a shared CLI contract, not a
+runtime-specific adapter. The portable shared skill is the sole host integration
+surface.
+
+## Phrase, span, and topic behavior
+
+The phrase registry owns stable IDs, capability ownership, literal phrases,
+global collision detection, and deprecation. Per-capability trigger schemas
+never create phrase ownership. Matching uses the contract's normalized token
+view (Unicode NFKC, case folding, whitespace normalization) while returning
+source UTF-8 byte offsets and exact slices from the original request. A `:`,
+`-`, or `—` that terminates the final phrase token is recognized in the
+comparison view but starts the preserved topic slice; other attached
+punctuation abstains.
+
+For example, `HELP\tME decide: migrate the store` recognizes only
+`HELP\tME decide`; its topic is the exact original `: migrate the store`.
+The separator is deliberately preserved. Quoted, negated, later-in-sentence,
+partial, and unregistered wording abstains; it belongs to the semantic phase.
+
+## Selection, ambiguity, and compounds
+
+The LLM host owns semantic selection and genuine consequential ambiguity. It
+consults trigger intent documentation, then chooses one of `select`, `clarify`,
+or `no_match`. A compound request never authorizes implicit chaining:
+
+- A direct or phrase selection preserves its entire original remainder as one
+  topic without interpreting it as follow-on work.
+- A semantic `select` may mark one original, UTF-8 code-point-aligned trailing
+  remainder span `preserve`; it is deferred intent, not a second startup.
+  `clarify` is an outcome, never a compound disposition.
+- Independent or consequential compound intent uses the `clarify` outcome when
+  one primary capability cannot be named safely.
+
+`next_action` informs readiness only after classification and cannot override the message intent. It never classifies a request.
+
+## Evaluation and privacy
+
+The visible frozen development and adversarial regression data live in
+[`fixtures/routing/hybrid-corpus.yaml`](../../fixtures/routing/hybrid-corpus.yaml).
+They use synthetic or explicitly consented text only and are the sole frozen
+implementation conformance corpus; no sealed holdout, credential, privacy
+approval, or provider-host benchmark is required.
+Retained evaluation evidence contains IDs, partition, outcome, tier,
+capability, timing, and aggregate metrics; private raw request
+text, topic text, receipt questions, and semantic rationale are absent by
+default.
+
+The portable host receipt shape has all fields required, using nullable fields
+for outcome-inapplicable values; the bounded host-to-CLI normalization seam first
+validates that unmodified shape, removes only contract-listed nulls, and preserves
+every non-null value unchanged. The CLI schema then separately validates outcome
+relationships, request binding, spans, canonical capabilities, and startup authorization.
+Normalization never authorizes startup or weakens a cross-field rule.
+The evaluator reports separate, run-specific local deterministic and
+receipt-validation p95 values. They prove protocol conformance for this visible
+corpus, not semantic generalization or an end-to-end latency commitment. Semantic
+model quality and latency remain host-dependent and unmeasured; it makes no live
+model calls.
+
+## Ownership boundaries
+
+- `references/cli/hybrid-route-contract.yaml` owns protocol, outcome vocabulary,
+  precedence, span rules, privacy, evaluation gates, and deprecations.
+- `skills/agentera/route-phrases.yaml` owns the deterministic phrase inventory.
+- `references/cli/trigger-schema-enrichment.md` owns semantic trigger intent
+  documentation only.
+- `packages/cli/src/eval/hybridRouteEvaluation.ts` evaluates the frozen offline
+  conformance corpus; its tests verify the evaluator and protocol structure.
+- `skills/agentera/SKILL.md` remains the thin portable host integration surface.
+
+## Maintenance
+
+- Maintainer: Agentera CLI maintainers
+- Source checkout root: `.`
+- Working directory: `.`
+- Command: `node packages/cli/dist/bin/agentera.js route evaluate --format json`