agentera 3.0.0-dev.41 → 3.0.0-dev.46

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

@@ -39,6 +39,19 @@ 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.
 
+`bootstrap_command_authority` closes the command-guidance inventory. Markdown,
+YAML, and JSON bundle surfaces are parsed and scanned in source and extracted
+package layouts. Other files need a path-specific reason, and unused exemption
+paths fail. Generated declarations compare `id`, `path`, `format`,
+`classification`, and reason exactly before the generated package file is
+parsed. Constructor inventory uses conservative reverse static import and
+re-export closure instead of local value-flow guesses. Every module in that
+closure is classified exactly once as an emitted producer or an explicit
+non-producer with a reason; dynamic module consumers, parse ambiguity, stale
+declarations, and bounded traversal fail closed. Aggregate outputs are scanned
+separately. This avoids a blind scan of compiled JavaScript while still
+checking generated behavior.
+
 ## Publication adapters
 
 [`package-publication.json`](./package-publication.json) owns the shared
@@ -57,3 +70,10 @@ The package registry defines no host-native manifest parity, package-manager
 command, runtime source tree, or native install command. Historical migration
 readers and fixtures remain source-only compatibility data; they do not create a
 current integration surface in the npm inventory.
+
+## Maintenance
+
+- Maintainer: Agentera CLI maintainers
+- Source checkout root: `.`
+- Working directory: `.`
+- Command: `pnpm -C packages/cli run pack:dry-run`

package/bundle/references/adapters/runtime-retired-resources.yaml

@@ -25,7 +25,7 @@ accepted_host_evidence:
     proof: Cursor loaded Agentera's specific canonical skill instructions and bootstrap command.
   - host: opencode
     state: supported
-    proof: OpenCode's native CLI listed /home/jgabor/.agents/skills/agentera/SKILL.md.
+    proof: OpenCode's native CLI listed ~/.agents/skills/agentera/SKILL.md.
   - host: copilot
     state: supported_disabled
     proof: Copilot's native CLI listed the canonical personal-agents skill; its disabled state is intentional.
@@ -45,8 +45,216 @@ hosts:
   - id: claude
     display_name: Claude Code historical migration
     support_status: retired_historical
