agentera 3.0.0-dev.25 → 3.0.0-dev.27

package/bundle/UPGRADE.md

@@ -1,141 +1,74 @@
-# Upgrade and runtime lifecycle
+# Upgrade and migration
 
-Agentera 3.0 uses one upgrade command for project/app migration and explicitly
-selected runtime lifecycle work. Preview and apply are separate operations.
+Agentera 3.0 uses one upgrade command for app/project migration and explicit
+retired Claude cleanup. Preview and apply are separate operations. Current
+runtime installation and repair are not upgrade operations.
 
 Before the npm stable dist-tag promotion, use `agentera@next`. The stable 2.x
-channel remains `agentera@latest` until that promotion; this repository does
-not publish or retag as part of an upgrade run.
+channel remains `agentera@latest` until that promotion; upgrade does not publish
+or retag packages.
 
-## Start with a preview
+## Active integration
 
-```bash
-npx -y agentera@next upgrade --dry-run --channel development
-```
+Agentera has one active integration contract:
 
-On the v3 development channel, a dry-run without `--runtime` also observes all
-active runtimes so blocked app or channel phases do not hide lifecycle findings.
-The preview remains read-only. Runtime apply is explicit:
-
-```bash
-npx -y agentera@next upgrade --runtime all --dry-run
-npx -y agentera@next upgrade --runtime cursor --dry-run
+```text
+~/.agents/skills/agentera + agentera CLI
 ```
 
-The active runtimes are OpenCode, Codex, Cursor, and GitHub Copilot. Selectors
-are `all`, `opencode`, `codex`, `cursor`, and `copilot`.
-`cursor-agent` is not a selector: Cursor Agent CLI and Cursor IDE are surfaces
-of the one `cursor` identity. CLI is required; IDE is conditional.
+Normal `prime`, `doctor`, `schema`, help, and project-integration output reports
+that shared skill and CLI/app/project state. Normal `upgrade` has no
+current-runtime selector or native-resource operation set. It creates no current
+plugin, hook, agent, command, descriptor, or marketplace file and does not run
+runtime package managers, authentication, enablement, or trust operations.
 
-The preview is strictly read-only. It creates no files, directories, locks,
-caches, ownership journals, telemetry, or other state changes. Its output
-includes:
+Passing `--runtime` fails before mutation. Remove `--runtime`, ensure the runtime
+can read `~/.agents/skills/agentera`, and invoke the CLI directly. The supported
+v2 migration and Claude cleanup routes below are separate from normal active
+integration.
 
-- observed runtime and surface evidence;
-- skill, plugin, hook, agent, configuration, enablement, trust, and native-action state;
-- planned operations and dependencies;
-- current ownership evidence and blocked reasons;
-- exact manual or host-native actions;
-- required support-floor gaps.
+## Preview and apply
 
-`prime` exposes a bounded projection of the same snapshot. `doctor` exposes the
-detailed read-only diagnosis:
+Preview normal app/project work:
 
 ```bash
-npx -y agentera@next prime --format json
-npx -y agentera@next doctor --format json
+npx -y agentera@next upgrade --dry-run --channel development
 ```
 
-Status and project-integration recommendations use the same lifecycle identity,
-counts, blockers, and retry guidance as `prime` and `doctor`.
-
-## Apply approved Agentera-owned work
-
-After reviewing an all-runtime preview, use its generated command or rerun the
-selection explicitly with `--runtime all --yes`:
+The preview is strictly read-only: it creates no files, directories, locks,
+caches, ownership records, telemetry, or other state. Apply only after reviewing
+the generated command:
 
 ```bash
