omp-llm-role 1.0.0 → 1.2.0

package/src/agent-create.ts

@@ -11,15 +11,16 @@
  * updater in-process right after (the same path `/refresh-roles` takes).
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { AGENT_NAME_RE, RESERVED_AGENT_NAMES, isReadOnlyTools, projectAgentsDir, renderAgentFile, userAgentsDir, writeAgentFile } from "./agent-file.ts";
-import type { RoleDef, SuffixLevel } from "./engine.ts";
+import { AGENT_NAME_RE, RESERVED_AGENT_NAMES, isReadOnlyTools, projectAgentsDir, removeAgentFile, renderAgentFile, userAgentsDir, writeAgentFile } from "./agent-file.ts";
+import { CAPABILITY_FILL, cardinalMetric, rankRole, type Model, type RoleDef, type SuffixLevel } from "./engine.ts";
+import { FEATURES, featureById } from "./features.ts";
 import { metricMeta } from "./explorer/explain.ts";
 import { ARCHETYPES, archetypeById, fitArchetype, type Archetype } from "./role-archetypes.ts";
-import { writeRoleSettings } from "./role-settings.ts";
+import { writeRoleSettings, type RoleWriteResult } from "./role-settings.ts";
 import { isKnownMetric, KNOWN_METRICS, PLUGIN_SETTINGS_PATH } from "./settings.ts";
-import { catalogMetric, type BenchmarkCatalogEntry } from "./benchmark-sources.ts";
+import { catalogBenchmarkDeclaration, catalogMetric, sourceForMetric, type BenchmarkCatalogEntry, type FocusSourceInfo, type SourceDeclaration } from "./benchmark-sources.ts";
 
 /** The architect's output (omp's `/agents` hub contract): the routing rule and
  * the system prompt, plus the identifier omp would use for the file name. */
