agentera 3.0.0-dev.25 → 3.0.0-dev.27

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

@@ -16,13 +16,11 @@ authority:
   implementation_boundary: >-
     Shared entity storage plus the progress, decisions, health, plan, objective,
     experiment, TODO-item, and documentation-inventory family writers and retrieval,
-    plus one-way Git cutover, are implemented but activate entity authority only
+    plus one-way forward import, are implemented but activate entity authority only
     from the durable cutover marker. The preserved
     singleton families remain legacy files. The
-    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.
+    current numbered archive and retrieval groups remain migration input while
+    that marker is absent; no independent legacy repair mutation remains.
 
 entity_target:
   status: progress_decisions_health_plan_objective_experiment_todo_and_docs_implemented_other_families_declared
@@ -300,7 +298,7 @@ entity_target:
     - boundary: plan_task
       artifact: plan
       independently_mutable: true
-      relationships: [plan, depends_on_tasks]
+      relationships: [plan, depends_on_tasks, superseded_by]
       implementation: implemented
       publication: replace_owned_entity
       record:
@@ -416,6 +414,10 @@ entity_target:
         field: depends_on
         target: plan_task
         cardinality: zero_or_many_same_plan
+      - source: plan_task
+        field: superseded_by
+        target: plan_task
+        cardinality: zero_or_many_same_plan
       - source: experiment
         field: objective
         target: objective
@@ -452,7 +454,7 @@ entity_target:
     - 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
+    status: 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
@@ -491,7 +493,7 @@ entity_target:
       never truncate bytes, omit required identity, or fabricate detail.
 
 entity_migration:
-  status: one_way_git_cutover_implemented
+  status: one_way_forward_import_implemented
   decision: 94
   kind: single_full_upgrade_cutover
   cutover_marker:
@@ -504,6 +506,12 @@ entity_migration:
     invalid_behavior: fail_without_fallback
     detection: read_only
     publication_owner: development_channel_v2_to_v3_upgrade
+    selection: >-
+      Project state and CLI installation state are independent dimensions. A v3
+      CLI selects this cutover for recognized marker-absent v2 aggregate state
+      whether the CLI runs from a self-contained npm package or a source
+      checkout. Pending v1 Markdown state and marker-absent state with no
+      recognized v2 entity input are rejected with manual recovery instructions.
   invocation:
     explicit_apply: full_upgrade_yes_only
     dry_run: optional_read_only_preview
@@ -515,9 +523,10 @@ entity_migration:
     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
+      Full upgrade serializes through the project writer lock, validates the
+      deterministic conversion, writes each missing canonical entity or accepts
+      an exact existing match, validates the complete graph, and writes the
+      authority marker last. There is no direct
       entity apply, public operation ID, resume, rollback, or cross-major restore.
     git_preflight:
       required: true
@@ -542,20 +551,21 @@ entity_migration:
         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.
+        A rerun recomputes the deterministic conversion from unchanged Git-bound
+        source, accepts existing canonical targets only when their bytes match,
+        writes the first missing target, validates the complete graph, and finishes
+        the marker forward. It never deletes or replaces canonical entities.
       completed: >-
         A valid entity marker makes legacy authority permanently inactive.
         Repeated upgrade validates current entity state and reports a no-op;
         normal entity writes may evolve records without reopening cutover.
       preflight: >-
         Upgrade plans artifact normalization, entity readiness, runtime work,
-        and cleanup read-only before any selected apply function runs. Any
-        blocker prevents every selected effect.
+        and cleanup read-only before any selected apply function runs. A detect,
+        artifact, or entity blocker prevents entity publication and activation.
+        Runtime or cleanup blockers do not prevent valid entity activation; their
+        resources remain untouched and are reported after the marker as
+        action-required work.
       phase_filters: >-
         Every --only apply is invalid during a v2-to-v3 boundary. Read-only
         filtered preview may remain available.
@@ -568,7 +578,7 @@ entity_migration:
         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
+      empty_state: unsupported_unknown_source_with_manual_handoff
       existing_entity_state: validate_then_no_op
   source_scope:
     included_entities: entity_target.entities
@@ -614,8 +624,7 @@ entity_migration:
       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.
+       preserves the deterministic mapping in each canonical target path.
     preview_digest: >-
       SHA-256 over canonical JSON of the complete unbounded inventory, proposed
       mapping, authority-validated final envelope byte SHA-256 values,
@@ -626,7 +635,7 @@ entity_migration:
       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
+       defensively by upgrade apply and forward retry. A target failure is a corrupt blocker tied
       to its source identity and recovery action; preserved nonentity residues are
       excluded from target validation and publication.
     output:
