agentera 3.0.0-dev.5 → 3.0.0-dev.51

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

@@ -1,337 +0,0 @@
-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.
-record:
-  required_groups:
-    - identity
-    - version_authority
-    - version_surfaces
-    - runtime_package_manifests
-    - bundle_surfaces
-    - package_commands
-    - docs_targets
-    - release_policy
-  groups:
-    identity:
-      type: object
-      owns:
-        - package id
-        - suite name
-        - skill path
-        - capability count expectation
-      required_fields:
-        id: string
-        name: string
-        skill_path: repo_relative_path
-        expected_capabilities: integer
-    version_authority:
-      type: object
-      owns:
-        - suite version access selector
-        - persisted authority declaration
-        - authority transition rule
-      required_fields:
-        persisted_authority: repo_relative_path
-        selector: string
-        access_interface: string
-        future_authority_change_requires: string
-    version_surfaces:
-      type: object
-      owns:
-        - version-bearing repository 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
-        - bundle skip rules
-        - bundle mismatch standardization target
-      required_fields:
-        directories: list[repo_relative_path]
-        files: list[repo_relative_path]
-        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
-    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:
-        - semver policy projection
-        - changelog decision guidance
-        - release publication exclusion
-      required_fields:
-        semver_policy_source: string
-        version_bump_required_for_interface_only_change: boolean
-        release_publication_in_scope: boolean
-ownership:
-  registry_json_version_authority:
-    owner: registry.json
-    persisted_authority: true
-    path: registry.json
-    selector: skills[0].version
-    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.
-    future_authority_change_requires: explicit ADR
-  install_root_delegated:
-    owner: scripts/install_root.py
-    forbidden_in_package_manifest:
-      - AGENTERA_HOME precedence
-      - default app home
-      - managed classification
-      - 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/runtime-adapter-characterization.md

