# SME Rule Library — Pillar 3 (Decision)

The Rule Library is the architectural mechanism for SME knowledge to
enter Pillar 3. SMEs encode their decision expertise as structured
YAML rule entries; the three Decision agents read those entries at
runtime and apply them. Analog to the Pillar 2 methodology library at
`src/intelligence/methodologies/`.

## Layout

```
src/decision/rules/
  README.md                                              <- this file
  cross_domain/                                          <- domain-agnostic foundations
    peer_positioning_recommendation.yaml                 (interpretation rule)
    decision_maker_peer_comparison_chart.yaml            (visualization rule)
    material_decision_maker_alert_delivery.yaml          (delivery rule)
  banking/                                               <- populated by banking SMEs
  wealth/                                                <- populated by wealth SMEs
  insurance/                                             <- populated by insurance SMEs
```

Rules in subfolders are picked up automatically — the loader walks
`src/decision/rules/` recursively for `*.yaml` and `*.yml`.

## Rule types

Three primary rule types live in the library, one per Decision agent:

1. **Interpretation rules** (`type: interpretation`) — How Agent 1
   (Output Ingestion & Interpretation) converts Pillar 2 findings
   into recommendations.
2. **Visualization rules** (`type: visualization`) — How Agent 2
   (Visualization) renders recommendations as audience-appropriate
   visual outputs.
3. **Delivery rules** (`type: delivery`) — How Agent 3 (Delivery &
   Distribution) routes outputs to recipients on approved channels.

## Entry format

Every rule satisfies this minimum structure (validated by
`src/decision/library.ts`):

```yaml
rule_id: <unique snake_case identifier>
name: <human-readable name>
type: interpretation | visualization | delivery
domain: <where this applies — banking | wealth | insurance | all>

applies_to:
  agent: output_ingestion | visualization | delivery
  triggers:
    - <free-text condition the agent matches on>
    - <case-insensitive substring search against this list>

conditions:
  - <predicate conditions that must match for this rule to fire>

action:
  <what the rule produces when its conditions match — structured>

confidence_framework:
  <how confidence is scored for outputs produced by this rule>

disclosure_policy:           # optional, mostly for visualization + delivery rules
  audience_clearance_check: required | not_required
  default_allowed_tiers: [<tier>, ...]
  default_restricted_tiers: [<tier>, ...]
  attachment_policy: <string>

rationale: |
  Why this rule exists, when to apply, when not to.

declared_by: <SME name or team>
declared_date: <YYYY-MM-DD>
last_reviewed: <YYYY-MM-DD>
status: active | deprecated | under_review
```

## How rules get added

Same three paths as the Pillar 2 methodology library:

1. **Direct encoding.** SME writes a new YAML file. Reviewed before
   merging. The loader picks it up automatically — no agent code
   changes.
2. **Escalation-driven.** An agent escalates a rule-gap case per Std
   9 (`category: 'rule-gap'`). SME provides guidance. If the case
   recurs, the guidance becomes a permanent library entry.
3. **Periodic review.** SMEs review the library at intervals.
   Outdated rules get `status: deprecated`. Coverage gaps get noted
   for SME work.

## What agents do at runtime

Per spec §SME Rule Library:

1. Agent receives input (interpretation request, visualization
   request, delivery request).
2. Agent queries the library through
   `find_rules({type, domain, agent, triggers})` (deterministic — no
   LLM needed for discovery, per Std 5 cost-appropriate execution).
3. If multiple rules match, resolve via `resolvePrecedence(rules)` —
   most specific match wins; domain-specific beats `domain: all`;
   newer `declared_date` beats older at equal specificity.
4. Apply the matched rule. Where the rule's conditions are
   natural-language predicates (e.g. the interpretation rule above),
   the agent uses the LLM to evaluate them against the input.
   Where the rule's action is structured (e.g. the visualization or
   delivery rules above), the agent applies it deterministically
   without an LLM call — Std 6 cost-appropriate execution.
5. Record the `rule_id` in the audit trail (Std 3).
6. If no rule matches, escalate per Std 9 with
   `category: 'rule-gap'`.

## Where to start

The three rules currently in `cross_domain/` are the foundational set
referenced by the Pillar 3 spec's example section. They demonstrate
the three rule types end-to-end and exercise the cross-pillar audit
trail.

To extend the framework into a new domain, drop YAML files into the
appropriate subfolder. To swap real channels for the default
`audit-log` channel, register your channel adapters via
`registerChannel(...)` from `src/decision/channel-registry.ts` and
reference them by name in your delivery rules.