-npx -y agentera@next upgrade --runtime all --yes
+npx -y agentera@next upgrade --yes --channel development
 ```
 
-An apply invoked without `--runtime` retains the existing app-only behavior.
-Named selectors such as `--runtime cursor` limit runtime-specific writes to that
-identity. Stable-channel v2 behavior remains app-only.
-
-Apply can write only resources declared by the lifecycle contract and proven
-Agentera-owned by the append-only ownership journal. Matching names or bytes do
-not establish ownership. User-owned, ambiguous, shadowed, or malformed targets
-remain blocked.
-
-For every blocked collision, the exact remediation is: “The destination is not
-ledger-owned; review the collision manually. Agentera will not adopt it by name
-or equality.” The destination remains unchanged until authoritative ownership is
-available.
-
-The operation outcomes are:
-
-- `applied` — the declared change was published;
-- `noop` — desired state was already exact;
-- `failed` — this operation failed; independent operations may continue;
-- `blocked_unowned` — ownership was not proven;
-- `skipped_dependency` — a prerequisite did not complete;
-- `action_required` — the user or host must perform the step.
+`prime` and `doctor` expose the same app/project classification and shared-skill
+state:
 
-Retries are designed to converge. Completed work becomes `noop`; failed or
-pending work is re-observed and retried. Corrupt, forked, disconnected, or
-non-contiguous ownership journals fail closed.
-
-Secure automatic filesystem publication currently requires Linux
-`/proc/self/fd`. On macOS, Windows, or a Linux environment without that secure
-primitive, preview and diagnosis still work but mutation is returned as
-`action_required`.
-
-## Ownership and trust boundary
-
-The canonical skill is:
-
-```text
-~/.agents/skills/agentera
+```bash
+npx -y agentera@next prime --format json
+npx -y agentera@next doctor --format json
 ```
 
-Agentera can maintain declared Agentera-owned skill, plugin, hook, and agent
-resources. It does not run native runtime package managers or approve:
-
-- runtime installation or self-update;
-- authentication;
-- plugin or hook enablement;
-- trust prompts or organizational policy;
-- user-owned configuration collisions.
-
-Those steps are reported with exact remediation and remain user-owned.
-
-## Cursor lifecycle
-
-Cursor is one runtime identity with two surfaces:
-
-| Surface | Support-floor role | Typical source |
-| --- | --- | --- |
-| Agent CLI | required | Cursor CLI binary and canonical shared skill |
-| IDE | conditional | `.cursor-plugin/plugin.json`, `.cursor/hooks.json`, `.cursor/agents/` |
-
-An absent IDE does not block a CLI-only installation. Once IDE evidence is
-present, its incomplete or denied mandatory evidence is reported beneath the
-same Cursor identity.
+Retries re-observe the current app/project state. Completed migration work
+converges to no change; interrupted v2 migration continues through the same full
+apply command.
 
 ## Retired Claude cleanup
 
-Claude Code is not an active Agentera runtime and cannot be passed to
-`--runtime`. Its legacy cleanup is a separate explicit selection:
+Claude cleanup is a distinct historical route, not a current-runtime selection:
 
 ```bash
 npx -y agentera@next upgrade --legacy-cleanup claude --dry-run
 npx -y agentera@next upgrade --legacy-cleanup claude --yes
 ```
 
-Cleanup is limited to the exact Agentera-owned legacy skill link recorded by
-the ownership ledger. It never removes Claude projects, transcripts, settings,
+Cleanup is limited to the exact Agentera-owned legacy skill link recorded by the
+ownership journal. It never removes Claude projects, transcripts, settings,
 credentials, caches, or other user data. Ambiguous or unowned resources remain
-blocked.
+blocked. Preview is read-only; apply is idempotent and can be retried with the
+same explicit selection.
 
 Historical transcript import is independent of cleanup. Default extraction and
 analytics do not read Claude history. Import requires explicit local consent:
@@ -145,9 +78,9 @@ npx -y agentera@next report refresh --import-source claude
 ```
 
 Imported records carry `historical_import` provenance, have no active runtime
-ID, and remain excluded from default active-runtime analytics.
+ID, and remain excluded from default active-source analytics.
 
-## Recommended upgrade v1 & v2 stable channel
+## Stable v2 line
 
 The stable `@latest` channel remains on the supported 2.x line. Preview before
 applying an in-line upgrade:
@@ -157,65 +90,35 @@ npx -y agentera@latest upgrade --dry-run
 npx -y agentera@latest upgrade --yes
 ```
 
