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

package/bundle/references/adapters/runtime-lifecycle-authority.yaml

@@ -0,0 +1,90 @@
+schema_version: agentera.runtimeLifecycleAuthority.v1
+status: active_authority
+decision: 92
+operation_contract: references/adapters/runtime-lifecycle-operation-contract.yaml
+adapter_contract: references/adapters/runtime-lifecycle-adapters.yaml
+retired_cleanup_contract: references/adapters/runtime-retired-resources.yaml
+canonical_skill:
+  path: ~/.agents/skills/agentera
+  required_for_support_floor: true
+projection_contract:
+  schema_version: agentera.runtimeLifecycleProjection.v1
+  snapshot_identity: deterministic_sha256
+  applicability:
+    - required
+    - conditional
+    - not_applicable
+  action_classes:
+    - repairable_owned
+    - manual_verification
+    - unobservable_gap
+  command_eligibility:
+    - preview
+    - apply
+    - manual
+    - diagnostic
+  shared_resource_rule: selected_and_required_by_at_least_one_selected_runtime
+evidence_contract:
+  mandatory_fields:
+    - host_present
+    - installed
+    - enabled
+    - trusted
+  values:
+    - true
+    - false
+    - unknown
+    - denied
+    - not_applicable
+  trust_policy: Trust is observed only; unknown trust must never be promoted to trusted.
+support_floor:
+  requirements:
+    - canonical_shared_skill_detected
+    - diagnosis_complete
+    - mandatory_evidence_resolved
+  evidence_rules:
+    unknown_or_missing_mandatory_blocks: true
+    denied_mandatory_trust_blocks: true
+    known_false_diagnoses_degraded:
+      - host_present
+      - installed
+      - enabled
+    not_applicable_scope: unobserved_conditional_surface_only
+  unmet_blocks_release: true
+active_runtimes:
+  - id: opencode
+    display_name: OpenCode
+    surfaces:
+      - id: host
+        display_name: OpenCode host
+        presence: required
+  - id: codex
+    display_name: Codex
+    surfaces:
+      - id: cli
+        display_name: Codex CLI
+        presence: required
+  - id: cursor
+    display_name: Cursor
+    surfaces:
+      - id: cli
+        display_name: Cursor Agent CLI
+        presence: required
+      - id: ide
+        display_name: Cursor IDE
+        presence: conditional
+  - id: copilot
+    display_name: GitHub Copilot
+    surfaces:
+      - id: cli
+        display_name: Copilot CLI
+        presence: required
+retired_runtime_inputs:
+  - id: claude
+    purposes:
+      - consent_gated_historical_import
+      - owned_legacy_resource_cleanup
+migration_aliases:
+  cursor-agent:
+    runtime_id: cursor
+    surface_id: cli

package/bundle/references/adapters/runtime-lifecycle-operation-contract.yaml

