Role X

role-x — bstack P17 — Lens-Routed Request Articulation

Primitive: P17 in the Broomva Stack. See `broomva/workspace` AGENTS.md §P17 for the full reflexive trigger rule and the design spec at docs/superpowers/specs/2026-05-13-role-x-primitive-design.md.

What this skill provides

1. Lens registry: roles/_meta.md (always-loaded base) + roles/<name>.md per-domain lenses. Each lens has YAML frontmatter (signals, context_loaders, quality_bar, prompt_improvement_patterns, default_mode, mode_escalation, out_of_scope) and a prose body. 2. Selection algorithm (reasoning-enforced): score each lens against current signals (paths, prompt_keywords, branch_patterns, linear_labels); threshold ≥ 2 matches; resolve extends: chain. 3. Mode selection (reasoning-enforced): augment (silent context load — default), rewrite (surfaced prompt refinement), decompose (P5 parallel-agent plan, user-approved). Mode escalation per the lens's mode_escalation field. 4. CLI helpers (scripts/role-x.py):

• role-x list — list all available lenses with status + extends + default_mode
• role-x validate <path> — validate lens YAML frontmatter against schema
• role-x index — regenerate roles/_index.md discovery file
• role-x intake (v0.2.0) — UserPromptSubmit hook entry point
• role-x suggest (v0.4.0) — analyze events.jsonl; surface fire-rate + drift + emergent clusters
• role-x init <name> (v0.4.0) — scaffold a status: candidate lens from CLI flags
• role-x coverage (v0.4.1) — brief registry-health summary; silent when healthy (SessionStart hook entry point)

