agentera 3.0.0-dev.3 → 3.0.0-dev.31

package/bundle/references/artifacts/state-storage-authority.yaml

@@ -0,0 +1,2167 @@
+schema_version: agentera.stateStorageAuthority.v1
+status: active_authority
+purpose: >-
+  Define both the implemented bounded-retrieval contracts for current state and
+  the Decision 94 target entity and cutover contracts. The target declaration is
+  authoritative before its storage, writer, retrieval, and migration behavior is
+  implemented; implementation status is explicit at each boundary.
+authority:
+  source: references/artifacts/state-storage-authority.yaml
+  single_source_rule: >-
+    Runtime readers, writers, validators, tests, help, and capability source
+    contracts may project this authority but must not create a second map of
+    archive paths, API verbs, compatibility classes, mutable overlay fields,
+    amendment revision paths, legacy label coexistence rules, failure classes,
+    or byte limits.
+  implementation_boundary: >-
+    Shared entity storage plus the progress, decisions, health, plan, objective,
+    experiment, TODO-item, and documentation-inventory family writers and retrieval,
+    plus one-way forward import, are implemented but activate entity authority only
+    from the durable cutover marker. The preserved
+    singleton families remain legacy files. The
+    current numbered archive and retrieval groups remain migration input while
+    that marker is absent; no independent legacy repair mutation remains.
+
+entity_target:
+  status: progress_decisions_health_plan_objective_experiment_todo_and_docs_implemented_other_families_declared
+  decision: 94
+  activation: >-
+    This target becomes active persisted and structured state authority only
+    after entity_migration publishes a validated entity graph and writes the marker
+    last. Before then, legacy aggregates
+    remain migration input and explicitly labelled migration-evidence writer state;
+    ordinary public reads fail with migration_required instead of exposing them.
+  implementation_status:
+    progress: implemented
+    decisions: implemented
+    health: implemented
+    plan: implemented
+    objective: implemented
+    experiments: implemented
+    todo: implemented
+    docs: implemented
+    remaining_families: declared_not_implemented
+    rule: >-
+      Every implemented family selects entity behavior only when the durable
+      cutover marker is valid. Marker-absent ordinary consumers fail with
+      migration_required; the read-only migration preview and readiness checks do
+      not create entity state or write both authorities.
+  public_schema:
+    canonical_identity_field: id
+    canonical_classification_field: artifact
+    identity_and_classification_fields: [id, artifact]
+    entity_envelope:
+      required_fields: [id, artifact, record]
+      additional_identity_or_classification_fields: forbidden
+    forbidden_canonical_aliases:
+      - stable_id
+      - artifact_id
+      - entry_number
+      - number
+      - task_number
+      - experiment_number
+      - plan_id
+      - objective_id
+      - type_prefixed_id
+    exemptions:
+      - historical prose and immutable historical evidence
+      - internal TypeScript variable names that are not persisted or public structured output
+      - current pre-cutover contracts explicitly marked as implemented legacy authority
+  public_retrieval:
+    schema_version: agentera.entityPublicRetrieval.v1
+    status: final
+    commands:
+      progress:
+        list: agentera state progress list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state progress get --id ID --format json
+      decisions:
+        list: agentera state decisions list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state decisions get --id ID --format json
+      health:
+        list: agentera state health list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state health get --id ID --format json
+      plans:
+        list: agentera state plan list [--status open|complete|archived] [--limit N] [--cursor TOKEN] --format json
+        get: agentera state plan get --id ID --format json
+      plan_tasks:
+        list: agentera state plan tasks list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state plan tasks get --id ID --format json
+      objective:
+        list: agentera state objective list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state objective get --id ID --format json
+      experiments:
+        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] --format json
+        get: agentera state experiments get --id ID --format json
+      todo:
+        list: agentera state todo list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state todo get --id ID --format json
+      docs:
+        list: agentera state docs list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state docs get --id ID --format json
+    collections:
+      - { artifact: progress, identity: id, classification: artifact }
+      - { artifact: decisions, identity: id, classification: artifact }
+      - { artifact: health, identity: id, classification: artifact }
+      - { artifact: plan, boundary: plan, identity: id, classification: artifact }
+      - { artifact: plan, boundary: plan_task, identity: id, classification: artifact }
+      - { artifact: objective, identity: id, classification: artifact }
+      - { artifact: experiments, identity: id, classification: artifact }
+      - { artifact: todo, identity: id, classification: artifact }
+      - { artifact: docs, identity: id, classification: artifact }
+  identity:
+    scope: project_wide_across_all_entity_artifacts
+    alphabet: abcdefghijklmnopqrstuvwxyz
+    length: 10
+    accepted_pattern: '^[a-z]{10}$'
+    example: qjtrmnpvka
+    allocation: random_from_declared_alphabet
+    collision_rule: retry before publication; an existing ID is never reassigned or overwritten
+    prohibited_components: [prefix, sequence, timestamp, branch, writer, git_reference]
+    meaning_rule: >-
+      The ID is opaque and carries no artifact or entity-boundary information;
+      artifact is the sole public classification field.
+  storage_boundary:
+    rule: one independently mutable entity per writer-owned canonical file
+    aggregate_authority: forbidden
+    shared_primitives:
+      status: implemented
+      canonical_root: .agentera/entities
+      canonical_path_template: .agentera/entities/<artifact>/<boundary>/<id>.yaml
+      path_components: [artifact, boundary, id]
+      extension: .yaml
+      publication: exclusive_immutable_file
+      publication_context:
+        scope: shared_by_all_entity_families
+        binding: validated_project_root_and_exact_cutover_marker_snapshot
+        lifetime: mode_detection_through_writer_lock_and_final_publication_validation
+        pathname_race_contract: >-
+          Entity publication is rooted through held directory descriptors. The
+          root and exact valid marker identity and bytes are revalidated before
+          each directory, stage, and immutable-link boundary and after durable
+          publication before success. Because Node cannot make pathname
+          validation and mutation one kernel operation, a detected substitution
+          rolls back only attempt-owned links, stages, and empty directories by
+          pinned identity; final failure retains no attempt-owned entity state.
+        marker_change_after_detection: conflict_without_legacy_fallback
+        successor_preservation: never_remove_unmatched_or_unrelated_identity
+      allocation: provisional_candidate_until_publication
+      project_wide_id_claim:
+        synchronization: .agentera/.writer.lock
+        critical_section: final_project_wide_scan_through_durable_publication
+        interrupted_writer_recovery: dead_process_lock_reclamation
+        persistent_reservation: none
+      identical_replay: idempotent
+      replay_equality: recursive_key_sorted_logical_content_with_array_order_preserved
+      divergent_same_id: reject_without_overwrite
+      state_validation:
+        canonical_command: agentera check validate state
+        mutates: false
+        failure_exit: nonzero
+        diagnostics: bounded_structured_with_exact_recovery
+    same_entity_conflict: >-
+      Concurrent divergent edits to one entity remain an ordinary explicit file
+      conflict or validation conflict; no runtime silently selects a winner.
+    unrelated_entity_merge: >-
+      Independently created or changed entities occupy distinct canonical files
+      so ordinary Git can preserve both changes.
+  entities:
+    - boundary: progress_cycle
+      artifact: progress
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      record:
+        required_fields: [timestamp, type, phase, what, context]
+        required_paths: [context.intent]
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+        temporal_fields: [timestamp]
+        timestamp_format: 'YYYY-MM-DD HH:MM'
+      retrieval:
+        exact: agentera state progress get --id ID --format json
+        list: agentera state progress list [--limit N] [--cursor TOKEN] --format json
+        ordering: timestamp_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: progress_summary
+      artifact: progress
+      independently_mutable: false
+      relationships: []
+      implementation: implemented
+      publication: immutable
+      mutation: forbidden
+      record:
+        required_fields: [summary, migration_provenance]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+      canonical_metadata:
+        summary_migration_provenance:
+          path: record.migration_provenance
+          required_fields: [source_path, source_record_sha256]
+          additional_fields: forbidden
+          source_path: project-relative v2 aggregate source path
+          sources:
+            - path: .agentera/progress.yaml
+              collections: [cycles, archive]
+          source_row_provenance: entity_target.declared_compacted_summary_contract.source_row_provenance
+    - boundary: decision
+      artifact: decisions
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: immutable
+      record:
+        required_fields: [date, question, context, alternatives, choice, reasoning, confidence]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, satisfaction]
+      canonical_metadata:
+        migration_provenance:
+          applicability: inherited_unsupported_confidence_only
+          required_fields: [kind, source, source_path, source_record_sha256, confidence]
+          additional_fields: forbidden
+          kind: inherited_decision_confidence
+          sources: [current_projection, verified_archive]
+          semantics: >-
+            Cutover persists this envelope-level metadata only when an authority-backed
+            complete-record classifier proves that high, medium, or low confidence is
+            the source record's sole schema violation. confidence must match the
+            canonical record, source_path is project-relative, and source_record_sha256
+            binds the complete parsed source record before canonical alias removal.
+            Current confidence values and ordinary decision writes omit this metadata.
+      retrieval:
+        exact: agentera state decisions get --id ID --format json
+        list: agentera state decisions list [--limit N] [--cursor TOKEN] --format json
+        ordering: date_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: decision_satisfaction
+      artifact: decisions
+      independently_mutable: true
+      relationships: [decision]
+      implementation: implemented
+      publication: replace_owned_entity
+      ownership: { fields: [decision], cardinality: zero_or_one }
+      record:
+        required_fields: [decision, state]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+    - boundary: decision_summary
+      artifact: decisions
+      independently_mutable: false
+      relationships: []
+      implementation: implemented
+      publication: immutable
+      mutation: forbidden
+      record:
+        required_fields: [summary, migration_provenance]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+      canonical_metadata:
+        summary_migration_provenance:
+          path: record.migration_provenance
+          required_fields: [source_path, source_record_sha256]
+          additional_fields: forbidden
+          source_path: project-relative v2 aggregate source path
+          sources:
+            - path: .agentera/decisions.yaml
+              collections: [decisions, archive]
+          source_row_provenance: entity_target.declared_compacted_summary_contract.source_row_provenance
+      satisfaction: optional_inline_read_only_source_retained_field
+    - boundary: decision_revision
+      artifact: decisions
+      independently_mutable: true
+      includes: [amendment]
+      relationships: [decision]
+      implementation: implemented
+      publication: immutable
+      ownership: { fields: [decision, base_sha256], cardinality: zero_or_one }
+      record:
+        required_fields: [decision, date, provenance, base_sha256, changes]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, satisfaction]
+    - boundary: health_audit
+      artifact: health
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: immutable
+      record:
+        required_fields: [date, dimensions, findings_summary, trajectory, grades]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+        cli_owned_append_fields: [appended_at]
+        legacy_optional_fields: [appended_at]
+        field_contract:
+          appended_at:
+            format: canonical_utc_iso8601
+            assignment: cli_writer_at_append
+            compatibility: >-
+              Legacy canonical health audits omit appended_at and remain valid without
+              reconstructed chronology.
+      retrieval:
+        exact: agentera state health get --id ID --format json
+        list: agentera state health list [--limit N] [--cursor TOKEN] --format json
+        ordering: appended_at_desc_then_id_asc_then_legacy_date_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+      repair: >-
+        Canonical health audit entities are immutable and cannot be row-deduplicated.
+         Malformed envelopes, duplicate IDs, or conflicting ownership fail before effects
+          and recover through agentera check validate state; no repair event is fabricated.
+    - boundary: health_summary
+      artifact: health
+      independently_mutable: false
+      relationships: []
+      implementation: implemented
+      publication: immutable
+      mutation: forbidden
+      record:
+        required_fields: [summary, migration_provenance]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+      canonical_metadata:
+        summary_migration_provenance:
+          path: record.migration_provenance
+          required_fields: [source_path, source_record_sha256]
+          additional_fields: forbidden
+          source_path: project-relative v2 aggregate source path
+          sources:
+            - path: .agentera/health.yaml
+              collections: [audits, archive]
+          source_row_provenance: entity_target.declared_compacted_summary_contract.source_row_provenance
+    - boundary: plan
+      artifact: plan
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [header, what, why, scope]
+        required_paths: [header.title, header.created, header.status]
+        forbidden_fields: [id, artifact, stable_id, plan_id, tasks, previous_plan_archived]
+        field_shapes:
+          scope:
+            type: mapping
+            required_fields:
+              included: string_list
+              excluded: string_list
+            optional_fields:
+              deferred: string_list
+            additional_fields: forbidden
+            legacy_source_normalization: >-
+              A block-style, non-flow, exactly-one-pair mapping used directly as
+              an included, excluded, or deferred sequence item is the historical
+              block-colon string encoding and normalizes to one `key: value`
+              string only when both source nodes are string scalars. Explicit
+              flow mapping syntax never normalizes and remains invalid under the
+              canonical validator. A deliberate block single-pair mapping is
+              syntactically indistinguishable from the legacy encoding and falls
+              under this source-form rule; no semantic intent is inferred.
+      retrieval:
+        exact: agentera state plan get --id ID --format json
+        list: agentera state plan list [--limit N] [--cursor TOKEN] --format json
+        ordering: created_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: plan_task
+      artifact: plan
+      independently_mutable: true
+      relationships: [plan, depends_on_tasks, superseded_by]
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [plan, name, status, depends_on, acceptance]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, task_number, stable_id, plan_id]
+    - boundary: objective
+      artifact: objective
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [header, objective, metric, baseline, scope]
+        required_paths: [header.title, header.status, objective.description, objective.measurement]
+        forbidden_fields: [id, artifact, stable_id, objective_id]
+      retrieval:
+        exact: agentera state objective get --id ID --format json
+        list: agentera state objective list [--limit N] [--cursor TOKEN] --format json
+        ordering: created_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: experiment
+      artifact: experiments
+      independently_mutable: true
+      relationships: [objective]
+      implementation: implemented
+      publication: immutable
+      baseline:
+        field: status
+        value: baseline
+        cardinality: exactly_one_when_experiments_exist
+      record:
+        required_fields: [objective, date, label, hypothesis, method, change, metric, regression, status, conclusion]
+        required_paths: [objective, date, label, status]
+        forbidden_fields: [id, artifact, number, experiment_number, stable_id, objective_id]
+      retrieval:
+        exact: agentera state experiments get --id ID --format json
+        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] --format json
+        ordering: date_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: todo_item
+      artifact: todo
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [severity, status, description]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, path]
+      retrieval:
+        exact: agentera state todo get --id ID --format json
+        list: agentera state todo list [--limit N] [--cursor TOKEN] --format json
+        ordering: severity_then_status_then_id
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: documentation_inventory_entry
+      artifact: docs
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [document, path, last_updated, status]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+      retrieval:
+        exact: agentera state docs get --id ID --format json
+        list: agentera state docs list [--limit N] [--cursor TOKEN] --format json
+        ordering: path_then_id
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+  relationships:
+    representation: bare target entity ID in the named record field
+    integrity: every non-null target must resolve to exactly one entity with the declared target boundary
+    unresolved_behavior: whole-state validation and migration cutover fail without creating a target
+    declarations:
+      - source: decision_satisfaction
+        field: decision
+        target: decision
+        cardinality: exactly_one
+      - source: decision_revision
+        field: decision
+        target: decision
+        cardinality: exactly_one
+      - source: plan_task
+        field: plan
+        target: plan
+        cardinality: exactly_one
+      - source: plan_task
+        field: depends_on
+        target: plan_task
+        cardinality: zero_or_many_same_plan
+      - source: plan_task
+        field: superseded_by
+        target: plan_task
+        cardinality: zero_or_many_same_plan
+      - source: experiment
+        field: objective
+        target: objective
+        cardinality: exactly_one
+  views:
+    authority: non_authoritative_cli_rendering
+    mutation: forbidden
+    source: canonical entity files only after cutover
+    requirements:
+      - bounded lists expose id and artifact and provide exact get by id
+      - ordering and cursors bind to an explicit snapshot and never imply identity
+      - omissions expose counts, reasons, and exact retrieval commands
+      - nested plan/task and objective/experiment views are relationship projections
+      - startup views use the same entities and may omit detail only under declared budgets
+  intentional_singletons:
+    exhaustive: true
+    additions_require_authority_amendment: true
+    boundaries:
+      - boundary: vision
+        reason: one project north star; excluded from execution-cycle mutation
+      - boundary: design
+        reason: one project visual identity editorial artifact
+      - boundary: changelog
+        reason: one ordered release-history editorial artifact
+      - boundary: profile
+        reason: one reusable decision-profile document per selected profile
+      - boundary: runtime_local_session_state
+        reason: runtime-local and not canonical project entity state
+      - boundary: docs_mapping
+        reason: one project path and documentation-policy mapping, distinct from documentation inventory entries
+    conflict_rule: concurrent edits remain explicit whole-document conflicts
+  excluded_from_entity_migration:
+    - all intentional_singletons
+    - immutable historical prose and evidence, except structured references explicitly declared for rewrite
+    - genuinely singleton editorial artifacts added by an authority amendment
+  declared_compacted_summary_contract:
+    status: implemented
+    activation: >-
+      The three summary boundaries are active entity and migration authority in
+       entity_target.entities. Ordinary summary readers and startup projection
+       expose retained degraded history without reconstructing missing detail.
+    runtime_boundary_source: entity_target.entities
+    runtime_exclusion: >-
+      No experiment_summary boundary is activated. Summary boundaries are
+      immutable/read-only and are not ordinary write targets.
+    source_scope:
+      included_artifacts: [progress, decisions, health]
+      excluded_artifacts:
+        - objective_experiments: protected v2 family; not a compacted-summary migration input
+        - runtime_local_session_state: runtime-local state is outside canonical project migration
+        - compacted_todo_rows: already satisfy the canonical TODO shape and are not remapped as summaries
+      authority_rule: >-
+        This implemented scope does not reconstruct Git history, normalize source
+        summaries, retain dual authority, or provide a repair or import command.
+    source_row_provenance:
+      semantic_id: v2_compacted_summary_physical_row.v1
+      status: implemented
+      accepted_parsed_row_values: [mapping, scalar_string]
+      normalization: >-
+        Preview normalizes either accepted parsed physical row value to canonical
+        retained summary content for matching and publication. A mapping retains
+        its source fields subject to canonical alias removal and declared metadata
+        injection; a scalar string becomes {summary: value}.
+      source_record_sha256:
+        format: lowercase_sha256_hex
+        input: >-
+          original parsed physical source row value, which may be a mapping or a
+          scalar string, before summary normalization, canonical alias removal, or
+          metadata injection
+        canonicalization: >-
+          SHA-256 of UTF-8 canonical JSON: recursively sort mapping keys, preserve
+          array order, serialize scalar strings with JSON.stringify, and emit no
+          insignificant whitespace.
+    diagnostics:
+      status: implemented
+      implementation: >-
+        Read-only migration preview classifies independent invalid source
+        identities as roots, then reports generated graph dependents separately.
+        Ordinary summary reads and startup do not expose these migration-only
+        fields.
+      counts:
+        blockers: total root_blockers plus dependent_blockers
+        root_blockers: independently invalid, ambiguous, conflicting, or unsupported source identities
+        dependent_blockers: >-
+          Downstream diagnostics caused by a named root blocker. Each dependent names
+          its root source identity and does not increase root corruption.
+        dependent_blocker_required_fields: [root_source_identity]
+        corruption_count: corrupt classification counts source roots only, never generated dependents
+      graph: >-
+        A resolved relationship to a root (including a chain) is a dependent
+        blocker. Missing references make their owning source a root. Cycles with
+        no source root choose their lexicographically first source identity as a
+        deterministic corrupt root; preview does not attempt graph recovery.
+    source_outcomes:
+      status: implemented
+      valid_compacted_summary:
+        outcome: ready_with_degraded_provenance
+        rule: >-
+          Map each valid supported v2 summary to its declared immutable summary
+          boundary, retain source fields and migration provenance, and never
+          reconstruct missing detail.
+      missing_detail_not_declared_summary:
+        outcome: blocked
+        rule: retain evidence and stop before publication; never infer omitted fields
+      inherited_confidence_only:
+        outcome: ready_with_legacy_caveat
+        rule: >-
+          Preserve an inherited full-decision high, medium, or low label exactly and
+          report its caveat. Only new or amended labels must use the current strict
+          vocabulary.
+    boundaries:
+      - boundary: progress_summary
+        artifact: progress
+        independently_mutable: false
+        implementation: implemented
+        publication: immutable
+        mutation: forbidden
+        canonical_representation: one_immutable_degraded_summary_entity_per_valid_v2_summary
+        relationships: []
+        record:
+          required_fields: [summary, migration_provenance]
+          additional_fields: source_retained_fields_plus_declared_metadata
+          declared_metadata_fields: [migration_provenance]
+          source_retained_fields: >-
+            Preserve every source-retained field in the canonical record except
+            public_schema.forbidden_canonical_aliases. migration_provenance is
+            declared canonical metadata, not a retained source field. Missing
+            full-detail fields remain absent; migration does not normalize or
+            reconstruct them.
+          forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+          migration_provenance:
+            path: record.migration_provenance
+            required_fields: [source_path, source_record_sha256]
+            additional_fields: forbidden
+            source_path: project-relative v2 aggregate source path
+            source_row_provenance: entity_target.declared_compacted_summary_contract.source_row_provenance
+        retrieval:
+          exact: agentera state progress get --id ID --format json
+          list: agentera state progress list [--limit N] [--cursor TOKEN] --format json
+          detail_availability: summary
+          compatibility: degraded
+          caveats: required
+          ordering: full_timestamp_desc_then_id_asc_then_summary_id_asc
+          summary_ordering: canonical_id_asc_without_chronology_claim
+          mutation: read_only
+      - boundary: decision_summary
+        artifact: decisions
+        independently_mutable: false
+        implementation: implemented
+        publication: immutable
+        mutation: forbidden
+        canonical_representation: one_immutable_degraded_summary_entity_per_valid_v2_summary
+        relationships: []
+        record:
+          required_fields: [summary, migration_provenance]
+          additional_fields: source_retained_fields_plus_declared_metadata
+          declared_metadata_fields: [migration_provenance]
+          source_retained_fields: >-
+            Preserve every source-retained field in the canonical record except
+            public_schema.forbidden_canonical_aliases. migration_provenance is
+            declared canonical metadata, not a retained source field. Missing
+            full-detail fields remain absent; migration does not normalize or
+            reconstruct them.
+          forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+          satisfaction: optional_inline_read_only_source_retained_field
+          satisfaction_rule: >-
+            Satisfaction may be absent. When retained, it remains inline and read-only;
+            a decision summary never creates or targets a decision_satisfaction entity.
+          migration_provenance:
+            path: record.migration_provenance
+            required_fields: [source_path, source_record_sha256]
+            additional_fields: forbidden
+            source_path: project-relative v2 aggregate source path
+            source_row_provenance: entity_target.declared_compacted_summary_contract.source_row_provenance
+        retrieval:
+          exact: agentera state decisions get --id ID --format json
+          list: agentera state decisions list [--limit N] [--cursor TOKEN] --format json
+          detail_availability: summary
+          compatibility: degraded
+          caveats: required
+          ordering: full_date_desc_then_id_asc_then_summary_id_asc
+          summary_ordering: canonical_id_asc_without_chronology_claim
+          mutation: read_only
+      - boundary: health_summary
+        artifact: health
+        independently_mutable: false
+        implementation: implemented
+        publication: immutable
+        mutation: forbidden
+        canonical_representation: one_immutable_degraded_summary_entity_per_valid_v2_summary
+        relationships: []
+        record:
+          required_fields: [summary, migration_provenance]
+          additional_fields: source_retained_fields_plus_declared_metadata
+          declared_metadata_fields: [migration_provenance]
+          source_retained_fields: >-
+            Preserve every source-retained field in the canonical record except
+            public_schema.forbidden_canonical_aliases. migration_provenance is
+            declared canonical metadata, not a retained source field. Missing
+            full-detail fields remain absent; migration does not normalize or
+            reconstruct them.
+          forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+          migration_provenance:
+            path: record.migration_provenance
+            required_fields: [source_path, source_record_sha256]
+            additional_fields: forbidden
+            source_path: project-relative v2 aggregate source path
+            source_row_provenance: entity_target.declared_compacted_summary_contract.source_row_provenance
+        retrieval:
+          exact: agentera state health get --id ID --format json
+          list: agentera state health list [--limit N] [--cursor TOKEN] --format json
+          detail_availability: summary
+          compatibility: degraded
+          caveats: required
+          ordering: full_date_desc_then_id_asc_then_summary_id_asc
+          summary_ordering: canonical_id_asc_without_chronology_claim
+          mutation: read_only
+  measurement_contract:
+    status: implemented
+    environment: Linux, Node.js 22 or newer, one cold CLI process per sample
+    fixtures:
+      small: 100 valid entities distributed across every active entity_target.entities boundary
+      large: 1000 valid entities distributed across every active entity_target.entities boundary
+      relationship_rule: every active entity_target.relationships declaration has at least one valid fixture edge
+    sampling:
+      repetitions: 5
+      pass_rule: every repetition stays within every applicable limit
+      elapsed: wall-clock milliseconds from process start through complete serialized output
+      heap: process heapUsed peak minus heapUsed before fixture discovery
+      bytes: UTF-8 byte length of stdout including the trailing newline
+    targets:
+      exact_get:
+        max_latency_ms: 1000
+        max_heap_delta_bytes: 67108864
+        max_utf8_bytes: 1048576
+      bounded_list_small:
+        max_latency_ms: 5000
+        max_heap_delta_bytes: 67108864
+        max_utf8_bytes: 32768
+      bounded_list_large:
+        max_latency_ms: 15000
+        max_heap_delta_bytes: 268435456
+        max_utf8_bytes: 32768
+      startup_small:
+        max_latency_ms: 5000
+        max_heap_delta_bytes: 67108864
+        serialized_limits: budgets.startup.surfaces
+      startup_large:
+        max_latency_ms: 15000
+        max_heap_delta_bytes: 268435456
+        serialized_limits: budgets.startup.surfaces
+    failure_rule: >-
+      Over-budget results fail the target gate. They may return a measured
+      degraded envelope only where the referenced budget permits omission; they
+      never truncate bytes, omit required identity, or fabricate detail.
+
+entity_migration:
+  status: one_way_forward_import_implemented
+  decision: 94
+  kind: single_full_upgrade_cutover
+  cutover_marker:
+    path: .agentera/state-mode.yaml
+    schema_version: agentera.stateMode.v1
+    entity_mode:
+      schemaVersion: agentera.stateMode.v1
+      mode: entities
+    absent_mode: legacy
+    invalid_behavior: fail_without_fallback
+    detection: read_only
+    publication_owner: development_channel_v2_to_v3_upgrade
+    selection: >-
+      Project state and CLI installation state are independent dimensions. A v3
+      CLI selects this cutover for recognized marker-absent v2 aggregate state
+      whether the CLI runs from a self-contained npm package or a source
+      checkout. Pending v1 Markdown state and marker-absent state with no
+      recognized v2 entity input are rejected with manual recovery instructions.
+  invocation:
+    explicit_apply: full_upgrade_yes_only
+    dry_run: optional_read_only_preview
+    ordinary_reads_migrate: false
+    ordinary_writes_migrate: false
+    apply_invokes_git: true
+    read_only_command: >-
+      npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+    apply_command: >-
+      npx -y agentera@next upgrade --channel development --project "$PWD" --yes
+    apply_boundary: >-
+      Full upgrade serializes through the project writer lock, validates the
+      deterministic conversion, writes each missing canonical entity or accepts
+      an exact existing match, validates the complete graph, and writes the
+      authority marker last. There is no direct
+      entity apply, public operation ID, resume, rollback, or cross-major restore.
+    git_preflight:
+      required: true
+      project_root: exact_worktree_root
+      source: HEAD_commit
+      checkout: no_staged_modified_renamed_or_untracked_paths_except_exact_cutover_outputs
+      migration_inputs: regular_tracked_files_whose_bytes_and_executable_mode_match_HEAD
+      absent_input: absent_from_HEAD_and_worktree
+      ignored_or_untracked_input: refuse
+      verification: >-
+        Planning and apply resolve the current HEAD commit and prove every present
+        migration input is a safe regular tracked path whose bytes and executable
+        mode match that commit. Apply repeats the proof under the writer lock
+        before its first effect. Non-Git projects and dirty or unsupported source
+        state are refused before any selected upgrade effect.
+    upgrade_composition:
+      owner: development_channel_v2_to_v3_upgrade
+      selected_with: [full]
+      apply_consent: >-
+        The upgrade --yes consent derives all source and target bindings in
+        process. Users provide no hashes, approval files, migration IDs, --force,
+        or additional cutover consent. Any --only apply is rejected at this
+        cross-major boundary.
+      interruption: >-
+        A rerun recomputes the deterministic conversion from unchanged Git-bound
+        source, accepts existing canonical targets only when their bytes match,
+        writes the first missing target, validates the complete graph, and finishes
+        the marker forward. It never deletes or replaces canonical entities.
+      completed: >-
+        A valid entity marker makes legacy authority permanently inactive.
+        Repeated upgrade validates current entity state and reports a no-op;
+        normal entity writes may evolve records without reopening cutover.
+      preflight: >-
+        Upgrade plans artifact normalization, entity readiness, runtime work,
+        and cleanup read-only before any selected apply function runs. A detect,
+        artifact, or entity blocker prevents entity publication and activation.
+        Runtime or cleanup blockers do not prevent valid entity activation; their
+        resources remain untouched and are reported after the marker as
+        action-required work.
+      phase_filters: >-
+        Every --only apply is invalid during a v2-to-v3 boundary. Read-only
+        filtered preview may remain available.
+      legacy_projection: >-
+        Canonical v2 YAML and already-resolved v1 conversions are inventoried
+        directly. A pending v1 Markdown conversion is not projected through a
+        prerequisite write during planning and therefore blocks the composed
+        apply before effects.
+      lifecycle_normalization: >-
+        Deterministic legacy plan lifecycle normalization is part of entity
+        projection during cutover. Upgrade retains the original legacy YAML as
+        source and recovery evidence instead of rewriting it first.
+      empty_state: unsupported_unknown_source_with_manual_handoff
+      existing_entity_state: validate_then_no_op
+  source_scope:
+    included_entities: entity_target.entities
+    included_structured_relationships: entity_target.relationships.declarations
+    preserved_singletons: entity_target.intentional_singletons.boundaries
+    sources: >-
+      Current canonical files, verified immutable archives, overlays, revisions,
+      and validated source evidence are inventoried together without changing
+      their pre-cutover authority. Every present input must be recoverable from
+      the pinned Git commit.
+    recovered_projection_correlation: >-
+      Every archive carrying recovery_provenance must match the immutable
+      .agentera/archive/recovery/projection-correlation.yaml recovery set by
+      identity, archive bytes, final record SHA-256, parent/child Git proof or
+      legacy converter/source proof, current projection bytes, and overlay.
+       Missing, changed, new, replaced, or unlisted recovery evidence blocks.
+  internal_migration_diagnostic: true
+  read_only_preview:
+    implementation: implemented
+    ordering: artifact_then_boundary_then_source_identity_then_source_path
+    filter: complete_declared_inventory
+    source_fingerprint: >-
+      SHA-256 over canonical JSON containing every declared source path's
+      project-relative name, presence, byte length, byte SHA-256, permission
+      mode, regular-file type, device, and inode from one verified open
+      descriptor. Missing declared roots are represented explicitly with null
+      identity. No mtime, Git value, or cache participates.
+    project_root: >-
+      The selected root must exist, be a directory, and resolve without a
+      symbolic-link root or symbolic-link traversal. Failure is structured and
+      occurs before inventory or effects.
+    recursive_roots: >-
+      Every declared archive and objective inventory root is lstat-validated
+      before traversal and again when recursion enters it. Existing symbolic
+      links and non-directories are project-bound inventory failures; their
+      targets are never inventoried.
+    authority_binding: >-
+      The preview records the active state-storage authority schema version and
+      byte SHA-256. The complete preview digest includes both values, so any
+      authority-only change invalidates approval before an apply effect.
+    proposed_id: >-
+      Preview-only ten-letter candidates are deterministically allocated from a
+      domain-separated SHA-256 of the complete source fingerprint and canonical
+      source key. This is allocation of a new opaque target candidate, not
+      reconstruction of a missing source ID. A collision is a blocker. Apply
+       preserves the deterministic mapping in each canonical target path.
+    preview_digest: >-
+      SHA-256 over canonical JSON of the complete unbounded inventory, proposed
+      mapping, authority-validated final envelope byte SHA-256 values,
+      relationship rewrite map, counts, blockers, and source
+      fingerprint plus the project selector, complete-source filter, declared
+      order, and migration-authority binding before output omission.
+    target_validation: >-
+      Before preview can be ready or produce an approvable digest, every proposed
+      final envelope, record, public field vocabulary, and relationship graph is
+      validated through the same authority-backed canonical target validator used
+       defensively by upgrade apply and forward retry. A target failure is a corrupt blocker tied
+      to its source identity and recovery action; preserved nonentity residues are
+      excluded from target validation and publication.
+    output:
+      max_utf8_bytes: 32768
+      default_limit: 100
+      maximum_limit: 1000
+      omission: whole entries and diagnostics only
+      scalar_truncation: forbidden
+      required_omission_fields: [omitted, omitted_count, omission_reason, retrieval]
+      recovery: >-
+        --after SOURCE_IDENTITY advances from the last whole logical identity
+        returned only when accompanied by that page's --source-fingerprint and
+        --preview-digest. The digest binds the project selector, complete-source
+        filter, authority-declared order, migration authority, and complete
+        source snapshot. Any mismatch refuses continuation with a command that
+        omits --after and restarts from the current snapshot. Diagnostics travel
+        with their owning entry, so repeated use of retrieval.command recovers
+        every later omitted entry and diagnostic.
+    counts:
+      physical_records: every observed record before identity grouping
+      logical_identities: every source identity after grouping
+      mirrors: excess canonical-identical physical records grouped under one logical identity
+      duplicates: excess divergent physical records claiming one logical identity
+      conflicts: logical identities with divergent candidates plus proposed-target collisions
+      root_blockers: independently invalid source identities, counted once per source identity
+      dependent_blockers: generated relationship-to-root diagnostics, each carrying root_source_identity
+      blockers: root_blockers plus dependent_blockers
+    zero_write: >-
+      Inventory, preview, malformed-input handling, and source-binding checks
+      open no writer or upgrade lock and create no directory, temporary file,
+      mapping, snapshot, journal, cache, or state file.
+    binding: >-
+       Before any apply effect, recompute the complete preview and require its
+       source fingerprint and preview digest to match the Git-pinned preparation.
+       A mismatch refuses every selected effect.
+  source_outcomes:
+    valid_full:
+      outcome: ready
+      rule: map one complete validated source entity and every relationship exactly once
+    canonical_mirror:
+      outcome: ready_with_mirrored_provenance
+      rule: group canonical-identical physical records as one logical identity and retain every provenance class
+    degraded_recoverable:
+      outcome: ready_with_provenance
+      rule: admit only independently validated full detail and record its recovery provenance
+    valid_compacted_summary:
+      outcome: ready_with_degraded_provenance
+      rule: preserve retained summary fields and source-record provenance without reconstructing omitted detail
+    missing_detail_not_declared_summary:
+      outcome: blocked
+      rule: retain evidence and stop before publication; never reconstruct omitted fields
+    ambiguous_or_duplicate_identity:
+      outcome: blocked
+      rule: retain every candidate and require explicit disposition; never choose by order or recency
+    proposed_target_conflict:
+      outcome: blocked
+      rule: retain every colliding logical identity and allocate no winner
+    corrupt_or_unresolved_relationship:
+      outcome: blocked
+      rule: report the exact source and recovery action; never publish a partial graph
+    unsupported:
+      outcome: blocked
+      rule: preserve bytes and report the unsupported source contract
+  non_fabrication:
+    forbidden:
+      - synthetic entities for missing source detail
+      - inferred IDs from order, numbers, paths, timestamps, branches, writers, or Git references
+      - guessed relationship targets
+      - silent dropping, deduplication, or winner selection
+    partial_cutover_success: forbidden
+  forward_state:
+    persisted_recovery_state: none
+    publication_order: exact_or_missing_entities_then_graph_validation_then_marker
+    retry_rule: accept_exact_targets_and_continue_at_first_missing_path
+    divergent_target: stop_without_replacement_and_name_first_unresolved_path
+    forbidden_fields: [operation_id, migration_id, snapshots, source_bytes, inode_receipts, rollback_state]
+    historical_evidence: >-
+      Already committed .agentera/migrations content is inert and remains
+      byte-for-byte untouched. Read-only legacy manifest parsing is retained only
+      for public validation of entity markers created by the former cutover.
+    fault_test_hook: >-
+      Tests may set NODE_ENV=test and
+      AGENTERA_FAULT_INJECT_ENTITY_MIGRATION_AFTER_PHASE to one declared publication
+      phase. Other environments ignore the variable.
+  lifecycle:
+    - phase: inventory
+      mutates: false
+      exit: every source entity and relationship is classified
+    - phase: preview
+      mutates: false
+      exit: proposed graph, mapping, outcomes, blockers, and digest are complete
+    - phase: git_preflight
+      mutates: false
+      exit: project root, HEAD, clean checkout, source bytes, types, and modes match
+    - phase: publishing_entities
+      mutates: true
+      exit: every canonical target is an exact match or is published once
+    - phase: entities_published
+      mutates: false
+      exit: canonical source-to-target parity, uniqueness, ownership, relationships, and budgets pass
+    - phase: marker
+      mutates: true
+      exit: one durable marker activates entity_target and retires writable legacy authority
+
+scope:
+  supported_artifacts:
+    - artifact_id: progress
+      current_projection_path: .agentera/progress.yaml
+      entry_collection: cycles
+      entry_number_field: number
+      entry_kind: cycle
+    - artifact_id: decisions
+      current_projection_path: .agentera/decisions.yaml
+      entry_collection: decisions
+      entry_number_field: number
+      entry_kind: decision
+    - artifact_id: health
+      current_projection_path: .agentera/health.yaml
+      entry_collection: audits
+      entry_number_field: number
+      entry_kind: audit
+  excluded_from_numbered_archive:
+    - plan
+    - vision
+    - todo
+    - changelog
+    - docs
+    - design
+    - objective
+    - experiments
+
+retrieval:
+  schema_version: agentera.stateRetrievalAuthority.v1
+  status: plan_task_plan_and_experiment_retrieval_implemented
+  implementation:
+    plan_tasks: implemented
+    plans: implemented
+    experiments: implemented
+    progress: implemented
+    decisions: implemented
+    health: implemented
+  authority_boundary: >-
+    This group owns public list/get envelopes, cursors, selectors, identities,
+    omissions, and structured retrieval failures. It does not replace storage
+    ownership: canonical entity files remain authoritative after the durable
+    cutover marker; retained v2 aggregates are immutable migration evidence only.
+  envelope:
+    schema_version: agentera.stateRetrieval.v1
+    required_fields:
+      - schemaVersion
+      - command
+      - status
+      - entries
+      - counts
+      - order
+      - filters
+      - snapshot
+      - source
+      - source_contract
+    entry_required_fields:
+      - id
+      - artifact
+      - boundary
+      - detail_availability
+      - compatibility
+      - provenance
+      - retrieval
+    summary_boundary_entries:
+      visibility: >-
+        Progress, decision, and health list/get reads include both the full
+        boundary and its corresponding immutable summary boundary under the
+        same artifact vocabulary.
+      full: { detail_availability: full, compatibility: current }
+      summary:
+        detail_availability: summary
+        compatibility: degraded
+        required_fields: [boundary, caveats, record.migration_provenance]
+        provenance: record_level_summary_migration_provenance
+        mutation: immutable_read_only
+      ordering: >-
+        Summary rows without a full-record temporal sort field sort after
+        timestamped or dated full rows and then by canonical ID ascending.
+    counts_required_fields: [total, returned, remaining, omitted]
+    status_values: [ok, degraded]
+  cursor:
+    vocabulary: opaque_snapshot_cursor
+    first_page: omit --cursor
+    response_field: next_cursor
+    binding: [collection, selectors, filters, order, snapshot]
+    append_behavior: >-
+      Records added after the first page are excluded from that cursor snapshot.
+      Experiment cursors bind each original stable identity to immutable archive
+      content when available, so unchanged full-to-summary or summary-to-drop
+      projection rollover does not invalidate continuation. Without sufficient
+      immutable or retained detail to prove an original identity unchanged, the
+      cursor fails with cursor_snapshot_unavailable.
+    invalid_behavior: cursor_invalid
+    unavailable_behavior: cursor_snapshot_unavailable
+    caller_rules: [do_not_parse, do_not_construct, do_not_compare_internals]
+  omission:
+    required_when_any_entry_is_not_returned:
+      - omitted
+      - omitted_count
+      - omission_reason
+      - retrieval
+    semantics: >-
+      Omission is explicit in both text and structured output. A response never
+      silently slices a collection, truncates a scalar, or claims omitted detail
+      is unavailable. Every omitted addressable item has an advancing cursor or
+      exact get command; unaddressable legacy items retain compatibility
+      diagnostics and are never assigned fabricated history.
+  output_bounds:
+    maximum_limit: 100
+    max_serialized_utf8_bytes: 32768
+    scalar_truncation: forbidden
+    omission_unit: whole_entries
+  identity:
+    plan:
+      canonical_format: 'plan:<lowercase-rfc9562-uuid>'
+      persistence: stored in header.id when a plan is first published
+      transition: the identical ID is copied unchanged into the immutable archive file
+      legacy_format: 'legacy-plan:<sha256>'
+      legacy_derivation: >-
+        SHA-256 over RFC 8785 canonical JSON of the complete plan after the
+        existing read-compatibility normalization of legacy status and task
+        shape. The archive transition computes identity from the same normalized
+        document before publication. Derivation is read-only and never rewrites
+        active or archived bytes; a legacy identity may change while an active
+        legacy plan is edited because no persisted historical identity exists.
+      test_vectors:
+        - canonical_json: '{"header":{"created":"2026-07-14","status":"open","title":"Plan: Complete bounded retrieval"},"tasks":[]}'
+          stable_id: legacy-plan:b6f93d6fc5a0ac3ada017670ac311794ad92800fb436703f8f09e25ddce8b89a
+          mirrored_example_paths: [.agentera/archive/PLAN-copy-a.yaml, .agentera/archive/PLAN-copy-b.yaml]
+          identical_result: mirrored_provenance
+      collision: >-
+        Byte-equivalent normalized legacy plans are one logical identity with
+        every physical path retained as mirrored provenance. Different plan
+        documents carrying the same persisted ID, or a detected digest collision,
+        are unaddressable; list reports compatibility=degraded and get returns
+        ambiguous with every candidate provenance path. The CLI never chooses by
+        mtime, archive filename, or discovery order.
+    task:
+      format: '<plan-id>/task:<positive-integer>'
+      selector: --task N
+      scope: task numbers are unique only inside one plan identity
+    objective:
+      canonical_format: 'objective:<lowercase-rfc9562-uuid>'
+      persistence: stored in header.id and unchanged by title or directory rename
+      canonical_root: .agentera/optimize/<objective-slug>
+      legacy_root: .agentera/optimera/<objective-slug>
+      legacy_format: 'legacy-objective:<sha256>'
+      legacy_derivation: >-
+        SHA-256 over RFC 8785 canonical JSON of the legacy objective's description,
+        measurement, metric, baseline, gates, constraints, and scope; title,
+        status, closure fields, directory root, and directory slug are excluded.
+        This preserves identity across a title/path-only rename without rewriting
+        history. Editing identity inputs may change a legacy identity and is
+        reported as degraded compatibility.
+      test_vectors:
+        - canonical_json: '{"baseline":{"description":"100 ms"},"constraints":[],"description":"Reduce latency","gates":{},"measurement":"p95","metric":{"direction":"minimize","unit":"ms"},"scope":{"excluded":[],"included":["CLI"]}}'
+          title_variants: [CLI latency, Faster CLI]
+          root_variants: [.agentera/optimize/cli-latency, .agentera/optimera/faster-cli]
+          stable_id: legacy-objective:aa987d92dadce65b8b2d8f54c741a10f5d024d864cb0ef309b4321b4e19e4ceb
+      path_compatibility: >-
+        Read both optimize and optimera roots. Identical records carrying one
+        persisted objective ID are mirrored provenance. Different records with
+        the same persisted or derived ID, or unresolved candidates in both roots,
+        return ambiguous; canonical-root preference must not hide a collision.
+    experiment:
+      format: '<objective-id>/experiment:<non-negative-integer>'
+      scope: experiment numbers are unique only within one objective identity
+      zero: experiment 0 is valid and is normally the baseline
+      collision: duplicate numbers inside one objective are ambiguous and never resolved by array order
+      compatibility: >-
+        Legacy full-detail or 10/40/50 summary entries with a missing or
+        duplicate number remain visible in reads with addressable=false and an
+        explicit compatibility caveat. Reads do not assign a number, choose a
+        duplicate by array order, migrate a root, or rewrite retained bytes.
+      publication_validation: >-
+        Before any publication effect, require one unambiguous objective
+        identity, a non-negative integer number, and no retained full-detail or
+        summary entry with that number. Ambiguous canonical/legacy objective
+        candidates, missing objective identity, and duplicate experiment
+        identity fail validation without changing bytes.
+      publication:
+        command: agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml --format json
+        authority: typed_state_writer
+        archive_ownership: experiment_archival
+        storage_scope: objective_directory
+        publication_order: archive_before_projection
+        projection_policy: uniform_10_40_50
+        input: one schema-valid experiment entry without the CLI-owned number field
+        identity_assignment: the CLI assigns the validated --number to the published entry
+        collision_rule: >-
+          An existing matching identity and byte-equivalent experiment is an
+          idempotent replay; the same identity with different content is a
+          collision and leaves the projection unchanged.
+        transaction: >-
+          Validate objective identity, canonical/legacy ambiguity, experiment
+          identity, existing projection schema, caller input schema, and final
+          projection bytes before atomically replacing experiments.yaml.
+        failure_atomicity: >-
+          Validation, staging, and pre-publication failures preserve both active
+          and one-line archive bytes. An interruption after atomic replacement
+          may report failure after publication; retrying the same command must
+          return the already-published entry without duplication.
+        scope_boundary: >-
+          Publication preserves the existing 10/40/50 projection contract and
+          durably publishes its objective-scoped immutable archive before
+          replacing the projection, as owned by experiment_archival.
+  commands:
+    plan_tasks:
+      list: agentera state plan tasks list [--plan PLAN_ID] [--limit N] [--cursor TOKEN] --format json
+      get: agentera state plan tasks get [--plan PLAN_ID] --task N --format json
+      selectors:
+        plan:
+          list_required: false
+          list_default: active plan resolved once and returned as filters.plan
+          get_required: false
+          get_default: active plan resolved once and returned in the response source
+          pattern: '^(plan:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|legacy-plan:[0-9a-f]{64})$'
+        task:
+          get_required: true
+          pattern: '^[1-9][0-9]*$'
+    plans:
+      list: agentera state plan list [--limit N] [--cursor TOKEN] --format json
+      get: agentera state plan get --plan PLAN_ID --format json
+      selectors:
+        plan:
+          get_required: true
+          pattern: '^(plan:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|legacy-plan:[0-9a-f]{64})$'
+    experiments:
+      list: agentera state experiments list --objective OBJECTIVE_ID [--limit N] [--cursor TOKEN] --format json
+      get: agentera state experiments get --objective OBJECTIVE_ID --number N --format json
+      publish: agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml --format json
+      selectors:
+        objective:
+          list_required: true
+          get_required: true
+          pattern: '^(objective:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|legacy-objective:[0-9a-f]{64})$'
+        number:
+          get_required: true
+          pattern: '^(0|[1-9][0-9]*)$'
+  failures:
+    schema_version: agentera.stateFailure.v1
+    required_fields: [class, message, syntax, example, recovery]
+    classes:
+      invalid_request: malformed, duplicate, missing, or incompatible selector
+      unsupported_artifact: collection is not exposed by the requested grammar
+      not_found: a valid exact identity has no matching record
+      ambiguous: legacy derivation, duplicate identity, or path compatibility has multiple candidates
+      corrupt: selected state cannot be parsed or validated safely
+      incomplete: selected record exists but required detail is unavailable
+      cursor_invalid: cursor is malformed or bound to different selectors, filters, collection, or order
+      cursor_snapshot_unavailable: the exact cursor snapshot cannot be resumed
+      unsupported_state: authority cannot return a safe bounded envelope
+    exit_codes:
+      usage: 2
+      state_or_compatibility_failure: 1
+    legacy_diagnostic_rule: >-
+      Compatibility failures include candidate provenance and a working recovery
+      command but never synthesize an ID, objective scope, task, experiment, or
+      archive event.
+  collections:
+    - collection_id: progress.records
+      artifact_id: progress
+      growth: append_only_unbounded
+      identity: 'progress:<positive-entry-number>'
+      storage_ownership: immutable_numbered_archive_with_bounded_current_projection
+      ordering: entry_number_desc
+      bounds: count_1_to_100_and_serialized_utf8_budget
+      cursor: opaque_snapshot_cursor
+      omission: explicit_with_advancing_cursor_or_exact_get
+      get: agentera state progress get --number N --format json
+    - collection_id: decisions.records
+      artifact_id: decisions
+      growth: append_only_unbounded_with_declared_mutable_overlay
+      identity: 'decisions:<positive-entry-number>'
+      storage_ownership: immutable_numbered_archive_plus_decision_overlay_with_bounded_current_projection
+      ordering: entry_number_desc
+      bounds: count_1_to_100_and_serialized_utf8_budget
+      cursor: opaque_snapshot_cursor
+      omission: explicit_with_advancing_cursor_or_exact_get
+      get: agentera state decisions get --number N --format json
+    - collection_id: health.records
+      artifact_id: health
+      growth: append_only_unbounded
+      identity: 'health:<positive-entry-number>'
+      storage_ownership: immutable_numbered_archive_with_bounded_current_projection
+      ordering: entry_number_desc
+      bounds: count_1_to_100_and_serialized_utf8_budget
+      cursor: opaque_snapshot_cursor
+      omission: explicit_with_advancing_cursor_or_exact_get
+      get: agentera state health get --number N --format json
+    - collection_id: plan.plans
+      artifact_id: plan
+      growth: one_active_plus_append_only_immutable_file_archives
+      identity: retrieval.identity.plan
+      storage_ownership: active_plan_file_and_immutable_plan_archive_files
+      ordering: created_desc_then_plan_id_asc
+      bounds: count_1_to_100_and_serialized_utf8_budget
+      cursor: opaque_snapshot_cursor
+      omission: explicit_with_advancing_cursor_or_exact_get
+      get: retrieval.commands.plans.get
+    - collection_id: plan.tasks
+      artifact_id: plan
+      growth: mutable_while_plan_active_then_immutable_with_archived_plan
+      identity: retrieval.identity.task
+      storage_ownership: owning_active_plan_file
+      ordering: task_number_asc
+      bounds: count_1_to_100_and_serialized_utf8_budget
+      cursor: opaque_snapshot_cursor
+      omission: explicit_with_advancing_cursor_or_exact_get
+      get: retrieval.commands.plan_tasks.get
+    - collection_id: experiments.records
+      artifact_id: experiments
+      growth: append_only_objective_scoped_with_10_full_40_summary_50_projection
+      identity: retrieval.identity.experiment
+      storage_ownership: objective_scoped_durable_records_and_bounded_10_40_50_projection
+      ordering: experiment_number_desc
+      bounds: count_1_to_100_serialized_utf8_budget_and_projection_10_40_50
+      cursor: opaque_snapshot_cursor
+      omission: explicit_with_advancing_cursor_or_exact_get_or_legacy_unavailable_diagnostic
+      get: retrieval.commands.experiments.get
+    - collection_id: todo.items
+      artifact_id: todo
+      growth: bounded_current_working_set_with_resolved_compaction
+      identity: absent_legacy_markdown_item_identity
+      storage_ownership: TODO.md
+      ordering: severity_then_document_order
+      bounds: 10_open_40_resolved_summary_50_total_projection
+      cursor: none_not_publicly_pageable
+      omission: current_query_must_report_omission_but_exact_get_is_unavailable
+      get: unsupported_no_stable_identity
+    - collection_id: docs.entries
+      artifact_id: docs
+      growth: bounded_document_inventory
+      identity: canonical_document_path_when_present
+      storage_ownership: .agentera/docs.yaml_or_docs_mapping
+      ordering: document_order
+      bounds: artifact_budget_and_projection_output_budget
+      cursor: none_not_publicly_pageable
+      omission: current_query_must_report_omission_but_exact_get_is_unavailable
+      get: unsupported_no_public_get
+    - collection_id: changelog.entries
+      artifact_id: changelog
+      growth: append_only_public_release_history
+      identity: absent_markdown_entry_identity
+      storage_ownership: CHANGELOG.md
+      ordering: document_order_newest_release_first
+      bounds: no_collection_page_contract
+      cursor: none_not_publicly_pageable
+      omission: query_result_may_be_filtered_but_must_not_claim_exact_retrieval
+      get: unsupported_no_stable_identity
+  non_collections:
+    - artifact_id: vision
+      behavior: singleton_document_no_list_or_get_grammar
+    - artifact_id: design
+      behavior: singleton_document_no_list_or_get_grammar
+    - artifact_id: objective
+      behavior: one_selected_objective_document; identity is only a required experiments selector in this task
+    - artifact_id: plan_archive
+      behavior: storage special case represented publicly by plan.plans
+    - artifact_id: optimize_harness
+      behavior: local harness storage, not public state retrieval
+  gap_closure_evidence:
+    - surface: agentera state plan --format json / plans
+      declared_gap: PLAN_HISTORY_CATALOG_LIMIT capped catalog rows without collection-level omission recovery
+      outcome: closed
+      closure: active and archive-only plan_catalog responses report omitted, omitted_count, omission_reason, and executable public list/get recovery; the plan list surface owns count and serialized-byte continuation
+    - surface: agentera state plan --format json / source.archive_paths
+      declared_gap: archive paths were capped at 10 with only an omitted count and no stable recovery
+      outcome: closed
+      closure: source reports archive_paths_omitted, archive_paths_omitted_count, archive_paths_omission_reason, and plan list/get recovery instead of requiring path traversal
+    - surface: agentera state plan text / tasks
+      declared_gap: legacy text projection capped tasks at 10 and needed explicit whole-record omission recovery
+      outcome: closed
+      closure: text retains complete scalar values and whole task rows only, caps rows at 10 and total output at budgets.list.max_utf8_bytes, and reports count/byte omissions with task list/get or exact-plan recovery without ellipsis
+    - surface: agentera state plan --format json / tasks
+      declared_gap: structured plan projection needed deterministic whole-task byte omission and public recovery
+      outcome: closed
+      closure: JSON and YAML report omitted, omitted_count, omission_reason, and task list/get recovery; task list JSON/YAML enforce budgets.list.max_utf8_bytes
+    - surface: legacy agentera state experiments projection
+      declared_gap: the pre-list/get projection is objective-selected rather than a stable cross-objective collection
+      outcome: out_of_scope
+      closure: objective-scoped experiments list/get is the supported retrieval surface; adding identity or pagination to the legacy projection would duplicate that contract
+  plan_archive_diagnostics:
+    classification: pre_existing_compatibility_caveat
+    smoke_test_behavior: >-
+      A lifecycle diagnostic on an unrelated archived plan degrades list/catalog
+      status and remains visible, but does not fail exact retrieval of a different
+      valid plan. Exact get fails only when the selected candidate is invalid,
+      corrupt, or ambiguous. Read-only smoke tests assert diagnostics and never
+      repair or rewrite archive history.
+    known_live_diagnostics:
+      - plan-2026-06-04-d56-parity-closeout.yaml
+      - plan-2026-07-08-cliDistributionMajor-secondary-signal.yaml
+
+consumer_matrix:
+  status: active_authority
+  purpose: >-
+    Mechanically account for every capability source and bundled artifact-schema
+    consumer of numbered decisions, progress, and health state. The artifact
+    schemas remain the role authority; this matrix binds each declared consumer
+    to the bounded startup and exact retrieval contracts below.
+  source_root: packages/cli/src/capabilities/<capability>/instructions.ts
+  bundle_root: skills/agentera/capabilities/<capability>/schemas/artifacts.yaml
+  required_capabilities:
+    - status
+    - vision
+    - discuss
+    - research
+    - plan
+    - build
+    - optimize
+    - audit
+    - document
+    - profile
+    - design
+    - orchestrate
+  access_contract:
+    startup: agentera prime --context <capability> --format json
+    list: agentera state <artifact-id> list --limit 20 --format json
+    get: agentera state <artifact> get --id ID --format json
+    policy: >-
+      Use the bounded prime context first, then the bounded state list for
+      discovery and exact state get for requested detail. Raw artifact or Git
+      traversal is not a normal consumer path; it is allowed only for a named
+      corruption or CLI-defect diagnostic exception, and must preserve missing,
+      ambiguous, compacted, and satisfaction-incomplete provenance.
+  capabilities:
+    - name: status
+      source: packages/cli/src/capabilities/status/instructions.ts
+      bundle: skills/agentera/capabilities/status/schemas/artifacts.yaml
+      state_consumers: [decisions, progress, health]
+    - name: vision
+      source: packages/cli/src/capabilities/vision/instructions.ts
+      bundle: skills/agentera/capabilities/vision/schemas/artifacts.yaml
+      state_consumers: [decisions, progress, health]
+    - name: discuss
+      source: packages/cli/src/capabilities/discuss/instructions.ts
+      bundle: skills/agentera/capabilities/discuss/schemas/artifacts.yaml
+      state_consumers: [decisions]
+    - name: research
+      source: packages/cli/src/capabilities/research/instructions.ts
+      bundle: skills/agentera/capabilities/research/schemas/artifacts.yaml
+      state_consumers: []
+    - name: plan
+      source: packages/cli/src/capabilities/plan/instructions.ts
+      bundle: skills/agentera/capabilities/plan/schemas/artifacts.yaml
+      state_consumers: [decisions, progress, health]
+    - name: build
+      source: packages/cli/src/capabilities/build/instructions.ts
+      bundle: skills/agentera/capabilities/build/schemas/artifacts.yaml
+      state_consumers: [decisions, progress, health]
+    - name: optimize
+      source: packages/cli/src/capabilities/optimize/instructions.ts
+      bundle: skills/agentera/capabilities/optimize/schemas/artifacts.yaml
+      state_consumers: [decisions, progress]
+    - name: audit
+      source: packages/cli/src/capabilities/audit/instructions.ts
+      bundle: skills/agentera/capabilities/audit/schemas/artifacts.yaml
+      state_consumers: [decisions, progress, health]
+    - name: document
+      source: packages/cli/src/capabilities/document/instructions.ts
+      bundle: skills/agentera/capabilities/document/schemas/artifacts.yaml
+      state_consumers: [decisions, progress, health]
+    - name: profile
+      source: packages/cli/src/capabilities/profile/instructions.ts
+      bundle: skills/agentera/capabilities/profile/schemas/artifacts.yaml
+      state_consumers: [decisions]
+    - name: design
+      source: packages/cli/src/capabilities/design/instructions.ts
+      bundle: skills/agentera/capabilities/design/schemas/artifacts.yaml
+      state_consumers: [progress]
+    - name: orchestrate
+      source: packages/cli/src/capabilities/orchestrate/instructions.ts
+      bundle: skills/agentera/capabilities/orchestrate/schemas/artifacts.yaml
+      state_consumers: [decisions, progress, health]
+  unchanged_archive_conventions:
+    plan:
+      location: .agentera/archive/plan-*.yaml
+      role: existing plan lifecycle archive
+      numbered_entry_discovery: forbidden
+      execution: archived plans remain historical and non-executable
+    vision:
+      location: .agentera/archive/vision-*.yaml
+      role: existing replace-mode vision archive
+      numbered_entry_discovery: forbidden
+      format: unchanged
+
+experiment_archival:
+  status: implemented
+  authority_boundary: >-
+    This is an objective-scoped full-detail publication archive for new
+    experiments. It is not part of the numbered archive authority, does not
+    migrate experiments into .agentera/archive, and does not reconstruct
+    detail already dropped by legacy projection compaction.
+  layout:
+    path_template: .agentera/<objective-root>/<objective>/archive/experiments/<experiment-number>.yaml
+    canonical_objective_root: optimize
+    readable_legacy_objective_roots: [optimera]
+    ownership: objective_directory
+    path_override: forbidden
+  identity:
+    stable_id: '<objective-id>/experiment:<non-negative-integer>'
+    path_selector: experiment_number
+    objective_binding: envelope.objective_id must equal the resolved objective header.id
+    content_binding: record.number must equal envelope.experiment_number
+  envelope:
+    schema_version: agentera.experimentArchive.v1
+    required_fields:
+      - schemaVersion
+      - stable_id
+      - objective_id
+      - experiment_number
+      - record
+      - record_sha256
+      - provenance
+    provenance_required_fields: [authority, objective_id, experiment_id, storage_scope, publication_order]
+    authority: references/artifacts/state-storage-authority.yaml
+    hash: sha256_of_canonical_record_json
+  publication:
+    order:
+      - validate_objective_identity
+      - validate_full_experiment_record
+      - validate_archive_envelope
+      - stage_and_compact_projection
+      - create_and_fsync_each_missing_archive_directory_entry
+      - publish_and_fsync_immutable_archive
+      - replace_and_fsync_projection
+    archive_before_projection: true
+    mutation_policy: no_overwrite_after_publication
+    retry_policy: >-
+      Byte-equivalent envelope bytes at the same stable identity are an
+      idempotent replay. Different bytes at that identity are an immutable
+      conflict and preserve both archive and projection bytes.
+    interruption_policy: >-
+      Failure before archive publication leaves archive and projection
+      unchanged. Failure after durable archive publication may leave the new
+      archive with the old projection; retry reuses that archive and publishes
+      the projection without duplicating detail.
+    directory_durability: >-
+      Each newly created archive path component is followed by fsync of its
+      parent before publication advances. In particular, creating the
+      experiments directory requires fsync of the archive directory before an
+      experiment record can be considered durably published.
+    exact_full_replay_recovery: >-
+      If the projection already contains the byte-equivalent full record but
+      its required archive is absent, publication reconstructs that one archive
+      from the exact retained detail before returning replay success. Summary-
+      only and dropped legacy detail remain unavailable and are never inferred.
+  projection:
+    policy: uniform_10_40_50
+    full_entries: 10
+    summary_entries: 40
+    total_entries: 50
+    archive_effect: none
+  compatibility:
+    legacy_projection_records: readable_without_archive
+    pre_feature_dropped_detail: unavailable_and_never_fabricated
+
+storage:
+  project_root:
+    fixed: true
+    resolution: >-
+      The caller's selected project root. The archive is project-local and is
+      never resolved through AGENTERA_HOME, a profile directory, XDG data, or a
+      docs.yaml path override.
+    archive_root: .agentera/archive
+    archive_path_template: .agentera/archive/<artifact-id>/<entry-number>.yaml
+    path_override: forbidden
+    project_boundary: >-
+      The resolved archive path and every parent must remain beneath the
+      selected project root. URI paths, traversal segments, encoded traversal,
+      and symlink escapes are invalid.
+  archive:
+    record_type: immutable_numbered_entry
+    supported_artifact_directories: [progress, decisions, health]
+    filename:
+      entry_number: positive_integer
+      canonical_form: base-10 decimal without a leading plus sign or leading zero
+      accepted_pattern: '^[1-9][0-9]*$'
+      directory_name: artifact_id
+      extension: .yaml
+    publication_order: archive_before_projection
+    mutation_policy: no_overwrite_after_publication
+    retry_policy: >-
+      An identical artifact_id, entry_number, and canonical record is an
+      idempotent replay. The same identity with different canonical content is
+      an immutable conflict and must not replace existing bytes.
+    discovery_policy: >-
+      Only the exact supported path template is eligible. Malformed names,
+      unsupported artifact directories, symlinks, duplicate logical identities,
+      invalid envelopes, and hash mismatches are not valid records.
+
+identity:
+  stable_id:
+    format: <artifact-id>:<entry-number>
+    accepted_pattern: '^(progress|decisions|health):[1-9][0-9]*$'
+    example: decisions:53
+  components:
+    artifact_id: one of the supported artifact values declared by scope
+    entry_number: positive integer from the artifact's entry_number_field
+  uniqueness: stable_id is unique within one project archive
+  ordering:
+    list: entry_number descending, numerically rather than lexicographically
+    tie_breaker: stable_id ascending (defensive only; numbers are unique per artifact)
+    get: exact stable_id match; no topic or summary scan is a substitute
+  legacy_rows:
+    canonical_number: >-
+      A positive entry_number field, or an artifact-labelled summary beginning
+      with Cycle N, Decision N, Audit N, or the decisions-only shorthand DNN.
+      The number is accepted only from that explicit position; arbitrary prose
+      and nested values never establish identity.
+    unaddressable: >-
+      A physical current or legacy-summary row without one explicit number.
+      It is list-only and uses stable_id: null and entry_number: null; no
+      synthetic number, position, or inferred reference is permitted.
+    ambiguous: >-
+      A row containing multiple explicit decision shorthands such as
+      Staging D3+D4. It remains list-only with stable_id: null and is never
+      assigned the first or most recent shorthand.
+    physical_accounting: >-
+      physical counts raw current rows, current archive-summary rows, and
+      validated or rejected numbered archive files. addressable counts those
+      physical rows carrying one explicit number; unaddressable and ambiguous
+      partition the remaining physical rows. addressable_ids counts unique
+      stable-ID groups. mirrored, duplicate, and conflict are non-additive
+      redundancy classifications over addressable rows; omitted counts rows
+      not emitted on the current bounded page.
+
+envelope:
+  schema_version: agentera.stateArchiveEntry.v1
+  required_fields:
+    - schemaVersion
+    - artifact_id
+    - entry_number
+    - record
+    - record_sha256
+  field_contract:
+    schemaVersion: exact string agentera.stateArchiveEntry.v1
+    artifact_id: supported artifact ID matching the archive directory
+    entry_number: positive integer matching the filename and record identity field
+    record: complete pre-projection entry, not a compact summary
+    record_sha256: lowercase SHA-256 of the canonical record bytes
+  canonical_record:
+    encoding: UTF-8
+    serialization: canonical JSON with recursively sorted object keys and no whitespace
+    arrays: preserve source order
+    hash_input: record only, excluding the envelope
+  identity_checks:
+    - envelope.artifact_id matches the parent artifact directory
+    - envelope.entry_number matches the filename
+    - envelope.entry_number matches record.<artifact entry_number_field>
+    - record_sha256 matches canonical_record
+  forbidden_fields:
+    - commit
+    - commit_hash
+    - git_commit
+    - git_ref
+    - parent_commit
+  provenance_rule: >-
+    Git provenance is durability evidence returned by a later diagnostic
+    surface, never per-entry commit bookkeeping and never part of immutable
+    record identity.
+
+overlays:
+  location: .agentera/overlays/decisions.yaml
+  project_root_fixed: true
+  docs_yaml_override: forbidden
+  schema_version: agentera.decisionOverlay.v1
+  supported_artifact: decisions
+  identity_key: decisions:<decision-number>
+  storage_shape: >-
+    A mapping keyed by stable decision ID. Each value contains only the
+    authority-declared mutable paths and never replaces the immutable archive
+    record.
+  mutable_paths:
+    - satisfaction.state
+    - satisfaction.evidence
+    - satisfaction.user_confirmation.confirmed_by
+    - satisfaction.user_confirmation.confirmed_at
+  derived_paths:
+    - satisfaction.review_needed
+    - satisfaction.source
+    - satisfaction.caveats
+  immutable_paths:
+    - number
+    - date
+    - question
+    - context
+    - alternatives
+    - choice
+    - reasoning
+    - confidence
+    - feeds_into
+  state_values: [open, provisionally_satisfied, user_confirmed_satisfied]
+  transition_rules:
+    open:
+      allowed_next: [open, provisionally_satisfied, user_confirmed_satisfied]
+      provisional_requires: non_empty_satisfaction.evidence
+      confirmed_requires: explicit_current_user_confirmation_metadata
+    provisionally_satisfied:
+      allowed_next: [open, provisionally_satisfied, user_confirmed_satisfied]
+      provisional_requires: non_empty_satisfaction.evidence
+      confirmed_requires: explicit_current_user_confirmation_metadata
+    user_confirmed_satisfied:
+      allowed_next: [user_confirmed_satisfied]
+      downgrade: forbidden_without_explicit_current_user_confirmation
+  decision_53_rules:
+    missing_satisfaction: valid legacy state; derive review_needed=true
+    open: review_needed=true
+    provisional: review_needed=true until explicit user confirmation
+    confirmed: review_needed=false only with confirmed_by and confirmed_at
+    inference: forbidden from commits, downstream references, summaries, or Git history
+    protected_review: unresolved decisions remain visible and never block archive storage
+
+revisions:
+  location: .agentera/revisions/decisions.yaml
+  project_root_fixed: true
+  docs_yaml_override: forbidden
+  schema_version: agentera.decisionRevision.v1
+  supported_artifact: decisions
+  identity_key: decisions:<decision-number>
+  storage_shape: >-
+    A mapping keyed by stable decision ID. Each value is an ordered list of
+    immutable revision records carrying only authority-declared amendable
+    content paths plus revision provenance. A revision never replaces the
+    immutable numbered archive record and never replaces the satisfaction
+    overlay; it is additional immutable evidence composed at read time.
+  amendable_paths:
+    - question
+    - context
+    - alternatives
+    - choice
+    - reasoning
+    - confidence
+    - feeds_into
+  identity_paths:
+    - number
+  temporal_paths:
+    - date
+  separation_from_overlay: >-
+    Amendments never touch satisfaction overlay paths. Satisfaction updates
+    remain under overlays; content amendments remain under revisions. Each
+    authority composes its own evidence and neither rewrites the other.
+  immutability: >-
+    Original numbered archive records remain immutable historical evidence.
+    Revisions are additional immutable evidence appended in declared order;
+    no revision overwrites, reorders, or deletes a prior revision. A revision
+    is byte-stable after publication and an identical revision is an
+    idempotent replay.
+  provenance: >-
+    Revision evidence carries revision provenance only. It is never labeled
+    as historical archive provenance. A revision bootstrapped from a complete
+    legacy projection record may carry degraded_projection provenance and
+    never historical_archive provenance.
+  publication_order:
+    - validate_target_identity
+    - validate_amendment_vocabulary
+    - stage_revision
+    - publish_revision
+    - update_effective_projection
+  apply_state: implemented
+  apply_state_note: >-
+    The revision authority and amend command publish record-local amendments
+    with recovery. A valid dry-run reports the exact revision, effective record,
+    and projection effect without writing any file. Apply writes a
+    record-local override to the revision document only (preserving unrelated
+    entries' bytes), retries converge on a stable revision identity, and an
+    identical re-submission is an idempotent replay. The decisions projection
+    is never rewritten by an amendment; effective detail composes
+    base→revisions→overlay. Amend execution still refuses before side effects
+    for an unsafe target-only change, a duplicate-revision conflict, a stale
+    base hash, or an unsafe target identity, returning an actionable retry or
+    repair action. Discover the contract with
+    `agentera state decisions explain --verb amend --format json`.
+
+projections:
+  archive:
+    role: complete immutable historical detail
+    source_of_truth_for: historical_record_fields
+    omission: never omit fields from an archive record
+  current:
+    role: bounded active projection for current artifact consumers
+    default_capacity:
+      active_entries: 10
+      summary_entries: 40
+      total_entries: 50
+      semantics: >-
+        These are projection defaults, not retention or deletion limits. Entries
+        outside the default display capacity remain in the numbered archive;
+        entries whose archive cannot be verified remain full in the projection
+        with recovery metadata rather than being discarded.
+    legacy_summary_overflow:
+      source: legacy_summary
+      compatibility: degraded
+      detail_availability: unavailable
+      archive_verified: false
+      semantics: >-
+        Legacy inline summaries without a verified numbered record are bounded
+        like every other projection item. If omitted, omission_provenance keeps
+        their degraded and incomplete status explicit; omission never promotes
+        them to archive-backed detail or reconstructs missing fields.
+    paths:
+      progress: .agentera/progress.yaml
+      decisions: .agentera/decisions.yaml
+      health: .agentera/health.yaml
+    source_of_truth_for: current_projection_and_legacy_compatibility_state
+    archive_relationship: >-
+      A current entry may be full, summary-only, or absent from the projection;
+      archive presence and hash verification determine whether full detail is
+      available. Current mutable decision overlay values are composed at read
+      time and do not rewrite archive bytes.
+  summary:
+    role: bounded list and startup representation
+    required_item_fields: [stable_id, artifact_id, entry_number, addressable, classification, detail_availability, source]
+    nullable_item_fields:
+      - stable_id
+      - entry_number
+    detail_availability: [full, summary, unavailable]
+    source_values: [archive, current_projection, legacy_full, legacy_summary]
+    classification_values: [canonical, mirrored, duplicate, conflict, ambiguous, unaddressable, corrupt]
+    counts:
+      required: [physical, addressable, addressable_ids, unaddressable, ambiguous, mirrored, duplicate, conflict, omitted]
+      reconciliation: >-
+        physical = addressable + unaddressable + ambiguous;
+        addressable_ids is the unique logical count and is not added to the
+        physical count; mirrored, duplicate, and conflict are overlapping
+        redundancy diagnostics, not partition buckets.
+    omission: >-
+      Omitted detail is represented by omitted=true, omitted_count,
+      omission_reason, and a get command pointer. It is never silently
+      truncated, represented as a fabricated summary, or treated as missing
+      history without provenance.
+  startup:
+    role: bounded orientation and capability-startup projection
+    required_fields: [command, status, source, source_contract]
+    allowed_payload: >-
+      Counts, bounded summaries, actionable stable IDs, detail availability,
+      omission metadata, compatibility classification, and retrieval pointers.
+    forbidden_payload: [raw_archive_records, raw_yaml, unbounded_entry_arrays, Git_history_scan]
+    incomplete_state: >-
+      Preserve degraded or blocked compatibility and omission metadata in
+      source_contract; do not fall back to raw archive traversal merely to fill
+      an omitted field.
+
+api:
+  namespace: agentera state
+  artifact_syntax: agentera state <artifact-id>
+  formats: [text, json, yaml]
+  direct_get:
+    command: agentera state <artifact-id> get --number N --format json
+    examples:
+      progress: agentera state progress get --number 747 --format json
+      decisions: agentera state decisions get --number 53 --format json
+      health: agentera state health get --number 29 --format json
+    required_selector: --number N
+    result: >-
+      One complete record composed from the immutable archive and only the
+      authority-declared current overlay fields, with stable_id, source,
+      detail_availability, compatibility, and provenance metadata.
+    archive_only: direct retrieval reads the exact numbered record without scanning unrelated records
+  list:
+    command: agentera state <artifact-id> list [--limit N] [--cursor TOKEN] --format json
+    examples:
+      progress: agentera state progress list --limit 20 --format json
+      decisions_next_page: agentera state decisions list --limit 20 --cursor TOKEN --format json
+    default_limit: 20
+    minimum_limit: 1
+    maximum_limit: 100
+    ordering: identity.ordering.list
+    response_fields:
+      required: [command, status, entries, counts, source, filters, snapshot, source_contract]
+      entry: [stable_id, artifact_id, entry_number, current_status, detail_availability, source, compatibility, provenance]
+      optional_entry: [summary, record_status, overlay_applied, retrieval]
+    empty_result: status=ok with entries=[] and counts.total=0; absence is not an error
+  durability:
+    command: agentera check durability [--project PATH] [--artifact ARTIFACT] [--number N] [--limit N] --format json
+    entity_command: agentera check durability --project PATH --artifact ARTIFACT --id ID --format json
+    formats: [text, json, yaml]
+    selectors:
+      artifact: optional supported numbered archive artifact ID
+      number: optional positive entry number; requires artifact
+      id: entity-mode bare entity ID; requires artifact and replaces number after cutover
+      limit: optional bounded result count
+    default_limit: 100
+    maximum_limit: 100
+    status_values: [complete, degraded, unavailable]
+    local_values: [verified, unavailable, corrupt]
+    git_values: [verified, degraded, unavailable]
+    response_fields:
+      required: [command, status, project, read_only, remote_contact, head, counts, entries, diagnostics, source_contract]
+      entry: [stable_id, artifact_id, entry_number, status, local, git]
+    guarantees:
+      read_only: true
+      remote_contact: forbidden
+      writes_independent: true
+      head_capture: >-
+        Capture the local HEAD before inspection and after inspection. If the
+        values differ, report changed_head and do not claim committed recovery.
+      deterministic: >-
+        With unchanged local files and reachable refs, repeated checks emit the
+        same ordered result and do not create state or contact a remote.
+  entity_migration_discovery:
+    command: agentera state migrate entities --project PATH --dry-run --format json
+    implementation: implemented
+    read_only: true
+    writes: forbidden
+    authority: entity_migration.read_only_preview
+  cursor:
+    syntax: opaque TOKEN returned as response.next_cursor
+    first_page: omit --cursor to establish a snapshot
+    snapshot_identity: >-
+      deterministic hash of ordered candidate IDs, archive hashes, legacy
+      projection hashes when no archive exists, filters, and overlay revision.
+    snapshot_scope: artifact and filters are bound to the cursor; limit may change between pages
+    append_behavior: >-
+      Entries appended after the first page are excluded from that cursor's
+      snapshot. They appear only in a new listing without the old cursor.
+    continuation: >-
+      Continue strictly after the last emitted numeric entry number. Never
+      restart from page one, skip an entry, or duplicate an entry.
+    unavailable: return cursor_snapshot_unavailable rather than silently creating a new snapshot
+    opacity: callers must not parse, construct, or compare token internals
+  filters:
+    allowed: artifact-specific existing filters plus --limit and --cursor
+    filter_binding: every filter value is included in snapshot identity
+    invalid_filters: structured failure with syntax, valid values, and example
+
+failures:
+  schema_version: agentera.stateFailure.v1
+  envelope:
+    required_fields: [schemaVersion, status, error]
+    status: fail
+    error_required_fields: [class, message, syntax, example, recovery]
+    error_optional_fields: [artifact_id, entry_number, stable_id, details, valid_values]
+  exit_codes:
+    invalid_input: 2
+    operational_failure: 1
+  classes:
+    invalid_request:
+      exit_class: invalid_input
+      use_for: malformed syntax, missing selector, invalid limit, or invalid cursor format
+    unsupported_artifact:
+      exit_class: invalid_input
+      use_for: artifact outside scope.supported_artifacts
+    not_found:
+      exit_class: operational_failure
+      use_for: requested stable ID has no available current or archive record
+    ambiguous:
+      exit_class: operational_failure
+      use_for: multiple legacy candidates or conflicting identities prevent safe selection
+    corrupt:
+      exit_class: operational_failure
+      use_for: malformed YAML, invalid envelope, hash mismatch, unsafe path, symlink, or duplicate identity
+    incomplete:
+      exit_class: operational_failure
+      use_for: a requested complete record is represented only by an irrecoverable legacy summary
+    immutable_conflict:
+      exit_class: operational_failure
+      use_for: same stable ID has different canonical content; existing bytes remain untouched
+    cursor_invalid:
+      exit_class: invalid_input
+      use_for: token is malformed, bound to another artifact, or bound to different filters
+    cursor_snapshot_unavailable:
+      exit_class: operational_failure
+      use_for: the original snapshot cannot be reproduced exactly
+    project_boundary:
+      exit_class: invalid_input
+      use_for: path resolution would leave the selected project root
+    unsupported_state:
+      exit_class: operational_failure
+      use_for: state format is outside the declared compatibility authority
+  guidance_rule: >-
+    Every failure includes the valid command syntax, a concrete example, and a
+    recovery action. A failure must not silently downgrade a complete record,
+    retry an invalid cursor as a fresh listing, or invent missing history.
+
+compatibility:
+  classifications: [complete, degraded, blocked, unsupported]
+  dimensions:
+    local_read: local project state and numbered archive availability
+    detail: whether full record fields are available without inference
+    git_durability: optional committed-history evidence only; never a write prerequisite
+  cases:
+    new:
+      classification: complete
+      local_read: complete
+      detail: complete
+      git_durability: optional
+      behavior: numbered archive is canonical; current projection is bounded
+    legacy_full:
+      classification: degraded
+      local_read: complete
+      detail: complete
+      git_durability: unavailable_until_migrated
+      behavior: full inline current/legacy entry is usable, but provenance declares noncanonical storage and migration-needed
+    legacy_summary:
+      classification: degraded
+      local_read: complete
+      detail: incomplete
+      git_durability: optional
+      behavior: summary and retained fields are usable; missing fields stay missing and are never reconstructed
+    non_git:
+      classification: complete
+      local_read: complete
+      detail: based_on_local_records
+      git_durability: unavailable
+      behavior: local archive reads and writes remain supported; no Git operation is attempted
+    shallow:
+      classification: degraded
+      local_read: complete_when_local_records_validate
+      detail: based_on_local_records
+      git_durability: history_unavailable
+      behavior: do not claim historical recovery beyond reachable local records
+    ambiguous:
+      classification: blocked
+      local_read: affected_identity_blocked
+      detail: not_safe_to_select
+      git_durability: not_evaluated
+      behavior: preserve candidates and require explicit disambiguation; never choose by recency or Git guess
+    corrupt:
+      classification: blocked
+      local_read: affected_record_blocked
+      detail: not_trusted
+      git_durability: not_evaluated
+      behavior: reject the affected record, preserve its bytes for diagnostics, and continue only with independently valid records
+    unsupported:
+      classification: unsupported
+      local_read: unsupported
+      detail: unavailable
+      git_durability: not_evaluated
+      behavior: identify the unsupported artifact or format and return valid supported values
+  precedence: corrupt > ambiguous > unsupported > degraded > complete
+  no_reconstruction: >-
+    Compatibility reports provenance and availability only. It does not
+    reconstruct missing decision fields, promote summaries to full records, or
+    use Git history to satisfy a current source contract.
+  legacy_label_coexistence:
+    dimensions:
+      - confidence
+    current_vocabulary: [firm, provisional, exploratory]
+    current_vocabulary_ref: protocol.yaml DECISION_LABELS (DL1-DL3)
+    known_legacy_examples: [high, medium, low]
+    classification_rule: >-
+      A label value is unsupported when it is not in current_vocabulary. An
+      unsupported inherited label on a record the caller did not touch is
+      explicit legacy state: it is preserved byte- and value-semantically,
+      reported as a legacy caveat, never coerced to the current vocabulary,
+      and never blocks an append, satisfaction update, or amend on a
+      different target. A confidence label supplied by append or amend is new
+      or amended content and must be a current_vocabulary value; otherwise the
+      operation rejects before side effects.
+    no_silent_normalization: >-
+      Unsupported inherited labels are never rewritten to current values
+      without explicit user migration consent. Reads classify them as legacy
+      and never silently promote them to current vocabulary or claim stronger
+      provenance than exists.
+
+budgets:
+  schema_version: agentera.stateOutputBudget.v1
+  measurement:
+    encoding: UTF-8
+    bytes: serialized byte length after encoding, including the final newline
+    json_serializer: JSON.stringify(value, null, 2) plus newline
+    yaml_serializer: YAML.stringify(value) as emitted by the CLI
+    measure_before_emit: true
+  list:
+    max_utf8_bytes: 32768
+    benchmark:
+      small:
+        entries: 100
+        max_latency_ms: 5000
+        max_heap_delta_bytes: 67108864
+      large:
+        entries: 1000
+        max_latency_ms: 15000
+        max_heap_delta_bytes: 268435456
+      response_max_utf8_bytes: 32768
+    index_decision:
+      decision: no_index
+      trigger: >-
+        Defer a persistent index until the large fixture exceeds any declared
+        latency, heap, or response threshold on a reproducible authority test.
+  projection:
+    max_utf8_bytes: 32768
+    applies_to: current, summary, and migration result responses
+    required_when_over_budget: [omitted, omitted_count, omission_reason, retrieval]
+    omission_semantics: >-
+      Remove optional detail entries in deterministic numeric order from the
+      response, retain required identity/count/source fields, and expose a next
+      retrieval pointer. Never split UTF-8, truncate a scalar, or silently drop
+      an entry. If required/source fields themselves exceed the budget, emit a
+      measured minimal degraded envelope with projection output-budget error
+      metadata rather than returning an over-budget payload.
+  startup:
+    source_manifest: scripts/json_output_surface_manifest.yaml
+    source_work:
+      schema_version: agentera.startupSourceWorkBudget.v1
+      measurement: >-
+        Count current projection entry rows and archive files inspected by the
+        source-side metadata query. Full archive records are never retained by
+        startup consumers.
+      small:
+        max_current_entries: 100
+        max_archive_files: 100
+        max_latency_ms: 5000
+        max_heap_delta_bytes: 67108864
+      large:
+        max_current_entries: 1000
+        max_archive_files: 1000
+        max_latency_ms: 15000
+        max_heap_delta_bytes: 268435456
+      serialized_output:
+        # Generic prime capability capsules retain the full instructions body.
+        # The status capability is a separate one-call surface with a stricter
+        # bound declared below and in the JSON surface manifest.
+        prime_capability_context_max_utf8_bytes: 55000
+        prime_status_context_max_utf8_bytes: 25000
+    surfaces:
+      prime_briefing:
+        manifest_id: prime-briefing
+        # Bounded default decision brief (Plan Task 3): the bare default
+        # `agentera prime --format json` projects the full orientation payload
+        # to routing-essential leaves plus named recovery pointers for omitted
+        # rich state. Pretty UTF-8 JSON + trailing newline is measured and an
+        # over-budget brief is rejected in favor of a bounded degraded envelope;
+        # diagnostics stay on stderr. prime_dashboard keeps full current state
+        # while omitting duplicated ordinary history entries with recovery.
+        max_utf8_bytes: 12000
+      prime_dashboard:
+        manifest_id: prime-dashboard
+        max_utf8_bytes: 35000
+      prime_status_context:
+        manifest_id: prime-status-context
+        # Status startup includes the full instructions capsule as well as the
+        # bounded Task 3 decision brief. Diagnostics remain on stderr.
+        max_utf8_bytes: 25000
+      prime_sparse:
+        manifest_id: prime-fields-sparse
+        max_utf8_bytes: 28000
+    required_when_over_budget: [omitted, omitted_count, omission_reason, retrieval]
+    omission_semantics: >-
+      Omit optional historical detail and retain counts, actionable IDs,
+      compatibility, source_contract, and exact get/list command pointers. The
+      caller must be able to distinguish omitted detail from unavailable detail.
+      The bare default briefing is a bounded decision brief: every required
+      top-level field stays present (content projected to routing-essential
+      leaves), missing versus present-but-empty stays distinguishable through
+      state_presence, and each omitted rich-state family carries a named
+      authoritative recovery command. When even the projected brief exceeds the
+      budget, emit a measured bounded degraded envelope that keeps command,
+      status, mode, state_presence, a brief source_contract, and the
+      byte-budget error with a recovery command; never emit an over-budget
+      payload. Diagnostics are measured on stderr separately.
+  validation:
+    authority: this file plus the referenced JSON surface manifest
+    drift_rule: tests fail if manifest IDs or byte values disagree with this contract