agentera 3.0.0-dev.2 → 3.0.0-dev.21

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

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

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

@@ -0,0 +1,136 @@
+# 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 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).
+
+## 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 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.
+- **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 and codebase health requests.
+    priority: medium
+    patterns:
+      - "check code health"
+      - "architecture review"
+```
+
+### 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 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.
+- **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 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 |
+| 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` |

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

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

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

@@ -0,0 +1,45 @@
+# Upgrade repair wording — v3 cursor agent skip
+
+When `agentera upgrade --runtime cursor` (or a full runtime phase) runs against a
+**project** directory, managed `.cursor/agents/*.md` descriptors are normally
+copied from the active app-home bundle. On a **v3 capability-surface** project
+that signal is suppressed so D65 `prime --context` bodies are not regressed to
+the retired `instructions.md` read path.
+
+## v3 surface probe
+
+Treat the project as v3 when **all twelve** instruction modules exist:
+
+`packages/cli/src/capabilities/<name>/instructions.ts`
+
+for every routed capability (`status`, `vision`, `discuss`, `research`,
+`plan`, `build`, `optimize`, `audit`, `document`, `profile`,
+`design`, `orchestrate`).
+
+If any module is missing, preserve v2 upgrade behavior (copy/refresh managed
+agents from the bundle).
+
+## Orchestrator behavior
+
+| Orchestrator | Branch | Behavior |
+| --- | --- | --- |
+| TypeScript (`packages/cli/src/upgrade/runtimeMigration.ts`) | `feat/v3` | On v3 probe match, emit `skipped` `copy-agent` items for in-tree `.cursor/agents/` instead of copying from the bundle. |
+| Python (`scripts/agentera_upgrade.py`) | `main` (stable) | Same probe before the cursor agent copy loop; do not schedule `copy-agent` targets under the project when the probe matches. Backport per the both-branch pattern. |
+
+## User-visible skip message
+
+`v3 capability instruction modules present; in-tree .cursor/agents/ uses prime --context and is not overwritten`
+
+## v2 install track successor surfacing (#32)
+
+When a **v2-classified** managed app-home (`install_track: v2`) runs the **v3 TypeScript
+CLI** (`agentera doctor` / `agentera prime`), the next-major successor block must surface
+the stable-line forward successor (`3.0.0` on the development channel) with the preview
+command (`npx -y agentera@next upgrade --dry-run`) and the v2→v3 guide URL from
+`references/cli/update-channels.yaml`. A v2 install must not be silently reported as
+up to date against the v3 line.
+
+| Surface | Branch | Behavior |
+| --- | --- | --- |
+| TypeScript (`packages/cli/src/upgrade/nextMajorDoctor.ts`, doctor/prime wiring) | `feat/v3` | Resolve successor from `channels.stable.next_major` for v2 installs; omit the block for v3 npm installs and feat/v3 source checkouts. |
+| Python (`scripts/agentera_upgrade.py` doctor/prime writer) | `main` (stable) | Mirror the same v2-install successor block and preview command in stable-line doctor/prime output. Backport per the both-branch pattern; verify by round-trip parity with the v3 reader, not pytest in the feat/v3 worktree. |

package/bundle/references/cli/v3-handoff-manifest.schema.yaml

@@ -0,0 +1,98 @@
+schema_version: agentera.v3_handoff_manifest.v1
+status: active_authority
+purpose: >-
+  Contract for the v2→v3 handoff manifest written by the stable Python CLI at the
+  app-home root and read by the v3 TypeScript migration preflight. The manifest
+  lets v3 migration classify preserved user state in O(1) time instead of
+  scanning the entire app home.
+manifest_file: v3-handoff.json
+manifest_path: >-
+  {app_home}/v3-handoff.json where app_home is the platform data-home install
+  root (for example ~/.local/share/agentera on Linux).
+writers:
+  - v2 stable Python CLI on install, upgrade apply, and doctor (refresh when stale)
+readers:
+  - v3 TypeScript migration preflight in packages/cli/src/migrate/v2HandoffManifest.ts
+performance:
+  reader_preflight_budget_ms: 100
+  note: >-
+    When the manifest is present and valid, the v3 reader must complete parsing
+    and validation within 100ms. When absent or invalid, the reader may fall
+    back to a full app-home scan with no time budget.
+required_top_level_fields:
+  schema_version:
+    type: string
+    const: agentera.v3_handoff_manifest.v1
+  written_at:
+    type: string
+    format: iso8601_utc
+    description: UTC timestamp when the manifest was last written.
+  installed_v2_version:
+    type: string
+    min_length: 1
+    description: Installed Agentera suite version from the active v2 bundle marker.
+  app_home_path:
+    type: string
+    min_length: 1
+    description: Absolute resolved app-home path the writer used.
+  user_data_inventory:
+    type: array
+    min_items: 6
+    description: >-
+      One entry per catalog id below. Entries for paths that do not exist on disk
+      set exists=false; writers still emit the full catalog so v3 preflight can
+      trust absence without rescanning.
+  runtime_adapters:
+    type: array
+    items:
+      type: string
+    description: >-
+      Runtime adapter ids (references/adapters/runtime-adapter-registry.yaml)
+      that the v2 install actively uses — runtimes whose setup doctor status is
+      pass at write time.
+user_data_inventory_catalog:
+  - id: benchmarks
+    relative_path: benchmarks
+    kind: directory
+  - id: intermediate
+    relative_path: intermediate
+    kind: directory
+  - id: sessions
+    relative_path: sessions
+    kind: directory
+  - id: history
+    relative_path: history
+    kind: directory
+  - id: corpus
+    relative_path: corpus
+    kind: directory
+  - id: profile_files
+    kind: profile_files
+    members:
+      - relative_path: PROFILE.md
+        kind: file
+      - relative_path: USAGE.md
+        kind: file
+user_data_inventory_entry_shapes:
+  directory:
+    required: [id, relative_path, kind, exists]
+    kind_const: directory
+  file:
+    required: [id, relative_path, kind, exists]
+    kind_const: file
+  profile_files:
+    required: [id, kind, members]
+    kind_const: profile_files
+    members:
+      required: [relative_path, kind, exists]
+      kind_const: file
+freshness:
+  writer_obligations:
+    - Refresh the manifest on every v2 upgrade apply.
+    - Refresh the manifest on v2 doctor when stale or missing (after warning).
+  stale_when_any:
+    - Manifest file missing.
+    - schema_version mismatch.
+    - app_home_path differs from the resolved install root.
+    - installed_v2_version differs from the active bundle marker version.
+    - written_at is older than the bundle marker mtime.

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

@@ -18,7 +18,7 @@ authority_order:
   - 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,17 +26,20 @@ 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
@@ -62,9 +65,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 +153,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 (`npx -y agentera@latest`, ships 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