agentera 3.0.0-dev.8 → 3.0.0-dev.81

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

@@ -0,0 +1,3075 @@
+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. A marker-absent Git root with no .agentera
+    residue is fresh_uninitialized and may publish that marker only with its first
+    complete Plan create. 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, and every other marker-absent residue fails
+    closed without publication.
+
+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. The sole marker-absent exception is fresh Plan
+      create at a proven fresh_uninitialized Git root; it publishes one complete
+      plan graph and marker or rolls back. Other marker-absent consumers fail
+      closed; 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: npx -y agentera@next state progress list [--topic TEXT] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state progress get --id ID --format json
+      decisions:
+        list: npx -y agentera@next state decisions list [--topic TEXT] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state decisions get --id ID --format json
+      health:
+        list: npx -y agentera@next state health list [--dimension DIMENSION] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state health get --id ID --format json
+      plans:
+        list: npx -y agentera@next state plan list [--status open|complete|archived] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state plan get --id ID --format json
+      plan_tasks:
+        list: npx -y agentera@next state plan tasks list [PLAN_ID] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state plan tasks get --id ID --format json
+      objective:
+        list: npx -y agentera@next state objective list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state objective get --id ID --format json
+      experiments:
+        list: npx -y agentera@next state experiments list --objective ID [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state experiments get --id ID --format json
+      todo:
+        list: npx -y agentera@next state todo list [--severity SEVERITY] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next state todo get --id ID --format json
+      docs:
+        list: npx -y agentera@next state docs list [--topic TEXT] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        get: npx -y agentera@next 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: npx -y agentera@next state progress list --limit 20 --format json
+        decisions:
+          command_tokens: [decisions]
+          bare_read: alias
+          filters:
+            - { flag: --topic TEXT, name: topic, values: free_text }
+          example: npx -y agentera@next state decisions list --limit 20 --format json
+        health:
+          command_tokens: [health]
+          bare_read: correction
+          bare_recovery: npx -y agentera@next state health list --limit 20 --format json
+          filters:
+            - { flag: --dimension DIMENSION, name: dimension, values: free_text }
+          example: npx -y agentera@next state health list --limit 20 --format json
+        plans:
+          command_tokens: [plan]
+          bare_read: correction
+          bare_recovery: npx -y agentera@next state plan list --status open --limit 20 --format json
+          filters:
+            - { flag: '--status open|complete|archived', name: status, values: [open, complete, archived] }
+          example: npx -y agentera@next state plan list --status open --limit 20 --format json
+        plan_tasks:
+          command_tokens: [plan, tasks]
+          bare_read: correction
+          bare_recovery: npx -y agentera@next 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: npx -y agentera@next state plan tasks list --limit 20 --format json
+        objective:
+          command_tokens: [objective]
+          bare_read: correction
+          bare_recovery: npx -y agentera@next state objective list --limit 20 --format json
+          filters: []
+          example: npx -y agentera@next state objective list --limit 20 --format json
+        experiments:
+          command_tokens: [experiments]
+          bare_read: correction
+          bare_recovery: npx -y agentera@next state objective list --limit 20 --format json
+          family_identifier:
+            syntax: --objective ID
+            required: true
+            description: Required bare objective entity ID.
+          filters: []
+          example: npx -y agentera@next 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: npx -y agentera@next state todo list --severity critical --ids-only --limit 20 --format json
+        docs:
+          command_tokens: [docs]
+          bare_read: correction
+          bare_recovery: npx -y agentera@next 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: npx -y agentera@next 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: npx -y agentera@next 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: npx -y agentera@next state progress get --id ID --format json
+        list: npx -y agentera@next 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: npx -y agentera@next state decisions get --id ID --format json
+        list: npx -y agentera@next 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: npx -y agentera@next state health get --id ID --format json
+        list: npx -y agentera@next 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 `npx -y agentera@next 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: [previous_plan_archived]
+      implementation: implemented
+      publication: replace_owned_entity_with_targeted_replacement_journal
+      targeted_replacement_journal:
+        path: .agentera/.entity-recovery/plan-replacement/<content-digest>.json
+        identity: canonical_operation_identity_and_complete_target_before_after_bytes
+        visibility: pending_journal_blocks_plan_reads_until_exact_retry_recovers_or_finishes
+        replay: exact_existing_roles_or_create_input_sha256_only
+      record:
+        required_fields: [header, what, why, scope]
+        required_paths: [header.title, header.created, header.status]
+        forbidden_fields: [id, artifact, stable_id, plan_id, tasks]
+        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: npx -y agentera@next state plan get --id ID --format json
+        list: npx -y agentera@next 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: npx -y agentera@next state objective get --id ID --format json
+        list: npx -y agentera@next 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: npx -y agentera@next state experiments get --id ID --format json
+        list: npx -y agentera@next 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
+          effect_sha256: optional_for_legacy_cutover_required_for_explicit_activation
+          journal_authorization: >-
+            Explicit activation journals bind the preview effect SHA-256 into
+            transaction identity. Recovery validates that digest before target
+            effects. A completed explicit activation retains the same digest in
+            activation metadata so exact apply replay converges and unrelated
+            digests reject without effects; legacy activation accepts only its
+            current no-op preview digest.
+          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.
+          unsafe_inactive: >-
+            One read-only pre-publication decision gates both activation preview
+            and confirmed apply. Every canonical entity must have one exact
+            public projection. Unmatched projections, duplicate public work,
+            stale entity public fields, or a prospective resurrection reject
+            before effects with bounded, content-private risk. Unsafe inactive
+            state emits neither an effect digest nor an apply command. Repair
+            requires an activation marker and is not pre-activation recovery;
+            owners must correct their source data, and any required mutation
+            must be replanned.
+        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: npx -y agentera@next state todo get --id ID --format json
+        list: npx -y agentera@next 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: npx -y agentera@next state docs get --id ID --format json
+        list: npx -y agentera@next 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
+    plan_lineage: An optional plan.previous_plan_archived points to one distinct archived predecessor, and that predecessor has at most one successor; reverse lineage is derived from the canonical source record rather than stored in a second mutable field.
+    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
+        field: previous_plan_archived
+        target: plan
+        cardinality: zero_or_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: npx -y agentera@next state progress get --id ID --format json
+          list: npx -y agentera@next 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: npx -y agentera@next state decisions get --id ID --format json
+          list: npx -y agentera@next 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: npx -y agentera@next state health get --id ID --format json
+          list: npx -y agentera@next 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
+      archive_small: 100 valid numbered progress archive entries
+      archive_large: 1000 valid numbered progress archive entries
+      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
+      archive_list_small:
+        max_latency_ms: 5000
+        max_heap_delta_bytes: 67108864
+        max_utf8_bytes: 32768
+      archive_list_large:
+        max_latency_ms: 15000
+        max_heap_delta_bytes: 268435456
+        max_utf8_bytes: 32768
+      startup_small:
+        max_latency_ms: 5000
+        # Retain margin for supported Node 22 peak-GC variance while keeping
+        # the small-startup ceiling at half the large-startup limit.
+        max_heap_delta_bytes: 134217728
+        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: classified
+    invalid_behavior: fail_without_fallback
+    detection: read_only
+    publication_owner: recognized_legacy_development_upgrade_or_fresh_plan_create
+    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. A Git-root project with no .agentera path is fresh_uninitialized:
+      Plan startup remains read-only and its first Plan create is the sole
+      initializer. Pending v1 Markdown, partial, corrupt, and unknown
+      marker-absent state are rejected with their read-only recovery instructions.
+  fresh_initialization:
+    classification: >-
+      fresh_uninitialized requires an exact Git root, absent .agentera state
+      root, no entity records, no recognized aggregate migration input, and no
+      unknown Agentera-owned residue. Ordinary root documents, table-based TODO
+      files, and report directories are user-owned and do not participate.
+    startup: plan_context_is_read_only_and_operable_without_upgrade_apply
+    writer: state_plan_create_only
+    dry_run: previews_marker_plan_and_tasks_without_filesystem_effects
+    apply: publishes_plan_and_tasks_then_marker_with_ordinary_rollback_on_failure
+    other_writers: reject_without_initialization_route
+    global_runtime_resources: not_read_or_changed
+  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.
+      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: fresh_plan_create_only_other_marker_absent_state_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: npx -y agentera@next 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: npx -y agentera@next 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: npx -y agentera@next 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: npx -y agentera@next prime --context <capability> --format json
+    list: npx -y agentera@next state <artifact-id> list --limit 20 --format json
+    get: npx -y agentera@next 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
+    `npx -y agentera@next 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: npx -y agentera@next state <artifact-id> get --id ID --format json
+    examples:
+      progress: npx -y agentera@next state progress get --id qjtrmnpvka --format json
+      decisions: npx -y agentera@next state decisions get --id imumkmffwh --format json
+      health: npx -y agentera@next 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: npx -y agentera@next state <artifact-id> list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+    examples:
+      progress: npx -y agentera@next state progress list --limit 20 --format json
+      decisions_next_page: npx -y agentera@next 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: npx -y agentera@next 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_upgrade:
+    command: npx -y agentera@next upgrade --channel development --project PATH --dry-run
+    implementation: upgrade_only
+    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 the one bounded aggregation surface.
+        prime_capability_context_max_utf8_bytes: 55000
+        prime_status_context_max_utf8_bytes: 22500
+      aggregation:
+        schema_version: agentera.primeStartup.v1
+        outcome_values: [ok, degraded, blocked]
+        availability_row_fields: [family, availability, detail_command]
+        availability_values: [included, deferred]
+        detail_discovery: npx -y agentera@next schema --format json
+        single_projection_rule: >-
+          Prime emits one per-family availability projection at startup. Status
+          renders the same aggregate outcome without copying that projection.
+          A deferred row names its exact read command; it is not a second-call
+          requirement for an ok status startup.
+        writer_payloads: forbidden
+    surfaces:
+      prime_briefing:
+        manifest_id: prime-briefing
+        # Bounded default decision brief (Plan Task 3): the bare default
+        # `npx -y agentera@next 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. The
+        # deprecated prime_dashboard alias emits the same status capsule.
+        max_utf8_bytes: 12000
+      prime_dashboard:
+        manifest_id: prime-dashboard
+        max_utf8_bytes: 22500
+      prime_status_context:
+        manifest_id: prime-status-context
+        # Status startup includes its instructions and one bounded availability
+        # aggregation. Diagnostics remain on stderr.
+        max_utf8_bytes: 22500
+      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 `npx -y agentera@next state progress explain --verb append --format json` and correct the rejected field; no state was changed.
+      examples: ['npx -y agentera@next 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 `npx -y agentera@next state decisions explain --verb append --format json` and supply every required field; no state was changed.
+      examples: ['npx -y agentera@next 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 npx -y agentera@next state decisions explain --verb update --format json, use the returned bare decision ID, and provide a valid satisfaction transition.
+      examples: ['npx -y agentera@next 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: ['npx -y agentera@next 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 npx -y agentera@next state plan explain --verb append --format json, select an open plan, and supply one complete task record with bare same-plan dependencies.
+      examples: ['npx -y agentera@next 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: ['npx -y agentera@next 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: ['npx -y agentera@next 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: ['npx -y agentera@next 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: ['npx -y agentera@next 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: ['npx -y agentera@next 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, lifecycle_effects_are_derived_from_locked_canonical_entities, selected_plan_is_complete_or_archived_or_force_archivable]
+      owned_fields: [id, artifact, plan, header.status]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Archive a complete plan normally. With --force, archive the selected open plan unchanged only after the locked canonical snapshot identifies it; multiple implicit open-plan candidates are rejected without effects.
+      examples: ['npx -y agentera@next state plan archive --dry-run --format json', 'npx -y agentera@next state plan archive --force --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, lifecycle_effects_are_derived_from_locked_canonical_entities, 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 npx -y agentera@next state plan explain --verb create --format json, keep task ordinals and dependencies local to this atomic input, remove CLI-owned fields, and use --force only when the locked canonical snapshot has exactly one open predecessor to archive unchanged.
+      examples: ['npx -y agentera@next state plan create --input plan.yaml --format json', 'npx -y agentera@next state plan create --force --input plan.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      allow_force: true
+      fields: []
+
+    - artifact: plan
+      verb: replace
+      class: batch_transaction
+      selectors: [--predecessor, --successor]
+      preconditions: [entity_mode_marker_is_valid, lifecycle_effects_are_derived_from_locked_canonical_entities, predecessor_and_existing_successor_are_explicit_or_one_complete_successor_input_is_supplied, named_roles_are_distinct_bare_plan_ids, replacement_leaves_no_unnamed_open_plan, exact_lineage_or_logical_create_input_replay_matches]
+      owned_fields: [id, artifact, header.status, header.id, previous_plan_archived, replacement_input_sha256, task_ids]
+      input:
+        mode: structured
+        root: complete plan document when creating a successor
+        optional: true
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, header.id, previous_plan_archived, replacement_input_sha256, task_ids]
+      recovery: Name one bare predecessor and either one existing bare successor or one complete successor plan input. The operation archives only the named predecessor, derives reverse lineage from the successor, and rejects divergent retries before effects. Competing-open diagnostics retain bounded bare IDs without assigning roles and recover through npx -y agentera@next state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json.
+      examples: ['npx -y agentera@next state plan replace --predecessor abcdefghij --successor klmnopqrst --format json', 'npx -y agentera@next state plan replace --predecessor abcdefghij --input plan.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      fields:
+        - { flag: --predecessor, field: predecessor, kind: string, required: true, description: Bare plan ID to archive as the explicit predecessor. }
+        - { flag: --successor, field: successor, kind: string, description: Existing bare open plan ID to retain as the explicit successor. }
+
+    - 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 npx -y agentera@next check validate state --format json, preserve audit evidence, and retry with one schema-valid audit entry.
+      examples: ['npx -y agentera@next 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: ['npx -y agentera@next 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: ['npx -y agentera@next 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: ['npx -y agentera@next 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: activate
+      class: batch_transaction
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, activation_is_absent_or_replay, todo_reconciliation_is_valid, inactive_projection_is_complete_one_to_one_and_safe, confirmed_effect_sha256_is_authorized_for_preview_or_replay]
+      owned_fields: [reconciliation, public_document, activation]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Preview and review every reported safe activation effect before explicit confirmed apply; unsafe inactive evidence requires the separate effect-bound owner-correction operation.
+      examples: ['npx -y agentera@next state todo activate --dry-run --format json', 'npx -y agentera@next state todo activate --effect-sha256 EFFECT_SHA256 --yes --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 256 }
+      compacts: true
+      fields:
+        - { flag: --effect-sha256, field: effect_sha256, kind: string }
+        - { flag: --yes, field: confirmed, kind: boolean }
+
+    - artifact: todo
+      verb: repair
+      class: batch_transaction
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, activation_is_present, complete_one_to_one_repair_evidence_is_valid, confirmed_effect_sha256_is_authorized_for_preview_or_replay]
+      owned_fields: [reconciliation, public_document, activation]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Preview and review every diagnosed repair decision before explicit confirmed apply; ambiguous evidence is rejected without effects.
+      examples: ['npx -y agentera@next state todo repair --dry-run --format json', 'npx -y agentera@next state todo repair --effect-sha256 EFFECT_SHA256 --yes --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 256 }
+      compacts: true
+      fields:
+        - { flag: --effect-sha256, field: effect_sha256, kind: string }
+        - { flag: --yes, field: confirmed, kind: boolean }
+
+    - artifact: todo
+      verb: correct-owners
+      class: batch_transaction
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, reconciliation_marker_is_absent_and_unsafe_inactive_or_exact_effect_replay, input_is_complete_one_to_one_owner_mapping, completed_markdown_work_is_not_reopened, confirmed_effect_sha256_and_owner_mapping_are_authorized_for_preview_or_replay]
+      owned_fields: [reconciliation, public_document, activation]
+      input:
+        mode: structured
+        root: one unsafe TODO owner mapping
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: []
+      recovery: Supply one complete id/source_line owner mapping, preview its bounded effect, then apply only the exact returned effect; malformed, ambiguous, unmatched, or stale evidence is rejected without effects.
+      examples: ['npx -y agentera@next state todo correct-owners --input owner-mapping.yaml --dry-run --format json', 'npx -y agentera@next state todo correct-owners --input owner-mapping.yaml --effect-sha256 EFFECT_SHA256 --yes --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 256 }
+      compacts: true
+      fields:
+        - { flag: --effect-sha256, field: effect_sha256, kind: string }
+        - { flag: --yes, field: confirmed, kind: boolean }
+
+    - artifact: todo
+      verb: create
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, singleton_or_versioned_batch_shape_is_valid, full_typed_records_are_valid, duplicate_local_references_are_absent, all_ids_are_allocated_before_local_reference_resolution, dependency_graph_is_valid, batch_effect_is_previewed_and_confirmed]
+      owned_fields: [id, artifact, status, public_order, lifecycle]
+      input:
+        mode: structured
+        root: full typed TODO record or agentera.todoCreateBatch.v1 envelope
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, status, public_order, lifecycle]
+      recovery: For one item, preserve the existing full-record form. For a batch, supply agentera.todoCreateBatch.v1, preview with --dry-run, then repeat the same input with its effect SHA-256 and --yes.
+      examples: ['npx -y agentera@next state todo create --input todo.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 256 }
+      fields:
+        - { flag: --effect-sha256, field: effect_sha256, kind: string }
+        - { flag: --yes, field: confirmed, kind: boolean }
+
+    - artifact: todo
+      verb: update
+      class: record_payload
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, singleton_or_versioned_batch_shape_is_valid, target_ids_are_bare_ten_letters, duplicate_targets_are_absent, typed_patches_are_valid, dependency_graph_is_valid, batch_effect_is_previewed_and_confirmed]
+      owned_fields: [id, artifact, status, public_order, lifecycle]
+      input:
+        mode: structured
+        root: TODO record patch or agentera.todoUpdateBatch.v1 envelope
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, status, public_order, lifecycle]
+      recovery: For one item, preserve the existing --id and patch form. For a batch, supply agentera.todoUpdateBatch.v1, preview with --dry-run, then repeat the same input with its effect SHA-256 and --yes.
+      examples: ['npx -y agentera@next state todo update --id qjtrmnpvka --input todo-patch.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 256 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --effect-sha256, field: effect_sha256, kind: string }
+        - { flag: --yes, field: confirmed, kind: boolean }
+
+    - artifact: todo
+      verb: set-severity
+      class: simple_transition
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, singleton_or_agentera_todoSetSeverityBatch_v1_shape_is_valid, target_ids_are_bare_ten_letters, duplicate_targets_are_absent, severity_is_valid, reason_and_date_are_present, batch_effect_is_previewed_and_confirmed]
+      owned_fields: [id, artifact, severity, lifecycle]
+      input: { mode: structured, root: agentera.todoSetSeverityBatch.v1 envelope, optional: true, sources: [file, stdin], structured_sources: [file, stdin], cli_owned_fields: [] }
+      recovery: Use singleton flags unchanged, or supply agentera.todoSetSeverityBatch.v1 through --input, preview it, then exact-apply it with the effect SHA-256 and --yes.
+      examples: ['npx -y agentera@next state todo set-severity --id qjtrmnpvka --severity degraded --reason "Impact changed" --date 2026-07-31 --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 256, 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 }
+        - { flag: --effect-sha256, field: effect_sha256, kind: string }
+        - { flag: --yes, field: confirmed, kind: boolean }
+
+    - 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: ['npx -y agentera@next 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, singleton_or_agentera_todoResolveBatch_v1_shape_is_valid, target_ids_are_bare_ten_letters, duplicate_targets_are_absent, every_item_is_open, reason_and_date_are_present, batch_effect_is_previewed_and_confirmed]
+      owned_fields: [id, artifact, status, lifecycle]
+      input: { mode: structured, root: agentera.todoResolveBatch.v1 envelope, optional: true, sources: [file, stdin], structured_sources: [file, stdin], cli_owned_fields: [] }
+      recovery: Use singleton flags unchanged, or supply agentera.todoResolveBatch.v1 through --input, preview it, then exact-apply it with the effect SHA-256 and --yes.
+      examples: ['npx -y agentera@next state todo resolve --id qjtrmnpvka --reason "Shipped" --date 2026-07-31 --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 256, 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 }
+        - { flag: --effect-sha256, field: effect_sha256, kind: string }
+        - { flag: --yes, field: confirmed, kind: boolean }
+
+    - 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: ['npx -y agentera@next 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: ['npx -y agentera@next 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: ['npx -y agentera@next 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 npx -y agentera@next state glossary explain --verb publish --format json and correct the bounded request or confirmation.
+      examples: ['npx -y agentera@next state glossary publish --input glossary-publication.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields: []