agentera 3.0.0-dev.2 → 3.0.0-dev.21

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

@@ -0,0 +1,1446 @@
+schema_version: agentera.stateStorageAuthority.v1
+status: active_authority
+purpose: >-
+  Define the public bounded-retrieval vocabulary for every state collection
+  while keeping each collection's storage authority explicit. It also defines
+  the lossless numbered-archive, project path, direct state API, compatibility,
+  projection, and serialized-output contracts for progress, decisions, and
+  health, plus objective-scoped immutable archival for newly published
+  experiments.
+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,
+    failure classes, or byte limits.
+  implementation_boundary: >-
+    This contract does not migrate legacy state or change existing plan and
+    vision archive behavior. The maintenance-only Git backfill surface declared
+    by api.backfill may inventory reachable local history and publish only an
+    exact immutable archive record after explicit apply intent.
+
+scope:
+  supported_artifacts:
+    - artifact_id: progress
+      current_projection_path: .agentera/progress.yaml
+      entry_collection: cycles
+      entry_number_field: number
+      entry_kind: cycle
+    - artifact_id: decisions
+      current_projection_path: .agentera/decisions.yaml
+      entry_collection: decisions
+      entry_number_field: number
+      entry_kind: decision
+    - artifact_id: health
+      current_projection_path: .agentera/health.yaml
+      entry_collection: audits
+      entry_number_field: number
+      entry_kind: audit
+  excluded_from_numbered_archive:
+    - plan
+    - vision
+    - todo
+    - changelog
+    - docs
+    - design
+    - objective
+    - experiments
+
+retrieval:
+  schema_version: agentera.stateRetrievalAuthority.v1
+  status: plan_task_plan_and_experiment_retrieval_implemented
+  implementation:
+    plan_tasks: implemented
+    plans: implemented
+    experiments: implemented
+  authority_boundary: >-
+    This group owns public list/get envelopes, cursors, selectors, identities,
+    omissions, and structured retrieval failures. It does not replace storage
+    ownership: numbered archives remain authoritative for progress, decisions,
+    and health; immutable plan files remain authoritative for plan history; and
+    objective directories remain authoritative for experiments.
+  envelope:
+    schema_version: agentera.stateRetrieval.v1
+    required_fields:
+      - schemaVersion
+      - command
+      - status
+      - entries
+      - counts
+      - order
+      - filters
+      - snapshot
+      - source
+      - source_contract
+    entry_required_fields:
+      - stable_id
+      - addressable
+      - detail_availability
+      - compatibility
+      - provenance
+      - retrieval
+    counts_required_fields: [total, returned, remaining, omitted]
+    status_values: [ok, degraded]
+  cursor:
+    vocabulary: opaque_snapshot_cursor
+    first_page: omit --cursor
+    response_field: next_cursor
+    binding: [collection, selectors, filters, order, snapshot]
+    append_behavior: >-
+      Records added after the first page are excluded from that cursor snapshot.
+      Experiment cursors bind each original stable identity to immutable archive
+      content when available, so unchanged full-to-summary or summary-to-drop
+      projection rollover does not invalidate continuation. Without sufficient
+      immutable or retained detail to prove an original identity unchanged, the
+      cursor fails with cursor_snapshot_unavailable.
+    invalid_behavior: cursor_invalid
+    unavailable_behavior: cursor_snapshot_unavailable
+    caller_rules: [do_not_parse, do_not_construct, do_not_compare_internals]
+  omission:
+    required_when_any_entry_is_not_returned:
+      - omitted
+      - omitted_count
+      - omission_reason
+      - retrieval
+    semantics: >-
+      Omission is explicit in both text and structured output. A response never
+      silently slices a collection, truncates a scalar, or claims omitted detail
+      is unavailable. Every omitted addressable item has an advancing cursor or
+      exact get command; unaddressable legacy items retain compatibility
+      diagnostics and are never assigned fabricated history.
+  output_bounds:
+    maximum_limit: 100
+    max_serialized_utf8_bytes: 32768
+    scalar_truncation: forbidden
+    omission_unit: whole_entries
+  identity:
+    plan:
+      canonical_format: 'plan:<lowercase-rfc9562-uuid>'
+      persistence: stored in header.id when a plan is first published
+      transition: the identical ID is copied unchanged into the immutable archive file
+      legacy_format: 'legacy-plan:<sha256>'
+      legacy_derivation: >-
+        SHA-256 over RFC 8785 canonical JSON of the complete plan after the
+        existing read-compatibility normalization of legacy status and task
+        shape. The archive transition computes identity from the same normalized
+        document before publication. Derivation is read-only and never rewrites
+        active or archived bytes; a legacy identity may change while an active
+        legacy plan is edited because no persisted historical identity exists.
+      test_vectors:
+        - canonical_json: '{"header":{"created":"2026-07-14","status":"open","title":"Plan: Complete bounded retrieval"},"tasks":[]}'
+          stable_id: legacy-plan:b6f93d6fc5a0ac3ada017670ac311794ad92800fb436703f8f09e25ddce8b89a
+          mirrored_example_paths: [.agentera/archive/PLAN-copy-a.yaml, .agentera/archive/PLAN-copy-b.yaml]
+          identical_result: mirrored_provenance
+      collision: >-
+        Byte-equivalent normalized legacy plans are one logical identity with
+        every physical path retained as mirrored provenance. Different plan
+        documents carrying the same persisted ID, or a detected digest collision,
+        are unaddressable; list reports compatibility=degraded and get returns
+        ambiguous with every candidate provenance path. The CLI never chooses by
+        mtime, archive filename, or discovery order.
+    task:
+      format: '<plan-id>/task:<positive-integer>'
+      selector: --task N
+      scope: task numbers are unique only inside one plan identity
+    objective:
+      canonical_format: 'objective:<lowercase-rfc9562-uuid>'
+      persistence: stored in header.id and unchanged by title or directory rename
+      canonical_root: .agentera/optimize/<objective-slug>
+      legacy_root: .agentera/optimera/<objective-slug>
+      legacy_format: 'legacy-objective:<sha256>'
+      legacy_derivation: >-
+        SHA-256 over RFC 8785 canonical JSON of the legacy objective's description,
+        measurement, metric, baseline, gates, constraints, and scope; title,
+        status, closure fields, directory root, and directory slug are excluded.
+        This preserves identity across a title/path-only rename without rewriting
+        history. Editing identity inputs may change a legacy identity and is
+        reported as degraded compatibility.
+      test_vectors:
+        - canonical_json: '{"baseline":{"description":"100 ms"},"constraints":[],"description":"Reduce latency","gates":{},"measurement":"p95","metric":{"direction":"minimize","unit":"ms"},"scope":{"excluded":[],"included":["CLI"]}}'
+          title_variants: [CLI latency, Faster CLI]
+          root_variants: [.agentera/optimize/cli-latency, .agentera/optimera/faster-cli]
+          stable_id: legacy-objective:aa987d92dadce65b8b2d8f54c741a10f5d024d864cb0ef309b4321b4e19e4ceb
+      path_compatibility: >-
+        Read both optimize and optimera roots. Identical records carrying one
+        persisted objective ID are mirrored provenance. Different records with
+        the same persisted or derived ID, or unresolved candidates in both roots,
+        return ambiguous; canonical-root preference must not hide a collision.
+    experiment:
+      format: '<objective-id>/experiment:<non-negative-integer>'
+      scope: experiment numbers are unique only within one objective identity
+      zero: experiment 0 is valid and is normally the baseline
+      collision: duplicate numbers inside one objective are ambiguous and never resolved by array order
+      compatibility: >-
+        Legacy full-detail or 10/40/50 summary entries with a missing or
+        duplicate number remain visible in reads with addressable=false and an
+        explicit compatibility caveat. Reads do not assign a number, choose a
+        duplicate by array order, migrate a root, or rewrite retained bytes.
+      publication_validation: >-
+        Before any publication effect, require one unambiguous objective
+        identity, a non-negative integer number, and no retained full-detail or
+        summary entry with that number. Ambiguous canonical/legacy objective
+        candidates, missing objective identity, and duplicate experiment
+        identity fail validation without changing bytes.
+      publication:
+        command: agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml --format json
+        authority: typed_state_writer
+        archive_ownership: experiment_archival
+        storage_scope: objective_directory
+        publication_order: archive_before_projection
+        projection_policy: uniform_10_40_50
+        input: one schema-valid experiment entry without the CLI-owned number field
+        identity_assignment: the CLI assigns the validated --number to the published entry
+        collision_rule: >-
+          An existing matching identity and byte-equivalent experiment is an
+          idempotent replay; the same identity with different content is a
+          collision and leaves the projection unchanged.
+        transaction: >-
+          Validate objective identity, canonical/legacy ambiguity, experiment
+          identity, existing projection schema, caller input schema, and final
+          projection bytes before atomically replacing experiments.yaml.
+        failure_atomicity: >-
+          Validation, staging, and pre-publication failures preserve both active
+          and one-line archive bytes. An interruption after atomic replacement
+          may report failure after publication; retrying the same command must
+          return the already-published entry without duplication.
+        scope_boundary: >-
+          Publication preserves the existing 10/40/50 projection contract and
+          durably publishes its objective-scoped immutable archive before
+          replacing the projection, as owned by experiment_archival.
+  commands:
+    plan_tasks:
+      list: agentera state plan tasks list [--plan PLAN_ID] [--limit N] [--cursor TOKEN] --format json
+      get: agentera state plan tasks get [--plan PLAN_ID] --task N --format json
+      selectors:
+        plan:
+          list_required: false
+          list_default: active plan resolved once and returned as filters.plan
+          get_required: false
+          get_default: active plan resolved once and returned in the response source
+          pattern: '^(plan:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|legacy-plan:[0-9a-f]{64})$'
+        task:
+          get_required: true
+          pattern: '^[1-9][0-9]*$'
+    plans:
+      list: agentera state plan list [--limit N] [--cursor TOKEN] --format json
+      get: agentera state plan get --plan PLAN_ID --format json
+      selectors:
+        plan:
+          get_required: true
+          pattern: '^(plan:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|legacy-plan:[0-9a-f]{64})$'
+    experiments:
+      list: agentera state experiments list --objective OBJECTIVE_ID [--limit N] [--cursor TOKEN] --format json
+      get: agentera state experiments get --objective OBJECTIVE_ID --number N --format json
+      publish: agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml --format json
+      selectors:
+        objective:
+          list_required: true
+          get_required: true
+          pattern: '^(objective:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|legacy-objective:[0-9a-f]{64})$'
+        number:
+          get_required: true
+          pattern: '^(0|[1-9][0-9]*)$'
+  failures:
+    schema_version: agentera.stateFailure.v1
+    required_fields: [class, message, syntax, example, recovery]
+    classes:
+      invalid_request: malformed, duplicate, missing, or incompatible selector
+      unsupported_artifact: collection is not exposed by the requested grammar
+      not_found: a valid exact identity has no matching record
+      ambiguous: legacy derivation, duplicate identity, or path compatibility has multiple candidates
+      corrupt: selected state cannot be parsed or validated safely
+      incomplete: selected record exists but required detail is unavailable
+      cursor_invalid: cursor is malformed or bound to different selectors, filters, collection, or order
+      cursor_snapshot_unavailable: the exact cursor snapshot cannot be resumed
+      unsupported_state: authority cannot return a safe bounded envelope
+    exit_codes:
+      usage: 2
+      state_or_compatibility_failure: 1
+    legacy_diagnostic_rule: >-
+      Compatibility failures include candidate provenance and a working recovery
+      command but never synthesize an ID, objective scope, task, experiment, or
+      archive event.
+  collections:
+    - collection_id: progress.records
+      artifact_id: progress
+      growth: append_only_unbounded
+      identity: 'progress:<positive-entry-number>'
+      storage_ownership: immutable_numbered_archive_with_bounded_current_projection
+      ordering: entry_number_desc
+      bounds: count_1_to_100_and_serialized_utf8_budget
+      cursor: opaque_snapshot_cursor
+      omission: explicit_with_advancing_cursor_or_exact_get
+      get: agentera state progress get --number N --format json
+    - collection_id: decisions.records
+      artifact_id: decisions
+      growth: append_only_unbounded_with_declared_mutable_overlay
+      identity: 'decisions:<positive-entry-number>'
+      storage_ownership: immutable_numbered_archive_plus_decision_overlay_with_bounded_current_projection
+      ordering: entry_number_desc
+      bounds: count_1_to_100_and_serialized_utf8_budget
+      cursor: opaque_snapshot_cursor
+      omission: explicit_with_advancing_cursor_or_exact_get
+      get: agentera state decisions get --number N --format json
+    - collection_id: health.records
+      artifact_id: health
+      growth: append_only_unbounded
+      identity: 'health:<positive-entry-number>'
+      storage_ownership: immutable_numbered_archive_with_bounded_current_projection
+      ordering: entry_number_desc
+      bounds: count_1_to_100_and_serialized_utf8_budget
+      cursor: opaque_snapshot_cursor
+      omission: explicit_with_advancing_cursor_or_exact_get
+      get: agentera state health get --number N --format json
+    - collection_id: plan.plans
+      artifact_id: plan
+      growth: one_active_plus_append_only_immutable_file_archives
+      identity: retrieval.identity.plan
+      storage_ownership: active_plan_file_and_immutable_plan_archive_files
+      ordering: created_desc_then_plan_id_asc
+      bounds: count_1_to_100_and_serialized_utf8_budget
+      cursor: opaque_snapshot_cursor
+      omission: explicit_with_advancing_cursor_or_exact_get
+      get: retrieval.commands.plans.get
+    - collection_id: plan.tasks
+      artifact_id: plan
+      growth: mutable_while_plan_active_then_immutable_with_archived_plan
+      identity: retrieval.identity.task
+      storage_ownership: owning_active_plan_file
+      ordering: task_number_asc
+      bounds: count_1_to_100_and_serialized_utf8_budget
+      cursor: opaque_snapshot_cursor
+      omission: explicit_with_advancing_cursor_or_exact_get
+      get: retrieval.commands.plan_tasks.get
+    - collection_id: experiments.records
+      artifact_id: experiments
+      growth: append_only_objective_scoped_with_10_full_40_summary_50_projection
+      identity: retrieval.identity.experiment
+      storage_ownership: objective_scoped_durable_records_and_bounded_10_40_50_projection
+      ordering: experiment_number_desc
+      bounds: count_1_to_100_serialized_utf8_budget_and_projection_10_40_50
+      cursor: opaque_snapshot_cursor
+      omission: explicit_with_advancing_cursor_or_exact_get_or_legacy_unavailable_diagnostic
+      get: retrieval.commands.experiments.get
+    - collection_id: todo.items
+      artifact_id: todo
+      growth: bounded_current_working_set_with_resolved_compaction
+      identity: absent_legacy_markdown_item_identity
+      storage_ownership: TODO.md
+      ordering: severity_then_document_order
+      bounds: 10_open_40_resolved_summary_50_total_projection
+      cursor: none_not_publicly_pageable
+      omission: current_query_must_report_omission_but_exact_get_is_unavailable
+      get: unsupported_no_stable_identity
+    - collection_id: docs.entries
+      artifact_id: docs
+      growth: bounded_document_inventory
+      identity: canonical_document_path_when_present
+      storage_ownership: .agentera/docs.yaml_or_docs_mapping
+      ordering: document_order
+      bounds: artifact_budget_and_projection_output_budget
+      cursor: none_not_publicly_pageable
+      omission: current_query_must_report_omission_but_exact_get_is_unavailable
+      get: unsupported_no_public_get
+    - collection_id: changelog.entries
+      artifact_id: changelog
+      growth: append_only_public_release_history
+      identity: absent_markdown_entry_identity
+      storage_ownership: CHANGELOG.md
+      ordering: document_order_newest_release_first
+      bounds: no_collection_page_contract
+      cursor: none_not_publicly_pageable
+      omission: query_result_may_be_filtered_but_must_not_claim_exact_retrieval
+      get: unsupported_no_stable_identity
+  non_collections:
+    - artifact_id: vision
+      behavior: singleton_document_no_list_or_get_grammar
+    - artifact_id: design
+      behavior: singleton_document_no_list_or_get_grammar
+    - artifact_id: objective
+      behavior: one_selected_objective_document; identity is only a required experiments selector in this task
+    - artifact_id: plan_archive
+      behavior: storage special case represented publicly by plan.plans
+    - artifact_id: optimize_harness
+      behavior: local harness storage, not public state retrieval
+  gap_closure_evidence:
+    - surface: agentera state plan --format json / plans
+      declared_gap: PLAN_HISTORY_CATALOG_LIMIT capped catalog rows without collection-level omission recovery
+      outcome: closed
+      closure: active and archive-only plan_catalog responses report omitted, omitted_count, omission_reason, and executable public list/get recovery; the plan list surface owns count and serialized-byte continuation
+    - surface: agentera state plan --format json / source.archive_paths
+      declared_gap: archive paths were capped at 10 with only an omitted count and no stable recovery
+      outcome: closed
+      closure: source reports archive_paths_omitted, archive_paths_omitted_count, archive_paths_omission_reason, and plan list/get recovery instead of requiring path traversal
+    - surface: agentera state plan text / tasks
+      declared_gap: legacy text projection capped tasks at 10 and needed explicit whole-record omission recovery
+      outcome: closed
+      closure: text retains complete scalar values and whole task rows only, caps rows at 10 and total output at budgets.list.max_utf8_bytes, and reports count/byte omissions with task list/get or exact-plan recovery without ellipsis
+    - surface: agentera state plan --format json / tasks
+      declared_gap: structured plan projection needed deterministic whole-task byte omission and public recovery
+      outcome: closed
+      closure: JSON and YAML report omitted, omitted_count, omission_reason, and task list/get recovery; task list JSON/YAML enforce budgets.list.max_utf8_bytes
+    - surface: legacy agentera state experiments projection
+      declared_gap: the pre-list/get projection is objective-selected rather than a stable cross-objective collection
+      outcome: out_of_scope
+      closure: objective-scoped experiments list/get is the supported retrieval surface; adding identity or pagination to the legacy projection would duplicate that contract
+  plan_archive_diagnostics:
+    classification: pre_existing_compatibility_caveat
+    smoke_test_behavior: >-
+      A lifecycle diagnostic on an unrelated archived plan degrades list/catalog
+      status and remains visible, but does not fail exact retrieval of a different
+      valid plan. Exact get fails only when the selected candidate is invalid,
+      corrupt, or ambiguous. Read-only smoke tests assert diagnostics and never
+      repair or rewrite archive history.
+    known_live_diagnostics:
+      - plan-2026-06-04-d56-parity-closeout.yaml
+      - plan-2026-07-08-cliDistributionMajor-secondary-signal.yaml
+
+consumer_matrix:
+  status: active_authority
+  purpose: >-
+    Mechanically account for every capability source and bundled artifact-schema
+    consumer of numbered decisions, progress, and health state. The artifact
+    schemas remain the role authority; this matrix binds each declared consumer
+    to the bounded startup and exact retrieval contracts below.
+  source_root: packages/cli/src/capabilities/<capability>/instructions.ts
+  bundle_root: skills/agentera/capabilities/<capability>/schemas/artifacts.yaml
+  required_capabilities:
+    - status
+    - vision
+    - discuss
+    - research
+    - plan
+    - build
+    - optimize
+    - audit
+    - document
+    - profile
+    - design
+    - orchestrate
+  access_contract:
+    startup: agentera prime --context <capability> --format json
+    list: agentera state <artifact-id> list --limit 20 --format json
+    get: agentera state <artifact-id> get --number N --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 scope.supported_artifacts.artifact_id
+    entry_number: positive integer from the artifact's entry_number_field
+  uniqueness: stable_id is unique within one project archive
+  ordering:
+    list: entry_number descending, numerically rather than lexicographically
+    tie_breaker: stable_id ascending (defensive only; numbers are unique per artifact)
+    get: exact stable_id match; no topic or summary scan is a substitute
+  legacy_rows:
+    canonical_number: >-
+      A positive entry_number field, or an artifact-labelled summary beginning
+      with Cycle N, Decision N, Audit N, or the decisions-only shorthand DNN.
+      The number is accepted only from that explicit position; arbitrary prose
+      and nested values never establish identity.
+    unaddressable: >-
+      A physical current or legacy-summary row without one explicit number.
+      It is list-only and uses stable_id: null and entry_number: null; no
+      synthetic number, position, or inferred reference is permitted.
+    ambiguous: >-
+      A row containing multiple explicit decision shorthands such as
+      Staging D3+D4. It remains list-only with stable_id: null and is never
+      assigned the first or most recent shorthand.
+    physical_accounting: >-
+      physical counts raw current rows, current archive-summary rows, and
+      validated or rejected numbered archive files. addressable counts those
+      physical rows carrying one explicit number; unaddressable and ambiguous
+      partition the remaining physical rows. addressable_ids counts unique
+      stable-ID groups. mirrored, duplicate, and conflict are non-additive
+      redundancy classifications over addressable rows; omitted counts rows
+      not emitted on the current bounded page.
+
+envelope:
+  schema_version: agentera.stateArchiveEntry.v1
+  required_fields:
+    - schemaVersion
+    - artifact_id
+    - entry_number
+    - record
+    - record_sha256
+  field_contract:
+    schemaVersion: exact string agentera.stateArchiveEntry.v1
+    artifact_id: supported artifact ID matching the archive directory
+    entry_number: positive integer matching the filename and record identity field
+    record: complete pre-projection entry, not a compact summary
+    record_sha256: lowercase SHA-256 of the canonical record bytes
+  canonical_record:
+    encoding: UTF-8
+    serialization: canonical JSON with recursively sorted object keys and no whitespace
+    arrays: preserve source order
+    hash_input: record only, excluding the envelope
+  identity_checks:
+    - envelope.artifact_id matches the parent artifact directory
+    - envelope.entry_number matches the filename
+    - envelope.entry_number matches record.<artifact entry_number_field>
+    - record_sha256 matches canonical_record
+  forbidden_fields:
+    - commit
+    - commit_hash
+    - git_commit
+    - git_ref
+    - parent_commit
+  provenance_rule: >-
+    Git provenance is durability evidence returned by a later diagnostic
+    surface, never per-entry commit bookkeeping and never part of immutable
+    record identity.
+
+overlays:
+  location: .agentera/overlays/decisions.yaml
+  project_root_fixed: true
+  docs_yaml_override: forbidden
+  schema_version: agentera.decisionOverlay.v1
+  supported_artifact: decisions
+  identity_key: decisions:<decision-number>
+  storage_shape: >-
+    A mapping keyed by stable decision ID. Each value contains only the
+    authority-declared mutable paths and never replaces the immutable archive
+    record.
+  mutable_paths:
+    - satisfaction.state
+    - satisfaction.evidence
+    - satisfaction.user_confirmation.confirmed_by
+    - satisfaction.user_confirmation.confirmed_at
+  derived_paths:
+    - satisfaction.review_needed
+    - satisfaction.source
+    - satisfaction.caveats
+  immutable_paths:
+    - number
+    - date
+    - question
+    - context
+    - alternatives
+    - choice
+    - reasoning
+    - confidence
+    - feeds_into
+  state_values: [open, provisionally_satisfied, user_confirmed_satisfied]
+  transition_rules:
+    open:
+      allowed_next: [open, provisionally_satisfied, user_confirmed_satisfied]
+      provisional_requires: non_empty_satisfaction.evidence
+      confirmed_requires: explicit_current_user_confirmation_metadata
+    provisionally_satisfied:
+      allowed_next: [open, provisionally_satisfied, user_confirmed_satisfied]
+      provisional_requires: non_empty_satisfaction.evidence
+      confirmed_requires: explicit_current_user_confirmation_metadata
+    user_confirmed_satisfied:
+      allowed_next: [user_confirmed_satisfied]
+      downgrade: forbidden_without_explicit_current_user_confirmation
+  decision_53_rules:
+    missing_satisfaction: valid legacy state; derive review_needed=true
+    open: review_needed=true
+    provisional: review_needed=true until explicit user confirmation
+    confirmed: review_needed=false only with confirmed_by and confirmed_at
+    inference: forbidden from commits, downstream references, summaries, or Git history
+    protected_review: unresolved decisions remain visible and never block archive storage
+
+projections:
+  archive:
+    role: complete immutable historical detail
+    source_of_truth_for: historical_record_fields
+    omission: never omit fields from an archive record
+  current:
+    role: bounded active projection for current artifact consumers
+    default_capacity:
+      active_entries: 10
+      summary_entries: 40
+      total_entries: 50
+      semantics: >-
+        These are projection defaults, not retention or deletion limits. Entries
+        outside the default display capacity remain in the numbered archive;
+        entries whose archive cannot be verified remain full in the projection
+        with recovery metadata rather than being discarded.
+    legacy_summary_overflow:
+      source: legacy_summary
+      compatibility: degraded
+      detail_availability: unavailable
+      archive_verified: false
+      semantics: >-
+        Legacy inline summaries without a verified numbered record are bounded
+        like every other projection item. If omitted, omission_provenance keeps
+        their degraded and incomplete status explicit; omission never promotes
+        them to archive-backed detail or reconstructs missing fields.
+    paths:
+      progress: .agentera/progress.yaml
+      decisions: .agentera/decisions.yaml
+      health: .agentera/health.yaml
+    source_of_truth_for: current_projection_and_legacy_compatibility_state
+    archive_relationship: >-
+      A current entry may be full, summary-only, or absent from the projection;
+      archive presence and hash verification determine whether full detail is
+      available. Current mutable decision overlay values are composed at read
+      time and do not rewrite archive bytes.
+  summary:
+    role: bounded list and startup representation
+    required_item_fields: [stable_id, artifact_id, entry_number, addressable, classification, detail_availability, source]
+    nullable_item_fields:
+      - stable_id
+      - entry_number
+    detail_availability: [full, summary, unavailable]
+    source_values: [archive, current_projection, legacy_full, legacy_summary]
+    classification_values: [canonical, mirrored, duplicate, conflict, ambiguous, unaddressable, corrupt]
+    counts:
+      required: [physical, addressable, addressable_ids, unaddressable, ambiguous, mirrored, duplicate, conflict, omitted]
+      reconciliation: >-
+        physical = addressable + unaddressable + ambiguous;
+        addressable_ids is the unique logical count and is not added to the
+        physical count; mirrored, duplicate, and conflict are overlapping
+        redundancy diagnostics, not partition buckets.
+    omission: >-
+      Omitted detail is represented by omitted=true, omitted_count,
+      omission_reason, and a get command pointer. It is never silently
+      truncated, represented as a fabricated summary, or treated as missing
+      history without provenance.
+  startup:
+    role: bounded orientation and capability-startup projection
+    required_fields: [command, status, source, source_contract]
+    allowed_payload: >-
+      Counts, bounded summaries, actionable stable IDs, detail availability,
+      omission metadata, compatibility classification, and retrieval pointers.
+    forbidden_payload: [raw_archive_records, raw_yaml, unbounded_entry_arrays, Git_history_scan]
+    incomplete_state: >-
+      Preserve degraded or blocked compatibility and omission metadata in
+      source_contract; do not fall back to raw archive traversal merely to fill
+      an omitted field.
+
+api:
+  namespace: agentera state
+  artifact_syntax: agentera state <artifact-id>
+  formats: [text, json, yaml]
+  direct_get:
+    command: agentera state <artifact-id> get --number N --format json
+    examples:
+      progress: agentera state progress get --number 747 --format json
+      decisions: agentera state decisions get --number 53 --format json
+      health: agentera state health get --number 29 --format json
+    required_selector: --number N
+    result: >-
+      One complete record composed from the immutable archive and only the
+      authority-declared current overlay fields, with stable_id, source,
+      detail_availability, compatibility, and provenance metadata.
+    archive_only: direct retrieval reads the exact numbered record without scanning unrelated records
+  list:
+    command: agentera state <artifact-id> list [--limit N] [--cursor TOKEN] --format json
+    examples:
+      progress: agentera state progress list --limit 20 --format json
+      decisions_next_page: agentera state decisions list --limit 20 --cursor TOKEN --format json
+    default_limit: 20
+    minimum_limit: 1
+    maximum_limit: 100
+    ordering: identity.ordering.list
+    response_fields:
+      required: [command, status, entries, counts, source, filters, snapshot, source_contract]
+      entry: [stable_id, artifact_id, entry_number, current_status, detail_availability, source, compatibility, provenance]
+      optional_entry: [summary, record_status, overlay_applied, retrieval]
+    empty_result: status=ok with entries=[] and counts.total=0; absence is not an error
+  durability:
+    command: agentera check durability [--project PATH] [--artifact ARTIFACT] [--number N] [--limit N] --format json
+    formats: [text, json, yaml]
+    selectors:
+      artifact: optional supported numbered archive artifact ID
+      number: optional positive entry number; 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: [stable_id, artifact_id, entry_number, status, local, git]
+    guarantees:
+      read_only: true
+      remote_contact: forbidden
+      writes_independent: true
+      head_capture: >-
+        Capture the local HEAD before inspection and after inspection. If the
+        values differ, report changed_head and do not claim committed recovery.
+      deterministic: >-
+        With unchanged local files and reachable refs, repeated checks emit the
+        same ordered result and do not create state or contact a remote.
+  backfill:
+    command: >-
+      agentera state backfill [--project PATH] [--artifact ARTIFACT]
+      [--number N] [--commit HASH] [--path PATH] [--limit N]
+      [--dry-run|--apply --force] --format {text,json,yaml}
+    formats: [text, json, yaml]
+    default_limit: 100
+    maximum_limit: 100
+    maximum_commits: 500
+    maximum_history_bytes: 16777216
+    supported_artifacts: [progress, decisions, health]
+    reachable_refs: [HEAD, refs/heads, refs/tags]
+    excluded_refs: [refs/remotes, custom_refs]
+    apply_requires: [--apply, --force, --project PATH, --artifact ARTIFACT, --number N]
+    status_values: [complete, degraded, blocked, unavailable]
+    response:
+      required_fields: [command, mode, status, project, read_only, remote_contact, head, scan, counts, active_projections_unchanged, active_projection_hashes, omitted, omitted_count, omission_reason, continuation, entries, diagnostics, source_contract]
+      entry_fields: [entry_id, artifact_id, entry_number, commit, path, blob_id, content_hash, ambiguity_reason, eligible, reachable, provenance, operation, refusal]
+    modes:
+      inventory: >-
+        The default read-only mode reports up to maximum_limit final rows after
+        combining reachable and rewritten-history occurrences. Omitted rows
+        carry explicit omission metadata; returned rows include commit, path,
+        blob identity, stable entry ID, canonical content hash, and an explicit
+        ambiguity reason.
+      preview: >-
+        --dry-run is read-only and shows proposed immutable archive bytes only
+        for a returned exact unique candidate, together with every matching
+        provenance.
+      apply: >-
+         --apply --force is the only mutation mode. It requires one project,
+         artifact, and entry number. A prior --dry-run is optional. Apply
+         independently revalidates the selected project, current HEAD, allowed
+         ref reachability, candidate path/blob/content, and immutable archive
+         target immediately before publication, and never overwrites conflicts.
+    ambiguity_reasons:
+      - none
+      - conflicting_versions
+      - shallow_history
+      - history_rewritten
+      - missing_history
+      - corrupt_history
+      - changed_head
+      - scan_bounded
+      - git_unavailable
+      - immutable_conflict
+      - candidate_changed
+      - no_matching_pin
+    guarantees:
+      read_only_inventory_and_preview: true
+      apply_requires_force: true
+      preview_optional: true
+      apply_revalidation: >-
+        Apply repeats project, HEAD, allowed-ref reachability, candidate
+        provenance/content, and immutable-target checks immediately before
+        publication; a failed check preserves active projections and archives.
+      remote_contact: forbidden
+      custom_refs: forbidden
+      commit_fields_in_archive_records: forbidden
+      projection_writes: forbidden
+      immutable_conflicts: refuse_without_overwrite
+      retry: identical_publication_is_idempotent
+      failure_projection_rule: active_projections_remain_byte_identical
+    omission:
+      fields: [omitted, omitted_count, omission_reason, continuation]
+      complete_reason: none
+      bounded_reason: result_limit
+      continuation: >-
+        No cursor is issued. Use --artifact ARTIFACT --number N to retrieve an
+        omitted entry because --limit cannot exceed maximum_limit (100).
+    traceability:
+      provenance_fields: [commit, path, blob_id, entry_id, content_hash, reachable]
+      archive_record_forbids: [commit, commit_hash, git_commit, git_ref]
+    recovery: >-
+      Resolve the reported ambiguity, unavailable Git state, changed candidate,
+      or immutable conflict and retry the same exact selectors. A refused
+      operation leaves active projections and existing archives unchanged;
+      identical publication is an idempotent replay.
+  migrate:
+    namespace: agentera state migrate
+    command: >-
+      agentera state migrate [--project PATH] [--artifact ARTIFACT]
+      [--number N] [--path PATH] [--limit N]
+      [--dry-run|--apply --force] --format {text,json,yaml}
+    purpose: >-
+      Inventory bounded, project-local legacy state and define the only
+      authority for a later non-Git migration apply. This surface does not
+      infer missing records, contact Git, contact a remote, or remove legacy
+      source files.
+    implementation_boundary: >-
+      The runtime owns bounded, project-local candidate inventory and the
+      explicit archive, backup, projection, and mutation flow described here.
+      Inventory never reads Git or writes archives, backups, or projections;
+      migration remains independent of the optional Git backfill surface.
+    formats: [text, json, yaml]
+    default_limit: 20
+    maximum_limit: 100
+    supported_artifacts: [progress, decisions, health]
+    selectors:
+      project:
+        flag: --project PATH
+        default: current_working_directory
+        resolution: >-
+          Resolve the selected directory to a real project root before any
+          candidate is considered. The project root is selected explicitly or
+          is the caller's current working directory; AGENTERA_HOME, profile
+          paths, docs.yaml overrides, and Git worktrees do not replace it.
+      artifact:
+        flag: --artifact ARTIFACT
+        required_for_apply: true
+        valid_values: [progress, decisions, health]
+      number:
+        flag: --number N
+        pattern: '^[1-9][0-9]*$'
+        required_with: --artifact
+        meaning: exact positive legacy entry number; never a positional offset
+      path:
+        flag: --path PATH
+        pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,63}\.(md|yaml|yml)$'
+        relative_to: selected_project_root
+        required_for_custom_apply: true
+        meaning: exact candidate path pin; inventory may omit it to enumerate candidates
+      limit:
+        flag: --limit N
+        default: 20
+        minimum: 1
+        maximum: 100
+        meaning: maximum returned candidate summaries, not a scan escape hatch
+      format:
+        flag: --format FORMAT
+        valid_values: [text, json, yaml]
+    modes:
+      inventory:
+        selector: default when neither --dry-run nor --apply is present
+        read_only: true
+        writes: forbidden
+      preview:
+        selector: --dry-run
+        read_only: true
+        writes: forbidden
+        output: exact proposed archive, backup, and projection operations only for addressable candidates
+      apply:
+         selector: --apply --force
+         read_only: false
+         mutation_intent: explicit_apply_and_force
+         selectors_required: [--artifact, --number]
+         mutation: >-
+           The runtime publishes only after revalidating the selected candidate,
+           project boundary, backup identity, and immutable archive identity.
+      invalid_combinations:
+        - flags: [--apply, --dry-run]
+          failure_class: invalid_selector
+          message: --apply and --dry-run are mutually exclusive
+        - flags: [--apply]
+          requires: --force
+          failure_class: invalid_selector
+          message: --apply requires explicit --force intent
+        - flags: [--force]
+          requires: --apply
+          failure_class: invalid_selector
+          message: --force requires --apply
+    inventory:
+      project_local: true
+      bounded_scan:
+        roots:
+          - path: .
+            maximum_depth: 1
+          - path: .agentera
+            maximum_depth: 1
+        excluded_relative_paths:
+          - .git
+          - .agentera/archive
+          - .agentera/overlays
+          - .agentera/migration-backups
+        maximum_candidate_files: 256
+        maximum_file_bytes: 1048576
+        maximum_total_bytes: 16777216
+        ordering: normalized_relative_path_ascending
+      candidate_rule: >-
+        A candidate is a regular, non-symlink file directly under one declared
+        scan root whose basename is ASCII and matches
+        ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}\.(md|yaml|yml)$. Fixed legacy names
+        are recognized first; every other accepted name is a custom candidate
+        and remains project-local.
+      fixed_names:
+        - path: .agentera/PROGRESS.md
+          artifact: progress
+        - path: .agentera/DECISIONS.md
+          artifact: decisions
+        - path: .agentera/HEALTH.md
+          artifact: health
+      custom_name_rule: >-
+        Custom names are discovered only within the declared roots and are
+        never mapped from their basename alone. A custom candidate is
+        addressable only when --path pins it, --artifact identifies the
+        numbered artifact, and parsing yields exactly one supported stable
+        identity for the requested --number. A candidate with zero, multiple,
+        conflicting, or unsupported identities is inventory-visible but not
+        apply-eligible.
+      deterministic_rejections:
+        unsafe_path: absolute paths, traversal segments, encoded traversal, URI paths, or symlink components
+        escaping_path: realpath is outside the selected project root
+        ambiguous_candidate: one candidate yields multiple artifact or entry identities, or identities conflict
+        unsupported_candidate: unsupported extension, non-regular file, invalid encoding, or unsupported artifact shape
+        scan_bounded: candidate or byte limits are exceeded; omitted candidates are reported, never silently dropped
+    project_boundary:
+      selected_root: resolved_realpath_of_project_selector
+      candidate_rule: >-
+        The candidate realpath and every existing parent must remain strictly
+        beneath selected_root. The project root itself is not a candidate.
+      reject: [absolute_candidate_path, traversal, encoded_traversal, uri_path, symlink_escape, outside_project]
+      docs_mapping: forbidden
+      remote_access: forbidden
+    compatibility_window:
+      name: v2_to_v3_local_state
+      scope: numbered_progress_decisions_health_only
+      supported_sources: [legacy_markdown, legacy_yaml, current_yaml_projection]
+      classifications: [complete, degraded, blocked, unsupported]
+      cases:
+        new:
+          classification: complete
+          behavior: preserve current archive and projection authority
+        legacy_full:
+          classification: degraded
+          behavior: archive exact parsed records and retain source provenance
+        legacy_summary:
+          classification: degraded
+          behavior: preserve summary-only detail and never reconstruct absent fields
+        non_git:
+          classification: complete
+          behavior: local inventory and publication do not require Git
+        ambiguous:
+          classification: blocked
+          behavior: never choose between candidates; preserve all diagnostics
+        corrupt:
+          classification: blocked
+          behavior: preserve source bytes and do not archive or project invalid records
+        unsupported:
+          classification: unsupported
+          behavior: report a deterministic candidate diagnostic without mutation
+      no_reconstruction: >-
+        Missing, ambiguous, compacted, summary-only, and satisfaction-incomplete
+        state remains explicitly classified. No fields, identity, satisfaction,
+        provenance, or history are inferred from names, summaries, Git, or
+        profile state. Decision 53 remains governed by overlays.decision_53_rules.
+    backups:
+      required_for_apply: true
+      project_local: true
+      root: .agentera/migration-backups
+      path_template: .agentera/migration-backups/<sha256-relative-source>.bak
+      bytes: exact_source_bytes_before_projection
+      identity: sha256(relative_source_path + NUL + source_bytes)
+      publication: exclusive_immutable_file
+      existing_backup: >-
+        An identical backup is an idempotent replay. Different bytes at the
+        same backup identity are backup_conflict and block without overwrite.
+      cleanup: forbidden
+      required_before_projection: true
+    publication:
+      order:
+        - validate_candidate_and_selector
+        - publish_immutable_archive_record
+        - publish_immutable_backup
+        - publish_current_projection
+      archive_before_projection: true
+      archive_immutability: storage.archive.mutation_policy
+      projection_failure: >-
+        Leave archive, backup, and the pre-existing projection bytes unchanged
+        except for successfully published immutable artifacts; retry must replay
+        identical artifacts rather than restart or synthesize a new identity.
+      monotonic_states: [inventory, previewed, archive_published, backup_published, projection_published]
+      retry: >-
+        Repeating the same project, selector, source bytes, and canonical record
+        is an idempotent replay. The same stable identity with different bytes
+        is immutable_conflict; no existing archive, backup, or projection bytes
+        may be overwritten.
+    git:
+      required: false
+      reads: forbidden
+      remote_contact: forbidden
+      completion_independent: true
+      provenance: local_source_path_and_content_hash_only
+    result:
+      schema_version: agentera.stateMigrationResult.v1
+      statuses: [complete, degraded, blocked, unavailable]
+      required_fields: [schemaVersion, command, status, mode, project, read_only, mutation_intent, mutation_performed, remote_contact, inventory_performed, entries, counts, diagnostics, source_contract, omitted, omitted_count, omission_reason, retrieval]
+      entry_fields: [candidate_id, path, artifact_id, entry_number, classification, detail_availability, compatibility, source, addressable, size_bytes, rejection, provenance]
+      count_fields: [physical, addressable, addressable_ids, unaddressable, ambiguous, mirrored, duplicate, conflict, omitted]
+      count_rules:
+        physical:
+          source: all_candidates
+          operation: count
+        addressable:
+          source: visible_entries
+          operation: count
+          predicates: [{field: addressable, equals: true}]
+        addressable_ids:
+          source: visible_entries
+          operation: distinct
+          field: candidate_id
+        unaddressable:
+          source: visible_entries
+          operation: count
+          predicates:
+            - {field: addressable, equals: false}
+            - {field: classification, not_equals: ambiguous}
+        ambiguous:
+          source: visible_entries
+          operation: count
+          predicates: [{field: classification, equals: ambiguous}]
+        mirrored:
+          source: visible_entries
+          operation: count
+          predicates: [{field: classification, equals: mirrored}]
+        duplicate:
+          source: visible_entries
+          operation: count
+          predicates: [{field: classification, equals: duplicate}]
+        conflict:
+          source: visible_entries
+          operation: count
+          predicates: [{field: classification, equals: conflict}]
+        omitted:
+          source: omitted_count
+          operation: value
+      omission:
+        fields: [omitted, omitted_count, omission_reason, retrieval]
+        field_sources:
+          omitted: has_omissions
+          omitted_count: omitted_count
+          omission_reason: omission_reason
+          retrieval: retrieval
+        complete_reason: none
+        bounded_reason: scan_bounded
+        output_bounded_reason: serialized_output_byte_budget
+        retry: >-
+          Retry with narrower project or selectors, or use the bounded list
+          pointer to continue from the same normalized snapshot.
+        output_retry: >-
+          Retry with a smaller --limit or narrower selectors; use --path with
+          --artifact and --number to address one omitted candidate. The omitted
+          records remain accounted for and no state was changed by output bounding.
+        retrieval: >-
+          agentera state migrate --project PATH [selectors] --limit N
+        semantics: >-
+          Omitted candidates are represented by omitted=true, omitted_count,
+          omission_reason, and a bounded retry/list pointer. Text, JSON, and YAML
+          are projections of the same envelope and never contain unbounded records.
+    failures:
+      schema_version: agentera.stateFailure.v1
+      deterministic: >-
+        The same authority, project bytes, selectors, and local filesystem
+        state produce the same failure class, syntax, example, and recovery.
+      classes:
+        - class: invalid_selector
+          message: selector is missing, duplicated, malformed, or not allowed for the selected mode
+          example: agentera state migrate --number 1 --format json
+          recovery: add one supported --artifact selector and retry; no state was changed
+        - class: project_boundary
+          message: selected project or candidate path escapes the project boundary
+          example: agentera state migrate --path ../secrets.yaml --format json
+          recovery: select a project-local relative path; no state was changed
+        - class: unsupported_candidate
+          message: candidate is not a supported regular file or artifact shape
+          example: agentera state migrate --path .agentera/state.txt --format json
+          recovery: use a supported Markdown or YAML candidate; no state was changed
+        - class: ambiguous_candidate
+          message: candidate has multiple or conflicting supported identities
+          example: agentera state migrate --artifact progress --number 1 --path CUSTOM.md --dry-run --format json
+          recovery: resolve the candidate ambiguity before retrying; no state was changed
+        - class: corrupt_candidate
+          message: candidate bytes or parsed record fail the declared artifact schema
+          example: agentera state migrate --artifact decisions --number 53 --dry-run --format json
+          recovery: repair or preserve the source and retry only after validation; no state was changed
+        - class: backup_conflict
+          message: immutable backup identity already contains different source bytes
+          example: agentera state migrate --artifact progress --number 1 --apply --force --format json
+          recovery: preserve the existing backup and resolve the source conflict; no projection was changed
+        - class: immutable_conflict
+          message: immutable archive identity already contains different canonical content
+          example: agentera state migrate --artifact progress --number 1 --apply --force --format json
+          recovery: preserve the existing archive and resolve the identity conflict; no projection was changed
+        - class: changed_candidate
+          message: candidate changed between inventory, preview, and apply
+          example: agentera state migrate --artifact health --number 1 --apply --force --format json
+          recovery: rerun inventory and preview against the current local bytes; no projection was changed
+        - class: scan_bounded
+          message: bounded candidate or byte limit was exceeded
+          example: agentera state migrate --limit 100 --format json
+          recovery: narrow the project or selectors; omitted candidates remain reported
+    guarantees:
+      read_only_inventory_and_preview: true
+      apply_requires_force: true
+      archive_before_projection: true
+      backups_before_projection: true
+      monotonic_retry: true
+      archive_immutability: true
+      project_local: true
+      remote_contact: forbidden
+      git_independent: true
+  cursor:
+    syntax: opaque TOKEN returned as response.next_cursor
+    first_page: omit --cursor to establish a snapshot
+    snapshot_identity: >-
+      deterministic hash of ordered candidate IDs, archive hashes, legacy
+      projection hashes when no archive exists, filters, and overlay revision.
+    snapshot_scope: artifact and filters are bound to the cursor; limit may change between pages
+    append_behavior: >-
+      Entries appended after the first page are excluded from that cursor's
+      snapshot. They appear only in a new listing without the old cursor.
+    continuation: >-
+      Continue strictly after the last emitted numeric entry number. Never
+      restart from page one, skip an entry, or duplicate an entry.
+    unavailable: return cursor_snapshot_unavailable rather than silently creating a new snapshot
+    opacity: callers must not parse, construct, or compare token internals
+  filters:
+    allowed: artifact-specific existing filters plus --limit and --cursor
+    filter_binding: every filter value is included in snapshot identity
+    invalid_filters: structured failure with syntax, valid values, and example
+
+failures:
+  schema_version: agentera.stateFailure.v1
+  envelope:
+    required_fields: [schemaVersion, status, error]
+    status: fail
+    error_required_fields: [class, message, syntax, example, recovery]
+    error_optional_fields: [artifact_id, entry_number, stable_id, details, valid_values]
+  exit_codes:
+    invalid_input: 2
+    operational_failure: 1
+  classes:
+    invalid_request:
+      exit_class: invalid_input
+      use_for: malformed syntax, missing selector, invalid limit, or invalid cursor format
+    unsupported_artifact:
+      exit_class: invalid_input
+      use_for: artifact outside scope.supported_artifacts
+    not_found:
+      exit_class: operational_failure
+      use_for: requested stable ID has no available current or archive record
+    ambiguous:
+      exit_class: operational_failure
+      use_for: multiple legacy candidates or conflicting identities prevent safe selection
+    corrupt:
+      exit_class: operational_failure
+      use_for: malformed YAML, invalid envelope, hash mismatch, unsafe path, symlink, or duplicate identity
+    incomplete:
+      exit_class: operational_failure
+      use_for: a requested complete record is represented only by an irrecoverable legacy summary
+    immutable_conflict:
+      exit_class: operational_failure
+      use_for: same stable ID has different canonical content; existing bytes remain untouched
+    cursor_invalid:
+      exit_class: invalid_input
+      use_for: token is malformed, bound to another artifact, or bound to different filters
+    cursor_snapshot_unavailable:
+      exit_class: operational_failure
+      use_for: the original snapshot cannot be reproduced exactly
+    project_boundary:
+      exit_class: invalid_input
+      use_for: path resolution would leave the selected project root
+    unsupported_state:
+      exit_class: operational_failure
+      use_for: state format is outside the declared compatibility authority
+  guidance_rule: >-
+    Every failure includes the valid command syntax, a concrete example, and a
+    recovery action. A failure must not silently downgrade a complete record,
+    retry an invalid cursor as a fresh listing, or invent missing history.
+
+compatibility:
+  classifications: [complete, degraded, blocked, unsupported]
+  dimensions:
+    local_read: local project state and numbered archive availability
+    detail: whether full record fields are available without inference
+    git_durability: optional committed-history evidence only; never a write prerequisite
+  cases:
+    new:
+      classification: complete
+      local_read: complete
+      detail: complete
+      git_durability: optional
+      behavior: numbered archive is canonical; current projection is bounded
+    legacy_full:
+      classification: degraded
+      local_read: complete
+      detail: complete
+      git_durability: unavailable_until_migrated
+      behavior: full inline current/legacy entry is usable, but provenance declares noncanonical storage and migration-needed
+    legacy_summary:
+      classification: degraded
+      local_read: complete
+      detail: incomplete
+      git_durability: optional
+      behavior: summary and retained fields are usable; missing fields stay missing and are never reconstructed
+    non_git:
+      classification: complete
+      local_read: complete
+      detail: based_on_local_records
+      git_durability: unavailable
+      behavior: local archive reads and writes remain supported; no Git operation is attempted
+    shallow:
+      classification: degraded
+      local_read: complete_when_local_records_validate
+      detail: based_on_local_records
+      git_durability: history_unavailable
+      behavior: do not claim historical recovery beyond reachable local records
+    ambiguous:
+      classification: blocked
+      local_read: affected_identity_blocked
+      detail: not_safe_to_select
+      git_durability: not_evaluated
+      behavior: preserve candidates and require explicit disambiguation; never choose by recency or Git guess
+    corrupt:
+      classification: blocked
+      local_read: affected_record_blocked
+      detail: not_trusted
+      git_durability: not_evaluated
+      behavior: reject the affected record, preserve its bytes for diagnostics, and continue only with independently valid records
+    unsupported:
+      classification: unsupported
+      local_read: unsupported
+      detail: unavailable
+      git_durability: not_evaluated
+      behavior: identify the unsupported artifact or format and return valid supported values
+  precedence: corrupt > ambiguous > unsupported > degraded > complete
+  no_reconstruction: >-
+    Compatibility reports provenance and availability only. It does not
+    reconstruct missing decision fields, promote summaries to full records, or
+    use Git history to satisfy a current source contract.
+
+budgets:
+  schema_version: agentera.stateOutputBudget.v1
+  measurement:
+    encoding: UTF-8
+    bytes: serialized byte length after encoding, including the final newline
+    json_serializer: JSON.stringify(value, null, 2) plus newline
+    yaml_serializer: YAML.stringify(value) as emitted by the CLI
+    measure_before_emit: true
+  list:
+    max_utf8_bytes: 32768
+    benchmark:
+      small:
+        entries: 100
+        max_latency_ms: 5000
+        max_heap_delta_bytes: 67108864
+      large:
+        entries: 1000
+        max_latency_ms: 15000
+        max_heap_delta_bytes: 268435456
+      response_max_utf8_bytes: 32768
+    index_decision:
+      decision: no_index
+      trigger: >-
+        Defer a persistent index until the large fixture exceeds any declared
+        latency, heap, or response threshold on a reproducible authority test.
+  projection:
+    max_utf8_bytes: 32768
+    applies_to: current, summary, and migration result responses
+    required_when_over_budget: [omitted, omitted_count, omission_reason, retrieval]
+    omission_semantics: >-
+      Remove optional detail entries in deterministic numeric order from the
+      response, retain required identity/count/source fields, and expose a next
+      retrieval pointer. Never split UTF-8, truncate a scalar, or silently drop
+      an entry. If required/source fields themselves exceed the budget, emit a
+      measured minimal degraded envelope with projection output-budget error
+      metadata rather than returning an over-budget payload.
+  startup:
+    source_manifest: scripts/json_output_surface_manifest.yaml
+    source_work:
+      schema_version: agentera.startupSourceWorkBudget.v1
+      measurement: >-
+        Count current projection entry rows and archive files inspected by the
+        source-side metadata query. Full archive records are never retained by
+        startup consumers.
+      small:
+        max_current_entries: 100
+        max_archive_files: 100
+        max_latency_ms: 5000
+        max_heap_delta_bytes: 67108864
+      large:
+        max_current_entries: 1000
+        max_archive_files: 1000
+        max_latency_ms: 15000
+        max_heap_delta_bytes: 268435456
+      serialized_output:
+        prime_capability_context_max_utf8_bytes: 50000
+    surfaces:
+      prime_briefing:
+        manifest_id: prime-briefing
+        max_utf8_bytes: 35000
+      prime_dashboard:
+        manifest_id: prime-dashboard
+        max_utf8_bytes: 35000
+      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.
+  validation:
+    authority: this file plus the referenced JSON surface manifest
+    drift_rule: tests fail if manifest IDs or byte values disagree with this contract