agentera 3.0.0-dev.3 → 3.0.0-dev.31

package/bundle/references/adapters/package-manifest-interface-model.yaml

@@ -2,19 +2,16 @@ interface: PackageManifest
 status: implemented
 implemented_by: references/adapters/package-registry.yaml
 intent: >
-  Define the package and release-surface access Interface before introducing an
-  executable registry Module. This model records ownership boundaries and the
-  validation contract for future PackageManifest records. The executable registry
-  at references/adapters/package-registry.yaml and its loader scripts/package_registry.py
-  now implement this interface; this model remains the authoritative design contract.
+  Define the self-contained Agentera package as the TypeScript CLI plus one
+  canonical shared skill and its required contracts. Host-native manifests,
+  runtime source trees, and native installation commands are not package
+  surfaces.
 record:
   required_groups:
     - identity
     - version_authority
     - version_surfaces
-    - runtime_package_manifests
     - bundle_surfaces
-    - package_commands
     - docs_targets
     - release_policy
   groups:
@@ -23,7 +20,7 @@ record:
       owns:
         - package id
         - suite name
-        - skill path
+        - canonical shared-skill path
         - capability count expectation
       required_fields:
         id: string
@@ -44,54 +41,59 @@ record:
     version_surfaces:
       type: object
       owns:
-        - version-bearing repository surfaces
+        - CLI and shared-skill version surfaces
         - version extraction selectors
-        - non-version surface exclusions
       required_fields:
         surfaces: list[object]
-        excluded_runtime_manifests: list[repo_relative_path]
-    runtime_package_manifests:
-      type: object
-      owns:
-        - runtime package manifest paths
-        - runtime package shape expectations
-        - shared package path expectations
-      required_fields:
-        manifests: list[object]
-        shared_paths_policy: string
     bundle_surfaces:
       type: object
       owns:
-        - bundled directories
-        - bundled files
+        - canonical bundled directories
+        - canonical bundled files
+        - generated bundled files
         - bundle skip rules
-        - bundle mismatch standardization target
       required_fields:
-        directories: list[repo_relative_path]
-        files: list[repo_relative_path]
+        directories: list[object]
+        files: list[object]
+        generated_files: list[generated_bundle_file]
         skip_parts: list[string]
         skip_suffixes: list[string]
-    package_commands:
-      type: object
-      owns:
-        - package-manager command specifications
-        - package command action names
-        - package command runtime scope
-        - package write-gate preservation
-      required_fields:
-        commands: list[object]
-        safety: object
+      entry_contracts:
+        directory_and_file:
+          applies_to:
+            - directories
+            - files
+          required_fields:
+            - id
+            - path
+          allowed_fields:
+            - id
+            - path
+          field_types:
+            id: string
+            path: repo_relative_path
+          uniqueness:
+            id: global_across_directories_and_files
+            path: global_across_directories_and_files
+          path_format: normalized_relative_posix
+          forbidden_path_forms:
+            - posix_absolute
+            - windows_absolute_or_drive_prefixed
+            - backslash
+            - dot_or_dot_dot_segment
+            - leading_dot_slash
+            - trailing_separator
+            - noncanonical_posix_normalization
+      value_authority: references/adapters/package-registry.yaml records[*].bundle_surfaces
     docs_targets:
       type: object
       owns:
         - docs version targets
         - docs index targets for package surfaces
-        - non-version docs exclusions
       required_fields:
         version_files_source: string
         version_files: list[repo_relative_path]
         index_targets: list[repo_relative_path]
-        excluded_version_files: list[repo_relative_path]
     release_policy:
       type: object
       owns:
@@ -111,11 +113,11 @@ ownership:
     access_interface: PackageManifest
     rule: >
       registry.json remains the persisted suite-version authority. PackageManifest
-      becomes the typed access Interface for consumers after migration, unless an
-      explicit future ADR changes persisted authority.
+      is the typed access interface unless an explicit future ADR changes that
+      authority.
     future_authority_change_requires: explicit ADR
   install_root_delegated:
-    owner: scripts/install_root.py
+    owner: packages/cli/src/state/installRoot.ts
     forbidden_in_package_manifest:
       - AGENTERA_HOME precedence
       - default app home
@@ -123,215 +125,3 @@ ownership:
       - stale classification
       - unmanaged classification
       - app-home diagnostics