@@ -1,79 +0,0 @@
-# Runtime Adapter Characterization
-
-Task 2 of `Deepen RuntimeAdapter Registry` records current behavior before any
-registry extraction. This is a characterization artifact, not the new registry.
-
-## Doctor Output
-
-Current JSON envelope fields are `schemaVersion`, `ok`, `installRoot`,
-`runtimes`, `summary`, and `smoke`. Each runtime result exposes `runtime`,
-`status`, `available`, `binary`, and `checks`. Each check exposes `name`,
-`status`, `message`, `source`, `path`, `gap`, and `details`.
-
-Primary pass messages by runtime:
-
-| Runtime | Primary check | Status | Message | Diagnostic label |
-|---------|---------------|--------|---------|------------------|
-| Claude Code | `CLAUDE_PLUGIN_ROOT` | `pass` | `runtime can reach shared Agentera helper scripts` | none |
-| OpenCode | `plugin_file` | `pass` | `OpenCode plugin file is present` | none |
-| Copilot CLI | `AGENTERA_HOME` | `pass` | `runtime can reach shared Agentera helper scripts` | none |
-| Codex CLI | `config.AGENTERA_HOME` | `pass` | `runtime can reach shared Agentera helper scripts` | none |
-
-Current diagnostic labels that are intentionally public are `user_environment`,
-`runtime_config`, `bundle_packaging`, `command_drift`, `skill_path_drift`, and
-`validation_drift`.
-
-## Upgrade Planning
-
-Runtime-phase items currently expose `runtime`, `action`, `target`, `status`,
-and `message`; copy operations also expose `source`, and configure operations
-carry private `newText` until public JSON rendering strips it.
-
-Characterized runtime actions:
-
-| Runtime | Action | Target | Dry-run status | Apply behavior |
-|---------|--------|--------|----------------|----------------|
-| Claude Code | `configure` | none | `noop` | no local config write |
-| Codex CLI | `configure` | `~/.codex/config.toml` | `pending` | writes config, then reports `runtime update applied` |
-| Codex CLI | `copy-hooks` | `~/.codex/hooks.json` | `pending` | copies hooks, then reports `runtime update applied` |
-| Codex CLI | `copy-agent` | `~/.codex/agents/*.toml` | `pending` | copies managed capability descriptors, then reports `runtime update applied` |
-| Copilot CLI | `configure` | none | `noop` | no local config write; use per-invocation `AGENTERA_HOME` |
-| OpenCode | `copy-plugin` | `~/.config/opencode/plugins/agentera.js` | `pending` | copies plugin, then reports `runtime update applied` |
-| OpenCode | `copy-agent` | `~/.config/opencode/agents/*.md` | `pending` | copies managed capability descriptors, then reports `runtime update applied` |
-
-Package-phase items currently expose `runtime`, `action`, `command`, `status`,
-and `message`. Without `--update-packages`, package items are `skipped`; with it,
-Claude Code and OpenCode package commands become `pending` and apply through the
-external command runner. Copilot CLI and Codex CLI have no package command item in
-the current upgrade phase.
-
-## Lifecycle Validation
-
-Current pass output from `scripts/validate_lifecycle_adapters.py` is exactly:
-
-```text
-lifecycle adapter metadata ok
-```
-
-Current failure output begins with:
-
-```text
-lifecycle adapter validation failed:
-```
-
-Representative fail messages are characterized in `tests/test_runtime_adapters.py`:
-Copilot stale `lifecycleHooks`, unsupported hook event files, missing `preToolUse`
-artifact validation, Codex unsupported status values, malformed event containers,
-missing supported-event declarations, missing unsupported-event declarations, and
-missing `codex_hooks` limitation text.
-
-## Drift Inventory
-
-| Drift point | Decision | Before-migration handling |
-|-------------|----------|---------------------------|
-| duplicated runtime order appears in doctor, upgrade, and tests | `standardize` | Later registry extraction should define one runtime order and have consumers read it. |
-| upgrade package phase only manages Claude Code and OpenCode | `preserve` | This is current behavior, not a registry gap; Copilot CLI and Codex CLI package command support is separate future work. |
-| Codex supports hook events but shipped config wires only apply_patch validation | `preserve` | Keep the distinction between host support and shipped Agentera wiring. |
-| Claude lifecycle behavior is validated through native hook files, not lifecycle metadata | `defer` | Do not invent Claude lifecycle metadata in Task 2; decide during registry interface design. |
-| OpenCode session preload observes `session.created` but has no verified context injection path | `preserve` | Keep degraded preload semantics in docs and diagnostics. |
-| hard-gate docs only claim blocking for reconstructable OpenCode and Copilot candidates | `preserve` | Keep scoped claims; do not standardize to full hard-gate parity. |

package/bundle/references/adapters/runtime-adapter-interface-model.yaml