+resource_vocabulary:
+  - id: claude.skill-link
+    resource_class: legacy_skill_link
+    migration_scope: explicit_cleanup
+    resource_ids:
+      - claude.agentera-skill-link
+    historical_ids: []
+  - id: codex.agent-descriptor
+    resource_class: capability_descriptor
+    migration_scope: explicit_cleanup
+    resource_ids:
+      - codex.agent-descriptor.status
+      - codex.agent-descriptor.vision
+      - codex.agent-descriptor.discuss
+      - codex.agent-descriptor.research
+      - codex.agent-descriptor.plan
+      - codex.agent-descriptor.build
+      - codex.agent-descriptor.optimize
+      - codex.agent-descriptor.audit
+      - codex.agent-descriptor.document
+      - codex.agent-descriptor.profile
+      - codex.agent-descriptor.design
+      - codex.agent-descriptor.orchestrate
+    historical_ids:
+      - codex.agents.status
+      - codex.agents.vision
+      - codex.agents.discuss
+      - codex.agents.research
+      - codex.agents.plan
+      - codex.agents.build
+      - codex.agents.optimize
+      - codex.agents.audit
+      - codex.agents.document
+      - codex.agents.profile
+      - codex.agents.design
+      - codex.agents.orchestrate
+  - id: opencode.plugin
+    resource_class: plugin
+    migration_scope: v2_upgrade_only
+    resource_ids:
+      - opencode.plugin.agentera
+    historical_ids: []
+  - id: opencode.command
+    resource_class: command
+    migration_scope: v2_upgrade_only
+    resource_ids:
+      - opencode.command.agentera
+      - opencode.command.hej
+    historical_ids: []
+  - id: legacy.primary-agent
+    resource_class: primary_agent
+    migration_scope: v2_upgrade_only
+    resource_ids:
+      - cursor.agent.agentera
+      - opencode.agent.agentera
+    historical_ids: []
+  - id: legacy.capability-agent
+    resource_class: capability_agent
+    migration_scope: v2_upgrade_only
+    resource_ids:
+      - cursor.agent.audit
+      - cursor.agent.build
+      - cursor.agent.design
+      - cursor.agent.discuss
+      - cursor.agent.document
+      - cursor.agent.optimize
+      - cursor.agent.orchestrate
+      - cursor.agent.plan
+      - cursor.agent.profile
+      - cursor.agent.research
+      - cursor.agent.status
+      - cursor.agent.vision
+      - cursor.agent.dokumentera
+      - cursor.agent.hej
+      - cursor.agent.inspektera
+      - cursor.agent.inspirera
+      - cursor.agent.optimera
+      - cursor.agent.orkestrera
+      - cursor.agent.planera
+      - cursor.agent.profilera
+      - cursor.agent.realisera
+      - cursor.agent.resonera
+      - cursor.agent.visionera
+      - cursor.agent.visualisera
+      - opencode.agent.audit
+      - opencode.agent.build
+      - opencode.agent.design
+      - opencode.agent.discuss
+      - opencode.agent.document
+      - opencode.agent.optimize
+      - opencode.agent.orchestrate
+      - opencode.agent.plan
+      - opencode.agent.profile
+      - opencode.agent.research
+      - opencode.agent.status
+      - opencode.agent.vision
+      - opencode.agent.dokumentera
+      - opencode.agent.hej
+      - opencode.agent.inspektera
+      - opencode.agent.inspirera
+      - opencode.agent.optimera
+      - opencode.agent.orkestrera
+      - opencode.agent.planera
+      - opencode.agent.profilera
+      - opencode.agent.realisera
+      - opencode.agent.resonera
+      - opencode.agent.visionera
+      - opencode.agent.visualisera
+    historical_ids: []
+  - id: opencode.stale-skill-link
+    resource_class: stale_skill_link
+    migration_scope: v2_upgrade_only
+    resource_ids:
+      - opencode.skill-link.agentera
+      - opencode.skill-link.status
+    historical_ids: []
+  - id: installed.hook
+    resource_class: installed_hook
+    migration_scope: v2_upgrade_only
+    resource_ids:
+      - agentera.installed-hook.validate_artifact.py
+      - agentera.installed-hook.cursor_session_start.py
+      - agentera.installed-hook.cursor_pre_tool_use.py
+      - agentera.installed-hook.cursor_session_stop.py
+      - agentera.installed-hook.session_start.py
+      - agentera.installed-hook.session_stop.py
+      - agentera.installed-hook.codex-hooks.json
+    historical_ids: []
+  - id: agentera.registration
+    resource_class: registration
+    migration_scope: v2_upgrade_only
+    resource_ids:
+      - agentera.registration.marketplace.cursor
+      - agentera.registration.plugin.codex
+      - agentera.registration.restorer.codex
+    historical_ids: []
+    identity_evidence:
+      - "Cursor marketplace registration: {project}/.cursor-plugin/plugin.json"
+      - "Codex plugin registration: [plugins.\"agentera@agentera\"] in {home}/.codex/config.toml"
+      - "Codex restorer registration: AGENTERA_HOME in {home}/.codex/config.toml"
+      - "No independent plugin, marketplace, skill, hook, or restorer file was installed for any other host; those former template labels are not resource identities."
+diagnostic_inventory:
+  maximum_resources: 96
+  maximum_file_bytes: 65536
+  resources:
+    - vocabulary: claude.skill-link
+      id: claude.agentera-skill-link
+      destinations:
+        - "{home}/.claude/skills/agentera"
+    - vocabulary: codex.agent-descriptor
+      id: codex.agent-descriptor.{name}
+      names: [status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, orchestrate]
+      destinations:
+        - "{home}/.codex/agents/{name}.toml"
+    - vocabulary: opencode.plugin
+      id: opencode.plugin.agentera
+      destinations:
+        - "{home}/.config/opencode/plugins/agentera.js"
+    - vocabulary: opencode.command
+      id: opencode.command.{name}
+      names: [agentera, hej]
+      destinations:
+        - "{home}/.config/opencode/commands/{name}.md"
+    - vocabulary: legacy.primary-agent
+      id: cursor.agent.agentera
+      destinations:
+        - "{home}/.cursor/agents/agentera.md"
+        - "{project}/.cursor/agents/agentera.md"
+    - vocabulary: legacy.primary-agent
+      id: opencode.agent.agentera
+      destinations:
+        - "{home}/.config/opencode/agents/agentera.md"
+    - vocabulary: legacy.capability-agent
+      id: cursor.agent.{name}
+      names: [audit, build, design, discuss, document, optimize, orchestrate, plan, profile, research, status, vision, dokumentera, hej, inspektera, inspirera, optimera, orkestrera, planera, profilera, realisera, resonera, visionera, visualisera]
+      destinations:
+        - "{home}/.cursor/agents/{name}.md"
+        - "{project}/.cursor/agents/{name}.md"
+    - vocabulary: legacy.capability-agent
+      id: opencode.agent.{name}
+      names: [audit, build, design, discuss, document, optimize, orchestrate, plan, profile, research, status, vision, dokumentera, hej, inspektera, inspirera, optimera, orkestrera, planera, profilera, realisera, resonera, visionera, visualisera]
+      destinations:
+        - "{home}/.config/opencode/agents/{name}.md"
+    - vocabulary: opencode.stale-skill-link
+      id: opencode.skill-link.{name}
+      names: [agentera, status]
+      destinations:
+        - "{home}/.config/opencode/skills/{name}"
+    - vocabulary: installed.hook
+      id: agentera.installed-hook.{name}
+      names: [validate_artifact.py, cursor_session_start.py, cursor_pre_tool_use.py, cursor_session_stop.py, session_start.py, session_stop.py, codex-hooks.json]
+      destinations:
+        - "{install_root}/hooks/{name}"
+    - vocabulary: agentera.registration
+      id: agentera.registration.marketplace.cursor
+      destinations:
+        - "{project}/.cursor-plugin/plugin.json"
+    - vocabulary: agentera.registration
+      id: agentera.registration.plugin.codex
+      destinations:
+        - "{home}/.codex/config.toml"
+      contains: '[plugins."agentera@agentera"]'
+    - vocabulary: agentera.registration
+      id: agentera.registration.restorer.codex
+      destinations:
+        - "{home}/.codex/config.toml"
+      contains: AGENTERA_HOME
 resources:
   - id: claude.agentera-skill-link