-  runtime_adapter_delegated:
-    owner: scripts/runtime_adapter_registry.py
-    forbidden_in_package_manifest:
-      - runtime discovery
-      - lifecycle events
-      - artifact validation hooks
-      - config target paths
-      - runtime diagnostics
-      - documentation claims
-command_safety:
-  argv_only: true
-  approved_executables:
-    - npx
-  approved_actions:
-    - remove-legacy-skills
-    - install-agentera-skill
-  approved_runtimes:
-    - all
-    - claude
-    - opencode
-  approved_runtime_agents:
-    - claude-code
-    - opencode
-  approved_package_tool:
-    executable: npx
-    command_namespace: skills
-    actions:
-      - remove
-      - add
-  cleanup_actions:
-    - remove-legacy-skills
-  runtime_install_actions:
-    - install-agentera-skill
-  gates:
-    update_packages_required_to_plan: true
-    yes_required_to_execute: true
-    preserve_existing_write_gates: true
-sample_manifest:
-  identity:
-    id: agentera
-    name: agentera
-    skill_path: skills/agentera
-    expected_capabilities: 12
-  version_authority:
-    persisted_authority: registry.json
-    selector: skills[0].version
-    access_interface: PackageManifest
-    future_authority_change_requires: explicit ADR
-  version_surfaces:
-    surfaces:
-      - id: registry
-        path: registry.json
-        selector: skills[0].version
-      - id: python-project
-        path: pyproject.toml
-        selector: project.version
-      - id: copilot-root
-        path: plugin.json
-        selector: version
-      - id: copilot-repository
-        path: .github/plugin/plugin.json
-        selector: version
-      - id: codex-plugin
-        path: .codex-plugin/plugin.json
-        selector: version
-      - id: claude-marketplace-metadata
-        path: .claude-plugin/marketplace.json
-        selector: metadata.version
-      - id: claude-marketplace-plugins
-        path: .claude-plugin/marketplace.json
-        selector: plugins[*].version
-      - id: opencode-plugin-marker
-        path: .opencode/plugins/agentera.js
-        selector: AGENTERA_VERSION
-    excluded_runtime_manifests:
-      - .opencode/package.json
-  runtime_package_manifests:
-    manifests:
-      - runtime: copilot
-        path: plugin.json
-        version_bearing: true
-        package_shape: suite-bundle
-      - runtime: copilot
-        path: .github/plugin/plugin.json
-        version_bearing: true
-        package_shape: suite-bundle
-      - runtime: codex
-        path: .codex-plugin/plugin.json
-        version_bearing: true
-        package_shape: suite-bundle
-      - runtime: claude
-        path: .claude-plugin/marketplace.json
-        version_bearing: true
-        package_shape: suite-bundle
-      - runtime: opencode
-        path: .opencode/package.json
-        version_bearing: false
-        package_shape: suite-bundle
-    shared_paths_policy: validate minimum shared paths separately from full bundle includes
-  bundle_surfaces:
-    directories:
-      - skills
-      - scripts
-      - hooks
-      - references
-      - agents
-      - .agents/plugins
-      - .codex-plugin
-      - .claude-plugin
-      - .github/hooks
-      - .github/plugin
-      - .opencode/commands
-      - .opencode/plugins
-    files:
-      - README.md
-      - UPGRADE.md
-      - CHANGELOG.md
-      - DESIGN.md
-      - LICENSE
-      - pyproject.toml
-      - uv.lock
-      - registry.json
-      - plugin.json
-      - .opencode/package.json
-    skip_parts:
-      - __pycache__
-      - .pytest_cache
-      - node_modules
-    skip_suffixes:
-      - .pyc
-      - .pyo
-  package_commands:
-    commands:
-      - runtime: all
-        action: remove-legacy-skills
-        phase: cleanup
-        argv:
-          - npx
-          - skills
-          - remove
-          - hej
-          - visionera
-          - resonera
-          - inspirera
-          - planera
-          - realisera
-          - inspektera
-          - optimera
-          - orkestrera
-          - visualisera
-          - dokumentera
-          - profilera
-          - -g
-          - -y
-        skipped_without_update_packages_message: legacy skill removal skipped; pass --update-packages to run
-      - runtime: claude
-        action: install-agentera-skill
-        phase: runtime-install
-        argv:
-          - npx
-          - skills
-          - add
-          - jgabor/agentera
-          - -g
-          - -a
-          - claude-code
-          - --skill
-          - agentera
-          - -y
-        skipped_without_update_packages_message: external package update skipped; pass --update-packages to run
-      - runtime: opencode
-        action: install-agentera-skill
-        phase: runtime-install
-        argv:
-          - npx
-          - skills
-          - add
-          - jgabor/agentera
-          - -g
-          - -a
-          - opencode
-          - --skill
-          - agentera
-          - -y
-        skipped_without_update_packages_message: external package update skipped; pass --update-packages to run
-    safety:
-      argv_only: true
-      update_packages_required_to_plan: true
-      yes_required_to_execute: true
-      preserve_existing_write_gates: true
-      cleanup_phase: cleanup
-      runtime_install_phase: runtime-install
-  docs_targets:
-    version_files_source: .agentera/docs.yaml conventions.version_files
-    version_files:
-      - pyproject.toml
-      - uv.lock
-      - plugin.json
-      - .github/plugin/plugin.json
-      - .codex-plugin/plugin.json
-      - .claude-plugin/marketplace.json
-      - .opencode/plugins/agentera.js
-      - registry.json
-    index_targets:
-      - references/adapters/package-surface-characterization.md
-      - references/adapters/package-manifest-interface-model.yaml
-    excluded_version_files:
-      - .opencode/package.json
-  release_policy:
-    semver_policy_source: .agentera/docs.yaml conventions.semver_policy
-    version_bump_required_for_interface_only_change: false
-    release_publication_in_scope: false

