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

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-publication.json

@@ -0,0 +1,43 @@
+{
+  "schemaVersion": "agentera.packagePublication.v1",
+  "owner": "repository/package scripts",
+  "invariants": {
+    "preparation": "Metadata preparation is non-publishing and leaves version and gitRef changes for review and commit.",
+    "preflight": "Publication requires explicit authority, a clean tree, committed package metadata, an adapter-valid version, and an existing gitRef before registry mutation.",
+    "publication": "Publish directly to the expected tag, then require bounded exact-version integrity and tag convergence.",
+    "access": "Publish the unscoped package with public access.",
+    "retry": "An exact version with matching integrity and expected tag is a successful replay; conflicting integrity or an expected tag already ahead of the committed version fails without mutation.",
+    "smoke": "Run one non-mutating no-project exact-version --version command after convergence; failure is explicit and does not imply rollback.",
+    "construction": "Each adapter returns the exact npm name, version, file count, packed and unpacked sizes, shasum, integrity, expected tag, artifact path, warnings, and complete file manifest before publication.",
+    "credentials": "Only the npm publish child receives credentials, through a mode-0600 temporary user config; inherited npm/pnpm lifecycle settings and token variables are removed from its environment, and the config is deleted when the child exits.",
+    "orchestration": "Root package scripts are the shared local and CI interface. Push-only development and stable jobs run the matching transaction after required gates; replay needs no credentials, mutation without credentials fails, and development publication precedes exact-version L2 bootstrap verification.",
+    "outputModes": "Default construction output omits the per-file list; --json and --verbose retain the complete npm pack manifest.",
+    "output": ["package", "version", "expectedTag", "phase", "outcome", "nextAction"]
+  },
+  "packages": {
+    "development": {
+      "label": "development TypeScript package",
+      "packagePath": "packages/cli",
+      "manifestPath": "packages/cli/package.json",
+      "expectedTag": "next",
+      "preparation": "incrementDevPrerelease",
+      "construction": "isolatedTypeScriptPackage",
+      "smoke": ["npx", "-y", "agentera@{version}", "--version"]
+    },
+    "stable": {
+      "label": "transitional stable shim",
+      "packagePath": "packages/cli/shim",
+      "manifestPath": "packages/cli/shim/package.json",
+      "expectedTag": "latest",
+      "preparation": "incrementPatch",
+      "construction": "stableShim",
+      "smoke": ["npx", "-y", "agentera@{version}", "--version"]
+    }
+  },
+  "bounds": {
+    "registryAttempts": 6,
+    "registryDelayMs": 5000,
+    "commandTimeoutMs": 120000,
+    "diagnosticCharacters": 1000
+  }
+}

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