rag-wright 0.11.0__tar.gz → 0.12.0__tar.gz

{rag_wright-0.11.0 → rag_wright-0.12.0}/.claude/skills/building-an-agent-harness/SKILL.md

@@ -161,9 +161,20 @@ them later and each one is a refactor with its own test fallout:
 | resuming a suspended run | the continuation renders ITSELF; the substrate asks |
 | the agent's chat model | from the engine's model profile, never a string in the substrate |
 
-**Collect them into ONE object the substrate is handed** -- we called it `AgentDefinition`, carrying the
-tool surface, the planning classification, the worker roster and the context type. Four declared facts, and
-**the substrate derives everything else**.
+**Collect them into ONE object the substrate is handed** -- `AgentDefinition`, with FIFTEEN required
+fields, and **the substrate derives everything else**. Four are the shape: the tool surface (`surface`), the
+planning classification (`planning`), the worker roster (`workers`) and the context type (`context_schema`).
+The other eleven are the customization surface, and an agent without them runs but is quietly less capable:
+`retry_on`, `message_for`, `model_id_for`, `prompts` (an `AgentPrompts`, eleven fields of its own: every word
+the model reads), `repeatable`, `question_argument`, `framings`, `carry_forward`, `rules`, `decision_points` and
+`read_framing`. The field-by-field reference, generated from the tier, is `docs/harness.md` in the engine
+repository.
+
+**Build every worker with `worker_spec(..., definition=...)`.** `worker_spec`'s policy parameters default to
+inert values, and all but the ledger are fields of the definition you already declared; a worker built
+without threading them ran with no retries, no repeat suppression and no decision recording while every test
+passed. With `definition=`, each parameter you leave at its default is taken from the definition, and a value
+you pass still wins.
 
 That last clause is the whole trick. The alternative -- let the product pass the derived sets too -- is a
 smaller diff and scores perfectly on every axis, and it exports an invariant as a convention the next

rag_wright-0.12.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.12.0"
+}

{rag_wright-0.11.0 → rag_wright-0.12.0}/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to RAG_Wright are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.11.0...0.12.0) (2026-10-15)
+
+
+### Features
+
+* **PS-43:** worker_spec(definition=), the harness design reference, and the harness source cleared of its originating product's vocabulary ([c19ff4d](https://github.com/fzaidi-dai/RAG_Wright/commit/c19ff4da006611383c6a7bca07ba633e345b44d8))
+
 ## [0.11.0](https://github.com/fzaidi-dai/RAG_Wright/compare/0.10.0...0.11.0) (2026-10-15)
 
 

{rag_wright-0.11.0 → rag_wright-0.12.0}/CLAUDE.md

@@ -55,7 +55,12 @@ The failure mode to avoid, which has happened before: a command fails with "modu
 
 ## Start of every session
 