@@ -0,0 +1,84 @@
+schema_version: agentera.lifecycleOperationContract.v1
+status: active_contract
+decision: 92
+scope: runtime_neutral_filesystem_resources
+ownership:
+  manifest_schema: agentera.lifecycleOwnershipManifest.v1
+  ledger_schema: agentera.lifecycleOwnershipLedger.v1
+  owner: agentera
+  mutation_rule: A destination declaration is always required. Existing resources additionally require one matching whole-resource ledger record.
+  equality_rule: Content equality and resource names never establish ownership.
+  collision_rule: Pre-existing resources without matching ledger ownership are never replaced or removed.
+  identity_rule: Managed and published pending-create records bind the filesystem device and inode observed at publication.
+  removal_rule: Removal requires a matching whole-resource ledger identity and fingerprint, a pinned non-symlink parent, and Linux /proc/self/fd directory-relative access.
+  manual_review_guidance: The destination is not ledger-owned; review the collision manually. Agentera will not adopt it by name or equality.
+  interrupted_create_rule: A pending_create record may be finalized when its recorded identity and expected fingerprint match, or when the durable pre-create record survived and the exclusively declared resource is observed at the exact expected kind and fingerprint after restart.
+  journal_rule: Apply publishes fsynced append-only ledger snapshots atomically at final names and accepts only a contiguous sequence-one hash chain with no gaps, forks, duplicate sequences, digest mismatches, or disconnected events.
+  journal_statuses:
+    absent: No journal directory exists; preview remains zero-write and apply may publish sequence one.
+    clean: Every authoritative final event is complete, schema-valid, digest-valid, and connected; mutation may append the next sequence.
+    recoverable_terminal_tail: Exactly one syntactically incomplete final event follows the clean prefix with no successor; reads preserve the prefix but every mutation is blocked until the tail is resolved.
+    corrupt: Any malformed complete event, middle incomplete event, gap, fork, duplicate sequence, body or filename mismatch, digest mismatch, disconnection, or unsafe entry blocks every mutation.
+  recovery_rule: Restart ignores uniquely named non-authoritative publication temporaries, folds only the strict connected final chain, and re-observes each resource before retry; append never continues from a rolled-back prefix or past an unresolved final tail.
+resource_states:
+  - exact
+  - modified
+  - missing
+  - legacy
+  - symlinked
+  - wrong_type
+  - partial_managed
+  - unowned
+  - unsafe_path
+  - ambiguous_ownership
+plan_actions:
+  - create
+  - update
+  - remove
+  - finalize_ownership
+  - noop
+  - blocked_unowned
+  - action_required
+apply_results:
+  - applied
+  - noop
+  - failed
+  - blocked_unowned
+  - skipped_dependency
+  - action_required
+aggregate_rule: Required results other than applied or noop make the aggregate non_success.
+dependency_rule: Independent operations continue after failure. Dependents skip with their failed dependency IDs.
+retry_rule: Successful work replans to noop; pending and failed work retries from observed filesystem and ledger state.
+preview_policy:
+  mode: strictly_read_only
+  forbidden:
+    - filesystem mutation
+    - directory creation
+    - locks
+    - temporary target files
+    - ownership record writes
+    - caches
+    - telemetry
+    - native commands
+    - package managers
+    - authentication
+    - trust changes
+path_safety:
+  - Destinations must be absolute and contained by an explicit existing allowed root.
+  - Apply pins the allowed root and every parent through Linux /proc/self/fd, then revalidates directory identities at the final publication boundary.
+  - Parent symlink traversal, parent identity substitution, link-target escapes, target identity substitution, hard-linked files, wrong types, partial ownership, and ambiguous ownership require action or fail safely.
+publication_policy:
+  supported_platform: linux_proc_self_fd
+  unsupported_platform_result: action_required
+  apply_serialization: lifecycle apply prepares a complete fsynced uniquely named lock directory and atomically renames it into final position; a complete live preparation blocks contenders, and the immutable owner record binds token, PID, Linux boot ID, and /proc process start ticks.
+  lock_recovery: Malformed or incomplete final locks fail closed. A complete lock is stale only when boot ID or process start ticks prove that exact owner identity is gone; release verifies the full identity and token before removing the owner record and lock directory.
+  journal_publication: Event bytes are fsynced under a unique non-authoritative temporary name, hard-linked atomically to the exclusive final event name, and followed by directory fsync before temporary cleanup.
+  create_protocol: directory-relative exclusive no-follow creation with no sibling temporary path
+  owned_file_update_protocol: directory-relative no-follow open, ledger and observation identity match, descriptor-local fingerprint check, in-place descriptor write, and post-write path identity check
+  destructive_path_mutations: owned_removal_only
+  destructive_path_reason: Removal is limited to declared resources whose whole-resource ledger identity and fingerprint still match through a pinned parent; every weaker case fails closed.
+  cleanup_rule: Publication creates no sibling temporary entry and never unlinks a colliding or replaced path; approved cleanup may unlink only the validated owned resource.
+  crash_boundary: Creates and owned file updates preserve the never-overwrite-unowned invariant but are not promised crash-atomic; a recorded pending identity makes partial Agentera-created files retryable.
+native_policy:
+  install_update_auth_trust_operations: forbidden
+  trust_is_observed_only: true