package/bundle/references/adapters/package-registry.yaml

@@ -17,116 +17,21 @@ records:
         - id: registry
           path: registry.json
           selector: skills[0].version
-        - id: python-project
-          path: pyproject.toml
-          selector: project.version
-        - id: copilot-root
-          path: plugin.json
+        - id: cli-package
+          path: packages/cli/package.json
           selector: version
-        - id: copilot-repository
-          path: .github/plugin/plugin.json
-          selector: version
-        - id: codex-plugin
-          path: .codex-plugin/plugin.json
-          selector: version
-        - id: claude-marketplace-metadata
-          path: .claude-plugin/marketplace.json
-          selector: metadata.version
-        - id: claude-marketplace-plugins
-          path: .claude-plugin/marketplace.json
-          selector: plugins[*].version
-        - id: opencode-plugin-marker
-          path: .opencode/plugins/agentera.js
-          selector: AGENTERA_VERSION
-      excluded_runtime_manifests:
-        - .opencode/package.json
-    runtime_package_manifests:
-      manifests:
-        - id: copilot-root-manifest
-          runtime: copilot
-          path: plugin.json
-          version_bearing: true
-          package_shape: suite-bundle
-        - id: copilot-repository-manifest
-          runtime: copilot
-          path: .github/plugin/plugin.json
-          version_bearing: true
-          package_shape: suite-bundle
-        - id: codex-plugin-manifest
-          runtime: codex
-          path: .codex-plugin/plugin.json
-          version_bearing: true
-          package_shape: suite-bundle
-        - id: cursor-plugin-manifest
-          runtime: cursor
-          path: .cursor-plugin/plugin.json
-          version_bearing: true
-          package_shape: suite-bundle
-        - id: claude-marketplace-manifest
-          runtime: claude
-          path: .claude-plugin/marketplace.json
-          version_bearing: true
-          package_shape: suite-bundle
-        - id: opencode-package-manifest
-          runtime: opencode
-          path: .opencode/package.json
-          version_bearing: false
-          package_shape: npm-loadable-plugin
-      shared_paths:
-        - id: skills
-          path: skills
-          kind: dir
-        - id: scripts
-          path: scripts
-          kind: dir
-        - id: hooks
-          path: hooks
-          kind: dir
-        - id: registry
-          path: registry.json
-          kind: file
-        - id: copilot-root-manifest
-          path: plugin.json
-          kind: file
-        - id: readme
-          path: README.md
-          kind: file
-        - id: upgrade-guide
-          path: UPGRADE.md
-          kind: file
-      shared_paths_policy: validate minimum shared paths separately from full bundle includes
+        - id: cli-suite-marker
+          path: packages/cli/package.json
+          selector: agentera.suiteVersion
+        - id: skill-frontmatter
+          path: skills/agentera/SKILL.md
+          selector: frontmatter.version
     bundle_surfaces:
       directories:
         - id: skills
           path: skills
