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

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

@@ -0,0 +1,2930 @@
+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
+    numbered archives, aggregate overlays, and aggregate revision documents
+    remain migration input while that marker is absent; no independent legacy
+    read or 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 [--topic TEXT] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: agentera state progress get --id ID --format json
+      decisions:
+        list: agentera state decisions list [--topic TEXT] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: agentera state decisions get --id ID --format json
+      health:
+        list: agentera state health list [--dimension DIMENSION] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --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] [--ids-only | --fields FIELDS] --format json
+        get: agentera state plan get --id ID --format json
+      plan_tasks:
+        list: agentera state plan tasks list [PLAN_ID] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: agentera state plan tasks get --id ID --format json
+      objective:
+        list: agentera state objective list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: agentera state objective get --id ID --format json
+      experiments:
+        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: agentera state experiments get --id ID --format json
+      todo:
+        list: agentera state todo list [--severity SEVERITY] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: agentera state todo get --id ID --format json
+      docs:
+        list: agentera state docs list [--topic TEXT] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: agentera state docs get --id ID --format json
+    list_help:
+      schema_version: agentera.entityListHelp.v1
+      defaults:
+        summary_fields: [id, artifact, retrieval.get]
+        selectors:
+          ids_only:
+            flag: --ids-only
+            description: Return only canonical minimum identity, exact-get recovery, and required family minimum fields such as TODO queue_rank.
+          fields:
+            flag: --fields FIELDS
+            description: Select comma-separated lowercase record paths present in the filtered snapshot; identity and exact-get recovery remain present.
+          mutual_exclusion: true
+        bounds: { minimum: 1, default: 20, maximum: 100, max_utf8_bytes: 32768 }
+        formats: [text, json, yaml]
+      families:
+        progress:
+          command_tokens: [progress]
+          bare_read: alias
+          filters:
+            - { flag: --topic TEXT, name: topic, values: free_text }
+            - { flag: --status STATUS, name: status, values: free_text }
+          example: agentera state progress list --limit 20 --format json
+        decisions:
+          command_tokens: [decisions]
+          bare_read: alias
+          filters:
+            - { flag: --topic TEXT, name: topic, values: free_text }
+          example: agentera state decisions list --limit 20 --format json
+        health:
+          command_tokens: [health]
+          bare_read: correction
+          bare_recovery: agentera state health list --limit 20 --format json
+          filters:
+            - { flag: --dimension DIMENSION, name: dimension, values: free_text }
+          example: agentera state health list --limit 20 --format json
+        plans:
+          command_tokens: [plan]
+          bare_read: correction
+          bare_recovery: agentera state plan list --status open --limit 20 --format json
+          filters:
+            - { flag: '--status open|complete|archived', name: status, values: [open, complete, archived] }
+          example: agentera state plan list --status open --limit 20 --format json
+        plan_tasks:
+          command_tokens: [plan, tasks]
+          bare_read: correction
+          bare_recovery: agentera state plan tasks list --limit 20 --format json
+          family_identifier:
+            syntax: PLAN_ID
+            required: false
+            description: Optional bare plan ID; omit it to list tasks from the active plan.
+          filters: []
+          example: agentera state plan tasks list --limit 20 --format json
+        objective:
+          command_tokens: [objective]
+          bare_read: correction
+          bare_recovery: agentera state objective list --limit 20 --format json
+          filters: []
+          example: agentera state objective list --limit 20 --format json
+        experiments:
+          command_tokens: [experiments]
+          bare_read: correction
+          bare_recovery: agentera state objective list --limit 20 --format json
+          family_identifier:
+            syntax: --objective ID
+            required: true
+            description: Required bare objective entity ID.
+          filters: []
+          example: agentera state experiments list --objective qjtrmnpvka --limit 20 --format json
+        todo:
+          command_tokens: [todo]
+          bare_read: alias
+          filters:
+            - { flag: --severity SEVERITY, name: severity, values: free_text }
+            - { flag: --status STATUS, name: status, values: free_text }
+          summary_fields: [id, artifact, public_order, readiness, actionability, queue_rank, reconciliation, retrieval.get]
+          summary_field_notes:
+            public_order:
+              description: Markdown-owned one-based order within the item's public section, or null before reconciliation activation.
+              ownership: markdown_read_projection
+              persisted: false
+              filter: false
+            readiness:
+              description: Public lifecycle state plus whether Agentera readiness declares an explicit blocker.
+              ownership: agentera_operational_projection
+              persisted: false
+              filter: false
+            actionability:
+              description: Read-only TODO readiness outcome and eligibility computed across the complete TODO snapshot.
+              ownership: computed_read_snapshot
+              persisted: false
+              filter: false
+            queue_rank:
+              description: Computed one-based position in the complete ordered TODO snapshot before filters.
+              ownership: computed_read_snapshot
+              persisted: false
+              filter: false
+            reconciliation:
+              description: Global reconciliation status and item-specific drift state for this read snapshot.
+              ownership: computed_read_snapshot
+              persisted: false
+              filter: false
+          example: agentera state todo list --severity critical --ids-only --limit 20 --format json
+        docs:
+          command_tokens: [docs]
+          bare_read: correction
+          bare_recovery: agentera state docs list --limit 20 --format json
+          filters:
+            - { flag: --topic TEXT, name: topic, values: free_text }
+            - { flag: --status STATUS, name: status, values: free_text }
+          example: agentera state docs list --limit 20 --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 }
+    policy:
+      schema_version: agentera.entityPublicRetrievalPolicy.v1
+      status: final
+      authority_boundary: >-
+        This canonical public-retrieval model owns list/get envelopes, cursors,
+        selectors, identities, omissions, structured failures, and output bounds.
+        Entity definitions own family ordering and storage. No other active
+        section may declare public retrieval commands, selectors, or identities.
+      envelope:
+        required_fields:
+          - schemaVersion
+          - command
+          - status
+          - entries
+          - counts
+          - filters
+          - snapshot
+          - source
+          - source_contract
+        counts_required_fields: [total, returned, remaining, candidate, omitted, continuation]
+        status_values: [ok, degraded]
+        bounded_summary_projection:
+          cardinality_owner: summary_rows_after_filters_and_cursor
+          limit_semantics: >-
+            Return exactly min(requested limit, candidates remaining in the bound
+            snapshot) rows. Serialized-byte pressure may remove optional detail
+            from those rows but never removes a selected row.
+          minimum_fields: [id, artifact, retrieval.get]
+          family_minimum_fields:
+            todo: [queue_rank]
+          optional_fields_rule: >-
+            Every declared family summary field that is not a minimum field is
+            optional under byte pressure and is removed as one deterministic tier.
+          queue_rank: >-
+            One-based position in the complete canonically ordered TODO queue
+            before request filters. It is computed from the read snapshot and is
+            never persisted or used to reorder TODO.md.
+          optional_detail_degradation:
+            status: degraded
+            reason: optional_detail_byte_budget
+            row_omission: forbidden
+            scalar_truncation: forbidden
+            required_metadata: [reason, detail_omitted_count, omitted_fields, recovery]
+            omitted_fields_order: lexical
+            recovery: concrete_exact_get_pointer_per_returned_row
+          selectors:
+            ids_only:
+              fields: canonical_minimum_fields
+              optional_summary_fields: excluded
+            fields:
+              fields: canonical_minimum_fields_plus_all_requested_record_paths
+              validation: >-
+                Each lowercase dot path must exist in at least one record in the
+                filtered cursor snapshot. Duplicate, malformed, or absent paths
+                are invalid_request. Requested paths are sorted before projection
+                and cursor binding; a missing value in one row remains absent.
+              scalar_truncation: forbidden
+            mutual_exclusion: ids_only_and_fields
+          byte_pressure:
+            ids_only: reject_without_partial_rows_if_minimum_rows_cannot_fit
+            selected_fields: reject_without_partial_rows_or_fields
+            default: degrade_full_to_summary_then_minimum_before_rejection
+          metadata:
+            continuation: binds_family_identifier_filters_selector_limit_order_and_snapshot
+            exact_get: one_concrete_command_per_returned_row
+      cursor:
+        vocabulary: opaque_snapshot_cursor
+        first_page: omit_cursor
+        response_field: next_cursor
+        binding: [collection, family_identifier, selectors, filters, limit, order, snapshot]
+        invalid_behavior: cursor_invalid
+        unavailable_behavior: cursor_snapshot_unavailable
+        caller_rules: [do_not_parse, do_not_construct, do_not_compare_internals]
+      omission:
+        required_when_candidates_remain: [omitted, omitted_count, omission_reason, retrieval]
+        semantics: >-
+          Omission reports only candidates beyond the selected row window.
+          Optional detail degradation is separate and names every omitted field.
+          A response never silently slices rows or truncates scalar values.
+      output_bounds:
+        maximum_limit: 100
+        max_serialized_utf8_bytes: 32768
+        scalar_truncation: forbidden
+        row_omission_under_byte_pressure: forbidden
+        optional_detail: degrade_before_minimum_row_rejection
+      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 canonical grammar
+          not_found: a valid exact identity has no matching record
+          ambiguous: duplicate identity or compatibility state 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 request state
+          cursor_snapshot_unavailable: exact cursor snapshot cannot be resumed
+          unsupported_state: authority cannot return a safe bounded envelope
+        exit_codes: { usage: 2, state_or_compatibility_failure: 1 }
+      archive_policy:
+        plan:
+          owner: canonical_plan_entities_and_immutable_plan_archive_entities
+          diagnostics: selected_candidate_only_blocks_exact_get
+          unselected_diagnostics: degrade_catalog_without_blocking_other_exact_gets
+        experiments:
+          owner: experiment_archival
+          storage_scope: objective_directory
+          publication_order: archive_before_projection
+          projection_policy: uniform_10_40_50
+          missing_detail: never_reconstructed
+  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
+        filesystem_contract:
+          primitives: [node_fs_linkSync, node_fs_renameSync]
+          replacement_visibility: complete_old_or_new_bytes_per_file
+          journal_visibility: pending_journal_blocks_reads
+          global_snapshot: not_promised
+          late_racer: outside_contract_after_final_successful_validation
+          unsupported_result: structured_unsupported_target_before_target_effects
+        pathname_race_contract: >-
+          Entity publication uses project-relative standard Node paths. The root,
+          exact valid marker, target, recovery directories, and attempt-owned
+          roles are revalidated at declared boundaries before publication or
+          recovery effects. Immutable creation linearizes through link and
+          replacement linearizes through complete-file rename. A detected
+          boundary change preserves the competitor and returns a structured
+          conflict. The journal is a read barrier and recovery authority, not a
+          global multi-file snapshot; a non-cooperating writer that races after
+          the final successful validation is outside this contract.
+        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'
+        publication_order:
+          field: publication_order
+          type: positive_safe_integer
+          presence: optional_for_legacy_required_for_new_publications
+          visibility: public_record_metadata
+          ownership: progress_writer_only
+          assignment: max_valid_existing_progress_publication_order_plus_one
+          synchronization: .agentera/.writer.lock
+          dry_run: omitted_without_consuming_or_mutating_order
+          caller_input: forbidden
+          malformed_or_spoofed_input: reject_before_mutation_with_bounded_diagnostics
+          durability: persisted_in_each_new_progress_cycle_entity
+          privacy: bounded_ordinal_without_time_identity_or_content
+      retrieval:
+        exact: agentera state progress get --id ID --format json
+        list: agentera state progress list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        ordering: timestamp_desc_then_publication_order_desc_then_id_asc
+        semantic_recency: >-
+          The first full progress cycle is latest. Timestamp remains the public
+          minute-compatible primary key. Within one timestamp, a valid writer-owned
+          publication_order sorts descending; a marked publication sorts after all
+          unmarked legacy records observed by that publication and therefore before
+          them in newest-first retrieval. Missing markers are legacy unordered ties.
+          Equal valid markers can result from independently published histories and
+          do not establish relative publication order. Missing or equal markers use
+          opaque ID ascending only as a deterministic final fallback and never claim
+          reconstructed publication chronology.
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor_v2
+        cursor_compatibility: >-
+          Version 2 continuation keys include timestamp, publication_order presence
+          and value, and opaque ID. Version 1 progress cursors are rejected with
+          recovery to omit --cursor and establish a new snapshot; authority changes
+          also invalidate prior cursor signatures by design.
+        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] [--ids-only | --fields FIELDS] --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, provenance, base_sha256, changes]
+        legacy_optional_fields: [date]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, satisfaction]
+      canonical_metadata:
+        migration_provenance:
+          applicability: inherited_unsupported_revision_confidence_only
+          required_fields: [kind, source, source_path, source_identity, source_fingerprint, source_record_sha256, confidence]
+          additional_fields: forbidden
+          kind: inherited_decision_revision_confidence
+          sources: [revision_document]
+          semantics: >-
+            Cutover persists this envelope-level metadata only when a legacy
+            aggregate revision carries high, medium, or low confidence and the
+            composed decision is otherwise valid. source_identity selects the
+            exact ordered row in .agentera/revisions/decisions.yaml,
+            source_fingerprint binds the deterministic canonical decision ID, and
+            source_record_sha256 binds that complete row. Ordinary decision
+            amendments accept only the current confidence vocabulary.
+    - 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] [--ids-only | --fields FIELDS] --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]
+        identity: >-
+          The canonical plan identity is the bare ten-letter entity envelope id.
+          A composite header.id belongs only to legacy migration source and is
+          never a public selector.
+        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] [--ids-only | --fields FIELDS] --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]
+        identity: >-
+          The canonical task identity is the bare ten-letter entity envelope id;
+          dependencies and replacements are bare IDs resolved within the same plan.
+    - 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] [--ids-only | --fields FIELDS] --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] [--ids-only | --fields FIELDS] --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: reconcile_markdown_under_recoverable_journal
+      record:
+        required_fields: [severity, status]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, path, public_order]
+      ownership:
+        fields: [kind, target_version, title, requirements, acceptance, release_blocker, severity, status, readiness, lifecycle, reconciliation]
+        cardinality: TODO.md owns public fields; Agentera owns operational fields
+        identity: managed row and canonical entity share one visible ten-letter id
+        markdown_public_fields: [description, severity, status, order]
+        agentera_operational_fields: [readiness, dependencies, blocked, gate, evidence, lifecycle]
+      reconciliation:
+        baseline: record.reconciliation
+        schema_version: agentera.todoReconciliation.v1
+        public_fields: [description, severity, status, order]
+        transaction_journal: .agentera/.todo-reconciliation/<content-digest>.json
+        create_recovery_receipt:
+          applicability: create_transactions_only
+          created_id: original_writer_assigned_ten_letter_id
+          request_sha256: sha256_of_domain_separated_canonical_normalized_create_record
+          transaction_identity: canonical_create_receipt_and_targets
+          retry: >-
+            Before applying a pending create journal, require the retry's normalized
+            request digest to match. Exact retry recovers and returns the original ID
+            as an idempotent replay without allocation; a different request rejects
+            before target effects and leaves the journal intact.
+        activation:
+          path: .agentera/todo-reconciliation-activation.json
+          schema_version: agentera.todoReconciliationActivation.v1
+          cardinality: zero_before_activation_then_exactly_one
+          initial_match: exact_unique_public_fields_only
+          retained_legacy_rows: bounded_section_and_exact_line_sha256_identities
+          rule: >-
+            The first reconciliation may assign a canonical ID only when one
+            ID-less pre-activation row exactly matches one otherwise-unclaimed
+            entity public record. It records unmatched pre-existing rows by
+            section-and-line digest as retained unmanaged legacy bytes. The
+            activation record, all entity baselines, and the public document
+            publish in the same journal. After activation, every new checkbox
+            row under a managed severity or resolved heading requires a
+            canonical ten-letter ID; each retained legacy exemption admits at
+            most one exact row occurrence per reconciliation and cannot
+            authorize a changed or duplicate row.
+        managed_row_identity: every_activated_managed_checkbox_row_has_one_ten_letter_id
+        unmanaged_regions: checkbox_rows_outside_managed_headings_remain_ordinary_markdown
+        public_path_binding: exact_docs_mapped_relative_path_plus_docs_yaml_snapshot_sha256
+        pending_visibility: agentera_todo_get_list_startup_and_dry_run_fail_closed_without_recovery_effects
+        hard_crash_recovery: consume_exact_original_previous_replacement_tmp_and_replacement_metadata_before_target_replay
+        startup_selection:
+          ordering_authority: skills/agentera/schemas/artifacts/todo.yaml#READINESS.ordering.modes.projected_startup
+          projected_entity_bound: 256
+        public_replacement: >-
+          Stage and fsync complete replacement bytes plus exact prior bytes on the
+          target filesystem, then replace each regular file with standard Node
+          filesystem operations. Each replacement linearizes as one complete-file
+          rename, so readers observe complete old or new bytes. The journal is a
+          read barrier and recovery authority, not a global multi-file atomic
+          snapshot. Publication validates the target and project context at
+          declared boundaries and preserves a change detected at a validation
+          boundary. A non-cooperating writer that races after the final successful
+          validation is outside this contract. Cross-filesystem or operational
+          filesystem rejection rolls back every attempted target before returning
+          one bounded correction. Recovery consumes exact private roles;
+          concurrent bytes remain canonical or retained and produce one structured
+          correction.
+        semantics: >-
+          TODO reads project Markdown-owned public fields and order with
+          Agentera-owned operational fields, report bounded field-level drift,
+          and have no reconciliation effects. Startup builds one complete
+          bounded projection through that same read authority; readiness,
+          dependency state, selection, and counts all consume its projected
+          status, severity, and order while retaining operational readiness and
+          gates. Eligibility and severity grouping apply before managed Markdown
+          order. An entity intentionally absent from managed Markdown sorts after
+          managed rows of the same severity by queue rank and then ID.
+          Every TODO mutation compares
+          TODO.md and the entity against the last public baseline, merges
+          one-sided or independent field edits, rejects different edits to the
+          same public field, applies the requested mutation, and publishes all
+          changed targets under one recoverable journal. Interrupted create retry
+          is bound to its canonical normalized request and original created ID;
+          exact retry returns that ID without allocating another entity, while a
+          different request rejects before recovery effects. Missing post-activation
+          baselines, divergent edits, duplicate or orphaned IDs, and removal of an
+          unchecked row reject before effects. One bounded activation
+          transaction admits exact legacy state
+          without treating retained unmatched rows as managed. The durable
+          journal is the Agentera-visible commit barrier:
+          while it exists, TODO reads and startup reject rather than expose mixed
+          targets, and dry-run inspects it without recovery effects. Each ordinary
+          file replacement remains whole-file atomic. A non-dry retry repairs a
+          target interrupted before or after replacement from exact retained role
+          files, and recovers the public document from the same portable
+          complete-file roles, then completes the prepared journal before
+          replaying the request. Invalid journals and stale or retained-role
+          conflicts preserve all target and recovery bytes and return one
+          bounded structured correction. Recovery is bound to the exact
+          docs-mapped public path and mapping snapshot; unrelated branch,
+          competitor, or mapping changes are never overwritten.
+          Rollback attempts every applied target even when one target reports a
+          boundary conflict; it retains the pending journal and bounded per-target role
+          evidence for only the targets that could not be restored.
+        bounds:
+          managed_items: 256
+          startup_projected_entities: 256
+          retained_pre_activation_legacy_rows: 256
+          transaction_targets: 258
+          activation_utf8_bytes: 32768
+          journal_utf8_bytes: 4194304
+          todo_markdown_utf8_bytes: 1048576
+      retrieval:
+        exact: agentera state todo get --id ID --format json
+        list: agentera state todo list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        ordering: severity_then_status_then_markdown_order_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] [--ids-only | --fields FIELDS] --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] [--ids-only | --fields FIELDS] --format json
+          detail_availability: summary
+          compatibility: degraded
+          caveats: required
+          ordering: full_timestamp_desc_then_publication_order_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] [--ids-only | --fields FIELDS] --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] [--ids-only | --fields FIELDS] --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 the normalized heapUsed baseline before fixture discovery
+      heap_baseline:
+        boundary: after CLI import reaches the fixture boundary and before the measured operation
+        normalization: await successful Node inspector HeapProfiler.collectGarbage, then read Runtime.getHeapUsage
+        measured_operation_collection: forbidden
+      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
+      source_fingerprint: lowercase_sha256_of_bound_migration_inputs
+      preview_digest: lowercase_sha256_of_bound_migration_preview
+    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
+
+historical_retrieval_evidence:
+  schema_version: agentera.stateRetrievalHistory.v1
+  status: retired_historical_evidence
+  runtime_consumption: forbidden
+  implementation:
+    plan_tasks: implemented
+    plans: implemented
+    experiments: implemented
+    progress: implemented
+    decisions: implemented
+    health: implemented
+  authority_boundary: >-
+    This inert group records pre-entity retrieval closure evidence only. It does
+    not own runtime grammar or policy; entity_target.public_retrieval is the sole
+    active public retrieval model.
+  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]
+    bounded_summary_projection:
+      cardinality_owner: summary_rows_after_filters_and_cursor
+      limit_semantics: >-
+        Return exactly min(requested limit, candidates remaining in the bound
+        snapshot) summary rows. Serialized-byte pressure may remove optional
+        full detail from those rows but never removes a summary row.
+      summary_required_fields: [id, artifact, retrieval.get]
+      todo_summary_additional_fields: [queue_rank]
+      queue_rank: >-
+        One-based position in the complete canonically ordered TODO candidate
+        queue before request filters. It is computed from the read snapshot and
+        does not persist, reorder, or add a public field to TODO.md.
+      optional_detail_degradation:
+        status: degraded
+        reason: optional_detail_byte_budget
+        row_omission: forbidden
+        scalar_truncation: forbidden
+        recovery: exact_get_pointer_per_summary_row
+      selectors:
+        ids_only:
+          flag: --ids-only
+          fields: [id, artifact, retrieval.get]
+          todo_additional_fields: [queue_rank]
+        fields:
+          flag: --fields COMMA_SEPARATED_RECORD_PATHS
+          validation: >-
+            Each lowercase dot path must exist in at least one record in the
+            filtered cursor snapshot. Duplicate or malformed paths and paths
+            absent from that snapshot are invalid_request. Paths are sorted
+            before projection and cursor binding; missing values in individual
+            rows remain absent.
+          identity_and_recovery_fields_always_present: true
+          scalar_truncation: forbidden
+        mutual_exclusion: ids_only_and_fields
+      byte_pressure:
+        ids_only_or_selected_fields: reject_without_partial_rows_or_fields
+        summary_rows: reject_without_partial_rows
+      metadata:
+        counts: [candidate, returned, omitted, continuation]
+        continuation: binds_collection_selectors_filters_order_and_snapshot
+        continuation_command: >-
+          Preserve every active family identifier, filter, selector, limit, and
+          cursor in deterministic grammar order. Quote every non-literal string
+          argument with the shared POSIX-shell argument primitive; generated
+          commands must be safe to paste and must not permit expansion or
+          injection through spaces, quotes, dollar signs, semicolons, or other
+          shell metacharacters.
+        exact_get: one_concrete_command_per_returned_row
+  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: candidates_beyond_the_summary_row_window
+    optional_detail: degrade_before_any_summary_row_omission
+  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: bare_ten_letter_entity_id
+      storage_ownership: canonical_progress_entities
+      ordering: timestamp_desc_then_publication_order_desc_then_id_asc
+      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 --id ID --format json
+    - collection_id: decisions.records
+      artifact_id: decisions
+      growth: immutable_base_and_revision_entities_with_replaceable_satisfaction_entity
+      identity: bare_ten_letter_entity_id
+      storage_ownership: canonical_decision_entities
+      ordering: date_desc_then_id_asc
+      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 --id ID --format json
+    - collection_id: health.records
+      artifact_id: health
+      growth: append_only_unbounded
+      identity: bare_ten_letter_entity_id
+      storage_ownership: canonical_health_entities
+      ordering: appended_at_desc_then_id_asc_then_legacy_date_desc_then_id_asc
+      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 --id ID --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: 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.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:
+  legacy_source_state: migration_input_only
+  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
+  legacy_source_state: migration_input_only
+  current_entity_boundary: decision_satisfaction
+  project_root_fixed: true
+  docs_yaml_override: forbidden
+  schema_version: agentera.decisionOverlay.v1
+  supported_artifact: decisions
+  identity_key: decisions:<decision-number>
+  storage_shape: >-
+    The legacy migration source is a mapping keyed by numbered decision ID.
+    Entity migration converts each value into one decision_satisfaction entity
+    related to the canonical decision ID. Current reads and writes use that
+    entity and never read or publish the aggregate overlay document.
+  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
+  legacy_source_state: migration_input_only
+  project_root_fixed: true
+  docs_yaml_override: forbidden
+  schema_version: agentera.decisionRevision.v1
+  supported_artifact: decisions
+  identity_key: decisions:<decision-number>
+  storage_shape: >-
+    The legacy migration source is a mapping keyed by numbered decision ID.
+    Entity migration converts each ordered row into one decision_revision
+    entity related to the canonical decision ID. Current reads and writes use
+    those entities and never read or publish the aggregate revision document.
+  amendable_paths:
+    - question
+    - context
+    - alternatives.chosen
+    - alternatives.rejected
+    - choice
+    - reasoning
+    - confidence
+    - feeds_into
+  migration_amendable_paths:
+    - alternatives
+  legacy_amendable_paths:
+    - question
+    - context
+    - alternatives
+    - choice
+    - reasoning
+    - confidence
+    - feeds_into
+  identity_paths:
+    - number
+  temporal_paths:
+    - date
+  separation_from_overlay: >-
+    Legacy content amendments never touch legacy aggregate satisfaction paths;
+    migration converts both sources independently. Current satisfaction and
+    content mutations publish decision_satisfaction and decision_revision
+    entities, and neither entity boundary rewrites the other.
+  immutability: >-
+    Imported numbered archive records remain immutable historical evidence.
+    Current decision_revision entities are additional immutable evidence;
+    no revision overwrites, reorders, or deletes a prior revision. An entity
+    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_entity_target_identity
+    - validate_amendment_vocabulary
+    - validate_base_sha256
+    - publish_decision_revision_entity
+    - compose_effective_entity_read
+  apply_state: entity_implemented_legacy_source_retired
+  apply_state_note: >-
+    The entity amend command publishes one immutable decision_revision entity
+    related to the selected bare decision ID. A valid dry-run reports the
+    candidate without writing; retries converge through canonical entity
+    replay. Effective entity reads compose base, ordered revision entities, and
+    satisfaction entities. The aggregate revision document is read only by
+    migration preview and cutover and is never a current publication target.
+    Amend execution refuses before side effects for an unsafe target, duplicate
+    same-base claim, or stale base hash. Discover the current contract with
+    `agentera state decisions explain --verb amend --format json`.
+
+projections:
+  archive:
+    source_state: migration_input_only
+    role: complete immutable historical migration detail
+    source_of_truth_for: historical_record_fields
+    omission: never omit fields from an archive record
+  current:
+    source_state: migration_input_only
+    role: bounded aggregate migration projection
+    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: legacy_migration_and_compatibility_state_only
+    archive_relationship: >-
+      A legacy aggregate entry may be full, summary-only, or absent from the projection;
+      archive presence and hash verification determine whether full detail is
+      available during migration. Legacy decision overlay values are converted
+      independently and do not rewrite archive bytes.
+  summary:
+    source_state: migration_input_only
+    role: bounded aggregate migration 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:
+    source_state: canonical_entity_authority
+    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 --id ID --format json
+    examples:
+      progress: agentera state progress get --id qjtrmnpvka --format json
+      decisions: agentera state decisions get --id imumkmffwh --format json
+      health: agentera state health get --id abcdefghij --format json
+    required_selector: --id ID
+    result: >-
+      One complete canonical entity record with id, artifact, detail availability,
+      compatibility, effective content, and provenance metadata. Decision reads
+      compose immutable base, ordered revisions, and current satisfaction entities.
+    exact_only: direct retrieval resolves one canonical entity ID without scanning unrelated records
+  list:
+    command: agentera state <artifact-id> list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --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:
+      progress: timestamp_desc_then_publication_order_desc_then_id_asc
+      decisions: date_desc_then_id_asc
+      health: appended_at_desc_then_id_asc_then_legacy_date_desc_then_id_asc
+    response_fields:
+      required: [command, status, entries, counts, source, filters, snapshot, source_contract]
+      entry: [id, artifact, detail_availability, compatibility, record, provenance, retrieval]
+      optional_entry: [summary, caveats]
+    empty_result: status=ok with entries=[] and counts.total=0; absence is not an error
+  durability:
+    command: agentera check durability [--project PATH] [--artifact ARTIFACT] [--id ID] [--limit N] --format json
+    formats: [text, json, yaml]
+    selectors:
+      artifact: optional supported entity artifact ID
+      id: optional bare entity ID; requires artifact
+      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: [id, artifact, 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 canonical entity IDs, projected record
+      hashes, and filters.
+    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 entity ordering key. 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, 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:
+      measurement_contract: entity_target.measurement_contract.sampling
+      fixture: numbered progress archive entries measured through one cold source process per scale
+      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
+
+# The mutation grammar is the only declarative inventory of public state writes.
+# Runtime code owns execution; this section owns the vocabulary, shape, bounds,
+# recovery, and projections exposed by discovery.
+mutation_grammar:
+  schema_version: agentera.stateMutationGrammar.v1
+  status: active
+  authority: references/artifacts/state-storage-authority.yaml
+  operation_classes: [record_payload, simple_transition, batch_transaction]
+  contract_scope: public_state_writer_verbs
+  structured_input:
+    parser: yaml_or_json_mapping
+    sources: [file, stdin]
+    flag: --input
+    stdin_value: '-'
+  operations:
+    - artifact: progress
+      verb: append
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid]
+      owned_fields: [id, artifact, publication_order]
+      input:
+        mode: structured
+        root: one progress cycle record
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, publication_order]
+      recovery: Run agentera state progress explain --verb append --format json and correct the rejected field; no state was changed.
+      examples: ['agentera state progress append --input progress.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      compacts: true
+      fields: []
+
+    - artifact: decisions
+      verb: append
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, exactly_one_chosen_alternative]
+      owned_fields: [id, artifact]
+      input:
+        mode: structured
+        root: one decision record
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact]
+      recovery: Run agentera state decisions explain --verb append --format json and supply every required field; no state was changed.
+      examples: ['agentera state decisions append --input decision.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      compacts: true
+      fields: []
+
+    - artifact: decisions
+      verb: update
+      class: simple_transition
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, satisfaction_state_is_valid]
+      owned_fields: [id, artifact, satisfaction]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Run agentera state decisions explain --verb update --format json, use the returned bare decision ID, and provide a valid satisfaction transition.
+      examples: ['agentera state decisions update --id qjtrmnpvka --satisfaction-state provisionally_satisfied --satisfaction-evidence "..." --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --satisfaction-state, field: satisfaction.state, kind: string, required: true, valid_values: [open, provisionally_satisfied, user_confirmed_satisfied] }
+        - { flag: --satisfaction-evidence, field: satisfaction.evidence, kind: string }
+        - { flag: --confirmed-by, field: satisfaction.user_confirmation.confirmed_by, kind: string }
+        - { flag: --confirmed-at, field: satisfaction.user_confirmation.confirmed_at, kind: string }
+
+    - artifact: decisions
+      verb: amend
+      class: record_payload
+      selectors: [--id, --base-sha256]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, base_sha256_matches_current_effective_record]
+      owned_fields: [id, artifact, base_sha256]
+      input:
+        mode: structured
+        root: amendable decision content
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, base_sha256]
+      recovery: Reread the exact decision, copy its current effective SHA-256, and retry with at least one amendable field; no state was changed.
+      examples: ['agentera state decisions amend --id qjtrmnpvka --base-sha256 HASH --input amendment.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --base-sha256, field: base_sha256, kind: string, required: true }
+
+    - artifact: plan
+      verb: append
+      class: record_payload
+      selectors: [--plan]
+      preconditions: [entity_mode_marker_is_valid, selected_plan_is_open, input_is_one_complete_plan_task_record, task_dependencies_are_bare_ids_in_same_plan]
+      owned_fields: [id, artifact, plan, status, superseded_by, superseded_reason, evaluation, header.status, header.id, previous_plan_archived, task_ids]
+      input:
+        mode: structured
+        root: one plan task record
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, plan, status, superseded_by, superseded_reason, evaluation, header.status, header.id, previous_plan_archived, task_ids]
+      recovery: Use agentera state plan explain --verb append --format json, select an open plan, and supply one complete task record with bare same-plan dependencies.
+      examples: ['agentera state plan append --plan qjtrmnpvka --input task.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields:
+         - { flag: --plan, field: plan, kind: string }
+
+    - artifact: plan
+      verb: update
+      class: record_payload
+      selectors: [--id, --plan]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, selected_plan_is_open, input_is_plan_task_patch, task_dependencies_are_bare_ids_in_same_plan]
+      owned_fields: [id, artifact, plan, status, superseded_by, superseded_reason, evaluation, header.status, header.id, previous_plan_archived, task_ids]
+      input:
+        mode: structured
+        root: plan task patch
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, plan, status, superseded_by, superseded_reason, evaluation, header.status, header.id, previous_plan_archived, task_ids]
+      recovery: Reread the plan task by its bare ID, supply an omission-preserving patch through --input, and retry; no state was changed.
+      examples: ['agentera state plan update --id qjtrmnpvka --plan abcdefghij --input task-patch.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields:
+         - { flag: --id, field: id, kind: string, required: true }
+         - { flag: --plan, field: plan, kind: string }
+
+    - artifact: plan
+      verb: set-status
+      class: simple_transition
+      selectors: [--id, --plan]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, task_exists_in_selected_plan]
+      owned_fields: [id, artifact, plan, status]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Reread the task list, copy its bare task ID, and use one of complete, in_progress, pending, or blocked.
+      examples: ['agentera state plan set-status --id qjtrmnpvka --status complete --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --plan, field: plan, kind: string }
+        - { flag: --status, field: status, kind: string, required: true, valid_values: [complete, in_progress, pending, blocked] }
+
+    - artifact: plan
+      verb: supersede
+      class: simple_transition
+      selectors: [--id, --plan]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, replacements_are_distinct_same_plan_complete_latest_pass]
+      owned_fields: [id, artifact, plan, superseded_by, superseded_reason]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Complete and evaluate each replacement task with latest PASS evidence, then retry with the returned bare IDs.
+      examples: ['agentera state plan supersede --id qjtrmnpvka --by zqtrmnpvka --reason "Replacement task" --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 100, max_reason_code_points: 500 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --plan, field: plan, kind: string }
+        - { flag: --by, field: superseded_by, kind: string_list, required: true, repeatable: true }
+        - { flag: --reason, field: superseded_reason, kind: string, required: true }
+
+    - artifact: plan
+      verb: set-plan-status
+      class: simple_transition
+      selectors: [--plan]
+      preconditions: [entity_mode_marker_is_valid, selected_plan_is_open_or_complete, completion_requires_complete_tasks_and_latest_pass_replacements]
+      owned_fields: [id, artifact, plan, header.status]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Keep the plan open or resolve every incomplete task and replacement evaluation before retrying completion.
+      examples: ['agentera state plan set-plan-status --status complete --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 100 }
+      fields:
+        - { flag: --plan, field: plan, kind: string }
+        - { flag: --status, field: status, kind: string, required: true, valid_values: [open, complete] }
+
+    - artifact: plan
+      verb: record-evaluation
+      class: simple_transition
+      selectors: [--id, --plan]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, attempt_id_is_idempotent, verdict_is_pass_or_fail]
+      owned_fields: [id, artifact, plan, evaluation]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Use the task's bare ID, a stable attempt ID, and evaluator provenance, then retry without changing published evidence.
+      examples: ['agentera state plan record-evaluation --id qjtrmnpvka --attempt-id audit-1 --verdict pass --provenance "audit report" --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --plan, field: plan, kind: string }
+        - { flag: --attempt-id, field: evaluation.attempt_id, kind: string, required: true }
+        - { flag: --verdict, field: evaluation.verdict, kind: string, required: true, valid_values: [pass, fail] }
+        - { flag: --failure-evidence, field: evaluation.failure_evidence, kind: string }
+        - { flag: --provenance, field: evaluation.provenance, kind: string, required: true }
+
+    - artifact: plan
+      verb: archive
+      class: simple_transition
+      selectors: [--plan]
+      preconditions: [entity_mode_marker_is_valid, selected_plan_is_not_open]
+      owned_fields: [id, artifact, plan, header.status]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Complete or preserve the selected plan, then retry archive with no content flags; no state was changed.
+      examples: ['agentera state plan archive --dry-run --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 100 }
+      allow_force: true
+      fields: [{ flag: --plan, field: plan, kind: string }]
+
+    - artifact: plan
+      verb: create
+      class: batch_transaction
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, input_is_one_complete_plan_document, create_local_task_ordinals_are_sequential, dependency_graph_is_valid]
+      owned_fields: [id, artifact, header.id, previous_plan_archived, task_ids]
+      input:
+        mode: structured
+        root: complete plan document
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact, header.id, previous_plan_archived, task_ids]
+      recovery: Run agentera state plan explain --verb create --format json, keep task ordinals and dependencies local to this atomic input, remove CLI-owned fields, and correct the first schema or dependency violation.
+      examples: ['agentera state plan create --input plan.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      allow_force: true
+      fields: []
+
+    - artifact: health
+      verb: append
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, input_is_one_audit_entry_not_a_whole_artifact]
+      owned_fields: [id, artifact, appended_at]
+      input:
+        mode: structured
+        root: one audit entry
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact, appended_at]
+      recovery: Run agentera check validate state --format json, preserve audit evidence, and retry with one schema-valid audit entry.
+      examples: ['agentera state health append --input audit.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      compacts: true
+      fields: []
+
+    - artifact: objective
+      verb: create
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, input_is_one_objective_document]
+      owned_fields: [id, artifact, header.id]
+      input:
+        mode: structured
+        root: one objective document
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact, header.id]
+      recovery: Remove identity fields assigned by the CLI and retry with one schema-valid objective document.
+      examples: ['agentera state objective create --input objective.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields: []
+
+    - artifact: objective
+      verb: update
+      class: record_payload
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, input_is_one_objective_document]
+      owned_fields: [id, artifact, header.id]
+      input:
+        mode: structured
+        root: one objective document
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact, header.id]
+      recovery: Reread the objective, copy its bare ID to --id, remove CLI-owned fields, and retry.
+      examples: ['agentera state objective update --id qjtrmnpvka --input objective.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields: [{ flag: --id, field: id, kind: string, required: true }]
+
+    - artifact: experiments
+      verb: publish
+      class: batch_transaction
+      selectors: [--objective, --id]
+      preconditions: [entity_mode_marker_is_valid, owner_is_bare_ten_letters, input_is_one_experiment_entry, archive_and_projection_publication_is_atomic]
+      owned_fields: [id, artifact, objective, archive_identity]
+      input:
+        mode: structured
+        root: one experiment entry
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact, objective]
+      recovery: Use a bare objective ID, omit numeric legacy selectors, and retry the exact input; divergent immutable identities remain untouched.
+      examples: ['agentera state experiments publish --objective qjtrmnpvka --input experiment.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      compacts: true
+      fields:
+        - { flag: --objective, field: objective, kind: string, required: true }
+        - { flag: --id, field: id, kind: string }
+
+    - artifact: todo
+      verb: create
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, full_typed_record_is_valid, readiness_is_complete_or_needs_triage, dependency_graph_is_valid]
+      owned_fields: [id, artifact, status, public_order, lifecycle]
+      input:
+        mode: structured
+        root: full typed TODO record
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, status, public_order, lifecycle]
+      recovery: Run agentera state todo explain --verb create --format json, remove CLI-owned fields, provide the full typed TODO record, and retry.
+      examples: ['agentera state todo create --input todo.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      fields: []
+
+    - artifact: todo
+      verb: update
+      class: record_payload
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, target_id_is_bare_ten_letters, typed_patch_is_valid, dependency_graph_is_valid]
+      owned_fields: [id, artifact, status, public_order, lifecycle]
+      input:
+        mode: structured
+        root: TODO record patch
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, status, public_order, lifecycle]
+      recovery: Reread the TODO item, use its bare ID, supply only typed patch fields, and use null or an empty list only for declared clearable fields.
+      examples: ['agentera state todo update --id qjtrmnpvka --input todo-patch.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields: [{ flag: --id, field: id, kind: string, required: true }]
+
+    - artifact: todo
+      verb: set-severity
+      class: simple_transition
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, target_id_is_bare_ten_letters, severity_is_valid, reason_and_date_are_present]
+      owned_fields: [id, artifact, severity, lifecycle]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Use the bare TODO ID, one immediate-impact severity, a reason, and a YYYY-MM-DD date; no record input is accepted.
+      examples: ['agentera state todo set-severity --id qjtrmnpvka --severity degraded --reason "Impact changed" --date 2026-07-31 --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1, max_reason_code_points: 500 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --severity, field: severity, kind: string, required: true, valid_values: [critical, degraded, normal, annoying] }
+        - { flag: --reason, field: lifecycle.reason, kind: string, required: true }
+        - { flag: --date, field: lifecycle.date, kind: date, required: true }
+
+    - artifact: todo
+      verb: supersede
+      class: simple_transition
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, target_id_is_bare_ten_letters, replacement_is_distinct_existing_todo, reason_and_date_are_present]
+      owned_fields: [id, artifact, status, lifecycle]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Use the selected bare TODO ID, an existing distinct replacement ID, a reason, and a YYYY-MM-DD date; no record input is accepted.
+      examples: ['agentera state todo supersede --id qjtrmnpvka --replacement zqtrmnpvka --reason "Replaced by narrower work" --date 2026-07-31 --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1, max_reason_code_points: 500 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --replacement, field: lifecycle.replacement, kind: string, required: true }
+        - { flag: --reason, field: lifecycle.reason, kind: string, required: true }
+        - { flag: --date, field: lifecycle.date, kind: date, required: true }
+
+    - artifact: todo
+      verb: resolve
+      class: simple_transition
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, target_id_is_bare_ten_letters, item_is_open, reason_and_date_are_present]
+      owned_fields: [id, artifact, status, lifecycle]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Use the bare TODO ID, a reason, and a YYYY-MM-DD date; no record input is accepted.
+      examples: ['agentera state todo resolve --id qjtrmnpvka --reason "Shipped" --date 2026-07-31 --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1, max_reason_code_points: 500 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --reason, field: lifecycle.reason, kind: string, required: true }
+        - { flag: --date, field: lifecycle.date, kind: date, required: true }
+
+    - artifact: todo
+      verb: reopen
+      class: simple_transition
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, target_id_is_bare_ten_letters, item_is_resolved, reason_and_date_are_present]
+      owned_fields: [id, artifact, status, lifecycle]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Use the bare resolved TODO ID, a reason, and a YYYY-MM-DD date; no record input is accepted.
+      examples: ['agentera state todo reopen --id qjtrmnpvka --reason "Scope returned" --date 2026-07-31 --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1, max_reason_code_points: 500 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --reason, field: lifecycle.reason, kind: string, required: true }
+        - { flag: --date, field: lifecycle.date, kind: date, required: true }
+
+    - artifact: docs
+      verb: create
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, input_is_one_documentation_inventory_entry]
+      owned_fields: [id, artifact]
+      input:
+        mode: structured
+        root: one documentation inventory entry
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact]
+      recovery: Remove id and artifact from the input and retry with one schema-valid documentation inventory entry.
+      examples: ['agentera state docs create --input documentation.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      fields: []
+
+    - artifact: docs
+      verb: update
+      class: record_payload
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, input_is_one_documentation_inventory_entry]
+      owned_fields: [id, artifact]
+      input:
+        mode: structured
+        root: one documentation inventory entry
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact]
+      recovery: Reread the documentation entry, copy its bare ID to --id, remove CLI-owned fields, and retry.
+      examples: ['agentera state docs update --id qjtrmnpvka --input documentation.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields: [{ flag: --id, field: id, kind: string, required: true }]
+
+    - artifact: glossary
+      verb: publish
+      class: batch_transaction
+      selectors: []
+      preconditions: [input_is_one_glossary_publication_request, cited_source_lines_are_current, confirmation_matches_proposal]
+      owned_fields: [approval_id, glossary_entry_id]
+      input:
+        mode: structured
+        root: one glossary publication request
+        sources: [file, stdin]
+        cli_owned_fields: []
+      recovery: Run agentera state glossary explain --verb publish --format json and correct the bounded request or confirmation.
+      examples: ['agentera state glossary publish --input glossary-publication.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields: []