agentera 3.0.0-dev.4 → 3.0.0-dev.6

package/README.md

@@ -17,10 +17,11 @@ npx -y agentera@next upgrade --dry-run --channel development
 Run those from a project root. `prime` reports `project_integration.recommendation`
 (`stay` or `upgrade`) and suggested commands for the current repo.
 
-Full preview instructions, highlights, and migration paths:
-[repository README — Agentera 3.0 preview](../../README.md#agentera-30-preview).
+Full preview instructions, channels, and migration paths: [`UPGRADE.md`](../../UPGRADE.md).
 
-Upgrade channels and v2→v3 opt-in: [`UPGRADE.md`](../../UPGRADE.md).
+## Editor runtime installs
+
+Agentera ships a skill bundle for supported editor runtimes (Claude Code, OpenCode, Cursor, Copilot CLI, Codex CLI). Install steps and parity details live in the [repository README — Internals](../../README.md#internals) and [`references/adapters/runtime-feature-parity.md`](../../references/adapters/runtime-feature-parity.md).
 
 ## Package layout
 

package/bundle/.agentera-npx-bundle.json

@@ -1,4 +1,4 @@
 {
   "kind": "agentera-npx-bundle",
-  "suiteVersion": "2.7.6"
+  "suiteVersion": "3.0.0"
 }

package/bundle/references/adapters/opencode.md

@@ -56,7 +56,7 @@ OpenCode skill search paths:
 - Global install: `npx skills add jgabor/agentera -g -a opencode --skill agentera -y`
 - Project install: symlink or copy `skills/agentera/` into `.opencode/skills/agentera/` or `.agents/skills/agentera/`
 
-The temporary `skills/hej/` entry point is a v1 upgrade bridge, not a new-install target. Each Agentera skill entry file already contains YAML frontmatter with `name` and `description`, which matches OpenCode's frontmatter requirements exactly. The OpenCode plugin adds one prompt transformation: when the complete user message is exactly bare text `hej`, `chat.message` rewrites it to load the bundled `agentera` skill and route through the `agentera hej` dashboard path. The match is exact except for OpenCode's CLI-added single trailing newline transport artifact, and does not apply to `/hej`, `Hej`, `hej there`, attachments, or other message parts.
+Each Agentera skill entry file contains YAML frontmatter with `name` and `description`, which matches OpenCode's frontmatter requirements exactly. The OpenCode plugin adds one prompt transformation: when the complete user message is exactly bare text `hej`, `chat.message` rewrites it to load the bundled `agentera` skill and route through the `agentera prime` dashboard path. The match is exact except for OpenCode's CLI-added single trailing newline transport artifact, and does not apply to `Hej`, `hej there`, attachments, or other message parts.
 
 **OpenCode frontmatter validation** requires: `name` (1-64 chars, lowercase alphanumeric with single hyphens), `description` (1-1024 chars). Agentera entry point names are lowercase, matching the validation regex `^[a-z0-9]+(-[a-z0-9]+)*$`.
 

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

@@ -233,7 +233,6 @@ records:
         - .claude-plugin/marketplace.json
         - .opencode/plugins/agentera.js
         - skills/agentera/SKILL.md
-        - skills/hej/SKILL.md
         - registry.json
       index_targets:
         - references/adapters/package-surface-characterization.md

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

@@ -17,7 +17,7 @@ The current version-bearing surfaces are:
 | `plugin.json` | version-bearing surface and runtime package manifest | root Copilot manifest `version` matches the suite version. |
 | `.github/plugin/plugin.json` | version-bearing surface and runtime package manifest | repository Copilot manifest `version` matches the suite version. |
 | `.codex-plugin/plugin.json` | version-bearing surface and runtime package manifest | Codex manifest `version` matches the suite version. |
-| `.claude-plugin/marketplace.json` | version-bearing surface and runtime package manifest | `metadata.version` and every plugin entry version, including the legacy `hej` bridge, match the suite version. |
+| `.claude-plugin/marketplace.json` | version-bearing surface and runtime package manifest | `metadata.version` and the bundled `agentera` plugin entry version match the suite version. |
 | `.opencode/plugins/agentera.js` | version-bearing surface | `AGENTERA_VERSION` matches the registry suite version and drives the OpenCode command marker file `.agentera-version`. |
 
 `.opencode/package.json` is intentionally not version-bearing. Its current behavior is runtime package manifest behavior only: it keeps `type: "module"`, `main`/`exports` pointing at `./plugins/agentera.js`, `dependencies["@opencode-ai/plugin"] == "1.14.33"`, and an `agentera` npm-loadable plugin metadata block, but it has no top-level `name` or `version` field.
@@ -44,5 +44,4 @@ Write gating is preserved: `--update-packages` changes package items from `skipp
 | `.agentera/docs.yaml` `version_files` includes version-bearing surfaces and excludes `.opencode/package.json`. | version-bearing surface | `preserve` | Keep `.opencode/package.json` out of version checks because it is a runtime package manifest, not a suite version surface. |
 | `.opencode/package.json` is force-included and bundled, but it is not in docs `version_files`. | runtime package manifest | `preserve` | Keep packaging it without treating it as version-bearing. |
 | Upgrade package commands are represented as argv lists for Claude Code and OpenCode only; Codex and Copilot have runtime manifests but no package-manager command entries. | package-manager command surface | `preserve` | Keep command planning limited to currently managed package runtimes. |
-| `.claude-plugin/marketplace.json` carries a `hej` legacy bridge version alongside `agentera`. | version-bearing surface | `defer` | Keep the legacy bridge version aligned until a separate legacy-bridge removal or marketplace simplification task exists. |
 | Live package-manager behavior is not characterized by this task. | package-manager command surface | `defer` | Keep tests mocked; do not introduce live `npx skills` execution. |

package/bundle/references/analysis/startup-measurement-contract.yaml

@@ -362,17 +362,17 @@ privacy_boundary:
     - canonical_event_class
     - salted_non_reconstructable_hash
   canonical_artifact_labels:
-    TODO.md: TODO.md
-    CHANGELOG.md: CHANGELOG.md
-    DESIGN.md: DESIGN.md
-    PLAN.md: PLAN.md
-    PROGRESS.md: PROGRESS.md
-    DOCS.md: DOCS.md
-    DECISIONS.md: DECISIONS.md
-    HEALTH.md: HEALTH.md
-    VISION.md: VISION.md
-    OBJECTIVE.md: OBJECTIVE.md
-    EXPERIMENTS.md: EXPERIMENTS.md
+    todo: todo
+    changelog: changelog
+    design: design
+    plan: plan
+    progress: progress
+    docs: docs
+    decisions: decisions
+    health: health
+    vision: vision
+    objective: objective
+    experiments: experiments
     AGENTS.md: AGENTS.md
     SKILL.md: SKILL.md
     AGENTERA_ARTIFACTS: AGENTERA_ARTIFACTS

package/bundle/references/cli/agent-ready-state-contract.yaml

@@ -282,10 +282,10 @@ structured_output:
             contract can summarize planning levels, step markers, CLI-first
             orientation, raw plan artifact boundaries, full-plan review/self-audit
             requirements, handoff expectations, and the Planera prose authority
-            boundary without reading `planera/instructions.md` at runtime. It must
-            not introduce `agentera planera`, new top-level commands, or hidden
-            capability-name aliases; `agentera schema` owns runtime/schema
-            introspection rather than a capability workflow payload.
+            boundary without reading `packages/cli/src/capabilities/planera/instructions.ts`
+            at runtime. It must not introduce `agentera planera`, new top-level
+            commands, or hidden capability-name aliases; `agentera schema` owns
+            runtime/schema introspection rather than a capability workflow payload.
           orchestration_context_semantics: >-
             `agentera prime --context orkestrera --format json` may include
             orchestration_context with dependency-ready tasks, blocked task reasons,
@@ -465,7 +465,7 @@ evidence_context_target_contract:
         verified_field: header.status=complete
       - reason: Inspektera prose and schemas are validated directly; complete evidence_context covers normal evaluation startup without raw plan/progress/docs/health/TODO/decisions reads.
         paths:
-          - skills/agentera/capabilities/inspektera/instructions.md
+          - packages/cli/src/capabilities/inspektera/instructions.ts
           - skills/agentera/capabilities/inspektera/schemas/artifacts.yaml
           - skills/agentera/capabilities/inspektera/schemas/validation.yaml
         raw_artifact_reads_required_for_startup: false

package/bundle/references/cli/audience-namespace-cli-migration.yaml

@@ -204,9 +204,10 @@ prime_hej_schema_migration_boundary:
   prime_absorbs_hej:
     status: target
     hej_cli: >-
-      Top-level `hej` is removed from the public parser after the alias period.
-      `agentera hej` prints one stderr deprecation naming `prime` and delegates
-      during Phase 1–2.
+      Top-level `hej` is removed from the npm 3.x public parser and dispatch.
+      During Phase 1–2, `agentera hej` printed one stderr deprecation naming
+      `prime` and delegated; Phase 3 on the development channel rejects the
+      command with an unsupported-target envelope.
     hej_skill_route: >-
       Bare `hej` in the Agentera skill still routes to orientation, but the installed
       CLI gate calls `agentera prime` and renders from that composite result.
@@ -225,8 +226,9 @@ prime_hej_schema_migration_boundary:
     status: target
     canonical: agentera schema [--format json|yaml]
     alias: >-
-      `agentera describe` prints one stderr deprecation naming `schema` and delegates
-      during Phase 1–2.
+      Top-level `describe` is removed from the npm 3.x public parser and dispatch.
+      During Phase 1–2, `agentera describe` printed one stderr deprecation naming
+      `schema` and delegated.
     discovery_ownership: >-
       `schema` owns runtime CLI/schema introspection formerly on `describe`, including
       command tree, audience tags, artifact locations, and linked contract sections.
@@ -260,7 +262,9 @@ plan_routing_distinction:
       is not a CLI command and does not read `.agentera/plan.yaml` by itself.
   state_read:
     invocation: agentera state plan
-    legacy_alias: agentera plan
+    legacy_alias: >-
+      Top-level `agentera plan` was removed on the npm 3.x CLI in Phase 3; use
+      `agentera state plan`.
     surface: CLI routine state read
     meaning: >-
       Read-only access to the active plan artifact summary, tasks, acceptance
@@ -275,8 +279,8 @@ plan_routing_distinction:
       for Planera remains `agentera prime --context planera --format json`.
   agent_guidance: >-
     Use `/agentera plan` when the user wants planning work routed to Planera; use
-    `agentera state plan` (or legacy `agentera plan`) when the agent needs plan
-    artifact state; use `agentera planera` for capability routing guidance; use
+    `agentera state plan` when the agent needs plan artifact state; use
+    `agentera planera` for capability routing guidance; use
     `agentera prime --context planera` for bounded Planera startup context.
 migration_phases:
   phase_1:
@@ -295,15 +299,18 @@ migration_phases:
       - Record measurement evidence for JSON surface moves.
   phase_3:
     name: remove_deprecated_top_level_parsers
+    status: shipped_on_development_channel
     actions:
       - >-
-        Remove `hej`, public `describe`, and `gate` from top-level parser help.
+        Remove `hej`, public `describe`, and `gate` from top-level parser help
+        and dispatch on the npm 3.x CLI.
       - >-
-        Remove other deprecated top-level parsers except documented capability and
-        lifecycle names and the Phase 1–2 alias set until post-major cleanup.
+        Remove routine-state top-level parsers (`plan`, `progress`, `health`,
+        `todo`, `decisions`, `docs`, `objective`, `experiments`) from help and
+        dispatch on the npm 3.x CLI.
       - >-
-        Deferred final removal of all routine-state top-level aliases after one
-        minor alias release.
+        Keep a transitional stderr-alias set (`validate`, `compact`, `verify`,
+        `stats`, `lint`, `query`) until post-cutover cleanup.
 alias_policy:
   stderr_format: one-line deprecation naming the canonical command
   delegation: forward to canonical handler with unchanged JSON/text envelopes
@@ -334,22 +341,29 @@ command_tree_target:
     - report [user]
     - check [maintainer]
 
-deprecated_top_level_aliases:
-  # Command aliases that emit stderr deprecation warnings
-  - { legacy: hej, canonical: prime }
-  - { legacy: describe, canonical: schema }
-  - { legacy: plan, canonical: "state plan" }
-  - { legacy: progress, canonical: "state progress" }
-  - { legacy: health, canonical: "state health" }
-  - { legacy: todo, canonical: "state todo" }
-  - { legacy: decisions, canonical: "state decisions" }
-  - { legacy: docs, canonical: "state docs" }
-  - { legacy: objective, canonical: "state objective" }
-  - { legacy: experiments, canonical: "state experiments" }
+removed_top_level_commands:
+  # Phase 3 on npm 3.x: removed from help and dispatch (unsupported_target)
+  - hej
+  - describe
+  - gate
+  - plan
+  - progress
+  - health
+  - todo
+  - decisions
+  - docs
+  - objective
+  - experiments
+
+transitional_stderr_aliases:
+  # Still delegate with one-line stderr deprecation on npm 3.x
   - { legacy: query, canonical: "state query" }
   - { legacy: compact, canonical: "check compact" }
-  - { legacy: gate, canonical: "check compact" }
   - { legacy: verify, canonical: "check verify" }
   - { legacy: stats, canonical: report }
   - { legacy: lint, canonical: "check lint" }
   - { legacy: validate, canonical: "check validate" }
+
+# Superseded by `removed_top_level_commands` and `transitional_stderr_aliases`
+# for npm 3.x Phase 3 (empty list retained for contract migration readers).
+deprecated_top_level_aliases: []

package/bundle/references/cli/bundle-skill-vocabulary.yaml

@@ -14,7 +14,7 @@ scope:
     - Package and distribution metadata that names the suite package shape.
     - Runtime hook packaging prose and metadata for plugin-shipped hooks.
     - Historical references to the removed `bundle-status` command.
-    - Current and legacy references to `skills/agentera/SKILL.md` and v1 skill entry files.
+    - Current references to `skills/agentera/SKILL.md`.
   excludes:
     - Routing and execution vocabulary collapse work.
     - Capability instruction-file rename work.
@@ -32,8 +32,6 @@ canonical_concept_order:
   - removed_bundle_status_command
   - agentera_routing_entry
   - skill_entry_file
-  - v1_skill_entry_file
-  - legacy_hej_bridge
 canonical_concepts:
   agentera_app_files:
     definition: >-
@@ -119,32 +117,6 @@ canonical_concepts:
       - SKILL.md
       - skill file
       - skill entry
-  v1_skill_entry_file:
-    definition: >-
-      A historical standalone v1 skill entry file or path retained in migration
-      notes, tests, stale-path checks, and compatibility fixtures.
-    allowed_terms:
-      - v1 skill entry file
-      - v1 standalone skill entry file
-      - "historical v1 `SKILL.md` file"
-      - v1 skill path
-    forbidden_ambiguous_shortcuts:
-      - SKILL.md
-      - v1 SKILL.md
-      - old skill file
-  legacy_hej_bridge:
-    definition: >-
-      The temporary v1 `/hej` bridge or exact bare `hej` compatibility path that
-      guides users toward `/agentera` and the v2 upgrade path.
-    allowed_terms:
-      - legacy hej bridge
-      - "legacy `/hej` bridge"
-      - v1 hej bridge
-      - "bare `hej` compatibility path"
-    forbidden_ambiguous_shortcuts:
-      - hej skill
-      - legacy skill
-      - old hej
 classification_order:
   - canonical_concept
   - compatibility_identifier
@@ -194,7 +166,7 @@ focused_scan:
     - (retired maintainer measurement tool)
     - skills/agentera/SKILL.md
     - skills/agentera/capabilities/hej/schemas/triggers.yaml
-    - skills/agentera/capabilities/resonera/instructions.md
+    - packages/cli/src/capabilities/resonera/instructions.ts
     - tests/test_cross_capability.py
     - tests/test_resonera_capability.py
     - tests/test_runtime_adapters.py

package/bundle/references/cli/capability-instruction-contract.yaml

@@ -3,9 +3,10 @@ status: active_authority
 decision: 57
 purpose: >-
   Define the Decision 57 capability instruction-file contract: the canonical
-  `instructions.md` file name, implemented CLI/schema first-invocation read
-  discoverability, compact-startup exception boundaries, and runtime behavior
-  that remains intentionally unsupported.
+  `instructions.ts` module path, implemented CLI/schema first-invocation read
+  discoverability, the `prime_context` runtime-enforcement boundary, and
+  retirement of the historical `full`/`compact_startup`/`skip` values
+  superseded by Decision 65.
 sources:
   decision: .agentera/decisions.yaml#decision-57
   prose:
@@ -13,91 +14,87 @@ sources:
     - README.md#development
 scope:
   includes:
-    - Documentation authority for the implemented capability instruction-file name.
+    - Documentation authority for the implemented capability instruction module path.
     - CLI/schema discoverability for first capability invocation startup-read metadata.
-    - Compact-startup exception semantics and boundaries.
-    - Current canonical references to existing `instructions.md` files.
+    - The single `prime_context` first-invocation shape enforced by the runtime.
+    - Current canonical references to existing `instructions.ts` modules.
     - Explicit separation from runtime behavior work.
   excludes:
     - Implementing first-invocation read behavior.
     - Marking Decision 57 satisfied or editing protected vision/objective/profile/installed-app state.
 current_state:
   canonical_instruction_file:
-    path: skills/agentera/capabilities/<name>/instructions.md
+    path: packages/cli/src/capabilities/<name>/instructions.ts
     status: current_canonical_implemented
     definition: >-
-      The human-readable instruction file for each capability.
+      The TypeScript module that exports the capability's behavioral
+      instructions as a default-exported string constant. The runtime loads
+      the compiled .js path and serves the prose through the slim
+      `capability_context` capsule's `prose` field.
   legacy_instruction_file:
+    path: skills/agentera/capabilities/<name>/instructions.md
+    status: historical_or_compatibility_evidence_only
+    definition: >-
+      The pre-D65 Markdown instruction filename. It may survive only in
+      archived history, compatibility fixtures, benchmark evidence, or
+      explicit migration documentation; real capability directories do not
+      use it as canonical.
+  legacy_prose_file:
     path: skills/agentera/capabilities/<name>/prose.md
     status: historical_or_compatibility_evidence_only
     definition: >-
-      The former capability instruction filename. It may survive only in archived
-      history, compatibility fixtures, benchmark evidence, or explicit migration
-      documentation; real capability directories do not use it as canonical.
+      The pre-D57 capability instruction filename. It may survive only in
+      archived history, compatibility fixtures, benchmark evidence, or
+      explicit migration documentation; real capability directories do not
+      use it as canonical.
   validator_requirement:
-    current_required_path: instructions.md
-    future_required_path: instructions.md
+    current_required_path: packages/cli/src/capabilities/<name>/instructions.ts
+    future_required_path: packages/cli/src/capabilities/<name>/instructions.ts
     status: current_requirement_enforced
   cli_metadata:
     field: first_invocation_read
     status: emitted_in_prime_capability_context
     current_behavior: >-
       `agentera prime --context <name> --format json` emits
-      `capability_context` metadata including `first_invocation_read` for
-      supported capabilities. Historical `hej --capability-context` is removed in 3.0.
+      `capability_context` metadata including `first_invocation_read`
+      (value: `prime_context`, runtime_enforcement: true) and the full prose
+      in the `prose` field for supported capabilities. Historical
+      `hej --capability-context` is removed in 3.0.
 first_invocation_read:
-  field_status: cli_schema_discoverability_implemented
+  field_status: runtime_enforced
   definition: >-
-    Capability metadata declaring what instruction content an agent must read on
-    the first invocation of that capability in a session.
+    Capability metadata declaring what instruction content an agent must
+    read on the first invocation of that capability in a session. Decision
+    65 collapses the legacy `full`/`compact_startup` distinction into a
+    single `prime_context` value because the CLI now owns the prose and
+    the runtime can mechanically shell out to the prime command.
   allowed_values:
-    full:
-      meaning: >-
-        The first capability invocation must read `instructions.md` in full before
-        executing capability-specific work.
-      obligation: full_instruction_file_read_required
-    compact_startup:
-      meaning: >-
-        A declared compact startup contract may satisfy initial orientation without
-        reading the full instruction file first.
-      obligation: compact_contract_must_name_covered_guidance_and_escalation_rules
-    skip:
+    prime_context:
       meaning: >-
-        No first-invocation instruction read is required for the declared scope.
-      obligation: requires_explicit_contract_justification
-      caution: >-
-        Reserved for narrow future surfaces; not a default and not implemented by
-        this authority.
-  default_rule: full
+        The first capability invocation must shell out to
+        `agentera prime --context <name> --format json` and read the
+        returned `prose` field (the full Markdown body) before executing
+        capability-specific work.
+      obligation: shell out to agentera prime --context <name> --format json
+  default_rule: prime_context
   full_read_obligation: >-
-    On initial capability invocation, read `instructions.md` in full unless that
-    capability declares a compact-startup exception with explicit coverage and
-    escalation boundaries.
-compact_startup_exception:
-  status: implemented_for_planera_compact_startup_discoverability
-  allowed_when:
-    - A machine-readable startup contract is available through supported state access.
-    - The compact contract states which instruction topics it covers.
-    - The compact contract states when the agent must escalate to a full instruction-file read.
-    - The compact contract preserves unsupported-command and raw-artifact-read boundaries.
-  not_allowed_when:
-    - The agent is editing the capability's own instructions or schemas.
-    - The compact contract is missing, incomplete, stale, or contradictory.
-    - The requested work touches behavior not covered by the compact contract.
-    - Safety rails, validation, exit semantics, or cross-capability boundaries are ambiguous.
+    On initial capability invocation, shell out to
+    `agentera prime --context <name> --format json` and read the
+    `capability_context.prose` field in full.
 implementation_state:
-  instructions_md_files: renamed
-  validators_require_instructions_md: true
+  instructions_ts_modules: implemented
+  validators_require_instructions_ts: true
   first_invocation_read_cli_metadata: true
   first_invocation_read_schema_metadata: true
-  runtime_first_invocation_behavior: false
-  descriptors_rewritten_to_instructions_md: true
-  package_metadata_rewritten_to_instructions_md: true
+  runtime_first_invocation_behavior: true
+  descriptors_rewritten_to_prime_command: true
+  package_metadata_rewritten_to_prime_command: true
 compatibility_preservation:
   preserve_legacy_references_only_when_classified:
-    - skills/agentera/capabilities/*/instructions.md paths
+    - skills/agentera/capabilities/*/instructions.md paths (historical)
+    - packages/cli/src/capabilities/*/instructions.ts paths (current canonical)
     - skills/agentera/capability_schema_contract.yaml directory requirements
-    - runtime descriptors and generated agent guidance that point to `instructions.md`
+    - runtime descriptors and generated agent guidance that point to `instructions.md` (retired)
     - archived v1/v2 migration records and progress evidence
     - compatibility fixtures and tests that intentionally preserve old behavior evidence
     - README, AGENTS, and vocabulary references that explicitly describe the current canonical state
@@ -116,6 +113,50 @@ surface_inventory:
   capability_schema_contract: current_canonical_validator_reference
   runtime_descriptors: current_canonical_instructions_md_pointers
   capability_instruction_files: current_canonical_instruction_files
+evaluator_handoff:
+  status: implemented
+  purpose: >-
+    Define the inspektera evaluation report schema and citation requirements
+    for orkestrera Step 3 Surface 2 delegations and post-plan health checks.
+  report_schema_version: agentera.inspekteraEvaluationReport.v1
+  row_schema:
+    required_fields:
+      - criterion
+      - status
+      - evidence
+    status_values:
+      - PASS
+      - WARN
+      - FAIL
+    citation_required_for:
+      - WARN
+      - FAIL
+    citation_formats:
+      file_line:
+        pattern: "^[^:\\s]+:\\d+$"
+        description: Relative repo path with 1-based line number, e.g. TODO.md:15
+      not_applicable:
+        prefix: "not-applicable:"
+        min_reason_length: 8
+        description: >-
+          Use when no file anchor exists; prefix with not-applicable: and give a
+          concrete reason (at least 8 characters after the prefix).
+    warn_verify_command:
+      required_when: file_line_citation
+      allowed_prefixes:
+        - grep
+        - git show
+      description: >-
+        WARN rows with a file:line citation MUST include verify_command with the
+        exact grep or git show invocation that reproduces the evidence at the
+        cited line.
+  orchestration_context_fields:
+    output_requirements:
+      citation_required_for:
+        - WARN
+        - FAIL
+      warn_verify_command_required: true
+      schema_authority: references/cli/capability-instruction-contract.yaml#evaluator_handoff
 docs_delegation:
   document: references/cli/vocabulary.md
   required_anchor: Capability instruction contract

package/bundle/references/cli/coexistence-probe.yaml

@@ -0,0 +1,9 @@
+# v2/v3 coexistence doctor warning contract (both CLI lines).
+schema_version: agentera.coexistenceProbe.v1
+section_header: Coexistence
+warning:
+  headline: "v3 detected alongside v2; pick one line"
+  resolutions:
+    - complete v3 migration
+    - uninstall v3
+    - stay on v2 explicitly

package/bundle/references/cli/routing-execution-vocabulary.yaml

@@ -171,9 +171,9 @@ focused_scan:
     - (retired maintainer measurement tool)
     - skills/agentera/SKILL.md
     - skills/agentera/references/contract.md
-    - skills/agentera/capabilities/realisera/instructions.md
-    - skills/agentera/capabilities/optimera/instructions.md
-    - skills/agentera/capabilities/orkestrera/instructions.md
+    - packages/cli/src/capabilities/realisera/instructions.ts
+    - packages/cli/src/capabilities/optimera/instructions.ts
+    - packages/cli/src/capabilities/orkestrera/instructions.ts
     - tests/test_skill_dispatch_contract.py
     - tests/test_runtime_adapters.py
     - tests/test_runtime_adapter_registry.py
@@ -222,15 +222,15 @@ focused_scan:
       text: checkpoint before worktree dispatch
       classification: compatibility-preserved
       reason: The contract preserves the parseable historical checkpoint commit message string.
-    - path: ^skills/agentera/capabilities/realisera/instructions\.md$
+    - path: ^packages/cli/src/capabilities/realisera/instructions\.ts$
       text: 'Step 5: Dispatch|checkpoint before worktree dispatch'
       classification: compatibility-preserved
       reason: Realisera preserves the current step heading and checkpoint commit message compatibility string.
-    - path: ^skills/agentera/capabilities/optimera/instructions\.md$
+    - path: ^packages/cli/src/capabilities/optimera/instructions\.ts$
       text: checkpoint before worktree dispatch
       classification: compatibility-preserved
       reason: Optimera preserves the current checkpoint commit message compatibility string.
-    - path: ^skills/agentera/capabilities/orkestrera/instructions\.md$
+    - path: ^packages/cli/src/capabilities/orkestrera/instructions\.ts$
       text: review pressure in dispatch|dispatch/evaluation context|`dispatch` and `chain` are autonomous orchestration verbs
       classification: canonical
       reason: Orkestrera capability prose uses dispatch for its explicitly owned orchestration loop.

package/bundle/references/cli/single-name-protocol.yaml

@@ -0,0 +1,42 @@
+schema_version: agentera.single_name_protocol.v1
+status: active_authority
+decision: 58
+purpose: >-
+  Machine-readable Decision 58 boundary: forbidden legacy protocol identifiers
+  and scan surfaces for the single-name protocol regression test.
+human_index:
+  document: references/cli/vocabulary.md
+forbidden_protocol_substrings:
+  - pattern: instruction_file
+    rationale: D65 renamed DIRECTORY_REQUIREMENTS and contract fields to instruction_module.
+  - pattern: canonical_instruction_file
+    rationale: Use canonical_instruction_module in capability-instruction-contract.yaml.
+  - pattern: legacy_instruction_file
+    rationale: Historical paths belong in archive or migration modules only.
+  - pattern: instructionPath
+    rationale: capabilityContract loader exposes instructionModulePath only.
+forbidden_storage_protocol_markdown_artifacts:
+  - PROGRESS.md
+  - PLAN.md
+  - DECISIONS.md
+  - VISION.md
+  - HEALTH.md
+  - DOCS.md
+  - OBJECTIVE.md
+  - EXPERIMENTS.md
+scan_roots:
+  - packages/cli/src
+  - skills/agentera/capability_schema_contract.yaml
+  - skills/agentera/protocol.yaml
+  - references/cli/capability-instruction-contract.yaml
+  - references/cli/vocabulary.md
+  - references/cli/vocabulary-index.yaml
+  - registry.json
+scan_exclude_globs:
+  - "**/capabilities/**/instructions.ts"
+  - "**/migrateArtifactsV1ToV2.ts"
+  - "**/migrateArtifactsV2ToV3.ts"
+  - "**/migrateArtifacts*.ts"
+  - "**/*.test.ts"
+  - "**/test/**"
+comment_line_exempt: true

package/bundle/references/cli/update-channels.yaml

@@ -33,6 +33,22 @@ channels:
       Tracks the supported 2.x release line for users who must not cross the v2→v3
       major boundary without explicit opt-in.
     distribution_major: 2
+    next_major:
+      concept: forward_successor_line
+      channel: development
+      version: "3.0.0"
+      announced: false
+      npm:
+        dist_tag: next
+      npm_only_advisory: >-
+        The successor line is npm-only; stable git/uvx installs remain on the
+        supported 2.x line until you explicitly opt in through npm.
+      guide_url: >-
+        https://github.com/jgabor/agentera/blob/main/UPGRADE.md#upgrading-v2-to-v3-development-channel-irreversible
+      preview_command: npx -y agentera@next upgrade --dry-run --channel development
+      irreversible_advisory: >-
+        Forward migration to the successor line is one-way; return to the prior
+        Python support line is permanently unsupported.
     resolution:
       npm:
         dist_tag: latest
@@ -127,8 +143,8 @@ version_resolution:
   latest_on_channel:
     resolver: npm_dist_tag_with_offline_defaults
     offline_defaults:
-      stable: "2.7.6"
-      development: "3.0.0-dev.4"
+      stable: "2.7.7"
+      development: "3.0.0"
   irreversibility:
     downgrade_to_v2: permanently_blocked
     supported_downgrade_lines: []