-> **CURRENT STATE (2026-10-14): PS-32 done: the agent harness is the engine's third public tier `rag_wright.harness`**
+> **CURRENT STATE (2026-10-15): `rag-wright` 0.11.0 is RELEASED** (PR #13: PS-40 the product-building skills ship,
+> PS-41 the skills audit, PS-42 by-slug registration; RuleWright's guide `docs/specs/public-surface/rulewright-migration-0.11.0.md`).
+> **PS-43 done, unreleased (next: 0.12.0)**: `worker_spec(definition=)`, `docs/harness.md` (tables generated by
+> `scripts/build_harness_doc.py`), the harness source cleared of RuleWright's vocabulary with a guard; guide
+> `rulewright-migration-0.12.0.md`. Before it,
+> **(2026-10-14): PS-32 done: the agent harness is the engine's third public tier `rag_wright.harness`**
 > (ADR-0139 handover; with PS-39 `ws.embedder` / `api.query_embedder`; RuleWright's guide
 > `docs/specs/public-surface/rulewright-migration-0.10.0.md`; RELEASED as `rag-wright` 0.10.0 on 2026-10-14: PyPI + GitHub release `0.10.0`, PR #12). Before it,
 > **(2026-10-13): `rag-wright` 0.9.0 is RELEASED** (PS-36 `agent_chat_model`, PS-37 drop/temporary

{rag_wright-0.11.0 → rag_wright-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rag-wright
-Version: 0.11.0
+Version: 0.12.0
 Summary: A domain-retargetable, open-core engine for hybrid retrieval + knowledge-graph RAG: parsing, chunking, embedding, hybrid search, reranking, graph extraction, entity resolution, ontology-driven knowledge, and a capability runtime.
 Project-URL: Homepage, https://github.com/fzaidi-dai/RAG_Wright
 Project-URL: Repository, https://github.com/fzaidi-dai/RAG_Wright
@@ -117,6 +117,8 @@ The whole doc set is under [`docs/`](docs/). Pick your path:
   product seam); a coding agent should drive it with the `using-the-rag-wright-engine` skill.
 - **Measuring a capability?** [Evals](docs/evals.md): gold sets from your experts' files, a scorer per capability
   kind, a runner with repeats, a report your backend can return, optional Langfuse runs.
+- **Building your product's agent?** [The agent harness](docs/harness.md): the third tier's design, every field a
+  product declares, and where it goes quiet rather than failing.
 - **Going deep?** [Architecture](docs/architecture.md), the generated [API reference](docs/api/), the
   [Reference pack](docs/reference-pack.md), and the [ADR index](docs/adr/README.md).
 - **Releases?** See the [CHANGELOG](CHANGELOG.md) and [how releases work](docs/releasing.md) (batched via

{rag_wright-0.11.0 → rag_wright-0.12.0}/README.md

@@ -59,6 +59,8 @@ The whole doc set is under [`docs/`](docs/). Pick your path:
   product seam); a coding agent should drive it with the `using-the-rag-wright-engine` skill.
 - **Measuring a capability?** [Evals](docs/evals.md): gold sets from your experts' files, a scorer per capability
   kind, a runner with repeats, a report your backend can return, optional Langfuse runs.
+- **Building your product's agent?** [The agent harness](docs/harness.md): the third tier's design, every field a
+  product declares, and where it goes quiet rather than failing.
 - **Going deep?** [Architecture](docs/architecture.md), the generated [API reference](docs/api/), the
   [Reference pack](docs/reference-pack.md), and the [ADR index](docs/adr/README.md).
 - **Releases?** See the [CHANGELOG](CHANGELOG.md) and [how releases work](docs/releasing.md) (batched via

{rag_wright-0.11.0 → rag_wright-0.12.0}/docs/api/harness.md

@@ -1,6 +1,6 @@
 # Agent harness reference — `rag_wright.harness`
 
-> **Generated** from the live `rag_wright.harness.__all__` by `scripts/build_api_docs.py` — do not edit by hand. The agent harness tier (ADR-0139): what a product builds its agent on. It reaches the rest of the engine only through `rag_wright.api`. See the package docstring.
+> **Generated** from the live `rag_wright.harness.__all__` by `scripts/build_api_docs.py` — do not edit by hand. The agent harness tier (ADR-0139): what a product builds its agent on. It reaches the rest of the engine only through `rag_wright.api`. The design reference, with what a product declares and why, is `docs/harness.md`.
 
 ## Types
 
@@ -20,11 +20,11 @@ Every word a product says to its model: the tier prompts, the memory line and th
 
 One user-initiated agent turn, and the scope it ran under.
 
-`run_id` is the run's identity: `run-contract.md` obligation 1 requires a run to outlive the view that started it, so it is returned rather than held in memory, and it is what `resume_run` addresses.
+`run_id` is the run's identity: a run must outlive the view that started it, so it is returned rather than held in memory, and it is what `resume_run` addresses.
 
 ### `RunOutcome(*values)`
 
-What became of a run, named in CODE because none of it is a judgement (T-5a.15).
+What became of a run, named in CODE because none of it is a judgement.
 
 **Every transition here is decidable from the state alone**, which is why it is not in a prompt: the project's own rule is that a warning in a prompt is not a constraint, and `read_the_question` was instructed in four places and obeyed zero times.
 
@@ -40,7 +40,7 @@ A memory operation reached the store with no run context.
 
 ### `WorkerReport(*, status: str, need: str = '') -> None`
 
-What every worker carries, whatever else it returns (`AR-16`).
+What every worker carries, whatever else it returns.
 
 **Structured, because the orchestrator chains it.** `status` lets a program branch; `need` is how a worker says it cannot finish without a person, since it has no way to ask.
 
@@ -54,7 +54,7 @@ One thing worth telling the client about.
 
 A model call passed a wall-clock ceiling. **Never raised directly** -- one of the two below is.
 
-There are two ceilings with OPPOSITE retry semantics, and they had one exception type between them until T-5a.12q. That cost a live run `compliance_worker` SEVEN identical dispatches: the whole-turn breach escaped the worker, arrived at the parent as a failed `task` tool call, and `ToolRetryMiddleware(retry_on=TRANSIENT)` re-ran the worker's entire job. Catch this base when you mean "some deadline fired"; never put it in a retry set.
+There are two ceilings with OPPOSITE retry semantics, and they had one exception type between them at first. That cost one worker in a live run SEVEN identical dispatches: the whole-turn breach escaped the worker, arrived at the parent as a failed `task` tool call, and `ToolRetryMiddleware(retry_on=TRANSIENT)` re-ran the worker's entire job. Catch this base when you mean "some deadline fired"; never put it in a retry set.
 
 ### `ModelAttemptTooSlow`
 
@@ -94,7 +94,7 @@ What a product offers an agent run, and the two things the substrate asks about
 
 The only thing the substrate needs to know about a run's tenancy.
 
-A product's own context type satisfies this by having the two members; it keeps whatever else it wants (`AgentContext` keeps typed ids, a user id and `for_tenant`).
+A product's own context type satisfies this by having the two members; it keeps whatever else it wants (typed ids, a user id, its own construction rule).
 
 ## Type aliases
 
@@ -138,13 +138,13 @@ Begin a run under `context`, and supply it to every invocation.
 
 The caller passes who is asking, what they asked, and the scope it runs under. **That scope is the PRODUCT's to derive** (engine ADR-0139): the substrate must not know what authenticated this run, so it takes the resolved scope rather than three identity rows it would have to re-read.
 
-**The obligation `AR-6` placed here therefore moves to the caller, and is not weaker for it**: the context must come from the authenticated session of THIS request, never from one remembered across requests. On the route that is structural -- `tenant: TenantDep` is a per-request dependency and the product's own `for_tenant` rule runs in the handler body -- which is why the door is still impossible to forget rather than merely documented.
+**The obligation to bind the context per invocation therefore moves to the caller, and is not weaker for it**: the context must come from the authenticated session of THIS request, never from one remembered across requests. On a route that is structural -- the tenant is a per-request dependency and the product's own construction rule runs in the handler body -- which is why the door is still impossible to forget rather than merely documented.
 
-A `run_id` is minted when the caller has none, so a run is addressable from the moment it exists rather than from whenever somebody remembers to name it (`run-contract.md` obligation 1).
+A `run_id` is minted when the caller has none, so a run is addressable from the moment it exists rather than from whenever somebody remembers to name it.
 
-**Tracing and accounting attach HERE, for the same reason the context does** (T-5a.4b): this is the only door, so it is the only place that cannot be forgotten. `settings=None` leaves both off and `accounting=None` is a no-op — the precedent `recording_usage` set, because accounting must never be the reason a user's work does not happen.
+**Tracing and accounting attach HERE, for the same reason the context does**: this is the only door, so it is the only place that cannot be forgotten. `settings=None` leaves both off and `accounting=None` is a no-op — the precedent `recording_usage` set, because accounting must never be the reason a user's work does not happen.
 
-**`continuation` must already be RESOLVED** (`AR-12`, T-5a.10). It is typed `Any` only because the harness must not import its own models into this module's signature dance; `render_continuation` refuses anything but a `ResolvedContinuation` by name, so a caller that skipped the workspace check gets `UnresolvedContinuation` here rather than a prompt full of the browser's claims.
+**`continuation` must already be RESOLVED.** It is typed `Any` only because the harness must not import its own models into this module's signature dance; `render_continuation` refuses anything but a `ResolvedContinuation` by name, so a caller that skipped the workspace check gets `UnresolvedContinuation` here rather than a prompt full of the browser's claims.
 
 ### `resume_run(agent: 'Any', context: 'RunScope', *, answer: 'Any', run_id: 'str', settings: 'Any' = None, accounting: 'Any' = None) -> 'RunResult'`
 
@@ -160,17 +160,17 @@ Begin a run and yield `(run_id, namespace, mode, chunk)` as it happens.
 
 **The streaming sibling of `start_run`, and it carries the same guarantees** — the context, the trace and both ledgers — because they attach here rather than at the call site. A surface that streamed through `agent.astream` directly would lose all three and look like it worked.
 
-`subgraphs=True` is what makes a subagent's output distinguishable from the main agent's; without it every event arrives flat and `AR-18`'s cards have nothing to index on. Two stream modes are requested, so langgraph yields **3-tuples** rather than 2 — verified, not assumed.
+`subgraphs=True` is what makes a subagent's output distinguishable from the main agent's; without it every event arrives flat and a client's per-subagent cards have nothing to index on. Two stream modes are requested, so langgraph yields **3-tuples** rather than 2 — verified, not assumed.
 
-**`continuation` is built the same way `start_run` builds it**, through `_opening_turn`. Two doors would mean two chances to forget the view, and the streaming one is the door the product actually uses — so a continuation that only worked on `start_run` would be a feature with no users (`AR-12`).
+**`continuation` is built the same way `start_run` builds it**, through `_opening_turn`. Two doors would mean two chances to forget the view, and the streaming one is the door the product actually uses — so a continuation that only worked on `start_run` would be a feature with no users.
 
 ### `read_run(agent: 'Any', context: 'RunScope', *, run_id: 'str') -> 'RunResult | None'`
 
-Where a run got to, by its id alone — or `None` if it is not this matter's (T-5a.4c-iii).
+Where a run got to, by its id alone — or `None` if it is not this scope's.
 
-**`run-contract.md` obligation 1, cashed:** *"the run is addressable, and its region renders from an id alone, never from in-memory state that a reload destroys."* A reload, a second tab, or a deploy all arrive here.
+**The run is addressable, cashed:** *"the run is addressable, and its region renders from an id alone, never from in-memory state that a reload destroys."* A reload, a second tab, or a deploy all arrive here.
 
-**`None` covers three cases deliberately** — no such run, another matter's run, and a run id that was never started. Not by comparing afterwards: the thread id is derived from the workspace, so another matter's run does not resolve to a thread at all. The checkpointer itself has no tenancy and cannot be given any, so the isolation has to be in the key.
+**`None` covers three cases deliberately** — no such run, another scope's run, and a run id that was never started. Not by comparing afterwards: the thread id is derived from the scope, so another scope's run does not resolve to a thread at all. The checkpointer itself has no tenancy and cannot be given any, so the isolation has to be in the key.
 
 **State, not replay.** This returns where the run got to; it does not re-emit the events that got it there. A reloading client renders the state and reconnects for what follows, which is enough for obligation 1 and is measurably cheaper than storing and replaying a transcript. If the surface turns out to need replay, the checkpointer keeps the history and `alist` is where that would come from — decided then, with a real surface to measure against, rather than guessed now.
 
@@ -186,37 +186,37 @@ What a run's stored state says became of it.
 
 ### `thread_for(context: 'RunScope', run_id: 'str') -> 'str'`
 
-The checkpointer thread a run lives in, **scoped to its matter**.
+The checkpointer thread a run lives in, **keyed by its scope**.
 
-**The checkpointer has no tenancy and cannot be given any.** `aget_tuple` keys on `thread_id` and `checkpoint_ns` alone — verified in the installed saver — so a bare run id is readable by anybody who can name it. That is exactly the hole T-2.4d closed on the jobs route, where a UUID in a URL was the whole access control and anybody holding a job id read its result across customers.
+**The checkpointer has no tenancy and cannot be given any.** `aget_tuple` keys on `thread_id` and `checkpoint_ns` alone — verified in the installed saver — so a bare run id is readable by anybody who can name it. That is exactly the hole a jobs route can have, where a UUID in a URL is the whole access control and anybody holding a job id reads its result across customers.
 
-So the workspace is part of the key rather than a comparison somebody must remember afterwards. Another matter's run id does not resolve to a thread at all, which makes "not yours" and "no such run" the same non-answer **by construction** — the non-oracle property this codebase applies to documents, jobs, workspaces, sessions and checks, arrived at structurally for once instead of by a check.
+So the scope is part of the key rather than a comparison somebody must remember afterwards. Another scope's run id does not resolve to a thread at all, which makes "not yours" and "no such run" the same non-answer **by construction** — the non-oracle property this codebase applies to documents, jobs, workspaces, sessions and checks, arrived at structurally for once instead of by a check.
 
 The run id stays the PUBLIC identity: it is what `usage_run.correlation_id` joins on and what a client keeps to reconnect. The thread id is ours and never leaves the process.
 
 ### `build_chat_agent(context: 'RunScope', resources: 'Any', settings: 'Any', *, model: 'Any' = None, definition: 'Any', checkpointer: 'Any' = None, store: 'Any' = None, ledger: 'Any' = None) -> 'Any'`
 
-The chat-manager for one run, holding the manifest bound to that run's matter.
+The chat-manager for one run, holding the manifest bound to that run's scope.
 
-**The model is resolved through DeepAgents**, not built here: `AGENT_MODEL_SPEC` plus a registered `ProviderProfile` is the only combination that applies our OpenRouter configuration (T-5a.4a-ii found that `init_chat_model` silently ignores the profile).
+**The model is resolved through DeepAgents**, not built here: `AGENT_MODEL_SPEC` plus a registered `ProviderProfile` is the only combination that applies the OpenRouter configuration (`init_chat_model` silently ignores the profile).
 
 **A `context_schema` is required, not conventional.** It comes from `definition.context_schema` -- the product's own context type, which the substrate never names -- and `start_run` refuses an agent without one, because an agent compiled with `context_schema=None` accepts `context=` and drops it silently.
 
-**The checkpointer defaults to in-memory, which is a real limitation.** `run-contract.md` obligation 1 says a run outlives the view that started it, and an in-memory saver does not outlive the process. A durable checkpointer is T-5a.4c's business, where re-attaching to a run by id is the requirement that forces it; passing one here is how that lands.
+**The checkpointer defaults to in-memory, which is a real limitation.** A run outlives the view that started it, and an in-memory saver does not outlive the process. A durable checkpointer is the caller's to pass, and re-attaching to a run by id is the requirement that forces it.
 
 ### `build_orchestrator(context: 'Any', resources: 'Any', settings: 'Any', *, model: 'Any' = None, tools: 'Any' = None, system_prompt: 'str | None' = None, extra_middleware: 'list | None' = None, definition: 'Any', checkpointer: 'Any' = None, store: 'Any' = None, ledger: 'Any' = None) -> 'Any'`
 
 The planning tier, compiled as an agent in its own right.
 
-**`context_schema` is declared rather than inherited.** A compiled child does receive the parent's context without declaring it — pinned in `test_harness_grounding.py` — but declaring it is what lets this be driven DIRECTLY, which T-5a.12 does and which `start_run` refuses without the schema.
+**`context_schema` is declared rather than inherited.** A compiled child does receive the parent's context without declaring it — pinned in `test_harness_grounding.py` — but declaring it is what lets this be driven DIRECTLY, which the orchestration eval does and which `start_run` refuses without the schema.
 
-`model`, `tools`, `system_prompt` and `extra_middleware` are overridable for tests and evals; **production passes none of them.** `system_prompt` and `extra_middleware` exist so T-5a.12b can run the two orchestration arms through the REAL builder rather than assembling its own agent -- an eval that builds its own would be measuring something the product does not ship.
+`model`, `tools`, `system_prompt` and `extra_middleware` are overridable for tests and evals; **production passes none of them.** `system_prompt` and `extra_middleware` exist so an eval can run the two orchestration arms through the REAL builder rather than assembling its own agent -- an eval that builds its own would be measuring something the product does not ship.
 
 ### `agent_chat_model(settings: 'Any', model_id: 'str') -> 'Any'`
 
 The agent's chat model, built by the engine and bounded by our clocks.
 
-**`model_id` is a PARAMETER (T-7.58).** It used to be read from one product's setting name, in the substrate, so a second product's model could not be reached at all. Which profile to reason with is the product's declaration; bounding the call with our clocks is the substrate's job and is all that is left here.
+**`model_id` is a PARAMETER.** It used to be read from one product's setting name, in the substrate, so a second product's model could not be reached at all. Which profile to reason with is the product's declaration; bounding the call with our clocks is the substrate's job and is all that is left here.
 
 **No `ProviderProfile`, and that removed a trap rather than just a dependency.** The old path handed DeepAgents a spec STRING and registered a profile to configure it. `deepagents._models.resolve_model` returns a pre-built `BaseChatModel` *unchanged* and applies its profile registry only to strings -- including, in its own words, "the OpenAI Responses API default". That default was ON, and with it on OpenRouter returns `object: "response"` and reports **no cost at all**, which is why this module carried `use_responses_api=False`. Passing an object retires the counter-measure with its cause.
 
@@ -226,7 +226,7 @@ The agent's chat model, built by the engine and bounded by our clocks.
 
 Time and trace one agent run, and hand it to `accounting` when it ends.
 
-`accounting` is anything with `collecting()`, `record(run_id=, since=, duration_ms=)` and `trace_metadata` -- the product supplies it (`operations.usage.AgentRunAccounting`). `None` disables recording without disabling the run.
+`accounting` is anything with `collecting()`, `record(run_id=, since=, duration_ms=)` and `trace_metadata` -- the product supplies it. `None` disables recording without disabling the run.
 
 **`collecting()` is opened OUTSIDE the trace and the timer is started before both**, which preserves the original order: the engine work a tool causes is collected through the caller's ContextVar for the whole run, including the setup the trace does not cover.
 
@@ -246,19 +246,19 @@ The run's thread id: its scope and its run id, composed.
 
 **Not the run id alone.** The run id is the PUBLIC identity a client keeps; the thread is ours and never leaves the process, and keying it by scope is what makes a guessed run id from another tenant resolve to nothing by construction.
 
-### `worker_spec(name: 'str', description: 'str', prompt: 'str', tools: 'list', report: 'type', ledger: 'Any' = None, *, retry_on: 'tuple[type[BaseException], ...]' = (), message_for: 'Any' = None, signposts: 'Any' = None, repeatable: 'frozenset[str]' = frozenset(), question_argument: 'dict[str, str] | None' = None, framings: 'tuple[str, ...]' = (), carry_forward: 'Any' = None, read_framing: 'Any' = None) -> 'dict[str, Any]'`
+### `worker_spec(name: 'str', description: 'str', prompt: 'str', tools: 'list', report: 'type', ledger: 'Any' = None, *, retry_on: 'tuple[type[BaseException], ...]' = (), message_for: 'Any' = None, signposts: 'Any' = None, repeatable: 'frozenset[str]' = frozenset(), question_argument: 'dict[str, str] | None' = None, framings: 'tuple[str, ...]' = (), carry_forward: 'Any' = None, read_framing: 'Any' = None, definition: 'Any' = None) -> 'dict[str, Any]'`
 
 A `SubAgent` spec, deliberately the opposite choice from the orchestrator's `CompiledSubAgent`.
 
 A worker has no middleware and no subagents of its own, so letting the parent build it keeps one model resolution and one place that knows how a tier is compiled.
 
-**No `ask_the_user` in any worker's tools**, and that absence is the mechanism (`AR-16`): a prompt saying "do not ask" is a suggestion; a tool the worker was never given is a fact.
+**Pass `definition=`, the product's `AgentDefinition`.** Every policy parameter after `ledger` defaults to something inert, and all of them but `signposts` are fields of that definition (`signposts` is its `prompts`). With a definition, each parameter left at its inert default is taken from it; a value passed explicitly still wins. Without one, a worker runs with no retries, no repeat suppression and no decision recording, and nothing fails to say so.
 
 ### `clarification_tool() -> 'BaseTool'`
 
 A tool whose entire body is a question.
 
-Returned from a factory for symmetry with the manifest's bindings, though it closes over nothing: a clarification has no tenancy to bind, because it touches no matter's data.
+Returned from a factory for symmetry with the manifest's bindings, though it closes over nothing: a clarification has no tenancy to bind, because it touches no scoped data.
 
 ### `translate(namespace: 'Any', mode: 'str', chunk: 'Any') -> 'list[RunEvent]'`
 
@@ -268,7 +268,7 @@ Turn one streamed item into zero or more events for the client.
 
 ### `what_was_finished(result: 'Any') -> 'list[RunEvent]'`
 
-What to tell the client about a run that did not finish (T-5a.15b).
+What to tell the client about a run that did not finish.
 
 **The route already stated the principle and did not honour it for failures:** *"a stream that stops is not a stream that finished. Without a terminal event a client cannot tell a completed answer from a dropped connection."* On a cut-off run the stream simply stopped -- no partial, no explanation, not even the terminating frame -- so it looked exactly like a dropped connection.
 
@@ -284,17 +284,17 @@ The stack, inner-first.
 
 `ToolRetryMiddleware` carries `on_failure="error"` so a failure that exhausts its retries becomes an exception the error middleware can see — rather than a message the model receives without anybody having retried.
 
-**Both arguments are the PRODUCT's and are required (T-7.58).** This imported one product's retry set and `message_for` directly, so the substrate held that product's judgement about what is recoverable -- and a greenfield product retrying a mill feed got the first product's client exception types and its domain errors. **No defaults**, deliberately: a default retry set is one a second product inherits without noticing, and `retry_on` defaulting to anything is how `Exception` creeps back in and a scope violation gets re-attempted with backoff.
+**Both arguments are the PRODUCT's and are required.** This imported one product's retry set and `message_for` directly, so the substrate held that product's judgement about what is recoverable -- and a greenfield product retrying a mill feed got the first product's client exception types and its domain errors. **No defaults**, deliberately: a default retry set is one a second product inherits without noticing, and `retry_on` defaulting to anything is how `Exception` creeps back in and a scope violation gets re-attempted with backoff.
 
 The deadline exceptions are the HARNESS's own (above in this module), because `ADeadlineForOneModelTurn` is what raises them. A product chooses whether its own `retry_on` includes `ModelAttemptTooSlow`; ours does, and deliberately omits `ModelTurnTooSlow`.
 
 ### `dispatched_more_than_once(recording: 'dict[str, Any]') -> 'str | None'`
 
-A worker covering the whole matter, run once per document.
+A worker covering the whole scope, run once per document.
 
 ### `reached_for_the_filesystem(recording: 'dict[str, Any]') -> 'str | None'`
 
-Tried to open the matter's documents as files.
+Tried to open the subject documents as files.
 
 ### `wrote_a_program_for_a_single_call(recording: 'dict[str, Any]') -> 'str | None'`
 

{rag_wright-0.11.0 → rag_wright-0.12.0}/docs/configuration.md

@@ -151,7 +151,8 @@ chat-manager tier, an orchestrator and dispatched workers on Deep Agents, with t
 retries, interrupts and resume, memory, metering and run grading. The product declares an `AgentDefinition` (its
 `ToolSurface`, planning split, workers, a context type satisfying `RunScope`, retry set, model id and `AgentPrompts`)
 and runs it with `start_run` / `resume_run` / `stream_run`; it passes its own checkpointer and memory store. The
-reference is `docs/api/harness.md`, and the `building-an-agent-harness` skill is the practice behind it.
+design reference, with every field a product declares, is [`harness.md`](harness.md); the generated
+signatures are `docs/api/harness.md`, and the `building-an-agent-harness` skill is the practice behind it.
 
 Its configuration is the engine's: the model by engine profile id (the definition's `model_id_for`), tracing by
 `RAG_TRACE_LEVEL` and the Langfuse keys (each agent turn is one generation, labelled `agent-llm`, grouped under the

rag_wright-0.12.0/docs/harness.md

@@ -0,0 +1,268 @@
+# The agent harness: reference design
+
+**What this is.** The design reference for `rag_wright.harness`, the engine's third public tier, for a developer
+building a product's agent on it. It states the idea, every customization point with its API, and where the
+substrate goes quiet rather than failing. It was drafted by RuleWright, the first product built on the tier.
+
+**The tables are generated** from the installed tier by `scripts/build_harness_doc.py`, and the test suite fails
+if they drift (`tests/arch/test_api_docs_current.py`). Edit the prose; regenerate the tables. Today:
+<!-- generated:counts -->
+42 public names; `AgentDefinition` has 15 fields and `AgentPrompts` 11, every one required.
+<!-- /generated -->
+
+**What it is not**, so the documents do not overlap:
+
+| document | answers |
+|---|---|
+| ADR-0139 | *why* the substrate is engine scope, and the shapes agreed when it moved here |
+| [`docs/api/harness.md`](api/harness.md) | the generated signatures and docstrings, exhaustively |
+| `building-an-agent-harness` (skill) | the *practice*: the doors the domain comes through, the build order, the lessons |
+| [`configuration.md`](configuration.md#the-agent-harness-rag_wrightharness) | the tier's environment variables, beside the engine's others |
+| this document | the design, and what a product must declare |
+
+---
+
+## 1. The idea
+
+The substrate runs an agent; it does not know your domain. It owns the parts that are expensive to get right and
+have nothing to do with what your documents contain:
+
+- **Three tiers.** A chat-manager a person talks to, an orchestrator that plans, and dispatched workers. The
+  chat-manager holds a direct read surface, so an unambiguous request never pays for three model calls.
+- **One entry point per lifecycle event**, because runtime context is per invocation: a resume that forgot it
+  would wake every tool with no scope, and the memory namespace would collapse to one global scope.
+- **The failure model**: named retry sets, a per-attempt clock inside the retry and a whole-turn ceiling outside
+  it, call and tool caps, and the rule that a deadline breach is never retried.
+- **Human-in-the-loop under replay.** An interrupt replays the node, so anything before the question runs twice;
+  the protocol is built around that rather than against it.
+- **Memory with a namespace factory that refuses** rather than falling back, run records that recognise a
+  repeated ask, checkpoints, metering, tracing, and run grading against your own rules.
+
+**What it never holds:** your tools, your workers, your prompts, your scope shape, your retry set, your model id,
+your rules, your decision points. Those are the fields of an `AgentDefinition`, and the substrate reads nothing
+else about you.
+
+**The asymmetry worth internalising.** `AgentDefinition` and `AgentPrompts` are **total**: every field is
+required, so an agent cannot be under-declared and the dataclass says so at construction. The per-worker builder
+`worker_spec` is **permissive**, and that is where silence lives (section 6).
+
+---
+
+## 2. `AgentDefinition`: what a product declares
+
+Hand one object to the builders. If a value follows from two others, the substrate derives it rather than
+accepting it: the direct surface is derived from `planning` plus the surface, and the tier split from the
+workers. A derived value crossing the boundary would become a convention the next product can break silently.
+
+<!-- generated:definition -->
+| field | type | what it is for |
+|---|---|---|
+| `surface` | `ToolSurface` | What a product offers an agent run, and the two things the substrate asks about it. |
+| `planning` | `dict[str, str]` | Operation name -> why it needs planning. The reason is kept: a classification without one cannot be revisited. |
+| `workers` | `tuple[Any, ...]` | The worker factories the orchestrator may dispatch. |
+| `context_schema` | `Any` | The type a run's context has, passed to the agent as `context_schema`; it must satisfy `RunScope`. The product's context stays its own: typed ids, its own construction rule, whatever else it wants. |
+| `retry_on` | `tuple[type[BaseException], ...]` | Which exceptions the retry middleware may re-attempt. **Named, never `Exception`** -- the library's default would retry a scope violation, which is re-attempting a leak with backoff. |
+| `message_for` | `Any` | `(error) -> str \| None`: what the model is told about a failure, or `None` to let it surface. |
+| `model_id_for` | `Any` | `(settings) -> str`: the ENGINE model id this product's agent reasons with (a registered profile's key). A model id is configuration: adopting a better model is a new profile and a changed setting. |
+| `prompts` | `AgentPrompts` | Every word this product says to its model (`AgentPrompts`). |
+| `repeatable` | `frozenset[str]` | Tools whose answer is the same twice in one run, so a repeat can be served from the record. |
+| `question_argument` | `dict[str, str]` | `{tool: argument}` -- which argument carries a QUESTION, so two phrasings of one ask are one ask. |
+| `framings` | `tuple[str, ...]` | Tools that FRAME a request rather than answer it, for the framing decision point. |
+| `carry_forward` | `Any` | `(record, tool, content) -> content \| None`, or `None`: the product's chance to amend a result in the light of what this run already found. `None` amends nothing. |
+| `rules` | `tuple[Any, ...]` | The rules this product holds its own runs to. The grading machinery is the substrate's; the rubric is not. |
+| `decision_points` | `tuple[Any, ...]` | The decisions a run of this product takes; the ledger reads each point's option space from here. |
+| `read_framing` | `Any` | `(tool_name, parsed_result) -> {chose, confidence, inputs} \| None`: how this product reads its own framing tool's reply. |
+<!-- /generated -->
+
+---
+
+## 3. `AgentPrompts`: what your agent says
+
+Every word the model reads is the product's. The substrate ships no prompt of its own.
+
+<!-- generated:prompts -->
+| field | type | what it is for |
+|---|---|---|
+| `chat` | `str` | The chat-manager's system prompt: the tier a person talks to. |
+| `orchestrator` | `str` | The orchestrator's, with the product's worker roster already interpolated into it. |
+| `memory` | `str` | One line of guidance about the agent's own memory, shown above whatever is in it. |
+| `skills` | `dict[str, str]` | `{published path: text}` -- the procedures a tier may read when they apply. |
+| `skills_preamble` | `str` | The paragraph that introduces the skills above. |
+| `not_a_filesystem` | `str` | The signpost a wrong filesystem call is answered with by default (it names the product's own tools). |
+| `looking_for_subjects` | `str` | The signpost for a filesystem search plainly hunting the subject documents (a path or pattern ending in one of `subject_file_endings`): it says where those documents ARE, rather than where they are not. |
+| `subject_file_endings` | `tuple[str, ...]` | File extensions that mean "this model is hunting the subject documents it was shown", not notes. |
+| `worker_filesystem_note` | `str` | What a worker is told about its own filesystem. |
+| `orchestrator_description` | `str` | How the orchestrator is described to the chat-manager: the `description` of its compiled subagent, which is what the chat-manager reads when deciding whether to hand a request down. |
+| `label` | `str` | What the model is shown as the SOURCE of the skills: the product's name. |
+<!-- /generated -->
+
+**Two constraints on your text.** `skills_preamble` must contain the three format slots
+`{skills_list}{skills_locations}{skills_load_warnings}` or the build raises. And no prompt may name a scope
+identifier: an injected instruction in an uploaded document can quote back whatever the prompt contains.
+
+---
+
+## 4. The two protocols
+
+<!-- generated:tool_surface -->
+**`ToolSurface`**: What a product offers an agent run, and the two things the substrate asks about it.
+
+| member | shape |
+|---|---|
+| `build` | `(self, context: 'Any', resources: 'Any', *, only: 'Any' = None) -> 'list[Any]'` |
+| `exposed_names` | a property |
+<!-- /generated -->
+
+<!-- generated:run_scope -->
+**`RunScope`**: The only thing the substrate needs to know about a run's tenancy.
+
+| member | shape |
+|---|---|
+| `scope` | `tuple[str, ...]` |
+| `shared_scope` | `tuple[str, ...] \| None` |
+<!-- /generated -->
+
+**`scope` is opaque to the substrate, and that is the point.** It keys the memory namespaces and the run's
+thread; a two-level product and a three-level one differ only in what they put in the tuple. `shared_scope` is
+the one wider scope a run may promote a learned fact into, and the substrate enforces that it is a strict,
+non-empty prefix of `scope`, so a sideways scope, the root, and anything outside the run's own chain are
+unrepresentable rather than discouraged. The memory mounts are `/memories/scope/`, `/memories/shared/` and the
+read-only `/memories/product/` (ADR-0139 addendum).
+
+---
+
+## 5. Entry points and builders
+
+Runs (`outcome` is read with `read_run`):
+
+<!-- generated:runs -->
+| name | what it does |
+|---|---|
+| `start_run` | Begin a run under `context`, and supply it to every invocation. |
+| `resume_run` | Answer a run that paused for a person, and re-supply its context. |
+| `stream_run` | Begin a run and yield `(run_id, namespace, mode, chunk)` as it happens. |
+| `read_run` | Where a run got to, by its id alone — or `None` if it is not this scope's. |
+<!-- /generated -->
+
+Builders:
+
+<!-- generated:builders -->
+| name | what it does |
+|---|---|
+| `build_chat_agent` | The chat-manager for one run, holding the manifest bound to that run's scope. |
+| `build_orchestrator` | The planning tier, compiled as an agent in its own right. |
+| `worker_spec` | A `SubAgent` spec, deliberately the opposite choice from the orchestrator's `CompiledSubAgent`. |
+<!-- /generated -->
+
+---
+
+## 6. Where the substrate goes quiet: build workers with `definition=`
+
+`worker_spec` takes a worker's policy as optional parameters, and each defaults to something inert. The defaults
+are right for a substrate that knows no product: it will not invent a retry set, a repeat-suppression list or a
+decision registry for you. They also mean that a worker built without them is quietly less capable, with nothing
+going red: no retries, every failure surfacing, a filesystem signpost naming no tool, nothing repeat-suppressed,
+no decision recording. The first product on the tier shipped all of its workers in that state with its full test
+suite green, and found it by reading the call sites.
+
+Every one of those values except the ledger is already in the `AgentDefinition` you declared. **So pass the
+definition**, and `worker_spec` takes each parameter you left at its default from it; a value you pass explicitly
+still wins:
+
+<!-- generated:worker_spec -->
+| parameter | inert default | with `definition=`, taken from |
+|---|---|---|
+| `ledger` | `None` | not from the definition: the run's, passed down by the builder |
+| `retry_on` | `()` | `definition.retry_on` |
+| `message_for` | `None` | `definition.message_for` |
+| `signposts` | `None` | `definition.prompts` |
+| `repeatable` | `frozenset()` | `definition.repeatable` |
+| `question_argument` | `None` | `definition.question_argument` |
+| `framings` | `()` | `definition.framings` |
+| `carry_forward` | `None` | `definition.carry_forward` |
+| `read_framing` | `None` | `definition.read_framing` |
+<!-- /generated -->
+
+```python
+from rag_wright.harness import worker_spec
+
+def my_worker(context, resources, ledger=None):
+    return worker_spec("my_worker", "What it does, for the orchestrator.", MY_WORKER_PROMPT,
+                       MY_SURFACE.build(context, resources), MyWorkerReport,
+                       ledger=ledger, definition=MY_DEFINITION)
+```
+
+**If you set the values yourself, guard the consequence, not the call.** Build a real spec for each of your
+workers and interrogate the middleware it produced: a non-empty retry set, a run record whose repeatable set is
+yours, your question map, your framings, signposts that are not `None`. Then prove the guard by removing the
+policy from one worker and watching it fail; a guard that has never failed is untested. The engine's own version
+is `test_A_WORKER_TAKES_ITS_POLICY_FROM_THE_DEFINITION_IT_IS_GIVEN` in `tests/harness/test_greenfield_conformance.py`.
+
+**A minimal composition**, every name taken from the tables above:
+
+```python
+from rag_wright.harness import AgentDefinition, AgentPrompts, build_chat_agent, start_run
+
+definition = AgentDefinition(
+    surface=MyToolSurface(),             # build(context, resources, only=None) + exposed_names
+    planning={"my.long_operation": "it fans out over the whole corpus"},
+    workers=(my_worker,),                # factories: (context, resources, ledger=None) -> worker_spec(...)
+    context_schema=MyContext,            # satisfies RunScope: scope + shared_scope
+    retry_on=(MyUpstreamOffline,),       # named, never Exception
+    message_for=my_message_for,          # (error) -> str | None; None lets it surface
+    model_id_for=lambda settings: settings.my_agent_model,
+    prompts=AgentPrompts(...),           # every field, every word yours
+    repeatable=frozenset({"my.read_one"}),
+    question_argument={"my.ask": "question"},
+    framings=("my.frame_the_request",),
+    carry_forward=None,                  # a real answer: amend nothing
+    rules=(my_rule,),
+    decision_points=(my_point,),
+    read_framing=my_read_framing,
+)
+
+agent = build_chat_agent(context, resources, settings, definition=definition,
+                         checkpointer=my_checkpointer, store=my_store)
+result = await start_run(agent, context, message=question, settings=settings,
+                         skills=definition.prompts.skills)
+```
+
+**Note what is not in that call**: no tier split, no direct surface, no worker-to-operation map; the substrate
+derives each from what you declared. `start_run` takes `skills` explicitly because seeding them is the product's
+decision: a tier advertised a skill it cannot read spends a `read_file` finding out.
+
+---
+
+## 7. Configuration is the engine's
+
+The tier reads the process environment, not your settings object:
+
+| variable | effect |
+|---|---|
+| `RAG_TRACE_LEVEL` | `off` / `generations` / `verbose`. `verbose` sends prompts, which are customer content |
+| `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` / `LANGFUSE_HOST` | a level alone traces nothing; the keys are needed too |
+| `RAG_QUESTION_ENCODER` | `off` stops the harness embedding tool questions to recognise a repeated ask |
+| `OPENROUTER_API_KEY`, or the profile's `api_key_env` | the model credentials, read where the engine builds the model |
+
+**Put them in the environment before anything builds an agent**: at application startup, and in any script, eval
+or test that builds a real model. A product that forgets gets the model client's *"Missing credentials"* error
+with nothing naming the cause. If a wrapper of yours used to export them as a side effect and stops being on the
+path, nothing exports them: when a seam stops being called, check what it did besides forwarding.
+
+---
+
+## 8. Verifying your own composition
+
+The order matters:
+
+1. **A second product, about 200 lines, hermetic**: a fake product in an unrelated domain that implements the
+   seams and builds a real agent. Write it before your seams are final, so each one is designed against an outside
+   implementer rather than audited afterwards. It is the only instrument that measures reusability; import counts
+   measure decoupling, which is a different property. The engine's is the fabric product in
+   `tests/harness/test_greenfield_conformance.py`, whose scope is three parts deep.
+2. **Guards on the consequence** of each permissive default (section 6), each proved by planting.
+3. **Your own rules and decision points**, graded by the substrate against the registries you declared.
+
+**The trap:** a conformance test that hands the substrate your own context type while asserting that a different
+product works proves nothing about a product whose scope has a different depth. When a seam changes, change the
+fake product first.

{rag_wright-0.11.0 → rag_wright-0.12.0}/docs/specs/public-surface/plan.md

@@ -115,3 +115,4 @@ in two at the PS-6 gate so the store rewrite is its own visible task. One task,
 | PS-40 | Prepare the engine for a greenfield product (TexWright, the first product built after de-domaining): (a) the product-starter templates corrected for 0.10.0 (the harness ships; the floor example; the skill lists); (b) RuleWright's generic `building-a-product-backend` and `building-a-product-frontend` skills graduate into the shipped skills (reviewed against 0.10.0: the harness is the engine's tier, a new domain's composites are its own pack's capabilities, an engine gap is an engine request), as `building-an-agent-harness` did; (c) a new shipped skill that turns a product's high-level spec into its low-level SPEC mapped to the engine's APIs, skills and docs, layered on the global `spec-driven-development` | the shipped-skills, doc-reference and vocabulary guards green; the wheel build ships all three skills; the templates fill with no stale line | done 2026-10-14 (templates corrected; backend and front-end skills graduated from RuleWright with 0.10.0 corrections; `specifying-a-product-on-the-engine` written; all three linked and shipped in the wheel) |
 | PS-41 | Audit the engine-authored product-developer skills and the domain-adaptation guide for omissions a greenfield product hits (TexWright as the test case), and fix them: the specifying skill (capability catalog + definition-of-done requirement, models, the operations registry and parity, the agent's guardrails, settled data semantics, confirming a primitive is public, a live reconciliation); the consumer skill (three tiers, the harness first, specify first, client data, the surface snapshot over all tiers); capability authoring (product homes and slug prefixes, the eval in the definition of done, the harness for agents); ingestion (images and scans, a model-backed extractor as a closure, interpretations as records, per-sheet roles, multi-row records, re-ingest under G8, registering the pipeline, field-level accuracy); evals (gold from provided data, field-level ingestion accuracy, judged gold, agent behavior classes); the backend skill (the operations registry, parity, read-only agent tools); the guide (step 0 specify, the bridge pack for an existing ontology, G24: no public hybrid search, the false 'compose hybrid search by import' claim removed, a `uv pip` fixed) | the doc-reference, shipped-skills and ingestion-example guards green | done 2026-10-14 |
 | PS-42 | Register only the engine capabilities a product uses, by slug (TexWright T-0.2 finding): the product-starter templates, the consumer skill and the domain-adaptation docs showed a blanket `for m in engine_capabilities(): register_capability(m)`, which puts unused capabilities into `discover()`'s ranking pool; now by slug, failing loudly when a used slug is no longer offered | the doc-reference and shipped-skills guards green | done 2026-10-14 |
+| PS-43 | The harness tier's design reference and its quiet defaults (RuleWright's 2026-10-15 note): `docs/harness.md` taken in from RuleWright's draft, its tables generated from the live tier by `scripts/build_harness_doc.py`; `worker_spec(definition=)` fills the seven policy parameters (and the signposts) a worker otherwise left inert from the product's `AgentDefinition`, explicit arguments winning; the harness source's docstrings and comments cleared of the originating product's vocabulary, task, requirement and ADR ids, with a guard; two `AgentPrompts` fields described; the agent-harness skill's 'Four declared facts' corrected to fifteen | the product-text guard, the `definition=` conformance tests and the harness-design drift test green | done 2026-10-15 |

rag_wright-0.12.0/docs/specs/public-surface/rulewright-migration-0.11.0.md

@@ -0,0 +1,22 @@
+# RuleWright: moving to rag-wright 0.11
+
+What 0.11.0 (released 2026-10-15: PyPI and GitHub release `0.11.0`) changes for RuleWright. Do the 0.10 guide
+first. Nothing here is edited from the engine repo, and nothing in 0.11.0 breaks an existing call.
+
+## 1. The product-building skills ship in the wheel (PS-40)
+
+`building-a-product-backend`, `building-a-product-frontend` and `specifying-a-product-on-the-engine` are engine
+skills now, with the 0.10.0 corrections. Retire `generic-product-dev-skills/` and `tests/test_product_dev_skills.py`
+(answered in our note of 2026-10-15); link any you want from the installed engine (ADR-0134).
+
+## 2. Register only the engine capabilities you use (PS-42, optional)
+
+The docs now register engine capabilities by slug rather than all of them:
+`for m in engine_capabilities(): if m.slug in USED: register_capability(m)`, raising when a slug in `USED` is no
+longer offered. Registering every one also puts the ones you never call into `discover()`'s ranking pool.
+`packs/contracts/pack.py` (`(*engine_capabilities(), *CONTRACT_SPECS)`) and `register_engine_capabilities()` in
+`engine/seam.py` register all of them; that still works. Change it if your agent plans over `discover()`.
+
+## Verify
+
+Your fast and db suites green on `>=0.11.0`; bump the floor. No harness name changed.