package/bundle/references/adapters/runtime-retired-resources.yaml

@@ -0,0 +1,33 @@
+schema_version: agentera.retiredRuntimeResources.v1
+status: retired_migration_contract
+decision: 92
+authority: references/adapters/runtime-lifecycle-authority.yaml
+operation_contract: references/adapters/runtime-lifecycle-operation-contract.yaml
+policy:
+  active_inventory_exposure: forbidden
+  preview: strictly_read_only
+  apply_requires: explicit_approval
+  ownership: matching_whole_resource_legacy_ledger_identity_and_fingerprint
+  unsupported_platform_result: action_required
+retired_runtimes:
+  - id: claude
+    display_name: Claude Code historical migration
+    active_runtime: false
+    source_product: claude-code
+    resources:
+      - id: claude.agentera-skill-link
+        kind: symlink
+        intent: remove
+        destination: "{home}/.claude/skills/agentera"
+        ledger_status: legacy
+    never_touch:
+      - "{home}/.claude/projects"
+      - "{home}/.claude/statsig"
+      - "{home}/.claude/settings.json"
+      - "{home}/.claude/settings.local.json"
+      - "{home}/.claude.json"
+      - "{home}/.claude/cache"
+      - "{home}/.claude/caches"
+      - "{home}/.claude/conversations"
+      - "{home}/.claude/credentials"
+    safety_note: Only the declared Agentera skill symlink may be removed, and only when a matching legacy ownership ledger still binds its identity and target fingerprint. Transcript, settings, credential, conversation, stats, cache, and ambiguous paths are never cleanup targets.

package/bundle/references/analysis/benchmark.md

@@ -83,11 +83,11 @@ Status interpretation is intentionally split:
 | No matching records | `sparse` / `no_matching_records` | Candidate storage was readable and schema-compatible, but no supported records were extracted. Treat this as sparse coverage evidence. |
 | Successful zero-record window | `ok` / `records_extracted` with `record_count: 0` and `error_count: 0` | Extraction succeeded, but the incremental benchmark window has no records after the previous watermark. Treat this as compatible successful behavior. |
 
-Current known runtime caveats are extraction caveats, not CLI behavior evidence:
-`claude-code` is degraded by `schema_divergent` with 4836 candidates, 0 records,
-and 2 errors; `github-copilot` is degraded by `schema_divergent` with 1
-candidate, 0 records, and 1 error; `opencode` currently contributes records;
-`codex` can validly report `ok` with zero records and zero errors for an empty
+Known active-runtime caveats are extraction caveats, not CLI behavior evidence:
+`cursor` is degraded by `schema_divergent` with 4836 candidates, 0 records,
+and 2 errors; `copilot` is degraded by `schema_divergent` with 1 candidate,
+0 records, and 1 error; `opencode` currently contributes records; `codex` can
+validly report `ok` with zero records and zero errors for an empty
 incremental window.
 
 Runtime-store runs are incremental by default. The first run for a runtime scope
@@ -121,7 +121,7 @@ Follow this loop:
    by `raw_artifact_access_after_cli_counts` when the read is not redundant yet
    but still happens after a successful CLI state call.
 4. Map each repeated raw read to the CLI state owner. Prefer enriching existing
-   routine commands or the `hej` composite startup result. Do not add Decision 43
+    routine commands or the `prime` composite startup result. Do not add Decision 43
    slash-route aliases as CLI commands.
 5. Make CLI completeness explicit. A startup-capable response should say whether
    it is complete for the requested capability, whether raw artifact reads are

package/bundle/references/analysis/startup-measurement-contract.yaml

@@ -15,7 +15,7 @@ boundary:
   rule: include records with timestamps strictly after committed_at
 
 section_22_compatibility:
-  consumes_adapter_version: agentera-v2-corpus-1
+  consumes_adapter_version: agentera-v3-corpus-2
   required_record_families:
     - conversation_turn
     - tool_call
@@ -39,7 +39,9 @@ benchmark_execution:
   live_host_checks: forbidden_by_default
   runtime_path_approval: >-
     Running mage bench:startupState authorizes inspection of the documented
