agentera 3.0.0-dev.3 → 3.0.0-dev.30

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

@@ -0,0 +1,416 @@
+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: agentera 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, 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:
+    version: agentera.route_receipt.v1
+    required_fields: [version, request_sha256, semantic_capsule_sha256, outcome]
+    cli_seam:
+      command: agentera 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 agentera 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: agentera 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/parity-expected-actual-template.md

@@ -0,0 +1,30 @@
+# Parity EXPECTED/ACTUAL bug-demonstration template
+
+Apply this pattern to `npmParityMatrix` / Python-oracle parity rows when fixing a
+regression: land a **demonstrate** commit first, then a **fix** commit that only
+flips the assertion.
+
+## Workflow
+
+1. **Demonstrate commit** — test passes on broken behavior; correct expectation
+   preserved in a block comment (`EXPECTED`); wrong behavior asserted (`ACTUAL`).
+2. **Fix commit** — delete comment markers and `ACTUAL` line; `EXPECTED` becomes the
+   live assertion. No other edits in the fix commit.
+
+## Minimal vitest shape
+
+See `packages/cli/test/cli/parityExpectedActualTemplate.test.ts` for a runnable
+micro-example. For real parity rows, mirror the pattern in the oracle fixture row
+and `npmParityMatrix.test.ts` drift assertions.
+
+## npmParityMatrix row
+
+When adding a row to the parity matrix for a pre-existing bug:
+
+- Register the row with `drift_direction: equal` as the target after fix.
+- In the demonstrate pass, temporarily pin oracle shape to the **wrong** envelope
+  or assert `ACTUAL` substring in a dedicated regression test.
+- Fix pass restores `equal` against the corrected CLI output.
+
+Do not apply EXPECTED/ACTUAL by default to every row — only where bisect clarity
+justifies the two-commit ritual.