agentera 3.0.0-dev.27 → 3.0.0-dev.28

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

@@ -1,94 +1,139 @@
-# Five-layer routing model
-
-Origin: Decision 76 (2026-06-30) — LLM-primary routing model. Retires the
-deterministic NL routing engine and repositions the trigger schema as
-LLM-readable intent documentation. Builds on the original five-layer concept
-from Decision 42 (2026-05-04), redefining Layers 3-4 as LLM-native.
-
-The Agentera routing model resolves incoming requests to a capability across
-five layers. Layers 1, 2, and 5 are deterministic dispatch (bare invocation,
-exact alias, no match); they are implemented and unchanged. Layers 3 and 4
-cover natural-language requests. Per Decision 76, the LLM host — the AI model
-that receives the user's message — owns natural-language routing natively. The
-trigger schema (`description`, `disambiguates_against`, `priority`, phase
-context) provides LLM-readable intent documentation the host consults; there is
-no scoring engine, no confidence threshold, and no borderline band. Layer 4
-(formerly borderline-band disambiguation) is dissolved into Layer 3: the LLM
-resolves ambiguity natively, using `disambiguates_against` hints as advisory
-context. Decision 75's request-vs-state mutual exclusivity is dissolved: request
-intent and state-readiness are both advisory context the LLM consults.
-
-## Layer 1: Bare `/agentera` — delegate to prime
-
-- **Input pattern**: the request is `/agentera` with no additional text.
-- **Action**: delegate immediately to the status capability. Status performs
-  state-aware routing through the `agentera prime` composite result, which
-  condenses project artifacts and suggests the most useful next capability.
-  This is deterministic and never wrong.
-- **Implementation status**: implemented and unchanged.
-
-## Layer 2: capability name or `/agentera <primary-alias>` — direct route
-
-- **Input pattern**: the request text exactly matches a capability name
-  (case-insensitive), or exactly matches one primary alias from
-  `capability_schema_contract.yaml` `ROUTE_ALIASES.primary_aliases`, or begins
-  with a canonical capability name followed by more text (`/agentera <capability>
-  <topic>`).
-- **Action**: route directly to that capability without evaluating natural-language
-  trigger descriptions. Pass any remaining text as the user's topic or instruction.
-  Each capability has exactly one primary alias; secondary wording stays in
-  capability trigger schemas below this layer.
-- **Implementation status**: implemented and unchanged.
-
-## Layer 3: Natural language — LLM-native routing
-
-- **Input pattern**: the request is natural language (e.g. "help me think
-  through this") that does not match Layer 1 or Layer 2.
-- **Action**: the LLM host routes natively. It consults the trigger schema's
-  `description` fields (what each capability does), `disambiguates_against`
-  hints (how to tell near-equal capabilities apart), and `priority`
-  (relevance precedence) as LLM-readable intent documentation, then selects a
-  capability. There are no confidence scores, no thresholds, and no
-  weighted-average computation; the LLM reads the intent descriptions and
-  routes.
-- **Resolving ambiguity**: when two capabilities could match a request, the
-  LLM host resolves the ambiguity natively, surfacing the
-  `disambiguates_against.hint` strings as advisory context when it asks the
-  user to confirm or clarify. The hints supply the words; the LLM supplies the
-  judgment.
-- **Implementation status**: implemented — the LLM host owns this layer.
-  `references/cli/trigger-schema-enrichment.md` is the intent documentation
-  contract the host reads.
-
-## Layer 4: Dissolved into Layer 3
-
-Layer 4 formerly described a borderline-band disambiguation engine that fired
-when two capabilities scored within a configurable band. Decision 76 retired
-that engine: ambiguity resolution is now part of Layer 3, performed natively by
-the LLM host using the `disambiguates_against` hints as advisory context. There
-is no separate disambiguation layer, no borderline band, and no
-disambiguation-engine output schema.
-
-## Layer 5: No match — fallback to status
-
-- **Input pattern**: the LLM host cannot map the request to any capability from
-  the trigger schema's intent descriptions.
-- **Action**: route to status for orientation. Status handles status requests
-  and ambiguous inputs.
-- **Implementation status**: implemented and unchanged.
+# 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
 
-- **This document** defines what Layers 1-5 mean: their input patterns, actions,
-  and implementation status.
-- **`skills/agentera/capability_schema_contract.yaml`** (`ENTRY_SCHEMA.fields.priority`
-  and `FIELD_RULES.TRIGGERS.priority`) defines trigger `priority` values
-  (`high`, `medium`, `low`) as an advisory relevance-precedence hint the LLM host
-  reads — not a scoring weight.
-- **Per-capability `schemas/triggers.yaml`** owns the trigger `description`,
-  `priority`, and `disambiguates_against` intent documentation that the LLM host
-  consults for Layer 3 routing. `references/cli/trigger-schema-enrichment.md` is
-  the intent documentation contract; pattern matching and scoring belong to
-  neither, having been retired by Decision 76.
-- **`skills/agentera/SKILL.md`** is the thin bootstrap routing surface per Decision
-  74; it cross-references this document rather than restating the full model.
+- `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/trigger-schema-enrichment.md

@@ -1,38 +1,31 @@
 # Trigger intent documentation contract
 
-Authority for Layer 3 LLM-native capability routing. This document defines the
-trigger-schema fields the LLM host consults to understand what each capability
-does and how to disambiguate near-equal requests. The fields are documentation
-the host reads, not inputs to a scoring engine.
+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:** Layer 3 (LLM-native natural-language routing) of the five-layer
-  routing model. Layer 4 (formerly borderline-band disambiguation) is dissolved
-  into Layer 3. Layers 1, 2, and 5 are unchanged.
-
-## Decision 76 — repositioning
-
-Decision 76 (2026-06-30) retires the deterministic NL routing engine. The LLM
-host — the AI model that receives the user's message — owns natural-language
-routing natively. This document is repositioned from a scoring-enrichment
-contract to the **trigger intent documentation contract**: it defines the
-`triggers.yaml` fields that help the LLM host understand what each capability
-does and how to disambiguate near-equal requests.
-
-The fields stay as documentation, not as scoring inputs. The LLM host reads the
-descriptions and disambiguates natively; `priority` and `disambiguates_against`
-are advisory hints, not scoring weights. There is no scoring algorithm, no
-confidence threshold, no borderline band, and no `prime --route` output schema.
-Decision 75's request-vs-state mutual exclusivity is dissolved: request intent
-and state-readiness are both advisory context the LLM consults. Decision 76
-supersedes Decision 75 design choices 2 (request-derived scoring as router), 4
-(mutual exclusivity), and 5 (pure request-derived).
-
-Decision 76 records the design choices and rejected alternatives (including the
-tuning-the-engine and reposition-`--route` alternatives that were rejected).
+- **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
 
@@ -45,11 +38,11 @@ one capability.
 ### 1.1 `description`
 
 - **Type:** non-empty string (required on every `TRIGGERS` entry).
-- **Meaning:** the LLM-readable explanation of what this trigger entry routes to.
-  The LLM host reads this to decide whether a natural-language request matches
-  the capability's intent. Prose that names the capability's purpose and the
-  request shapes it owns reads better than keyword lists; write it for a reader
-  who has never seen the capability before.
+- **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.
 
@@ -58,11 +51,11 @@ TRIGGERS:
   1:
     id: T2
     description: >-
-      Audit and codebase health requests.
-    priority: medium
-    patterns:
-      - "check code health"
-      - "architecture review"
+      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`
@@ -76,11 +69,10 @@ TRIGGERS:
   - `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 LLM host consults when it sees a request that
-  could match more than one capability. The list is advisory: the LLM host
-  resolves ambiguity natively and MAY surface the hint when asking the user to
-  confirm or clarify. The hint supplies the words; the LLM supplies the
-  judgment.
+  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.
@@ -98,7 +90,8 @@ disambiguates_against:
 - **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 request. `high`
+  `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
@@ -132,5 +125,16 @@ contract-owned values).
 | `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 |
-| Document reframed as LLM-readable intent documentation; no scoring algorithm, thresholds, borderline band, or `--route` output schema | Decision 76, §1 |
-| Decision artifact lists each choice, ≥1 alternative, and rationale | Decision 76 in `.agentera/decisions.yaml` |
+| 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/vocabulary.md

@@ -53,11 +53,10 @@ examples. Diagnostics should state object, state, cause, and fix.
 | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
 | Agentera                   | The agent. One persistent identity that thinks through every step and keeps working when you walk away — the colleague, not the team. The CLI is the brain and spine: it owns routing, memory, capability prose, and the worker-spec contract. Coding hosts consume the same shared skill and CLI contract; Agentera does not ship host-native package surfaces. Identity is per-project: same personality, same capabilities, different memory, no bleed. Headline: one agent, one CLI, many capabilities. | `README.md`, `.agentera/vision.yaml`, `.agentera/decisions.yaml` (D74), `skills/agentera/SKILL.md` |
 | Host runtime (harness)      | A coding agent host that provides the model, tools, and worker execution. Agentera is the agent; the host is the harness. Hosts consume the shared skill at `~/.agents/skills/agentera` and the JSON returned by `agentera prime`; Agentera does not install or repair host-native plugins, hooks, agents, or packages. | `.agentera/vision.yaml`, `.agentera/decisions.yaml` (D74), `skills/agentera/SKILL.md` |
-| Product surface            | Where the fixed Agentera workflow ships: `@agentera/cli` (the agent runtime and narrow waist), `@agentera/mobile` (a client of the CLI), and `@agentera/web` (site and docs). Coding hosts consume the shared skill and CLI rather than receiving native Agentera package surfaces. | `README.md`, `AGENTS.md`, `packages/*/README.md`, `.agentera/decisions.yaml` (D74) |
-| @agentera/mobile           | The flagship mobile/web app package at `packages/mobile`. SvelteKit, Cursor SDK, Cloudflare Worker.                                                                                                                                                                                 | `packages/mobile/README.md`, `packages/mobile/DESIGN.md`                         |
+| Product surface            | The fixed Agentera workflow ships through the `agentera` package and CLI. Coding hosts consume the shared skill and CLI rather than receiving native Agentera package surfaces. | `README.md`, `AGENTS.md`, `packages/cli/README.md`, `.agentera/decisions.yaml` |
 | Agentera skill             | Shared transport, not a product extension point. The source at `skills/agentera/` is installed once at `~/.agents/skills/agentera` and packages Agentera's routing entry and capability prose without host-native manifests. It is the same fixed workflow, not user extensibility. Per Decision 74, the product word is capabilities. | `skills/agentera/SKILL.md`, `README.md` Internals, `.agentera/decisions.yaml` (D74) |
 | Capability                 | A routed behavioral unit of the single Agentera agent, driven through the CLI. Eleven top-level capabilities (status, vision, discuss, research, plan, build, optimize, audit, document, design, orchestrate) plus profile, which surfaces through existing capabilities but appears as a peer row in user-facing docs. Each capability has a prose module at `packages/cli/src/capabilities/<name>/instructions.ts` plus `triggers.yaml`, `artifacts.yaml`, `validation.yaml`, and `exit.yaml`. English names are canonical per Decision 70; the Swedish `-era` names are legacy v2 stable only (see Legacy Swedish capability names). | `AGENTS.md`, `skills/agentera/capabilities/*`, `packages/cli/src/capabilities/*`, `.agentera/decisions.yaml` (D70, D74) |
-| Capability canonical name (v3) | The English name binding for v3+ capability invocation, per Decision 70, under the single-agent identity crystallized in Decision 74. Promoted from the Decision 43 alias set. Mobile UX, web docs, host runtimes, and the CLI all use the same English name; the v2 stable distribution uses the legacy Swedish `-era` IDs (see `Legacy Swedish capability names`). | `.agentera/decisions.yaml` (D43, D70, D74), `references/cli/vocabulary-index.yaml` (protected_surfaces) |
+| Capability canonical name (v3) | The English name binding for v3+ capability invocation, per Decision 70, under the single-agent identity crystallized in Decision 74. Promoted from the Decision 43 alias set. Host runtimes and the CLI use the same English name; the v2 stable distribution uses the legacy Swedish `-era` IDs (see `Legacy Swedish capability names`). | `.agentera/decisions.yaml` (D43, D70, D74), `references/cli/vocabulary-index.yaml` (protected_surfaces) |
 | Legacy Swedish capability names (v2 stable) | The historical Swedish `-era` IDs (e.g. `hej`, `resonera`) used by the v2 stable distribution (`npx -y agentera@latest`) and preserved 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. | `.agentera/decisions.yaml` (D70, D74), `references/cli/vocabulary-index.yaml` (protected_surfaces) |
 | Shared protocol            | Internal primitive vocabulary in `protocol.yaml`: confidence, severity, decision labels, exits, visual tokens, glyphs, and phases.                                                                                                                                                  | `skills/agentera/protocol.yaml`                                                  |
 | Capability schema contract | The executable contract for capability schema groups, stable IDs, priorities, deprecations, and primitive references.                                                                                                                                                               | `skills/agentera/capability_schema_contract.yaml`                                |
@@ -132,12 +131,11 @@ authoritative recovery command.
 | Direct route                 | A canonical capability name with optional following topic text, `/agentera <capability-name>` with optional topic text, or `/agentera <primary-alias>` routes directly to that capability and bypasses natural-language matching.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | Canonical capability route   | An English capability name such as `discuss`, `plan`, or `orchestrate`, optionally followed by topic text, plus the slash form `/agentera <capability-name>` with optional topic text. Canonical names remain protocol identity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | Primary route alias          | The one plain `/agentera <alias>` direct route for a capability, owned by `ROUTE_ALIASES.primary_aliases`. Each canonical capability has exactly one primary alias.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Secondary request wording    | Natural-language phrases in capability trigger schemas, such as `deliberate`, `brainstorm`, `rubber duck`, `brief`, and `what's next`. They route through trigger matching and are not primary aliases.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| Natural-language trigger     | A phrase in `schemas/triggers.yaml` that maps a request to a capability.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| Trigger priority             | `high`, `medium`, or `low`; owned by the schema contract.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| High-confidence match        | A natural-language request with enough trigger evidence to route without asking.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Borderline match             | A request with competing plausible routes. Agentera asks for disambiguation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Fallback to status             | No sufficient match routes to status for orientation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Secondary request wording    | LLM-readable intent descriptions in capability trigger entries. They describe secondary wording and are not primary aliases.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Natural-language trigger     | A trigger entry in `schemas/triggers.yaml` whose description and collision hints a host reads only after deterministic routing returns `semantic_required`. The host's semantic judgment must be submitted as a receipt the CLI validates before startup.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Trigger priority             | `high`, `medium`, or `low`; an advisory relevance-precedence hint owned by the schema contract, not a score.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Genuine consequential ambiguity | Two materially plausible capabilities without enough intent to choose responsibly. Ask one clarification.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Fallback to status           | Route to status for orientation only when no capability fits.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | Concrete next action         | A route suggestion tied to an object such as `PLAN Task N`, `TODO`, `OBJECTIVE`, or `VISION refresh`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | Suggest, don't force         | Status recommends the next capability but waits for user confirmation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | Capability handoff label     | A recommendation from one capability to another. Use glyph plus canonical name, such as `⧉ build` or `≡ plan`, not standalone slash-capability names. SG priority codes are internal protocol references and are not user-facing handoff labels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

package/bundle/references/meta/documentation-inventory.md

@@ -11,7 +11,6 @@ guides — not under `docs/`.
 | Path | Topic |
 | ---- | ----- |
 | `docs/packaging/v3-packaging.md` | v3 CLI npm distribution and verification-lane contract |
-| `docs/consolidation/monorepo-plan.md` | Product pivot, `@agentera/*` package layout, migration checklist (D67) |
 
 ## Authority stack
 
@@ -23,11 +22,10 @@ guides — not under `docs/`.
 | Human vocabulary index | `references/cli/vocabulary.md` |
 | Benchmark contract | `references/analysis/startup-measurement-contract.yaml` |
 | Benchmark runbook | `references/analysis/benchmark.md` |
-| Verification optimization baseline | `references/analysis/verification-baseline-2026-07-20.yaml` |
 | Verification ownership and execution policy | `references/analysis/verification-policy.yaml` |
 | State storage, path, API, compatibility, and output authority | `references/artifacts/state-storage-authority.yaml` |
 | JSON surface budgets | `scripts/json_output_surface_manifest.yaml` |
-| Project drafts | `docs/` (gitignored except `docs/README.md`, `docs/packaging/`, `docs/consolidation/`) |
+| Project drafts | `docs/` (gitignored except `docs/README.md` and `docs/packaging/`) |
 
 ## `docs/` policy
 

package/bundle/skills/agentera/SKILL.md

@@ -25,9 +25,10 @@ capabilities:
 
 # agentera
 
-One agent, one CLI, many capabilities. The CLI is the routing brain — it owns
-project memory, capability instructions, routing judgment, and the worker-spec contract.
-The host agent learns one contract: the CLI.
+One agent, one CLI, many capabilities. The CLI owns project memory,
+capability instructions, the deterministic routing tiers, and the worker-spec
+contract. The host owns open-ended semantic judgment from the trigger intent
+documentation after deterministic abstention; it learns that contract from the CLI.
 
 ---
 
@@ -75,27 +76,58 @@ interruption; recovery continues forward internally.
 
 ## Routing
 
-The CLI routes. The host agent follows.
+The CLI first applies deterministic explicit and curated route tiers. For
+`semantic_required` requests, the LLM host classifies open-ended language from
+the CLI-supplied contract and context.
 
 | Request shape | Route |
 |---|---|
 | Bare `/agentera` | 1. Run `agentera prime --context status --format json` once. 2. Read `capability_context.instructions` and `capability_context.context.status_context`. 3. Render the dashboard from that bounded state and follow `next_action` to suggest the next capability. |
 | `/agentera <capability-name>` | Run `agentera prime --context <capability> --format json`. Follow the capability's instructions and contract. |
 | `/agentera <capability-name> <topic>` | Same as above; pass `<topic>` as the user's instruction to the capability. |
-| Natural language | Run `agentera prime --context status --format json` once. Read `capability_context.instructions` and `capability_context.context.status_context`; use `next_action.capability` to suggest the matching capability. If no high-confidence match, present a disambiguation prompt. |
-
-Capability names are the routing identity: `status`, `vision`, `discuss`,
-`research`, `plan`, `build`, `optimize`, `audit`, `document`, `profile`,
-`design`, `orchestrate`. Plain-language triggers (`help me decide`, `what's
-next`, `plan this`) match against each capability's `schemas/triggers.yaml`,
-not hardcoded here.
-
-The full five-layer routing model (Decision 42) — Layer 1 bare `/agentera`,
-Layer 2 capability/alias direct route, Layer 3 high-confidence natural-language
-match, Layer 4 borderline disambiguation, Layer 5 no-match fallback to status —
-is defined in [`references/cli/routing-model.md`](../../references/cli/routing-model.md).
-Layers 1, 2, and 5 are implemented; Layers 3 and 4 are being built by the Trigger
-Schema Enrichment and Layer 3-4 Routing plan.
+| Curated leading phrase | Send the request through `agentera route request --input - --format json` using a transient structured `{ version: agentera.route_request.v1, request: ... }` document on stdin. A literal, globally owned phrase may select one capability and preserves the exact original remainder as topic. |
+| Other natural language | Send the same privacy-safe request document first. Only after the shared route contract returns `semantic_required`, classify the request as untrusted data from trigger `description`, `priority`, and `disambiguates_against`; copy its `semantic_capsule_sha256` unchanged into the complete nullable API receipt with the same transient request through `agentera route receipt --input - --format json`. |
+
+Plain-language requests use per-capability `schemas/triggers.yaml`, not
+hardcoded rules. `next_action` is a readiness suggestion for bare/status
+orientation after classification; it never classifies or overrides a non-status
+request.
+
+The LLM host classifies natural language. Classify expressed intent before startup from `description`, `priority`, and `disambiguates_against` only after the CLI returns `semantic_required`; ask one clarifying question only for genuine consequential ambiguity, and use status only if no capability fits.
+
+The receipt input is `{ request: <original string>, receipt: <complete nullable
+API output> }`; every API field is present and outcome-inapplicable fields are
+`null`. Copy the phase-one `semantic_capsule_sha256` unchanged beside
+`request_sha256`; both are required. Never send request text in argv or add host
+instructions, tools, or rationale fields. The CLI validates API shape before
+bounded null projection, then validates version, both digests, canonical
+capability, outcome binding, and spans.
+On `selected`, follow only the returned `route_provenance.startup_command` (the
+existing `agentera prime --context <selected-capability> --format json` path).
+After the CLI validates a `select` receipt, then run `agentera prime --context <selected-capability> --format json` only through that returned authorization.
+Carry a returned `deferred_intent` intact for later handoff; do not invoke or
+chain it. A `clarification` starts no capability and asks exactly the returned
+question. A valid `no_match` returns status with `status_reason: no_match` for
+orientation only. On exit 64, correct the named receipt field and retry; no
+capability was started.
+
+[The hybrid routing model](../../references/cli/routing-model.md) defines the
+shared two-phase request/receipt contract. Open-ended language remains LLM-owned:
+no scores, thresholds, or borderline band. The phrase registry is the only
+deterministic natural-language authority; do not revive legacy trigger patterns,
+regexes, thresholds, or bands. `next_action` never classifies or overrides a
+request, and a compound remainder is preserved rather than silently chained.
+Decision mpulyomlyl supersedes Decision 76 only for this curated literal fast
+path.
+
+Run `agentera route evaluate --format json` to evaluate the frozen visible
+development and adversarial corpus. Its report binds the protocol, phrase
+authority, and shared-skill hashes, labels every result with a routing tier, and
+keeps request text out of output. It proves protocol conformance, not semantic
+generalization. It does not invoke a semantic host: deterministic and
+receipt-validation conformance and run-specific local p95 values are measured
+locally, while semantic model quality and latency are host-dependent and
+explicitly unmeasured.
 
 Handoff verbs: