agentera 3.0.0-dev.39 → 3.0.0-dev.41

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

@@ -73,32 +73,142 @@ entity_target:
     status: final
     commands:
       progress:
-        list: agentera state progress list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state progress list [--topic TEXT] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         get: agentera state progress get --id ID --format json
       decisions:
-        list: agentera state decisions list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state decisions list [--topic TEXT] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         get: agentera state decisions get --id ID --format json
       health:
-        list: agentera state health list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state health list [--dimension DIMENSION] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         get: agentera state health get --id ID --format json
       plans:
-        list: agentera state plan list [--status open|complete|archived] [--limit N] [--cursor TOKEN] --format json
+        list: agentera state plan list [--status open|complete|archived] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         get: agentera state plan get --id ID --format json
       plan_tasks:
-        list: agentera state plan tasks list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state plan tasks list [PLAN_ID] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         get: agentera state plan tasks get --id ID --format json
       objective:
-        list: agentera state objective list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state objective list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         get: agentera state objective get --id ID --format json
       experiments:
-        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] --format json
+        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         get: agentera state experiments get --id ID --format json
       todo:
-        list: agentera state todo list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state todo list [--severity SEVERITY] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         get: agentera state todo get --id ID --format json
       docs:
-        list: agentera state docs list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state docs list [--topic TEXT] [--status STATUS] [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         get: agentera state docs get --id ID --format json
+    list_help:
+      schema_version: agentera.entityListHelp.v1
+      defaults:
+        summary_fields: [id, artifact, retrieval.get]
+        selectors:
+          ids_only:
+            flag: --ids-only
+            description: Return only canonical minimum identity, exact-get recovery, and required family minimum fields such as TODO queue_rank.
+          fields:
+            flag: --fields FIELDS
+            description: Select comma-separated lowercase record paths present in the filtered snapshot; identity and exact-get recovery remain present.
+          mutual_exclusion: true
+        bounds: { minimum: 1, default: 20, maximum: 100, max_utf8_bytes: 32768 }
+        formats: [text, json, yaml]
+      families:
+        progress:
+          command_tokens: [progress]
+          bare_read: alias
+          filters:
+            - { flag: --topic TEXT, name: topic, values: free_text }
+            - { flag: --status STATUS, name: status, values: free_text }
+          example: agentera state progress list --limit 20 --format json
+        decisions:
+          command_tokens: [decisions]
+          bare_read: alias
+          filters:
+            - { flag: --topic TEXT, name: topic, values: free_text }
+          example: agentera state decisions list --limit 20 --format json
+        health:
+          command_tokens: [health]
+          bare_read: correction
+          bare_recovery: agentera state health list --limit 20 --format json
+          filters:
+            - { flag: --dimension DIMENSION, name: dimension, values: free_text }
+          example: agentera state health list --limit 20 --format json
+        plans:
+          command_tokens: [plan]
+          bare_read: correction
+          bare_recovery: agentera state plan list --status open --limit 20 --format json
+          filters:
+            - { flag: '--status open|complete|archived', name: status, values: [open, complete, archived] }
+          example: agentera state plan list --status open --limit 20 --format json
+        plan_tasks:
+          command_tokens: [plan, tasks]
+          bare_read: correction
+          bare_recovery: agentera state plan tasks list --limit 20 --format json
+          family_identifier:
+            syntax: PLAN_ID
+            required: false
+            description: Optional bare plan ID; omit it to list tasks from the active plan.
+          filters: []
+          example: agentera state plan tasks list --limit 20 --format json
+        objective:
+          command_tokens: [objective]
+          bare_read: correction
+          bare_recovery: agentera state objective list --limit 20 --format json
+          filters: []
+          example: agentera state objective list --limit 20 --format json
+        experiments:
+          command_tokens: [experiments]
+          bare_read: correction
+          bare_recovery: agentera state objective list --limit 20 --format json
+          family_identifier:
+            syntax: --objective ID
+            required: true
+            description: Required bare objective entity ID.
+          filters: []
+          example: agentera state experiments list --objective qjtrmnpvka --limit 20 --format json
+        todo:
+          command_tokens: [todo]
+          bare_read: alias
+          filters:
+            - { flag: --severity SEVERITY, name: severity, values: free_text }
+            - { flag: --status STATUS, name: status, values: free_text }
+          summary_fields: [id, artifact, public_order, readiness, actionability, queue_rank, reconciliation, retrieval.get]
+          summary_field_notes:
+            public_order:
+              description: Markdown-owned one-based order within the item's public section, or null before reconciliation activation.
+              ownership: markdown_read_projection
+              persisted: false
+              filter: false
+            readiness:
+              description: Public lifecycle state plus whether Agentera readiness declares an explicit blocker.
+              ownership: agentera_operational_projection
+              persisted: false
+              filter: false
+            actionability:
+              description: Read-only TODO readiness outcome and eligibility computed across the complete TODO snapshot.
+              ownership: computed_read_snapshot
+              persisted: false
+              filter: false
+            queue_rank:
+              description: Computed one-based position in the complete ordered TODO snapshot before filters.
+              ownership: computed_read_snapshot
+              persisted: false
+              filter: false
+            reconciliation:
+              description: Global reconciliation status and item-specific drift state for this read snapshot.
+              ownership: computed_read_snapshot
+              persisted: false
+              filter: false
+          example: agentera state todo list --severity critical --ids-only --limit 20 --format json
+        docs:
+          command_tokens: [docs]
+          bare_read: correction
+          bare_recovery: agentera state docs list --limit 20 --format json
+          filters:
+            - { flag: --topic TEXT, name: topic, values: free_text }
+            - { flag: --status STATUS, name: status, values: free_text }
+          example: agentera state docs list --limit 20 --format json
     collections:
       - { artifact: progress, identity: id, classification: artifact }
       - { artifact: decisions, identity: id, classification: artifact }
@@ -109,6 +219,116 @@ entity_target:
       - { 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
@@ -135,14 +355,23 @@ entity_target:
         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 is rooted through held directory descriptors. The
-          root and exact valid marker identity and bytes are revalidated before
-          each directory, stage, and immutable-link boundary and after durable
-          publication before success. Because Node cannot make pathname
-          validation and mutation one kernel operation, a detected substitution
-          rolls back only attempt-owned links, stages, and empty directories by
-          pinned identity; final failure retains no attempt-owned entity state.
+          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
@@ -192,7 +421,7 @@ entity_target:
           privacy: bounded_ordinal_without_time_identity_or_content
       retrieval:
         exact: agentera state progress get --id ID --format json
-        list: agentera state progress list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state progress list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: timestamp_desc_then_publication_order_desc_then_id_asc
         semantic_recency: >-
           The first full progress cycle is latest. Timestamp remains the public
@@ -263,7 +492,7 @@ entity_target:
             Current confidence values and ordinary decision writes omit this metadata.
       retrieval:
         exact: agentera state decisions get --id ID --format json
-        list: agentera state decisions list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state decisions list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: date_desc_then_id_asc
         default_limit: 20
         maximum_limit: 100
@@ -354,7 +583,7 @@ entity_target:
               reconstructed chronology.
       retrieval:
         exact: agentera state health get --id ID --format json
-        list: agentera state health list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state health list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: appended_at_desc_then_id_asc_then_legacy_date_desc_then_id_asc
         default_limit: 20
         maximum_limit: 100
@@ -398,6 +627,10 @@ entity_target:
         required_fields: [header, what, why, scope]
         required_paths: [header.title, header.created, header.status]
         forbidden_fields: [id, artifact, stable_id, plan_id, tasks, previous_plan_archived]
+        identity: >-
+          The canonical plan identity is the bare ten-letter entity envelope id.
+          A composite header.id belongs only to legacy migration source and is
+          never a public selector.
         field_shapes:
           scope:
             type: mapping
@@ -418,7 +651,7 @@ entity_target:
               under this source-form rule; no semantic intent is inferred.
       retrieval:
         exact: agentera state plan get --id ID --format json
-        list: agentera state plan list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state plan list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: created_desc_then_id_asc
         default_limit: 20
         maximum_limit: 100
@@ -437,6 +670,9 @@ entity_target:
         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
@@ -449,7 +685,7 @@ entity_target:
         forbidden_fields: [id, artifact, stable_id, objective_id]
       retrieval:
         exact: agentera state objective get --id ID --format json
-        list: agentera state objective list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state objective list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: created_desc_then_id_asc
         default_limit: 20
         maximum_limit: 100
@@ -474,7 +710,7 @@ entity_target:
         forbidden_fields: [id, artifact, number, experiment_number, stable_id, objective_id]
       retrieval:
         exact: agentera state experiments get --id ID --format json
-        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] --format json
+        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: date_desc_then_id_asc
         default_limit: 20
         maximum_limit: 100
@@ -488,15 +724,120 @@ entity_target:
       independently_mutable: true
       relationships: []
       implementation: implemented
-      publication: replace_owned_entity
+      publication: reconcile_markdown_under_recoverable_journal
       record:
-        required_fields: [severity, status, description]
+        required_fields: [severity, status]
         required_paths: []
-        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, path]
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, path, public_order]
+      ownership:
+        fields: [kind, target_version, title, requirements, acceptance, release_blocker, severity, status, readiness, lifecycle, reconciliation]
+        cardinality: TODO.md owns public fields; Agentera owns operational fields
+        identity: managed row and canonical entity share one visible ten-letter id
+        markdown_public_fields: [description, severity, status, order]
+        agentera_operational_fields: [readiness, dependencies, blocked, gate, evidence, lifecycle]
+      reconciliation:
+        baseline: record.reconciliation
+        schema_version: agentera.todoReconciliation.v1
+        public_fields: [description, severity, status, order]
+        transaction_journal: .agentera/.todo-reconciliation/<content-digest>.json
+        create_recovery_receipt:
+          applicability: create_transactions_only
+          created_id: original_writer_assigned_ten_letter_id
+          request_sha256: sha256_of_domain_separated_canonical_normalized_create_record
+          transaction_identity: canonical_create_receipt_and_targets
+          retry: >-
+            Before applying a pending create journal, require the retry's normalized
+            request digest to match. Exact retry recovers and returns the original ID
+            as an idempotent replay without allocation; a different request rejects
+            before target effects and leaves the journal intact.
+        activation:
+          path: .agentera/todo-reconciliation-activation.json
+          schema_version: agentera.todoReconciliationActivation.v1
+          cardinality: zero_before_activation_then_exactly_one
+          initial_match: exact_unique_public_fields_only
+          retained_legacy_rows: bounded_section_and_exact_line_sha256_identities
+          rule: >-
+            The first reconciliation may assign a canonical ID only when one
+            ID-less pre-activation row exactly matches one otherwise-unclaimed
+            entity public record. It records unmatched pre-existing rows by
+            section-and-line digest as retained unmanaged legacy bytes. The
+            activation record, all entity baselines, and the public document
+            publish in the same journal. After activation, every new checkbox
+            row under a managed severity or resolved heading requires a
+            canonical ten-letter ID; each retained legacy exemption admits at
+            most one exact row occurrence per reconciliation and cannot
+            authorize a changed or duplicate row.
+        managed_row_identity: every_activated_managed_checkbox_row_has_one_ten_letter_id
+        unmanaged_regions: checkbox_rows_outside_managed_headings_remain_ordinary_markdown
+        public_path_binding: exact_docs_mapped_relative_path_plus_docs_yaml_snapshot_sha256
+        pending_visibility: agentera_todo_get_list_startup_and_dry_run_fail_closed_without_recovery_effects
+        hard_crash_recovery: consume_exact_original_previous_replacement_tmp_and_replacement_metadata_before_target_replay
+        startup_selection:
+          ordering_authority: skills/agentera/schemas/artifacts/todo.yaml#READINESS.ordering.modes.projected_startup
+          projected_entity_bound: 256
+        public_replacement: >-
+          Stage and fsync complete replacement bytes plus exact prior bytes on the
+          target filesystem, then replace each regular file with standard Node
+          filesystem operations. Each replacement linearizes as one complete-file
+          rename, so readers observe complete old or new bytes. The journal is a
+          read barrier and recovery authority, not a global multi-file atomic
+          snapshot. Publication validates the target and project context at
+          declared boundaries and preserves a change detected at a validation
+          boundary. A non-cooperating writer that races after the final successful
+          validation is outside this contract. Cross-filesystem or operational
+          filesystem rejection rolls back every attempted target before returning
+          one bounded correction. Recovery consumes exact private roles;
+          concurrent bytes remain canonical or retained and produce one structured
+          correction.
+        semantics: >-
+          TODO reads project Markdown-owned public fields and order with
+          Agentera-owned operational fields, report bounded field-level drift,
+          and have no reconciliation effects. Startup builds one complete
+          bounded projection through that same read authority; readiness,
+          dependency state, selection, and counts all consume its projected
+          status, severity, and order while retaining operational readiness and
+          gates. Eligibility and severity grouping apply before managed Markdown
+          order. An entity intentionally absent from managed Markdown sorts after
+          managed rows of the same severity by queue rank and then ID.
+          Every TODO mutation compares
+          TODO.md and the entity against the last public baseline, merges
+          one-sided or independent field edits, rejects different edits to the
+          same public field, applies the requested mutation, and publishes all
+          changed targets under one recoverable journal. Interrupted create retry
+          is bound to its canonical normalized request and original created ID;
+          exact retry returns that ID without allocating another entity, while a
+          different request rejects before recovery effects. Missing post-activation
+          baselines, divergent edits, duplicate or orphaned IDs, and removal of an
+          unchecked row reject before effects. One bounded activation
+          transaction admits exact legacy state
+          without treating retained unmatched rows as managed. The durable
+          journal is the Agentera-visible commit barrier:
+          while it exists, TODO reads and startup reject rather than expose mixed
+          targets, and dry-run inspects it without recovery effects. Each ordinary
+          file replacement remains whole-file atomic. A non-dry retry repairs a
+          target interrupted before or after replacement from exact retained role
+          files, and recovers the public document from the same portable
+          complete-file roles, then completes the prepared journal before
+          replaying the request. Invalid journals and stale or retained-role
+          conflicts preserve all target and recovery bytes and return one
+          bounded structured correction. Recovery is bound to the exact
+          docs-mapped public path and mapping snapshot; unrelated branch,
+          competitor, or mapping changes are never overwritten.
+          Rollback attempts every applied target even when one target reports a
+          boundary conflict; it retains the pending journal and bounded per-target role
+          evidence for only the targets that could not be restored.
+        bounds:
+          managed_items: 256
+          startup_projected_entities: 256
+          retained_pre_activation_legacy_rows: 256
+          transaction_targets: 258
+          activation_utf8_bytes: 32768
+          journal_utf8_bytes: 4194304
+          todo_markdown_utf8_bytes: 1048576
       retrieval:
         exact: agentera state todo get --id ID --format json
