agentera 3.0.0-dev.7 → 3.0.0-dev.72

package/bundle/skills/agentera/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: agentera
 description: >
-  One agent, one CLI, many capabilities. Per-capability prose lives in
+  One agent, one CLI, many capabilities. Per-capability instructions live in
   `packages/cli/src/capabilities/<name>/instructions.ts` and the runtime serves
-  it through `agentera prime --context <name> --format json`. Use this skill
+  it through `npx -y agentera@next prime --context <name> --format json`. Use this skill
   for /agentera and Agentera capability requests; bare `/agentera` runs the
-  agentera prime orientation dashboard path instead of a generic greeting.
+  prime orientation dashboard path instead of a generic greeting.
 version: "3.0.0"
 spec_sections: [1, 2, 3, 4, 5, 6, 11, 13, 18, 19, 20, 22, 23]
 capabilities:
@@ -25,63 +25,122 @@ capabilities:
 
 # agentera
 
-One agent, one CLI, many capabilities. The CLI is the routing brain — it owns
-project memory, capability prose, 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.
 
 ---
 
 ## Bootstrap
 
-Run `agentera prime` for orientation. The JSON it returns is the complete
-contract — app status, state slices, attention items, next action, and the
-source contract that declares what's complete and what requires fallback.
+Run one pre-cutover `@next` call for orientation. It is read-only in fresh, v2,
+partially migrated, and v3 projects. A Git-root project with no `.agentera`
+state is `fresh_uninitialized`: `prime --context plan` is operable and its first
+`state plan create` is the sole initializer. Recognized v2 state returns the
+full entity-upgrade recovery; partial, corrupt, and unknown marker-absent state
+returns read-only recovery. V3 returns `ok` unless health is degraded. The JSON
+also returns bounded app status, state slices, attention, and startup
+availability.
 
 ```bash
-npx -y agentera prime
+npx -y agentera@next prime --context status --format json
 ```
 
+An `ok` outcome needs no fallback or second dashboard call. Follow an exact
+recovery command for other outcomes; every returned v3 command stays on
+`npx -y agentera@next`. Do not use bare or stable-channel CLI forms before
+stable promotion. For deeper read-only evidence, run
+`npx -y agentera@next doctor --format json`.
+
 For capability-specific startup context:
 
 ```bash
-npx -y agentera prime --context <capability> --format json
+npx -y agentera@next prime --context <capability> --format json
 ```
 
-This returns the capability's prose, declared read/write needs, artifact
-inventory, included/missing state, and fallback commands. Use it before
-reading the instructions module directly.
+This returns the capability's instructions, declared read/write needs, artifact
+inventory, and `capability_context.startup`. Check its `outcome` (`ok`,
+`degraded`, or `blocked`). The `availability` rows identify bounded included
+families and deferred families; use a deferred row's `detail_command` for
+detail. Use this response before reading the instructions module directly.
 
-For static routing guidance (agentera vs native tools):
+For static routing guidance (CLI vs native tools):
 
 ```bash
-npx -y agentera prime --guidance
+npx -y agentera@next prime --guidance
 ```
 
+### Upgrade from v2 to v3 development
+
+The preview is optional. Apply is one full command:
+
+```bash
+npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+npx -y agentera@next upgrade --channel development --project "$PWD" --yes
+```
+
+Apply requires the complete v2 migration source to be tracked by Git and
+unchanged at `HEAD`. The boundary is one-way: there is no rollback, restore,
+non-Git, or partial cross-major workflow. Rerun the same apply command after an
+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` | Run `agentera prime`. Render the dashboard from the data returned. Follow `next_action` to suggest the next capability. |
-| `/agentera <capability-name>` | Run `agentera prime --context <capability>`. Follow the capability's prose and contract. |
+| Bare `/agentera` | 1. Run `npx -y agentera@next 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 `npx -y agentera@next 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`. 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 `npx -y agentera@next 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 `npx -y agentera@next 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. Read that response's `receipt_contract` for the exact nullable `agentera.route_receipt.v1` schema, outcomes, nullability, compound and span rules, and runnable stdin example; `npx -y agentera@next route receipt --help` presents the same guide.
+
+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 `npx -y agentera@next prime --context <selected-capability> --format json` path).
+After the CLI validates a `select` receipt, then run `npx -y agentera@next 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 `npx -y agentera@next 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:
 