+    vocabulary: claude.skill-link
     host: claude
     kind: symlink
     intent: remove
@@ -65,11 +273,14 @@ resources:
       - "{home}/.claude/credentials"
     safety_note: Only the declared Agentera skill symlink may be removed, and only when a matching legacy ownership ledger still binds its identity and target fingerprint. Transcript, settings, credential, conversation, stats, cache, and ambiguous paths are never cleanup targets.
   - id: codex.agent-descriptor
+    vocabulary: codex.agent-descriptor
     host: codex
     kind: file
     intent: remove
     destination: "{home}/.codex/agents/{descriptor}.toml"
     descriptors: [status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, orchestrate]
+    historical_ids:
+      - codex.agents.{descriptor}
     ledger_status: managed
     durable_proof: matching whole-resource ledger identity and fingerprint for each declared descriptor file
     safety_note: Each descriptor is an independently owned file. A managed marker, descriptor name, or matching content never establishes ownership.
@@ -95,3 +306,28 @@ configuration_inventory:
     durable_proof: key-level ownership ledger identity and fingerprint
     ownership_available: false
     result_without_proof: action_required
+cutover_deletion_inventory:
+  schema_version: agentera.v2CutoverDeletionInventory.v1
+  approval_gate: approved_stable_cutover
+  policy: delete_only_after_approved_stable_cutover
+  entries:
+    - path: packages/cli/src/migrate/v2HandoffManifest.ts
+      responsibility: tracked_v2_handoff_preflight
+    - path: packages/cli/src/upgrade/appContentRefresh.ts
+      responsibility: v2_managed_app_content_refresh
+    - path: packages/cli/src/upgrade/compatibility.ts
+      responsibility: v2_install_classification
+    - path: packages/cli/src/upgrade/installedHooksRetirement.ts
+      responsibility: installed_v2_hook_retirement
+    - path: packages/cli/src/upgrade/legacyAgentCleanup.ts
+      responsibility: v2_native_agent_retirement
+    - path: packages/cli/src/upgrade/migrateArtifactsV2ToV3.ts
+      responsibility: v2_project_artifact_migration
+    - path: packages/cli/src/upgrade/runtimeMigration.ts
+      responsibility: v2_native_hook_retirement
+    - path: packages/cli/src/upgrade/versionResolution.ts
+      responsibility: cross_major_v2_upgrade_resolution
+    - path: packages/cli/shim/lib/exec.mjs
+      responsibility: v2_shim_handoff
+    - path: packages/cli/test/upgrade/fixtures/v2-*
+      responsibility: v2_migration_fixtures