-        list: agentera state todo list [--limit N] [--cursor TOKEN] --format json
-        ordering: severity_then_status_then_id
+        list: agentera state todo list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
+        ordering: severity_then_status_then_markdown_order_then_id
         default_limit: 20
         maximum_limit: 100
         max_utf8_bytes: 32768
@@ -516,7 +857,7 @@ entity_target:
         forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
       retrieval:
         exact: agentera state docs get --id ID --format json
-        list: agentera state docs list [--limit N] [--cursor TOKEN] --format json
+        list: agentera state docs list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
         ordering: path_then_id
         default_limit: 20
         maximum_limit: 100
@@ -688,7 +1029,7 @@ entity_target:
             source_row_provenance: entity_target.declared_compacted_summary_contract.source_row_provenance
         retrieval:
           exact: agentera state progress get --id ID --format json
-          list: agentera state progress list [--limit N] [--cursor TOKEN] --format json
+          list: agentera state progress list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
           detail_availability: summary
           compatibility: degraded
           caveats: required
@@ -726,7 +1067,7 @@ entity_target:
             source_row_provenance: entity_target.declared_compacted_summary_contract.source_row_provenance
         retrieval:
           exact: agentera state decisions get --id ID --format json
-          list: agentera state decisions list [--limit N] [--cursor TOKEN] --format json
+          list: agentera state decisions list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
           detail_availability: summary
           compatibility: degraded
           caveats: required