@@ -96,27 +155,16 @@ Capability handoffs use glyph plus canonical name (e.g. `⧉ build`, `≡ plan`)
 
 ## Dashboard rendering
 
-When rendering the prime dashboard for the user, transform the CLI's source
-labels into the README-style layout. Do not paste raw `prime` JSON or raw
-labels (`mode:`, `profile:`, `health:`, etc.) as the briefing.
-
-```text
-┌─┐┌─┐┌─┐┌┐┌┌┬┐┌─┐┬─┐┌─┐
-├─┤│ ┬├┤ │││ │ ├┤ ├┬┘├─┤
-┴ ┴└─┘└─┘┘└┘ ┴ └─┘┴└─┴ ┴
-
-─── status ─────────────────────────────
-  [metric lines: health, todo, plan, objective, profile as available]
-  [1-2 sentence narrative read closing the status section]
-─── attention ──────────────────────────
-─── next ───────────────────────────────
-```
-
-Metrics first, narrative read inside `status`, then attention and next. The todo
-summary line uses `critical · degraded · normal · annoying` in the order prime
-emits them. Omit `attention` only when the source has no attention items.
-Always include the `⌂ status · <status>` marker below the dashboard, and ask
-for confirmation before invoking the suggested downstream capability.
+The prime dashboard rendering contract — template, field-by-field rules, output
+budget, attention-item ordering, exit marker — is owned by the status capability
+instructions. `npx -y agentera@next prime --context status --format json` returns the full
+`capability_context.instructions` body and the bounded
+`capability_context.context.status_context` state and one
+`capability_context.startup` availability projection in one response. Render
+from that capsule without a separate bare-prime call or raw artifact read. An
+`ok` outcome needs no second call; for deferred detail, use only that family's
+exact `detail_command`.
+Ask for confirmation before invoking a state-changing downstream capability.
 
 The first response in a fresh interaction delivers the brief and a free-form
 continuation prompt, not a native question menu — unless the user explicitly
@@ -131,7 +179,8 @@ Proceed/Cancel handoff.
 - NEVER push to remote repos without explicit user instruction
 - NEVER modify `.agentera/vision.yaml` or objective state during execution cycles (only the user or the owning capability may change these)
 - NEVER commit secrets or credentials to any artifact or file
-- Respect artifact path resolution: check `.agentera/docs.yaml` for path overrides before accessing any agent-facing artifact
+- For supported mutations, use the state writer; it resolves `.agentera/docs.yaml` path overrides and validates the published bytes
+- For direct access to other agent-facing artifacts, respect `.agentera/docs.yaml` path overrides
 </critical>
 
 ---
@@ -155,17 +204,88 @@ Proceed/Cancel handoff.
 
 ---
 
