agentera 3.0.0-dev.1 → 3.0.0-dev.10

package/bundle/references/cli/capability-instruction-structure.md

@@ -0,0 +1,144 @@
+# Capability instruction structure
+
+Origin: Decision 80 (2026-07-06) — Six-section spine for capability instructions.
+Builds on D79 (status rewrite, direct-contract philosophy), D71 (RFC 2119 modal
+vocabulary), D72 (bundle-to-app terminology), D57/D65 (instructions.ts as
+canonical module served via `agentera prime --context`).
+
+Agentera's 12 capability instruction files (`packages/cli/src/capabilities/<name>/instructions.ts`)
+MUST follow a shared six-section spine. Five sections are shape-constrained; one
+(Workflow phases) is mandatory-as-section but free-form in content. This document
+owns the spine spec, the five workflow shapes taxonomy, and the per-capability
+deviation table filled incrementally as each audit completes.
+
+---
+
+## The six-section spine
+
+Every capability instructions.ts MUST contain these six sections in order:
+
+### 1. Purpose
+
+One paragraph stating what the capability does, plus the capability glyph
+(SG1-SG12). Shape-constrained: glyph plus one-paragraph purpose. No sub-sections.
+
+### 2. State artifacts
+
+What the capability reads, writes, and consumes. Shape-constrained:
+reads/writes/consumes declarations plus artifact path resolution. Per-capability
+artifact-schema subsections allowed (e.g., vision's `vision.yaml shape`, document's
+`docs.yaml shape`, design's `DESIGN.md format`).
+
+### 3. Workflow phases (mandatory section, free-form content)
+
+The per-capability core. The section MUST exist and MUST be named "Workflow phases"
+or a per-capability equivalent that names the workflow shape (e.g., "The orchestration
+loop", "The cycle", "Briefing", "Running state"). Internal structure is per-capability:
+linear steps, conversational loop, cycle-based, mode-split, or multi-surface. See
+the five workflow shapes taxonomy below.
+
+### 4. Safety rails
+
+`<critical>` block with MUST NOT / NEVER rules. Protocol-bound. Shape-constrained:
+MUST start with `<critical>` tag, MUST use D71 RFC 2119 modal vocabulary for
+protocol-force rules.
+
+### 5. Exit signals
+
+EX1-EX4 conditions with the capability's canonical glyph marker. Protocol-bound.
+Shape-constrained: MUST list all four exit conditions, MUST use the
+`<glyph> <capability> · <status>` marker format.
+
+### 6. Cross-capability integration
+
+Feeds-into, triggers, and informed-by declarations, plus getting-started use-case
+examples (when to invoke this capability from other contexts). Shape-constrained:
+MUST be present; depth is per-capability (status = one paragraph; orchestrate =
+substantial surface descriptions). Invocation guidance ("Before a build session,
+run `/agentera discuss`") folds into this section as the inverse of
+feeds-into/triggers — same relationship, consumer perspective.
+
+---
+
+## Flex sections (per-capability optional)
+
+Domain content sections MAY appear between spine sections when the capability has
+capability-specific content that does not fit the spine (e.g., design: Colors and
+Typography; profile: PROFILE.md template; research: deliverable template). These
+are rare and documented in the deviation table below.
+
+---
+
+## Five workflow shapes taxonomy
+
+Capabilities declare their workflow shape at the top of the Workflow phases section
+so the deviation table can classify them:
+
+| Shape | Capabilities | Structure |
+|---|---|---|
+| **Linear** | status, research, audit | Step N then Step N+1; one-shot progression |
+| **Conversational loop** | discuss | Scratchpad plus per-turn question loop; no linear progression |
+| **Cycle-based** | build, optimize | Iterative cycle with hypothesis/task/constraints; repeat until done |
+| **Mode-split** | vision, document, profile, design, plan | Step 0 detect mode then mode-A / mode-B / mode-C |
+| **Multi-surface** | orchestrate | Multiple surface templates with different structures per surface |
+
+---
+
+## Reference implementation
+
+Status (D79) is the reference implementation. Its structure:
+
+1. **Purpose**: header plus glyph plus one-paragraph purpose plus direct-contract rule
+2. **State artifacts**: source_contract.capability_startup delegation rule (lean on
+   the contract; do not re-encode machine-readable rules in prose)
+3. **Workflow phases**: Dashboard rendering then Briefing then Routing suggestion
+   (linear shape, three phases)
+4. **Safety rails**: six MUST NOT rules in `<critical>` block
+5. **Exit signals**: EX1-EX4 with `⌂ status · <status>` marker
+6. **Cross-capability integration**: one paragraph (status has no
+   getting-started use-case examples to fold in)
+
+Prose length: 10,389 chars. Modal vocabulary: 5 MUST, 5 MUST NOT. No v2-era residue.
+
+---
+
+## Per-capability deviation table
+
+Filled incrementally as each audit completes. "Not audited" = not yet audited
+against D80 plus this reference doc.
+
+| Capability | Shape | Length | D71 modal | D72 terms | Direct contract | Deviations | Audit |
+|---|---|---|---|---|---|---|---|
+| ⌂ status | Linear | 10,389 | Yes | Yes | Yes | None | Complete (D79) |
+| ⛥ vision | Mode-split | 16,667 | Yes | Yes | Yes | Has vision.yaml shape subsection; shared pre-write self-audit hoist (DRY between Create and Refine modes) | Complete (D81) |
+| ❈ discuss | Loop | 13,816 | Not audited | Not audited | Not audited | Has deliverable template; has Getting started to fold | Not audited |
+| ⬚ research | Linear | 12,251 | Not audited | Not audited | Not audited | Has deliverable template; has Notes on depth | Not audited |
+| ≡ plan | Mode-split | 14,800 | Not audited | Not audited | Not audited | Has light/normal/full modes; has How build reads PLAN.md | Not audited |
+| ⧉ build | Cycle | 20,662 | Not audited | Not audited | Not audited | Has Handling blocked work; no Getting started | Not audited |
+| ⎘ optimize | Cycle | 25,990 | Not audited | Not audited | Not audited | Has Handling blocked experiments | Not audited |
+| ⛶ audit | Linear | 31,313 | Not audited | Not audited | Not audited | Has finding taxonomy plus health.yaml write; Steps 1-7 | Not audited |
+| ▤ document | Mode-split | 21,779 | Not audited | Not audited | Not audited | Has closeout context startup; has docs.yaml shape | Not audited |
+| ♾ profile | Mode-split | 24,219 | Not audited | Not audited | Not audited | Has PROFILE.md template; has Notes on depth vs speed | Not audited |
+| ◰ design | Mode-split | 20,596 | Not audited | Not audited | Not audited | Has Colors/Typography domain content; has DESIGN.md format | Not audited |
+| ⎈ orchestrate | Multi-surface | 28,544 | Not audited | Not audited | Not audited | Has three surface templates; has Keeping the orchestrator lean | Not audited |
+
+---
+
+## Cross-cutting rules (apply to all 12)
+
+These rules are inherited from prior decisions and are not re-stated per capability:
+
+- **D71**: RFC 2119 modal vocabulary (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY).
+  Capitalized keywords carry protocol force; lowercase modal verbs are ordinary English.
+- **D72**: `app.*` terminology (not `bundle.*`).
+- **D79 direct-contract philosophy**: lean on `source_contract.capability_startup`;
+  the prose MUST NOT re-encode rules the contract mechanizes (forbidden-command lists,
+  fallback ladders, do-not-read-raw-yaml warnings). If `complete_for_capability_startup`
+  is true, the prose trusts the contract.
+- **D57/D65**: instructions.ts is the canonical module, served via
+  `agentera prime --context <name> --format json`.
+- **Artifact path resolution**: SKILL.md owns the host-bootstrap artifact-path
+  resolution; capability prose delegates (status proved this in D79).
+- **Procedural recovery content**: lives in the owning capability, not the consuming
+  one (status renders `project_integration` fields; upgrade/doctor owns the repair
+  procedure).

package/bundle/references/cli/capability-tool-classification.yaml

@@ -7,47 +7,47 @@ classification:
   mutation_capable:
     description: Needs file write, edit, and/or shell execution to fulfill purpose
     capabilities:
-      realisera:
+      build:
         permission: {write: allow, bash: allow}
         rationale: Autonomous dev execution — writes code, runs tests/builds, commits
-      optimera:
+      optimize:
         permission: {write: allow, bash: allow}
         rationale: Metric-driven optimization — runs experiments, writes harnesses
-      orkestrera:
+      orchestrate:
         permission: {write: allow, bash: allow}
         rationale: Multi-cycle orchestration — dispatches workers, updates plan/progress
-      dokumentera:
+      document:
         permission: {write: allow, bash: deny}
         rationale: Documentation generation — creates/updates doc files
-      planera:
+      plan:
         permission: {write: allow, bash: deny}
         rationale: Plan management — writes plan.yaml, archives completed plans
 
   contextual_write:
     description: Writes owned Agentera state artifacts
     capabilities:
-      visionera:
+      vision:
         permission: {write: allow, bash: deny}
         rationale: Writes vision.yaml, archives old visions
-      resonera:
+      discuss:
         permission: {write: allow, bash: deny}
         rationale: Writes decisions.yaml, may update TODO.md
-      visualisera:
+      design:
         permission: {write: allow, bash: deny}
         rationale: Writes DESIGN.md, archives old designs
-      profilera:
+      profile:
         permission: {write: allow, bash: allow}
         rationale: Runs extraction scripts, writes PROFILE.md
-      inspektera:
+      audit:
         permission: {write: allow, bash: deny}
         rationale: Writes health.yaml audit reports
 
   read_only:
     description: Only reads files, searches, analyzes
     capabilities:
-      hej:
+      status:
         permission: {write: deny, bash: deny}
         rationale: Strictly read-only orientation dashboard
-      inspirera:
+      research:
         permission: {write: deny, bash: deny}
         rationale: Analysis-only creative exploration

package/bundle/references/cli/coexistence-probe.yaml

@@ -0,0 +1,13 @@
+# v2/v3 coexistence doctor warning contract (both CLI lines).
+schema_version: agentera.coexistenceProbe.v1
+section_header: Coexistence
+warning:
+  headline: "v3 detected alongside v2; pick one line"
+  resolutions:
+    - complete v3 migration
+    - uninstall v3
+    - stay on v2 explicitly
+naming_divergence:
+  description: "v3 uses English capability IDs (status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, orchestrate); v2 stable uses Swedish -era IDs (hej, visionera, resonera, inspirera, planera, realisera, optimera, inspektera, dokumentera, profilera, visualisera, orkestrera)"
+  v3_canonical: [status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, orchestrate]
+  v2_stable: [hej, visionera, resonera, inspirera, planera, realisera, optimera, inspektera, dokumentera, profilera, visualisera, orkestrera]

package/bundle/references/cli/parity-expected-actual-template.md

@@ -0,0 +1,30 @@
+# Parity EXPECTED/ACTUAL bug-demonstration template
+
+Apply this pattern to `npmParityMatrix` / Python-oracle parity rows when fixing a
+regression: land a **demonstrate** commit first, then a **fix** commit that only
+flips the assertion.
+
+## Workflow
+
+1. **Demonstrate commit** — test passes on broken behavior; correct expectation
+   preserved in a block comment (`EXPECTED`); wrong behavior asserted (`ACTUAL`).
+2. **Fix commit** — delete comment markers and `ACTUAL` line; `EXPECTED` becomes the
+   live assertion. No other edits in the fix commit.
+
+## Minimal vitest shape
+
+See `packages/cli/test/cli/parityExpectedActualTemplate.test.ts` for a runnable
+micro-example. For real parity rows, mirror the pattern in the oracle fixture row
+and `npmParityMatrix.test.ts` drift assertions.
+
+## npmParityMatrix row
+
+When adding a row to the parity matrix for a pre-existing bug:
+
+- Register the row with `drift_direction: equal` as the target after fix.
+- In the demonstrate pass, temporarily pin oracle shape to the **wrong** envelope
+  or assert `ACTUAL` substring in a dedicated regression test.
+- Fix pass restores `equal` against the corrected CLI output.
+
+Do not apply EXPECTED/ACTUAL by default to every row — only where bisect clarity
+justifies the two-commit ritual.

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

@@ -31,7 +31,7 @@ compatibility_boundary: >-
 canonical_concept_order:
   - request_to_capability_routing
   - next_action_recommendation
-  - orkestrera_task_assignment
+  - orchestrate_task_assignment
   - worker_launch
   - runtime_subagent_support
   - worker_safety_git_commit
@@ -40,7 +40,7 @@ canonical_concepts:
     definition: >-
       Agentera chooses the capability that should handle a user request, using
       direct routes, primary route aliases, trigger schemas, disambiguation, or
-      fallback to hej.
+      fallback to status.
     preferred_terms:
       - Agentera router
       - request-to-capability routing
@@ -65,15 +65,15 @@ canonical_concepts:
       - force
       - chain
       - conductor handoff
-  orkestrera_task_assignment:
+  orchestrate_task_assignment:
     definition: >-
-      Orkestrera assigns approved plan work to a worker capability during an
+      Orchestrate assigns approved plan work to a worker capability during an
       explicitly orchestrated flow; it evaluates the result instead of implementing
       the task itself.
     preferred_terms:
       - delegate
       - delegation
-      - Orkestrera task delegation
+      - Orchestrate task delegation
       - assigned plan work
     forbidden_ambiguous_shortcuts:
       - conductor
@@ -82,7 +82,7 @@ canonical_concepts:
       - orchestrator implementation
   worker_launch:
     definition: >-
-      Realisera or Optimera starts a worker through the host runtime when an
+      Build or Optimize starts a worker through the host runtime when an
       implementation or measurement cycle needs isolated execution.
     preferred_terms:
       - spawn
@@ -171,9 +171,9 @@ focused_scan:
     - (retired maintainer measurement tool)
     - skills/agentera/SKILL.md
     - skills/agentera/references/contract.md
-    - skills/agentera/capabilities/realisera/instructions.md
-    - skills/agentera/capabilities/optimera/instructions.md
-    - skills/agentera/capabilities/orkestrera/instructions.md
+    - packages/cli/src/capabilities/realisera/instructions.ts
+    - packages/cli/src/capabilities/optimera/instructions.ts
+    - packages/cli/src/capabilities/orkestrera/instructions.ts
     - tests/test_skill_dispatch_contract.py
     - tests/test_runtime_adapters.py
     - tests/test_runtime_adapter_registry.py
@@ -222,15 +222,15 @@ focused_scan:
       text: checkpoint before worktree dispatch
       classification: compatibility-preserved
       reason: The contract preserves the parseable historical checkpoint commit message string.
-    - path: ^skills/agentera/capabilities/realisera/instructions\.md$
+    - path: ^packages/cli/src/capabilities/realisera/instructions\.ts$
       text: 'Step 5: Dispatch|checkpoint before worktree dispatch'
       classification: compatibility-preserved
       reason: Realisera preserves the current step heading and checkpoint commit message compatibility string.
-    - path: ^skills/agentera/capabilities/optimera/instructions\.md$
+    - path: ^packages/cli/src/capabilities/optimera/instructions\.ts$
       text: checkpoint before worktree dispatch
       classification: compatibility-preserved
       reason: Optimera preserves the current checkpoint commit message compatibility string.
-    - path: ^skills/agentera/capabilities/orkestrera/instructions\.md$
+    - path: ^packages/cli/src/capabilities/orkestrera/instructions\.ts$
       text: review pressure in dispatch|dispatch/evaluation context|`dispatch` and `chain` are autonomous orchestration verbs
       classification: canonical
       reason: Orkestrera capability prose uses dispatch for its explicitly owned orchestration loop.

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

@@ -0,0 +1,94 @@
+# 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.
+
+## 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.

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` |