agentera 3.0.0-dev.3 → 3.0.0-dev.31

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

@@ -2,7 +2,7 @@ schema_version: agentera.routing_execution_vocabulary.v1
 status: active_authority
 purpose: >-
   Define routing and execution vocabulary boundaries so request routing, next-action
-  recommendation, Orkestrera task assignment, worker launch, runtime support, and
+  recommendation, Orkestrera task assignment, worker launch, host-provided worker support, and
   worker-safety Git commits stay distinct without forcing mechanical renames of
   shipped compatibility identifiers or historical evidence.
 sources:
@@ -14,7 +14,7 @@ scope:
     - Hej and capability next-action recommendations that wait for confirmation.
     - Orkestrera assignment of approved plan work to worker capabilities.
     - Realisera and Optimera launch of runtime workers.
-    - Runtime subagent support mechanisms and compatibility identifiers.
+    - Host-provided worker mechanisms without Agentera-owned runtime integration.
     - Git commit safety language before spawning isolated worker execution.
   excludes:
     - Broad current-prose replacement across capability instructions.
@@ -31,7 +31,7 @@ compatibility_boundary: >-
 canonical_concept_order:
   - request_to_capability_routing
   - next_action_recommendation
-  - orkestrera_task_assignment
+  - orchestrate_task_assignment
   - worker_launch
   - runtime_subagent_support
   - worker_safety_git_commit
@@ -40,7 +40,7 @@ canonical_concepts:
     definition: >-
       Agentera chooses the capability that should handle a user request, using
       direct routes, primary route aliases, trigger schemas, disambiguation, or
-      fallback to hej.
+      fallback to status.
     preferred_terms:
       - Agentera router
       - request-to-capability routing
@@ -65,15 +65,15 @@ canonical_concepts:
       - force
       - chain
       - conductor handoff
-  orkestrera_task_assignment:
+  orchestrate_task_assignment:
     definition: >-
-      Orkestrera assigns approved plan work to a worker capability during an
+      Orchestrate assigns approved plan work to a worker capability during an
       explicitly orchestrated flow; it evaluates the result instead of implementing
       the task itself.
     preferred_terms:
       - delegate
       - delegation
-      - Orkestrera task delegation
+      - Orchestrate task delegation
       - assigned plan work
     forbidden_ambiguous_shortcuts:
       - conductor
@@ -82,7 +82,7 @@ canonical_concepts:
       - orchestrator implementation
   worker_launch:
     definition: >-
-      Realisera or Optimera starts a worker through the host runtime when an
+      Build or Optimize starts a worker through the host runtime when an
       implementation or measurement cycle needs isolated execution.
     preferred_terms:
       - spawn
@@ -96,8 +96,8 @@ canonical_concepts:
       - launch substrate
   runtime_subagent_support:
     definition: >-
-      Runtime-specific support that lets Agentera use a host's subagent surface,
-      descriptor model, or equivalent worker mechanism.
+      A worker mechanism supplied by the coding host. Agentera may request a
+      worker but ships no host-specific descriptor, adapter, plugin, or hook.
     preferred_terms:
       - subagent mechanism
       - runtime subagent mechanism
@@ -167,13 +167,12 @@ focused_scan:
   paths:
     - AGENTS.md
     - references/cli/vocabulary.md