+## Artifact writes
+
+The CLI state writer is the canonical mutation path for entity-backed state.
+Every public record has `id` and `artifact`, lives in one writer-owned entity
+file, and is retrieved through bounded `list` or exact `get --id` commands. Do
+not edit `.agentera/entities/` directly. The writer assigns bare IDs, validates
+records, publishes atomically, and supports filesystem-safe previews.
+
+Discover the live contract before constructing a write:
+
+```bash
+npx -y agentera@next state decisions explain --format json
+npx -y agentera@next state decisions explain --verb update --format json
+```
+
+The same pattern applies to every writable artifact:
+
+```bash
+npx -y agentera@next state <progress|decisions|plan|health> explain --verb <verb> --format json
+```
+
+Common mutations:
+
+- `npx -y agentera@next state progress append --input <path|-> --format json`
+- `npx -y agentera@next state decisions append --input <path|-> --format json`
+- `npx -y agentera@next state decisions amend --id ID --base-sha256 HASH --input <path|-> --format json`
+- `npx -y agentera@next state decisions update --id ID ... --format json`
+- `npx -y agentera@next state plan create [--force] --input plan.yaml --format json`
+- `npx -y agentera@next state plan append [--plan PLAN_ID] --input task.yaml --format json`
+- `npx -y agentera@next state plan update --id TASK_ID [--plan PLAN_ID] --input task-patch.yaml --format json`
+- `npx -y agentera@next state plan set-status --id TASK_ID --status STATUS --format json`
+- `npx -y agentera@next state plan set-plan-status [--plan PLAN_ID] --status complete --format json`
+- `npx -y agentera@next state plan archive [--plan ID] [--force] --format json`
+- `npx -y agentera@next state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json`
+- `npx -y agentera@next state health append --input audit.yaml --format json`
+- `npx -y agentera@next state todo create --input todo.yaml --format json`
+- `npx -y agentera@next state todo update --id ID --input todo-patch.yaml --format json`
+- `npx -y agentera@next state todo set-severity --id ID ... --format json`
+- `npx -y agentera@next state todo supersede --id ID ... --format json`
+- `npx -y agentera@next state todo resolve --id ID ... --format json`
+- `npx -y agentera@next state todo reopen --id ID ... --format json`
+
+TODO create input is a full YAML/JSON typed record. TODO update input is a
+patch: omitted fields remain unchanged and only `target_version`,
+`requirements`, `acceptance`, and `readiness` accept typed clears. Public TODO
+fields remain TODO.md-owned; readiness, dependencies, gates, evidence, and
+lifecycle metadata remain Agentera-owned. Lifecycle verbs are flag-only and do
+not accept record payloads.
+
+Plan create task numbers and dependency values are create-local symbolic
+ordinals inside one atomic input document; the writer removes them before
+publishing bare ten-letter plan and task envelope IDs. A legacy composite
+`header.id` is migration-only and is never a public selector. Post-publication
+task append/update payloads use only mutable task content and bare task IDs.
+Without `--force`, an open plan blocks creation. With exactly one canonical open
+predecessor, forced create archives that plan without changing task, evaluation,
+or completion history, then records its bare ID in the successor's
+writer-owned `previous_plan_archived` field. Forced archive preserves the same
+history. Multiple implicit open candidates reject before effects. When they
+block a reader or implicit writer, use the targeted replacement command only
+after canonical evidence names both roles; list order never assigns predecessor
+or successor roles.
+
+Add `--dry-run` to preview any mutation without publishing it. Artifacts not
+listed above are outside the typed writer contract and remain governed by their
+owning capability's instructions and safety rails.
+`npx -y agentera@next schema --format json` exposes the machine-readable writer operation matrix under
+`state_writer` and on each writable `artifact_schemas[*].write_interface`.
+
+---
+
 ## Artifact path resolution
 
-Before reading or writing any artifact, check if `.agentera/docs.yaml` exists.
-If it has an Artifact Mapping section, use the path specified for each canonical
-filename. If `.agentera/docs.yaml` doesn't exist or has no mapping for a given
-artifact, use the default layout:
+The state writer resolves entity storage itself. Before directly reading or
+writing an intentional singleton outside the writer contract, check whether
+`.agentera/docs.yaml` maps it to another path. If no mapping exists, use the
+default singleton layout:
 
 - Human-facing artifacts at the project root: `TODO.md`, `CHANGELOG.md`, `DESIGN.md`
-- Agent-facing artifacts in `.agentera/` as YAML: `progress.yaml`, `decisions.yaml`, `health.yaml`, `plan.yaml`, `docs.yaml`, `vision.yaml`, `objective.yaml`, `experiments.yaml`
+- Agent-facing singletons: `.agentera/docs.yaml` and `.agentera/vision.yaml`
 
-Do not silently bypass the CLI and read raw `.agentera/*.yaml` files first. If
+Do not silently bypass the CLI and read raw entity files first. If
 CLI state declares complete coverage, do not perform defensive raw artifact
-reads. Use raw artifact reads only as a last-resort fallback after CLI
-fallback commands fail or declare incomplete state.
+reads. Use raw artifact reads only as a last-resort after the applicable
+availability row's exact detail command fails or state declares corruption.

package/bundle/skills/agentera/capabilities/audit/schemas/artifacts.yaml

@@ -1,17 +1,19 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: health
+    artifact: health
     local_role: produces_and_consumes
     description: >-
       Codebase health assessment with findings, dimension grades, and trajectory.
       Audit writes audit entries with per-dimension grades, findings with
       severity and confidence scores, trend comparisons, and de facto
       architecture patterns. During evaluation startup, Audit consumes health
-      state through CLI `evidence_context` before raw health artifact fallback.
+      state through CLI `evidence_context`, then bounded `npx -y agentera@next state health
+       list --limit 20 --format json` and exact `state health get --id ID`.
+      Raw health reads are diagnostic-only for corruption or CLI-defect investigation.
   2:
     id: A2