-        - id: scripts
-          path: scripts
-        - id: hooks
-          path: hooks
         - id: references
           path: references
-        - id: agents
-          path: agents
-        - id: agents-plugins
-          path: .agents/plugins
-        - id: codex-plugin
-          path: .codex-plugin
-        - id: cursor-plugin
-          path: .cursor-plugin
-        - id: cursor-agents
-          path: .cursor/agents
-        - id: claude-plugin
-          path: .claude-plugin
-        - id: github-hooks
-          path: .github/hooks
-        - id: github-plugin
-          path: .github/plugin
-        - id: opencode-commands
-          path: .opencode/commands
-        - id: opencode-agents
-          path: .opencode/agents
-        - id: opencode-plugins
-          path: .opencode/plugins
       files:
         - id: readme
           path: README.md
@@ -138,18 +43,19 @@ records:
           path: DESIGN.md
         - id: license
           path: LICENSE
-        - id: python-project
-          path: pyproject.toml
-        - id: python-lock
-          path: uv.lock
         - id: registry
           path: registry.json
-        - id: copilot-root-manifest
-          path: plugin.json
-        - id: opencode-package-manifest
-          path: .opencode/package.json
-        - id: cursor-hooks
-          path: .cursor/hooks.json
+        - id: routing-evaluation-corpus
+          path: fixtures/routing/hybrid-corpus.yaml
+      generated_files:
+        - id: npx-bundle-marker
+          path: .agentera-npx-bundle.json
+          format: json
+          classification: active
+        - id: extract-corpus-parity
+          path: extract-corpus-parity.json
+          format: json
+          classification: active
       skip_parts:
         - __pycache__
         - .pytest_cache
@@ -157,90 +63,16 @@ records:
       skip_suffixes:
         - .pyc
         - .pyo
-    package_commands:
-      commands:
-        - id: remove-legacy-skills
-          runtime: all
-          action: remove-legacy-skills
-          phase: cleanup
-          argv:
-            - npx
-            - skills
-            - remove
-            - hej
-            - visionera
-            - resonera
-            - inspirera
-            - planera
-            - realisera
-            - inspektera
-            - optimera
-            - orkestrera
-            - visualisera
-            - dokumentera
-            - profilera
-            - -g
-            - -y
-          skipped_without_update_packages_message: legacy skill removal skipped; pass --update-packages to run
-        - id: install-agentera-skill-claude
-          runtime: claude
-          action: install-agentera-skill
-          phase: runtime-install
-          argv:
-            - npx
-            - skills
-            - add
-            - jgabor/agentera
-            - -g
-            - -a
-            - claude-code
-            - --skill
-            - agentera
-            - -y
-          skipped_without_update_packages_message: external package update skipped; pass --update-packages to run
-        - id: install-agentera-skill-opencode
-          runtime: opencode
-          action: install-agentera-skill
-          phase: runtime-install
-          argv:
-            - npx
-            - skills
-            - add
-            - jgabor/agentera
-            - -g
-            - -a
-            - opencode
-            - --skill
-            - agentera
-            - -y
-          skipped_without_update_packages_message: external package update skipped; pass --update-packages to run
-      safety:
-        argv_only: true
-        update_packages_required_to_plan: true
-        yes_required_to_execute: true
-        preserve_existing_write_gates: true
-        cleanup_phase: cleanup
-        runtime_install_phase: runtime-install
     docs_targets:
       version_files_source: .agentera/docs.yaml conventions.version_files
       version_files:
-        - pyproject.toml
-        - uv.lock
-        - plugin.json
-        - .github/plugin/plugin.json
-        - .codex-plugin/plugin.json
-        - .cursor-plugin/plugin.json
-        - .claude-plugin/marketplace.json
-        - .opencode/plugins/agentera.js
+        - packages/cli/package.json
         - skills/agentera/SKILL.md
-        - skills/hej/SKILL.md
         - registry.json
       index_targets:
         - references/adapters/package-surface-characterization.md
         - references/adapters/package-manifest-interface-model.yaml
         - references/adapters/package-registry.yaml
-      excluded_version_files:
-        - .opencode/package.json
     release_policy:
       semver_policy_source: .agentera/docs.yaml conventions.semver_policy
       version_bump_required_for_interface_only_change: false

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

@@ -1,48 +1,47 @@
-# 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 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`. |
+## 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. |
+## Native package boundary
 
-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. |
+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.