package/bundle/references/analysis/evidence-tier-authority.yaml

@@ -440,7 +440,7 @@ compatibility_states:
       reason: oversized
       outcome: degrade
       recovery: >-
-        Refresh bounded tiers with `agentera stats refresh --consent
+        Refresh bounded tiers with `npx -y agentera@next stats refresh --consent
         local-history` or read the signal tier, which is bounded to fit. Do not
         attempt to load the oversized artifact whole.
       determinism: >-
@@ -454,7 +454,7 @@ compatibility_states:
       reason: legacy_monolithic_state
       outcome: degrade
       recovery: >-
-        Emit deterministic refresh guidance: run `agentera stats refresh
+        Emit deterministic refresh guidance: run `npx -y agentera@next stats refresh
         --consent local-history` to publish bounded tiers. Legacy monolithic
         state receives refresh guidance rather than indefinite read
         compatibility.
@@ -467,7 +467,7 @@ compatibility_states:
       reason: no_evidence
       outcome: degrade
       recovery: >-
-        Report `agentera stats refresh --consent local-history` and the
+        Report `npx -y agentera@next stats refresh --consent local-history` and the
         `--corpus PATH` override. Must not auto-build, scan home directories, or
         run live extraction without consent.
       determinism: >-

package/bundle/references/analysis/verification-policy.yaml

@@ -37,6 +37,33 @@ overlap:
     executes_when:
       platform: darwin
 
+# Release source qualification executes this evidence DAG without changing the
+# owner inventories or public commands above. generated-overlap is the only
+# checkout generated-output writer and the only execution origin for source,
+# package, build, and overlap evidence.
+release_qualification:
+  schedule_authority: references/adapters/package-publication.json#qualification.source.dag
+  deadline_authority: references/adapters/package-publication.json#benchmark.timeouts.sourceQualificationMs
+  deadline_behavior: the source coordinator passes the actual absolute deadline;
+    overlap stops new work at the contract cleanup margin, settles owned children,
+    removes its generated state on failure, and returns before the contract parent margin
+  isolation: distinct_home_cache_user_global_config_and_report_per_child
+  resource_isolation: performance_runs_alone_after_batch_a_settles
+  failure:
+    first_observed_owner: preserved
+    cancellable_process_groups: cancel
+    generated_overlap: cooperative_stop_settle_and_cleanup_without_parent_force_kill
+    performance_after_batch_failure: forbidden
+    barrier_b_after_performance_failure: forbidden
+    barrier_b_after_batch_failure: forbidden
+    receipt_after_any_failure: forbidden
+  source_generated_access:
+    checkout_generated_write: forbidden
+    conditional_read_when_present:
+      - packages/cli/.agentera-generated/current/bundle
+    authority: source tests may compare a settled bundled schema when present;
+      they never construct, publish, replace, or clean checkout generated output
+
 owners:
   source:
     config: packages/cli/vite.config.ts