@@ -42,6 +43,14 @@ export type CreateAgentRequest = {
   tools?: string[];
   scope: "user" | "project";
   image?: boolean;
+  /**
+   * Capability flags to author on the role (`roles.<name>.features.<id>`). The
+   * request wins over the archetype's own `features` list; an unknown id is
+   * rejected by the parser before any write. The flag is persisted, not the
+   * knobs it expands to, so a later change to the recommendation still reaches
+   * the role.
+   */
+  features?: Record<string, boolean>;
   /** Override the generated body. */
   body?: string;
   /**
@@ -66,6 +75,13 @@ export type CreateAgentRequest = {
    * body's `<criteria>` (the architect path gets them in its prompt instead).
    */
   benchmarkLabels?: string[];
+  /**
+   * Per-metric coverage of the ranking field, for the focus-coverage gate and
+   * the report annotation. The extension loads the ranking universe once and
+   * supplies it; omitted (the CLI, tests) means the field size is unknown and
+   * the share rule is skipped.
+   */
+  coverage?: FocusCoverage;
   /** Overwrite an existing agent file. */
   force: boolean;
   dryRun: boolean;
@@ -148,7 +164,7 @@ function buildBody(request: CreateAgentRequest, archetype: Archetype, readOnly:
  * half-enforces (it accepts Σ ∈ [0.99, 1.01]; `rankRole` computes
  * `q = Σ (wᵢ/(1−w_price))·tᵢ`, so any other split silently rescales q against λ).
  */
-function checkWeightMath(name: string, weights: Record<string, number>, required: readonly string[]): string[] {
+export function checkWeightMath(name: string, weights: Record<string, number>, required: readonly string[]): string[] {
   const errors: string[] = [];
   const metrics = Object.keys(weights);
   if (metrics.length === 0) return [`role ${name}: no weights given`];
@@ -183,6 +199,10 @@ export type BenchmarkApplication = {
   added: string[];
   duplicates: string[];
   unknown: string[];
+  /** Focus metrics dropped by the top-K cap (priority order preserved). */
+  dropped: string[];
+  /** Nine-axis assessment per focus metric, for the report annotation. */
+  assessments: Record<string, FocusMetricAssessment>;
 };
 
 /** The backbone every role keeps: the general/reasoning quality axes plus the
@@ -194,6 +214,493 @@ const BACKBONE_METRICS: Record<string, true> = { general: true, reasoning: true,
 const FOCUS_SHARE_FLOOR = 0.25;
 const FOCUS_SHARE_CAP = 0.4;
 
+/** The most focus metrics one role may weight, so one benchmark keeps a decisive
+ * share instead of five sharing the budget. */
+export const FOCUS_METRIC_CAP = 3;
+
+/** The coverage share a fill-0 focus metric must clear to be safe to weight. */
+export const FOCUS_COVERAGE_FLOOR = 0.35;
+
+/** The dispersion floor: IQR/median of the cardinal-normalized covered values.
+ * A metric flatter than this cannot separate models (saturation). */
+export const FOCUS_DISPERSION_FLOOR = 0.05;
+
+/** The staleness bar: months the covered set may trail the pool's newest model
+ * before the source is flagged as frozen. */
+export const FOCUS_STALENESS_MONTHS = 1;
+
+/** The dataset-staleness bar: months since the catalog row's `updated_at` before
+ * a benchmark's dataset is flagged as unmaintained. The issue's user story is
+ * "not updated in over a year", so 12 months. This is the **dataset-date** axis,
+ * distinct from `FOCUS_STALENESS_MONTHS` (the **model-date** freshness axis):
+ * freshness asks whether the benchmark tracks the model field, maintenance asks
+ * whether the benchmark *project* is alive. A benchmark whose dataset was last
+ * touched years ago but whose rows happen to include one recent model passes
+ * freshness and is caught here. */
+export const FOCUS_DATASET_STALENESS_MONTHS = 12;
+
+/** The pool share above which an org's absence from the covered set is flagged
+ * (a smaller provider's absence is not a false positive). */
+export const FOCUS_ORG_MIN_SHARE = 0.1;
+
+/** The self-reported share above which a source is flagged as vendor-submitted.
+ * The per-entry `self_reported` flag is the varying trust signal (measured
+ * 2026-10-07: gpqa 19/20, deepswe-1.1 14/20, terminal-bench-4.0 10/20,
+ * aa-omniscience-index 2/3, automationbench-aa 0/1, the general benchmarks
+ * ~20/20). A strict majority (0.5) flags the mostly-self-reported general/gpqa
+ * sources while passing an independently measured one (automationbench 0/1) and
+ * a half-and-half source (terminal-bench 10/20). `verified` is uniformly `false`
+ * today, so it is carried but not gated. */
+export const FOCUS_SELF_REPORTED_MAX_SHARE = 0.5;
+
+/** The per-entry org share above which a source is flagged as vendor-populated:
+ * one lab's own scores dominate the benchmark's entries. A **chosen, tunable
+ * heuristic** (a strict majority), not a measured value — the source's per-entry
+ * org mix is not measurable from the repo's caches at implementation time, so
+ * this bar is picked to flag a single-lab source while passing a mixed one. The
+ * axis is an annotation, never a gate: a `below-bar` provenance is warned but
+ * never drops a discovered candidate. */
+export const FOCUS_PROVENANCE_DOMINANT_SHARE = 0.5;
+
+/** The relative divergence above which the zeroeval per-entry price/context is
+ * flagged as disagreeing with the plugin's own value. A **chosen, tunable
+ * heuristic** (a factor-of-two band), not a measured value — the two sources are
+ * independent and a small divergence is expected (rounding, a different route
+ * mix). The axis is an annotation, never a gate. */
+export const PRICE_AGREEMENT_TOLERANCE = 0.5;
+
+/** The status vocabulary shared by every focus-metric axis. */
+export type FocusSignal = "ok" | "below-bar" | "unknown";
+
+/** Per-metric coverage of the ranking field (the coverage axis). */
+export type FocusCoverageEntry = {
+  covered: number;
+  total: number | null;
+  share: number | null;
+  fill: number;
+  status: FocusSignal;
+};
+
+/** The nine-axis assessment of one focus metric: coverage, dispersion, provider
+ * composition, freshness, source trust, modality, benchmark maintenance,
+ * provenance and cross-source agreement. The single object the gate and every
+ * report share. */
+export type FocusMetricAssessment = {
+  coverage: FocusCoverageEntry;
+  dispersion: { value: number | null; status: FocusSignal };
+  composition: { omittedOrgs: string[]; status: FocusSignal };
+  freshness: { newestCovered: string | null; newestPool: string | null; monthsBehind: number | null; status: FocusSignal };
+  /** The source's per-entry trust: the self-reported share of the covered
+   * entries. Zeros + `unknown` when the payload carried no entry flags (a
+   * declared/writing source) or the metric's scores were not loaded. `community`
+   * is the catalog row's `is_community` flag: a community-submitted benchmark is
+   * still visible even when the payload half is absent (its scores carry no
+   * entry flags). It is an **annotation, never a gate** — it never changes
+   * `status` and `belowBarReason` has no community branch. */
+  trust: { selfReported: number; covered: number; status: FocusSignal; community: boolean };
+  /** The benchmark's modality: the catalog row's `modality` and the payload's
+   * multimodal share. Informational only — there is no role modality field, so
+   * this axis is never `below-bar` and never a drop reason; it is `unknown` only
+   * when neither the catalog row nor the payload carries a modality signal. */
+  modality: { value: string | null; multimodalShare: number | null; status: FocusSignal };
+  /** The benchmark's own maintenance: the catalog row's `updated_at` age in
+   * months against `FOCUS_DATASET_STALENESS_MONTHS`, with `version_count` and
+   * `star_count` carried as supporting detail. This is the **dataset-date** axis,
+   * distinct from `freshness` (the **model-date** axis): it measures whether the
+   * benchmark *project* is alive, not whether it tracks the model field. It is an
+   * **annotation, never a gate** — `belowBarReason` has no maintenance branch, so
+   * a stale dataset is warned but never drops a discovered candidate. `unknown`
+   * when the catalog row is absent or its `updated_at` is missing/unparseable. */
+  maintenance: { updatedAt: string | null; monthsOld: number | null; versionCount: number | null; starCount: number | null; status: FocusSignal };
+  /** The benchmark's provenance: the catalog row's owning organisation
+   * (`dataset_org_id`, falling back to `dataset_slug`) and the source's own
+   * per-entry org mix (the dominant lab and its share). This is the **source's
+   * own claim** about who publishes the benchmark and whose scores it carries —
+   * an independent cross-check on the pool-derived `composition` axis, not a
+   * replacement for it. `compositionAgreement` records whether the two concur:
+   * `"disagree"` when exactly one of the two flags `below-bar`, `"agree"` when
+   * both or neither do, `"unknown"` when the payload carries no org mix. It is an
+   * **annotation, never a gate** — `belowBarReason` has no provenance branch, so
+   * a vendor-populated source is warned but never drops a discovered candidate.
+   * `unknown` when there is neither an owner nor a payload org mix. */
+  provenance: {
+    owner: string | null;
+    dominantOrg: string | null;
+    dominantShare: number | null;
+    compositionAgreement: "agree" | "disagree" | "unknown";
+    status: FocusSignal;
+  };
+  /** The cross-source agreement: the zeroeval per-entry price/throughput/context
+   * (`BenchmarkPayloadMeta.crossSource`) compared against the plugin's own
+   * `price`/`throughput`/`context` for the models that carry the metric. The join
+   * is **direct on the bare `model_id`** (the generic llm-stats benchmark's
+   * `entries[].model_id` is the llm-stats id, the same space as `Model.id`).
+   * `compared` counts the models present in the map AND carrying the metric;
+   * `priceDivergence`/`contextDivergence` are the median relative divergence
+   * (`|a − b| / max(a, b, 1e-9)`) over the models compared on that axis, `null`
+   * when none. `priceAgreement`/`contextAgreement` are `unknown` when nothing was
+   * compared on the axis, else `ok` within `PRICE_AGREEMENT_TOLERANCE`, else
+   * `below-bar`. `speedAgreement` is **informational only** and excluded from
+   * `status`: the units differ (zeroeval `speed_rps` is requests/s, the plugin's
+   * `throughput` is output tok/s) and re-deriving throughput from `speed_rps` is
+   * explicitly out of scope. `status` is `unknown` when `compared === 0`, else
+   * `below-bar` when `priceAgreement` or `contextAgreement` is `below-bar`, else
+   * `ok`. It is an **annotation, never a gate** — `belowBarReason` has no
+   * cross-source branch, and the axis never feeds `price`/`weightPrice` or any
+   * ranking input. */
+  crossSource: {
+    compared: number;
+    priceAgreement: FocusSignal;
+    contextAgreement: FocusSignal;
+    speedAgreement: FocusSignal;
+    priceDivergence: number | null;
+    contextDivergence: number | null;
+    status: FocusSignal;
+  };
+};
+
+/** Per-metric coverage of the ranking field, for the focus-coverage gate. */
+export type FocusCoverage = {
+  /** Total models in the ranking universe; null when the load failed. */
+  total: number | null;
+  /** metric -> models that actually carry it (not the imputed fill). */
+  covered: Record<string, number>;
+  /** Declared sources, so a declared metric's fill resolves. */
+  declared?: readonly SourceDeclaration[];
+  /** Nine-axis assessment per metric, when the caller assessed the loaded pool.
+   * Absent → the eight new axes are `unknown` (the metric's scores were not
+   * loaded), never a silent `ok`. */
+  assessments?: Record<string, FocusMetricAssessment>;
+};
+
+/** The capability fill a metric's absence is scored at (0 = a coverage penalty). */
+export function metricFill(metric: string, declared: readonly SourceDeclaration[] = []): number {
+  return CAPABILITY_FILL[metric] ?? sourceForMetric(metric, declared)?.fill ?? 0;
+}
+
+/**
+ * The one coverage rule, shared by the discovery gate and the report annotation:
+ * a focus metric is safe when its source is capability-filled (`fill > 0`, so
+ * absence is a known non-penalty) or its coverage share clears
+ * `FOCUS_COVERAGE_FLOOR`. When the field size is unknown the share rule is
+ * skipped and the result is `unknown` (annotated, not warned).
+ */
+export function focusCoverageOk(
+  metric: string,
+  covered: number,
+  total: number | null,
+  declared: readonly SourceDeclaration[] = [],
+): FocusSignal {
+  if (metricFill(metric, declared) > 0) return "ok";
+  if (total === null || total <= 0) return "unknown";
+  return covered / total >= FOCUS_COVERAGE_FLOOR ? "ok" : "below-bar";
+}
+
+/** Count the models a metric actually covers: a non-null value that is not the
+ * source's imputed fill. */
+export function countMetricCoverage(models: readonly Model[], metric: string, declared: readonly SourceDeclaration[] = []): number {
+  const fill = metricFill(metric, declared);
+  let covered = 0;
+  for (const model of models) {
+    const value = model.metrics[metric];
+    if (value == null) continue;
+    if (fill > 0 && value === fill) continue;
+    covered++;
+  }
+  return covered;
+}
+
+/** The covered models' values for a metric, cardinal-normalized: the engine's
+ * transform first (index metrics are raw −16..+60, benchmarks 0–1), so one
+ * dispersion floor is comparable across metrics. The imputed fill is skipped. */
+function coveredValues(models: readonly Model[], metric: string, fill: number): number[] {
+  const values: number[] = [];
+  for (const model of models) {
+    const value = model.metrics[metric];
+    if (value == null) continue;
+    if (fill > 0 && value === fill) continue;
+    values.push(cardinalMetric(metric, value));
+  }
+  return values;
+}
+
+/** Linear-interpolated quantile (R type 7) of a value list. */
+function quantile(values: readonly number[], p: number): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  const h = (sorted.length - 1) * p;
+  const lo = Math.floor(h);
+  const hi = Math.ceil(h);
+  return sorted[lo] + (h - lo) * (sorted[hi] - sorted[lo]);
+}
+
+/** The dispersion axis: IQR/median of the cardinal-normalized covered values.
+ * Fewer than two values, or a zero median, is `unknown` (no scale to divide by). */
+function dispersionAxis(models: readonly Model[], metric: string, fill: number): FocusMetricAssessment["dispersion"] {
+  const values = coveredValues(models, metric, fill);
+  if (values.length < 2) return { value: null, status: "unknown" };
+  const median = quantile(values, 0.5);
+  if (median === 0) return { value: null, status: "unknown" };
+  const value = (quantile(values, 0.75) - quantile(values, 0.25)) / median;
+  return { value, status: value >= FOCUS_DISPERSION_FLOOR ? "ok" : "below-bar" };
+}
+
+/** The composition axis: an org present in the pool above `FOCUS_ORG_MIN_SHARE`
+ * but absent from the covered set is flagged. Orgs below the minimum pool share
+ * are ignored (a small provider's absence is not a false positive). */
+function compositionAxis(models: readonly Model[], metric: string, fill: number): FocusMetricAssessment["composition"] {
+  const poolCounts = new Map<string, number>();
+  const coveredCounts = new Map<string, number>();
+  for (const model of models) {
+    poolCounts.set(model.org, (poolCounts.get(model.org) ?? 0) + 1);
+    const value = model.metrics[metric];
+    if (value == null) continue;
+    if (fill > 0 && value === fill) continue;
+    coveredCounts.set(model.org, (coveredCounts.get(model.org) ?? 0) + 1);
+  }
+  const total = models.length;
+  const omittedOrgs: string[] = [];
+  for (const [org, count] of poolCounts) {
+    if (count / total < FOCUS_ORG_MIN_SHARE) continue;
+    if ((coveredCounts.get(org) ?? 0) === 0) omittedOrgs.push(org);
+  }
+  omittedOrgs.sort();
+  return { omittedOrgs, status: omittedOrgs.length === 0 ? "ok" : "below-bar" };
+}
+
+/** The freshness axis: the newest covered model's date against the pool's newest.
+ * A missing date on either side degrades to `unknown` (a sparse date field must
+ * not false-positive). */
+function freshnessAxis(models: readonly Model[], metric: string, fill: number): FocusMetricAssessment["freshness"] {
+  let newestPool: string | null = null;
+  let newestCovered: string | null = null;
+  for (const model of models) {
+    const date = model.releaseDate;
+    if (date == null) continue;
+    if (newestPool === null || date > newestPool) newestPool = date;
+    const value = model.metrics[metric];
+    if (value == null) continue;
+    if (fill > 0 && value === fill) continue;
+    if (newestCovered === null || date > newestCovered) newestCovered = date;
+  }
+  if (newestPool === null || newestCovered === null) {
+    return { newestCovered, newestPool, monthsBehind: null, status: "unknown" };
+  }
+  // 30.4375 = 365.25/12 days per month, so a calendar-month gap reads as ~1.
+  const monthsBehind = (Date.parse(newestPool) - Date.parse(newestCovered)) / (1000 * 60 * 60 * 24 * 30.4375);
+  return { newestCovered, newestPool, monthsBehind, status: monthsBehind > FOCUS_STALENESS_MONTHS ? "below-bar" : "ok" };
+}
+
+/** The trust axis: the self-reported share of the covered entries against
+ * `FOCUS_SELF_REPORTED_MAX_SHARE`. A payload with no entry flags (a declared or
+ * writing source) or no covered entries is `unknown` — never a silent `ok`. */
+function trustAxis(source?: FocusSourceInfo): FocusMetricAssessment["trust"] {
+  const community = source?.catalog?.isCommunity ?? false;
+  const trust = source?.payload?.trust ?? null;
+  if (trust === null || trust.covered === 0) return { selfReported: 0, covered: 0, status: "unknown", community };
+  return {
+    selfReported: trust.selfReported,
+    covered: trust.covered,
+    status: trust.selfReported / trust.covered > FOCUS_SELF_REPORTED_MAX_SHARE ? "below-bar" : "ok",
+    community,
+  };
+}
+
+/** The modality axis: the catalog row's `modality` and the payload's multimodal
+ * share. Informational only — there is no role modality field, so this axis is
+ * never `below-bar` and never a drop reason; it is `unknown` only when neither
+ * the catalog row nor the payload carries a modality signal. */
+function modalityAxis(source?: FocusSourceInfo): FocusMetricAssessment["modality"] {
+  const value = source?.catalog?.modality ?? null;
+  const summary = source?.payload?.modality ?? null;
+  const multimodalShare = summary !== null && summary.covered > 0 ? summary.multimodal / summary.covered : null;
+  return { value, multimodalShare, status: value === null && multimodalShare === null ? "unknown" : "ok" };
+}
+
+/** The maintenance axis: the catalog row's dataset age against
+ * `FOCUS_DATASET_STALENESS_MONTHS`, with `version_count`/`star_count` carried as
+ * supporting detail. This is the **dataset-date** axis, distinct from `freshness`
+ * (the **model-date** axis). It is an **annotation, never a gate**:
+ * `belowBarReason` has no maintenance branch, so a stale dataset is warned but
+ * never drops a discovered candidate. `unknown` when the catalog row is absent or
+ * its `updated_at` is missing/unparseable. */
+function maintenanceAxis(source?: FocusSourceInfo): FocusMetricAssessment["maintenance"] {
+  const catalog = source?.catalog ?? null;
+  const updatedAt = catalog?.updatedAt ?? null;
+  const versionCount = catalog?.versionCount ?? null;
+  const starCount = catalog?.starCount ?? null;
+  const parsed = updatedAt === null ? Number.NaN : Date.parse(updatedAt);
+  if (Number.isNaN(parsed)) return { updatedAt, monthsOld: null, versionCount, starCount, status: "unknown" };
+  // 30.4375 = 365.25/12 days per month, matching the freshness axis.
+  const monthsOld = (Date.now() - parsed) / (1000 * 60 * 60 * 24 * 30.4375);
+  return { updatedAt, monthsOld, versionCount, starCount, status: monthsOld > FOCUS_DATASET_STALENESS_MONTHS ? "below-bar" : "ok" };
+}
+
+/** The provenance axis: the benchmark's owner (the catalog row's `dataset_org_id`,
+ * falling back to `dataset_slug`) and the source's own per-entry org mix (the
+ * dominant lab and its share). This is the **source's own claim** about who
+ * publishes the benchmark and whose scores it carries — an independent
+ * cross-check on the pool-derived `composition` axis, not a replacement for it.
+ * `compositionAgreement` records whether the two concur: `"disagree"` when
+ * exactly one of the two flags `below-bar`, `"agree"` when both or neither do,
+ * `"unknown"` when the payload carries no org mix. It is an **annotation, never a
+ * gate**: `belowBarReason` has no provenance branch, so a vendor-populated source
+ * is warned but never drops a discovered candidate. `unknown` when there is
+ * neither an owner nor a payload org mix. */
+function provenanceAxis(source: FocusSourceInfo | undefined, compositionStatus: FocusSignal): FocusMetricAssessment["provenance"] {
+  const owner = source?.catalog?.datasetOrgId ?? source?.catalog?.datasetSlug ?? null;
+  const mix = source?.payload?.provenance ?? null;
+  const dominantOrg = mix?.dominantOrg ?? null;
+  const dominantShare = mix?.dominantShare ?? null;
+  const status: FocusSignal =
+    owner === null && mix === null ? "unknown" : dominantShare !== null && dominantShare > FOCUS_PROVENANCE_DOMINANT_SHARE ? "below-bar" : "ok";
+  const compositionAgreement: "agree" | "disagree" | "unknown" =
+    mix === null ? "unknown" : (compositionStatus === "below-bar") !== (status === "below-bar") ? "disagree" : "agree";
+  return { owner, dominantOrg, dominantShare, compositionAgreement, status };
+}
+
+/** The cross-source axis: the zeroeval per-entry price/throughput/context
+ * (`BenchmarkPayloadMeta.crossSource`, keyed by the entry's `model_id`) compared
+ * against the plugin's own `price`/`throughput`/`context`. The join is **direct
+ * on the bare id**: the generic llm-stats benchmark's `entries[].model_id` is the
+ * llm-stats id, the same space as `Model.id` (the same assumption
+ * `parseLlmStatsBenchmark`'s direct join makes). Only models that are BOTH
+ * present in the map AND carry the metric (`m.metrics[metric] != null` and not
+ * the fill) count toward `compared`.
+ *
+ * price compares zeroeval's 3:1 blend `(3·input + output)/4` against `m.price`
+ * ($/M); context compares `row.context` against `m.context`; speed compares
+ * `row.speed` (requests/s) against `m.throughput` (output tok/s). The relative
+ * divergence is `|a − b| / max(a, b, 1e-9)`; `priceDivergence`/
+ * `contextDivergence` are the median over the models compared on that axis
+ * (`null` when none). An axis is `unknown` when nothing was compared on it, else
+ * `ok` within `PRICE_AGREEMENT_TOLERANCE`, else `below-bar`.
+ *
+ * `speedAgreement` is **informational only** and excluded from `status`: the
+ * units differ (rps vs tok/s) and re-deriving throughput from `speed_rps` is
+ * explicitly out of scope. `status` is `unknown` when `compared === 0`, else
+ * `below-bar` when `priceAgreement` or `contextAgreement` is `below-bar`, else
+ * `ok`. It is an **annotation, never a gate** — `belowBarReason` has no
+ * cross-source branch, and the axis never feeds `price`/`weightPrice` or any
+ * ranking input. (A future option, recorded in the docs only: use zeroeval's
+ * list price as a fallback fill for a model with no OpenRouter route.) */
+function crossSourceAxis(models: readonly Model[], metric: string, fill: number, source?: FocusSourceInfo): FocusMetricAssessment["crossSource"] {
+  const map = source?.payload?.crossSource ?? null;
+  const priceDivergences: number[] = [];
+  const contextDivergences: number[] = [];
+  const speedDivergences: number[] = [];
+  let compared = 0;
+  for (const model of models) {
+    const value = model.metrics[metric];
+    if (value == null) continue;
+    if (fill > 0 && value === fill) continue;
+    const row = map?.[model.id];
+    if (row === undefined) continue;
+    compared++;
+    if (row.input !== null && row.output !== null && model.price !== null) {
+      const zeroPrice = (3 * row.input + row.output) / 4;
+      priceDivergences.push(Math.abs(zeroPrice - model.price) / Math.max(zeroPrice, model.price, 1e-9));
+    }
+    if (row.context !== null && model.context !== null) {
+      contextDivergences.push(Math.abs(row.context - model.context) / Math.max(row.context, model.context, 1e-9));
+    }
+    if (row.speed !== null && model.throughput !== null) {
+      speedDivergences.push(Math.abs(row.speed - model.throughput) / Math.max(row.speed, model.throughput, 1e-9));
+    }
+  }
+  const priceDivergence = priceDivergences.length === 0 ? null : quantile(priceDivergences, 0.5);
+  const contextDivergence = contextDivergences.length === 0 ? null : quantile(contextDivergences, 0.5);
+  const speedDivergence = speedDivergences.length === 0 ? null : quantile(speedDivergences, 0.5);
+  const priceAgreement: FocusSignal = priceDivergence === null ? "unknown" : priceDivergence <= PRICE_AGREEMENT_TOLERANCE ? "ok" : "below-bar";
+  const contextAgreement: FocusSignal = contextDivergence === null ? "unknown" : contextDivergence <= PRICE_AGREEMENT_TOLERANCE ? "ok" : "below-bar";
+  const speedAgreement: FocusSignal = speedDivergence === null ? "unknown" : speedDivergence <= PRICE_AGREEMENT_TOLERANCE ? "ok" : "below-bar";
+  const status: FocusSignal = compared === 0 ? "unknown" : priceAgreement === "below-bar" || contextAgreement === "below-bar" ? "below-bar" : "ok";
+  return { compared, priceAgreement, contextAgreement, speedAgreement, priceDivergence, contextDivergence, status };
+}
+
+/** The all-unknown assessment: the field size is unknown, or the metric's scores
+ * were not loaded. Annotated, never warned. */
+function unknownAssessment(coverage: FocusCoverageEntry, source?: FocusSourceInfo): FocusMetricAssessment {
+  return {
+    coverage,
+    dispersion: { value: null, status: "unknown" },
+    composition: { omittedOrgs: [], status: "unknown" },
+    freshness: { newestCovered: null, newestPool: null, monthsBehind: null, status: "unknown" },
+    trust: { selfReported: 0, covered: 0, status: "unknown", community: source?.catalog?.isCommunity ?? false },
+    modality: { value: null, multimodalShare: null, status: "unknown" },
+    maintenance: { updatedAt: null, monthsOld: null, versionCount: null, starCount: null, status: "unknown" },
+    provenance: { owner: null, dominantOrg: null, dominantShare: null, compositionAgreement: "unknown", status: "unknown" },
+    crossSource: { compared: 0, priceAgreement: "unknown", contextAgreement: "unknown", speedAgreement: "unknown", priceDivergence: null, contextDivergence: null, status: "unknown" },
+  };
+}
+
+/**
+ * The one assessment rule, shared by the discovery gate, the report and the
+ * explorer: coverage, dispersion, provider composition, freshness, source trust,
+ * modality, benchmark maintenance, provenance and cross-source agreement of one
+ * focus metric over the loaded pool. `focusCoverageOk`/`countMetricCoverage` are
+ * its coverage branch; `source` (the cached trust, modality, catalog, provenance
+ * and cross-source inputs) is its trust/modality/maintenance/provenance/
+ * cross-source branch.
+ *
+ * An empty pool (unknown field size) or a metric with no covered values (its
+ * scores were not loaded) reports every axis `unknown` — never a silent `ok`.
+ */
+export function assessFocusMetric(
+  models: readonly Model[],
+  metric: string,
+  declared: readonly SourceDeclaration[] = [],
+  source?: FocusSourceInfo,
+): FocusMetricAssessment {
+  const total = models.length;
+  const covered = countMetricCoverage(models, metric, declared);
+  const fill = metricFill(metric, declared);
+  const coverage: FocusCoverageEntry = {
+    covered,
+    total: total > 0 ? total : null,
+    share: total > 0 ? covered / total : null,
+    fill,
+    status: focusCoverageOk(metric, covered, total > 0 ? total : null, declared),
+  };
+  if (total === 0 || covered === 0) return unknownAssessment({ ...coverage, status: "unknown" }, source);
+  const composition = compositionAxis(models, metric, fill);
+  return {
+    coverage,
+    dispersion: dispersionAxis(models, metric, fill),
+    composition,
+    freshness: freshnessAxis(models, metric, fill),
+    trust: trustAxis(source),
+    modality: modalityAxis(source),
+    maintenance: maintenanceAxis(source),
+    provenance: provenanceAxis(source, composition.status),
+    crossSource: crossSourceAxis(models, metric, fill, source),
+  };
+}
+
+/** The one-line reason a below-bar assessment is dropped/warned, naming the
+ * failed axis; null when every axis is ok or unknown. Deliberately has **no
+ * maintenance, provenance or cross-source branch**: those axes are annotations,
+ * never drop reasons, so a stale dataset, a vendor-populated source or a
+ * price/context divergence cannot remove a discovered candidate. */
+export function belowBarReason(assessment: FocusMetricAssessment): string | null {
+  const { coverage, dispersion, composition, freshness, trust } = assessment;
+  if (coverage.status === "below-bar") {
+    return `coverage ${coverage.covered}/${coverage.total} is below the ${Math.round(FOCUS_COVERAGE_FLOOR * 100)}% bar`;
+  }
+  if (dispersion.status === "below-bar") {
+    return `dispersion ${dispersion.value?.toFixed(3)} below the ${FOCUS_DISPERSION_FLOOR} bar`;
+  }
+  if (composition.status === "below-bar") {
+    return `composition omits ${composition.omittedOrgs.join(", ")}`;
+  }
+  if (freshness.status === "below-bar") {
+    return `freshness ${freshness.monthsBehind?.toFixed(1)} months behind the pool`;
+  }
+  if (trust.status === "below-bar") {
+    return `trust ${trust.selfReported}/${trust.covered} self-reported is above the ${FOCUS_SELF_REPORTED_MAX_SHARE} bar`;
+  }
+  return null;
+}
+
 /**
  * Fold user-named benchmarks into a role's weights as a decisive *focus* share.
  *
@@ -211,8 +718,19 @@ const FOCUS_SHARE_CAP = 0.4;
  * known-metric set (a shipped key or an external `<ns>:<local>`) is unknown.
  * Naming the archetype's own specialist set is a no-op (the focus share equals
  * its archetype share). Nothing changes when the list is empty.
+ *
+ * The focus set is capped at `FOCUS_METRIC_CAP` in priority order (named/linked
+ * first, then discovery order), so the caller's explicit choices survive and one
+ * benchmark keeps a decisive share; the metrics beyond the cap are reported as
+ * `dropped`. `coverage.assessments` (the nine-axis assessment the caller computed
+ * over the loaded pool) drives the per-metric annotation; without it the eight
+ * new axes are `unknown` (the metric's scores were not loaded).
  */
-export function applyFocusBenchmarks(weights: Record<string, number>, metrics: readonly string[]): BenchmarkApplication {
+export function applyFocusBenchmarks(
+  weights: Record<string, number>,
+  metrics: readonly string[],
+  coverage?: FocusCoverage,
+): BenchmarkApplication {
   const added: string[] = [];
   const duplicates: string[] = [];
   const unknown: string[] = [];
@@ -225,22 +743,45 @@ export function applyFocusBenchmarks(weights: Record<string, number>, metrics: r
       continue;
     }
     if (focus.includes(metric)) continue; // the same metric named twice
+    focus.push(metric);
+  }
+  const kept = focus.slice(0, FOCUS_METRIC_CAP);
+  const dropped = focus.slice(FOCUS_METRIC_CAP);
+  for (const metric of kept) {
     if (metric in weights) duplicates.push(metric);
     else added.push(metric);
-    focus.push(metric);
   }
-  if (focus.length === 0) return { weights: { ...weights }, added, duplicates, unknown };
+
+  const declared = coverage?.declared ?? [];
+  const total = coverage?.total ?? null;
+  const assessments: Record<string, FocusMetricAssessment> = {};
+  for (const metric of kept) {
+    const assessed = coverage?.assessments?.[metric];
+    if (assessed !== undefined) {
+      assessments[metric] = assessed;
+      continue;
+    }
+    const covered = coverage?.covered[metric] ?? 0;
+    assessments[metric] = unknownAssessment({
+      covered,
+      total,
+      share: total !== null && total > 0 ? covered / total : null,
+      fill: metricFill(metric, declared),
+      status: focusCoverageOk(metric, covered, total, declared),
+    });
+  }
+  if (kept.length === 0) return { weights: { ...weights }, added, duplicates, unknown, dropped, assessments };
 
   const price = weights.price ?? 0;
   const specialistShare = Object.keys(weights)
     .filter((key) => key !== "price" && !BACKBONE_METRICS[key])
     .reduce((sum, key) => sum + weights[key], 0);
   const focusShare = Math.min(FOCUS_SHARE_CAP, Math.max(FOCUS_SHARE_FLOOR, specialistShare));
-  const perFocus = focusShare / focus.length;
+  const perFocus = focusShare / kept.length;
 
   const next: Record<string, number> = { ...weights };
-  for (const metric of focus) next[metric] = perFocus;
-  const rest = Object.keys(next).filter((key) => key !== "price" && !focus.includes(key));
+  for (const metric of kept) next[metric] = perFocus;
+  const rest = Object.keys(next).filter((key) => key !== "price" && !kept.includes(key));
   const restSum = rest.reduce((sum, key) => sum + next[key], 0);
   const target = 1 - price - focusShare;
   if (restSum > 0) for (const key of rest) next[key] = (next[key] * target) / restSum;
@@ -256,11 +797,27 @@ export function applyFocusBenchmarks(weights: Record<string, number>, metrics: r
     const largest = keys.reduce((a, b) => (next[a] >= next[b] ? a : b));
     next[largest] = Math.round((next[largest] + residual) * 1e4) / 1e4;
   }
-  return { weights: next, added, duplicates, unknown };
+  return { weights: next, added, duplicates, unknown, dropped, assessments };
 }
 
-/** A benchmark discovered for a purpose: the metric it feeds and its label. */
-export type DiscoveredBenchmark = { metric: string; label: string };
+/** A benchmark discovered for a purpose: the metric it feeds, its label, the
+ * catalog's model count (the pre-fetch coverage numerator for the report
+ * annotation), and — for an id whose raw form the metric key cannot reconstruct
+ * (a dotted id) — the declaration the caller must persist so the updater can
+ * re-fetch it. */
+export type DiscoveredBenchmark = { metric: string; label: string; covered: number; declaration?: SourceDeclaration };
+
+/** A candidate the discovery gate dropped, with the reason (for the report). */
+export type DroppedBenchmark = { metric: string; label: string; reason: string };
+
+/** The discovery outcome: the benchmarks to fold in, and the ones the coverage
+ * gate dropped (non-fatal, reported). */
+export type DiscoveryOutcome = { discovered: DiscoveredBenchmark[]; dropped: DroppedBenchmark[] };
+
+/** The post-fetch assessor the discovery gate injects: probe-fetch a candidate's
+ * source, join it onto the loaded pool and assess it. The extension supplies the
+ * real one (via `loadBenchmarkScores`); tests inject a stub. */
+export type FocusAssessor = (metric: string) => Promise<FocusMetricAssessment>;
 
 /** Catalog benchmarks with fewer models than this are skipped (a 1-model
  * benchmark would distort the ranking). */
@@ -329,28 +886,59 @@ function rankCatalogCandidates(purpose: string, candidates: readonly BenchmarkCa
  * capped (the catalog is alphabetical, so a blind cap would drop late-sorting
  * benchmarks), a selected benchmark resolves to its shipped metric when one
  * exists (else `bench:<id>`), and a metric already in `exclude` is skipped.
+ *
+ * `fieldSize` is the ranking universe's model count (null when unknown). A
+ * selected benchmark whose metric is fill-0 and whose catalog coverage is below
+ * `FOCUS_COVERAGE_FLOOR` of the field is dropped (non-fatal) with a reason, so a
+ * sparse pass-rate benchmark cannot turn `q` into a coverage score. When the
+ * field size is unknown the share rule is skipped and only the fill rule applies.
+ *
+ * `assess` is the post-fetch gate: the create-agent pool carries no `bench:<id>`
+ * scores, so the caller probe-fetches each survivor's source and assesses the
+ * joined pool. A survivor below-bar on any axis is dropped with a reason naming
+ * the failed axis. Without `assess` only the pre-fetch count gate runs (the
+ * catalog has no scores to assess).
  */
 export async function discoverBenchmarks(
   purpose: string,
   catalog: readonly BenchmarkCatalogEntry[],
   decide: (purpose: string, candidates: readonly BenchmarkCatalogEntry[]) => Promise<readonly string[]>,
   exclude: readonly string[] = [],
-): Promise<DiscoveredBenchmark[]> {
+  fieldSize: number | null = null,
+  assess?: FocusAssessor,
+): Promise<DiscoveryOutcome> {
   const candidates = catalog.filter((entry) => entry.modelCount >= MIN_CATALOG_MODELS);
-  if (candidates.length === 0) return [];
+  if (candidates.length === 0) return { discovered: [], dropped: [] };
   const ranked = rankCatalogCandidates(purpose, candidates);
-  if (ranked.length === 0) return [];
+  if (ranked.length === 0) return { discovered: [], dropped: [] };
   const selected = new Set(await decide(purpose, ranked));
   const seen = new Set(exclude);
-  const out: DiscoveredBenchmark[] = [];
+  const discovered: DiscoveredBenchmark[] = [];
+  const dropped: DroppedBenchmark[] = [];
   for (const entry of ranked) {
     if (!selected.has(entry.id)) continue;
     const metric = catalogMetric(entry.id);
     if (seen.has(metric)) continue;
     seen.add(metric);
-    out.push({ metric, label: entry.name });
+    if (focusCoverageOk(metric, entry.modelCount, fieldSize) === "below-bar") {
+      dropped.push({
+        metric,
+        label: entry.name,
+        reason: `coverage ${entry.modelCount}/${fieldSize} is below the ${Math.round(FOCUS_COVERAGE_FLOOR * 100)}% bar`,
+      });
+      continue;
+    }
+    if (assess !== undefined) {
+      const reason = belowBarReason(await assess(metric));
+      if (reason !== null) {
+        dropped.push({ metric, label: entry.name, reason });
+        continue;
+      }
+    }
+    const declaration = catalogBenchmarkDeclaration(entry.id);
+    discovered.push({ metric, label: entry.name, covered: entry.modelCount, ...(declaration !== null ? { declaration } : {}) });
   }
-  return out;
+  return { discovered, dropped };
 }
 
 /**
@@ -372,8 +960,12 @@ export function formatBenchmarks(weights?: Record<string, number>, extra?: reado
 /** Shared empty match list for an explicitly chosen archetype (no keyword hits). */
 const EMPTY_MATCHED: string[] = [];
 
-/** Resolve the archetype, then layer the caller's explicit overrides on top. */
-function resolveRole(request: CreateAgentRequest): { archetype: Archetype; matched: string[]; def: RoleDef } | { errors: string[] } {
+/**
+ * Resolve the archetype, then layer the caller's explicit overrides on top.
+ * Exported so the extension can preview the request's weights (for the live
+ * "already in this role's weights" marker) without writing anything.
+ */
+export function resolveRole(request: CreateAgentRequest): { archetype: Archetype; matched: string[]; def: RoleDef } | { errors: string[] } {
   const match = request.archetypeId === undefined ? fitArchetype(stripBenchmarkLinks(request.purpose)) : { archetype: archetypeById(request.archetypeId), matched: EMPTY_MATCHED };
   if (match.archetype === null) {
     return { errors: [`unknown archetype "${request.archetypeId}" — one of ${ARCHETYPES.map((a) => a.id).join(", ")}`] };
@@ -385,12 +977,27 @@ function resolveRole(request: CreateAgentRequest): { archetype: Archetype; match
   const thinking = request.thinking ?? archetype.thinking;
   if (thinking !== undefined) def.thinking = thinking;
   if (request.image === true || (request.image === undefined && archetype.image === true)) def.filters = { image: true };
+  // The request's flags win; otherwise the archetype's own list (no shipped
+  // archetype sets one, so a plugin-created role starts from nothing unless the
+  // user asks). The flag is authored, not expanded — `resolveSettings` expands it.
+  let features: Record<string, boolean> | undefined = request.features;
+  if (features === undefined && archetype.features !== undefined && archetype.features.length > 0) {
+    features = {};
+    for (const id of archetype.features) features[id] = true;
+  }
+  if (features !== undefined) def.features = features;
   return { archetype, matched: match.matched, def };
 }
 
 /**
  * Create the role and the agent file for `request`. Nothing is written when any
  * check fails; `dryRun` runs every check and stops before the writes.
+ *
+ * The agent file is written **before** the role: an agent with no role is
+ * harmless (its `@<name>, @default` chain falls back to `@default`), while a
+ * role with no agent is a ranked-but-dead entry the updater would still wire. If
+ * the role write fails after the agent file landed, the agent file is removed
+ * (rollback), so a retry needs no `--force`.
  */
 export function createAgent(request: CreateAgentRequest): CreateAgentResult {
   const errors: string[] = [];
@@ -404,7 +1011,7 @@ export function createAgent(request: CreateAgentRequest): CreateAgentResult {
 
   const resolved = resolveRole(request);
   if ("errors" in resolved) return { ok: false, errors: [...errors, ...resolved.errors] };
-  const bench = applyFocusBenchmarks(resolved.def.weights, request.extraBenchmarks ?? []);
+  const bench = applyFocusBenchmarks(resolved.def.weights, request.extraBenchmarks ?? [], request.coverage);
   resolved.def.weights = bench.weights;
   errors.push(...checkWeightMath(name, resolved.def.weights, resolved.def.required));
 
@@ -413,8 +1020,8 @@ export function createAgent(request: CreateAgentRequest): CreateAgentResult {
   const agentsDir = request.scope === "project" ? projectAgentsDir(request.projectAnchor ?? process.cwd()) : userAgentsDir();
   const agentPath = join(agentsDir, `${name}.md`);
   const model = `@${name}, @default`;
-  // Pre-flight: the role write must not land when the agent file is going to be
-  // refused, or a failed run leaves a role with no agent behind it.
+  // Pre-flight: the agent file must not be written when the role is going to be
+  // refused, or a failed run leaves an agent behind for a role that never lands.
   if (existsSync(agentPath) && !request.force) errors.push(`${agentPath} already exists — pass --force to overwrite`);
   if (errors.length > 0) return { ok: false, errors };
 
@@ -425,23 +1032,68 @@ export function createAgent(request: CreateAgentRequest): CreateAgentResult {
     return { ok: true, name, archetype: resolved.archetype, matched: resolved.matched, def: resolved.def, agentPath, model, readOnly, backupPath: null, dryRun: true, bench };
   }
 
-  const written = writeRoleSettings(request.lockPath, { [name]: resolved.def });
-  if (!written.ok) return { ok: false, errors: written.errors };
-
   // omp's architect supplies the routing rule and the body; the plugin adds the
   // `model:`/`tools:` frontmatter omp's own writer omits. Without a spec (the
   // CLI, or a caller that skipped the architect) the archetype template is used.
   const description = request.spec?.whenToUse ?? routingDescription(request.purpose);
   const body = request.spec?.systemPrompt ?? buildBody(request, resolved.archetype, readOnly);
   const text = renderAgentFile({ name, description, model, tools, body });
+  // Capture the prior text (only reachable with `--force`) so a failed role write
+  // restores it instead of destroying the user's file and leaving the old role
+  // dangling.
+  const priorAgent = existsSync(agentPath) ? readFileSync(agentPath, "utf8") : null;
   const agent = writeAgentFile(agentPath, text, request.force);
-  if (!agent.ok) {
-    return { ok: false, errors: [`roles.${name} was written, but the agent file was not: ${agent.error}`] };
+  if (!agent.ok) return { ok: false, errors: [agent.error] };
+
+  // The real role write can return `{ ok: false }` (validation/lock/merge/mtime)
+  // or throw (a filesystem error in the atomic writer), so both paths roll the
+  // agent file back — a retry then needs no `--force`.
+  let written: RoleWriteResult;
+  try {
+    written = writeRoleSettings(request.lockPath, { [name]: resolved.def });
+  } catch (err) {
+    return { ok: false, errors: [rollbackAgent(agentPath, priorAgent, err instanceof Error ? err.message : String(err))] };
   }
+  if (!written.ok) return { ok: false, errors: [rollbackAgent(agentPath, priorAgent, written.errors.join("; "))] };
 
   return { ok: true, name, archetype: resolved.archetype, matched: resolved.matched, def: resolved.def, agentPath, model, readOnly, backupPath: written.backupPath, dryRun: false, bench };
 }
 
+/**
+ * Undo the agent write after a failed role write: restore the prior file when one
+ * existed (a `--force` re-create), else remove the new one. Blind removal under
+ * `--force` would destroy the user's agent and leave the old role dangling.
+ */
+function rollbackAgent(agentPath: string, priorAgent: string | null, roleError: string): string {
+  if (priorAgent === null) {
+    const removed = removeAgentFile(agentPath);
+    const note = removed.ok ? "the agent file was removed" : `removing the agent file failed: ${removed.error}`;
+    return `the agent file ${agentPath} was written, but the role was not: ${roleError} (${note})`;
+  }
+  const restored = writeAgentFile(agentPath, priorAgent, true);
+  const note = restored.ok ? "the prior agent file was restored" : `restoring the prior agent file failed: ${restored.error}`;
+  return `the agent file ${agentPath} was written, but the role was not: ${roleError} (${note})`;
+}
+
+/**
+ * A warning when the new role's top pick equals the `default` role's top pick —
+ * the role adds nothing over the default. `null` when they differ or the pool is
+ * empty (nothing to compare).
+ */
+export function differentiationWarning(
+  newDef: RoleDef,
+  defaultDef: RoleDef,
+  models: readonly Model[],
+): string | null {
+  if (models.length === 0) return null;
+  const pool = models as Model[];
+  const next = rankRole(newDef, pool);
+  const base = rankRole(defaultDef, pool);
+  if (next.length === 0 || base.length === 0) return null;
+  if (next[0].model.id !== base[0].model.id) return null;
+  return `the new role's leader (${next[0].model.id}) is also the default role's leader — the role adds nothing; raise its distinctive metric or drop it`;
+}
+
 /** The ok branch of a create run, for the report formatters. */
 export type CreatedAgent = Extract<CreateAgentResult, { ok: true }>;
 
@@ -468,8 +1120,11 @@ export const CREATE_AGENT_USAGE = [
   "  --thinking <level>     off|minimal|low|medium|high|xhigh|max|auto",
   "  --tools <a,b,...>      builtin tool allowlist (default: the archetype's)",
   "  --benchmarks <m,...>   extra benchmarks to fold into the weights (see --list-benchmarks)",
+  "  --feature <id,...>     capability flag(s) to author on the role (see --list-features);",
+  "                         repeatable, comma-separated, merged",
   "  --no-discover          skip benchmark discovery (rank only on named benchmarks)",
   "  --list-benchmarks      print the weightable benchmarks and exit",
+  "  --list-features        print the capability flags and the settings each applies, then exit",
   "  --scope <user|project> where the agent file goes (default: user)",
   "  --image                require image input (filters.image)",
   "  --body <text>          override the generated agent body",
@@ -533,13 +1188,13 @@ function parseList(spec: string): string[] {
 }
 
 export type ParsedCreateAgentArgs =
-  | { ok: true; request: CreateAgentRequest; json: boolean; bodyFile: string | undefined; listArchetypes: boolean; listBenchmarks: boolean; help: boolean; freeText: boolean; yes: boolean; noDiscover: boolean; explicitBenchmarks: boolean }
+  | { ok: true; request: CreateAgentRequest; json: boolean; bodyFile: string | undefined; listArchetypes: boolean; listBenchmarks: boolean; listFeatures: boolean; help: boolean; freeText: boolean; yes: boolean; noDiscover: boolean; explicitBenchmarks: boolean }
   | { ok: false; error: string };
 
 /** The flag half of the parse, without the required-name/purpose check (the
  * free-text form supplies those itself). */
 type ParsedFlags =
-  | { ok: true; request: CreateAgentRequest; json: boolean; bodyFile: string | undefined; listArchetypes: boolean; listBenchmarks: boolean; help: boolean; yes: boolean; noDiscover: boolean; explicitBenchmarks: boolean }
+  | { ok: true; request: CreateAgentRequest; json: boolean; bodyFile: string | undefined; listArchetypes: boolean; listBenchmarks: boolean; listFeatures: boolean; help: boolean; yes: boolean; noDiscover: boolean; explicitBenchmarks: boolean }
   | { ok: false; error: string };
 
 function parseFlags(argv: string[]): ParsedFlags {
@@ -555,6 +1210,7 @@ function parseFlags(argv: string[]): ParsedFlags {
   let bodyFile: string | undefined;
   let listArchetypes = false;
   let listBenchmarks = false;
+  let listFeatures = false;
   let help = false;
   let yes = false;
   let noDiscover = false;
@@ -574,6 +1230,10 @@ function parseFlags(argv: string[]): ParsedFlags {
       listBenchmarks = true;
       continue;
     }
+    if (flag === "--list-features") {
+      listFeatures = true;
+      continue;
+    }
     if (flag === "--force") {
       request.force = true;
       continue;
@@ -613,6 +1273,17 @@ function parseFlags(argv: string[]): ParsedFlags {
     else if (flag === "--benchmarks") {
       explicitBenchmarks = true;
       request.extraBenchmarks = parseList(value);
+    } else if (flag === "--feature") {
+      const ids = parseList(value);
+      if (ids.length === 0) return { ok: false, error: `--feature: no capability id given\n\n${CREATE_AGENT_USAGE}` };
+      const features = request.features ?? {};
+      for (const id of ids) {
+        if (featureById(id) === null) {
+          return { ok: false, error: `--feature: unknown capability "${id}" — one of ${FEATURES.map((f) => f.id).join(", ")}\n\n${CREATE_AGENT_USAGE}` };
+        }
+        features[id] = true;
+      }
+      request.features = features;
     } else if (flag === "--scope") {
       if (value !== "user" && value !== "project") return { ok: false, error: `--scope must be user or project, got "${value}"` };
       request.scope = value;
@@ -622,30 +1293,35 @@ function parseFlags(argv: string[]): ParsedFlags {
     else return { ok: false, error: `unknown flag "${flag}"\n\n${CREATE_AGENT_USAGE}` };
   }
 
-  return { ok: true, request, json, bodyFile, listArchetypes, listBenchmarks, help, yes, noDiscover, explicitBenchmarks };
+  return { ok: true, request, json, bodyFile, listArchetypes, listBenchmarks, listFeatures, help, yes, noDiscover, explicitBenchmarks };
 }
 
 /** Parse the flag form of `/create-agent` into a request. */
 export function parseCreateAgentArgs(argv: string[]): ParsedCreateAgentArgs {
   const parsed = parseFlags(argv);
   if (!parsed.ok) return parsed;
-  if (!parsed.help && !parsed.listArchetypes && !parsed.listBenchmarks) {
+  if (!parsed.help && !parsed.listArchetypes && !parsed.listBenchmarks && !parsed.listFeatures) {
     if (parsed.request.name === "") return { ok: false, error: `--name is required\n\n${CREATE_AGENT_USAGE}` };
     if (parsed.request.purpose === "") return { ok: false, error: `--purpose is required\n\n${CREATE_AGENT_USAGE}` };
   }
   return { ...parsed, freeText: false };
 }
 
+/** Metrics every archetype already weights, so naming one in prose adds nothing
+ * and must not be read as a benchmark. `reasoning` is deliberately absent: not
+ * every archetype weights it, so it stays extractable. */
+const ALWAYS_WEIGHTED_METRICS: Record<string, true> = { general: true, price: true, throughput: true };
+
 /**
  * Metric names a free-text request names explicitly. Whole-word, case-insensitive,
  * with `_`/`-`/space interchangeable inside a name (`long_context` ↔ "long context").
- * `price`/`throughput` are excluded: every archetype already weights them, so
- * naming them adds nothing.
+ * The always-weighted backbone (`general`/`price`/`throughput`) is excluded: every
+ * archetype already weights them, so ordinary prose naming one adds nothing.
  */
 export function extractBenchmarks(text: string): string[] {
   const found: string[] = [];
   for (const metric of Object.keys(KNOWN_METRICS)) {
-    if (metric === "price" || metric === "throughput") continue;
+    if (metric in ALWAYS_WEIGHTED_METRICS) continue;
     const pattern = metric.replace(/_/g, "[ _-]?");
     if (new RegExp(`\\b${pattern}\\b`, "i").test(text)) found.push(metric);
   }
@@ -689,7 +1365,7 @@ export function parseCreateAgentInput(raw: string): ParsedCreateAgentArgs {
   if (purpose === "") return { ok: false, error: `nothing to create\n\n${CREATE_AGENT_USAGE}` };
   const parsed = parseFlags(firstFlag === -1 ? [] : tokens.slice(firstFlag));
   if (!parsed.ok) return parsed;
-  if (parsed.help || parsed.listArchetypes || parsed.listBenchmarks) return { ...parsed, freeText: false };
+  if (parsed.help || parsed.listArchetypes || parsed.listBenchmarks || parsed.listFeatures) return { ...parsed, freeText: false };
 
   parsed.request.purpose = purpose;
   if (parsed.request.extraBenchmarks === undefined) {
@@ -710,10 +1386,48 @@ export function formatArchetypes(): string {
   }).join("\n\n");
 }
 
+/** One focus-metric line: coverage plus the eight new signals. */
+function assessmentLine(metric: string, a: FocusMetricAssessment): string {
+  const c = a.coverage;
+  const head =
+    c.status === "unknown"
+      ? `${metric} unknown (field size unavailable)`
+      : `${metric} ${c.covered}/${c.total} (${c.share === null ? "?" : `${(c.share * 100).toFixed(1)}%`}) ${c.status}`;
+  const dispersion = a.dispersion.status === "unknown" ? "unknown" : `${a.dispersion.value?.toFixed(3)} ${a.dispersion.status}`;
+  const composition =
+    a.composition.status === "unknown" ? "unknown" : a.composition.status === "ok" ? "ok" : `omits ${a.composition.omittedOrgs.join(", ")}`;
+  const freshness = a.freshness.status === "unknown" ? "unknown" : `${a.freshness.monthsBehind?.toFixed(1)}mo ${a.freshness.status}`;
+  const trust =
+    a.trust.status === "unknown"
+      ? a.trust.community
+        ? "community"
+        : "unknown"
+      : `${a.trust.selfReported}/${a.trust.covered} ${a.trust.status}${a.trust.community ? " community" : ""}`;
+  const modality =
+    a.modality.status === "unknown"
+      ? "unknown"
+      : `${a.modality.value ?? "?"}${a.modality.multimodalShare === null ? "" : ` ${(a.modality.multimodalShare * 100).toFixed(0)}% multimodal`}`;
+  const maintenance = a.maintenance.status === "unknown" ? "unknown" : `${a.maintenance.monthsOld?.toFixed(1)}mo ${a.maintenance.status}`;
+  const provenance =
+    a.provenance.status === "unknown"
+      ? "unknown"
+      : `${a.provenance.owner ?? "?"}${a.provenance.dominantShare === null ? "" : ` ${(a.provenance.dominantShare * 100).toFixed(0)}% ${a.provenance.dominantOrg ?? "?"}`} ${a.provenance.compositionAgreement}`;
+  const crossSource =
+    a.crossSource.status === "unknown"
+      ? "unknown"
+      : `${a.crossSource.compared} priceΔ${a.crossSource.priceDivergence === null ? "?" : `${(a.crossSource.priceDivergence * 100).toFixed(0)}%`} ctxΔ${a.crossSource.contextDivergence === null ? "?" : `${(a.crossSource.contextDivergence * 100).toFixed(0)}%`} ${a.crossSource.status}`;
+  return `${head}  dispersion ${dispersion}  composition ${composition}  freshness ${freshness}  trust ${trust}  modality ${modality}  maintenance ${maintenance}  provenance ${provenance}  cross-source ${crossSource}`;
+}
+
 /** The human-readable report for a completed (or dry-run) create. */
-export function formatCreateAgentReport(result: CreatedAgent, updaterHint: string): string {
+export function formatCreateAgentReport(
+  result: CreatedAgent,
+  updaterHint: string,
+  opts: { differentiation?: string | null } = {},
+): string {
   const weights = Object.entries(result.def.weights).map(([metric, weight]) => `${metric}=${weight}`).join(",");
   const fit = result.matched.length > 0 ? `matched ${result.matched.join(", ")}` : "fallback (no purpose keyword matched)";
+  const featureEntries = Object.entries(result.def.features ?? {});
   const lines = [
     `create-agent: ${result.dryRun ? "(dry run) " : ""}${result.name}`,
     `  archetype: ${result.archetype.id} (${result.archetype.label}) — ${fit}`,
@@ -722,9 +1436,55 @@ export function formatCreateAgentReport(result: CreatedAgent, updaterHint: strin
     `  agent:     ${result.agentPath}${result.readOnly ? "  (read-only)" : ""}`,
     `             model: ${result.model}`,
   ];
+  if (featureEntries.length > 0) lines.push(`  features:  ${featureEntries.map(([id, on]) => `${id}=${on}`).join(",")}`);
   if (result.bench.added.length > 0) lines.push(`  benchmarks: added ${result.bench.added.join(", ")}`);
   if (result.bench.duplicates.length > 0) lines.push(`  benchmarks: already weighted (skipped) ${result.bench.duplicates.join(", ")}`);
   if (result.bench.unknown.length > 0) lines.push(`  benchmarks: unknown (skipped) ${result.bench.unknown.join(", ")}`);
+  if (result.bench.dropped.length > 0) lines.push(`  benchmarks: dropped (focus cap ${FOCUS_METRIC_CAP}) ${result.bench.dropped.join(", ")}`);
+  for (const [metric, a] of Object.entries(result.bench.assessments)) lines.push(`  coverage:  ${assessmentLine(metric, a)}`);
+  for (const [metric, a] of Object.entries(result.bench.assessments)) {
+    if (a.coverage.status === "below-bar") {
+      lines.push(
+        `  warning:   ${metric} coverage ${a.coverage.covered}/${a.coverage.total} is below the ${Math.round(FOCUS_COVERAGE_FLOOR * 100)}% bar — the role may rank on coverage, not quality`,
+      );
+    }
+    if (a.dispersion.status === "below-bar") {
+      lines.push(`  warning:   ${metric} dispersion ${a.dispersion.value?.toFixed(3)} is below the ${FOCUS_DISPERSION_FLOOR} bar — the metric cannot separate models`);
+    }
+    if (a.composition.status === "below-bar") {
+      lines.push(`  warning:   ${metric} omits ${a.composition.omittedOrgs.join(", ")} — the source is provider-skewed`);
+    }
+    if (a.freshness.status === "below-bar") {
+      lines.push(`  warning:   ${metric} trails the pool by ${a.freshness.monthsBehind?.toFixed(1)} months — the source is stale`);
+    }
+    if (a.trust.status === "below-bar") {
+      lines.push(
+        `  warning:   ${metric} trust ${a.trust.selfReported}/${a.trust.covered} self-reported is above the ${FOCUS_SELF_REPORTED_MAX_SHARE} bar — the source is mostly vendor-submitted`,
+      );
+    }
+    if (a.maintenance.status === "below-bar") {
+      lines.push(
+        `  warning:   ${metric} dataset last updated ${a.maintenance.monthsOld?.toFixed(1)} months ago — the benchmark may be unmaintained`,
+      );
+    }
+    if (a.provenance.status === "below-bar") {
+      const share = a.provenance.dominantShare === null ? "?" : `${(a.provenance.dominantShare * 100).toFixed(0)}%`;
+      lines.push(
+        `  warning:   ${metric} provenance ${a.provenance.dominantOrg ?? "?"} dominates ${share} of the source's entries — the benchmark is vendor-populated`,
+      );
+    }
+    if (a.provenance.compositionAgreement === "disagree") {
+      lines.push(
+        `  warning:   ${metric} provenance disagrees with the composition axis — the source's own org mix and the pool-derived check do not concur`,
+      );
+    }
+    if (a.crossSource.status === "below-bar") {
+      lines.push(
+        `  warning:   ${metric} cross-source price/context diverges from the source's own per-entry values — the price basis may be stale or mis-joined`,
+      );
+    }
+  }
+  if (opts.differentiation) lines.push(`  warning:   ${opts.differentiation}`);
   if (result.backupPath !== null) lines.push(`  backup:    ${result.backupPath}`);
   if (result.dryRun) lines.push("  nothing written (--dry-run)");
   else lines.push(`  next:      ${updaterHint}`);