rag-wright 0.1.0__py3-none-any.whl

rag_wright/skills/generation/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: generation
+description: >
+  The grounded-answer method: answer a question using ONLY the supplied evidence, cite the bracketed chunk id
+  that supports each claim, abstain rather than guess when the evidence does not support an answer, and hedge
+  according to the certainty of graph-derived facts. A single grounded, cited LLM act (FR-C.9 / FR-Q.6). The applying
+  capability enforces the hard guarantees in code (dropping fabricated citations, coercing an uncited answer to
+  an abstention) -- this skill teaches only the reading.
+---
+
+# Answer generation: grounded, cited, willing to abstain
+
+This skill teaches a **method** for turning retrieved evidence into a final answer that never makes a claim
+without a citation. It is a single grounded reading, not a workflow.
+
+## The method
+
+- **Answer using ONLY the evidence below.** Do not use outside knowledge; if a fact is not in the evidence,
+  it is not available to you.
+- **Cite the bracketed chunk id that supports each claim** in `citations`. Every claim in the answer must be
+  traceable to an evidence item by its `[chunk_id]`.
+- **Abstain rather than guess.** If the evidence does not support an answer at all, abstain and do not
+  fabricate one.
+- **Hedge honestly instead of over-answering.** There are three outcomes, not two. When the evidence only
+  *partially* or *tangentially* addresses the question -- it mentions related material but does not actually
+  state what was asked -- do NOT present that mention as a confident answer. Give only what the evidence
+  supports, cite it, and say plainly what the evidence does *not* establish: this is a **partial** answer, not a
+  full one. Reserve a full, confident answer for when the evidence genuinely states it. (An unsupported
+  confident answer is the one failure to avoid; an honest "the evidence mentions X but does not state Y" is
+  correct behavior, not a miss.)
+- **Judge each item by its actual text; verify the text really instantiates the concept the question asks
+  about.** Do not assume an item answers the question just because it was retrieved. If the text does not match
+  the concept asked -- e.g. the question asks for a monetary/maximum liability cap but the text is a
+  force-majeure / excused-performance clause, or asks for minimum commitments but the text is research notes,
+  definitions, or table fragments -- that item does **not** answer the question. Give only what the text
+  genuinely supports and mark `<partial/>`, or abstain if nothing supports it. (A confident answer built from
+  off-topic evidence is the exact failure to avoid.)
+- **Hedge according to the certainty note, if one is given.** Some questions come with a short certainty note
+  flagging that part of the evidence is uncertain or inferred rather than directly stated. When present, present
+  the points that depend on such evidence tentatively (an inference, not a settled fact). Never mention certainty,
+  confidence, or any internal label to the reader; let it shape only how tentatively you phrase the answer.
+- **The answer is prose for a person; keep the engine's markers out of it.** Evidence items carry machine
+  markers -- the citation id, `[dimension=value; ...]` typed-property groups, any `[Exception ... (inferred)]`
+  framing, and the `<partial/>` marker itself -- that are **inputs to your judgement, not facts to relay**. Never
+  repeat, name, quote, or describe them to the reader, and never narrate how certain or uncertain the engine is
+  about a fact. In particular, `<partial/>` is a SIGNAL the engine reads to flag a partial answer, never words for
+  the reader: emit it (per the abstention rule above) but keep it out of the answer prose -- write the partial
+  answer in plain language, not the tag. Let the markers shape only *how confidently* you answer, then state the
+  substance in plain language. Quote the clause's **real text** when it helps; never quote the markers. (Citation
+  ids are recorded separately for the reader, so you never spell an id out in the answer prose.)
+- **State a rule together with its inferred exceptions.** When an evidence item is framed as an exception or
+  carve-out to another provision (e.g. "[Exception to the liability cap (inferred)] ..."), do not omit it or
+  read it as a separate contradictory fact: answer with the rule AND its exceptions in one breath ("capped at
+  X, EXCEPT ... for [the carve-outs]"), citing each, and present the exception as an inference -- so the reader
+  sees both the limit and the conditions under which it lifts.
+
+## What this skill does NOT own (the applying capability's job, enforced in CODE)
+
+- **citation validity** -- a citation to an id not present in the evidence is dropped by the capability, not
+  trusted from the model;
+- **the no-claim-without-a-citation guarantee** (FR-Q.6) -- an answer that ends up with no valid citation is
+  coerced to an abstention by the capability;
+- **the empty-evidence short-circuit** (abstain without a model call) and the **output contract**
+  (`GeneratedAnswer`). The model reads; the code guarantees.

rag_wright/skills/generation/__init__.py

@@ -0,0 +1 @@
+"""generation agent-skill folder: SKILL.md (the grounded-answer method)."""

rag_wright/skills/generic_compliance_judgment/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: generic_compliance_judgment
+description: >
+  The DOMAIN-AGNOSTIC compliance-judgment method: given ONE subject (a practice, document, statement, or
+  scenario) and ONE applicable regulatory requirement, and seeing only the subject text (never the actor's
+  internal records or evidence), decide whether the subject clearly VIOLATES the requirement, clearly SATISFIES
+  it, or cannot be judged from the text and must be escalated for human review. Applies to ANY regulatory domain
+  (safety, privacy, financial, environmental, advertising, ...). The advertising-specific method
+  (`compliance_judgment`) is a SPECIALIZATION of this base method with FTC substantiation/disclosure doctrine;
+  this base carries none of that domain doctrine. The applying capability owns the deterministic guarantees
+  (verdict vocab, conservative default, both-sided citation) -- this skill teaches only the reading.
+---
+
+# Compliance judgment (generic): does this subject satisfy or violate this requirement?
+
+This skill teaches a **method**, not a behavior, and it is **domain-agnostic** -- it works for any regulation,
+not one vertical. It extends the grounding-judge idea (ADR-0028) from "is X supported by cue Y?" to "does the
+subject X satisfy or violate requirement Y?". A capability applies it with its own contract
+(`ComplianceFinding`) and its own guarantees (see "What this skill does NOT own").
+
+## The one hard constraint: you see only the subject text
+
+You are given the requirement and the subject. You **cannot** see the actor's internal records, evidence,
+files, or context beyond the text in front of you. So you can only judge what the *subject text itself* shows.
+This constraint is the whole reason the verdict is three-way, not two-way.
+
+## The three verdicts
+
+Judge the subject against **this one requirement**, reading the requirement's obligation/prohibition/permission
+literally:
+
+- **violation** — reserve this for what is **clearly wrong from the subject text itself**: the text shows the
+  required act was **not done** (an obligation the subject plainly failed to meet), or a prohibited act **was
+  done**, or a stated condition is plainly **breached**. The breach must be evident in the text, not inferred
+  from missing evidence.
+
+- **needs_review** — the requirement plausibly applies, but the subject text **does not show enough** to confirm
+  either compliance or breach (the relevant record, evidence, or detail isn't in the text). You cannot verify it
+  from the text alone, so **escalate** it: a human will check the actor's records/evidence. Do **not** call this
+  a violation (you don't have the proof) and do **not** clear it as compliant (you can't confirm it either).
+
+- **compliant** — the requirement is clearly met **from the text**, or the requirement **does not bite** on this
+  subject at all (it governs a different situation than the one the text describes).
+
+## The discipline
+
+Only say **violation** when the text clearly shows the breach; only say **compliant** when the text clearly
+clears it (or the requirement plainly does not apply); **otherwise `needs_review`**. Uncertainty is escalation,
+never a silent pass. Give a one-sentence rationale grounded in the subject text and the requirement, and a
+confidence in [0,1]. Refer to the material you are judging as "the subject" -- never assume a domain.
+
+## What this skill does NOT own (the applying capability's job)
+
+- the verdict **vocabulary** and the **conservative default** -- an unreadable or missing verdict maps to
+  `needs_review` deterministically, in the capability, not here;
+- the **both-sided citation** -- the exact subject span and the exact requirement clause are attached from the
+  INPUTS by the capability, never authored by this skill (the model rules; it never fabricates a citation);
+- any **roll-up** of findings and the **human gate**.

rag_wright/skills/okf_navigate/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: okf_navigate
+description: >
+  The embedding-free knowledge-navigation method: find the concepts in an Open Knowledge Format (OKF)
+  bundle that answer a question by progressive disclosure, not by vector similarity. Keep the bundle in
+  interpreter variables, read index signposts and frontmatter with tools, dispatch a selector sub-agent
+  to choose which signposts to explore and use the judgeBodies tool to judge candidate bodies in parallel,
+  and return the shortlist of concept ids. Applied by the okf_navigate capability (FR-K.6).
+---
+
+# OKF navigation: progressive disclosure over a knowledge bundle, without similarity
+
+This skill teaches a **method**, not a behavior. An OKF bundle is a directory tree of markdown files
+(one concept per file) with an `index.md` in each directory listing its entries with a one-line
+description, and cross-links between related concepts. The bundle is large; you cannot load it all into
+your context, and you must **never** compute an embedding similarity. You navigate it the way a person
+skims a table of contents: read the signposts, follow the promising ones, read only the documents worth
+reading.
+
+## The method: interpreter holds the bundle → a workflow selects and reads via sub-agents
+
+You do not see the bundle. You write a **workflow** in the `eval` tool that reads the bundle with `tools.*`
+into interpreter variables (never into your context) and makes the two judgments that need a model:
+
+1. **Selection.** For a directory, `tools.readIndex(...)` returns its signposts (each a `path`, a
+   `description`, and `is_dir`). You cannot judge them yourself (they are interpreter data, not in your
+   context), so you dispatch an **`okf_selector`** sub-agent with the list and it returns which to explore.
+   Descend into chosen subdirectories; collect chosen concept files as candidates.
+2. **Reading.** You judge candidate bodies with **`tools.judgeBodies({ rel_paths })`** — hand it a *batch* of
+   candidate paths and it reads and judges them **in parallel**, returning one boolean per path (in order). A
+   relevant concept's id goes on the shortlist, and you push its cross-links onto the frontier to expand.
+   Reading is a tool, not a sub-agent, on purpose: the interpreter runs one JS engine, so dispatching readers
+   with `task()` would serialize them; `tools.judgeBodies` fans them out in the tool instead.
+
+The bundle stays in interpreter variables; the selector is only ever called (via `task()`) on a focused list
+of signposts, and body judging happens inside `tools.judgeBodies`. The selector and the judge both already
+know the question — you pass the selector only the signposts, and the judge only the batch of paths.
+
+### The canonical workflow (write it this way)
+
+**Your ONLY action is to emit this workflow to the `eval` tool in one call, then return its JSON result and
+stop.** The bundle is reachable ONLY through the `tools.*` calls inside `eval` — there is NO filesystem, so
+never call `ls`, `glob`, `read_file`, or `write_file`; they find nothing and waste the turn. Do not answer
+from your own knowledge; the answer only comes from running the workflow.
+
+Call the tools with an **object argument** exactly as their signatures show (for example
+`tools.readIndex({ rel_dir: dir })`, `tools.judgeBodies({ rel_paths: batch })`). The `okf_selector` sub-agent
+returns a JSON **string** in its text; `JSON.parse` it (extract the object with a `{ ... }` match first). Do
+NOT pass a `responseSchema` to `task()` — forcing structured output makes a reasoning model reject the call;
+the selector is instructed to reply with JSON, so parse its text. `tools.judgeBodies` returns a real array of
+booleans (not text) — use it directly, no parsing.
+
+```javascript
+// Navigate an OKF bundle by progressive disclosure. The bundle is read via tools.* into interpreter
+// variables, never into your context; a model is only ever called (task()) on a list of signposts or one
+// document body. No query-to-document similarity is ever computed.
+const BUDGET = await tools.frontierBudget();   // max document bodies to read
+const shortlist = [];                          // concept ids judged relevant
+const visited = new Set();                     // concept paths already read
+
+// SELECTION: hand a list of signposts to the selector sub-agent; it returns the indices worth exploring.
+// Send BOTH the name (`path`) and the `description`: a directory's description may be just a count, so the
+// name carries the signal; a concept's description is its summary. The selector needs both to choose well.
+async function pick(signposts) {
+  const raw = await task({
+    description: "Signposts to choose from:\n" +
+      JSON.stringify(signposts.map((s, i) => ({ i, name: s.path, description: s.description, isDir: s.is_dir }))),
+    subagentType: "okf_selector",
+  });
+  let keep = [];
+  try { keep = JSON.parse(raw.match(/\{[\s\S]*\}/)[0]).keep || []; } catch (e) { keep = []; }
+  return keep.filter((i) => Number.isInteger(i) && i >= 0 && i < signposts.length).map((i) => signposts[i]);
+}
+
+// Descend the tree to a depth bound. The selector gates DIRECTORIES (which subtrees are worth exploring),
+// but once a directory is chosen, collect ALL of its concept files -- do not sub-select concepts. This
+// maximizes recall: a chosen category's clauses are all read (the reader is the precision filter). A
+// signpost's `path` is already resolved (root-relative) by the tool -- pass it straight to readIndex/readBody.
+async function collect(dir, depth) {
+  if (depth > 3) return [];
+  const signposts = await tools.readIndex({ rel_dir: dir });
+  if (!signposts.length) return [];
+  const dirs = signposts.filter((s) => s.is_dir);
+  const out = signposts.filter((s) => !s.is_dir).map((s) => s.path);  // ALL concepts in this directory
+  if (dirs.length) {
+    const chosenDirs = await pick(dirs);  // the selector chooses only which subdirectories to descend
+    for (const d of chosenDirs) out.push(...(await collect(d.path, depth + 1)));
+  }
+  return out;
+}
+
+const frontier = await collect("", 0);
+const log = [];            // one entry per body judged: { path, relevant } — the traversal's decision trace
+const BATCH = 16;          // paths handed to judgeBodies at once; the tool judges them in parallel internally
+// READING: hand batches of candidate paths to judgeBodies (it reads + judges them in PARALLEL and returns a
+// boolean per path), keep the relevant, expand relevant concepts' links. Do NOT read/judge one body at a
+// time -- that serializes the slow step. The tool owns the fan-out; you just batch and combine.
+while (frontier.length && shortlist.length < BUDGET) {
+  const batch = [];
+  while (frontier.length && batch.length < BATCH) {
+    const p = frontier.shift();
+    if (!visited.has(p)) { visited.add(p); batch.push(p); }
+  }
+  if (!batch.length) break;
+  const verdicts = await tools.judgeBodies({ rel_paths: batch });  // parallel [bool], one per path, in order
+  for (let k = 0; k < batch.length && shortlist.length < BUDGET; k++) {
+    log.push({ path: batch[k], relevant: verdicts[k] });
+    if (verdicts[k]) {
+      shortlist.push(await tools.conceptId({ rel_path: batch[k] }));
+      for (const link of await tools.related({ rel_path: batch[k] })) frontier.push(link);  // lateral expansion
+    }
+  }
+}
+JSON.stringify({ shortlist, considered: log.length, log });
+```
+
+**These rules are not optional:**
+
+1. **Never compute similarity.** There is no embedding step and no query-to-document scoring; relevance
+   is judged by `tools.judgeBodies` reading each document, and selection by the selector reading signposts.
+2. **The judgments are not yours to make.** Which signposts to explore comes from `okf_selector`; whether a
+   document is relevant comes from `tools.judgeBodies`. You do not decide these yourself — you cannot, the
+   signposts and bodies are interpreter data, not in your context.
+3. **Read bodies only after the signpost sift.** Select from `index.md` descriptions first; read a body
+   only for a concept the selector kept. Bodies read must stay a small fraction of concepts considered.
+4. **Pass tool arguments as an object**, matching each tool's signature (`{ rel_dir }`, `{ rel_path }`).
+5. **Return `JSON.stringify({ shortlist })`** as the final expression, and nothing else.
+
+## What this skill does NOT own (deferred to the applying capability)
+
+- **Which model each sub-agent uses** — the model-profile seam (the navigation judgments run on the strong
+  model), never a hardcoded flag.
+- **The bounds** (depth, frontier budget) — supplied as run parameters via `tools.*`.
+- **The bundle itself** — compiled by `okf_compile` (FR-K.1-K.4); this method only reads it.
+
+The method is the shape of the computation; the capability supplies the tools, the sub-agents, the bounds,
+and the tests. Keep this file about the shape.

rag_wright/skills/requirement_extraction/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: requirement_extraction
+description: >
+  The regulatory-rule extraction method: read one § section of a regulation and pull out the distinct DEONTIC
+  rules it states (each an obligation / prohibition / permission), with the actor it binds, the claim types it
+  applies to, and any evidence standard. Used by the requirement_extraction SUBGRAPH's extraction node. Because
+  a section spreads its rules across the whole text, extraction runs multi-call (skeleton-then-fill) -- which is
+  why the capability is a subgraph, not a single-shot skill. The schema is the co-located asset template.py; the
+  deterministic mapping to the closed Requirement vocab is the requirement_adaptation FUNCTION's job.
+---
+
+# Requirement extraction: what deontic rules does this regulatory section state?
+
+This skill teaches a **method**, not a behavior. It turns one regulatory § section into the deontic rules the
+compliance check will judge against. The extraction **schema** is the co-located asset **`template.py`**
+(`ExtractedRegulationSection` → `ExtractedRequirement[]`), filled by the model.
+
+## What to extract (the schema — `template.py`)
+
+Per section, an `ExtractedRegulationSection` whose `requirements` are the distinct **operative** rules. For each:
+
+- **requirement_text** — one rule, paraphrased in a sentence: what must, must not, or may be done.
+- **deontic_type** — `obligation` (must/required), `prohibition` (must not/may not), or `permission` (may).
+- **actor** — who the rule binds (advertiser, endorser, expert, …).
+- **claim_types** — which advertising claim types it applies to (from the closed vocab), when the rule is
+  claim-type-specific; leave empty when it applies by context (the applicability map handles that downstream).
+- **evidence_standard** — the substantiation the rule requires, if any.
+
+Extract only **operative rules**, not the section's definitions or purpose statements.
+
+## The reliability method (docling-graph, from GP-1B + EXTRACT-TUNE)
+
+1. **source must be a file path**, not a raw string (docling-graph `stat()`s it — write a temp file).
+2. **`structured_output=False`** (json_object) — the strict nested json_schema returns nothing on some models.
+3. **a `max_tokens` cap** + a wide `preamble_chars` (a full section, not a contract preamble).
+4. **`extraction_contract="auto"`** -- CRITICAL. A regulatory section spreads its rules across the whole text, so
+   a single `"direct"` call SILENTLY self-rations and loses most of them (measured: §255.5 → 6 direct vs 31
+   dense). `"auto"` picks dense (skeleton-then-fill, multiple calls) on long sections. This multi-call is the
+   reason the capability is a **subgraph**.
+
+## What this skill does NOT own (the subgraph / the function)
+
+- the deterministic mapping to the closed vocab (`deontic_type` coercion -- off-vocab → AMBIGUOUS; off-vocab
+  claim_type dropped; blank rule skipped), the `citation` (= the section) and the content-hash `requirement_id`
+  -- the `requirement_adaptation` FUNCTION;
+- the extract → adapt chaining, retry/dead-letter, and the write -- the `requirement_extraction` SUBGRAPH and the
+  `compliance_ingestion` corpus driver.

rag_wright/skills/requirement_extraction/__init__.py

@@ -0,0 +1 @@
+"""requirement_extraction agent-skill folder: SKILL.md + the template.py schema asset."""

rag_wright/skills/requirement_extraction/template.py

@@ -0,0 +1,50 @@
+"""Schema ASSET for the `requirement_extraction` subgraph's extraction node (referenced by this folder's SKILL.md).
+
+The docling-graph extraction template the extraction node fills: `ExtractedRegulationSection` (a § section) with
+its `ExtractedRequirement`s. Loose strings by design (robust to model output); the deterministic
+`requirement_adaptation` FUNCTION maps them to the closed CC-1 `Requirement` vocab. Co-located with the skill
+because the schema IS part of the authored extraction method (an Agent-Skill asset).
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from rag_wright.capabilities.dg_extraction import edge
+
+
+class ExtractedRequirement(BaseModel):
+    """One rule the LLM reads out of a regulatory section (a docling-graph child entity). Loose strings by
+    design (robust to model output); the adapter maps them to the closed CC-1 vocab."""
+
+    model_config = ConfigDict(graph_id_fields=["requirement_text"], extra="ignore", populate_by_name=True)
+
+    requirement_text: str = Field(
+        description="One rule the section states, paraphrased in a single sentence: what must, must not, or may be done")
+    deontic_type: str = Field(
+        default="obligation",
+        description="obligation (must / required), prohibition (must not / may not), or permission (may / allowed)")
+    actor: str = Field(default="", description="Who the rule binds, e.g. advertiser, endorser, expert")
+    claim_types: list[str] = Field(
+        default_factory=list,
+        description=("Which advertising claim types this rule applies to, chosen from: efficacy, comparative, "
+                     "pricing, health, environmental, endorsement, performance, guarantee"))
+    applicability: list[str] = Field(
+        default_factory=list,
+        description=("P3a (Gap 2): the conditions under which THIS rule applies, as 'dimension: value' pairs (one "
+                     "per entry) -- for ANY policy domain, not only advertising. E.g. 'jurisdiction: California', "
+                     "'employee_class: hourly', 'data_category: biometric', 'product_category: supplement'. Leave "
+                     "empty if the rule applies unconditionally. (Advertising claim types go in claim_types.)"))
+    evidence_standard: str = Field(
+        default="", description="The substantiation the rule requires, if any (e.g. competent and reliable scientific evidence)")
+
+
+class ExtractedRegulationSection(BaseModel):
+    """A regulatory section and the distinct rules it states (the docling-graph root entity)."""
+
+    model_config = ConfigDict(graph_id_fields=["section"], extra="ignore", populate_by_name=True)
+
+    section: str = Field(description="The section number, e.g. 255.5")
+    requirements: list[ExtractedRequirement] = edge(
+        "STATES_REQUIREMENT", default_factory=list,
+        description="The distinct rules stated in this section (one entry per rule)")

rag_wright/skills/rlm/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: rlm
+description: >
+  The recursive-language-model (RLM) divide-and-conquer method: when a working set is too large for
+  one context window, load it into the code interpreter as data, then write a recursive workflow that
+  dispatches the work to sub-agents in code (a fresh decomposer per level, a worker per leaf) and
+  combines their results, so the model never attends over the full volume. Applied by the RLM chunking
+  capability (ingestion) and the RLM synthesis capability (query).
+---
+
+# RLM: divide and conquer over a working set too large for one prompt
+
+This skill teaches a **method**, not a behavior. It is authored software (FR-C.10), not a build-tool
+feature. Two capabilities apply it with their own contracts and tests: **RLM chunking** (FR-I.1,
+ingestion) and **RLM synthesis** (FR-Q.5, query). This document is deliberately general; every
+guarantee an application needs (determinism, boundary validation, gating, idempotence) is the
+**applying capability's** job, not the method's (see "What this skill does NOT own").
+
+## The problem
+
+A prompt has a bounded context window. Real working sets, a whole parsed document or a large candidate
+set of retrieved chunks, routinely exceed it, or fit but degrade quality when the model must attend
+over everything at once. Stuffing the whole volume into one call is the failure mode this method avoids.
+
+## The method: interpreter holds the whole → a recursive workflow dispatches sub-agents → combine
+
+1. **Get the working set from the runtime, as data — the WHOLE set.** Call
+   `const workingSet = await tools.workingSet();` — the runtime returns the full input as ordinary
+   interpreter values (strings, lists, dicts), *not* into a prompt. Load **all** of it: never sample,
+   slice, or subset it, and never decide part of it suffices — you cannot see it, so you cannot judge
+   that. Immediately assert you loaded the whole delivered set against `tools.workingSetSize()` (see the
+   canonical workflow); a short load is a silent evidence drop the coverage tail cannot catch, because the
+   tail only guarantees coverage over what you loaded. The interpreter, not the model, holds the state and
+   the recursion stack, and is not bounded by a context window. The working set is never in your context;
+   you only ever hold it as an interpreter variable.
+
+2. **Write a recursive `decompose()` workflow in code that dispatches sub-agents.** This is a
+   **workflow**: fan the work out to sub-agents with `task()` from interpreter code, never one grinding
+   tool call at a time. `decompose(slice)` does one of two things:
+   - If the slice is small and focused enough, dispatch it to an **`rlm_slice_worker`** (a leaf): a
+     full agentic loop that handles that one slice with its own tools and skills, and sees only that
+     slice.
+   - Otherwise dispatch a **fresh `rlm_decomposer`** to decide this level's split, then **call
+     `decompose()` again on each returned sub-slice.** The recursion lives here, in the interpreter:
+     the same function re-enters itself to arbitrary depth, and each level's decomposer is a fresh
+     agent with fresh context. A model is only ever called on a focused slice, never on the whole.
+
+   The recursion is driven by the **interpreter**, not by an agent dispatching itself: on this runtime
+   a sub-agent cannot dispatch to itself (a self-referential agent is not constructible). The
+   interpreter re-dispatching a fresh `rlm_decomposer` per level *is* the recursion, and it delivers
+   the per-level fresh context the method wants.
+
+3. **Combine the results in code, recursively if needed.** Collect the per-leaf outputs and reduce them
+   in code (a fan-in). When the combined intermediate is itself too large, apply the same reduce
+   recursively, so a model is called on the *reduced* material, never on the raw whole.
+
+The invariant across all three steps: **the model is only ever called on a small, focused slice; the
+interpreter holds the whole and drives the recursion.**
+
+### The canonical workflow (write it this way)
+
+The recursive descent, written into the `eval` tool. Read the working set from the runtime tool
+`tools.workingSet()` — it returns the whole working set as a JavaScript value that lives in the
+interpreter and never enters your context. Do **not** expect the working set in your prompt; call the
+tool.
+
+Write this workflow **exactly** — the decomposer dispatch MUST carry the item count (`over N items`) or
+the decomposer cannot return index cuts and you fall back to a flat, non-recursive run:
+
+```javascript
+// Recursive divide-and-conquer over a working set of items. Read it from the runtime tool (a JS value
+// that stays in the interpreter and never enters the model's context), then fan the work out to
+// sub-agents in code (a "workflow"), never one grinding tool call at a time. The interpreter holds the
+// working set and the recursion stack; the model is only ever called on a focused slice.
+const workingSet = await tools.workingSet();  // [{id, ...}, ...] delivered by the runtime, never in context
+// LOAD-COMPLETENESS ASSERTION (T37): verify you loaded the WHOLE delivered set before anything else. The
+// size comes from the runtime (a scalar it cannot under-read); if the load is short, fail loud rather than
+// silently working over a truncated set — the coverage tail below only guarantees coverage over what you
+// loaded, so an under-read here is a silent evidence drop nothing downstream catches.
+const _delivered = await tools.workingSetSize();
+if (workingSet.length !== _delivered) {
+  throw new Error("LOAD UNDER-READ: loaded " + workingSet.length + " of " + _delivered + " delivered items");
+}
+const _MAX_DEPTH = 3;                // hard cap on recursion — beyond this, force leaf (no runaway splits)
+const _splitDepths = [];             // the depths at which decompose() re-entered itself (proof of descent)
+const _handled = new Set();          // ids of working-set items a leaf worker covered
+async function decompose(items, depth) {
+  if (items.length === 0) return [];    // empty slice — nothing to dispatch (no-op leaf)
+  if (depth >= _MAX_DEPTH) {
+    for (const it of items) _handled.add(it.id);
+    return [await task({ description: "handle leaf depth " + depth + " over " + items.length + " items: " + JSON.stringify(items), subagentType: "rlm_slice_worker" })];
+  }
+  const decision = JSON.parse(await task({
+    description: "decompose depth " + depth + " over " + items.length + " items",
+    subagentType: "rlm_decomposer",
+  }));
+  if (decision.leaf) {
+    for (const it of items) _handled.add(it.id);
+    return [await task({ description: "handle leaf depth " + depth + " over " + items.length + " items: " + JSON.stringify(items), subagentType: "rlm_slice_worker" })];
+  }
+  _splitDepths.push(depth);
+  // decision.cuts partition `items` into contiguous groups (no item lost); recurse on every group.
+  const bounds = [0, ...decision.cuts, items.length];
+  const groups = [];
+  for (let i = 0; i < bounds.length - 1; i++) groups.push(items.slice(bounds[i], bounds[i + 1]));
+  const handled = await Promise.all(groups.map((g) => decompose(g, depth + 1)));
+  return handled.flat();
+}
+const _leaves = await decompose(workingSet, 0);
+// COVERAGE TAIL (structural, in-interpreter): the code holds EVERY item, so it guarantees coverage even
+// if the recursion missed a deep leaf out of context — a silent drop otherwise (T37). Any uncovered item
+// is dispatched now, not dropped. This is code checking coverage, not the model asked to be thorough.
+const _missed = workingSet.filter((it) => !_handled.has(it.id));
+if (_missed.length) {
+  for (const it of _missed) _handled.add(it.id);
+  _leaves.push(await task({ description: "cover " + _missed.length + " missed items: " + JSON.stringify(_missed), subagentType: "rlm_slice_worker" }));
+}
+JSON.stringify({
+  leaves: _leaves,
+  leafCount: _leaves.length,
+  covered: _handled.size,
+  total: workingSet.length,
+  missed: _missed.length,
+  maxSplitDepth: _splitDepths.length ? Math.max(..._splitDepths) : -1,
+});
+```
+
+**These rules are not optional. Follow them exactly:**
+
+1. **The split is the decomposer's job, never yours.** How to partition each level MUST come from a
+   `rlm_decomposer` return value (`decision.cuts`), obtained by dispatching the decomposer. You do not
+   decide the split yourself and you do not know the grouping in advance; only the decomposer does.
+2. **Recurse on the decomposer's output.** When the decomposer returns `cuts`, slice `items` into those
+   groups and call `decompose()` again on **each group**. A group may itself split, up to `_MAX_DEPTH`
+   (3) — beyond that the code force-terminates the branch as a leaf without calling the decomposer
+   again (a hard cap against runaway recursion). Stop a branch early when the decomposer marks that
+   slice a leaf (`decision.leaf === true`), then dispatch a `rlm_slice_worker`.
+3. **One `decompose()` per node, one decomposer dispatch per node.** A single decomposer call for the
+   whole working set is wrong: that is a flat split, and it defeats the method.
+4. **The coverage tail guarantees completeness — never skip it, and never rely on it as a licence to be
+   incomplete.** After the recursion, the tail (above) diffs the working set against `handled` and
+   dispatches any item the recursion missed, in interpreter code, before returning. This is *code checking
+   coverage against the whole working set you hold*, not you being asked to be thorough — the structural
+   guarantee the method needs, because out of context a missed deep leaf is a silent drop that still
+   reports success. Still write a complete recursion; the tail is the safety net, not the method.
+
+**Anti-pattern (do NOT do this):**
+
+```javascript
+// WRONG: calling the decomposer once, then hardcoding the slice list and skipping the recursion.
+await task({ description: "split it", subagentType: "rlm_decomposer" });
+const slices = [ {id: "part_a", ...}, {id: "part_b", ...}, {id: "part_c", ...} ];  // <-- you invented these
+for (const s of slices) { await task({ subagentType: "rlm_slice_worker", description: "handle " + s.id }); }
+```
+
+That is the failure this method exists to prevent: it looks like it ran, but the slices came from you, not
+from a recursive decomposition, so the working set was never actually divided and conquered. If you find
+yourself writing a literal array of slices, stop: you should be recursing on `decision.parts` instead.
+
+## How the two capabilities apply it
+
+- **RLM chunking (FR-I.1).** Working set = one whole parsed document. `decompose` splits along topic /
+  section / chapter boundaries into semantically coherent, capped chunks; each leaf worker summarizes
+  its chunk. The applying capability keeps the boundary and `chunk_id` computation deterministic
+  (that stays a separate, exact function; it is not the RLM method's job).
+- **RLM synthesis (FR-Q.5).** Working set = the candidate chunks a query retrieved. `decompose` slices
+  the candidate set; each leaf worker extracts the query-relevant facts from its slice; the code-side
+  fan-in reduce combines the extracts, so synthesis never attends over the full chunk volume.
+
+## The dynamic-dispatch trigger
+
+This workflow only fans out if the run is triggered for code-driven dispatch. The skill declares that
+requirement (`skillRuntime.requiresDynamicDispatch`); the runtime that hosts the RLM node applies the
+trigger so this `eval` workflow fires, rather than a slower one-slice-at-a-time fallback. The skill does
+not carry the trigger phrasing itself.
+
+## What this skill does NOT own (deferred to the applying capability)
+
+- **Determinism and reproducibility** — temperature zero or structured output, and stable ids. (RLM
+  chunking owns this for `chunk_id`s and boundaries, in a separate deterministic function.)
+- **Boundary validation** — checking that produced slices are well-formed and within caps.
+- **Gating** — content-hash gating so unchanged input does no work; incremental, resumable runs.
+- **Model choice** — which model each role uses, via the model-profile seam (never a hardcoded flag).
+
+The method is the shape of the computation; the capability supplies the contract, the guarantees, and
+the tests. Keep this file about the shape.

rag_wright/skills/rlm/__init__.py

@@ -0,0 +1,31 @@
+"""RLM skill package — the divide-and-conquer method (FR-C.10).
+
+Exposes the authored RLM method: the recursive workflow that holds the working set in the
+interpreter, dispatches sub-agents per level (a fresh ``rlm_decomposer`` each) and per leaf
+(``rlm_slice_worker``), then combines results. Two applying capabilities build on this skill:
+RLM chunking (FR-I.1, ingestion) and RLM synthesis (FR-Q.5, query).
+"""
+
+from rag_wright.skills.rlm.agent import (
+    GRANTED_SUBAGENTS,
+    RLM_DECOMPOSER,
+    RLM_SLICE_WORKER,
+    RLM_WORKFLOW_JS,
+    build_rlm_agent,
+    decomposer_config,
+    method_prompt,
+    rlm_interpreter_session,
+    slice_worker_config,
+)
+
+__all__ = [
+    "GRANTED_SUBAGENTS",
+    "RLM_DECOMPOSER",
+    "RLM_SLICE_WORKER",
+    "RLM_WORKFLOW_JS",
+    "build_rlm_agent",
+    "decomposer_config",
+    "method_prompt",
+    "rlm_interpreter_session",
+    "slice_worker_config",
+]