@@ -656,9 +665,9 @@ entity_migration:
       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.
+       Before any apply effect, recompute the complete preview and require its
+       source fingerprint and preview digest to match the Git-pinned preparation.
+       A mismatch refuses every selected effect.
   source_outcomes:
     valid_full:
       outcome: ready
@@ -692,30 +701,18 @@ entity_migration:
       - 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
+    persisted_recovery_state: none
+    publication_order: exact_or_missing_entities_then_graph_validation_then_marker
+    retry_rule: accept_exact_targets_and_continue_at_first_missing_path
+    divergent_target: stop_without_replacement_and_name_first_unresolved_path
+    forbidden_fields: [operation_id, migration_id, snapshots, source_bytes, inode_receipts, rollback_state]
     historical_evidence: >-
       Already committed .agentera/migrations content is inert and remains
       byte-for-byte untouched. Read-only legacy manifest parsing is retained only
       for public validation of entity markers created by the former cutover.
     fault_test_hook: >-
       Tests may set NODE_ENV=test and
-      AGENTERA_FAULT_INJECT_ENTITY_MIGRATION_AFTER_PHASE to one declared durable
+      AGENTERA_FAULT_INJECT_ENTITY_MIGRATION_AFTER_PHASE to one declared publication
       phase. Other environments ignore the variable.
   lifecycle:
     - phase: inventory
@@ -727,12 +724,9 @@ entity_migration:
     - 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
+      exit: every canonical target is an exact match or is published once
     - phase: entities_published
       mutates: false
       exit: canonical source-to-target parity, uniqueness, ownership, relationships, and budgets pass
@@ -1623,406 +1617,12 @@ api:
       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
+  entity_migration_discovery:
+    command: agentera state migrate entities --project PATH --dry-run --format json
+    implementation: implemented
+    read_only: true
+    writes: forbidden
+    authority: entity_migration.read_only_preview
   cursor:
     syntax: opaque TOKEN returned as response.next_cursor
     first_page: omit --cursor to establish a snapshot

package/bundle/references/cli/agent-ready-state-contract.yaml

@@ -70,21 +70,21 @@ doctor:
   compatibility_alias: forbidden
   owns:
     - Agentera CLI self-check status
-    - installed bundle status
-    - install-root status
-    - runtime adapter availability and configuration diagnostics
-    - hook, package, and schema availability checks when implemented
+    - installed app and install-root status
+    - canonical shared-skill diagnosis
+    - project integration and project-state migration diagnostics
+    - bounded offline smoke checks when requested
   excludes:
     - project artifact health
     - codebase quality audit findings
     - inspektera architecture, test, dependency, or documentation audit output
   adjacent_surfaces:
     codebase_audit: /agentera audit routes to inspektera
-    setup_specific_diagnostics: packages/cli/src/setup/doctor.ts
   rationale: >-
     Decision 45 rejects `bundle-status` as too narrow and rejects an alias for
-     release-clean vocabulary; `doctor` is the CLI/install/runtime self-check
-     vocabulary, while artifact health and codebase audits remain separate concerns.
+     release-clean vocabulary; `doctor` is the CLI, app, shared-skill, and project
+     integration self-check vocabulary, while artifact health and codebase audits
+     remain separate concerns.
 schema:
   status: implemented_runtime_introspection
   command: schema
@@ -237,7 +237,7 @@ structured_output:
         - project_integration
         - attention
         - history
-        - runtime_lifecycle
+        - shared_skill
         - decision_attention
         - next_action
         - orchestration_context
@@ -575,7 +575,7 @@ field_selection:
         - project_integration
         - attention
         - history
-        - runtime_lifecycle
+        - shared_skill
         - decision_attention
         - next_action
         - orchestration_context

package/bundle/references/cli/app-lifecycle-vocabulary.yaml

@@ -25,10 +25,9 @@ scope:
     - Update channel names, dist-tag resolution, and override keys.
     - General prose outside app lifecycle metadata.
 compatibility_boundary: >-
-  Compatibility identifiers such as `.agentera-bundle.json`, `bundle.status`,
-  `activeBundleRoot`, and `--only bundle` may remain until an explicit migration
-  exists. They do not make bundle/fresh/stale/refresh/fixed canonical app
-  lifecycle status vocabulary.
+  Retired v2 identifiers such as `.agentera-bundle.json`, `bundle.status`,
+  `activeBundleRoot`, and `--only bundle` may remain only in migration readers,
+  fixtures, and released history. They are not current app lifecycle vocabulary.
 canonical_status_order:
   - up_to_date
   - outdated