agentera 3.0.0-dev.4 → 3.0.0-dev.41

package/bundle/references/adapters/package-surface-characterization.md

@@ -1,48 +1,59 @@
-# Package Surface Characterization
-
-Characterized on 2026-05-06 before the PackageManifest registry migration. This file records current behavior only; it is not the registry design.
-
-The executable PackageManifest registry at `references/adapters/package-registry.yaml` and its loader `scripts/package_registry.py` now own the single source of truth for version surfaces, runtime package manifests, bundle surfaces, package commands, and docs targets. Validators, upgrade, and tests consume registry facts instead of duplicating constants.
-
-## Version-Bearing Surfaces
-
-`registry.json` is the persisted suite-version authority. The current suite version is `2.2.0` at `skills[0].version`.
-
-The current version-bearing surfaces are:
-
-| Surface | Kind | Current behavior |
-| --- | --- | --- |
-| `registry.json` | version-bearing surface | `skills[0].version` is the suite authority. |
-| `pyproject.toml` | version-bearing surface | `[project].version` matches the registry suite version. |
-| `plugin.json` | version-bearing surface and runtime package manifest | root Copilot manifest `version` matches the suite version. |
-| `.github/plugin/plugin.json` | version-bearing surface and runtime package manifest | repository Copilot manifest `version` matches the suite version. |
-| `.codex-plugin/plugin.json` | version-bearing surface and runtime package manifest | Codex manifest `version` matches the suite version. |
-| `.claude-plugin/marketplace.json` | version-bearing surface and runtime package manifest | `metadata.version` and every plugin entry version, including the legacy `hej` bridge, match the suite version. |
-| `.opencode/plugins/agentera.js` | version-bearing surface | `AGENTERA_VERSION` matches the registry suite version and drives the OpenCode command marker file `.agentera-version`. |
-
-`.opencode/package.json` is intentionally not version-bearing. Its current behavior is runtime package manifest behavior only: it keeps `type: "module"`, `main`/`exports` pointing at `./plugins/agentera.js`, `dependencies["@opencode-ai/plugin"] == "1.14.33"`, and an `agentera` npm-loadable plugin metadata block, but it has no top-level `name` or `version` field.
-
-## Package-Manager Command Surface
-
-Upgrade package planning currently emits package-manager commands only for Claude Code and OpenCode runtime selections.
-
-| Runtime | Action | Command argv | Skipped message | Dry-run behavior | Apply behavior with mocked command |
-| --- | --- | --- | --- | --- | --- |
-| `all` | `remove-legacy-skills` | `npx skills remove hej visionera resonera inspirera planera realisera inspektera optimera orkestrera visualisera dokumentera profilera -g -y` | `legacy skill removal skipped; pass --update-packages to run` | `--update-packages` without `--yes` leaves status `pending` and does not execute. | status becomes `applied`, message `package update completed`, and command result tails are recorded. |
-| `claude` | `install-agentera-skill` | `npx skills add jgabor/agentera -g -a claude-code --skill agentera -y` | `external package update skipped; pass --update-packages to run` | `--update-packages` without `--yes` leaves status `pending` and does not execute. | status becomes `applied`, message `package update completed`, and command result tails are recorded. |
-| `opencode` | `install-agentera-skill` | `npx skills add jgabor/agentera -g -a opencode --skill agentera -y` | `external package update skipped; pass --update-packages to run` | `--update-packages` without `--yes` leaves status `pending` and does not execute. | status becomes `applied`, message `package update completed`, and command result tails are recorded. |
-
-Write gating is preserved: `--update-packages` changes package items from `skipped` to `pending`, but package-manager commands execute only during apply mode behind `--yes`. Focused tests mock `subprocess.run`; no live package-manager call is part of this characterization.
-
-## Bundle And Docs Drift Inventory
-
-| Drift point | Surface class | Decision | Current behavior to preserve before migration |
-| --- | --- | --- | --- |
-| `pyproject.toml` force-includes and `scripts/agentera_upgrade.py` bundle lists duplicate the same shipped bundle directories and files. | bundle metadata surface | `standardize` | Keep both lists aligned now; later PackageManifest should own the list once. |
-| Lifecycle validation requires only the minimal shared runtime package paths (`skills`, `scripts`, `hooks`, `registry.json`, `plugin.json`, `pyproject.toml`, `README.md`) while pyproject and upgrade copy the larger distributable bundle. | runtime package manifest | `standardize` | Keep the validator as a minimum package-shape check now; later PackageManifest should separate minimal runtime metadata from full bundle includes. |
-| Runtime manifest `agentera.sharedPaths` includes `UPGRADE.md`, but `SUITE_BUNDLE_REQUIRED_PATHS` does not require it. | runtime package manifest | `standardize` | Keep current validator leniency now; later PackageManifest should make required shared paths explicit in one place. |
-| `.agentera/docs.yaml` `version_files` includes version-bearing surfaces and excludes `.opencode/package.json`. | version-bearing surface | `preserve` | Keep `.opencode/package.json` out of version checks because it is a runtime package manifest, not a suite version surface. |
-| `.opencode/package.json` is force-included and bundled, but it is not in docs `version_files`. | runtime package manifest | `preserve` | Keep packaging it without treating it as version-bearing. |
-| Upgrade package commands are represented as argv lists for Claude Code and OpenCode only; Codex and Copilot have runtime manifests but no package-manager command entries. | package-manager command surface | `preserve` | Keep command planning limited to currently managed package runtimes. |
-| `.claude-plugin/marketplace.json` carries a `hej` legacy bridge version alongside `agentera`. | version-bearing surface | `defer` | Keep the legacy bridge version aligned until a separate legacy-bridge removal or marketplace simplification task exists. |
-| Live package-manager behavior is not characterized by this task. | package-manager command surface | `defer` | Keep tests mocked; do not introduce live `npx skills` execution. |
+# Package surface characterization
+
+Current Agentera 3.0 package behavior is owned by
+`references/adapters/package-registry.yaml` and the TypeScript
+`PackageRegistry` loader. The package has two product surfaces: the CLI and the
+canonical shared skill.
+
+## Version matrix
+
+`registry.json` `skills[0].version` is the persisted suite authority. Tracked
+suite mirrors must match it exactly. The npm package `version` may carry a
+development pre-release suffix, but its `X.Y.Z` core must match the suite:
+
+| Surface | Selector |
+| --- | --- |
+| `packages/cli/package.json` | `version` (development pre-release) and `agentera.suiteVersion` (suite) |
+| `skills/agentera/SKILL.md` | frontmatter `version` |
+
+`packages/cli/package.json#agentera.gitRef` identifies the last substantive
+package-source commit, not a later verification-only commit. Repository-local
+release validation requires that commit to exist and compares the package
+contract, compiled-source inputs, scripts, and bundled-data inputs against it.
+Only the package version and `gitRef`, project state, and the release validator
+implementing this check are excluded, avoiding a circular source reference.
+
+## npm bundle
+
+Contributor construction, checkout-generation, and recovery behavior is owned
+by [`docs/packaging/v3-packaging.md`](../../docs/packaging/v3-packaging.md).
+
+The self-contained npm package ships `dist/` plus `bundle/`. Bundle data
+includes the canonical `skills/` tree, required `references/`, `registry.json`,
+the frozen routing evaluation corpus, and package guidance. Compiled commands
+ship in `dist/`. The shared-skill tree includes its capability schemas and artifact schemas.
+
+The package lane's isolated package fixture invokes `npm pack --json
+--ignore-scripts` after governed construction and fails if the CLI or required
+bundle data disappears, or if a current host-native descriptor/runtime path
+enters the package. Contributors use `pnpm -C packages/cli run pack:dry-run`;
+direct checkout packing remains rejected by the canonical packaging authority.
+
+## Publication adapters
+
+[`package-publication.json`](./package-publication.json) owns the shared
+repository publication transaction and distinguishes the development
+TypeScript package from the transitional stable shim. Both require separately
+prepared and committed version and `gitRef` metadata, explicit publication
+authority, a clean tree, exact registry convergence, safe exact-version replay,
+and bounded phase results. Development retains isolated construction and the
+`next` tag; stable retains shim tests/construction and the `latest` tag. Each
+adapter's only publication smoke is its non-mutating, no-project exact-version
+`--version` invocation, so publication does not absorb migration coverage.
+
+## Native package boundary
+
+The package registry defines no host-native manifest parity, package-manager
+command, runtime source tree, or native install command. Historical migration
+readers and fixtures remain source-only compatibility data; they do not create a
+current integration surface in the npm inventory.

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

@@ -0,0 +1,74 @@
+schema_version: agentera.runtimeLifecycleAdapters.v1
+status: migration_only_contract
+decision: 92
+authority: references/adapters/runtime-lifecycle-authority.yaml
+operation_contract: references/adapters/runtime-lifecycle-operation-contract.yaml
+categories:
+  - skills
+  - plugins
+  - hooks
+  - agents
+  - configuration
+  - enablement
+  - trust
+  - native_actions
+category_contract:
+  required_fields:
+    - capability
+    - evidence
+    - remediation
+  capabilities:
+    - repairable
+    - observable
+    - action_required
+    - unsupported
+    - unverified
+    - not_applicable
+  evidence_states:
+    - confirmed
+    - absent
+    - drifted
+    - shadowed
+    - denied
+    - unknown
+    - blocked_unowned
+    - unsupported
+    - not_applicable
+    - action_required
+  remediation_kinds:
+    - none
+    - repair
+    - action_required
+    - unavailable
+support_floor:
+  authority: references/adapters/runtime-lifecycle-authority.yaml#support_floor
+  required_category: skills
+  required_capability: repairable
+  unknown_or_unverified_required_detection_blocks: true
+  incomplete_required_diagnosis_blocks: true
+  unknown_or_missing_mandatory_evidence_blocks: true
+  denied_required_trust_blocks: true
+  known_false_presence_install_enable_is_diagnosed_degraded: true
+  not_applicable_only_for_unobserved_conditional_surface: true
+native_policy:
+  execution: forbidden
+  exact_action_required_only: true
+  install_update_enable_auth_trust_are_user_owned: true
+path_policy:
+  destination_templates_are_declarations: true
+  matching_ledger_required_for_existing_resources: true
+  equality_or_name_never_establishes_ownership: true
+  forbidden_destination_segments:
+    - cache
+    - caches
+    - cacheddata
+    - node_modules
+    - .npm
+    - .pnpm-store
+    - marketplace-cache
+known_caveats:
+  - Append-only ownership journal recovery accepts only a strict contiguous hash chain, ignores uniquely named non-authoritative publication temporaries, blocks malformed or disconnected final events, and re-observes every resource before retry.
+  - This contract is retained only for migration and minimum-cleanup readers; it declares no current runtime adapters or repository-native resources.
+shared_resources: []
+managed_resources: []
+adapters: []

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

@@ -0,0 +1,62 @@
+schema_version: agentera.runtimeLifecycleAuthority.v1
+status: migration_only_authority
+decision: 92
+operation_contract: references/adapters/runtime-lifecycle-operation-contract.yaml
+adapter_contract: references/adapters/runtime-lifecycle-adapters.yaml
+native_resource_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: []
+historical_inputs:
+  - id: claude
+    purposes:
+      - consent_gated_historical_import
+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: migration_only_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,97 @@
+schema_version: agentera.nativeResourceCleanup.v1
+status: resource_retirement_contract
+decision: nksvqmnevm
+authority: references/adapters/runtime-lifecycle-authority.yaml
+operation_contract: references/adapters/runtime-lifecycle-operation-contract.yaml
+policy:
+  host_inventory_exposure: evidence_only
+  selection: native_agentera_resource_only
+  preview: strictly_read_only
+  apply_requires: explicit_approval
+  ownership: matching_whole_resource_ledger_identity_and_fingerprint
+  shared_configuration: action_required_without_key_level_ownership
+  forbidden_ownership_evidence:
+    - value_equality
+    - managed_marker
+    - resource_name
+    - file_equality
+  unsupported_platform_result: action_required
+accepted_host_evidence:
+  - host: codex
+    state: supported
+    proof: Codex loaded Agentera's specific canonical skill instructions and bootstrap command.
+  - host: cursor
+    state: supported
+    proof: Cursor loaded Agentera's specific canonical skill instructions and bootstrap command.
+  - host: opencode
+    state: supported
+    proof: OpenCode's native CLI listed /home/jgabor/.agents/skills/agentera/SKILL.md.
+  - host: copilot
+    state: supported_disabled
+    proof: Copilot's native CLI listed the canonical personal-agents skill; its disabled state is intentional.
+hosts:
+  - id: codex
+    display_name: Codex
+    support_status: supported
+  - id: cursor
+    display_name: Cursor
+    support_status: supported
+  - id: opencode
+    display_name: OpenCode
+    support_status: supported
+  - id: copilot
+    display_name: Copilot
+    support_status: supported_disabled
+  - id: claude
+    display_name: Claude Code historical migration
+    support_status: retired_historical
+resources:
+  - id: claude.agentera-skill-link
+    host: claude
+    kind: symlink
+    intent: remove
+    destination: "{home}/.claude/skills/agentera"
+    ledger_status: legacy
+    durable_proof: matching whole-resource legacy ledger identity and fingerprint
+    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.
+  - id: codex.agent-descriptor
+    host: codex
+    kind: file
+    intent: remove
+    destination: "{home}/.codex/agents/{descriptor}.toml"
+    descriptors: [status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, orchestrate]
+    ledger_status: managed
+    durable_proof: matching whole-resource ledger identity and fingerprint for each declared descriptor file
+    safety_note: Each descriptor is an independently owned file. A managed marker, descriptor name, or matching content never establishes ownership.
+configuration_inventory:
+  - id: codex.config.shell_environment_policy.set.AGENTERA_HOME
+    host: codex
+    destination: "{home}/.codex/config.toml"
+    key: shell_environment_policy.set.AGENTERA_HOME
+    durable_proof: key-level ownership ledger identity and fingerprint
+    ownership_available: false
+    result_without_proof: action_required
+  - id: codex.config.agents.max_depth
+    host: codex
+    destination: "{home}/.codex/config.toml"
+    key: agents.max_depth
+    durable_proof: key-level ownership ledger identity and fingerprint
+    ownership_available: false
+    result_without_proof: action_required
+  - id: codex.config.features.multi_agent_v2
+    host: codex
+    destination: "{home}/.codex/config.toml"
+    key: features.multi_agent_v2
+    durable_proof: key-level ownership ledger identity and fingerprint
+    ownership_available: false
+    result_without_proof: action_required

package/bundle/references/analysis/benchmark.md

@@ -23,6 +23,10 @@ contract validators, and runtime smoke checks.
 | --- | --- | --- | --- |
 | Startup state benchmark | `mage bench:startupState` | Measures how often Agentera CLI state reads are followed by raw artifact access during startup/state gathering. | Manual only; forbidden in normal CI. |
 
+Verification ownership, independent owner commands, mixed-file separation
+markers, conservative routing, and named execution-policy compositions live in
+[`verification-policy.yaml`](./verification-policy.yaml).
+
 The startup benchmark is an optimization signal for Decision 51 and Decision 52.
 It does not implement a startup state envelope or change runtime behavior.
 
@@ -83,11 +87,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 +125,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