agentera 3.0.0-dev.41 → 3.0.0-dev.47

package/bundle/references/cli/prime-consumer-compatibility.yaml

@@ -1,701 +0,0 @@
-schema_version: agentera.prime_consumer_compatibility.v1
-status: approved_boundary
-plan: plan:634c092e-a7bc-48f4-80ee-2c91940e54f1
-plan_task: 1
-purpose: >-
-  Task 1 compatibility boundary for the "Make prime startup compact and
-  self-contained" plan. Inventory every documented prime consumer, classify
-  every field proposed for omission as removable, conditional, or
-  transition-required, and record the approved public-output policy that Tasks 2
-  through 4 must satisfy. This file is the consumer-facing contract boundary; it
-  does not consolidate the emitted field authority (Task 2) and does not define
-  byte budgets (json_output_surface_manifest.yaml owns those).
-exclusions:
-  - Structured attention records (attention stays delimiter-encoded string[]).
-  - Stable artifact identities and reference-based routing.
-  - New summary-versus-diagnostic projection modes.
-  - Compiled or cached capability instructions.
-
-# ---------------------------------------------------------------------------
-# Consumer inventory. Each consumer names its startup command and the concrete
-# fields it reads, with a file:line evidence pointer into the current tree.
-# Tasks 2-4 MUST keep every consumed field resolvable from a declared surface.
-# ---------------------------------------------------------------------------
-consumers:
-  - id: status_dashboard_renderer
-    startup_command: agentera prime --context status --format json
-    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:209
-    consumed_fields:
-      - capability_context.instructions
-      - capability_context.context.status_context.health
-      - capability_context.context.status_context.todo
-      - capability_context.context.status_context.plan
-      - capability_context.context.status_context.objective
-      - capability_context.context.status_context.profile
-      - capability_context.context.status_context.next_action
-      - capability_context.context.status_context.attention
-      - capability_context.context.status_context.state_presence
-      - capability_context.context.status_context.source_contract.capability_startup
-      - capability_context.context.status_context.source_contract.empty_state
-    notes: >-
-      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:264
-    skill_evidence: skills/agentera/SKILL.md:77-96
-    consumed_fields:
-      - command
-      - status
-      - capability_context
-      - capability_context.instructions
-    notes: >-
-      Per-capability startup capsule. The CLI emits
-      `capability_context.instructions` (the capability's instructions module),
-      not `prose`; the shared skill consumes that field directly. This consumer
-      governs the `--context`
-      surface, not the bare briefing; the bounded decision brief (Task 3) must
-      not break the `--context` capsule. Executable fixture proves the emitted
-      payload contains `capability_context.instructions` and NOT `prose`.
-  - id: packaging_distribution_gate
-    startup_command: agentera prime --format json
-    evidence: packages/cli/test/packaging/packageVerification.test.ts
-    consumed_fields:
-      - command
-      - status
-      - app_home
-      - app_home.source
-    notes: >-
-      Distribution-boundary consumer. The one extracted-package conjunction
-      asserts `command: "prime"`, `status: "ok"`, and that `app_home.source`
-      reflects resolution after the packed upgrade path. Tasks 2-4 must keep
-      the published prime JSON shape stable so fresh-cache npx gates keep
-      passing. Not a dashboard consumer; does not read state families.
-  - id: json_output_surface_manifest
-    startup_command: agentera prime [ --dashboard | --context <capability> ] --format json
-    evidence: scripts/json_output_surface_manifest.yaml:47-161
-    consumed_fields: declared_surfaces
-    notes: >-
-       Measurement/budget authority, not a runtime consumer. Declares five prime
-       surfaces: prime-dashboard, prime-status-context, prime-briefing,
-       prime-fields-sparse, and prime-capability-context. The capability surface expands over the current
-       English CAPABILITY_NAMES set; generic capsules use the 55000-byte ceiling,
-       while status uses its dedicated 25000-byte one-call budget. It owns the
-       byte/token budgets; Task 3 (<=12000) and Task 4 (<=25000) budgets are
-       reconciled against it.
-  - id: vocabulary_capability_context_guide
-    startup_command: agentera prime --context <capability> --format json
-    evidence: references/cli/vocabulary.md:90-113
-    consumed_fields:
-      - capability_context
-      - capability_context.instructions
-    notes: >-
-      Documentation consumer, not a runtime consumer: the vocabulary guide
-      tells capability consumers how to read the startup capsule. Reconciled
-      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: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.
-
-# ---------------------------------------------------------------------------
-# Field-authority reconciliation. The four lists that described the prime field
-# surface used to disagree (Task 1 documented the drift). Task 2 reconciled them
-# to one authority: PRIME_STRUCTURED_FIELDS in packages/cli/src/cli/stateQuery.ts
-# (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 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
-    location: packages/cli/src/cli/commands/prime/orientationOutput.ts
-    authority: packages/cli/src/cli/stateQuery.ts:PRIME_STRUCTURED_FIELDS
-    field_count: 27
-    role: actual_emission_authority
-    notes: >-
-      Emits PRIME_STRUCTURED_FIELDS as source_contract.fields; the keys actually
-      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
-    field_count: 27
-    role: schema_discovery
-    notes: >-
-      Reconciled by Task 2: availableStructuredFields for the prime selector
-      advertises PRIME_STRUCTURED_FIELDS plus the context-only capability_context
-      pointer (28 declared); fields_by_command.status advertises the 27-field
-      set. Previously drifted (missing project_integration and history).
-  - id: text_briefing_hardcoded
-    location: packages/cli/src/cli/commands/prime/orientationOutput.ts
-    authority: packages/cli/src/cli/stateQuery.ts:PRIME_STRUCTURED_FIELDS
-    field_count: 27
-    role: text_briefing
-    notes: >-
-      Reconciled by Task 2: the text-mode source_contract fields line is now
-      derived from PRIME_STRUCTURED_FIELDS.join so text and JSON advertise one
-      canonical representation. Previously hardcoded a 21-field subset.
-  - id: agent_ready_state_contract
-    location: references/cli/agent-ready-state-contract.yaml
-    authority: packages/cli/src/cli/stateQuery.ts:PRIME_STRUCTURED_FIELDS
-    field_count: 27
-    role: documented_consumer_contract
-    notes: >-
-      Reconciled by Task 2: both hej.fields lists now mirror the canonical
-      27-field set (retired `bundle` dropped; app, app_home, project_integration,
-      shared_skill, project_integration, and history added).
-
-# ---------------------------------------------------------------------------
-# Field classification. Every field proposed for omission is classified with a
-# rationale and the task that consumes the decision.
-#   required: always present in bare prime; consumers depend on it.
-#   conditional: default-only; Task 2 may omit when in default state, preserving
-#     missing-vs-empty semantics and named-command recovery.
-#   diagnostic: lifecycle/history detail; omitted from default startup unless
-#     status declares it necessary (Task 4 decision).
-#   deprecated_transition: emitted alias; removable at the 3.0.0 stable cut only.
-#   retired: not emitted; a consumer depending on it must fail visibly.
-# ---------------------------------------------------------------------------
-field_classification:
-  - field: command
-    status: required
-    rationale: REQUIRED_SPARSE_CONTEXT_FIELDS; emitted on every structured payload.
-  - field: status
-    status: required
-    rationale: REQUIRED_SPARSE_CONTEXT_FIELDS; every consumer gates on status=ok.
-  - field: app_home
-    status: required
-    rationale: Install/v1/profile safety; status text briefing prints app_home.
-  - field: app
-    status: required
-    rationale: publicDoctorStatus projection; app/v1/profile safety per source_contract.access.
-  - field: mode
-    status: required
-    rationale: Fresh-vs-returning routing; opencode and status consumers read it.
-  - field: profile
-    status: required
-    rationale: opencode reads profile.status; status dashboard glyph.
-  - field: v1_migration
-    status: conditional
-    rationale: >-
-      Default-only when detected=false. No documented consumer reads it in the
-      default startup path. Task 2 omits it from the default bare briefing when
-      not detected (see default_emission_omission_contract); recovery via
-      `agentera upgrade --dry-run`.
-  - field: health
-    status: required
-    rationale: opencode reads grade/trajectory; status dashboard glyph.
-  - field: todo
-    status: required
-    rationale: Status dashboard glyph; canonical replacement for the issues alias.
-  - field: plan
-    status: required
-    rationale: opencode reads exists/status/title/first_pending; status dashboard glyph.
-  - field: docs
-    status: conditional
-    rationale: >-
-      Default-only when no docs state. Task 2 omits it from the default bare
-      briefing when docs.exists is false (see default_emission_omission_contract);
-      recovery via `agentera state docs list --format json`.
-  - field: progress
-    status: required
-    rationale: opencode reads progress.latest; status brief references shipped work.
-  - field: objective
-    status: conditional
-    rationale: >-
-      Default-only when none active. Task 2 omits it from the default bare
-      briefing when objective.active is false (see
-      default_emission_omission_contract); status derives "none active" from
-      state_presence.active.objective. Recovery via
-      `agentera state objective list --format json`.
-  - field: state_presence
-    status: required
-    rationale: Owns missing-versus-empty semantics; must not be omitted.
-  - field: project_integration
-    status: required
-    rationale: >-
-      Status routing consumes the app and project-state recommendation; the
-      bounded brief retains that routing projection even when no upgrade
-      recommendation is active.
-  - field: attention
-    status: required
-    rationale: >-
-      Bounded; opencode and status dashboard consume it. Valid current glossary
-      caveats add at most one generic review item through the glossary authority's
-      declared prime projection. When current, its one reserved final slot leaves
-      the first five unrelated items in their existing order under the six-item
-      public cap; lifecycle identity and private semantics remain internal, and
-      next_action is unchanged.
-  - field: history
-    status: diagnostic
-    rationale: >-
-      Startup history. The bounded brief retains counts and named retrieval
-      pointers while omitting entry detail; explicit state list/get commands
-      recover the current history.
-  - field: shared_skill
-    status: required
-    rationale: >-
-      Canonical shared-skill status and read-only diagnosis. Bare prime omits
-      the privacy-sensitive absolute path; doctor or an explicit shared_skill
-      field read recovers full path diagnostics.
-  - field: decision_attention
-    status: conditional
-    rationale: Null unless returned decisions require satisfaction review.
-  - field: next_action
-    status: required
-    rationale: opencode and status routing; SKILL.md bare /agentera route follows it.
-  - field: orchestration_context
-    status: conditional
-    rationale: >-
-      Always null in bare prime; meaningful only in --context orchestrate. Task 2
-      may omit null bespoke contexts from the bare briefing without breaking
-      documented consumers.
-  - field: closeout_context
-    status: conditional
-    rationale: Always null in bare prime; meaningful only in --context document.
-  - field: evidence_context
-    status: conditional
-    rationale: Always null in bare prime; meaningful only in --context audit.
-  - field: benchmark_context
-    status: conditional
-    rationale: Always null in bare prime; meaningful only in --context optimize.
-  - field: execution_context
-    status: conditional
-    rationale: Always null in bare prime; meaningful only in --context build.
-  - field: source
-    status: required
-    rationale: Provenance; artifacts_present drives fresh-vs-returning dashboard.
-  - field: source_contract
-    status: required
-    rationale: Declares fields, capability_startup, capability_context, artifact_writes.
-  - field: capability_context
-    status: conditional
-    rationale: >-
-      Declared available on the `prime` selector but emitted only by the
-      `--context <capability>` surface (buildPrimeCapabilityContextPayload),
-      NOT by the default bare briefing. The bare briefing instead carries a
-      `source_contract.capability_context` pointer with a `fetch_command`. The
-      capability_context_dispatcher consumer depends on it. Required when
-      present; its nested `instructions` field is the capability's startup
-      instructions module (runtime authority: capabilityContext/startup.ts:250).
-      Task 2 may keep it off the bare default; Tasks 3-4 must not break the
-      `--context` capsule that emits it.
-  - field: issues
-    status: deprecated_transition
-    rationale: >-
-      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: >-
-      v2-era field renamed to `app`/`app_home` in v3. agent-ready-state-contract
-      still documents it (drift); it is not emitted. A consumer depending on it
-      must fail visibly (see fail fixtures).
-
-# ---------------------------------------------------------------------------
-# Approved public-output policy for Tasks 2-4. Unambiguous so each later task
-# can make emission decisions without re-litigating compatibility.
-# ---------------------------------------------------------------------------
-public_output_policy:
-  canonical_field_set: >-
-    The emitted STATUS_STRUCTURED_FIELDS (27) is the single consumer-facing
-    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:
-    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
-    semantics stay distinguishable and a named authoritative command returns the
-    current detail (`agentera state <artifact>`, `agentera schema`,
-    `agentera upgrade --dry-run`). Null bespoke contexts
-    (orchestration/closeout/evidence/benchmark/execution) may be omitted from
-    the bare briefing; they remain declared on the `--context` surface.
-  bounded_brief_rule: >-
-    Task 3 produces a bounded default decision brief (<=12000 bytes pretty
-    UTF-8 JSON + trailing newline; diagnostics on stderr) that retains every
-    required field plus any active conditional field, and never collapses
-    missing versus present-but-empty.
-  self_contained_status_rule: >-
-    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, 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. The nested status projection keeps
-      source_contract.capability_startup and source_contract.empty_state, and
-      omits bare-prime source inventory metadata that the dashboard does not
-      consume. When the envelope 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
-      - plan
-      - profile
-      - next_action
-      - 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: >-
-    Undeclared or retired field dependencies must fail visibly: selecting an
-    undeclared field via `--fields` returns nonzero exit code 1 and a correction
-    listing the declared available fields. Tasks 2-4 must preserve this
-    contract after any field-set change.
-
-# ---------------------------------------------------------------------------
-# Default-emission conditional omission contract. Advertised selectable fields
-# (declared_available_fields / PRIME_STRUCTURED_FIELDS) may be broader than the
-# keys present in a given bare prime response: the declaration is the union of
-# fields a consumer may select, not a promise that every one is emitted on every
-# call. The following conditional top-level fields are OMITTED from the default
-# bare briefing when they carry only default/inactive payload so startup does not
-# carry adjective noise. Their omission is unambiguous because (a) the field
-# stays declared in source_contract.fields as a selectable surface, (b)
-# state_presence carries the missing-vs-empty signal for the artifact families
-# it owns, and (c) a named authoritative command returns the live detail.
-# Required consumers and missing-vs-empty semantics are preserved: explicit
-# `--fields <name>` selection and the `--context` capsule keep the full payload,
-# so a consumer recovering an omitted field is never confused by its absence.
-# The emitted `issues` deprecated transition alias is NOT conditional: it ships
-# by default (excluded only from the canonical advertised set) until the stable
-# cut; see deprecated_alias_rule.
-# ---------------------------------------------------------------------------
-default_emission_omission_contract:
-  implemented_by: packages/cli/src/cli/commands/prime/orientationOutput.ts:omitInactiveConditionalDefaults
-  applies_to: default bare prime (requested fields empty)
-  does_not_apply_to: explicit `--fields <name>` selection; `--context <capability>` capsule
-  omitted_when_default:
-    - field: v1_migration
-      omitted_when: v1_migration.detected !== true
-      recovery_command: agentera upgrade --dry-run
-      disambiguated_by: >-
-        source_contract.fields declares v1_migration as a selectable field; the
-        named recovery command returns the live migration preview. state_presence
-        does not carry v1_migration (it is not an artifact family); the field is
-        the sole v1 signal.
-    - field: docs
-      omitted_when: docs.exists !== true
-      recovery_command: agentera state docs list --format json
-      disambiguated_by: >-
-        state_presence.available.docs and state_presence.absence.docs carry the
-        missing-vs-empty signal for the docs artifact family.
-    - field: objective
-      omitted_when: objective.active !== true
-      recovery_command: agentera state objective list --format json
-      disambiguated_by: >-
-        state_presence.active.objective is false; status derives "none active"
-        from state_presence rather than from an emitted default-only objective
-        blob.
-  never_omitted:
-    - state_presence
-    - next_action
-    - health
-    - todo
-    - plan
-    - progress
-    - profile
-    - source
-    - source_contract
-    - attention
-
-  # Task 3 bounded decision brief. The default bare emission projects the full
-  # orientation payload to a bounded decision brief (<=12000 bytes pretty UTF-8
-  # JSON + trailing newline; diagnostics on stderr). Every required top-level
-  # field stays PRESENT (compatibility_boundary test asserts the key set); only
-  # rich diagnostic/writer detail WITHIN those fields is projected to
-  # routing-essential leaves. Each projected sub-detail carries a named
-  # authoritative recovery command so an agent never needs raw artifact access.
-  # `--dashboard` (full fidelity, 35000-byte budget), `--fields <name>`, and the
-  # `--context` capsule are NOT projected and keep the full payload. The byte
-  # gate is deterministic pretty-JSON UTF-8 measurement; an over-budget brief is
-  # rejected in favor of a bounded degraded envelope (status ok, brief.status
-  # signals degraded). Every successful envelope keeps bounded plan selection,
-  # executable next_action, canonical history evidence, profile,
-  # state_presence, source_contract, and the byte-budget recovery.
-  brief_omission_contract:
-    implemented_by: packages/cli/src/cli/commands/prime/briefOrientation.ts:briefOrientationPayload
-    applies_to: default bare prime (no --fields, no --dashboard, no --context)
-    does_not_apply_to: "agentera prime --dashboard --format json; --fields <name>; --context <capability>"
-    budget_utf8_bytes: 12000
-    measurement: >-
-      Buffer.byteLength(JSON.stringify(brief, null, 2) + "\n", "utf8"); stdout
-      only; diagnostics measured separately on stderr.
-    retained_top_level_fields: >-
-      Every field in never_omitted plus command, status, app_home, app, mode,
-      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 count-only
-      transition projection and excludes canonical todo.detail.
-    projected_subdetail:
-      - field: startup.path_diagnostics
-        reason: startup_path_diagnostics
-        recovery: agentera doctor --format json
-      - field: plan.tasks
-        reason: plan_task_detail
-        recovery: agentera state plan tasks list --format json
-      - field: plan.archived_plans
-        reason: archive_catalog
-        recovery: agentera state plan list --format json
-      - field: plan.diagnostics
-        reason: plan_diagnostics
-        recovery: agentera state plan list --format json
-      - field: history.progress.entries
-        reason: startup_history_entries
-        recovery: agentera state progress list --format json
-      - field: history.decisions.entries
-        reason: startup_history_entries
-        recovery: agentera state decisions list --format json
-      - field: history.health.entries
-        reason: startup_history_entries
-        recovery: agentera state health list --format json
-      - field: project_integration.phases
-        reason: phase_blockers
-        recovery: agentera doctor --format json
-      - field: source_contract.artifact_writes.artifacts
-        reason: writer_contract_detail
-        recovery: agentera schema --format json
-      - field: source_contract.capability_startup.available_state
-        reason: startup_available_state_listing
-        recovery: agentera schema --format json
-      - field: profile.bounded_signals
-        reason: profile_signal_detail
-        recovery: agentera profile --format json
-    history_projection:
-      count_fields: [total, returned, remaining, full, summary]
-      degraded_fields: [caveats, degraded_history]
-      provenance_fields: [source_contract]
-      recovery_fields: [retrieval.list, retrieval.get]
-      semantics: >-
-        Progress, decisions, and health retain canonical entity-history counts.
-        A degraded or compacted history retains bounded caveats, explicit
-        summary-only counts, source-contract provenance, and exact list/get
-        pointers. It never reconstructs omitted records or infers decision
-        satisfaction; explicit firm, provisional, missing, compacted, and
-        review-needed evidence remains unchanged when present.
-    never_collapsed: >-
-      state_presence is projected to its finite contract-owned active, available,
-      any_active, absence_explained, and absence keys rather than copied verbatim;
-      known boolean values and absence reasons remain bounded, so missing versus
-      present-but-empty stays behaviorally distinguishable even for adversarial
-      caller objects. source_contract is likewise projected to bounded known
-      fields and named recovery pointers. Every successful normal or degraded
-      envelope keeps plan.first_pending identity, dependencies, acceptance, and
-      exact task get; next_action keeps its executable identity, capability,
-      phase, eligibility, and exact retrieval. Canonical history counts,
-      degraded caveats, and exact history recovery remain bounded consumer
-      evidence. Every bare-prime projection omits absolute app-home,
-      source-root, shared-skill, schema, and project path diagnostics while
-      retaining app/shared-skill status, stable source identity, truthful
-      presence, and doctor recovery. brief.path_diagnostics_recovery retains
-      that doctor command even when compact or irreducible metadata omits the
-      full recovery catalog. Normal and degraded projections retain bounded progress and
-      health signals; degraded projections also retain bounded TODO counts and
-      attention. Optional startup paths, plan task catalogs, and next-action
-      alternatives compact before selected routing or canonical history evidence.
-    fallback_behavior: >-
-      The detailed degraded envelope is byte-gated again after utf8_bytes is
-      settled. If it cannot fit, the recovery catalog, optional source-contract
-      detail, next-action alternatives, and free text compact proportionally
-      before selected plan, executable next_action, or canonical history
-      evidence. A compact and then irreducible finite routing envelope are tried
-      deterministically. If the configured budget cannot hold that routing
-      evidence, briefOrientationPayload fails explicitly rather than returning
-      exit zero without an executable task or emitting over-budget stdout.
-
-# ---------------------------------------------------------------------------
-# Fixtures used by packages/cli/test/cli/primeCompatibilityBoundary.test.ts.
-# Pass fixtures are the documented consumers; their consumed_fields must be a
-# subset of declared_available_fields. Fail fixtures depend on retired or
-# undeclared fields and must fail visibly through the fail_visible_rule.
-# ---------------------------------------------------------------------------
-declared_available_fields:
-  - command
-  - status
-  - app_home
-  - app
-  - mode
-  - profile
-  - v1_migration
-  - health
-  - todo
-  - plan
-  - docs
-  - progress
-  - objective
-  - state_presence
-  - project_integration
-  - attention
-  - history
-  - shared_skill
-  - decision_attention
-  - next_action
-  - orchestration_context
-  - closeout_context
-  - evidence_context
-  - benchmark_context
-  - execution_context
-  - source
-  - source_contract
-  - capability_context
-  - issues
-fixtures:
-  pass:
-    - consumer: status_dashboard_renderer
-      executable_command: agentera prime --context status --format json
-      depends_on:
-        - capability_context
-      nested_fields:
-        - capability_context.instructions
-        - capability_context.context.status_context.health
-        - capability_context.context.status_context.todo
-        - capability_context.context.status_context.plan
-        - capability_context.context.status_context.profile.status
-        - capability_context.context.status_context.next_action.object
-        - capability_context.context.status_context.attention
-        - capability_context.context.status_context.state_presence
-        - capability_context.context.status_context.source_contract
-      conditional_nested_fields:
-        # objective is a conditional top-level field (see
-        # default_emission_omission_contract): emitted when an objective is
-        # active, omitted (and rendered "none active") otherwise. The dashboard
-        # derives the active/none-active signal from state_presence, so it does
-        # not declare objective as an always-present dependency.
-        - path: capability_context.context.status_context.objective
-          present_when: capability_context.context.status_context.state_presence.active.objective
-    - consumer: capability_context_dispatcher
-      executable_command: agentera prime --context build --format json
-      depends_on:
-        - command
-        - status
-        - capability_context
-      nested_fields:
-        - capability_context.instructions
-      absent_fields:
-        - capability_context.prose
-    - consumer: packaging_distribution_gate
-      executable_command: agentera prime --format json
-      depends_on:
-        - command
-        - status
-        - app_home
-      nested_fields:
-        - app_home.source
-      asserts:
-        - path: command
-          equals: prime
-        - path: status
-          equals: ok
-    - consumer: bare_agentera_route
-      executable_command: agentera prime --format json
-      depends_on:
-        - next_action
-        - source_contract
-      nested_fields:
-        - source_contract.capability_context
-        - next_action.object
-  fail:
-    - consumer: v2_bundle_consumer
-      depends_on:
-        - bundle
-      executable_command: agentera prime --fields bundle --format json
-      rationale: >-
-        `bundle` was renamed to `app`/`app_home` in v3 and is not emitted.
-        Selecting it via `--fields bundle` must return exit code 1 with a
-        correction listing the declared available fields.
-
-# ---------------------------------------------------------------------------
-# Documentation drift guard. Active consumer guidance must not send consumers
-# to the retired `prose` field; the runtime emits `instructions` only (see
-# capability_context_dispatcher fixture for the executable proof). Each entry
-# names a documentation file that governs the consumer field name; the test
-# suite scans the live file so the documented field cannot drift back.
-# ---------------------------------------------------------------------------
-documentation_drift:
-  canonical_field: capability_context.instructions
-  retired_field: capability_context.prose
-  scanned_documents:
-    - id: vocabulary_capability_context_contract
-      path: references/cli/vocabulary.md
-      evidence: references/cli/vocabulary.md:90-113
-      governs: the `--context` capsule field capability consumers are told to read
-      must_contain: capability_context.instructions
-      must_not_contain: capability_context.prose
-
-approval:
-  recorded_for_tasks: [2, 3, 4]
-  decision: >-
-    The compatibility boundary above is approved. Tasks 2-4 implement emission
-    changes within this policy without re-deriving consumer compatibility.
-  recorded_at: 2026-07-16