agentera 3.0.0-dev.22 → 3.0.0-dev.25

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

@@ -1,24 +1,744 @@
 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.
+  Define both the implemented bounded-retrieval contracts for current state and
+  the Decision 94 target entity and cutover contracts. The target declaration is
+  authoritative before its storage, writer, retrieval, and migration behavior is
+  implemented; implementation status is explicit at each boundary.
 authority:
   source: references/artifacts/state-storage-authority.yaml
   single_source_rule: >-
     Runtime readers, writers, validators, tests, help, and capability source
     contracts may project this authority but must not create a second map of
     archive paths, API verbs, compatibility classes, mutable overlay fields,
-    failure classes, or byte limits.
+    amendment revision paths, legacy label coexistence rules, 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.
+    Shared entity storage plus the progress, decisions, health, plan, objective,
+    experiment, TODO-item, and documentation-inventory family writers and retrieval,
+    plus one-way Git cutover, are implemented but activate entity authority only
+    from the durable cutover marker. The preserved
+    singleton families remain legacy files. The
+    current numbered archive and retrieval groups remain implemented legacy
+    authority while that marker is absent. The maintenance-only Git backfill
+    surface declared by api.backfill remains a separate legacy repair operation
+    and is not the Decision 94 cutover.
+
+entity_target:
+  status: progress_decisions_health_plan_objective_experiment_todo_and_docs_implemented_other_families_declared
+  decision: 94
+  activation: >-
+    This target becomes active persisted and structured state authority only
+    after entity_migration publishes a validated entity graph and writes the marker
+    last. Before then, legacy aggregates
+    remain migration input and explicitly labelled migration-evidence writer state;
+    ordinary public reads fail with migration_required instead of exposing them.
+  implementation_status:
+    progress: implemented
+    decisions: implemented
+    health: implemented
+    plan: implemented
+    objective: implemented
+    experiments: implemented
+    todo: implemented
+    docs: implemented
+    remaining_families: declared_not_implemented
+    rule: >-
+      Every implemented family selects entity behavior only when the durable
+      cutover marker is valid. Marker-absent ordinary consumers fail with
+      migration_required; the read-only migration preview and readiness checks do
+      not create entity state or write both authorities.
+  public_schema:
+    canonical_identity_field: id
+    canonical_classification_field: artifact
+    identity_and_classification_fields: [id, artifact]
+    entity_envelope:
+      required_fields: [id, artifact, record]
+      additional_identity_or_classification_fields: forbidden
+    forbidden_canonical_aliases:
+      - stable_id
+      - artifact_id
+      - entry_number
+      - number
+      - task_number
+      - experiment_number
+      - plan_id
+      - objective_id
+      - type_prefixed_id
+    exemptions:
+      - historical prose and immutable historical evidence
+      - internal TypeScript variable names that are not persisted or public structured output
+      - current pre-cutover contracts explicitly marked as implemented legacy authority
+  public_retrieval:
+    schema_version: agentera.entityPublicRetrieval.v1
+    status: final
+    commands:
+      progress:
+        list: agentera state progress list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state progress get --id ID --format json
+      decisions:
+        list: agentera state decisions list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state decisions get --id ID --format json
+      health:
+        list: agentera state health list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state health get --id ID --format json
+      plans:
+        list: agentera state plan list [--status open|complete|archived] [--limit N] [--cursor TOKEN] --format json
+        get: agentera state plan get --id ID --format json
+      plan_tasks:
+        list: agentera state plan tasks list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state plan tasks get --id ID --format json
+      objective:
+        list: agentera state objective list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state objective get --id ID --format json
+      experiments:
+        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] --format json
+        get: agentera state experiments get --id ID --format json
+      todo:
+        list: agentera state todo list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state todo get --id ID --format json
+      docs:
+        list: agentera state docs list [--limit N] [--cursor TOKEN] --format json
+        get: agentera state docs get --id ID --format json
+    collections:
+      - { artifact: progress, identity: id, classification: artifact }
+      - { artifact: decisions, identity: id, classification: artifact }
+      - { artifact: health, identity: id, classification: artifact }
+      - { artifact: plan, boundary: plan, identity: id, classification: artifact }
+      - { artifact: plan, boundary: plan_task, identity: id, classification: artifact }
+      - { artifact: objective, identity: id, classification: artifact }
+      - { artifact: experiments, identity: id, classification: artifact }
+      - { artifact: todo, identity: id, classification: artifact }
+      - { artifact: docs, identity: id, classification: artifact }
+  identity:
+    scope: project_wide_across_all_entity_artifacts
+    alphabet: abcdefghijklmnopqrstuvwxyz
+    length: 10
+    accepted_pattern: '^[a-z]{10}$'
+    example: qjtrmnpvka
+    allocation: random_from_declared_alphabet
+    collision_rule: retry before publication; an existing ID is never reassigned or overwritten
+    prohibited_components: [prefix, sequence, timestamp, branch, writer, git_reference]
+    meaning_rule: >-
+      The ID is opaque and carries no artifact or entity-boundary information;
+      artifact is the sole public classification field.
+  storage_boundary:
+    rule: one independently mutable entity per writer-owned canonical file
+    aggregate_authority: forbidden
+    shared_primitives:
+      status: implemented
+      canonical_root: .agentera/entities
+      canonical_path_template: .agentera/entities/<artifact>/<boundary>/<id>.yaml
+      path_components: [artifact, boundary, id]
+      extension: .yaml
+      publication: exclusive_immutable_file
+      publication_context:
+        scope: shared_by_all_entity_families
+        binding: validated_project_root_and_exact_cutover_marker_snapshot
+        lifetime: mode_detection_through_writer_lock_and_final_publication_validation
+        pathname_race_contract: >-
+          Entity publication is rooted through held directory descriptors. The
+          root and exact valid marker identity and bytes are revalidated before
+          each directory, stage, and immutable-link boundary and after durable
+          publication before success. Because Node cannot make pathname
+          validation and mutation one kernel operation, a detected substitution
+          rolls back only attempt-owned links, stages, and empty directories by
+          pinned identity; final failure retains no attempt-owned entity state.
+        marker_change_after_detection: conflict_without_legacy_fallback
+        successor_preservation: never_remove_unmatched_or_unrelated_identity
+      allocation: provisional_candidate_until_publication
+      project_wide_id_claim:
+        synchronization: .agentera/.writer.lock
+        critical_section: final_project_wide_scan_through_durable_publication
+        interrupted_writer_recovery: dead_process_lock_reclamation
+        persistent_reservation: none
+      identical_replay: idempotent
+      replay_equality: recursive_key_sorted_logical_content_with_array_order_preserved
+      divergent_same_id: reject_without_overwrite
+      state_validation:
+        canonical_command: agentera check validate state
+        mutates: false
+        failure_exit: nonzero
+        diagnostics: bounded_structured_with_exact_recovery
+    same_entity_conflict: >-
+      Concurrent divergent edits to one entity remain an ordinary explicit file
+      conflict or validation conflict; no runtime silently selects a winner.
+    unrelated_entity_merge: >-
+      Independently created or changed entities occupy distinct canonical files
+      so ordinary Git can preserve both changes.
+  entities:
+    - boundary: progress_cycle
+      artifact: progress
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      record:
+        required_fields: [timestamp, type, phase, what, context]
+        required_paths: [context.intent]
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+        temporal_fields: [timestamp]
+        timestamp_format: 'YYYY-MM-DD HH:MM'
+      retrieval:
+        exact: agentera state progress get --id ID --format json
+        list: agentera state progress list [--limit N] [--cursor TOKEN] --format json
+        ordering: timestamp_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: decision
+      artifact: decisions
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: immutable
+      record:
+        required_fields: [date, question, context, alternatives, choice, reasoning, confidence]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, satisfaction]
+      retrieval:
+        exact: agentera state decisions get --id ID --format json
+        list: agentera state decisions list [--limit N] [--cursor TOKEN] --format json
+        ordering: date_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: decision_satisfaction
+      artifact: decisions
+      independently_mutable: true
+      relationships: [decision]
+      implementation: implemented
+      publication: replace_owned_entity
+      ownership: { fields: [decision], cardinality: zero_or_one }
+      record:
+        required_fields: [decision, state]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+    - boundary: decision_revision
+      artifact: decisions
+      independently_mutable: true
+      includes: [amendment]
+      relationships: [decision]
+      implementation: implemented
+      publication: immutable
+      ownership: { fields: [decision, base_sha256], cardinality: zero_or_one }
+      record:
+        required_fields: [decision, date, provenance, base_sha256, changes]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, satisfaction]
+    - boundary: health_audit
+      artifact: health
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: immutable
+      record:
+        required_fields: [date, dimensions, findings_summary, trajectory, grades]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+      retrieval:
+        exact: agentera state health get --id ID --format json
+        list: agentera state health list [--limit N] [--cursor TOKEN] --format json
+        ordering: date_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+      repair: >-
+        Canonical health audit entities are immutable and cannot be row-deduplicated.
+        Malformed envelopes, duplicate IDs, or conflicting ownership fail before effects
+        and recover through agentera check validate state; no repair event is fabricated.
+    - boundary: plan
+      artifact: plan
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [header, what, why, scope]
+        required_paths: [header.title, header.created, header.status]
+        forbidden_fields: [id, artifact, stable_id, plan_id, tasks, previous_plan_archived]
+        field_shapes:
+          scope:
+            type: mapping
+            required_fields:
+              included: string_list
+              excluded: string_list
+            optional_fields:
+              deferred: string_list
+            additional_fields: forbidden
+            legacy_source_normalization: >-
+              A block-style, non-flow, exactly-one-pair mapping used directly as
+              an included, excluded, or deferred sequence item is the historical
+              block-colon string encoding and normalizes to one `key: value`
+              string only when both source nodes are string scalars. Explicit
+              flow mapping syntax never normalizes and remains invalid under the
+              canonical validator. A deliberate block single-pair mapping is
+              syntactically indistinguishable from the legacy encoding and falls
+              under this source-form rule; no semantic intent is inferred.
+      retrieval:
+        exact: agentera state plan get --id ID --format json
+        list: agentera state plan list [--limit N] [--cursor TOKEN] --format json
+        ordering: created_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: plan_task
+      artifact: plan
+      independently_mutable: true
+      relationships: [plan, depends_on_tasks]
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [plan, name, status, depends_on, acceptance]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, task_number, stable_id, plan_id]
+    - boundary: objective
+      artifact: objective
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [header, objective, metric, baseline, scope]
+        required_paths: [header.title, header.status, objective.description, objective.measurement]
+        forbidden_fields: [id, artifact, stable_id, objective_id]
+      retrieval:
+        exact: agentera state objective get --id ID --format json
+        list: agentera state objective list [--limit N] [--cursor TOKEN] --format json
+        ordering: created_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: experiment
+      artifact: experiments
+      independently_mutable: true
+      relationships: [objective]
+      implementation: implemented
+      publication: immutable
+      baseline:
+        field: status
+        value: baseline
+        cardinality: exactly_one_when_experiments_exist
+      record:
+        required_fields: [objective, date, label, hypothesis, method, change, metric, regression, status, conclusion]
+        required_paths: [objective, date, label, status]
+        forbidden_fields: [id, artifact, number, experiment_number, stable_id, objective_id]
+      retrieval:
+        exact: agentera state experiments get --id ID --format json
+        list: agentera state experiments list --objective ID [--limit N] [--cursor TOKEN] --format json
+        ordering: date_desc_then_id_asc
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: todo_item
+      artifact: todo
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [severity, status, description]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number, path]
+      retrieval:
+        exact: agentera state todo get --id ID --format json
+        list: agentera state todo list [--limit N] [--cursor TOKEN] --format json
+        ordering: severity_then_status_then_id
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+    - boundary: documentation_inventory_entry
+      artifact: docs
+      independently_mutable: true
+      relationships: []
+      implementation: implemented
+      publication: replace_owned_entity
+      record:
+        required_fields: [document, path, last_updated, status]
+        required_paths: []
+        forbidden_fields: [id, artifact, number, stable_id, artifact_id, entry_number]
+      retrieval:
+        exact: agentera state docs get --id ID --format json
+        list: agentera state docs list [--limit N] [--cursor TOKEN] --format json
+        ordering: path_then_id
+        default_limit: 20
+        maximum_limit: 100
+        max_utf8_bytes: 32768
+        cursor: opaque_snapshot_cursor
+        mutation_after_snapshot: cursor_snapshot_unavailable
+        omission: whole_entries_only_with_count_reason_continuation_and_exact_get
+        scalar_truncation: forbidden
+  relationships:
+    representation: bare target entity ID in the named record field
+    integrity: every non-null target must resolve to exactly one entity with the declared target boundary
+    unresolved_behavior: whole-state validation and migration cutover fail without creating a target
+    declarations:
+      - source: decision_satisfaction
+        field: decision
+        target: decision
+        cardinality: exactly_one
+      - source: decision_revision
+        field: decision
+        target: decision
+        cardinality: exactly_one
+      - source: plan_task
+        field: plan
+        target: plan
+        cardinality: exactly_one
+      - source: plan_task
+        field: depends_on
+        target: plan_task
+        cardinality: zero_or_many_same_plan
+      - source: experiment
+        field: objective
+        target: objective
+        cardinality: exactly_one
+  views:
+    authority: non_authoritative_cli_rendering
+    mutation: forbidden
+    source: canonical entity files only after cutover
+    requirements:
+      - bounded lists expose id and artifact and provide exact get by id
+      - ordering and cursors bind to an explicit snapshot and never imply identity
+      - omissions expose counts, reasons, and exact retrieval commands
+      - nested plan/task and objective/experiment views are relationship projections
+      - startup views use the same entities and may omit detail only under declared budgets
+  intentional_singletons:
+    exhaustive: true
+    additions_require_authority_amendment: true
+    boundaries:
+      - boundary: vision
+        reason: one project north star; excluded from execution-cycle mutation
+      - boundary: design
+        reason: one project visual identity editorial artifact
+      - boundary: changelog
+        reason: one ordered release-history editorial artifact
+      - boundary: profile
+        reason: one reusable decision-profile document per selected profile
+      - boundary: runtime_local_session_state
+        reason: runtime-local and not canonical project entity state
+      - boundary: docs_mapping
+        reason: one project path and documentation-policy mapping, distinct from documentation inventory entries
+    conflict_rule: concurrent edits remain explicit whole-document conflicts
+  excluded_from_entity_migration:
+    - all intentional_singletons
+    - immutable historical prose and evidence, except structured references explicitly declared for rewrite
+    - genuinely singleton editorial artifacts added by an authority amendment
+  measurement_contract:
+    status: target_gate_not_yet_implemented
+    environment: Linux, Node.js 22 or newer, one cold CLI process per sample
+    fixtures:
+      small: 100 valid entities distributed across every declared entity boundary
+      large: 1000 valid entities distributed across every declared entity boundary
+      relationship_rule: every declared relationship has at least one valid fixture edge
+    sampling:
+      repetitions: 5
+      pass_rule: every repetition stays within every applicable limit
+      elapsed: wall-clock milliseconds from process start through complete serialized output
+      heap: process heapUsed peak minus heapUsed before fixture discovery
+      bytes: UTF-8 byte length of stdout including the trailing newline
+    targets:
+      exact_get:
+        max_latency_ms: 1000
+        max_heap_delta_bytes: 67108864
+        max_utf8_bytes: 1048576
+      bounded_list_small:
+        max_latency_ms: 5000
+        max_heap_delta_bytes: 67108864
+        max_utf8_bytes: 32768
+      bounded_list_large:
+        max_latency_ms: 15000
+        max_heap_delta_bytes: 268435456
+        max_utf8_bytes: 32768
+      startup_small:
+        max_latency_ms: 5000
+        max_heap_delta_bytes: 67108864
+        serialized_limits: budgets.startup.surfaces
+      startup_large:
+        max_latency_ms: 15000
+        max_heap_delta_bytes: 268435456
+        serialized_limits: budgets.startup.surfaces
+    failure_rule: >-
+      Over-budget results fail the target gate. They may return a measured
+      degraded envelope only where the referenced budget permits omission; they
+      never truncate bytes, omit required identity, or fabricate detail.
+
+entity_migration:
+  status: one_way_git_cutover_implemented
+  decision: 94
+  kind: single_full_upgrade_cutover
+  cutover_marker:
+    path: .agentera/state-mode.yaml
+    schema_version: agentera.stateMode.v1
+    entity_mode:
+      schemaVersion: agentera.stateMode.v1
+      mode: entities
+    absent_mode: legacy
+    invalid_behavior: fail_without_fallback
+    detection: read_only
+    publication_owner: development_channel_v2_to_v3_upgrade
+  invocation:
+    explicit_apply: full_upgrade_yes_only
+    dry_run: optional_read_only_preview
+    ordinary_reads_migrate: false
+    ordinary_writes_migrate: false
+    apply_invokes_git: true
+    read_only_command: >-
+      npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+    apply_command: >-
+      npx -y agentera@next upgrade --channel development --project "$PWD" --yes
+    apply_boundary: >-
+      Full upgrade serializes through the project writer lock, stages and graph-
+      validates deterministic entities, publishes them without deleting a
+      canonical entity, and writes the authority marker last. There is no direct
+      entity apply, public operation ID, resume, rollback, or cross-major restore.
+    git_preflight:
+      required: true
+      project_root: exact_worktree_root
+      source: HEAD_commit
+      checkout: no_staged_modified_renamed_or_untracked_paths_except_exact_cutover_outputs
+      migration_inputs: regular_tracked_files_whose_bytes_and_executable_mode_match_HEAD
+      absent_input: absent_from_HEAD_and_worktree
+      ignored_or_untracked_input: refuse
+      verification: >-
+        Planning and apply resolve the current HEAD commit and prove every present
+        migration input is a safe regular tracked path whose bytes and executable
+        mode match that commit. Apply repeats the proof under the writer lock
+        before its first effect. Non-Git projects and dirty or unsupported source
+        state are refused before any selected upgrade effect.
+    upgrade_composition:
+      owner: development_channel_v2_to_v3_upgrade
+      selected_with: [full]
+      apply_consent: >-
+        The upgrade --yes consent derives all source and target bindings in
+        process. Users provide no hashes, approval files, migration IDs, --force,
+        or additional cutover consent. Any --only apply is rejected at this
+        cross-major boundary.
+      interruption: >-
+        Before forward-manifest publication, a rerun may discard only the fixed
+        migration-owned staging path and recompute it from the same Git-bound
+        source. After manifest or canonical publication, a rerun validates the
+        manifest binding and every existing canonical target, republishes only
+        missing targets from recomputed staging, validates the graph, and finishes
+        the marker forward. It never deletes canonical entities.
+      completed: >-
+        A valid entity marker makes legacy authority permanently inactive.
+        Repeated upgrade validates current entity state and reports a no-op;
+        normal entity writes may evolve records without reopening cutover.
+      preflight: >-
+        Upgrade plans artifact normalization, entity readiness, runtime work,
+        and cleanup read-only before any selected apply function runs. Any
+        blocker prevents every selected effect.
+      phase_filters: >-
+        Every --only apply is invalid during a v2-to-v3 boundary. Read-only
+        filtered preview may remain available.
+      legacy_projection: >-
+        Canonical v2 YAML and already-resolved v1 conversions are inventoried
+        directly. A pending v1 Markdown conversion is not projected through a
+        prerequisite write during planning and therefore blocks the composed
+        apply before effects.
+      lifecycle_normalization: >-
+        Deterministic legacy plan lifecycle normalization is part of entity
+        projection during cutover. Upgrade retains the original legacy YAML as
+        source and recovery evidence instead of rewriting it first.
+      empty_state: valid_empty_initialization
+      existing_entity_state: validate_then_no_op
+  source_scope:
+    included_entities: entity_target.entities
+    included_structured_relationships: entity_target.relationships.declarations
+    preserved_singletons: entity_target.intentional_singletons.boundaries
+    sources: >-
+      Current canonical files, verified immutable archives, overlays, revisions,
+      and validated source evidence are inventoried together without changing
+      their pre-cutover authority. Every present input must be recoverable from
+      the pinned Git commit.
+    recovered_projection_correlation: >-
+      Every archive carrying recovery_provenance must match the immutable
+      .agentera/archive/recovery/projection-correlation.yaml recovery set by
+      identity, archive bytes, final record SHA-256, parent/child Git proof or
+      legacy converter/source proof, current projection bytes, and overlay.
+      Missing, changed, new, replaced, or unlisted recovery evidence blocks.
+  internal_migration_diagnostic: true
+  read_only_preview:
+    implementation: implemented
+    ordering: artifact_then_boundary_then_source_identity_then_source_path
+    filter: complete_declared_inventory
+    source_fingerprint: >-
+      SHA-256 over canonical JSON containing every declared source path's
+      project-relative name, presence, byte length, byte SHA-256, permission
+      mode, regular-file type, device, and inode from one verified open
+      descriptor. Missing declared roots are represented explicitly with null
+      identity. No mtime, Git value, or cache participates.
+    project_root: >-
+      The selected root must exist, be a directory, and resolve without a
+      symbolic-link root or symbolic-link traversal. Failure is structured and
+      occurs before inventory or effects.
+    recursive_roots: >-
+      Every declared archive and objective inventory root is lstat-validated
+      before traversal and again when recursion enters it. Existing symbolic
+      links and non-directories are project-bound inventory failures; their
+      targets are never inventoried.
+    authority_binding: >-
+      The preview records the active state-storage authority schema version and
+      byte SHA-256. The complete preview digest includes both values, so any
+      authority-only change invalidates approval before an apply effect.
+    proposed_id: >-
+      Preview-only ten-letter candidates are deterministically allocated from a
+      domain-separated SHA-256 of the complete source fingerprint and canonical
+      source key. This is allocation of a new opaque target candidate, not
+      reconstruction of a missing source ID. A collision is a blocker. Apply
+      preserves the deterministic mapping in staged canonical paths and the
+      bounded forward manifest before canonical publication.
+    preview_digest: >-
+      SHA-256 over canonical JSON of the complete unbounded inventory, proposed
+      mapping, authority-validated final envelope byte SHA-256 values,
+      relationship rewrite map, counts, blockers, and source
+      fingerprint plus the project selector, complete-source filter, declared
+      order, and migration-authority binding before output omission.
+    target_validation: >-
+      Before preview can be ready or produce an approvable digest, every proposed
+      final envelope, record, public field vocabulary, and relationship graph is
+      validated through the same authority-backed canonical target validator used
+      defensively by upgrade apply and forward continuation. A target failure is a corrupt blocker tied
+      to its source identity and recovery action; preserved nonentity residues are
+      excluded from target validation and publication.
+    output:
+      max_utf8_bytes: 32768
+      default_limit: 100
+      maximum_limit: 1000
+      omission: whole entries and diagnostics only
+      scalar_truncation: forbidden
+      required_omission_fields: [omitted, omitted_count, omission_reason, retrieval]
+      recovery: >-
+        --after SOURCE_IDENTITY advances from the last whole logical identity
+        returned only when accompanied by that page's --source-fingerprint and
+        --preview-digest. The digest binds the project selector, complete-source
+        filter, authority-declared order, migration authority, and complete
+        source snapshot. Any mismatch refuses continuation with a command that
+        omits --after and restarts from the current snapshot. Diagnostics travel
+        with their owning entry, so repeated use of retrieval.command recovers
+        every later omitted entry and diagnostic.
+    counts:
+      physical_records: every observed record before identity grouping
+      logical_identities: every source identity after grouping
+      mirrors: excess canonical-identical physical records grouped under one logical identity
+      duplicates: excess divergent physical records claiming one logical identity
+      conflicts: logical identities with divergent candidates plus proposed-target collisions
+    zero_write: >-
+      Inventory, preview, malformed-input handling, and source-binding checks
+      open no writer or upgrade lock and create no directory, temporary file,
+      mapping, snapshot, journal, cache, or state file.
+    binding: >-
+      Before any apply effect, recompute the complete preview and require its
+      source fingerprint and preview digest to match the Git-pinned preparation
+      or retained forward manifest. A mismatch refuses every selected effect.
+  source_outcomes:
+    valid_full:
+      outcome: ready
+      rule: map one complete validated source entity and every relationship exactly once
+    canonical_mirror:
+      outcome: ready_with_mirrored_provenance
+      rule: group canonical-identical physical records as one logical identity and retain every provenance class
+    degraded_recoverable:
+      outcome: ready_with_provenance
+      rule: admit only independently validated full detail and record its recovery provenance
+    summary_only_or_missing_detail:
+      outcome: blocked
+      rule: retain evidence and stop before publication; never reconstruct omitted fields
+    ambiguous_or_duplicate_identity:
+      outcome: blocked
+      rule: retain every candidate and require explicit disposition; never choose by order or recency
+    proposed_target_conflict:
+      outcome: blocked
+      rule: retain every colliding logical identity and allocate no winner
+    corrupt_or_unresolved_relationship:
+      outcome: blocked
+      rule: report the exact source and recovery action; never publish a partial graph
+    unsupported:
+      outcome: blocked
+      rule: preserve bytes and report the unsupported source contract
+  non_fabrication:
+    forbidden:
+      - synthetic entities for missing source detail
+      - inferred IDs from order, numbers, paths, timestamps, branches, writers, or Git references
+      - guessed relationship targets
+      - silent dropping, deduplication, or winner selection
+    partial_cutover_success: forbidden
+  forward_state:
+    root: .agentera/migrations/entities
+    staging: .agentera/migrations/entities/staging
+    manifest: .agentera/migrations/entities/forward.yaml
+    manifest_schema_version: agentera.entityCutoverManifest.v1
+    manifest_fields: [schemaVersion, phase, source, targets, marker]
+    source_fields: [head, source_fingerprint, preview_digest]
+    target_fields: [path, sha256]
+    marker_fields: [path, sha256]
+    phases: [publishing_entities, entities_published]
+    forbidden_fields:
+      - operation_id
+      - migration_id
+      - snapshots
+      - source_bytes
+      - inode_receipts
+      - rollback_state
+    publication_order: staging_then_forward_manifest_then_entities_then_marker
+    historical_evidence: >-
+      Already committed .agentera/migrations content is inert and remains
+      byte-for-byte untouched. Read-only legacy manifest parsing is retained only
+      for public validation of entity markers created by the former cutover.
+    fault_test_hook: >-
+      Tests may set NODE_ENV=test and
+      AGENTERA_FAULT_INJECT_ENTITY_MIGRATION_AFTER_PHASE to one declared durable
+      phase. Other environments ignore the variable.
+  lifecycle:
+    - phase: inventory
+      mutates: false
+      exit: every source entity and relationship is classified
+    - phase: preview
+      mutates: false
+      exit: proposed graph, mapping, outcomes, blockers, and digest are complete
+    - phase: git_preflight
+      mutates: false
+      exit: project root, HEAD, clean checkout, source bytes, types, and modes match
+    - phase: stage_entities
+      mutates: true
+      exit: deterministic entity bytes and graph validate under the fixed staging path
+    - phase: publishing_entities
+      mutates: true
+      exit: one bounded forward manifest exists and every canonical target matches or is published once
+    - phase: entities_published
+      mutates: false
+      exit: canonical source-to-target parity, uniqueness, ownership, relationships, and budgets pass
+    - phase: marker
+      mutates: true
+      exit: one durable marker activates entity_target and retires writable legacy authority
 
 scope:
   supported_artifacts:
@@ -421,7 +1141,7 @@ consumer_matrix:
   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
+    get: agentera state <artifact> get --id ID --format json
     policy: >-
       Use the bounded prime context first, then the bounded state list for
       discovery and exact state get for requested detail. Raw artifact or Git
@@ -600,7 +1320,7 @@ identity:
     accepted_pattern: '^(progress|decisions|health):[1-9][0-9]*$'
     example: decisions:53
   components:
-    artifact_id: one of scope.supported_artifacts.artifact_id
+    artifact_id: one of the supported artifact values declared by scope
     entry_number: positive integer from the artifact's entry_number_field
   uniqueness: stable_id is unique within one project archive
   ordering:
@@ -716,6 +1436,67 @@ overlays:
     inference: forbidden from commits, downstream references, summaries, or Git history
     protected_review: unresolved decisions remain visible and never block archive storage
 
+revisions:
+  location: .agentera/revisions/decisions.yaml
+  project_root_fixed: true
+  docs_yaml_override: forbidden
+  schema_version: agentera.decisionRevision.v1
+  supported_artifact: decisions
+  identity_key: decisions:<decision-number>
+  storage_shape: >-
+    A mapping keyed by stable decision ID. Each value is an ordered list of
+    immutable revision records carrying only authority-declared amendable
+    content paths plus revision provenance. A revision never replaces the
+    immutable numbered archive record and never replaces the satisfaction
+    overlay; it is additional immutable evidence composed at read time.
+  amendable_paths:
+    - question
+    - context
+    - alternatives
+    - choice
+    - reasoning
+    - confidence
+    - feeds_into
+  identity_paths:
+    - number
+  temporal_paths:
+    - date
+  separation_from_overlay: >-
+    Amendments never touch satisfaction overlay paths. Satisfaction updates
+    remain under overlays; content amendments remain under revisions. Each
+    authority composes its own evidence and neither rewrites the other.
+  immutability: >-
+    Original numbered archive records remain immutable historical evidence.
+    Revisions are additional immutable evidence appended in declared order;
+    no revision overwrites, reorders, or deletes a prior revision. A revision
+    is byte-stable after publication and an identical revision is an
+    idempotent replay.
+  provenance: >-
+    Revision evidence carries revision provenance only. It is never labeled
+    as historical archive provenance. A revision bootstrapped from a complete
+    legacy projection record may carry degraded_projection provenance and
+    never historical_archive provenance.
+  publication_order:
+    - validate_target_identity
+    - validate_amendment_vocabulary
+    - stage_revision
+    - publish_revision
+    - update_effective_projection
+  apply_state: implemented
+  apply_state_note: >-
+    The revision authority and amend command publish record-local amendments
+    with recovery. A valid dry-run reports the exact revision, effective record,
+    and projection effect without writing any file. Apply writes a
+    record-local override to the revision document only (preserving unrelated
+    entries' bytes), retries converge on a stable revision identity, and an
+    identical re-submission is an idempotent replay. The decisions projection
+    is never rewritten by an amendment; effective detail composes
+    base→revisions→overlay. Amend execution still refuses before side effects
+    for an unsafe target-only change, a duplicate-revision conflict, a stale
+    base hash, or an unsafe target identity, returning an actionable retry or
+    repair action. Discover the contract with
+    `agentera state decisions explain --verb amend --format json`.
+
 projections:
   archive:
     role: complete immutable historical detail
@@ -817,10 +1598,12 @@ api:
     empty_result: status=ok with entries=[] and counts.total=0; absence is not an error
   durability:
     command: agentera check durability [--project PATH] [--artifact ARTIFACT] [--number N] [--limit N] --format json
+    entity_command: agentera check durability --project PATH --artifact ARTIFACT --id ID --format json
     formats: [text, json, yaml]
     selectors:
       artifact: optional supported numbered archive artifact ID
       number: optional positive entry number; requires artifact
+      id: entity-mode bare entity ID; requires artifact and replaces number after cutover
       limit: optional bounded result count
     default_limit: 100
     maximum_limit: 100
@@ -1369,6 +2152,26 @@ compatibility:
     Compatibility reports provenance and availability only. It does not
     reconstruct missing decision fields, promote summaries to full records, or
     use Git history to satisfy a current source contract.
+  legacy_label_coexistence:
+    dimensions:
+      - confidence
+    current_vocabulary: [firm, provisional, exploratory]
+    current_vocabulary_ref: protocol.yaml DECISION_LABELS (DL1-DL3)
+    known_legacy_examples: [high, medium, low]
+    classification_rule: >-
+      A label value is unsupported when it is not in current_vocabulary. An
+      unsupported inherited label on a record the caller did not touch is
+      explicit legacy state: it is preserved byte- and value-semantically,
+      reported as a legacy caveat, never coerced to the current vocabulary,
+      and never blocks an append, satisfaction update, or amend on a
+      different target. A confidence label supplied by append or amend is new
+      or amended content and must be a current_vocabulary value; otherwise the
+      operation rejects before side effects.
+    no_silent_normalization: >-
+      Unsupported inherited labels are never rewritten to current values
+      without explicit user migration consent. Reads classify them as legacy
+      and never silently promote them to current vocabulary or claim stronger
+      provenance than exists.
 
 budgets:
   schema_version: agentera.stateOutputBudget.v1
@@ -1425,14 +2228,29 @@ budgets:
         max_latency_ms: 15000
         max_heap_delta_bytes: 268435456
       serialized_output:
-        prime_capability_context_max_utf8_bytes: 50000
+        # Generic prime capability capsules retain the full instructions body.
+        # The status capability is a separate one-call surface with a stricter
+        # bound declared below and in the JSON surface manifest.
+        prime_capability_context_max_utf8_bytes: 55000
+        prime_status_context_max_utf8_bytes: 25000
     surfaces:
       prime_briefing:
         manifest_id: prime-briefing
-        max_utf8_bytes: 35000
+        # Bounded default decision brief (Plan Task 3): the bare default
+        # `agentera prime --format json` projects the full orientation payload
+        # to routing-essential leaves plus named recovery pointers for omitted
+        # rich state. Pretty UTF-8 JSON + trailing newline is measured and an
+        # over-budget brief is rejected in favor of a bounded degraded envelope;
+        # diagnostics stay on stderr. prime_dashboard keeps full fidelity.
+        max_utf8_bytes: 12000
       prime_dashboard:
         manifest_id: prime-dashboard
         max_utf8_bytes: 35000
+      prime_status_context:
+        manifest_id: prime-status-context
+        # Status startup includes the full instructions capsule as well as the
+        # bounded Task 3 decision brief. Diagnostics remain on stderr.
+        max_utf8_bytes: 25000
       prime_sparse:
         manifest_id: prime-fields-sparse
         max_utf8_bytes: 28000
@@ -1441,6 +2259,15 @@ budgets:
       Omit optional historical detail and retain counts, actionable IDs,
       compatibility, source_contract, and exact get/list command pointers. The
       caller must be able to distinguish omitted detail from unavailable detail.
+      The bare default briefing is a bounded decision brief: every required
+      top-level field stays present (content projected to routing-essential
+      leaves), missing versus present-but-empty stays distinguishable through
+      state_presence, and each omitted rich-state family carries a named
+      authoritative recovery command. When even the projected brief exceeds the
+      budget, emit a measured bounded degraded envelope that keeps command,
+      status, mode, state_presence, a brief source_contract, and the
+      byte-budget error with a recovery command; never emit an over-budget
+      payload. Diagnostics are measured on stderr separately.
   validation:
     authority: this file plus the referenced JSON surface manifest
     drift_rule: tests fail if manifest IDs or byte values disagree with this contract