5. Hooks (scripts/*-hook.sh):

• role-x-intake-hook.sh (v0.2.0) — UserPromptSubmit wrapper
• role-x-coverage-hook.sh (v0.4.1) — SessionStart wrapper with 24h cooldown

6. Reference docs (references/):

• lens-schema.md — YAML frontmatter field reference
• selection-algorithm.md — scoring algorithm in detail
• mode-selection.md — augment/rewrite/decompose decision tree
• feedback-loop.md — Nous-pattern telemetry + P13 consolidation (M2+)

When to invoke

Intake reflex (every prompt)

Always — at the start of every session, before responding to substantive user input. P17 is a reflexive primitive. The skill exists to make the lens registry and CLI helpers discoverable; the behavior is enforced by reasoning + the UserPromptSubmit hook.

Carve-outs (no role-x intake needed): single-line typo fixes, pure read questions ("what does this function do?"), conversation continuation without new substantive request.

Meta-progression discipline (v0.4.1+)

The intake reflex routes prompts in real-time. The meta-progression discipline ensures the registry itself grows from real telemetry:

When NOT to invoke meta-actions

• Single-prompt sessions where the intake nudge is purely informational — don't pause work to author lenses mid-flow
• Edits to existing active lenses unless role-x tune <lens> (v0.5.0+) surfaces concrete drift signals
• New lenses without ≥3 distinct-session evidence in events.jsonl (avoids cargo-cult lens proliferation)

When NOT to invoke

• One-shot read questions answered from context alone
• Conversation-only exchanges (no work to execute)
• Brainstorming / design discussion (use superpowers:brainstorming instead; role-x kicks in once implementation begins)

Composition with other primitives

How to use

1. Start of session — agent reads roles/_meta.md + all roles/*.md (cached in working context). At UserPromptSubmit for substantive work, agent reasons through:

• Snapshot signals (P15): current branch, touched files (git diff --name-only), prompt content, Linear ticket if any
• Score each lens against signals (≥2 matches → applies)
• Resolve extends: chain; merge context_loaders + quality_bar
• Choose mode (augment / rewrite / decompose) per the lens's default_mode + mode_escalation rules
• Surface mode + selected lenses to user unless mode is augment
• Proceed with the user's request, applying the lens's quality_bar as the P14 dep-chain trace

2. Adding a new lens — author roles/<name>.md following the schema in references/lens-schema.md; run role-x validate roles/<name>.md; run role-x index to regenerate roles/_index.md; commit on a worktree branch; PR. 3. Lens consolidation (M4) — python3 scripts/role-x-replay.py <lens-name> runs the P13 dream cycle against ~/.config/broomva/role/events.jsonl.

Cardinal invariant

No `act as X` persona rewrites. Lenses load substantive context (files, conventions, checklists, optional suggestions). They do not insert persona declarations into the model's working context. The 2026 research (PRISM USC, Zheng et al. arXiv 2311.10054, Anthropic best-practices) is clear: persona declarations don't add expertise and frequently hurt accuracy for code/factual tasks (MMLU drops 71.6% → 66.3% with long expert personas).

Files

• roles/_meta.md — always-loaded base lens (the workspace's implicit "bstack-aware autonomous senior engineer" contract made addressable). Lives in the consuming workspace, not in this skill repo.
• roles/<name>.md — per-domain lenses. Live in the consuming workspace.
• roles/_index.md — auto-generated discovery index.
• scripts/role-x.py — CLI helpers.
• references/*.md — schema + algorithm reference docs.
• ~/.config/broomva/role/events.jsonl — telemetry log (M2).
• ~/.config/broomva/role/status.json — per-lens stats cache (M2).
• ~/.config/broomva/role/consolidation-runs/ — dream-cycle snapshots (M4).

Related

• Design spec: `broomva/workspace`/docs/superpowers/specs/2026-05-13-role-x-primitive-design.md
• Implementation plan: `broomva/workspace`/docs/superpowers/plans/2026-05-13-role-x-primitive-implementation.md
• Pattern entity: `broomva/workspace`/research/entities/pattern/role-x.md
• Reflexive trigger rule: `broomva/workspace`/AGENTS.md §P17
• bstack engine ledger: `broomva/workspace`/research/entities/pattern/bstack-engine.md (P17 in Promoted Patterns)
• Seed meta-role source: `broomva/autonomous` — /autonomous skill embeds the universal role contract

Changelog

All notable changes to role-x are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.5.0] — 2026-06-01

Adds task-relevant entity auto-loading to intake (BRO-1295). Until now the intake hook surfaced only persona constraints every prompt; task-specific entities loaded only when a domain lens scored ≥2. For off-lens prompts (most), no topic knowledge was auto-loaded — the agent was contextualized on who the user is, not on what we already know about the task at hand. This closes that gap, so every turn carries the most relevant entities from the knowledge graph.

Added

• Task-relevant entity scan in _format_intake_context. After lens

selection, intake reads the dense knowledge catalog (docs/knowledge-index.md, schema dense-catalog-v2), scores each entity's slug/tags/claim against the prompt tokens, and surfaces the top-5 under a new "Task-relevant knowledge (auto-loaded by relevance — read full bodies via `/kg load <slug>` …)" block. Self-contained: no cross-skill import of the kg loader, so the hook degrades gracefully when the catalog (or kg) is absent.

• Helpers _task_scan_tokens, _parse_catalog_entities, _score_catalog_entity,

_load_task_entities, _clean_claim_or_none; TASK_ENTITY_* constants.

• 4 tests covering surface-relevant, body-excerpt→path-only, curated-gate

rejection of body-only matches, and graceful no-catalog behavior.

Behavior / guards

• Curated-match gate: an entity surfaces only on a slug or tag token overlap,

never on body-text claim overlap alone — precision over a 300+ entity graph.

• Weighted scoring: slug (3) > tag (2) > claim (1); min total 3; top-5;

deduped against persona/lens entities; persona-type skipped (surfaced already).

• Body-excerpt suppression: entities with a weak/missing core_claim carry a

truncated body excerpt in the catalog; those render path-only instead of markdown noise (ellipsis + structural-marker heuristic).

• Robust catalog header parse — tolerates a trailing · score N/9 suffix that

previously made the parser drift and mis-attribute claims.

• Never blocks the turn: any absence/parse error → empty list, exit 0.

[0.4.2] — 2026-05-29

Activates the previously-inert context_loaders.entities wire. The field was validated (REQUIRED_CONTEXT_KEYS) and templated since v0.2.0, but the intake formatter only ever rendered context_loaders.files — so entities a lens declared never reached the agent's working context. This is the load half of the persona substrate (workspace spec docs/specs/2026-05-28-persona-substrate-architecture.html, Phase 2): persona constraint entities can now ride every turn, regardless of agent discipline.

Added

• `context_loaders.entities` now surfaced in intake output. For each

workspace-relative entity path a lens declares, intake resolves the file, parses its frontmatter core_claim, and emits a one-liner under a new block:

  Knowledge-graph constraints to honor (core_claim):
    - Default deploy target is Railway; suggest AWS only on explicit ask.  ·  [research/entities/persona/railway-deploy-default.md]

Hybrid load path (per spec §6): the compact core_claim index rides every turn; kg loads full entity bodies on demand for depth.

• **_confined_entity_path() + _entity_core_claim() + _safe_inline()

helpers** — resolve an entity path (confined to the workspace) and read its core_claim, collapsed to a single length-capped line. Hardened across three P20 cross-review rounds for the every-turn path: absolute paths are rejected (entity paths are workspace-relative by contract), and ../ / symlink escapes are skipped entirely (never read, never surfaced); oversized files are skipped; non-mapping frontmatter is rejected; the displayed provenance is run through _safe_inline() (strips control characters, newlines, and square brackets, collapses whitespace, caps length) so a crafted entry can't break the [...] wrapper or inject a standalone directive line; and any error degrades to the bare path — intake still exits 0 (the never-fail-the-turn invariant). Entity entries dedup on the cleaned path string, so an #anchor suffix no longer double-renders a claim. Requires the CI floor of Python 3.11+ (Path.is_relative_to).

Changed

• _format_intake_context(selection) → `_format_intake_context(selection,

workspace=None). Backward-compatible: when workspace` is omitted, entities render as bare paths; when no lens declares entities the block is absent and output is byte-identical to v0.4.1.

Tests

• Added happy-path, missing-file, and empty-entities tests, plus hardening

tests from two P20 cross-review rounds: non-mapping frontmatter, multiline-claim collapse, out-of-workspace path confinement (../ and absolute), and newline / bracket / control-char sanitization. Full suite: 47 passing.

[0.4.1] — 2026-05-14

Closes the meta-progression gap. The per-prompt routing was wired in v0.2.0; v0.4.0 shipped the observability substrate; v0.4.1 wires the agent-facing nudges so the expression of the system progresses naturally — without requiring the user to remember to run role-x suggest or notice when the registry undercovers their work.

Added

• In-prompt authoring nudge — when intake routes to _meta only AND

the prompt is "domain-rich" (≥8 words, ≥4 distinct meaningful tokens), the agent's working-context output appends one line:

  Note: no domain lens scored ≥2 for this prompt. If this kind of work
  recurs, consider expanding the registry: `role-x init <slug>` (status:
  candidate).

The slug is auto-derived from the first 2 distinctive tokens. Tuning knobs: DOMAIN_RICH_MIN_WORDS = 8, DOMAIN_RICH_MIN_TOKENS = 4.

• `role-x coverage` — brief registry-health summary suitable for a

SessionStart hook. Silent (exit 0, no output) when fire-rate ≥30% AND sanitized capture is enabled. Surfaces a 3-5 line nudge otherwise.

  role-x coverage [--since 7d --min-events N --force --events-path PATH]

• `scripts/role-x-coverage-hook.sh` — Claude Code SessionStart hook

wrapper. 24h cooldown via ~/.config/broomva/role/coverage-stamp (override via ROLE_X_COVERAGE_COOLDOWN_HOURS). Graceful-fail on missing Python / missing PyYAML / missing CLI. Always exits 0. Wired into workspace via .claude/settings.json SessionStart entry (separate PR on broomva/workspace).

• 8 new tests (30 → 38 total):
• intake_nudges_for_meta_only_domain_rich_prompt
• intake_no_nudge_when_lens_fires
• intake_no_nudge_for_short_prompt
• coverage_silent_when_healthy
• coverage_reports_when_no_sanitized_capture
• coverage_reports_low_fire_rate
• coverage_silent_below_min_events
• coverage_force_prints_when_below_min

Why this exists (the gap closed)

v0.4.0 made role-x suggest available, but nothing reminded agents to run it. The system captured 31 unrouted prompts over 7 days but no one noticed the pattern. v0.4.1 fixes that with two complementary nudges:

Both are non-blocking and exit silently when the registry is healthy. Like P8 skill-freshness, they nudge but never gate.

Backward compatibility

• All v0.1.0-v0.4.0 lenses work unchanged.
• Event schema unchanged — nudge is computed at runtime, not stored.
• CLI signatures preserved.
• The intake context output has a new optional appendix; agents that don't

consume it experience no change.

Workspace wiring (separate PR on broomva/workspace)

To enable the SessionStart hook, add to .claude/settings.json:

"SessionStart": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "$HOME/.agents/skills/role-x/scripts/role-x-coverage-hook.sh",
        "timeout": 5
      }
    ]
  }
]

If the role-x install doesn't have v0.4.1+ yet, the hook silently exits 0. No new failure mode introduced.

[0.4.0] — 2026-05-14

Observability for organic lens growth. Closes the half-loop from v0.3.0 — the substrate that lets the roles/ registry expand from real telemetry instead of speculative authoring. Two new subcommands + opt-in sanitized prompt capture + a privacy-by-default config layer.

Added

• `role-x suggest` — analyze events.jsonl over a window; report fire

rate, per-lens drift, and (when sanitized capture is enabled) emergent keyword clusters in _meta-only events with suggested lens names. Read-only — never mutates the registry. Hints at the config knob when cluster discovery is disabled.

  role-x suggest --since 7d [--threshold N] [--limit M] [--events-path PATH]

• `role-x init <name>` — scaffold a new status: candidate lens under

roles/<name>.md from CLI flags. Always emits candidates (rule-of-three not yet met); author promotes to status: active after ≥3 positive-outcome uses (P16). Scaffolded file passes validate immediately.

  role-x init <name>
    [--roles-dir DIR]
    [--keywords K1,K2,…]
    [--paths P1,P2,…]
    [--branch-patterns B1,B2,…]
    [--linear-labels L1,L2,…]
    [--threshold N]
    [--extends NAME]
    [--mode MODE]
    [--force]

• Opt-in sanitized prompt capture — when ~/.config/broomva/role/config.json

contains {"capture_sanitized_prompt": true}, the intake hook records a sanitized representation (default: top-N unique keywords) alongside the existing prompt_digest. Two strategies supported:

Config example:

  {
    "capture_sanitized_prompt": true,
    "sanitization_strategy": "keywords",
    "sanitization_top_n_keywords": 5
  }

Privacy invariant: absent config = no sanitized capture. Existing v0.1.0/v0.2.0/v0.3.0 installations with no config file behave identically to before — only prompt_digest (sha256) recorded.

• Event schema additions (backward-compatible): events now optionally

carry prompt_sanitized: {strategy, value}. Events lacking this field continue to validate against the existing schema. M5 dream-cycle consumers must handle both shapes.

• 10 new tests (20 → 30 total): suggest fire-rate summary, lens drift,

cluster discovery, config-hint path, empty log, init success, invalid name rejection, overwrite refusal, sanitized capture on, sanitized capture off.

Changed

• _emit_event accepts an optional config parameter (default: load from

CONFIG_PATH). Backward-compatible — existing callers unaffected.

• references/feedback-loop.md marked v0.4.0 substrate as shipped; M4

dream-cycle phase header retitled to v0.5.0+ (tune + propose-lens) and v0.6.0+ (role-x-replay.py).

Backward compatibility

• No schema breaking changes. Lenses authored under v0.1.0-v0.3.0 work

unchanged.

• Existing events.jsonl files are readable by role-x suggest without

modification (cluster discovery silently disabled until sanitized capture starts producing events).

• CLI surface preserved — all v0.1.0-v0.3.0 subcommands keep their signatures.
• No new required config files. Privacy-by-default; opt-in via config.

What this enables

# After 7+ days of telemetry with sanitized capture on:
$ role-x suggest --since 7d
[role-x suggest] window: --since 7d, events: 247
  fired ≥1 lens: 89 (36%)
  _meta only:    158 (64%)

Top 3 emergent keyword clusters in _meta-only events:
  1. [deploy, vercel, env] — 12 events, 6 sessions
     → role-x init deploy-vercel-env
  2. [spec, synthesis, research, entity] — 9 events, 7 sessions
     → role-x init spec-synthesis-research
  3. [tenant, exclusive-rentals, sentinel] — 5 events, 2 sessions
     → role-x init tenant-exclusive-rentals

Active lens drift summary:
  rust-systems: 41 fires, 18 sessions, avg prompt 14 words
  ts-nextjs:    27 fires, 12 sessions, avg prompt 11 words
  ...

Data-driven lens authoring — no more speculation about "what lenses might be useful".

Roadmap reshuffle

• v0.5.0 — role-x tune <lens> (propose keyword/threshold/weight diffs

from event log) + role-x propose-lens <cluster> (generate candidate lens from cluster). PRs only — never silent mutations.

• v0.6.0 (M5) — role-x-replay.py (full P13 dream cycle: gather → replay

→ prune → consolidate → index). Auto-promotion of candidates on positive outcomes.

• v0.7.0 — Stop + PostToolUse outcome hooks → quality signals per

lens-use (did the agent reference the loaded context? did the PR merge green? Nous score on resulting entity?).

• v0.8.0 — Lens decay + auto-demotion of unused lenses.

[0.3.0] — 2026-05-14

Trigger-strategy upgrade: lenses can now declare their own threshold and per-signal-type weights. Closes the "every lens shares the same global scoring rules" limitation in v0.1.0/v0.2.0.

Added

• Per-lens threshold override — optional top-level threshold: int in lens

frontmatter. Defaults to workspace global (DEFAULT_THRESHOLD = 2). Specialist lenses can set threshold: 3 to avoid false positives; broad lenses can set threshold: 1 to fire on a single strong signal.

• Per-signal-type weights — optional nested signals.weights: block. Each

signal type (paths, prompt_keywords, branch_patterns, linear_labels) can declare its own multiplier (default 1 each). Use cases:

• Weight branch patterns higher (e.g. branch_patterns: 3) when branch name

is a strong intent signal

• Set a signal type to 0 to disable it for a specific lens without removing

the declaration

• Amplify keyword matches (e.g. prompt_keywords: 2) for lenses where a

single keyword hit should suffice

• Validation extensions — role-x validate now rejects:
• threshold that is non-integer, boolean, or <1
• signals.weights entries with non-int or negative values
• signals.weights keys not in the recognised signal-type set
• 7 new tests — boundary cases for per-lens threshold (1 and 3), weighted

amplification, zero-weight signal disabling, and schema validation. Total: 20/20.

• Output: _score_lens breakdown now includes weights_applied so a future

role-x explain subcommand can surface why a lens fired (or didn't).

• Event log: per_lens_thresholds map added to internal selection dict for

future telemetry consumers. Wire-format events.jsonl schema is unchanged (raw counts in signals_matched, not weighted) — backward-compat preserved for M4 dream-cycle consumers.

Changed

• _score_lens total is now sum(raw_count × weight) per signal type instead

of sum(raw_count). Lenses without signals.weights are unaffected (all weights default to 1, identical to v0.2.0 behavior).

• _select_lenses uses _resolve_threshold(lens) per-lens instead of a single

global threshold. The threshold= argument remains the fallback default.

• Test count: 13 → 20 (Python 3.11 + 3.12 matrix).

Backward compatibility

• All v0.1.0/v0.2.0 lenses (no threshold, no signals.weights) keep their

exact prior behavior. Verified: workspace's roles/_meta.md + roles/rust-systems.md unchanged in scoring outcome.

• events.jsonl schema unchanged — recorded counts remain raw (unweighted).
• CLI surface unchanged — validate / list / index / intake subcommands

all preserve their v0.2.0 signatures.

Migration

No migration needed. Existing lenses keep working. To opt into the new strategies, add threshold: or signals.weights: to a lens's frontmatter and re-run role-x validate <lens> to confirm.

Example: a security-review lens with strict threshold

---
name: security-review
status: active
extends: _meta
threshold: 3                  # require ≥3 signals — avoid false positives
signals:
  paths:
    - "**/auth/**"
    - "**/credentials*"
  prompt_keywords:
    - "auth", "secret", "credential", "JWT", "OAuth"
  branch_patterns:
    - "feat/auth-*"
    - "feat/security-*"
  linear_labels:
    - "topic:security"
  weights:
    branch_patterns: 3          # branch is a strong signal — 1 hit = 3 score
    prompt_keywords: 1
    paths: 1
…
---

A prompt mentioning "auth" on feat/auth-something branch → 1 keyword (×1) + 1 branch (×3) = 4 ≥ threshold 3 → fires.

[0.2.0] — 2026-05-13

Hook integration (M2): role-x intake fires automatically on every substantive user prompt via a Claude Code UserPromptSubmit hook. Closes the reasoning-enforcement gap from v0.1.0 — now machine-checkable.

Added

• scripts/role-x-intake-hook.sh — Claude Code UserPromptSubmit hook

wrapper. Reads JSON payload from stdin, calls role-x.py intake, outputs context to stdout (added to the agent's working context). Graceful-fails (exit 0) if PyYAML missing, roles/ absent, or workspace not detected. Never blocks a user turn.

• role-x intake subcommand on scripts/role-x.py. Reads JSON event from

stdin or accepts --prompt/--workspace/--session flags for testing. Snapshots git signals (branch, touched files), tokenizes prompt keywords, scores all roles/*.md lenses, walks extends: chain, decides mode (augment / rewrite / decompose), emits structured event to ~/.config/broomva/role/events.jsonl, prints intake context to stdout.

• 7 new tests covering carve-outs (short prompts, missing roles/),

keyword matching, event persistence, multi-domain decompose escalation, _meta-only fallback, stdin JSON protocol.

Changed

• Test count: 6 → 13 (all green on Python 3.11 + 3.12 CI).
• references/feedback-loop.md is now wired up: hook + intake subcommand

produce events the M4 dream cycle will replay.

Workspace wiring (separate PR in broomva/workspace)

This release ships the hook script. The workspace's .claude/settings.json must register the hook to fire automatically:

"UserPromptSubmit": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "$HOME/.agents/skills/role-x/scripts/role-x-intake-hook.sh",
        "timeout": 5
      }
    ]
  }
]

The hook is reasoning-supplementing, not blocking — exit 0 always.

Manual invocation (test or fallback)

# Direct CLI test
python3 ~/.agents/skills/role-x/scripts/role-x.py intake \
  --prompt "your prompt here" \
  --workspace "$PWD" \
  --session "manual"

# Via the hook script (simulating Claude Code stdin)
echo '{"prompt": "your prompt", "session_id": "manual"}' \
  | ~/.agents/skills/role-x/scripts/role-x-intake-hook.sh

[0.1.0] — 2026-05-13

Initial release. Ships the Markdown lens registry + Python CLI for the bstack P17 primitive (Lens-Routed Request Articulation).

Added

• SKILL.md — skill front-door with frontmatter for skills.sh discovery
• scripts/role-x.py — CLI with validate, list, index subcommands
• references/lens-schema.md — YAML frontmatter field reference
• references/selection-algorithm.md — scoring algorithm (paths + prompt_keywords + branch_patterns + linear_labels, threshold ≥2)
• references/mode-selection.md — augment/rewrite/decompose decision tree
• references/feedback-loop.md — Nous-pattern telemetry design (implementation deferred to v0.2.0+)
• tests/test_role_x.py — pytest battery covering validate (3 tests) + list + index subcommands
• tests/fixtures/ — valid + invalid lens fixtures for testing
• .github/workflows/test.yml — CI: pytest on push/PR
• README.md, LICENSE (MIT), CHANGELOG.md, .gitignore

Deferred (roadmap)

• v0.2.0 (M2) — Hook integration (UserPromptSubmit / PostToolUse / Stop) + events.jsonl capture + status.json cache
• v0.3.0 (M3) — Seed lens corpus expansion (ts-nextjs, api-design, security-review, infra-deploy, docs-research)
• v0.4.0 (M4) — P13 dream cycle: role-x-replay.py with replay-against-frozen-substrate
• v0.5.0 (M5) — persona-* skill referenceability + thin lens wrappers

Design provenance

Reframed by 2026 research that empirically debunks naive "act as X" persona prompting for code/factual tasks:

• Hu, Rostami, Thomason — PRISM (USC, arXiv 2603.18507): MMLU drop 71.6% → 66.3% with long expert personas
• Zheng et al. (arXiv 2311.10054) — 162-persona × 4-LLM study: "no or small negative effects"
• Anthropic best-practices — lists heavy role prompting as outdated

The substance is in what the agent loads next — concrete files, conventions, prior decisions, domain-specific checklists — not in how the agent introduces itself. v0.1.0 ships that substance.

role-x — bstack P17: Lens-Routed Request Articulation

The typed routing layer above P5 parallel-agent dispatch. On every substantive user input, the first-touch agent reflexively selects a domain lens, loads its substantive context, and decides single-agent vs surfaced rewrite vs parallel-team plan. No "act as X" persona theater — substantive context grounding only.

  

Why role-x exists

Modern frontier-model evidence (PRISM USC 2026, Zheng et al. arXiv 2311.10054, Anthropic best-practices) shows that naive "act as expert X" persona prompting hurts code/factual accuracy — MMLU drops 71.6% → 66.3% with long expert personas; "no or small negative effects" across 162 personas × 4 LLMs × 2410 questions. Telling a model it's an expert does not impart expertise.

What does work is substantive context grounding: concrete files, conventions, prior decisions, domain-specific checklists. role-x makes that grounding addressable, composable, and self-improving via a Markdown lens registry the agent reasons over before responding.

What role-x is

A bstack P17 skill providing:

1. Lens registry — roles/_meta.md (always-loaded base) + roles/<name>.md per-domain lenses. Each lens has YAML frontmatter (signals, context_loaders, quality_bar, prompt_improvement_patterns, mode_escalation, out_of_scope) and a prose body. 2. Three modes per request — augment (silent context load, default) / rewrite (surfaced prompt refinement, user accepts) / decompose (parallel-agent plan via P5, user-approved). 3. CLI helpers (this repo's scripts/role-x.py):

• role-x list — list all lenses in roles/
• role-x validate <path> — validate lens YAML frontmatter against schema
• role-x index — regenerate roles/_index.md discovery file

4. Reference docs — schema, selection algorithm, mode-decision tree, feedback loop (M2+).

Quick start

# 1. Install via skills.sh
npx skills add broomva/role-x

# 2. Create a lens registry in your workspace
mkdir -p roles
# Author roles/_meta.md (always-loaded base) and per-domain lenses

# 3. Validate a lens against the schema
python3 ~/.agents/skills/role-x/scripts/role-x.py validate roles/_meta.md
# → OK: roles/_meta.md is a valid lens

# 4. List all lenses
python3 ~/.agents/skills/role-x/scripts/role-x.py list --roles-dir roles

# 5. Regenerate the discovery index
python3 ~/.agents/skills/role-x/scripts/role-x.py index --roles-dir roles
# → wrote roles/_index.md (N lenses)

How the agent uses role-x

At UserPromptSubmit for substantive work, the agent reasons through:

1. Snapshot signals (P15)
   - current branch (git rev-parse --abbrev-ref HEAD)
   - touched files (git diff --name-only)
   - prompt keywords
   - Linear ticket labels

2. Score lens registry
   For each roles/<name>.md:
     score = matches in {paths, prompt_keywords, branch_patterns, linear_labels}
   Threshold: score ≥ 2

3. Resolve extends: chain
   Walk back to _meta; merge context_loaders + quality_bar + prompt_improvement_patterns

4. Decide mode
   augment | rewrite | decompose
   per lens default_mode + mode_escalation

5. Surface to user (unless augment)
   "Applying lens(es) X, Y because [signals]. Suggestions: …. Proceeding."

6. Emit event to ~/.config/broomva/role/events.jsonl  (M2 — hook-driven)

Selection and mode-decision are reasoning-enforced (bstack-idiom, same as P10/P14/P15/P16). The CLI validates lens schemas and generates the discovery index; it does not run selection at runtime.

Subcommands

Hook integration (v0.2.0+)

The intake subcommand can fire automatically on every substantive user prompt via a Claude Code UserPromptSubmit hook. Add to your workspace's .claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.agents/skills/role-x/scripts/role-x-intake-hook.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

The hook:

• Reads the prompt JSON payload from stdin
• Resolves workspace via $CLAUDE_PROJECT_DIR (or $PWD)
• Scores roles/*.md against signals (git branch, touched files, prompt keywords)
• Selects lens(es) with score ≥2, walks extends: chain to _meta
• Decides mode (augment / rewrite / decompose)
• Appends a structured event to ~/.config/broomva/role/events.jsonl
• Prints the lens metadata + composed quality_bar + suggestions to stdout (added to the agent's working context)

Always exits 0. Graceful-fails if PyYAML is missing, the workspace has no roles/ directory, or the prompt is shorter than 3 words (carve-out for trivial prompts).

Test the hook locally

echo '{"prompt": "implement rust cargo tokio async support", "session_id": "manual"}' \
  | CLAUDE_PROJECT_DIR=$PWD ~/.agents/skills/role-x/scripts/role-x-intake-hook.sh

Expected output: lens selected, mode decided, quality_bar surfaced, any context_loaders.entities core_claim constraints surfaced, event appended to events.jsonl.

Event schema

{
  "ts": "<ISO-8601 UTC>",
  "event": "intake",
  "session": "<session id>",
  "prompt_digest": "sha256:<hex>",
  "prompt_word_count": 42,
  "lenses_selected": ["rust-systems"],
  "lenses_extended": ["rust-systems", "_meta"],
  "mode": "augment",
  "mode_escalation_reason": null,
  "signals_matched": {"paths": 0, "prompt_keywords": 4, "branch_patterns": 0, "linear_labels": 0}
}

See `references/feedback-loop.md` for the full design (M4 dream cycle consumes this telemetry).

Lens schema (minimal example)

---
name: rust-systems
status: active
extends: _meta
signals:
  paths: ["**/Cargo.toml", "**/*.rs"]
  prompt_keywords: ["rust", "cargo", "tokio", "MSRV"]
  branch_patterns: ["feat/rust-*"]
  linear_labels: ["lang:rust"]
context_loaders:
  files: ["AGENTS.md#Conventions", "core/life/CLAUDE.md"]
  entities: ["research/entities/concept/stability-budget.md"]
  skills: ["rust-best-practices"]
  glob_hints: ["core/life/rust-toolchain.toml"]
default_mode: augment
quality_bar:
  - "MSRV declared in Cargo.toml is honored (workspace default: 1.85)"
  - "Edition 2024 idioms used"
  - "No unwrap() in non-test code unless documented"
prompt_improvement_patterns:
  - signal: "no MSRV mentioned"
    suggestion: "Specify target MSRV"
mode_escalation:
  rewrite_when: ["prompt asks for new API without naming trait shape"]
  decompose_when: ["prompt spans ≥2 crates with no shared types"]
out_of_scope: ["Non-Rust files"]
related_lenses: ["api-design", "security-review"]
created: 2026-05-13
updated: 2026-05-13
---
# rust-systems lens
[Body: prose detail, anti-patterns, composition triggers]

Full schema reference: `references/lens-schema.md`.

Cardinal invariant

No `act as X` persona rewrites. Lenses load substantive context (files, conventions, checklists, optional suggestions). They do not insert persona declarations into the model's working context. The 2026 research is clear: persona declarations don't add expertise and frequently hurt accuracy.

Where role-x fits in the bstack

User intent → P17 role-x intake → P15 state snapshot → Linear (P3) → Agent (P5)
                ↓ typed edges (lens per fan-out)
              P5 parallel dispatch becomes a typed graph
                ↓ lens.quality_bar IS the P14 dep-chain template
              P14 enumeration is domain-specific
                ↓ events.jsonl (M2)
              P13 dream cycle consolidates lens rules (M4)
                ↓ per-lens rule-of-three
              P16 promotes candidate lenses to status: active

role-x composes with — does not duplicate — existing primitives. See `broomva/workspace` AGENTS.md §P17 for the full reflexive trigger rule.

Tests

python3 -m venv .venv && source .venv/bin/activate
pip install -r tests/requirements-dev.txt
python3 -m pytest tests/ -v

Spec & design

Full design lives at `broomva/workspace` under docs/superpowers/specs/2026-05-13-role-x-primitive-design.md (570 lines) and the implementation plan at docs/superpowers/plans/2026-05-13-role-x-primitive-implementation.md (2068 lines).

Observability + lens authoring (v0.4.0+)

The system is designed to grow organically — the roles/ registry expands from real telemetry, not speculative authoring. The pipeline:

1. Capture (v0.2.0+) — intake hook logs every prompt routing decision to ~/.config/broomva/role/events.jsonl 2. Sanitize (v0.4.0, opt-in) — optionally extract top-N keywords or first-N chars from prompts for downstream clustering 3. Analyze (v0.4.0) — role-x suggest reports fire-rate, per-lens drift, and emergent keyword clusters 4. Scaffold (v0.4.0) — role-x init <name> generates a candidate lens from CLI flags 5. Promote (P16) — after ≥3 positive-outcome uses, author updates status: candidate → active 6. Tune (v0.5.0, planned) — role-x tune <lens> proposes keyword/threshold/weight diffs as a PR 7. Replay (v0.6.0, planned) — full P13 dream cycle: role-x-replay.py consolidates lens rule updates from outcome data

Privacy by default: sanitized prompt capture is off unless you write ~/.config/broomva/role/config.json with {"capture_sanitized_prompt": true}. Without that file, only prompt_digest (sha256) is recorded — same as v0.1.0-v0.3.0.

Example workflow (after a week of telemetry):

# 1. Turn on sanitized capture
cat > ~/.config/broomva/role/config.json <<EOF
{"capture_sanitized_prompt": true, "sanitization_strategy": "keywords", "sanitization_top_n_keywords": 5}
EOF

# 2. Let the hook accumulate events for a few days

# 3. See what lenses to author
role-x suggest --since 7d

# 4. Scaffold the top suggestion
role-x init deploy-vercel-env --keywords "deploy,vercel,env,preview" --paths "**/vercel.json"

# 5. Edit the TODO sections, validate, commit
role-x validate roles/deploy-vercel-env.md
role-x index --roles-dir roles
git add roles/ && git commit -m "feat(roles): add deploy-vercel-env candidate lens"

Roadmap

• v0.1.0 — Markdown lens registry + CLI (validate, list, index) + reference docs
• v0.2.0 — intake subcommand + UserPromptSubmit hook + ~/.config/broomva/role/events.jsonl capture
• v0.3.0 — Per-lens threshold: override + per-signal-type signals.weights:
• v0.4.0 — Observability for organic growth: role-x suggest + role-x init + opt-in sanitized prompt capture
• v0.4.1 (this release) — Meta-progression nudges: role-x coverage SessionStart hook + per-prompt authoring suggestion when intake routes to _meta only on a domain-rich prompt
• v0.5.0 — role-x tune <lens> + role-x propose-lens <cluster> (PR-driven lens updates)
• v0.6.0 — P13 dream cycle: role-x-replay.py with replay-against-frozen-substrate; status.json per-lens stats cache; auto-promote candidates on rule-of-three positive outcomes
• v0.7.0 — PostToolUse + Stop outcome hooks → quality signals per lens-use
• v0.8.0 — Lens decay + auto-demotion of unused lenses

License

MIT — see LICENSE.

Related

• broomva/workspace — unified workspace + governance (P17 §AGENTS.md, roles/ registry)
• broomva/bstack — bstack catalog skill (counts P1-P17)
• broomva/p9 — bstack P7 (CI watcher + productive wait)
• broomva/persist — bstack P12 (cross-context restart loop)
• broomva/bookkeeping — bstack P6 (knowledge graph engine)

Feedback Loop — design + shipped status

Lens-use telemetry feeds back into lens-rule improvements via the P13 dream cycle. v0.2.0 shipped the capture layer; v0.4.0 shipped the observability + scaffolding layer. v0.5.0+ adds tuning/proposal automation; v0.6.0 (M5) ships the full dream cycle.

See [`observability.md`](observability.md) for the v0.4.0 substrate (event schema, role-x suggest, role-x init, sanitized capture).

Three hook integration points (M2)

Events append one-per-line (flock-protected). Schema is intentionally narrow — no model output content, no PII, just routing decisions and their downstream signals.

Dream-cycle consolidation (M4)

python3 scripts/role-x-replay.py <lens-name> runs the P13 5-phase dream cycle applied to lens rules:

Critical: replay does NOT touch the live lens; it computes counterfactuals against the frozen snapshot. This is the stop-gradient property that distinguishes dream cycles from shadow dreams.

Cadence

• Per-50-uses-per-lens (statistically sufficient for rule-change signal)
• OR weekly (whichever fires first)
• Manual invocation always available

Shipped scope

• v0.2.0 — UserPromptSubmit hook + role-x intake subcommand + events.jsonl capture ✓
• v0.4.0 — role-x suggest + role-x init + opt-in sanitized prompt capture + privacy-by-default config ✓

Pipeline status

Lens Schema Reference

Each lens lives at roles/<name>.md and consists of YAML frontmatter (machine-readable) + Markdown body (prose detail).

Required frontmatter fields

Optional fields (v0.3.0+)

Setting a weight to 0 disables that signal type for the lens without removing the declaration. All weight values must be non-negative integers.

Example — strict specialist lens with branch-amplified scoring

---
name: security-review
status: active
extends: _meta
threshold: 3
signals:
  paths: ["**/auth/**", "**/credentials*"]
  prompt_keywords: ["auth", "secret", "credential", "JWT", "OAuth"]
  branch_patterns: ["feat/auth-*", "feat/security-*"]
  linear_labels: ["topic:security"]
  weights:
    branch_patterns: 3
    prompt_keywords: 1
    paths: 1
context_loaders:
  files: ["docs/security/checklist.md"]
  …
---

Resolution at intake:

• Prompt = "rotate the JWT signing key" on branch feat/auth-rotate
• Raw counts: prompt_keywords=1 ("JWT"), branch_patterns=1 (matches feat/auth-*), paths=0
• Weighted total: 1×1 + 1×3 + 0×1 = 4
• Threshold: 3 → lens fires ✓

When to use which strategy

Body content

The Markdown body is for the agent's reasoning context when the lens fires. Typical sections:

• Workspace conventions specific to this domain
• Common anti-patterns the lens flags
• Composition triggers — when this lens commonly composes with others
• Reference docs — links to authoritative sources

The body is human-readable but agent-consumed — assume an agent will be reading it before responding to a user prompt in this domain.

Validation

Run python3 scripts/role-x.py validate roles/<name>.md to check frontmatter against schema. CI gate (M2+) enforces validation in pre-commit.

Example: minimal valid lens

---
name: example
status: active
extends: _meta
signals:
  paths: ["**/*.example"]
  prompt_keywords: ["example"]
  branch_patterns: []
  linear_labels: []
context_loaders:
  files: []
  entities: []
  skills: []
  glob_hints: []
default_mode: augment
quality_bar: []
prompt_improvement_patterns: []
mode_escalation:
  rewrite_when: []
  decompose_when: []
out_of_scope: []
related_lenses: []
created: 2026-05-13
updated: 2026-05-13
---

# example lens

Mode Selection

After lens(es) are selected, the agent decides the operating mode.

The three modes

augment (default)

Lens context is loaded silently. User prompt passes verbatim to the working agent. Quality-bar checklist is the P14 dep-chain template for the response.

Chosen when:

• Prompt is clear and single-domain
• No obvious missing constraints
• Work fits in a single agent's scope

User-facing surface: minimal — agent proceeds with the request. Quality-bar checklist appears as the agent's dep-chain enumeration in the response per P14.

rewrite (surfaced)

Agent produces a refined version of the user prompt with explicit constraints (the lens's prompt_improvement_patterns applied). Surfaces both original and rewritten to the user. Proceeds with whichever the user accepts (default: rewritten).

Chosen when:

• Prompt is ambiguous about scope, target, or constraint
• The lens's mode_escalation.rewrite_when triggers fire
• The request implicitly assumes context the user didn't state

User-facing surface:

I'm applying lens(es): rust-systems (signals: 3 path matches, 2 keyword matches)

Your prompt was ambiguous about MSRV — the rust-systems quality_bar
requires it. Suggested rewrite:

  Original: "Add async support to the auth module"

  Rewritten: "Add tokio-based async support to the auth module in
  core/life/crates/anima, honoring workspace MSRV 1.85, with Send-bound
  futures, thiserror-based error type, and a conformance test."

Proceed with rewritten, original, or edit?

decompose (surfaced)

Agent produces a parallel-agent plan: N sub-tasks, each with its own lens, scoped boundaries, and merge instructions. User approves the plan; P5 dispatches the parallel agents. Each sub-agent runs role-x recursively at its scope.

Chosen when:

• Prompt spans ≥2 independent domains
• Independent sub-tasks emit no cross-references
• The lens's mode_escalation.decompose_when triggers fire

User-facing surface:

I'm applying lens(es): rust-systems + ts-nextjs + infra-deploy

Your prompt spans 3 independent domains. Proposed parallel plan:

  Sub-agent 1 (lens: rust-systems): refactor auth handler in core/life/crates/anima
    Worktree: .worktrees/auth-rust
    Owns: core/life/crates/anima/**

  Sub-agent 2 (lens: ts-nextjs): update chatOS auth UI in apps/chatOS
    Worktree: .worktrees/auth-ts
    Owns: apps/chatOS/app/**

  Sub-agent 3 (lens: infra-deploy): update Vercel env vars
    Worktree: .worktrees/auth-deploy
    Owns: apps/chatOS/vercel.json + ops/vercel-config/**

Merge order: 1 → 2 → 3 (TS depends on Rust API; deploy depends on TS build).

Approve? (yes / edit / cancel)

Mode escalation rules

• augment can escalate to rewrite or decompose
• rewrite can escalate to decompose
• Never escalate in reverse within a single intake pass — prevents thrashing
• Sub-agents start fresh with augment default at their scope

When a lens has default_mode: rewrite or default_mode: decompose

Lens authors can override the workspace default of augment per lens. Example: a hypothetical migration lens might default to decompose because migration work naturally fans out.

Escalation rules still apply — a lens with default_mode: rewrite can still escalate to decompose per mode_escalation.decompose_when.

Observability — data substrate for organic lens growth

v0.4.0+ ships the telemetry primitives that let the roles/ registry grow from real data instead of speculative authoring. This file documents the data flow, schema, and the v0.5.0+ pipeline this substrate enables.

Pipeline overview

UserPromptSubmit
      ↓ (role-x intake — v0.2.0)
events.jsonl  ← prompt_digest + signals_matched + lenses_selected + mode
      ↓ (role-x suggest — v0.4.0)
analysis report  ← fire-rate + per-lens drift + emergent keyword clusters
      ↓ (role-x init — v0.4.0)
roles/<name>.md (status: candidate)
      ↓ (rule-of-three positive outcomes — P16)
roles/<name>.md (status: active)
      ↓ (role-x tune — v0.5.0, planned)
PR diff with proposed keyword/threshold/weight updates
      ↓ (role-x-replay.py — v0.6.0, M5, planned)
auto-promote / auto-demote based on counterfactual replay against frozen snapshots

Each transition is human-reviewable (the lens file diff is the artifact). The system makes proposals; humans accept/reject via PR.

Event schema (current, backward-compat preserved)

Every intake appends one line to ~/.config/broomva/role/events.jsonl:

{
  "ts": "2026-05-14T12:30:35.150348+00:00",
  "event": "intake",
  "session": "<claude-session-id>",
  "prompt_digest": "sha256:<64-hex-chars>",
  "prompt_word_count": 12,
  "lenses_selected": ["rust-systems"],
  "lenses_extended": ["rust-systems", "_meta"],
  "mode": "augment",
  "mode_escalation_reason": null,
  "signals_matched": {
    "paths": 0,
    "prompt_keywords": 4,
    "branch_patterns": 0,
    "linear_labels": 0
  },
  "prompt_sanitized": {                    // ← v0.4.0 optional
    "strategy": "keywords",
    "value": ["rust", "cargo", "tokio", "async"]
  }
}

Fields:

Sanitized prompt capture (v0.4.0, opt-in)

Privacy invariant

Absent config = no sanitized capture. Existing installations from

v0.1.0/v0.2.0/v0.3.0 with no config file behave identically to before —

only prompt_digest (sha256) is recorded. Any sanitization is **opt-in

per workstation** via ~/.config/broomva/role/config.json.

Config file

~/.config/broomva/role/config.json:

{
  "capture_sanitized_prompt": true,
  "sanitization_strategy": "keywords",
  "sanitization_top_n_keywords": 5,
  "sanitization_first_chars": 80
}

Defaults (when keys missing): capture_sanitized_prompt: false, sanitization_strategy: "keywords", sanitization_top_n_keywords: 5. Unknown values fall back to defaults silently.

Strategy: keywords (recommended)

Extracts the top-N unique alphanumeric tokens (length > 2) from the prompt, in order of first appearance, lowercased. Excludes 1- and 2-character words.

Input: "Implement rust cargo tokio runtime support with proper error handling" Output: ["implement", "rust", "cargo", "tokio", "runtime"] (N=5)

• Pros: useful for cluster discovery; resilient to typos in long prompts (frequency washes out noise); easy to scan visually
• Cons: loses structure (sentence boundaries, modifiers); won't catch multi-word concepts like "next.js"

Strategy: first_chars

Captures the first N characters of the raw prompt.

Input: "Implement rust cargo tokio runtime" (configured n=20) Output: "Implement rust cargo"

• Pros: higher fidelity for debugging; preserves phrasing
• Cons: more PII-sensitive; sensitive to prompt-opening boilerplate; less useful for clustering

role-x suggest analysis

Three sections in every suggest report:

1. Window summary

[role-x suggest] window: --since 7d, events: 247
  fired ≥1 lens: 89 (36%)
  _meta only:    158 (64%)

Coverage ratio (lens-fired %) is the primary health metric. If it's < 30%, the registry doesn't cover what users are actually working on — author more lenses. If it's > 90%, lenses may be over-firing (false positives) — raise thresholds.

2. Emergent keyword clusters (requires sanitized capture)

Greedy clustering: take the top-frequency keyword among _meta-only events, find its co-occurring keywords, group events that share ≥2 of them. Cluster size threshold via --threshold N (default 2).

If sanitized capture is off, this section is replaced with a config-enablement hint.

3. Per-active-lens drift summary

For each lens that fired in the window: fire count, distinct session count, average prompt word count. v0.5.0 will extend this with keyword drift (top co-occurring keywords NOT in the lens's prompt_keywords list) and threshold drift (% events that fired vs missed by 1-2 signals).

Privacy guarantees

The sha256 digest is irreversible. Even with sanitized capture on, only the top-N keywords (lowercase, deduped) appear in events — not the original prompt text or its structure.

Operational notes

• Log rotation: events.jsonl grows ~1 line per substantive prompt. At ~50-200 prompts/day, expect ~1-5MB per quarter. No auto-rotation today; if it becomes a concern, archive with mv events.jsonl events.jsonl.YYYY-MM-DD && touch events.jsonl.
• Concurrent writes: the intake hook writes in append-only mode with one line per event. Brief contention between concurrent sessions is benign — line boundaries are preserved.
• Schema migrations: any future schema change must be backward-additive (new optional fields only). role-x suggest is designed to tolerate older event lines missing newer fields.

Future (v0.5.0+)

• role-x tune <lens> — analyze the event log for an active lens; propose YAML diffs to its prompt_keywords, paths, threshold, signals.weights. Output is a PR-ready diff; never auto-applies.
• role-x propose-lens <cluster-name> — take a cluster from suggest output; generate a fully-scaffolded candidate lens with signals pre-populated from cluster keywords.
• PostToolUse outcome hook — record whether the agent actually referenced the lens's context_loaders.files during the session. This bridges "lens fired" to "lens fired AND was useful".
• Stop outcome hook — record session-end outcomes: did the PR merge green? Did Nous score the resulting entity ≥5? These are the quality signals that drive auto-promotion in v0.6.0.
• role-x-replay.py (M5 / v0.6.0) — full P13 dream cycle: gather events → replay against frozen lens snapshots → prune events with no behavior change → consolidate as YAML PR → re-index registry. Auto-promote candidates after rule-of-three positive outcomes; auto-demote unused lenses after 90 days.

See also

• `feedback-loop.md` — the M5 dream-cycle architecture this telemetry feeds
• `selection-algorithm.md` — how raw counts in signals_matched get computed
• `lens-schema.md` — the lens fields that role-x init scaffolds and role-x tune will modify

Selection Algorithm

When the first-touch agent receives a substantive user input, it executes:

Step 1: Snapshot signals

• current_branch — git rev-parse --abbrev-ref HEAD
• touched_files — git diff --name-only HEAD~1 HEAD + git diff --name-only (uncommitted)
• prompt_tokens — case-insensitive tokenization of user prompt
• linear_labels — from active Linear ticket if discoverable from branch name

Step 2: Load lens registry

• Read roles/_meta.md (always)
• Read all roles/*.md where status: active
• Cache at session start; reload only on session restart

Step 3: Score each lens

For each lens L (v0.3.0+):

raw_counts = {
  paths:           count(glob in L.signals.paths        : any fnmatch(f, glob) for f in touched_files),
  prompt_keywords: count(kw   in L.signals.prompt_keywords : kw.lower() in prompt_tokens),
  branch_patterns: count(pat  in L.signals.branch_patterns : fnmatch(current_branch, pat)),
  linear_labels:   count(lbl  in L.signals.linear_labels   : lbl in linear_labels),
}

# v0.3.0 — per-signal-type weights. Each lens may declare
# signals.weights.<type>: <int>. Missing entries default to 1.
weights = L.signals.weights ∪ {paths: 1, prompt_keywords: 1, branch_patterns: 1, linear_labels: 1}

score(L) = Σ raw_counts[type] × weights[type]   for each signal type

Raw counts are preserved separately for backward-compat with v0.2.0 event-log schema (events.jsonl records counts, not weighted scores). The weighted total is only used for selection.

Step 4: Select lens(es)

• Threshold (v0.3.0): per-lens via L.threshold (top-level frontmatter

field); falls back to DEFAULT_THRESHOLD = 2 if not declared.

• Selection: selected = [L for L in lenses if score(L) >= L.effective_threshold]
• Composition: if multiple lenses pass, apply all in descending score order
• Fallback: if no lens passes, apply _meta only

v0.3.0 design notes

• signals.weights.<type>: 0 is the supported way to disable a signal type for

a specific lens without removing its declaration.

• A lens's threshold cannot be less than 1 (validated at schema check).
• The _meta lens is excluded from scoring — it's always applied as the base

via the extends: resolution.

• The linear_labels signal source is still stubbed (always returns 0 raw

count) — declaring a weight on it has no runtime effect until Linear MCP is wired (v0.4.0+ planned).

Step 5: Resolve extension chain

For each selected lens, walk extends: back to _meta:

chain(L) = [L, L.extends, L.extends.extends, ..., _meta]

Merge context_loaders + quality_bar + prompt_improvement_patterns with child overrides parent semantics (a child lens can override a parent's entry by re-stating it with new content).

Step 6: Decide mode

See mode-selection.md for the mode-decision tree.

Step 7: Emit event

Log to ~/.config/broomva/role/events.jsonl:

{"ts":"<ISO>","event":"intake","session":"<id>","prompt_digest":"sha256:<hash>","lenses_selected":["<names>"],"lenses_extended":["<chain>"],"mode":"<mode>","signals_matched":{"paths":N,"prompt_keywords":N,"branch_patterns":N,"linear_labels":N}}

M1: reasoning-enforced (agent appends manually). M2: hook-driven via UserPromptSubmit Claude Code hook.

Reasoning-enforced caveat

The algorithm above is the contract. Agents implement it via reasoning, not via a deterministic script — same pattern as P10, P14, P15, P16. The Python CLI (role-x.py) validates lens schemas and generates the discovery index but does NOT run selection at runtime.

A future enhancement (M2+) may add role-x select --prompt "..." for deterministic scoring, which would let the agent verify its reasoning-enforced choice against the algorithm. Not in M1 scope.

invalid-lens-missing-required

An invalid lens — missing required fields, should fail validation.

valid-lens

A valid lens for tests.