-Use the v3 development migration below only when you explicitly intend to
-leave the stable line.
+Use the v3 development migration below only when you explicitly intend to leave
+the stable line.
 
-## Upgrading v2 to v3 development channel (irreversible)
+## Upgrading v2 to v3 development channel
 
-Use the development channel explicitly while 3.0 is on `@next`:
+Recognized marker-absent v2 aggregate state has one supported forward route:
 
 ```bash
 npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
 npx -y agentera@next upgrade --channel development --project "$PWD" --yes
 ```
 
-The dry-run is optional and read-only. Before applying, commit or restore the
-complete v2 migration source: every input must be a regular file tracked by Git
-and unchanged at `HEAD`. The apply command performs the full runtime and entity
-state upgrade, then validates state and representative `prime` startup.
-
-Forward migration to v3 is one-way. Returning to the Python 2.x line is not
-supported, and cross-major apply has no rollback, restore, non-Git, or partial
-workflow. If an apply is interrupted, rerun the same full apply command to
-continue forward.
-
-## Legacy state and optional Git enrichment
-
-Project-state migration and historical Git enrichment are separate local
-operations. Migration does not read Git, contact a remote, or remove its source
-files. Its default inventory and `--dry-run` are read-only; apply requires the
-exact artifact and entry selectors with `--apply --force`:
-
-```bash
-npx -y agentera@next state migrate --project "$PWD" --artifact progress --number N --dry-run --format json
-npx -y agentera@next state migrate --project "$PWD" --artifact progress --number N --apply --force --format json
-```
-
-Git enrichment is optional. A preview is useful but not required before direct
-apply. Inventory and preview may use the current working directory when
-`--project` is omitted; direct apply must name `--project PATH` explicitly.
-Apply revalidates the selected project, current `HEAD`, allowed-ref
-reachability, candidate provenance and content, and the immutable archive target
-immediately before publication:
+The optional preview is read-only. Before apply, commit or restore the complete
+v2 migration source: every input must be a regular file tracked by Git and
+unchanged at `HEAD`. Apply performs the full project rewiring and entity-state
+cutover, then validates state and representative `prime` startup. Rewiring may
+update recognized v2 project files; it does not install current native resources.
 
-```bash
-npx -y agentera@next state backfill --project "$PWD" --artifact progress --number N --dry-run --format json
-npx -y agentera@next state backfill --project "$PWD" --artifact progress --number N --apply --force --format json
-```
+Forward migration is one-way. Returning to the Python 2.x line is unsupported,
+and cross-major apply has no rollback, restore, non-Git, or partial workflow.
+If apply is interrupted, rerun the same full apply command.
 
-The backfill contract is bounded to 100 result rows, 500 history units, and
-16 MiB of Git output. It inspects only `HEAD`, local heads, and tags; remote and
-custom refs and operations are excluded. Returned provenance keeps the commit,
-path, blob ID, stable entry ID, content hash, and reachability so a result can
-be traced without adding commit fields to the archive record.
+## Unsupported legacy state
 
-`complete`, `degraded`, `blocked`, and `unavailable` are explicit outcomes.
-Changed, shallow, rewritten, ambiguous, corrupt, missing, bounded, unavailable,
-and immutable-conflict results are reported rather than guessed. Resolve the
-reported local condition and retry the same selectors; refused operations leave
-active projections and existing archives unchanged, and identical publication
-converges as a replay. The full command, limits, failure, recovery, and
-traceability contract is `references/artifacts/state-storage-authority.yaml`.
+Pending v1 Markdown state and unknown marker-absent state are not automatic
+mutation inputs. `state migrate`, `state backfill`, projection repair, v1
+conversion, restore, and downgrade are unsupported. The read-only
+`state migrate entities --dry-run` diagnostic may inventory cutover input but
+cannot publish it.
 
 ## Verification and recovery
 