@@ -110,6 +137,12 @@ policies:
 # Pre-commit routing chooses release policy for authority and verification
 # surfaces. All other paths retain the existing targeted source routing.
 conservative_routing:
+  receipt_reuse:
+    environment: AGENTERA_PRECOMMIT_SOURCE_CANDIDATE_DIR
+    command: [node, scripts/release-qualification.mjs, source-check]
+    success: skip_source_or_release_policy_only
+    absent_or_invalid: preserve_existing_policy
+    path_is_authority: false
   exact:
     - .lefthook.yml
     - protocol.yaml
@@ -128,11 +161,26 @@ conservative_routing:
     - packages/cli/scripts/generate-extract-corpus-parity.mjs
     - packages/cli/scripts/verification-barrier.mjs
     - packages/cli/scripts/verify-generated-overlap.mjs
+    - packages/cli/scripts/observe-capability-source.mjs
+    - packages/cli/scripts/observe-runtime-artifact.mjs
     - packages/cli/scripts/pack-package.mjs
     - packages/cli/scripts/package-construction.mjs
     - packages/cli/scripts/reject-direct-prepack.mjs
+    - packages/cli/scripts/publication-transaction.mjs
+    - packages/cli/scripts/release-qualification.mjs
+    - packages/cli/scripts/release-benchmark.mjs
+    - packages/cli/src/validate/activationConjunction.ts
+    - packages/cli/src/validate/activationArtifactEvidence.ts
+    - packages/cli/src/validate/activationEvidenceManifest.ts
+    - packages/cli/src/validate/activationPackageSemantics.ts
+    - packages/cli/src/validate/bootstrapAuthority.ts
+    - packages/cli/src/registries/activationTuples.ts
+    - packages/cli/src/registries/packagePublication.ts
     - packages/cli/test/sourceSetup.ts
     - packages/cli/test/helpers/sourceSubprocess.ts
+    - packages/cli/test/helpers/runtimeBootstrapMatrix.ts
+    - packages/cli/test/helpers/preCutoverBootstrapDispatcher.mjs
+    - packages/cli/test/helpers/runtimeProofCliBoundary.mjs
     - references/analysis/verification-policy.yaml
     - scripts/precommit-vitest.sh
   prefixes:

package/bundle/references/artifacts/artifact-registry-interface-model.yaml

@@ -245,7 +245,7 @@ explicit_special_cases:
     display_name: benchmark_context
     artifact_type: cli_context
     scope: cli_context
-    default_path: agentera prime --context optimize --format json#benchmark_context
+    default_path: npx -y agentera@next prime --context optimize --format json#benchmark_context
     producers:
       - agentera
     consumers:

package/bundle/references/artifacts/glossary-entry-contract.yaml

@@ -156,7 +156,7 @@ ownership_contracts:
       owner: profile_full
       lifecycle_callable: packages/cli/src/analytics/personalGlossaryProfile.ts#updatePersonalGlossaryProfile
       command:
-        canonical: agentera report profile-glossary
+        canonical: npx -y agentera@next report profile-glossary
         namespace: report
         input_flag: --input
         stdin_value: "-"
@@ -169,7 +169,7 @@ ownership_contracts:
           additional_fields: forbidden
           profile_path_rule: >-
             Pass exactly profile_context.profile.path returned by
-            agentera prime --context profile --format json. The command never
+            npx -y agentera@next prime --context profile --format json. The command never
             discovers a profile, project root, or project glossary.
           retained_history_shape: >-
             A list of source_id, evidence_anchor, source_kind, and signal_type
@@ -283,7 +283,7 @@ ownership_contracts:
         is absent or invalid; never invent a field or extend the shared entry.
     publication:
       owner: build
