agentera 3.0.0-dev.6 → 3.0.0-dev.69

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

@@ -0,0 +1,155 @@
+# 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
+`npx -y agentera@next 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:
+
+Every `semantic_required` response includes a `receipt_contract` with the exact
+`agentera.route_receipt.v1` nullable schema, legal outcomes, outcome nullability,
+compound and `remainder_span` rules, and a current runnable stdin example. The
+same guide appears in `npx -y agentera@next route receipt --help`; a host does not need to
+inspect implementation or contract files to construct its receipt. The example
+uses a fixed public request, never the transient request being classified.
+
+| 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
+`npx -y agentera@next 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.
+
+## Maintenance
+
+- Maintainer: Agentera CLI maintainers
+- Source checkout root: `.`
+- Working directory: `.`
+- Command: `node packages/cli/dist/bin/agentera.js route evaluate --format json`

package/bundle/references/cli/trigger-schema-enrichment.md

@@ -0,0 +1,147 @@
+# 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.
+
+## Maintenance
+
+- Maintainer: Agentera CLI maintainers
+- Source checkout root: `.`
+- Working directory: `.`
+- Command: `node packages/cli/dist/bin/agentera.js check validate capability-contract --format json`

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

@@ -37,7 +37,7 @@ channels:
       concept: forward_successor_line
       channel: development
       version: "3.0.0"
-      announced: false
+      announced: true
       npm:
         dist_tag: next
       npm_only_advisory: >-
@@ -45,7 +45,8 @@ channels:
         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
+      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.
@@ -64,6 +65,22 @@ channels:
       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

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

@@ -14,9 +14,7 @@ authority_order:
   - references/artifacts/artifact-registry-interface-model.yaml
   - references/cli/app-lifecycle-vocabulary.yaml
   - references/cli/update-channels.yaml
-  - references/cli/bundle-skill-vocabulary.yaml
   - references/cli/capability-instruction-contract.yaml
-  - references/cli/routing-execution-vocabulary.yaml
   - skills/agentera/SKILL.md
   - packages/cli/src/capabilities/*/instructions.ts
   - the agentera CLI
@@ -26,21 +24,24 @@ authority_order:
   - DESIGN.md
   - .agentera/
 normalization_rules:
-  - rule: Internal workflows are capabilities.
-    use: capability, twelve capabilities, capability prose, capability schemas
-    avoid: Calling hej/realisera/etc. standalone skills, except in v1 history.
-  - rule: The runtime surface is a skill.
-    use: Agentera skill, single installed Agentera app
-    avoid: twelve-skill suite for v2 behavior.
+  - rule: Agentera is one agent, not a team; workflows are capabilities.
+    use: capability, twelve capabilities, one agent with many capabilities, capability prose, capability schemas
+    avoid: Calling status/build/etc. standalone skills or agents; "engineering team" as a product word; except in v1 history.
+  - rule: The runtime install is internal transport, not a product surface.
+    use: single Agentera agent, capabilities (the product word); "skill" and "plugin" survive only as internal transport (the skills/ directory and plugin.json manifests host editors require)
+    avoid: '"Agentera skill" or "plugin" as product words; "twelve-skill suite" or "plugin suite" for the capability set.'
+  - rule: Agentera is the agent; the host is the harness (Decision 74).
+    use: host runtime, harness, host coding agent (OpenCode, Codex, Cursor, Copilot); the CLI owns routing, memory, capability prose, and the worker-spec contract
+    avoid: Calling host coding agents peers or extension hosts of Agentera; implying Agentera is a module loaded into the host.
   - rule: /agentera is the main invocation.
     use: /agentera, $agentera for Codex-specific docs
     avoid: /hej except as a legacy bridge.
   - rule: The CLI source and rendered dashboard are different.
-    use: agentera hej source data, Hej dashboard rendered briefing
+    use: agentera prime source data, status dashboard rendered briefing
     avoid: Treating raw CLI labels as the user-facing dashboard.
-  - rule: Routine state uses flat commands.
-    use: agentera plan, agentera docs, agentera health
-    avoid: agentera query plan for routine state.
+  - rule: Routine state uses the state namespace.
+    use: agentera state plan list, agentera state docs list, agentera state health list
+    avoid: agentera plan, agentera docs, or agentera health as routine state commands.
   - rule: query is advanced access.
     use: agentera query --list-artifacts, agentera query <artifact>
     avoid: Calling it the normal state interface.
@@ -64,7 +65,7 @@ normalization_rules:
     avoid: Non-Git checkpoint or pre-dispatch commit gate in new docs.
   - rule: Capability instruction modules have current metadata and a runtime boundary.
     use: instructions.ts plus emitted prime_context first_invocation_read; runtime enforcement is true via the CLI prime command
-    avoid: Claiming agents are policed for actual reads, or adding unsupported agentera planera commands.
+    avoid: Claiming agents are policed for actual reads, or adding unsupported agentera plan commands.
 plain_language:
   lead_with_plain_phrase:
     - use: final state sync, the plan-level freshness checkpoint
@@ -150,10 +151,12 @@ decision_44:
       boundary: Preserve capability IDs, artifact IDs, group IDs, route IDs, and test fixture IDs unless a migration is planned.
     - surface: CLI labels and exit behavior
       boundary: Preserve current command names, parseable labels, exit codes, and source-contract labels unless an explicit CLI migration is recorded.
-    - surface: Canonical capability names
-      boundary: Preserve hej, visionera, resonera, inspirera, planera, realisera, optimera, inspektera, dokumentera, profilera, visualisera, and orkestrera.
-    - surface: Decision 43 aliases
-      boundary: Preserve /agentera status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, and orchestrate.
+    - surface: Canonical capability names (v3 surface)
+      boundary: >-
+        Preserve the Decision 43 English alias set as the binding canonical names for v3 and onward under the single-agent identity (Decision 74): status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, orchestrate. Future capability additions follow the same transfer-friendly English-verb pattern (Decision 70). Per Decisions 70 and 74, the D43 alias set is the binding name set under one agent, one CLI, many capabilities; future renames require a new decision.
+    - surface: Legacy Swedish capability names (v2 stable only)
+      boundary: >-
+        Preserve hej, visionera, resonera, inspirera, planera, realisera, optimera, inspektera, dokumentera, profilera, visualisera, and orkestrera for the v2 stable distribution from main and as historical references in archived plans, decisions, and changelogs. Out of scope for v3 surface per Decisions 70 and 74; the single-agent identity uses English capability names exclusively. Coexistence probe surfaces per-distribution naming divergence.
     - surface: Historical artifacts
       boundary: Do not rewrite old progress, changelog, archived plans, or decisions solely for vocabulary cleanup.
     - surface: Release version