@@ -227,14 +130,11 @@ npx -y agentera@next prime --format json
 ```
 
 `upgrade --verify` without `--yes` is a read-only doctor and capability-context
-verification. With `--yes`, it runs those checks after the approved upgrade
-apply. Lifecycle selections with `--verify` require `--yes`.
-For lifecycle partial failure, rerun the same preview and apply selection. Do
-not delete or hand-edit the ownership journal to force adoption.
+verification. With `--yes`, it runs those checks after approved migration.
+Explicit Claude cleanup with `--verify` requires `--yes`.
 
 `--force` applies only where the owning migration contract explicitly permits
-replacement. It does not convert user-owned resources into Agentera-owned
-resources and does not approve native or trust actions.
+replacement. It never adopts user-owned resources.
 
 ## Maintainer verification
 
@@ -244,8 +144,14 @@ Release preparation does not publish, tag, or push:
 pnpm -C packages/cli test
 pnpm -C packages/cli run typecheck
 pnpm -C packages/cli build
-node packages/cli/dist/bin/agentera.js check validate lifecycle-adapters
+node packages/cli/dist/bin/agentera.js check validate capability-contract --format json
 node packages/cli/dist/bin/agentera.js check validate release-metadata
-pnpm -C packages/cli run bundle:data
-npm pack --dry-run --json --ignore-scripts
 ```
+
+## Mutation ownership
+
+Upgrade apply holds the required project lock before migration begins. Explicit
+Claude cleanup additionally uses its ownership journal and shared lock. Lock
+creation is atomic, and release succeeds only for the matching ownership token.
+A stale or malformed lock stops the operation; inspect the named lock file,
+remove only that file after confirming no operation owns it, then rerun.

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 TypeScript PackageRegistry loader
-  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,56 +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
-        - generated-only 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:
@@ -113,8 +113,8 @@ 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: packages/cli/src/state/installRoot.ts
@@ -125,204 +125,3 @@ ownership:
       - stale classification
       - unmanaged classification
       - app-home diagnostics
-  runtime_adapter_delegated:
-    owner: packages/cli/src/registries/runtimeAdapterRegistry.ts
-    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
-    - opencode
-    - codex
-    - cursor
-    - copilot
-  approved_runtime_agents:
-    - 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: cli-package
-        path: packages/cli/package.json
-        selector: version
-      - id: cli-suite-marker
-        path: packages/cli/package.json
-        selector: agentera.suiteVersion
-      - 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: cursor-plugin
-        path: .cursor-plugin/plugin.json
-        selector: version
-      - id: opencode-plugin-marker
-        path: .opencode/plugins/agentera.js
-        selector: AGENTERA_VERSION
-      - id: skill-frontmatter
-        path: skills/agentera/SKILL.md
-        selector: frontmatter.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: cursor
-        path: .cursor-plugin/plugin.json
-        version_bearing: true
-        package_shape: suite-bundle
-      - runtime: opencode
-        path: .opencode/package.json
-        version_bearing: false
-        package_shape: npm-loadable-plugin
-    shared_paths_policy: validate minimum shared paths separately from full bundle includes
-  bundle_surfaces:
-    directories:
-      - skills
-      - references
-      - agents
-      - hooks
-      - .github/hooks
-      - .codex-plugin
-      - .cursor-plugin
-      - .cursor/agents
-      - .opencode/commands
-      - .opencode/agents
-      - .opencode/plugins
-    files:
-      - README.md
-      - UPGRADE.md
-      - CHANGELOG.md
-      - DESIGN.md
-      - LICENSE
-      - registry.json
-      - plugin.json
-      - .github/plugin/plugin.json
-      - .opencode/package.json
-      - .cursor/hooks.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: 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:
-      - packages/cli/package.json
-      - plugin.json
-      - .github/plugin/plugin.json
-      - .codex-plugin/plugin.json
-      - .cursor-plugin/plugin.json
-      - .opencode/plugins/agentera.js
-      - skills/agentera/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
-    release_publication_in_scope: false