agentera 3.0.0-dev.26 → 3.0.0-dev.28

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/prime-consumer-compatibility.yaml

@@ -24,9 +24,9 @@ exclusions:
 consumers:
   - id: status_dashboard_renderer
     startup_command: agentera prime --context status --format json
-    evidence: skills/agentera/SKILL.md:68
+    evidence: skills/agentera/SKILL.md:83
     dashboard_evidence: packages/cli/src/capabilities/status/instructions.ts
-    state_evidence: packages/cli/src/cli/commands/prime/orientationOutput.ts:206
+    state_evidence: packages/cli/src/cli/commands/prime/orientationOutput.ts:209
     consumed_fields:
       - capability_context.instructions
       - capability_context.context.status_context.health
@@ -39,16 +39,17 @@ consumers:
       - capability_context.context.status_context.state_presence
       - capability_context.context.status_context.source_contract
     notes: >-
-      Bare `/agentera` and natural-language routing run one status-context call.
-      The response contains the full `capability_context.instructions` body and
-      the bounded `capability_context.context.status_context` projection. The
-      dashboard glyphs (health/todo/plan/objective/profile/next_action/attention)
-      define the minimum required state families; omitted rich detail is recovered
-      through the named command in the status context, never by raw artifact read.
+      Bare `/agentera` and status orientation run one status-context call.
+       Deterministic routing resolves bare, direct, and curated phrase requests;
+       every other request requires a validated semantic receipt before the
+       selected capability context starts. The status response contains the full
+      `capability_context.instructions` body and bounded
+      `capability_context.context.status_context`; omitted rich detail recovers
+      through its named command, never by raw artifact read.
   - id: capability_context_dispatcher
     startup_command: agentera prime --context <capability> --format json
-    evidence: packages/cli/src/cli/capabilityContext/startup.ts:250
-    skill_evidence: skills/agentera/SKILL.md:68-103
+    evidence: packages/cli/src/cli/capabilityContext/startup.ts:264
+    skill_evidence: skills/agentera/SKILL.md:77-96
     consumed_fields:
       - command
       - status
@@ -100,7 +101,7 @@ consumers:
       from the retired `prose` field to the v3 `capability_context.instructions`
       field after the second Task 1 evaluation found this guidance was the one
       remaining live consumer contradiction. Runtime authority
-      (capabilityContext/startup.ts:250) and SKILL.md (lines 68, 103) both use
+      (capabilityContext/startup.ts:264) and SKILL.md (lines 112-114) both use
       `capability_context.instructions`. The
       `documentation_drift` guard below prevents this guidance from drifting
       back to `prose`; it does not execute a prime command.
@@ -112,12 +113,13 @@ consumers:
 # (public_output_policy.canonical_field_set). Each list below now derives from
 # that authority, so schema discovery, the emitted JSON source_contract.fields,
 # the text-mode fields line, and the agent-ready-state contract advertise the
-# same canonical 27-field set. The `issues` deprecated transition alias is
-# emitted by default as a duplicate of `todo` (with a stderr deprecation warning)
-# and kept until the 3.0.0 stable cut; it is excluded only from the canonical
-# advertised `source_contract.fields` set (one canonical representation — `todo`
-# is canonical). It is NOT selector-only: it ships in the default bare briefing
-# only as bounded CLI transition compatibility.
+# same canonical 27-field set. The `issues` deprecated transition field preserves
+# the four legacy severity counts (`critical`, `degraded`, `normal`, `annoying`)
+# with a stderr deprecation warning, but intentionally excludes canonical
+# `todo.detail` so bounded detail is serialized once. It remains until the 3.0.0
+# stable cut and is excluded from the canonical advertised
+# `source_contract.fields` set (`todo` is canonical). It is NOT selector-only: it
+# ships in the default bare briefing as bounded CLI transition compatibility.
 # ---------------------------------------------------------------------------
 field_authorities:
   - id: orientation_output_emission
@@ -127,9 +129,9 @@ field_authorities:
     role: actual_emission_authority
     notes: >-
       Emits PRIME_STRUCTURED_FIELDS as source_contract.fields; the keys actually
-      serialized by buildOrientationJsonPayload. `issues` is emitted as a
-      deprecated alias of `todo` with a stderr warning, not as a member of the
-      canonical set.
+      serialized by buildOrientationJsonPayload. `issues` emits only `todo`'s
+      four legacy severity counts with a stderr warning; canonical `todo.detail`
+      is not duplicated. `issues` is not a member of the canonical set.
   - id: schema_advertised
     location: packages/cli/src/cli/commands/schema.ts
     authority: packages/cli/src/cli/stateQuery.ts:PRIME_STRUCTURED_FIELDS
@@ -287,9 +289,11 @@ field_classification:
   - field: issues
     status: deprecated_transition
     rationale: >-