@@ -1,200 +0,0 @@
-interface: RuntimeAdapter
-status: design_contract
-purpose: >-
-  Define the runtime-owned facts that a later registry Module may expose without
-  absorbing package metadata, app-home classification, or caller behavior.
-record:
-  required_groups:
-    - identity
-    - host_detection
-    - lifecycle_events
-    - artifact_validation
-    - subagent_dispatch
-    - config_targets
-    - diagnostics
-    - documentation_claims
-  groups:
-    identity:
-      type: object
-      owns:
-        - runtime_id
-        - display_name
-        - adapter_family
-        - support_status
-      required_fields:
-        runtime_id: string
-        display_name: string
-        adapter_family: string
-        support_status: enum
-    host_detection:
-      type: object
-      owns:
-        - binary_names
-        - host_config_locations
-        - availability_probe_label
-      required_fields:
-        binary_names: list[string]
-        host_config_locations: list[string]
-        availability_probe_label: string
-    lifecycle_events:
-      type: object
-      owns:
-        - supported_events
-        - unsupported_events
-        - event_status
-        - limitations
-      required_fields:
-        supported_events: list[string]
-        unsupported_events: list[string]
-        event_status: map[string,string]
-        limitations: list[string]
-    artifact_validation:
-      type: object
-      owns:
-        - validation_events
-        - hard_gate_claims
-        - payload_reconstruction_limitations
-      required_fields:
-        validation_events: list[string]
-        hard_gate_claims: list[string]
-        payload_reconstruction_limitations: list[string]
-    subagent_dispatch:
-      type: object
-      owns:
-        - mechanism
-        - setup_targets
-        - descriptor_sources
-        - invocation_pattern
-        - limitations
-        - tool_configuration
-      required_fields:
-        mechanism: string
-        setup_targets: list[string]
-        descriptor_sources: list[string]
-        invocation_pattern: string
-        limitations: list[string]
-    config_targets:
-      type: object
-      owns:
-        - runtime_config_files
-        - hook_targets
-        - plugin_targets
-        - environment_exports
-        - write_safety_labels
-      required_fields:
-        runtime_config_files: list[string]
-        hook_targets: list[string]
-        plugin_targets: list[string]
-        environment_exports: list[string]
-        write_safety_labels: list[string]
-    diagnostics:
-      type: object
-      owns:
-        - check_names
-        - status_labels
-        - gap_labels
-        - primary_messages
-      required_fields:
-        check_names: list[string]
-        status_labels: list[string]
-        gap_labels: list[string]
-        primary_messages: list[string]
-    documentation_claims:
-      type: object
-      owns:
-        - reference_paths
-        - parity_claims
-        - install_claims
-        - known_drifts
-      required_fields:
-        reference_paths: list[string]
-        parity_claims: list[string]
-        install_claims: list[string]
-        known_drifts: list[string]
-ownership:
-  runtime_adapter_owns:
-    - runtime identity and display labels
-    - host detection facts used by runtime-facing consumers
-    - lifecycle event support and limitations
-    - artifact validation support claims
-    - runtime-native subagent dispatch descriptor and invocation facts
-    - runtime config, hook, plugin, and environment target paths
-    - diagnostic check names, statuses, gaps, and messages
-        - adapter documentation parity and known-mismatch claims
-  package_metadata_out_of_scope:
-    owner: package_manifest_registry
-    deferred_todo: arch-package-manifest-registry
-    facts:
-      - version_authority
-      - package_manifest_schemas
-      - shared_package_paths
-      - release_metadata
-  install_root_out_of_scope:
-    owner: scripts/install_root.py
-    facts:
-      - AGENTERA_HOME precedence
-      - default app home
-      - managed classification
-      - stale classification
-      - unmanaged classification
-      - app-home diagnostics
-consumer_permissions:
-  lifecycle_validation:
-    allowed_groups:
-      - identity
-      - lifecycle_events
-      - artifact_validation
-      - subagent_dispatch
-      - documentation_claims
-    forbidden_ownership:
-      - package_metadata_out_of_scope
-      - install_root_out_of_scope
-  doctor:
-    allowed_groups:
-      - identity
-      - host_detection
-      - config_targets
-      - diagnostics
-      - documentation_claims
-    forbidden_ownership:
-      - package_metadata_out_of_scope
-      - install_root_out_of_scope
-  upgrade:
-    allowed_groups:
-      - identity
-      - host_detection
-      - subagent_dispatch
-      - config_targets
-      - diagnostics
-    forbidden_ownership:
-      - package_metadata_out_of_scope
-      - install_root_out_of_scope
-  docs:
-    allowed_groups:
-      - identity
-      - lifecycle_events
-      - artifact_validation
-      - subagent_dispatch
-      - config_targets
-      - diagnostics
-      - documentation_claims
-    forbidden_ownership:
-      - package_metadata_out_of_scope
-      - install_root_out_of_scope
-  tests:
-    allowed_groups:
-      - identity
-      - host_detection
-      - lifecycle_events
-      - artifact_validation
-      - subagent_dispatch
-      - config_targets
-      - diagnostics
-      - documentation_claims
-    forbidden_ownership:
-      - package_metadata_out_of_scope
-      - install_root_out_of_scope
-non_goals:
-  - Do not introduce an executable RuntimeAdapter registry Module in this task.
-  - Do not migrate lifecycle validation, doctor, upgrade, docs, or runtime tests to consume a registry in this task.
-  - Do not change app-home classification, package metadata validation, artifact write validation, or live runtime behavior.