@@ -760,7 +1101,7 @@ entity_target:
             source_row_provenance: entity_target.declared_compacted_summary_contract.source_row_provenance
         retrieval:
           exact: agentera state health get --id ID --format json
-          list: agentera state health list [--limit N] [--cursor TOKEN] --format json
+          list: agentera state health list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
           detail_availability: summary
           compatibility: degraded
           caveats: required
@@ -1087,9 +1428,10 @@ scope:
     - objective
     - experiments
 
-retrieval:
-  schema_version: agentera.stateRetrievalAuthority.v1
-  status: plan_task_plan_and_experiment_retrieval_implemented
+historical_retrieval_evidence:
+  schema_version: agentera.stateRetrievalHistory.v1
+  status: retired_historical_evidence
+  runtime_consumption: forbidden
   implementation:
     plan_tasks: implemented
     plans: implemented
@@ -1098,10 +1440,9 @@ retrieval:
     decisions: implemented
     health: implemented
   authority_boundary: >-
-    This group owns public list/get envelopes, cursors, selectors, identities,
-    omissions, and structured retrieval failures. It does not replace storage
-    ownership: canonical entity files remain authoritative after the durable
-    cutover marker; retained v2 aggregates are immutable migration evidence only.
+    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:
@@ -1140,6 +1481,54 @@ retrieval:
         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
@@ -1171,134 +1560,8 @@ retrieval:
     maximum_limit: 100
     max_serialized_utf8_bytes: 32768
     scalar_truncation: forbidden
-    omission_unit: whole_entries
-  identity:
-    plan:
-      canonical_format: 'plan:<lowercase-rfc9562-uuid>'
-      persistence: stored in header.id when a plan is first published
-      transition: the identical ID is copied unchanged into the immutable archive file
-      legacy_format: 'legacy-plan:<sha256>'
-      legacy_derivation: >-
-        SHA-256 over RFC 8785 canonical JSON of the complete plan after the
-        existing read-compatibility normalization of legacy status and task
-        shape. The archive transition computes identity from the same normalized
-        document before publication. Derivation is read-only and never rewrites
-        active or archived bytes; a legacy identity may change while an active
-        legacy plan is edited because no persisted historical identity exists.
-      test_vectors:
-        - canonical_json: '{"header":{"created":"2026-07-14","status":"open","title":"Plan: Complete bounded retrieval"},"tasks":[]}'
-          stable_id: legacy-plan:b6f93d6fc5a0ac3ada017670ac311794ad92800fb436703f8f09e25ddce8b89a
-          mirrored_example_paths: [.agentera/archive/PLAN-copy-a.yaml, .agentera/archive/PLAN-copy-b.yaml]
-          identical_result: mirrored_provenance
-      collision: >-
-        Byte-equivalent normalized legacy plans are one logical identity with
-        every physical path retained as mirrored provenance. Different plan
-        documents carrying the same persisted ID, or a detected digest collision,
-        are unaddressable; list reports compatibility=degraded and get returns
-        ambiguous with every candidate provenance path. The CLI never chooses by
-        mtime, archive filename, or discovery order.
-    task:
-      format: '<plan-id>/task:<positive-integer>'
-      selector: --task N
-      scope: task numbers are unique only inside one plan identity
-    objective:
-      canonical_format: 'objective:<lowercase-rfc9562-uuid>'
-      persistence: stored in header.id and unchanged by title or directory rename
-      canonical_root: .agentera/optimize/<objective-slug>
-      legacy_root: .agentera/optimera/<objective-slug>
-      legacy_format: 'legacy-objective:<sha256>'
-      legacy_derivation: >-
-        SHA-256 over RFC 8785 canonical JSON of the legacy objective's description,
-        measurement, metric, baseline, gates, constraints, and scope; title,
-        status, closure fields, directory root, and directory slug are excluded.
-        This preserves identity across a title/path-only rename without rewriting
-        history. Editing identity inputs may change a legacy identity and is
-        reported as degraded compatibility.
-      test_vectors:
-        - canonical_json: '{"baseline":{"description":"100 ms"},"constraints":[],"description":"Reduce latency","gates":{},"measurement":"p95","metric":{"direction":"minimize","unit":"ms"},"scope":{"excluded":[],"included":["CLI"]}}'
-          title_variants: [CLI latency, Faster CLI]
-          root_variants: [.agentera/optimize/cli-latency, .agentera/optimera/faster-cli]
-          stable_id: legacy-objective:aa987d92dadce65b8b2d8f54c741a10f5d024d864cb0ef309b4321b4e19e4ceb
-      path_compatibility: >-
-        Read both optimize and optimera roots. Identical records carrying one
-        persisted objective ID are mirrored provenance. Different records with
-        the same persisted or derived ID, or unresolved candidates in both roots,
-        return ambiguous; canonical-root preference must not hide a collision.
-    experiment:
-      format: '<objective-id>/experiment:<non-negative-integer>'
-      scope: experiment numbers are unique only within one objective identity
-      zero: experiment 0 is valid and is normally the baseline
-      collision: duplicate numbers inside one objective are ambiguous and never resolved by array order
-      compatibility: >-
-        Legacy full-detail or 10/40/50 summary entries with a missing or
-        duplicate number remain visible in reads with addressable=false and an
-        explicit compatibility caveat. Reads do not assign a number, choose a
-        duplicate by array order, migrate a root, or rewrite retained bytes.
-      publication_validation: >-
-        Before any publication effect, require one unambiguous objective
-        identity, a non-negative integer number, and no retained full-detail or
-        summary entry with that number. Ambiguous canonical/legacy objective
-        candidates, missing objective identity, and duplicate experiment
-        identity fail validation without changing bytes.
-      publication:
-        command: agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml --format json
-        authority: typed_state_writer
-        archive_ownership: experiment_archival
-        storage_scope: objective_directory
-        publication_order: archive_before_projection
-        projection_policy: uniform_10_40_50
-        input: one schema-valid experiment entry without the CLI-owned number field
-        identity_assignment: the CLI assigns the validated --number to the published entry
-        collision_rule: >-
-          An existing matching identity and byte-equivalent experiment is an
-          idempotent replay; the same identity with different content is a
-          collision and leaves the projection unchanged.
-        transaction: >-
-          Validate objective identity, canonical/legacy ambiguity, experiment
-          identity, existing projection schema, caller input schema, and final
-          projection bytes before atomically replacing experiments.yaml.
-        failure_atomicity: >-
-          Validation, staging, and pre-publication failures preserve both active
-          and one-line archive bytes. An interruption after atomic replacement
-          may report failure after publication; retrying the same command must
-          return the already-published entry without duplication.
-        scope_boundary: >-
-          Publication preserves the existing 10/40/50 projection contract and
-          durably publishes its objective-scoped immutable archive before
-          replacing the projection, as owned by experiment_archival.
-  commands:
-    plan_tasks:
-      list: agentera state plan tasks list [--plan PLAN_ID] [--limit N] [--cursor TOKEN] --format json
-      get: agentera state plan tasks get [--plan PLAN_ID] --task N --format json
-      selectors:
-        plan:
-          list_required: false
-          list_default: active plan resolved once and returned as filters.plan
-          get_required: false
-          get_default: active plan resolved once and returned in the response source
-          pattern: '^(plan:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|legacy-plan:[0-9a-f]{64})$'
-        task:
-          get_required: true
-          pattern: '^[1-9][0-9]*$'
-    plans:
-      list: agentera state plan list [--limit N] [--cursor TOKEN] --format json
-      get: agentera state plan get --plan PLAN_ID --format json
-      selectors:
-        plan:
-          get_required: true
-          pattern: '^(plan:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|legacy-plan:[0-9a-f]{64})$'
-    experiments:
-      list: agentera state experiments list --objective OBJECTIVE_ID [--limit N] [--cursor TOKEN] --format json
-      get: agentera state experiments get --objective OBJECTIVE_ID --number N --format json
-      publish: agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml --format json
-      selectors:
-        objective:
-          list_required: true
-          get_required: true
-          pattern: '^(objective:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|legacy-objective:[0-9a-f]{64})$'
-        number:
-          get_required: true
-          pattern: '^(0|[1-9][0-9]*)$'
+    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]
@@ -1365,7 +1628,7 @@ retrieval:
       growth: mutable_while_plan_active_then_immutable_with_archived_plan
       identity: retrieval.identity.task
       storage_ownership: owning_active_plan_file