-      Deprecated alias of `todo`. No current consumer in this inventory reads
-      it; the alias remains only as bounded CLI transition compatibility until
-      its owning contract removes it.
+      Deprecated count-only compatibility projection of `todo`. It preserves
+      critical, degraded, normal, and annoying for legacy consumers while
+      excluding canonical `todo.detail` to prevent startup payload duplication.
+      No current consumer in this inventory reads it; the projection remains
+      until its owning contract removes it.
   - field: bundle
     status: retired
     rationale: >-
@@ -307,9 +311,21 @@ public_output_policy:
     authority for the bare prime briefing. Task 2 reconciles schema.ts, the text
     briefing hardcoded list, and agent-ready-state-contract.yaml hej.fields to
     this set, removing the four-way drift documented above.
-  deprecated_alias_rule: >-
-    `issues` remains a transition alias of `todo` with a stderr deprecation
-    warning until the 3.0.0 stable cut. No task in this plan may remove it.
+  deprecated_alias_rule:
+    field: issues
+    status: retained_until_3_0_0_stable_cut
+    retained_fields:
+      - critical
+      - degraded
+      - normal
+      - annoying
+    excluded_fields:
+      - detail
+    rationale: >-
+      `issues` preserves the four legacy severity counts with a stderr
+      deprecation warning. Canonical bounded detail belongs only to `todo.detail`
+      and is intentionally excluded to prevent duplicate startup payload. No
+      task in this plan may remove the compatibility projection before the cut.
   default_only_omission_rule: >-
     Fields classified conditional or diagnostic may be omitted by Task 2 when
     they are in their default/empty state, provided missing-versus-empty
@@ -327,17 +343,41 @@ public_output_policy:
     Task 4 folds the bounded state into one `agentera prime --context status
     --format json` response (<=25000 bytes) so the status dashboard needs no
     separate bare-prime call or raw artifact read. The `--context` capsule
-    contract (command/status/capability_context) is unchanged. The status
-    capsule puts the canonical Task 3 projection at
-    `capability_context.context.status_context`; app/project integration and
-    shared-skill diagnosis remain available for routing while unrelated detail
-    is omitted.
+    contract (command/status/capability_context) is unchanged, including
+    contract-owned state declarations, inventory, included/missing families,
+    schema diagnostics, and first-invocation reads. The status capsule assembles
+    and measures that fixed envelope first, then bounds
+    `capability_context.context.status_context` to the remaining complete-capsule
+    budget. If a projection leaves the complete envelope over budget, the next
+    allowance is set one byte below that projection's actual serialized size,
+    forcing a strictly smaller bounded form; projection continues monotonically
+    until the capsule fits or the routing-preserving irreducible form fails
+    explicitly. The status-specific degraded envelope retains TODO
+    aggregate/detail recovery, attention, and next_action rather than collapsing
+    to non-routing metadata. App/project integration and shared-skill diagnosis
+    remain available through the bounded status state while unrelated rich
+    copies are omitted.
   status_context_contract:
     startup_command: agentera prime --context status --format json
     state_path: capability_context.context.status_context
     instructions_path: capability_context.instructions
     max_utf8_bytes: 25000
     measurement: Buffer.byteLength(JSON.stringify(payload, null, 2) + "\n", "utf8")
+    budget_allocation: >-
+      Assemble contract-owned capability metadata, instructions, and context
+      keys and measure the complete envelope. When it is over budget, set the
+      next status_context allowance one byte below the current nested
+      projection's measured serialized size. Every accepted retry is therefore
+      strictly smaller; terminate only with a <=25000-byte capsule or explicit
+      irreducible routing-envelope failure.
+    required_capability_metadata:
+      - capability_context.state.declared_read_needs
+      - capability_context.state.declared_write_targets
+      - capability_context.state.artifact_inventory
+      - capability_context.state.included
+      - capability_context.state.schema_error
+      - capability_context.context.first_invocation_read
+      - capability_context.context.schema_error
     required_state:
       - health
       - todo
@@ -347,6 +387,10 @@ public_output_policy:
       - attention
       - state_presence
       - source_contract
+    budget_fallback_retains:
+      - todo
+      - attention
+      - next_action
     omitted_detail_recovery: capability_context.context.status_context.brief.omitted_rich_state
     raw_artifact_reads_required: false
   fail_visible_rule: >-
@@ -437,7 +481,8 @@ default_emission_omission_contract:
       history, shared_skill, project_integration, decision_attention, and
       the bespoke context pointers (kept null on the bare surface). The
       conditional v1_migration/docs/objective are retained when active (see
-      omitted_when_default). issues ships as the deprecated transition alias.
+      omitted_when_default). issues ships as the deprecated count-only
+      transition projection and excludes canonical todo.detail.
     projected_subdetail:
       - field: plan.tasks
         reason: plan_task_detail