agentera 3.0.0-dev.7 → 3.0.0-dev.74

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

@@ -1,47 +1,81 @@
-# Package Surface Characterization
+# 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.
+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.
 
-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 matrix
 
-## Version-Bearing Surfaces
+`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:
 
-`registry.json` is the persisted suite-version authority. The current suite version is `2.2.0` at `skills[0].version`.
+| Surface | Selector |
+| --- | --- |
+| `packages/cli/package.json` | `version` (development pre-release) and `agentera.suiteVersion` (suite) |
+| `skills/agentera/SKILL.md` | frontmatter `version` |
 
-The current version-bearing surfaces are:
+`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.
 
-| 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 the bundled `agentera` plugin entry version 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`. |
+## npm bundle
 
-`.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.
+Contributor construction, checkout-generation, and recovery behavior is owned
+by [`docs/packaging/v3-packaging.md`](../../docs/packaging/v3-packaging.md).
 
-## Package-Manager Command Surface
+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.
 
-Upgrade package planning currently emits package-manager commands only for Claude Code and OpenCode runtime selections.
+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.
 
-| 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. |
+`bootstrap_command_authority` closes the command-guidance inventory. Markdown,
+YAML, and JSON bundle surfaces are parsed and scanned in source and extracted
+package layouts. Other files need a path-specific reason, and unused exemption
+paths fail. Generated declarations compare `id`, `path`, `format`,
+`classification`, and reason exactly before the generated package file is
+parsed. Constructor inventory uses conservative reverse static import and
+re-export closure instead of local value-flow guesses. Every module in that
+closure is classified exactly once as an emitted producer or an explicit
+non-producer with a reason; dynamic module consumers, parse ambiguity, stale
+declarations, and bounded traversal fail closed. Aggregate outputs are scanned
+separately. This avoids a blind scan of compiled JavaScript while still
+checking generated behavior.
 
-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.
+## Publication adapters
 
-## Bundle And Docs Drift Inventory
+[`package-publication.json`](./package-publication.json) owns the shared
+repository publication transaction and distinguishes the development
+TypeScript package from the transitional stable shim. Normal development CI
+derives version and `gitRef` metadata in isolated construction without changing
+the checkout. Manual development recovery and stable publication retain their
+separate prepared metadata paths. Both adapters require explicit publication
+authority, a clean tree, exact registry convergence, safe exact-version replay,
+and bounded phase results. Development uses 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.
 
-| 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. |
-| 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. |
+## 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.
+
+## Maintenance
+
+- Maintainer: Agentera CLI maintainers
+- Source checkout root: `.`
+- Working directory: `.`
+- Command: `pnpm -C packages/cli run pack:dry-run`

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