-      ordering: task_number_asc
+      ordering: id_asc
       bounds: count_1_to_100_and_serialized_utf8_budget
       cursor: opaque_snapshot_cursor
       omission: explicit_with_advancing_cursor_or_exact_get
@@ -1938,7 +2201,7 @@ api:
       compose immutable base, ordered revisions, and current satisfaction entities.
     exact_only: direct retrieval resolves one canonical entity ID without scanning unrelated records
   list:
-    command: agentera state <artifact-id> list [--limit N] [--cursor TOKEN] --format json
+    command: agentera state <artifact-id> list [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json
     examples:
       progress: agentera state progress list --limit 20 --format json
       decisions_next_page: agentera state decisions list --limit 20 --cursor TOKEN --format json
@@ -2146,6 +2409,8 @@ budgets:
   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
@@ -2231,6 +2496,435 @@ budgets:
       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
+validation:
+  authority: this file plus the referenced JSON surface manifest
+  drift_rule: tests fail if manifest IDs or byte values disagree with this contract
+
+# The mutation grammar is the only declarative inventory of public state writes.
+# Runtime code owns execution; this section owns the vocabulary, shape, bounds,
+# recovery, and projections exposed by discovery.
+mutation_grammar:
+  schema_version: agentera.stateMutationGrammar.v1
+  status: active
+  authority: references/artifacts/state-storage-authority.yaml
+  operation_classes: [record_payload, simple_transition, batch_transaction]
+  contract_scope: public_state_writer_verbs
+  structured_input:
+    parser: yaml_or_json_mapping
+    sources: [file, stdin]
+    flag: --input
+    stdin_value: '-'
+  operations:
+    - artifact: progress
+      verb: append
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid]
+      owned_fields: [id, artifact, publication_order]
+      input:
+        mode: structured
+        root: one progress cycle record
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, publication_order]
+      recovery: Run agentera state progress explain --verb append --format json and correct the rejected field; no state was changed.
+      examples: ['agentera state progress append --input progress.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      compacts: true
+      fields: []
+
+    - artifact: decisions
+      verb: append
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, exactly_one_chosen_alternative]
+      owned_fields: [id, artifact]
+      input:
+        mode: structured
+        root: one decision record
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact]
+      recovery: Run agentera state decisions explain --verb append --format json and supply every required field; no state was changed.
+      examples: ['agentera state decisions append --input decision.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      compacts: true
+      fields: []
+
+    - artifact: decisions
+      verb: update
+      class: simple_transition
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, satisfaction_state_is_valid]
+      owned_fields: [id, artifact, satisfaction]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Run agentera state decisions explain --verb update --format json, use the returned bare decision ID, and provide a valid satisfaction transition.
+      examples: ['agentera state decisions update --id qjtrmnpvka --satisfaction-state provisionally_satisfied --satisfaction-evidence "..." --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --satisfaction-state, field: satisfaction.state, kind: string, required: true, valid_values: [open, provisionally_satisfied, user_confirmed_satisfied] }
+        - { flag: --satisfaction-evidence, field: satisfaction.evidence, kind: string }
+        - { flag: --confirmed-by, field: satisfaction.user_confirmation.confirmed_by, kind: string }
+        - { flag: --confirmed-at, field: satisfaction.user_confirmation.confirmed_at, kind: string }
+
+    - artifact: decisions
+      verb: amend
+      class: record_payload
+      selectors: [--id, --base-sha256]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, base_sha256_matches_current_effective_record]
+      owned_fields: [id, artifact, base_sha256]
+      input:
+        mode: structured
+        root: amendable decision content
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, base_sha256]
+      recovery: Reread the exact decision, copy its current effective SHA-256, and retry with at least one amendable field; no state was changed.
+      examples: ['agentera state decisions amend --id qjtrmnpvka --base-sha256 HASH --input amendment.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --base-sha256, field: base_sha256, kind: string, required: true }
+
+    - artifact: plan
+      verb: append
+      class: record_payload
+      selectors: [--plan]
+      preconditions: [entity_mode_marker_is_valid, selected_plan_is_open, input_is_one_complete_plan_task_record, task_dependencies_are_bare_ids_in_same_plan]
+      owned_fields: [id, artifact, plan, status, superseded_by, superseded_reason, evaluation, header.status, header.id, previous_plan_archived, task_ids]
+      input:
+        mode: structured
+        root: one plan task record
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, plan, status, superseded_by, superseded_reason, evaluation, header.status, header.id, previous_plan_archived, task_ids]
+      recovery: Use agentera state plan explain --verb append --format json, select an open plan, and supply one complete task record with bare same-plan dependencies.
+      examples: ['agentera state plan append --plan qjtrmnpvka --input task.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields:
+         - { flag: --plan, field: plan, kind: string }
+
+    - artifact: plan
+      verb: update
+      class: record_payload
+      selectors: [--id, --plan]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, selected_plan_is_open, input_is_plan_task_patch, task_dependencies_are_bare_ids_in_same_plan]
+      owned_fields: [id, artifact, plan, status, superseded_by, superseded_reason, evaluation, header.status, header.id, previous_plan_archived, task_ids]
+      input:
+        mode: structured
+        root: plan task patch
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, plan, status, superseded_by, superseded_reason, evaluation, header.status, header.id, previous_plan_archived, task_ids]
+      recovery: Reread the plan task by its bare ID, supply an omission-preserving patch through --input, and retry; no state was changed.
+      examples: ['agentera state plan update --id qjtrmnpvka --plan abcdefghij --input task-patch.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields:
+         - { flag: --id, field: id, kind: string, required: true }
+         - { flag: --plan, field: plan, kind: string }
+
+    - artifact: plan
+      verb: set-status
+      class: simple_transition
+      selectors: [--id, --plan]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, task_exists_in_selected_plan]
+      owned_fields: [id, artifact, plan, status]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Reread the task list, copy its bare task ID, and use one of complete, in_progress, pending, or blocked.
+      examples: ['agentera state plan set-status --id qjtrmnpvka --status complete --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --plan, field: plan, kind: string }
+        - { flag: --status, field: status, kind: string, required: true, valid_values: [complete, in_progress, pending, blocked] }
+
+    - artifact: plan
+      verb: supersede
+      class: simple_transition
+      selectors: [--id, --plan]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, replacements_are_distinct_same_plan_complete_latest_pass]
+      owned_fields: [id, artifact, plan, superseded_by, superseded_reason]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Complete and evaluate each replacement task with latest PASS evidence, then retry with the returned bare IDs.
+      examples: ['agentera state plan supersede --id qjtrmnpvka --by zqtrmnpvka --reason "Replacement task" --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 100, max_reason_code_points: 500 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --plan, field: plan, kind: string }
+        - { flag: --by, field: superseded_by, kind: string_list, required: true, repeatable: true }
+        - { flag: --reason, field: superseded_reason, kind: string, required: true }
+
+    - artifact: plan
+      verb: set-plan-status
+      class: simple_transition
+      selectors: [--plan]
+      preconditions: [entity_mode_marker_is_valid, selected_plan_is_open_or_complete, completion_requires_complete_tasks_and_latest_pass_replacements]
+      owned_fields: [id, artifact, plan, header.status]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Keep the plan open or resolve every incomplete task and replacement evaluation before retrying completion.
+      examples: ['agentera state plan set-plan-status --status complete --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 100 }
+      fields:
+        - { flag: --plan, field: plan, kind: string }
+        - { flag: --status, field: status, kind: string, required: true, valid_values: [open, complete] }
+
+    - artifact: plan
+      verb: record-evaluation
+      class: simple_transition
+      selectors: [--id, --plan]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, attempt_id_is_idempotent, verdict_is_pass_or_fail]
+      owned_fields: [id, artifact, plan, evaluation]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Use the task's bare ID, a stable attempt ID, and evaluator provenance, then retry without changing published evidence.
+      examples: ['agentera state plan record-evaluation --id qjtrmnpvka --attempt-id audit-1 --verdict pass --provenance "audit report" --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --plan, field: plan, kind: string }
+        - { flag: --attempt-id, field: evaluation.attempt_id, kind: string, required: true }
+        - { flag: --verdict, field: evaluation.verdict, kind: string, required: true, valid_values: [pass, fail] }
+        - { flag: --failure-evidence, field: evaluation.failure_evidence, kind: string }
+        - { flag: --provenance, field: evaluation.provenance, kind: string, required: true }
+
+    - artifact: plan
+      verb: archive
+      class: simple_transition
+      selectors: [--plan]
+      preconditions: [entity_mode_marker_is_valid, selected_plan_is_not_open]
+      owned_fields: [id, artifact, plan, header.status]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Complete or preserve the selected plan, then retry archive with no content flags; no state was changed.
+      examples: ['agentera state plan archive --dry-run --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 100 }
+      allow_force: true
+      fields: [{ flag: --plan, field: plan, kind: string }]
+
+    - artifact: plan
+      verb: create
+      class: batch_transaction
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, input_is_one_complete_plan_document, create_local_task_ordinals_are_sequential, dependency_graph_is_valid]
+      owned_fields: [id, artifact, header.id, previous_plan_archived, task_ids]
+      input:
+        mode: structured
+        root: complete plan document
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact, header.id, previous_plan_archived, task_ids]
+      recovery: Run agentera state plan explain --verb create --format json, keep task ordinals and dependencies local to this atomic input, remove CLI-owned fields, and correct the first schema or dependency violation.
+      examples: ['agentera state plan create --input plan.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      allow_force: true
+      fields: []
+
+    - artifact: health
+      verb: append
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, input_is_one_audit_entry_not_a_whole_artifact]
+      owned_fields: [id, artifact, appended_at]
+      input:
+        mode: structured
+        root: one audit entry
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact, appended_at]
+      recovery: Run agentera check validate state --format json, preserve audit evidence, and retry with one schema-valid audit entry.
+      examples: ['agentera state health append --input audit.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      compacts: true
+      fields: []
+
+    - artifact: objective
+      verb: create
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, input_is_one_objective_document]
+      owned_fields: [id, artifact, header.id]
+      input:
+        mode: structured
+        root: one objective document
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact, header.id]
+      recovery: Remove identity fields assigned by the CLI and retry with one schema-valid objective document.
+      examples: ['agentera state objective create --input objective.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields: []
+
+    - artifact: objective
+      verb: update
+      class: record_payload
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, input_is_one_objective_document]
+      owned_fields: [id, artifact, header.id]
+      input:
+        mode: structured
+        root: one objective document
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact, header.id]
+      recovery: Reread the objective, copy its bare ID to --id, remove CLI-owned fields, and retry.
+      examples: ['agentera state objective update --id qjtrmnpvka --input objective.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields: [{ flag: --id, field: id, kind: string, required: true }]
+
+    - artifact: experiments
+      verb: publish
+      class: batch_transaction
+      selectors: [--objective, --id]
+      preconditions: [entity_mode_marker_is_valid, owner_is_bare_ten_letters, input_is_one_experiment_entry, archive_and_projection_publication_is_atomic]
+      owned_fields: [id, artifact, objective, archive_identity]
+      input:
+        mode: structured
+        root: one experiment entry
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact, objective]
+      recovery: Use a bare objective ID, omit numeric legacy selectors, and retry the exact input; divergent immutable identities remain untouched.
+      examples: ['agentera state experiments publish --objective qjtrmnpvka --input experiment.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      compacts: true
+      fields:
+        - { flag: --objective, field: objective, kind: string, required: true }
+        - { flag: --id, field: id, kind: string }
+
+    - artifact: todo
+      verb: create
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, full_typed_record_is_valid, readiness_is_complete_or_needs_triage, dependency_graph_is_valid]
+      owned_fields: [id, artifact, status, public_order, lifecycle]
+      input:
+        mode: structured
+        root: full typed TODO record
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, status, public_order, lifecycle]
+      recovery: Run agentera state todo explain --verb create --format json, remove CLI-owned fields, provide the full typed TODO record, and retry.
+      examples: ['agentera state todo create --input todo.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      fields: []
+
+    - artifact: todo
+      verb: update
+      class: record_payload
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, target_id_is_bare_ten_letters, typed_patch_is_valid, dependency_graph_is_valid]
+      owned_fields: [id, artifact, status, public_order, lifecycle]
+      input:
+        mode: structured
+        root: TODO record patch
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: [id, artifact, status, public_order, lifecycle]
+      recovery: Reread the TODO item, use its bare ID, supply only typed patch fields, and use null or an empty list only for declared clearable fields.
+      examples: ['agentera state todo update --id qjtrmnpvka --input todo-patch.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields: [{ flag: --id, field: id, kind: string, required: true }]
+
+    - artifact: todo
+      verb: set-severity
+      class: simple_transition
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, target_id_is_bare_ten_letters, severity_is_valid, reason_and_date_are_present]
+      owned_fields: [id, artifact, severity, lifecycle]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Use the bare TODO ID, one immediate-impact severity, a reason, and a YYYY-MM-DD date; no record input is accepted.
+      examples: ['agentera state todo set-severity --id qjtrmnpvka --severity degraded --reason "Impact changed" --date 2026-07-31 --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1, max_reason_code_points: 500 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --severity, field: severity, kind: string, required: true, valid_values: [critical, degraded, normal, annoying] }
+        - { flag: --reason, field: lifecycle.reason, kind: string, required: true }
+        - { flag: --date, field: lifecycle.date, kind: date, required: true }
+
+    - artifact: todo
+      verb: supersede
+      class: simple_transition
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, target_id_is_bare_ten_letters, replacement_is_distinct_existing_todo, reason_and_date_are_present]
+      owned_fields: [id, artifact, status, lifecycle]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Use the selected bare TODO ID, an existing distinct replacement ID, a reason, and a YYYY-MM-DD date; no record input is accepted.
+      examples: ['agentera state todo supersede --id qjtrmnpvka --replacement zqtrmnpvka --reason "Replaced by narrower work" --date 2026-07-31 --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1, max_reason_code_points: 500 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --replacement, field: lifecycle.replacement, kind: string, required: true }
+        - { flag: --reason, field: lifecycle.reason, kind: string, required: true }
+        - { flag: --date, field: lifecycle.date, kind: date, required: true }
+
+    - artifact: todo
+      verb: resolve
+      class: simple_transition
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, target_id_is_bare_ten_letters, item_is_open, reason_and_date_are_present]
+      owned_fields: [id, artifact, status, lifecycle]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Use the bare TODO ID, a reason, and a YYYY-MM-DD date; no record input is accepted.
+      examples: ['agentera state todo resolve --id qjtrmnpvka --reason "Shipped" --date 2026-07-31 --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1, max_reason_code_points: 500 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --reason, field: lifecycle.reason, kind: string, required: true }
+        - { flag: --date, field: lifecycle.date, kind: date, required: true }
+
+    - artifact: todo
+      verb: reopen
+      class: simple_transition
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, todo_reconciliation_is_valid, target_id_is_bare_ten_letters, item_is_resolved, reason_and_date_are_present]
+      owned_fields: [id, artifact, status, lifecycle]
+      input: { mode: none, sources: [], cli_owned_fields: [] }
+      recovery: Use the bare resolved TODO ID, a reason, and a YYYY-MM-DD date; no record input is accepted.
+      examples: ['agentera state todo reopen --id qjtrmnpvka --reason "Scope returned" --date 2026-07-31 --format json']
+      bounds: { max_input_utf8_bytes: 0, max_collection_items: 1, max_reason_code_points: 500 }
+      fields:
+        - { flag: --id, field: id, kind: string, required: true }
+        - { flag: --reason, field: lifecycle.reason, kind: string, required: true }
+        - { flag: --date, field: lifecycle.date, kind: date, required: true }
+
+    - artifact: docs
+      verb: create
+      class: record_payload
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, input_is_one_documentation_inventory_entry]
+      owned_fields: [id, artifact]
+      input:
+        mode: structured
+        root: one documentation inventory entry
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact]
+      recovery: Remove id and artifact from the input and retry with one schema-valid documentation inventory entry.
+      examples: ['agentera state docs create --input documentation.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 100 }
+      fields: []
+
+    - artifact: docs
+      verb: update
+      class: record_payload
+      selectors: [--id]
+      preconditions: [entity_mode_marker_is_valid, target_id_is_bare_ten_letters, input_is_one_documentation_inventory_entry]
+      owned_fields: [id, artifact]
+      input:
+        mode: structured
+        root: one documentation inventory entry
+        sources: [file, stdin]
+        cli_owned_fields: [id, artifact]
+      recovery: Reread the documentation entry, copy its bare ID to --id, remove CLI-owned fields, and retry.
+      examples: ['agentera state docs update --id qjtrmnpvka --input documentation.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields: [{ flag: --id, field: id, kind: string, required: true }]
+
+    - artifact: glossary
+      verb: publish
+      class: batch_transaction
+      selectors: []
+      preconditions: [input_is_one_glossary_publication_request, cited_source_lines_are_current, confirmation_matches_proposal]
+      owned_fields: [approval_id, glossary_entry_id]
+      input:
+        mode: structured
+        root: one glossary publication request
+        sources: [file, stdin]
+        cli_owned_fields: []
+      recovery: Run agentera state glossary explain --verb publish --format json and correct the bounded request or confirmation.
+      examples: ['agentera state glossary publish --input glossary-publication.yaml --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 }
+      fields: []