-    artifact_id: vision
+    artifact: vision
     local_role: consumes
     description: >-
       Audit treats vision state as protected during evidence-context startup;
@@ -19,56 +21,62 @@ ARTIFACTS:
       instead of forcing a raw vision read.
   3:
     id: A3
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
-      Audit consumes decision caveats through CLI `evidence_context` and the
-      listed `agentera decisions --format json` fallback before raw decisions artifact fallback.
-      Compacted decision caveats must be preserved rather than reconstructed.
+      Audit consumes decision caveats through CLI `evidence_context`, then
+      bounded `npx -y agentera@next state decisions list --limit 20 --format json` discovery
+       and exact `state decisions get --id ID` retrieval. Raw decision reads
+      are diagnostic-only for corruption or CLI-defect investigation. Compacted
+      decision caveats must be preserved rather than reconstructed.
   4:
     id: A4
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Audit reads this to avoid re-reporting known issues and writes to it
       with user confirmation when filing
       critical and warning findings. During evaluation startup, known TODO state is
-      consumed through CLI `evidence_context` before raw TODO artifact fallback.
+      consumed through CLI `evidence_context`; raw TODO reads are diagnostic-only
+      for corruption or CLI-defect investigation.
   5:
     id: A5
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Audit consumes latest progress verification and progress caveats through
-      CLI `evidence_context` before raw progress artifact fallback.
+      CLI `evidence_context`, then bounded `npx -y agentera@next state progress list --limit
+       20 --format json` discovery and exact `state progress get --id ID`
+      retrieval. Raw progress reads are diagnostic-only for corruption or
+      CLI-defect investigation.
   6:
     id: A6
-    artifact_id: plan
+    artifact: plan
     local_role: consumes
     description: >-
       Audit consumes evaluation target and plan criteria through CLI
-      `evidence_context` before raw plan artifact fallback. The plan's Created date
+      `evidence_context` before any diagnostic-only raw plan read. The plan's Created date
       still provides the artifact-current-state baseline when that state is needed.
   7:
     id: A7
-    artifact_id: design
+    artifact: design
     local_role: consumes
     description: >-
       Audit treats design state as optional during evidence-context startup;
-      missing design caveats from CLI `evidence_context` are preserved before any raw
-      design artifact fallback.
+      missing design caveats from CLI `evidence_context` are preserved before any
+      diagnostic-only raw design read.
   8:
     id: A8
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Audit reads this first to resolve project-local artifact mappings
       and checks the versioning convention for the version health dimension. During
       evaluation startup, docs state and version-boundary caveats are consumed through
-      CLI `evidence_context` before raw docs artifact fallback.
+      CLI `evidence_context` before any diagnostic-only raw docs read.
   9:
     id: A9
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Audit consumes profile status and stale-profile caveats through CLI

package/bundle/skills/agentera/capabilities/audit/schemas/exit.yaml

@@ -4,8 +4,8 @@ EXIT_CONDITIONS:
     condition: complete
     description: >-
       All selected audit dimensions were assessed, findings were synthesized,
-      grades were assigned, HEALTH.md was updated, and the user was presented
-      with actionable results.
+      grades were assigned, the health artifact was updated, and the user was
+      presented with actionable results.
     exit_signal: complete
   2:
     id: E2

package/bundle/skills/agentera/capabilities/audit/schemas/triggers.yaml

@@ -1,47 +1,25 @@
 TRIGGERS:
   1:
     id: T1
-    description: >-
-      Direct invocation by name or slash command. Matches when the user
-      explicitly requests audit.
+    description: Audit local codebase health, architecture, quality, or technical debt.
     priority: high
-    patterns:
-      - "audit"
-      - "/audit"
-    confidence_threshold: 60
-    borderline_band: 10
-    patterns_regex:
-      - "\\b/audit\\b"
   2:
     id: T2
-    description: >-
-      Audit and codebase health requests. Matches when the user wants to
-      assess codebase health, architecture quality, or structural integrity.
-    priority: medium
-    patterns:
-      - "audit the codebase"
-      - "check code health"
-      - "architecture review"
-      - "find technical debt"
-      - "assess code quality"
-      - "how healthy is this codebase"
-      - "what needs fixing"
-      - "structural review"
-      - "pattern audit"
-      - "dependency check"
-      - "test coverage audit"
-    confidence_threshold: 55
+    description: Review the local repository's code, architecture, dependencies, or structural health.
+    priority: high
+    disambiguates_against:
+      - capability: research
+        hint: "audit reviews this local codebase; research analyzes an external source or repository"
+      - capability: document
+        hint: "audit owns code and architecture health; document owns documentation maintenance and docs audits"
+      - capability: design
+        hint: "audit owns code and architecture health; design owns visual identity and design-system review"
+      - capability: optimize
+        hint: "audit assesses local health; optimize improves an existing system against a measurable target"
   3:
     id: T3