-    default runtime stores for codex, claude-code, opencode, and github-copilot.
+    default active-runtime stores for codex, cursor, opencode, and copilot.
+    Claude history is excluded unless the caller separately supplies
+    --import-source claude with its concrete local path.
     Custom runtime history sources must be supplied as exact runtime labels and
     concrete filesystem paths. A generic consent flag or runtime label without
     its concrete path is insufficient for custom sources.
@@ -59,10 +61,10 @@ benchmark_execution:
 
 runtime_extraction_contract:
   supported_runtime_order:
-    - codex
-    - claude-code
     - opencode
-    - github-copilot
+    - codex
+    - cursor
+    - copilot
   normalized_record_fields:
     required:
       - source_id
@@ -70,6 +72,9 @@ runtime_extraction_contract:
       - project_id
       - source_kind
       - runtime
+      - source_class
+      - source_product
+      - active_runtime
       - adapter_version
       - data
     optional:
@@ -90,16 +95,16 @@ runtime_extraction_contract:
         parsing encountered schema errors. This is extraction failure evidence,
         not a successful zero-record benchmark window.
       required_counts:
-        - candidate_count when discovery can count candidates
+        - file_count when discovery can count store files
         - record_count, which may be zero or partial
         - error_count greater than zero
       current_examples:
-        - runtime: claude-code
-          candidate_count: 4836
+        - runtime: cursor
+          file_count: 4836
           record_count: 0
           error_count: 2
-        - runtime: github-copilot
-          candidate_count: 1
+        - runtime: copilot
+          file_count: 1
           record_count: 0
           error_count: 1
     no_matching_records:
@@ -110,7 +115,7 @@ runtime_extraction_contract:
         shape, but no supported message or tool records were extracted. This is
         sparse coverage evidence and remains distinct from schema divergence.
       required_counts:
-        - candidate_count when discovery can count candidates
+        - file_count when discovery can count store files
         - "record_count: 0"
         - no error_count greater than zero
     successful_zero_record_window:
@@ -127,7 +132,7 @@ runtime_extraction_contract:
         - runtime: codex
           record_count: 0
           error_count: 0
-  supported_runtimes:
+  source_products:
     codex:
       accepted_input_schema_classes:
         - JSONL session files containing session_meta or turn_context records
@@ -146,6 +151,9 @@ runtime_extraction_contract:
         - Do not retain cwd, project_path, store_path, file_path, raw session ids, or generated salted hashes.
         - Retain only canonical runtime labels, canonical artifact labels, bounded counts, and aggregate status fields.
     claude-code:
+      source_class: historical_import
+      active_runtime: false
+      inclusion_rule: explicit --import-source claude only; excluded from default active-runtime metrics
       accepted_input_schema_classes:
         - JSONL project session files with top-level role or type user/assistant events
         - JSONL message objects with nested message.role plus content/text/message content variants
@@ -180,6 +188,9 @@ runtime_extraction_contract:
         - Do not retain SQLite file paths, project paths, transcript text, raw session ids, or generated salted hashes.
         - Retain only canonical runtime labels, canonical artifact labels, bounded counts, and aggregate status fields.
     github-copilot:
+      runtime: copilot
+      source_class: active_runtime
+      active_runtime: true
       accepted_input_schema_classes:
         - SQLite session-store.db with sessions and turns tables
         - session id columns id, session_id, or sessionID
@@ -312,8 +323,8 @@ state_gathering_sequence:
   start_anchor: first_agentera_state_call_after_capability_related_user_turn
   capability_invocation_markers:
     - slash route such as /agentera plan or /agentera build
-    - bare capability name such as planera, resonera, or orkestrera
-    - natural-language capability mention such as run orkestrera
+    - bare capability name such as plan, discuss, or orchestrate
+    - natural-language capability mention such as run orchestrate
     - assistant capability intro marker
   end_anchors:
     - first_implementation_boundary
@@ -324,7 +335,7 @@ state_gathering_sequence:
 
 counted_event_classes:
   - class: cli_state_call