-      command: agentera state glossary publish --input REQUEST --format json
+      command: npx -y agentera@next state glossary publish --input REQUEST --format json
       request:
         schema_version: agentera.glossaryPublicationRequest.v1
         required_fields: [schema_version, proposal, confirmation]
@@ -520,7 +520,7 @@ consumer_boundary:
     runtime: packages/cli/src/analytics/glossaryAdviceResolution.ts#resolveGlossaryAdvice
     mutation: forbidden
     invocation:
-      command: agentera report glossary-advice --input REQUEST --format json
+      command: npx -y agentera@next report glossary-advice --input REQUEST --format json
       request_schema_version: agentera.glossaryAdviceRequest.v1
       request_fields: [schema_version, requested_term, host_review]
       max_request_utf8_bytes: 131072
@@ -848,7 +848,7 @@ consumer_boundary:
       forbidden_fields: [caveat_id, capability, transition_id]
       forbidden_claims: [delivered, stored, persisted, published, durable_envelope]
       durable_writer: build
-      writer_interface: agentera state progress explain --verb append --format json
+      writer_interface: npx -y agentera@next state progress explain --verb append --format json
       writer_result: authoritative_identity_and_six_field_envelope
       allowed_reason_state_pairs: consumer_boundary.autonomous_caveat.allowed_current_pairs
       rule: >-
@@ -978,11 +978,11 @@ consumer_boundary:
     durable_owner: build
     durable_channel: progress
     authority: skills/agentera/schemas/artifacts/progress.yaml#ENTITY_AUTHORITY
-    publication_command: agentera state progress append
+    publication_command: npx -y agentera@next state progress append
     publication_boundary: progress_cycle.glossary_caveat
     publication_status: active_build
     writer_runtime: packages/cli/src/state/progressEntities.ts#appendProgressEntity
-    writer_interface: agentera state progress explain --verb append --format json
+    writer_interface: npx -y agentera@next state progress explain --verb append --format json
     envelope_validator: packages/cli/src/state/progressGlossaryCaveat.ts#validateProgressGlossaryCaveat
     lifecycle_validator: packages/cli/src/state/progressGlossaryCaveat.ts#glossaryCaveatLifecycleInvalidEntities
     allowed_current_pairs:
@@ -1123,7 +1123,7 @@ consumer_boundary:
   downstream_gate:
     status: blocked_until_contract_valid
     validator: packages/cli/src/registries/glossaryEntryContract.ts#validateGlossaryEntryContract
-    command: agentera check validate vocabularyAuthority --format json
+    command: npx -y agentera@next check validate vocabularyAuthority --format json
     required_sections:
       - consumer_boundary.acquisition
       - consumer_boundary.advice_resolution
@@ -1143,7 +1143,7 @@ consumer_boundary:
   profile_grounding:
     implementation: active_exclusion_only
     capabilities: [discuss, plan, build]
-    command: agentera report profile-grounding --format json
+    command: npx -y agentera@next report profile-grounding --format json
     schema_version: agentera.profileGrounding.v1
     parser: packages/cli/src/analytics/personalGlossaryProfile.ts#personalProfileGrounding
     max_profile_utf8_bytes: 65536
@@ -1155,9 +1155,9 @@ consumer_boundary:
       rule: Freshness is computed only after one source passes validity and never changes validity.
     recovery:
       repair: >-
-        Run agentera profile to repair or regenerate PROFILE.md, then retry agentera report profile-grounding --format json; no profile bytes were changed.
+        Use the Profile capability to repair or regenerate PROFILE.md, then retry `npx -y agentera@next report profile-grounding --format json`; no profile bytes were changed.
       absent: >-
-        Run agentera profile to generate PROFILE.md, then retry agentera report profile-grounding --format json.
+        Use the Profile capability to generate PROFILE.md, then retry npx -y agentera@next report profile-grounding --format json.
     raw_profile_read: forbidden
     content_rule: >-
       Return the complete profile with exactly the validated owned personal