-    description: >-
-      Implicit trigger after extended build activity. Matches when
-      build has run 5+ cycles without a health check and the system
-      detects an overdue audit.
+    description: Review local health after implementation activity reveals a need for assessment.
     priority: medium
-    patterns:
-      - "health check overdue"
-      - "audit after build"
-    confidence_threshold: 50
     disambiguates_against:
       - capability: build
         hint: "audit checks codebase health after build activity; build continues development"

package/bundle/skills/agentera/capabilities/audit/schemas/validation.yaml

@@ -24,9 +24,10 @@ VALIDATION:
     id: V3
     rule: decisions_respected
     description: >-
-      Findings that contradict deliberate decisions documented in DECISIONS.md
-      MUST be discarded or downgraded to info (SF3). A deliberate decision is
-      not a finding; it is an implementation of that decision.
+      Findings that contradict deliberate decisions returned by the bounded
+      decisions entity view MUST be discarded or downgraded to info
+      (SF3). A deliberate decision is not a finding; it is an
+      implementation of that decision.
     severity: critical
     checks:
       - "No finding contradicts a known deliberate decision"
@@ -65,25 +66,25 @@ VALIDATION:
     id: V7
     rule: evidence_context_first
     description: >-
-      Audit evaluation startup MUST begin with `agentera prime --context
+      Audit evaluation startup MUST begin with `npx -y agentera@next prime --context
       audit --format json` and use complete CLI `evidence_context` before
-      raw plan, progress, docs, health, TODO, or decisions artifacts.
+      bounded state list/get contracts for plan, progress, docs, health, TODO,
+      or decisions. Raw artifact access is diagnostic-only.
     severity: critical
     checks:
-      - "Evidence context is requested through prime --context before raw artifacts"
-      - "Complete evidence_context is used for evaluation target, criteria, evidence, caveats, and residual risks"
+      - "Evidence context is requested through prime --context before bounded state list/get"
   8:
     id: V8
     rule: evidence_context_fallback_before_raw
     description: >-
       When evidence_context is absent, incomplete, or caveated for needed state,
-      Audit MUST run listed existing CLI fallback commands before any last-resort
-      raw artifact read.
+       Audit MUST run listed bounded CLI fallback commands before any
+       diagnostic-only raw artifact read.
     severity: critical
     checks:
-      - "evidence_context.fallback_commands are attempted before raw artifact reads"
+      - "evidence_context.fallback_commands are attempted before diagnostic-only raw reads"
       - "capability_context.state.fallback_commands is used when evidence_context is unavailable"
-      - "Raw artifact reads are last-resort diagnostics, not normal evaluation startup"
+      - "Raw artifact reads are diagnostic-only, not normal evaluation startup"
   9:
     id: V9
     rule: evidence_context_caveats_preserved
@@ -111,3 +112,21 @@ VALIDATION:
       - "Provisional satisfaction requires evidence"
       - "Only the user confirms final satisfaction"
       - "Missing or compacted satisfaction caveats are preserved"
+  11:
+    id: V11
+    rule: terminology_drift_read_only
+    description: >-
+      Terminology-drift findings MUST cite every variant with verified
+      project-relative file and line evidence. Canonical terms are proposals,
+      never decisions or writes. Optional personal-profile divergence is
+      comparison evidence only; missing profile evidence produces no claim.
+      Audit remains mutation-free and read-only. Build project-glossary
+      publication is active. Audit performs no consumer lookup; Discuss, Plan,
+      and Build use the separate active read-only advice path. Personal-profile
+      mutation and docs-mapping mutation remain outside both paths.
+    severity: critical
+    checks:
+      - "Every reported drift variant has project-file evidence"
+      - "Weak, deliberate, tracked, and no-drift candidates produce no finding"
+      - "Audit mutates no glossary, profile, docs mapping, code, or project file"
+      - "Build publication and read-only glossary consumers are active under separate mutation boundaries"