agentera 3.0.0-dev.4 → 3.0.0-dev.41

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

@@ -0,0 +1,701 @@
+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