-    - references/adapters/runtime-feature-parity.md
     - (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
@@ -198,10 +197,6 @@ focused_scan:
       text: subagent_dispatch|fixture names
       classification: compatibility-preserved
       reason: Routing vocabulary docs preserve explicit compatibility identifiers and fixture terminology.
-    - path: ^references/adapters/runtime-feature-parity\.md$
-      text: prompt rewrite router|Subagent Dispatch|Dispatch surface|Capability dispatch|subagent dispatch
-      classification: compatibility-preserved
-      reason: Runtime parity docs name concrete host and compatibility surfaces around descriptor dispatch support.
     - path: ^scripts/measure_token_payload\.py$
       text: static dispatch payload|Agentera router
       classification: historical
@@ -222,15 +217,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.
@@ -238,27 +233,10 @@ focused_scan:
       text: '`dispatch`: invoke another capability autonomously|`chain`: dispatch multiple capabilities autonomously|In orkestrera only, `dispatch` and `chain` are autonomous'
       classification: fixture-only
       reason: Skill dispatch contract tests assert the canonical Orkestrera dispatch reservation.
-    - path: ^tests/test_runtime_adapters\.py$
-      text: opencode bare-hej router|routeBareHejMessage|subagent_dispatch
-      classification: fixture-only
-      reason: Runtime adapter tests assert plugin routing helpers and compatibility identifier fixtures.
-    - path: ^tests/test_runtime_adapter_registry\.py$
-      text: subagent_dispatch
-      classification: code-identifier
-      reason: Runtime adapter registry tests preserve the shipped subagent_dispatch field name.
 compatibility_identifiers:
-  runtime_adapter:
-    - subagent_dispatch
-    - RuntimeAdapter.subagent_dispatch
-    - subagent_dispatch.supported
-    - subagent_dispatch.group
   route_aliases:
     - ROUTE_ALIASES
     - primary_aliases
-  command_and_schema_surfaces:
-    - agentera validate descriptors
-    - descriptor_sources
-    - invocation_pattern
 code_identifiers:
   - subagent_dispatch
   - test_runtime_adapter_subagent_dispatch_metadata_is_complete

package/bundle/references/cli/routing-model.md

@@ -0,0 +1,139 @@
+# Hybrid routing model
+
+The portable shared skill and CLI use one hybrid cascade. Explicit routes and
+curated, globally unique literal phrases provide deterministic tiers; open-ended
+language remains host-owned. The normative protocol is
+[`hybrid-route-contract.yaml`](./hybrid-route-contract.yaml); this page is a
+reader-oriented model, not a second contract.
+
+Decision 76 remains in force for natural-language judgment. Decision mpulyomlyl supersedes it only for the curated literal fast path: there is still no scoring engine, no confidence threshold, and no borderline band. Legacy trigger patterns, regexes, thresholds, and bands do not route requests.
+
+## Cascade and precedence
+
+1. **Bare `/agentera`.** With no added text, select status deterministically.
+2. **Explicit direct route.** A canonical capability name or primary alias uses
+   the established direct-route grammar and passes its remaining text as topic.
+3. **Curated leading phrase.** Match one active phrase from
+   [`skills/agentera/route-phrases.yaml`](../../skills/agentera/route-phrases.yaml)
+   only when it is the exact normalized leading phrase. It selects that phrase's
+   sole owner and preserves the original remainder as topic.
+4. **Deterministic abstention.** Every other request returns
+   `semantic_required`. This tier never guesses from trigger prose, substrings,
+   regexes, scores, thresholds, bands, state, or `next_action`.
+5. **Validated semantic receipt.** The host makes an LLM-native semantic
+   judgment and submits `select`, `clarify`, or `no_match`; the CLI validates it
+   before capability startup. `select` starts one selected capability, `clarify` starts none, and `no_match` must route to status for orientation only after no capability matches.
+
+The direct grammar has precedence over phrase matching. A phrase collision is a
+registry validation error, not a tie to resolve at runtime.
+
+## Phase one: route request
+
+`agentera.route_request.v1` takes the transient original request. Its response
+is exactly one of:
+
+- `deterministic_selection`: a `bare`, `direct`, or `phrase` selection with
+  capability, provenance, recognized span, and topic span.
+- `semantic_required`: a request digest, semantic intent capsule, and canonical
+  capsule digest. It does not start a capability.
+
+The request itself is not persisted. The semantic capsule contains active
+trigger `description`, `priority`, and `disambiguates_against` documentation,
+not executable matcher inputs. Its digest is SHA-256 over contract-owned
+canonical JSON (recursively sorted object keys, no insignificant whitespace,
+and the presented array order) for exactly that capsule. It excludes private
+request text, request digests, diagnostics, state, and matcher authorities the
+host did not see.
+
+## Phase two: semantic receipt
+
+For `semantic_required`, the host sends the same transient original request and
+the complete nullable host receipt to `agentera route receipt --input - --format
+json`. The receipt binds to the SHA-256 of the request's UTF-8 bytes and the
+`semantic_capsule_sha256` returned in phase one. The CLI first validates the
+unmodified host shape, removes only contract-listed nulls, then reruns
+deterministic routing and accepts the receipt only when the same request still
+produces `semantic_required` with both bound digests. It then validates the
+projected CLI receipt with canonical-capability binding and request-bound span
+rules:
+
+| Receipt | Required result | Startup |
+| --- | --- | --- |
+| `select` | one canonical capability and `none` or `preserve` compound disposition | selected capability only |
+| `clarify` | one non-empty question | none |
+| `no_match` | no capability or question | status only |
+| invalid | bounded field-level correction, exit 64 | none |
+
+The resulting `selected` or `status_fallback` authorization contains bounded
+route provenance and the existing `agentera prime --context <capability>
+--format json` startup path. A `clarification` contains exactly one bounded
+question and no startup. This is intentionally a shared CLI contract, not a
+runtime-specific adapter. The portable shared skill is the sole host integration
+surface.
+
+## Phrase, span, and topic behavior
+
+The phrase registry owns stable IDs, capability ownership, literal phrases,
+global collision detection, and deprecation. Per-capability trigger schemas
+never create phrase ownership. Matching uses the contract's normalized token
+view (Unicode NFKC, case folding, whitespace normalization) while returning
+source UTF-8 byte offsets and exact slices from the original request. A `:`,
+`-`, or `—` that terminates the final phrase token is recognized in the
+comparison view but starts the preserved topic slice; other attached
+punctuation abstains.
+
+For example, `HELP\tME decide: migrate the store` recognizes only
+`HELP\tME decide`; its topic is the exact original `: migrate the store`.
+The separator is deliberately preserved. Quoted, negated, later-in-sentence,
+partial, and unregistered wording abstains; it belongs to the semantic phase.
+
+## Selection, ambiguity, and compounds
+
+The LLM host owns semantic selection and genuine consequential ambiguity. It
+consults trigger intent documentation, then chooses one of `select`, `clarify`,
+or `no_match`. A compound request never authorizes implicit chaining:
+
+- A direct or phrase selection preserves its entire original remainder as one
+  topic without interpreting it as follow-on work.
+- A semantic `select` may mark one original, UTF-8 code-point-aligned trailing
+  remainder span `preserve`; it is deferred intent, not a second startup.
+  `clarify` is an outcome, never a compound disposition.
+- Independent or consequential compound intent uses the `clarify` outcome when
+  one primary capability cannot be named safely.
+
+`next_action` informs readiness only after classification and cannot override the message intent. It never classifies a request.
+
+## Evaluation and privacy
+
+The visible frozen development and adversarial regression data live in
+[`fixtures/routing/hybrid-corpus.yaml`](../../fixtures/routing/hybrid-corpus.yaml).
+They use synthetic or explicitly consented text only and are the sole frozen
+implementation conformance corpus; no sealed holdout, credential, privacy
+approval, or provider-host benchmark is required.
+Retained evaluation evidence contains IDs, partition, outcome, tier,
+capability, timing, and aggregate metrics; private raw request
+text, topic text, receipt questions, and semantic rationale are absent by
+default.
+
+The portable host receipt shape has all fields required, using nullable fields
+for outcome-inapplicable values; the bounded host-to-CLI normalization seam first
+validates that unmodified shape, removes only contract-listed nulls, and preserves
+every non-null value unchanged. The CLI schema then separately validates outcome
+relationships, request binding, spans, canonical capabilities, and startup authorization.
+Normalization never authorizes startup or weakens a cross-field rule.
+The evaluator reports separate, run-specific local deterministic and
+receipt-validation p95 values. They prove protocol conformance for this visible
+corpus, not semantic generalization or an end-to-end latency commitment. Semantic
+model quality and latency remain host-dependent and unmeasured; it makes no live
+model calls.
+
+## Ownership boundaries
+
+- `references/cli/hybrid-route-contract.yaml` owns protocol, outcome vocabulary,
+  precedence, span rules, privacy, evaluation gates, and deprecations.
+- `skills/agentera/route-phrases.yaml` owns the deterministic phrase inventory.
+- `references/cli/trigger-schema-enrichment.md` owns semantic trigger intent
+  documentation only.
+- `packages/cli/src/eval/hybridRouteEvaluation.ts` evaluates the frozen offline
+  conformance corpus; its tests verify the evaluator and protocol structure.
+- `skills/agentera/SKILL.md` remains the thin portable host integration surface.

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/trigger-schema-enrichment.md

@@ -0,0 +1,140 @@
+# Trigger intent documentation contract
+
+Authority for semantic-phase trigger intent documentation. This document
+defines the trigger-schema fields a host consults only after the CLI
+deterministically abstains, so it can make a semantic judgment and submit a
+receipt. The fields are documentation, not inputs to a routing engine.
+
+- **Authority path:** `references/cli/trigger-schema-enrichment.md`
+- **Schema contract:** `skills/agentera/capability_schema_contract.yaml` (the
+  contract loader at `packages/cli/src/registries/capabilityContract.ts` consumes it)
+- **Trigger files:** `skills/agentera/capabilities/<name>/schemas/triggers.yaml`
+- **Scope:** The semantic phase of the two-phase route contract. See
+  `references/cli/hybrid-route-contract.yaml` for the authoritative precedence,
+  abstention, receipt validation, and startup authorization rules.
+
+## Current boundary and obsolete layer numbering
+
+Earlier Decision 76 material described open-ended routing as Layer 3 and folded
+the former Layer 4 into it. That layer numbering is obsolete; it is not another
+routing model. The hybrid route contract now has one deterministic request phase
+(bare, direct, and curated phrase selection) and one semantic receipt phase.
+
+Only a `semantic_required` response may expose these fields to a host. The host
+uses them to choose `select`, `clarify`, or `no_match`, then submits the complete
+receipt. The CLI validates that receipt before authorizing capability startup.
+`priority` and `disambiguates_against` are advisory semantic-judgment context,
+not scoring weights. There is no scoring algorithm, confidence threshold,
+borderline band, or `prime --route` output schema.
+
+## 1. Field shape
+
+The fields below are the LLM-readable intent documentation the host consults.
+`description` and `priority` are base trigger fields required on every
+`TRIGGERS` entry; `disambiguates_against` is an optional enrichment that gives
+the host disambiguation words to surface when a request could match more than
+one capability.
+
+### 1.1 `description`
+
+- **Type:** non-empty string (required on every `TRIGGERS` entry).
+- **Meaning:** the semantic-judgment explanation of this capability's intent.
+  After `semantic_required`, the host reads it to decide whether a request fits
+  the capability. Prose that names the capability's purpose and request shapes
+  reads better than keyword lists; write it for a reader who has never seen the
+  capability before.
+- **Validation failure:** a missing, empty, or non-string `description` fails
+  validation with an error message naming the offending entry ID.
+
+```
+TRIGGERS:
+  1:
+    id: T2
+    description: >-
+      Audit local codebase health, architecture, quality, or technical debt.
+    priority: high
+    disambiguates_against:
+      - capability: document
+        hint: "audit owns code and architecture health; document owns documentation maintenance"
+```
+
+### 1.2 `disambiguates_against`
+
+- **Type:** list of mappings. Each entry MUST contain:
+  - `capability` — string referencing a valid capability ID (one of the twelve
+    English canonical IDs enumerated by `ROUTE_ALIASES.primary_aliases` in
+    `capability_schema_contract.yaml`: `status`, `vision`, `discuss`, `research`,
+    `plan`, `build`, `optimize`, `audit`, `document`, `profile`, `design`,
+    `orchestrate`).
+  - `hint` — non-empty string distinguishing this trigger's intent from the
+    named capability on near-equal requests.
+- **Meaning:** declares which other capabilities this trigger's intent could be
+  confused with, with a hint the host consults after `semantic_required`. The
+  list is advisory: the host resolves ambiguity and MAY surface the hint when
+  asking the user to clarify. The hint supplies the words; the host supplies the
+  judgment in a receipt the CLI validates.
+- **Validation failure:** a `capability` value that is not one of the twelve
+  canonical IDs, a missing `hint`, an empty `hint`, or an entry that is not a
+  mapping fails validation with the offending entry ID and the constraint.
+
+```
+disambiguates_against:
+  - capability: build
+    hint: "vision refines existing project direction; build implements code"
+  - capability: optimize
+    hint: "vision is about what to build, not tuning existing code"
+```
+
+### 1.3 `priority`
+
+- **Type:** string enum `high` | `medium` | `low` (required on every `TRIGGERS`
+  entry).
+- **Meaning:** advisory relevance-precedence hint the LLM host reads alongside
+  `description` when deciding which capability best fits a semantically
+  abstained request. `high`
+  marks a capability that owns the request strongly; `low` marks a capability
+  that is a plausible but weaker fit. It is not a scoring weight and feeds no
+  weighted-average calculation; the LLM host uses it as one signal among the
+  intent documentation.
+- **Validation failure:** a missing `priority` or a value outside `high`,
+  `medium`, `low` fails validation with the offending entry ID.
+
+```
+priority: high
+```
+
+## 2. Defaults summary
+
+| Field | Required | Default when absent |
+| --- | --- | --- |
+| `description` | required | — |
+| `disambiguates_against` | optional | empty list (no explicit collisions declared) |
+| `priority` | required (`TRIGGERS`) | — |
+
+`description` and `priority` are required on every `TRIGGERS` entry and have no
+default. `disambiguates_against` is optional and defaults to an empty list. The
+loader at `packages/cli/src/registries/capabilityContract.ts` is the consumer of
+these shapes; tests and source that need them read through the loader rather than
+re-declaring the values (per the AGENTS.md rule against duplicating
+contract-owned values).
+
+## 3. Acceptance criteria mapping
+
+| Criterion | Section |
+| --- | --- |
+| `description` is a non-empty string on every `TRIGGERS` entry | §1.1 |
+| `disambiguates_against` entries reference a valid capability ID and include a non-empty hint | §1.2 |
+| `priority` is one of `high` / `medium` / `low` on every `TRIGGERS` entry | §1.3 |
+| Trigger fields are semantic-phase documentation; no scoring algorithm, thresholds, borderline band, or `--route` output schema | Current boundary, §1 |
+| Deterministic precedence and validated receipt authorization remain singular | `hybrid-route-contract.yaml` |
+
+## 4. Legacy enriched fields
+
+`patterns`, `patterns_regex`, `confidence_threshold`, and `borderline_band`
+remain accepted only so inherited enriched trigger files validate and load. They
+are discarded by the loader: the active trigger model does not expose strings,
+`RegExp` objects, scores, thresholds, or bands from them. The capability
+validator validates their compatibility shapes; specifically, it validates the
+numeric fields' integer 0..100 range, while the loader accepts and discards
+their values. Do not add them to new active trigger entries. Their presence
+cannot change a natural-language classification.

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

@@ -10,12 +10,13 @@ sources:
 scope:
   includes:
     - Channel names, default selection, and resolution precedence.
-    - npm dist-tag and git ref resolution per channel.
+    - npm dist-tag resolution per channel and git ref resolution for the stable line only.
     - Environment, config, and CLI override keys.
   excludes:
     - App lifecycle canonical statuses and operation verb definitions.
     - Migration orchestration phases, apply semantics, and compatibility detection.
     - Package publication, dist-tag retirement, and release approval decisions.
+    - uv/git install paths for the development (3.x) channel; feat/v3 is TS-only on npm.
 compatibility_boundary: >-
   Stable channel must continue resolving to 2.x until an explicit release decision
   retires it. Cross-major v2→v3 migration is never implied by default channel
@@ -32,6 +33,23 @@ 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: true
+      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 --channel development --project "$PWD" --dry-run
+      apply_command: npx -y agentera@next upgrade --channel development --project "$PWD" --yes
+      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
@@ -43,16 +61,36 @@ channels:
     concept: v3_pre_release_line
     definition: >-
       Tracks 3.x alphas, betas, and release candidates for early adopters and
-      maintainers testing the npm self-contained distribution.
+      maintainers testing the npm self-contained TypeScript distribution. The
+      feat/v3 branch and v3 CLI are npm-only; v2→v3 is a one-way upgrade through
+      npx @next, not through uvx or git checkout installs.
     distribution_major: 3
+    next_major:
+      concept: forward_successor_line
+      channel: development
+      version: "3.0.0"
+      announced: true
+      npm:
+        dist_tag: next
+      npm_only_advisory: >-
+        The v3 successor line is npm-only; opt in to v2→v3 migration through npx @next.
+      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 --channel development --project "$PWD" --dry-run
+      apply_command: npx -y agentera@next upgrade --channel development --project "$PWD" --yes
+      irreversible_advisory: >-
+        Forward migration to the v3 line is one-way; return to the prior
+        Python support line is permanently unsupported.
     resolution:
       npm:
         dist_tag: next
         update_command: npx -y agentera@next
       git:
-        ref: feat/v3
-        update_command: >-
-          uvx --from git+https://github.com/jgabor/agentera@feat/v3 agentera
+        supported: false
+        reason: >-
+          feat/v3 has no Python packaging; development-channel CLI delivery is
+          npm-only. Stable-channel git/uvx remains the Python 2.x maintainer path
+          on @main.
 override_precedence:
   - cli_flag
   - env_var
@@ -122,8 +160,8 @@ version_resolution:
   latest_on_channel:
     resolver: npm_dist_tag_with_offline_defaults
     offline_defaults:
-      stable: "2.7.6"
-      development: "3.0.0-dev.3"
+      stable: "2.7.7"
+      development: "3.0.0"
   irreversibility:
     downgrade_to_v2: permanently_blocked
     supported_downgrade_lines: []

package/bundle/references/cli/upgrade-repair-wording.md

@@ -0,0 +1,25 @@
+# Upgrade repair wording
+
+## Runtime migration boundary
+
+Recognized v2-to-v3 project migration rewires existing Agentera v2 hook
+configurations to the npm CLI and retires only proven Agentera-owned legacy hook
+files. It does not copy or refresh plugins, agents, commands, or skill links.
+
+Runtime lifecycle installation and remediation are separate. Apply requires an
+explicit `--runtime` selector and `--yes`; declared ownership, collision
+remediation, and convergent retry behavior remain governed by `UPGRADE.md`.
+
+## v2 install track successor surfacing (#32)
+
+When a **v2-classified** managed app-home (`install_track: v2`) runs the **v3 TypeScript
+CLI** (`agentera doctor` / `agentera prime`), the next-major successor block must surface
+the stable-line forward successor (`3.0.0` on the development channel) with the preview
+command (`npx -y agentera@next upgrade --dry-run`) and the v2→v3 guide URL from
+`references/cli/update-channels.yaml`. A v2 install must not be silently reported as
+up to date against the v3 line.
+
+| Surface | Branch | Behavior |
+| --- | --- | --- |
+| TypeScript (`packages/cli/src/upgrade/nextMajorDoctor.ts`, doctor/prime wiring) | `feat/v3` | Resolve successor from `channels.stable.next_major` for v2 installs; omit the block for v3 npm installs and feat/v3 source checkouts. |
+| Python (`scripts/agentera_upgrade.py` doctor/prime writer) | `main` (stable) | Mirror the same v2-install successor block and preview command in stable-line doctor/prime output. Backport per the both-branch pattern; verify by round-trip parity with the v3 reader, not pytest in the feat/v3 worktree. |