agentera 3.0.0-dev.4 → 3.0.0-dev.46

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

@@ -33,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
@@ -48,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
@@ -127,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.4"
+      stable: "2.7.7"
+      development: "3.0.0"
   irreversibility:
     downgrade_to_v2: permanently_blocked
     supported_downgrade_lines: []

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

@@ -14,11 +14,9 @@ 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
-  - skills/agentera/capabilities/*/instructions.md
+  - packages/cli/src/capabilities/*/instructions.ts
   - the agentera CLI
   - packages/cli/src/upgrade (doctor/upgrade)
   - README.md
@@ -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.
@@ -62,9 +63,9 @@ normalization_rules:
   - rule: Worker safety commits are Git-only.
     use: pre-spawn Git commit
     avoid: Non-Git checkpoint or pre-dispatch commit gate in new docs.
-  - rule: Capability instruction files have current metadata and a runtime boundary.
-    use: instructions.md plus emitted first_invocation_read; runtime enforcement remains false
-    avoid: Claiming agents are policed for actual reads, or adding unsupported agentera planera commands.
+  - 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 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