agentera 3.0.0-dev.21 → 3.0.0-dev.23

package/README.md

@@ -12,9 +12,13 @@ npx -y agentera@next prime --format json
 npx -y agentera@next doctor --format json
 ```
 
-`prime` returns a bounded project and four-runtime lifecycle summary. `doctor`
-returns detailed read-only evidence and exact user actions. The status and
-project-integration projections consume the same lifecycle snapshot.
+`prime --format json` returns a bounded decision brief (at most 12000 UTF-8
+bytes); use `prime --dashboard --format json` for the full orientation payload.
+Status startup is one call: `prime --context status --format json` returns
+`capability_context.instructions` and bounded
+`capability_context.context.status_context` together (at most 25000 UTF-8
+bytes). Omitted detail names its authoritative recovery command. `doctor`
+returns detailed read-only evidence and exact user actions.
 
 ## Runtime lifecycle
 

package/bundle/.cursor/agents/agentera.md

@@ -4,4 +4,4 @@ description: Turn your coding agent into an engineering team.
 
 <!-- agentera: managed -->
 
-Load the Agentera skill for request routing and project orientation. When a capability is invoked, run `agentera prime --context build --format json` (or the relevant capability name) to fetch the authoritative instructions as a JSON capsule, then dispatch to a general-purpose subagent with the `prose` field as the task prompt. Do not invent unsupported capability-name CLI commands. Do not invoke per-capability subagents; the single Agentera agent handles all capability dispatch.
+Load the Agentera skill for request routing and project orientation. When a capability is invoked, run `agentera prime --context build --format json` (or the relevant capability name) to fetch the authoritative instructions as a JSON capsule, then dispatch to a general-purpose subagent with the `capability_context.instructions` field as the task prompt. Do not invent unsupported capability-name CLI commands. Do not invoke per-capability subagents; the single Agentera agent handles all capability dispatch.

package/bundle/.opencode/agents/agentera.md

@@ -9,4 +9,4 @@ permission:
 
 <!-- agentera: managed -->
 
-Load the Agentera skill for request routing and project orientation. When a capability is invoked, run `agentera prime --context build --format json` (or the relevant capability name) to fetch the authoritative instructions as a JSON capsule, then dispatch to a general-purpose subagent with the `prose` field as the task prompt. Do not invent unsupported capability-name CLI commands. Do not invoke per-capability subagents; the single Agentera agent handles all capability dispatch.
+Load the Agentera skill for request routing and project orientation. When a capability is invoked, run `agentera prime --context build --format json` (or the relevant capability name) to fetch the authoritative instructions as a JSON capsule, then dispatch to a general-purpose subagent with the `capability_context.instructions` field as the task prompt. Do not invent unsupported capability-name CLI commands. Do not invoke per-capability subagents; the single Agentera agent handles all capability dispatch.

package/bundle/CHANGELOG.md

@@ -4,11 +4,19 @@
 
 ### Changed
 
+- Split lifecycle validation orchestration from the public validation facade while preserving its import surface and validation behavior.
+- Eliminated the monolithic `corpus.json` publication output from the extract CLI; report dry-run diagnostics now reference tier files and the `privacy.corpus_write` field is renamed to `privacy.tier_write`.
+- Changed `agentera check lint` verbosity checks to consume schema-owned full-file and per-entry word limits, skip no-limit and token-only dimensions, and report authority failures without fallback budgets.
 - Corrected packaged experiment-publication authority to declare validated objective-scoped archive-before-projection ownership and reject contradictory structured scope metadata.
 - Synchronized bounded plan, plan-task, and experiment retrieval across help, schema introspection, capability guidance, operator docs, packaged contracts, output bounds, archive ownership, and structured recovery errors.
 
 ### Added
 
+- Added an authoritative evidence-tier contract (`references/analysis/evidence-tier-authority.yaml`) and contract-model loader (`packages/cli/src/registries/evidenceTierContract.ts`) fixing the bounded full-evidence and signal tiers, supported Codex, Cursor, OpenCode, Copilot, and historical Claude source coverage, the consumer field-supply map including the latent startup-analysis reader, reserved signal semantics for the deferred glossary, and deterministic recovery outcomes for oversized, legacy, missing, corrupt, and incomplete state.
+- Added bounded tier publication and direct retrieval (`packages/cli/src/analytics/extractCorpus/evidenceTiers.ts`): complete local evidence is retained as independently bounded, source-family shards that split when exceeding the reader cap; a derived, content-addressable bounded signal tier carries only contract-required fields plus a resolvable `evidence_anchor`; generations are staged and revealed by an atomic current-pointer swap so no consumer observes a partial publication; and direct retrieval resolves a signal identity to its full record. The monolithic `corpus.json` write is eliminated; tiers are the only canonical publication output.
+- Added bounded tier-aware reads for usage analytics, report status, prime corpus coverage, startup analysis, and profile synthesis so every analytics consumer reads from bounded evidence shards one at a time instead of loading the monolithic `corpus.json`. A new `tierReader.ts` module projects contract compatibility states and recovery guidance, streams full-evidence records, and reads signal-tier metadata. A new `profileSignals.ts` module reads the bounded signal tier, assesses per-family retention sufficiency against the contract threshold, and resolves synthesized claims' evidence anchors to retained full-evidence shards. Legacy `corpus.json` remains a fallback when no tiers are published; oversized legacy state is never loaded whole.
+- Added a schema-owned verbosity-budget authority that classifies numeric word limits, explicit no-limit declarations, and token-only budgets while rejecting malformed, ambiguous, unreadable, and unsupported ownership without fallback limits.
+- Added a `profile_sufficiency` section to the evidence-tier authority defining `minimum_family_retention=0.5`, profile signal types (decision, question, correction, instruction, configuration), and insufficiency rules so bounded profile synthesis surfaces underrepresented families without fabricating confidence.
 - Added `agentera state experiments list|get --objective OBJECTIVE_ID` with newest-first bounded pages, snapshot-bound opaque cursors, merged projection/archive identity, verified archive-first detail, explicit provenance and detail availability, and structured compatibility failures.
 - Added objective-scoped immutable full-detail archives under `.agentera/optimize/<objective>/archive/experiments/<number>.yaml` before 10/40/50 projection replacement, with explicit provenance, conflict rejection, and crash-consistent idempotent retries.
 - Added `agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml` with schema and identity preflight, atomic projection replacement, idempotent interruption retry, collision safety, and existing 10/40/50 projection behavior.
@@ -16,6 +24,7 @@
 - Added `agentera state plan list` and `agentera state plan get --plan PLAN_ID` for deterministic, cursor-paginated active and archived plan retrieval, full-plan exact reads, lifecycle provenance, and explicit legacy, invalid, missing, and ambiguous archive outcomes.
 - Added persisted plan identity across active-to-archive transitions, deterministic read-only identity for legacy plans, explicit lifecycle provenance, mirrored-path reporting, and structured ambiguity failures for identity collisions.
 - Added `agentera state plan tasks list` and `agentera state plan tasks get --task N` for bounded active-plan task retrieval with declared task-number order, opaque snapshot cursors, structured not-found and compatibility errors, and exact omission recovery in text and JSON plan output.
+- Added `agentera state decisions amend --number N [--question ... --context ... --alternative-chosen ... --alternative-rejected ... --choice ... --reasoning ... --confidence firm|provisional|exploratory --feeds-into ...] [--dry-run] --format json`: validates and publishes a record-local revision under `.agentera/revisions/decisions.yaml` that composes over the immutable numbered archive at read time. Apply never rewrites the decisions projection, preserves unrelated decisions' bytes (including comments, block scalars, quoting, and inherited legacy confidence labels), refuses a broken revision document or unsafe record-local boundary without side effects, retries converge on a stable revision identity, and an identical re-submission is an idempotent replay. Append, satisfaction update, and amend tolerate untouched inherited confidence labels as explicit legacy caveats while requiring current vocabulary for new or amended content.
 
 - Added an executable bounded-retrieval authority and reserved CLI grammar for plan tasks, plans, and objective-scoped experiments, including stable and legacy identity rules, experiment `0`, opaque cursors, explicit omissions, and structured compatibility errors; retrieval execution remains staged for subsequent tasks.
 - Added a canonical runtime lifecycle projection with deterministic snapshot identity, applicability, ownership, action classes, counts, and command eligibility for OpenCode, Codex, Cursor, and Copilot.
@@ -73,6 +82,8 @@
 
 ### Fixed
 
+- Fixed the npm shim to diagnose a configured `AGENTERA_HOME` whose managed script is missing or not runnable before continuing through repository and `uvx` fallback resolution.
+- Fixed `agentera check lint` to report findings without failing by default, fail the same findings with `--strict`, and keep invalid input, authority failures, and validated plan publication nonzero.
 - Fixed schema/runtime alias parity: introspection now advertises exactly the six Phase 3 transitional aliases, Build startup and compaction guidance use canonical `agentera check compact`, check/fix output reports `command: "check compact"`, top-level `compact` remains behavior-compatible, and removed names such as `gate` return structured runnable corrections.
 - Fixed archive-only plan catalogs to expose executable list/get recovery, plan-task cursors to validate explicit plan selectors before lookup, and legacy plan text to omit oversized whole rows instead of truncating Unicode scalars.
 - Fixed bounded plan and experiment retrieval to declare legacy projection omissions with public recovery, enforce plan-task YAML byte limits, reject wrong-family and wrong-objective cursors, and fail closed when plan snapshot diagnostics change.

package/bundle/references/analysis/evidence-tier-authority.yaml

@@ -0,0 +1,516 @@
+schema_version: agentera.evidenceTierAuthority.v1
+status: active_authority
+purpose: >-
+  Define the authoritative tier model for local agent-history evidence so that
+  bounded consumers receive useful analysis at realistic corpus scale instead
+  of degrading solely because complete local evidence exceeds a single-reader
+  limit. The contract fixes the tiers, supported source families, the consumer
+  map, the required signal semantics, and the deterministic compatibility
+  outcomes for oversized, legacy, missing, corrupt, and incomplete state. It is
+  the single source of truth for what every bounded input contract must supply.
+
+authority:
+  source: references/analysis/evidence-tier-authority.yaml
+  single_source_rule: >-
+    Extraction, readers, validators, tests, help, and capability source
+    contracts may project this authority but must not create a second map of
+    tiers, source families, consumer required fields, signal semantics,
+    compatibility outcomes, or evidence bounds. A consumer that needs a field
+    declares it here; a field declared here is the only name a consumer may
+    require from a bounded tier.
+  implementation_boundary: >-
+    This contract defines and verifies the tier model, source coverage, signal
+    semantics, consumer field supply, and compatibility outcomes. It does not
+    implement the complete extraction writer, migrate consumers to bounded
+    tiers, change profile levels, generate a glossary, or alter suite version
+    metadata. Tasks 2 through 4 of the approved plan implement publication,
+    consumer migration, and bounded profile synthesis against this contract.
+
+decision_55_reconciliation:
+  decision_number: 55
+  date: 2026-05-17
+  preserved_intent: >-
+    Decision 55 established `agentera stats` as the user-facing analytics
+    workflow, forbade a top-level `agentera corpus` command, bound local
+    history to explicit consent, and wrote the internal corpus to a single
+    `$AGENTERA_PROFILE_DIR/intermediate/corpus.json` envelope. The intent
+    survives: analytics remain behind `agentera stats`/`agentera usage`, no
+    `agentera corpus` namespace is introduced, and local-history extraction
+    remains consent-bound and read-only.
+  superseded_surface: >-
+    The single monolithic `corpus.json` envelope is superseded by the tier
+    model below. Complete local evidence is retained as independently bounded
+    shards; a derived bounded signal view replaces the monolithic record array
+    as the analytic input. Decision history itself is not rewritten: the
+    decision record stands as adopted, and this reconciliation is recorded in
+    the tier authority rather than by editing the decision.
+  non_goal: >-
+    Do not rewrite, renumber, or restate Decision 55's adopted text. Do not
+    introduce `agentera corpus` or any new top-level analytics command.
+
+tiers:
+  full_evidence:
+    tier_id: full_evidence
+    rank: 1
+    definition: >-
+      Complete local evidence retained as independently bounded shards. Every
+      record ever extracted from a supported source is addressable here; nothing
+      is dropped to fit a reader limit. Each shard is independently bounded so a
+      single oversized shard cannot poison the whole tier.
+    stored_fields:
+      required:
+        - source_id
+        - source_kind
+        - timestamp
+        - project_id
+        - runtime
+        - source_class
+        - source_product
+        - active_runtime
+        - adapter_version
+        - data
+      optional:
+        - project_path
+        - session_id
+        - conversation_key
+    source_identity_rule: >-
+      `source_id` is the stable, content-addressable identity of one full
+      record. It is derived deterministically from source kind and source parts
+      and must resolve to exactly one retained full-evidence shard. No other
+      tier may invent identities that do not resolve here.
+    completeness_rule: >-
+      The union of full-evidence shards is the lossless local history for the
+      selected source scope. Consumers that need an entire record read it here;
+      consumers that need only a derived view read the signal tier instead.
+  signal:
+    tier_id: signal
+    rank: 2
+    definition: >-
+      A reproducible, bounded, derived view of the full-evidence tier. It
+      carries only the fields each declared consumer needs plus a resolvable
+      evidence anchor back to full evidence. It is small enough to load under
+      the reader bound even when the full-evidence tier is hundreds of
+      megabytes.
+    stored_fields:
+      required:
+        - source_id
+        - source_kind
+        - signal_type
+        - timestamp
+        - project_id
+        - runtime
+        - source_product
+        - evidence_anchor
+      optional:
+        - conversation_key
+        - session_id
+    derivation_rule: >-
+      The signal tier is a pure function of the full-evidence tier: identical
+      inputs produce identical signal membership and ordering. It never stores
+      transcript text, raw tool arguments, raw store paths, or raw session ids
+      beyond what a declared consumer requires with provenance visible.
+    evidence_anchor_rule: >-
+      Every signal record carries `evidence_anchor` resolving to the
+      `source_id` of exactly one retained full-evidence shard. A bounded
+      consumer that needs the full record follows the anchor; it must not
+      re-scan unbounded history.
+
+source_families:
+  coverage_rule: >-
+    The supported source families are fixed. A source family is either supplied
+    by an active runtime or imported as historical Claude history. No supported
+    family may be silently omitted from the contract, the coverage audit, or
+    the compatibility evaluation. An unavailable family reports a deterministic
+    discovery status; it is never absent from the map.
+  families:
+    codex:
+      source_class: active_runtime
+      source_product: codex
+      active_runtime: true
+      accepted_input: JSONL session/turn/response_item and tool_call records
+      store_glob: "*.jsonl"
+    cursor:
+      source_class: active_runtime
+      source_products:
+        - cursor
+        - cursor-agent
+      active_runtime: true
+      accepted_input: >-
+        Cursor project JSONL sessions and Cursor Agent CLI store.db SQLite
+        conversations. cursor-agent is a Cursor source product, never a
+        separate runtime identity.
+      store_glob: "*.jsonl"
+    opencode:
+      source_class: active_runtime
+      source_product: opencode
+      active_runtime: true
+      accepted_input: SQLite opencode.db with session, message, and part tables
+      store_glob: opencode.db
+    copilot:
+      source_class: active_runtime
+      source_product: github-copilot
+      active_runtime: true
+      accepted_input: SQLite session-store.db with conversation message rows
+      store_glob: session-store.db
+    claude-code:
+      source_class: historical_import
+      source_product: claude-code
+      active_runtime: false
+      inclusion_rule: >-
+        Explicit `--import-source claude` only. Excluded from default
+        active-runtime metrics and never described as runtime health, Claude
+        support, or active-runtime coverage.
+      accepted_input: JSONL project session files with user/assistant and tool_use events
+      store_glob: "*.jsonl"
+  filesystem_substrate:
+    note: >-
+      instruction_document and project_config_signal records are extracted
+      from the project filesystem (AGENTS.md, package manifests, config files).
+      They are source kinds, not runtime families, and follow source identity
+      and bounds rules like any other record.
+
+signal_semantics:
+  fixed_taxonomy_rule: >-
+    The signal semantics below are fixed. Current consumers and the deferred
+    glossary consumer depend on their meaning; the contract must preserve that
+    meaning even though glossary implementation and profile levels remain out
+    of scope. A semantic kind present here must remain derivable from a bounded
+    signal record without restoring unbounded transcript content.
+  kinds:
+    correction:
+      meaning: >-
+        A user signal that revises a prior position ("no", "not quite",
+        "actually", "instead"). Used to detect decision drift and overrides.
+      derivable_from: history_prompt and conversation_turn records
+      deferred_consumer: glossary
+    decision:
+      meaning: >-
+        A decision-bearing signal (decide, prefer, trade-off, scope, approve,
+        reject). The primary profile-synthesis input.
+      derivable_from: history_prompt and conversation_turn records
+      deferred_consumer: glossary
+      current_consumer: profile_synthesis
+    question:
+      meaning: >-
+        An interrogative signal ("why", "how", "should", or a "?"). Surfaces
+        uncertainty and information-gathering intent.
+      derivable_from: history_prompt and conversation_turn records
+      deferred_consumer: glossary
+    instruction:
+      meaning: >-
+        Explicit user-authored instructions (AGENTS.md and project memory
+        documents). The highest-signal, most durable evidence.
+      derivable_from: instruction_document records
+      deferred_consumer: glossary
+      current_consumer: profile_synthesis
+    configuration:
+      meaning: >-
+        Recurring config patterns across projects (manifest names, scripts,
+        dependencies, build/tool config). Objective evidence of what shipped.
+      derivable_from: project_config_signal records
+      deferred_consumer: glossary
+      current_consumer: profile_synthesis
+    record_identity:
+      meaning: >-
+        The stable, addressable identity (`source_id`) of one full record. Lets
+        any consumer cite evidence without retaining its content.
+      derivable_from: every record's source_id
+      deferred_consumer: glossary
+    date:
+      meaning: >-
+        The record timestamp anchoring evidence in time. Drives decay,
+        recency, and watermark windows.
+      derivable_from: every record's timestamp field
+      deferred_consumer: glossary
+    evidence_anchor:
+      meaning: >-
+        The resolvable link from a bounded signal record back to exactly one
+        retained full-evidence shard. Guarantees that bounded analysis never
+        severs the citation chain.
+      derivable_from: signal record evidence_anchor -> full_evidence source_id
+      deferred_consumer: glossary
+  preservation_rule: >-
+    Fixing the contract must not remove the required meaning of any kind above
+    from current or declared deferred consumers. A deferred consumer (glossary)
+    is named here so the contract reserves the fields and semantics it will
+    need, even though its implementation is out of scope.
+
+consumer_map:
+  supply_rule: >-
+    Each supported consumer maps to exactly one bounded input contract that
+    supplies every required field with source identity. The input tier is the
+    smallest sufficient tier; consumers that need full records read
+    full_evidence, others read signal. No consumer may require a field not
+    declared in its input contract.
+  consumers:
+    usage_stats:
+      tier: signal
+      purpose: Skill-invocation analytics and USAGE.md reporting
+      required_fields:
+        - source_kind
+        - timestamp
+        - project_id
+        - runtime
+        - source_product
+      source_identity: source_id with source_product provenance
+      input_contract: signal tier conversation_turn projection
+    report_status:
+      tier: signal
+      purpose: Truthful corpus/coverage status (missing, stale, available)
+      required_fields:
+        - source_kind
+        - source_product
+      source_identity: tier presence and discovery status per source family
+      input_contract: signal tier metadata projection
+    prime_coverage:
+      tier: signal
+      purpose: Prime startup coverage of supported sources and selected scope
+      required_fields:
+        - runtime
+        - source_product
+        - source_class
+        - active_runtime
+      source_identity: available/selected/skipped per source family
+      input_contract: signal tier coverage projection
+    startup_analysis:
+      tier: signal
+      purpose: >-
+        Latent startup-analysis reader measuring state-gathering overhead. Reads
+        conversation_turn and tool_call signals; full tool arguments stay in
+        full_evidence.
+      required_fields:
+        - source_kind
+        - timestamp
+        - runtime
+        - source_class
+        - source_product
+        - evidence_anchor
+      source_identity: source_id and evidence_anchor to full evidence
+      input_contract: signal tier conversation_turn + tool_call projection
+    profile_synthesis:
+      tier: signal
+      purpose: Current profile synthesis (PROFILE.md) from bounded signals
+      required_fields:
+        - source_kind
+        - signal_type
+        - timestamp
+        - project_id
+        - runtime
+        - source_product
+        - evidence_anchor
+      source_identity: source_id and evidence_anchor for every synthesized claim
+      input_contract: signal tier instruction/decision/question/config projection
+  deferred_consumers:
+    glossary:
+      tier: signal
+      status: declared_deferred
+      required_semantics:
+        - correction
+        - decision
+        - question
+        - instruction
+        - configuration
+        - record_identity
+        - date
+        - evidence_anchor
+      rule: >-
+        The glossary is out of scope to implement, but its required semantics
+        are fixed here so the signal contract reserves them. Implementation must
+        not drop a reserved semantic or remove the field that carries it.
+
+profile_sufficiency:
+  question: >-
+    Does bounded profile synthesis preserve useful evidence distribution
+    compared with the current full-corpus intent? (planning Unknown 2)
+  profile_signal_types:
+    - decision
+    - question
+    - correction
+    - instruction
+    - configuration
+  prior_intended_distribution: >-
+    The prior intended distribution is the complete set of profile-relevant
+    signals (the profile_signal_types above) across all supported source
+    families, mirroring what a full-corpus read would have surfaced before
+    tiering. The signal tier's derivation is total when no cap is applied:
+    every full-evidence record yields exactly one signal, so the bounded and
+    intended distributions are identical. The comparison below is the safety
+    net that detects when signal selection reduces a family below a useful
+    threshold.
+  threshold_rule: >-
+    Profile synthesis is sufficient when the signal tier is uncapped (retained
+    == total) or every profile-relevant source family retains at least the
+    minimum representative fraction of its intended decision-bearing signals.
+    A family with zero intended signals is not a sufficiency violation; a
+    family with intended signals that retains none is.
+  minimum_family_retention: 0.5
+  minimum_family_retention_note: >-
+    The minimum per-family retention is 0.5 (half of the family's intended
+    profile-relevant signals). Below this, a family is underrepresented and
+    profile synthesis must surface the limitation rather than silently reduce
+    confidence for that family's contributions. The threshold is deliberately
+    lenient because proportional-per-family selection already preserves the
+    relative distribution; the check exists to catch a cap severe enough to
+    distort a family's evidence below a useful floor.
+  insufficiency_rule: >-
+    When insufficient, profile synthesis surfaces the underrepresented families
+    with their retained and intended counts, caps confidence for affected
+    categories to the single-signal band (CS4, 30-49) or below, and never
+    fabricates high-confidence claims from sparse or missing evidence. The
+    limitation is reported in the profile output and exit signal, not silently
+    absorbed.
+  derivation: >-
+    Resolves planning Unknown 2. The comparison is reproducible: identical
+    full evidence yields an identical sufficiency assessment because signal
+    derivation and selection are deterministic (Unknown 1). The prior
+    intended distribution is reconstructed from the signal tier's selection
+    report (total per family) and the retained distribution from the published
+    signal records (retained per family), so the comparison needs no separate
+    full-corpus read.
+
+bounds:
+  reader_byte_cap: 67108864
+  reader_byte_cap_note: >-
+    64 MiB. Existing bounded readers cap monolithic reads at this size and
+    safely degrade. The tier model replaces "safely degrade" with "useful
+    analysis" by feeding consumers bounded tiers that fit under this cap even
+    when complete local evidence is hundreds of megabytes.
+  shard_bound_rule: >-
+    Each full-evidence shard is independently bounded. A single oversized shard
+    is reported and recoverable; it cannot make the whole tier unloadable.
+  shard_byte_cap: 67108864
+  shard_byte_cap_note: >-
+    A full-evidence shard encodes no more than `reader_byte_cap` bytes. Shards
+    are grouped by source family; when a family's encoded records exceed the
+    cap the family is split into numbered sub-shards so no shard exceeds it and
+    no record is dropped. This is the measured bound a bounded reader loads.
+  signal_bound_rule: >-
+    The signal tier is bounded to fit under the reader cap. Selection must
+    preserve representative evidence across all supported sources rather than
+    silently truncating one source.
+  signal_byte_cap: 67108864
+  signal_byte_cap_note: >-
+    The whole signal tier encodes no more than `reader_byte_cap` bytes. A signal
+    record carries only the contract's required fields plus `evidence_anchor` and
+    no transcript text, raw tool arguments, or raw store paths; measured
+    per-record size is far below the cap for realistic corpora, so the natural
+    outcome is to retain every derived signal. The selection below is the
+    deterministic safety net that keeps the bound when a real-scale corpus would
+    otherwise exceed it.
+  signal_selection:
+    rule: >-
+      Applied only when the derived signal tier exceeds `signal_byte_cap`. The
+      derivation is otherwise total: identical full evidence yields identical
+      signal membership and ordering.
+    algorithm: >-
+      Group derived signal records by source family. Allocate a per-family record
+      quota proportional to that family's share of the total record count, with a
+      minimum of one record per family so no supported source is silently
+      truncated to zero. Within each family, keep the most recent records first
+      (timestamp descending, then `source_id` ascending as the deterministic
+      tie-break). Reassemble the kept records in the stable tier order
+      (timestamp ascending, then `source_id` ascending). The generation identity
+      is derived from the retained membership so identical input reproduces an
+      identical selected tier.
+    derivation: >-
+      Resolves planning Unknown 1. The bound is the existing reader cap reused as
+      the signal cap because a bounded consumer must load the whole signal tier in
+      one read. Proportional-per-family selection preserves the relative evidence
+      distribution across all supported sources; recency-within-family preserves
+      the most decision-relevant signals; the fixed `(timestamp, source_id)`
+      ordering makes membership and ordering reproducible.
+  real_scale_acknowledgement: >-
+    Real corpora exceed 500 MB. The goal is useful analysis, not merely
+    graceful failure; bounded tiers exist so consumers analyze real scale
+    rather than reporting unavailable or stale results.
+
+compatibility_states:
+  determinism_rule: >-
+    Every compatibility state has a fixed status, reason, recovery action, and
+    outcome. Recovery is actionable: it names the command or correction that
+    restores useful analysis. outcomes are limited to `recover` and `degrade`;
+    a `degrade` outcome must keep provenance visible and never fabricate
+    coverage. These outcomes are covered by passing and failing checks.
+  states:
+    oversized:
+      trigger: A full-evidence shard or legacy monolithic corpus exceeds the reader cap.
+      status: stale
+      reason: oversized
+      outcome: degrade
+      recovery: >-
+        Refresh bounded tiers with `agentera stats refresh --consent
+        local-history` or read the signal tier, which is bounded to fit. Do not
+        attempt to load the oversized artifact whole.
+      determinism: >-
+        Size is computed before read; the artifact is never partially loaded.
+        The signal tier remains usable.
+    legacy:
+      trigger: >-
+        A pre-tiering monolithic corpus.json exists but no bounded tiers have
+        been published.
+      status: stale
+      reason: legacy_monolithic_state
+      outcome: degrade
+      recovery: >-
+        Emit deterministic refresh guidance: run `agentera stats refresh
+        --consent local-history` to publish bounded tiers. Legacy monolithic
+        state receives refresh guidance rather than indefinite read
+        compatibility.
+      determinism: >-
+        Legacy state is detected by envelope shape and missing tier markers; it
+        is never silently treated as current.
+    missing:
+      trigger: No evidence artifact or tier exists at the resolved path.
+      status: missing
+      reason: no_evidence
+      outcome: degrade
+      recovery: >-
+        Report `agentera stats refresh --consent local-history` and the
+        `--corpus PATH` override. Must not auto-build, scan home directories, or
+        run live extraction without consent.
+      determinism: >-
+        Missing is reported as a concrete status with a path, never as an empty
+        success.
+    corrupt:
+      trigger: An artifact exists but is not readable JSON or fails schema validation.
+      status: stale
+      reason: unreadable_or_schema_divergent
+      outcome: degrade
+      recovery: >-
+        Refresh from source history. If a single shard is corrupt, the other
+        shards and the signal tier remain usable; only the corrupt shard is
+        flagged.
+      determinism: >-
+        Parse errors are caught per artifact/shard and reported with the
+        failing reason; one corrupt shard cannot crash tier reads.
+    incomplete:
+      trigger: >-
+        Tiers exist but a supported source family is unavailable, skipped
+        without acceptance, or extracted zero records.
+      status: flagged
+      reason: coverage_gap_or_sparse
+      outcome: degrade
+      recovery: >-
+        Surface the skipped/sparse family with its reason. Available skipped
+        sources require explicit `--accept-coverage-gap`; sparse (zero-record)
+        extraction is distinct from schema divergence.
+      determinism: >-
+        Coverage gaps and sparse extraction are reported per family with
+        discovery status; none is silently omitted.
+
+scope:
+  in_scope:
+    - Tier contract definition, source coverage, consumer field supply.
+    - Signal semantics reservation for current and deferred consumers.
+    - Compatibility state definitions and deterministic recovery outcomes.
+    - Small contract-model code and focused tests making invariants executable.
+  out_of_scope:
+    - Complete extraction writer implementation.
+    - Migration of all consumers to bounded tiers.
+    - Bounded profile synthesis runtime.
+    - Glossary implementation.
+    - Profile level selection.
+    - Suite version bump, release, or publish.
+  version_constraint: >-
+    Suite and version metadata remain at 3.0.0. This contract does not bump,
+    release, or publish anything.