-    description: Agentera state CLI reads such as hej, todo, docs, plan, progress, decisions, health, and query.
+    description: Agentera state CLI reads such as prime, todo, docs, plan, progress, decisions, health, and query.
   - class: raw_artifact_access
     description: Direct read, grep, or glob access to Agentera state artifacts after CLI state access.
   - class: capability_prose_read
@@ -362,17 +373,17 @@ privacy_boundary:
     - canonical_event_class
     - salted_non_reconstructable_hash
   canonical_artifact_labels:
-    TODO.md: TODO.md
-    CHANGELOG.md: CHANGELOG.md
-    DESIGN.md: DESIGN.md
-    PLAN.md: PLAN.md
-    PROGRESS.md: PROGRESS.md
-    DOCS.md: DOCS.md
-    DECISIONS.md: DECISIONS.md
-    HEALTH.md: HEALTH.md
-    VISION.md: VISION.md
-    OBJECTIVE.md: OBJECTIVE.md
-    EXPERIMENTS.md: EXPERIMENTS.md
+    todo: todo
+    changelog: changelog
+    design: design
+    plan: plan
+    progress: progress
+    docs: docs
+    decisions: decisions
+    health: health
+    vision: vision
+    objective: objective
+    experiments: experiments
     AGENTS.md: AGENTS.md
     SKILL.md: SKILL.md
     AGENTERA_ARTIFACTS: AGENTERA_ARTIFACTS

package/bundle/references/artifacts/artifact-registry-interface-model.yaml

@@ -89,7 +89,7 @@ record:
       owns:
         - global profile artifact
         - plan archive artifact
-        - optimera harness path
+        - optimize harness path with optimera read compatibility
         - objective-scoped path placeholders
         - global/local/project-root/project-agent-state distinctions
       required_fields:
@@ -185,7 +185,7 @@ required_artifact_identities:
   objective_scoped:
     - artifact_id: objective
       display_name: OBJECTIVE.md
-      default_path: .agentera/optimera/<name>/objective.yaml
+      default_path: .agentera/optimize/<name>/objective.yaml
       path_template:
         placeholder: <name>
         meaning: active objective directory name
@@ -193,7 +193,7 @@ required_artifact_identities:
           - <objective-name>
     - artifact_id: experiments
       display_name: EXPERIMENTS.md
-      default_path: .agentera/optimera/<name>/experiments.yaml
+      default_path: .agentera/optimize/<name>/experiments.yaml
       path_template:
         placeholder: <name>
         meaning: active objective directory name
@@ -204,9 +204,10 @@ explicit_special_cases:
     display_name: PROFILE.md
     artifact_type: global_user_state
     scope: global_user_state
-    default_path: $PROFILERA_PROFILE_DIR/PROFILE.md
+    default_path: $AGENTERA_PROFILE_DIR/PROFILE.md
     path_template:
       env_precedence:
+        - AGENTERA_PROFILE_DIR
         - PROFILERA_PROFILE_DIR
         - XDG_DATA_HOME/agentera
         - ~/.local/share/agentera
@@ -220,11 +221,11 @@ explicit_special_cases:
       placeholder: '{date}'
       meaning: archive date or archive-safe plan suffix
     docs_yaml_can_override_path: false
-  - artifact_id: optimera_harness
+  - artifact_id: optimize_harness
     display_name: harness
     artifact_type: local_harness
     scope: local_harness
-    default_path: .agentera/optimera/<name>/harness
+    default_path: .agentera/optimize/<name>/harness
     path_template:
       placeholder: <name>
       meaning: active objective directory name
@@ -235,11 +236,11 @@ explicit_special_cases:
     display_name: benchmark_context
     artifact_type: cli_context
     scope: cli_context
-    default_path: agentera prime --context optimera --format json#benchmark_context
+    default_path: agentera prime --context optimize --format json#benchmark_context
     producers:
       - agentera
     consumers:
-      - optimera
+      - optimize
     docs_yaml_can_override_path: false
 consumer_permissions:
   cross_capability_validator: