@tangle-network/agent-knowledge 1.8.0 → 1.10.0

package/dist/memory/index.d.ts

@@ -1,4 +1,4 @@
-import { S as SourceRecord } from '../types-BEDGlXB-.js';
+import { S as SourceRecord } from '../types-C17sAROL.js';
 import { z } from 'zod';
 
 type AgentMemoryKind = 'message' | 'entity' | 'fact' | 'preference' | 'observation' | 'reasoning-trace';

package/dist/{types-BEDGlXB-.d.ts → types-C17sAROL.d.ts}

@@ -170,4 +170,4 @@ interface KnowledgeRelease {
     metadata?: Record<string, unknown>;
 }
 
-export type { ClaimRef as C, KnowledgeGraphEdge as K, SourceRecord as S, KnowledgeGraphNode as a, KnowledgeGraph as b, KnowledgeIndex as c, KnowledgeSearchResult as d, KnowledgeEventType as e, KnowledgeEvent as f, KnowledgePage as g, KnowledgeLintFinding as h, KnowledgeWriteBlock as i, KnowledgeClaim as j, KnowledgeRelease as k, SourceRegistry as l, KnowledgeWriteParseResult as m, KnowledgeBaseCandidate as n, KnowledgeId as o, KnowledgePolicy as p, KnowledgeRelation as q, KnowledgeUnit as r, SourceAnchor as s };
+export type { ClaimRef as C, KnowledgeGraphEdge as K, SourceRecord as S, KnowledgeGraphNode as a, KnowledgeGraph as b, KnowledgeIndex as c, KnowledgeSearchResult as d, SourceRegistry as e, KnowledgeEvent as f, KnowledgeEventType as g, KnowledgePage as h, KnowledgeLintFinding as i, KnowledgeWriteBlock as j, KnowledgeClaim as k, KnowledgeRelease as l, KnowledgeWriteParseResult as m, KnowledgeBaseCandidate as n, KnowledgeId as o, KnowledgePolicy as p, KnowledgeRelation as q, KnowledgeUnit as r, SourceAnchor as s };

package/dist/viz/index.d.ts

@@ -1,4 +1,4 @@
-import { K as KnowledgeGraphEdge, a as KnowledgeGraphNode, b as KnowledgeGraph } from '../types-BEDGlXB-.js';
+import { K as KnowledgeGraphEdge, a as KnowledgeGraphNode, b as KnowledgeGraph } from '../types-C17sAROL.js';
 
 interface KnowledgeVizNode extends KnowledgeGraphNode {
     degree: number;

package/docs/results/adaptive.md

@@ -0,0 +1,120 @@
+# Adaptive topology: spend the LLM verifier only when it pays
+
+The cost/quality A/B (`docs/results/cost-quality.md`) found the LLM relevance
+verifier's cleanliness win is dominated by **de-duplication** — which a
+deterministic content-hash / canonical-URL check captures at ~none of the LLM
+premium — and that an LLM check only earns its dollar on the off-scope tail. The
+production move it named was: do the cheap deterministic work first, reserve the
+LLM for the ambiguous tail. `createAdaptiveResearchDriver`
+(`src/adaptive-driver.ts`) is that driver, and this is its measurement.
+
+Per candidate source the adaptive driver runs three stages, cheapest first,
+stopping at the first that decides:
+
+1. **Dedup ($0).** Reject a source whose canonical URL (scheme/`www`/trailing
+   slash/tracking params stripped) or normalized-text content hash matches one
+   already accepted this round or in the KB.
+2. **Heuristic triage ($0).** Classify a unique survivor with host/title/length
+   signals only: an authoritative host (arxiv, `*.edu`, `*.gov`, official docs,
+   github, …) with a substantial body is **kept**; an obvious spam/listicle
+   title or a too-thin body is **dropped**; everything else is **ambiguous**.
+3. **LLM escalation ($).** Only ambiguous survivors reach the shipped LLM
+   relevance verifier (`createVerifyingResearchDriver`) — one call each.
+
+## Live frontier, n=5 topics (glm-5.2)
+
+Real web-research worker fetches each topic once; the same fetched proposals
+(plus one planted tracking-decorated mirror of the first source, so the dedup
+stage has a real duplicate to catch) are gated through all three drivers. Cost
+is the per-arm `RouterClient.usage()` diff (#36). Total spend for the run:
+**$0.033**.
+
+| topic | fetched | single admit | full-LLM admit / calls / $ | adaptive admit / LLM calls / $ |
+|---|---|---|---|---|
+| self-speculative decoding | 3 | 3 | 1 / 3 / $0.0027 | 2 / **0** / **$0.0000** |
+| rotary position embeddings | 3 | 3 | 1 / 3 / $0.0031 | 2 / **0** / **$0.0000** |
+| grouped-query attention | 7 | 7 | 3 / 7 / $0.0072 | 6 / 3 / $0.0030 |
+| KV-cache quantization | 5 | 5 | 3 / 5 / $0.0052 | 4 / **0** / **$0.0000** |
+| LoRA fine-tuning | 7 | 7 | 4 / 7 / $0.0079 | 6 / 3 / $0.0037 |
+| **total** | **25** | **25** | **12 / 25 / $0.0261** | **20 / 6 / $0.0068** |
+
+**Cost.** Adaptive cuts LLM verifier calls **76%** (25 → 6) and dollars **74%**
+($0.0261 → $0.0068). On 3 of the 5 topics it spent **zero** LLM calls — every
+unique survivor was on an authoritative host, so the $0 stages decided
+everything.
+
+## The honest reading: adaptive is a frontier POINT, not a free lunch
+
+Admitted-source counts (lower = cleaner KB): **single 25, adaptive 20,
+full-LLM 12**. Adaptive sits **between** the two:
+
+- It removes **5 of the 13 sources** the full-LLM judge rejects that the
+  single-agent loop keeps (every one of them a real duplicate caught by the $0
+  dedup stage — exactly the de-dup-dominated win the cost/quality result
+  predicted).
+- It does **NOT** match full-LLM cleanliness. The remaining 8 sources full-LLM
+  rejects, adaptive keeps. The cause is structural and visible in the trace: on
+  this topic set every non-duplicate survivor landed on an authoritative host
+  (arxiv / github / official docs), so the heuristic **kept** it without ever
+  asking the LLM — and the LLM, when full-LLM did ask it, judged several of
+  those same authoritative pages not-quite-on-topic and dropped them. The host
+  prior is coarser than the relevance judge.
+
+So the frontier tradeoff is concrete: **adaptive recovers the deterministic
+de-dup half of full-LLM's cleanliness for ~26% of full-LLM's dollars, and gives
+up the relevance-judgment half.** Whether that is the right point depends on the
+cost of a kept-but-marginal source. If a slightly-off-topic authoritative page
+is cheap to carry, adaptive dominates. If every admitted source must clear a
+relevance bar, the host heuristic is too permissive and you want the full LLM —
+or a tightened heuristic.
+
+## Where the heuristic is weak — stated plainly
+
+The escalation count is the diagnostic. On 3 of 5 topics it was **zero**: the
+heuristic never deferred to the LLM, so on those topics adaptive is a
+**pure host/title/length rule**, and its cleanliness is exactly that rule's
+cleanliness — no smarter than "trust arxiv/github, drop spam." That is fine when
+the worker's sources are dominated by authoritative hosts (as here), but it
+means the LLM's relevance judgment is contributing nothing on those topics, by
+construction. The two topics where adaptive *did* escalate (grouped-query
+attention, LoRA) are where some survivors were on unknown hosts — and there the
+3 LLM calls per topic are the off-scope tail the verifier is actually for.
+
+The heuristic would mis-route in two directions a richer worker would expose,
+neither seen on this authoritative-host-heavy set:
+
+- **False keep:** an authoritative-host page that is off-topic or low-value
+  (an arxiv paper on an unrelated subject) is kept without the LLM ever seeing
+  it. The host prior cannot catch this; only the relevance judge can.
+- **False drop:** a genuinely good source on an unknown blog/host with a
+  spam-shaped title, or under the 400-char body floor, is dropped before the LLM
+  could rescue it.
+
+## What this changes
+
+The deployable recommendation from the cost/quality result was "deterministic
+dedup first, reserve the LLM for the tail." This driver ships that and the
+measurement confirms the **cost** half cleanly (76% fewer calls, 74% cheaper)
+and qualifies the **quality** half honestly: adaptive captures the de-dup
+cleanliness (the dominant, free win) but not the LLM's relevance cleanliness,
+because the host heuristic resolves authoritative survivors without asking. For
+a worker whose sources are mostly authoritative, adaptive is the right frontier
+point. For one whose junk is on-topic-looking pages on unknown hosts, the
+ambiguous tail grows and adaptive converges toward full-LLM cost — which is the
+correct behavior: it pays for the LLM exactly when the cheap signals can't
+decide.
+
+## Run it
+
+```
+# offline (controlled wiring + escalates-only-ambiguous proof, no creds)
+pnpm exec vitest run tests/loops/adaptive-ab.test.ts
+
+# live three-topology frontier (needs TANGLE_API_KEY with glm-5.2 credits)
+AGENT_KNOWLEDGE_LIVE=1 \
+ADAPTIVE_LIVE_GOALS="self-speculative decoding|rotary position embeddings|grouped-query attention|KV-cache quantization|LoRA fine-tuning" \
+pnpm exec vitest run tests/loops/adaptive-ab.test.ts -t "three-topology"
+```
+
+A cheap one-call glm-5.2 smoke gates the multi-topic burn (fails fast if the key
+or the reasoning-token floor is broken) before any dollars are spent.

package/docs/results/claim-grounding.md

@@ -0,0 +1,97 @@
+# Claim-grounding: the band where the verifier earns its dollar
+
+`docs/results/cost-quality.md` found the relevance verifier's cleanliness win is
+**dominated by de-duplication** — a deterministic content-hash captures most of it
+at ~none of the LLM premium. So the open question was: is there an error band where
+a verifier earns its cost — something a hash AND a relevance judge both miss?
+
+**Yes: misattributed citations.** A source that is on-topic, unique, and real, but
+whose cited CLAIM does not appear in the page (the LLM wrote a plausible sentence
+and hung a real URL off it). De-dup passes it (it's unique). A relevance judge
+passes it (the page is on-topic). Only checking the claim against the fetched text
+catches it — and that check is **deterministic text presence, $0 inference**.
+
+## The mode
+
+Each proposed source now carries the specific claim it is cited for
+(`withCitedClaim` → `metadata.citedClaim`). The verifier
+(`createClaimGroundingVerifier`) runs `groundClaimInText(claim, pageText)` over the
+`htmlToText` output of the page the worker actually fetched — verbatim, normalized
+(punctuation/whitespace-insensitive), or a ≥70% content-word overlap close
+paraphrase. A claim that isn't present is rejected as **misattributed**. The oracle
+is text presence, not a model call, so it composes with the LLM relevance verifier
+(reject off-topic AND misattributed) or runs alone at zero inference cost.
+
+## Live A/B (glm-5.2, real web fetch, planted misattribution band)
+
+Real worker (glm-5.2 query-gen → live `/v1/search` → `politeFetch` → `htmlToText`)
+fetches the sources once per topic; we then plant ONE misattribution per topic (real
+fetched page + a deliberately-wrong claim) and run three verifier arms over the SAME
+proposals. Cost diffed per arm with the #36 `RouterClient.usage()` instrumentation.
+
+| n=5 topics | misattributions caught | marginal $ | $/topic | per-$ caught |
+|---|---|---|---|---|
+| no-verifier | 0 / 5 | $0.0000 | — | — |
+| relevance (LLM judge) | **4 / 5** | $0.0157 | ~$0.0031 | 254 |
+| claim-grounding (text) | **5 / 5** | **$0.0000** | $0 | ∞ |
+
+Per-topic (caught relevance / grounding): self-speculative decoding 1/1, rotary
+position embeddings 1/1, grouped-query attention 1/1, **KV-cache quantization 0/1**,
+LoRA 1/1. (An earlier 3-topic run missed self-speculative decoding instead — the
+miss moves around; it is not a fixed topic.)
+
+**Reading.** Claim-grounding catches every misattribution at **$0**; the relevance
+judge catches most but **misses one in five at ~$0.003/topic**. The miss is the
+point: the relevance verifier only ever sees the page text, never the cited claim,
+so it is *structurally blind* to misattribution. It catches one only by accident —
+when the fabricated claim happens to also make the page read off-topic
+(e.g. a "12-billion-parameter draft transformer" claim on a rotary-embeddings page).
+When the fabrication stays on-topic (the KV-cache case), the judge waves it through.
+
+So on THIS band the verifier-per-dollar comparison inverts the cost/quality result:
+there, the LLM verifier bought a dedup-shaped gain a free hash already captures —
+expensive for what a cheap rule does. Here the cheap, deterministic check
+**dominates** the expensive judge: it catches strictly more (5/5 vs 4/5) at strictly
+less ($0 vs $0.0157). The verifier earns its dollar on misattribution; it does not on
+de-duplication.
+
+## Why this is a real correctable band (not dedup, not relevance)
+
+- **Not de-duplication.** Every planted source has a unique URL and unique text; a
+  content-hash / canonical-URL dedup keeps all of them.
+- **Not generic relevance.** Every planted source is on-topic; the relevance judge
+  (and the offline relevance stand-in) accept them. The error is in the *claim*, not
+  the *topic*.
+- **Executable ground truth.** The check is presence/close-paraphrase of the claim
+  in the fetched text — deployable in production with no oracle and no model call.
+
+The offline arm proves the floor with a controlled 4-source pool (2 grounded, 2
+misattributed): claim-grounding admits **0/2** misattributions and keeps **2/2**
+grounded sources, while relevance and no-verifier both admit **2/2**.
+
+## Threats to validity
+
+- **n=5 topics, 1 misattribution each.** The direction (grounding ≥ relevance caught,
+  at ≤ cost) is asserted in the test on every run; the magnitude is small-n. The
+  relevance miss-rate (1/5 here, 1/3 earlier) is an existence proof of the blind
+  spot, not a calibrated rate.
+- **Planted misattributions, not naturally-occurring ones.** Like the cost/quality
+  offline floor, the misattribution is injected so the band is measurable. It models
+  the real LLM citation-fabrication failure but does not measure its base rate in the
+  wild — that needs a corpus of model-written citations checked by hand.
+- **The grounding oracle is conservative.** A real paraphrase whose inflected words
+  differ from the page ("drafts" vs "draft") can score below 0.7 and be rejected —
+  a false-positive misattribution flag. `minOverlap` tunes this; the worker should
+  cite the page's own key terms (the `createClaimDecorator` extractor is told to).
+
+## Run it
+
+```bash
+# offline floor (no creds)
+pnpm exec vitest run tests/loops/claim-grounding-ab.test.ts -t "offline"
+
+# live A/B (creds-gated). A cheap glm-5.2 smoke runs BEFORE the multi-topic burn.
+AGENT_KNOWLEDGE_LIVE=1 TANGLE_API_KEY=… \
+  CLAIM_GROUNDING_LIVE_GOALS='self-speculative decoding|rotary position embeddings|grouped-query attention|KV-cache quantization|LoRA' \
+  pnpm exec vitest run tests/loops/claim-grounding-ab.test.ts -t "three verifier arms"
+```

package/docs/results/cost-quality.md

@@ -0,0 +1,27 @@
+# Cost/quality: the two-agent loop's inference premium
+
+Live 9-topic A/B (glm-5.2, budget B ≤ 4 passes/arm), measured per arm with the
+router-client instrumentation. The original A/B reported only admitted-sources at
+"equal passes" — which charged the two-agent verify step as one pass while it is
+actually N `verifySource` LLM calls. Pricing the calls shows what that hid.
+
+| per topic (mean) | two-agent | single-agent | ratio |
+|---|---|---|---|
+| LLM chat calls | 5.4 | 1.0 | ~5.4× |
+| tokens (in+out) | ~4,900 | ~530 | ~9× |
+| cost (USD) | ~$0.0072 | ~$0.0013 | ~5.5× |
+| latency (wall) | ~37 s | ~11 s | ~3.4× |
+| cleanliness Δ (single − two admitted) | — | — | +1.56, 95% CI [0.33, 2.67] |
+
+Per-topic Δ (single − two admitted) this run: self-speculative decoding +4,
+grouped-query attention 0, rotary position embeddings +1, KV-cache quantization
+**−1**, LoRA +4, ring attention +2, constitutional AI +3, transformer +2, gradient
+descent **−1**. Coverage 1.00 every topic, both arms.
+
+**Reading.** The verifier buys ~1.5–2.7 fewer junk sources for roughly **5× the
+dollars, 9× the tokens, and 3× the latency** — and on two topics it admitted *more*
+than the single agent (the cleanliness signal is real but noisier than the +2.3 /
++2.7 of earlier runs). The cleanliness gain is dominated by de-duplication, so the
+honest production move is a deterministic content-hash / canonical-URL dedup, which
+captures most of the cleanliness at ~none of this premium; reserve an LLM check for
+the off-scope tail. This is the cost half the "equal passes" framing left out.

package/docs/supervisor-profiles.md

@@ -0,0 +1,295 @@
+# Supervisor prompt + agent-profile ideas
+
+Four `AgentProfile` sketches for the research/knowledge domain — a **researcher worker**, a
+**verifier driver**, a **research supervisor**, and a thin **dedup-first verifier** — plus a port
+plan for the existing `~/code/supervisor-lab`.
+
+This is a *design doc*, not shipped code. Each sketch names the real primitive it composes (in
+`agent-knowledge` or `supervisor-lab`) so building it is "assemble", not "invent". Where a primitive
+already exists, the sketch says so and points at it — we extend, we do not fork.
+
+## What we borrowed from emilkowalski/skills
+
+[`emilkowalski/skills`](https://github.com/emilkowalski/skills) is a small pack of Claude skills for
+design engineering (`emil-design-eng`, `review-animations`). It is not about agents, but its *skill
+shape* is worth copying, and one structural choice maps directly onto our verifier:
+
+- **Tight frontmatter, two fields.** `name` + a one-paragraph `description` that says *when* to
+  invoke. Nothing else. Our profiles' `description` should read the same way: a trigger, not a
+  feature list.
+- **Terse non-negotiable rules over prose.** `review-animations` is "The Ten Non-Negotiable
+  Standards" — numbered, imperative, absolute ("Animate `transform` and `opacity` only").
+  A worker system prompt is more legible as a short numbered contract than as paragraphs.
+- **"Default to flagging; approval is earned."** The review skill is *adversarial by posture* — it
+  exists to reject, and its output is a findings table + a verdict. This is exactly the right posture
+  for a verifier, and it informs the dedup point below.
+- **`disable-model-invocation: true` on the reviewer.** The review skill is not auto-invoked by the
+  model; it is routed in deliberately. Our verifier is the same: a driver *calls* it at a gate, the
+  worker never invokes it on a whim.
+- **Cheap because narrow.** Each skill does one thing. The review skill carries no design *generation*
+  ability — it only judges. That separation (generate vs. judge) is the whole reason the judge can be
+  thin.
+
+### The dedup insight (why the verifier is a thin profile, not a heavy one)
+
+`review-animations` is mostly a deduplicated rule set: the craft knowledge lives in `emil-design-eng`,
+and the reviewer is a thin lens that *applies the same rules* to a diff. It does not re-derive taste;
+it checks against a list.
+
+Our verifier is the same. In this repo the "rules" are already deterministic code:
+
+- `createResearcherValidator` (`src/profiles/researcher.ts:235`) — citation-density floor + namespace
+  check, **no LLM**.
+- the `lint` / `validate --strict` CLI path — citation, link, and schema checks over markdown, **no
+  LLM** (`docs/architecture.md`, "The CLI ... does not call an LLM").
+- `assessAuthoredProfile` / `profileRichnessFinding` in supervisor-lab's bench — a deterministic
+  "is this profile a stub" gate.
+
+So the verifier profile should be **thin and cheap**: it mostly *calls the deterministic checker and
+reports the verdict*, escalating to an LLM judge **only** for the residual a deterministic check can't
+cover (does the cited source actually support the claim — a semantic check). A heavy verifier that
+re-reasons every claim from scratch is wasted spend: the dedup already happened in the validator.
+**Spend the model budget on the worker (generation is hard); keep the verifier a cheap lens (judging
+against a list is easy).**
+
+---
+
+## Sketch 1 — `grounded-researcher` (leaf worker)
+
+**Status: already exists, twice.** `agent-knowledge` ships `researcherProfile()`
+(`src/profiles/researcher.ts:130`) — `tools: { web_search, fs, shell }`, propose-don't-apply, with a
+matching `createResearcherValidator`. `supervisor-lab` ships
+`profiles/research/grounded-researcher.ts` (web-search MCP, search→cite→synthesize). This sketch is
+the **canonical shape both converge on** — build new only if you need a variant; otherwise
+`mergeAgentProfiles` over the existing one.
+
+**When to use:** one self-contained research question, spawned one-per-sub-topic by a driver. The
+leaf — it does not spawn.
+
+**Tools / resources:** `web_search` (the `tcloud mcp` stdio server, or the `web_search: true` tool),
+`fs` for writing the cited dossier, `shell` for `agent-knowledge index/lint`.
+
+**System prompt (the contract):**
+
+```
+You are a grounded research WORKER. You answer ONE question, and every load-bearing
+claim is traceable to a real source you actually retrieved.
+
+THE LOOP — search → cite → synthesize:
+1. SEARCH   issue multiple focused web_search queries; never stop at the first hit.
+2. CITE     attach every load-bearing claim to its source (title + url/identifier).
+            A claim you cannot cite is a claim you do NOT make. Never invent a source.
+3. SYNTH    lead with the answer; note where sources agree, conflict, or leave a gap.
+
+NON-NEGOTIABLE:
+- Honest "the evidence is thin / conflicting" beats a confident hallucination.
+- Citation density floor is enforced downstream — under-citing is a hard fail, not a warning.
+- You are the LEAF. You do not spawn sub-workers.
+
+Return your cited synthesis as the settled output (a structured object if a schema was passed).
+```
+
+**Why this shape:** the validator (`createResearcherValidator`) checks citation density and namespace
+*deterministically*, so the prompt's job is only to make the worker *produce* citable output — the
+checking is not the worker's job. That split is what keeps the verifier cheap (Sketch 4).
+
+---
+
+## Sketch 2 — `verifier-driver` (the gate, NOT the judge)
+
+**Status: composes existing primitives.** This is `agent-runtime`'s `verify({ implement, verifier })`
+combinator (`src/runtime/personify/combinators.ts:333`) wired to a research worker + a thin checker.
+**Do not write a new verify-loop** — the 2-node implement→gate already exists.
+
+**When to use:** when "did the worker actually deliver" must be proven before the result counts —
+i.e. always, on a graded run. A driver that runs ONE worker behind ONE gate.
+
+**Tools:** the coordination verbs (`spawn_agent`, `await_event`, `steer_agent`) over a `Scope`, plus
+the ability to call the deterministic checker (`agent-knowledge lint` / `createResearcherValidator`).
+
+**System prompt (the contract):**
+
+```
+You are a VERIFIER-DRIVER. You spawn ONE research worker, then you GATE its output —
+you never accept the worker's own say-so.
+
+THE GATE — generate → check → decide:
+1. SPAWN     author a grounded-researcher worker for the question and spawn it.
+2. AWAIT     pull its settled output (await_event). Read the REAL output, not a summary.
+3. CHECK     run the DETERMINISTIC checker first (citation density, namespace, lint,
+             schema). This is cheap and catches most failures. Only if it PASSES do you
+             escalate to the one semantic question a checker can't answer:
+             "does each cited source actually support the claim it's attached to?"
+4. DECIDE    PASS → settle. FAIL → steer_agent with the SPECIFIC gap named
+             ("claim X cites source Y but Y does not say X"), or respawn a sharper worker.
+
+NON-NEGOTIABLE:
+- selector != judge. You GATE (pass/fail against a contract); you do not re-rank or
+  rewrite the worker's content yourself.
+- "Settled a file" is not delivery. The deterministic check passing is delivery.
+- Default to FAILING. A pass is earned by surviving the checker, not by looking plausible.
+```
+
+**Why this shape:** the driver's intelligence is *deciding what to check and how to steer on a
+fail*, not re-doing the research. The expensive judgment (does the source support the claim) is gated
+behind the cheap deterministic checker, so on most runs the LLM-judge step never fires.
+
+---
+
+## Sketch 3 — `research-supervisor` (fan-out → fuse → recurse)
+
+**Status: exists as `research-then-build-driver` + `parallel-fanout-supervisor` in supervisor-lab.**
+This sketch is the **research-specialized merge** of those two — build new only as a thin overlay via
+`mergeAgentProfiles`; the orchestration body is identical.
+
+**When to use:** a research question too broad for one worker — needs decomposition into disjoint
+sub-topics, parallel grounded workers, and a fused cited synthesis. The top of a research tree.
+
+**Tools / resources:** coordination MCP (`spawn_agent` / `await_event` / `steer_agent` /
+`answer_question` / `stop`) over a `Scope`; `web_search` to *ground the decomposition itself*; skills
+`dynamic-workflows`, `orchestrating-workers`, `authoring-agent-profiles` (all already in
+`supervisor-lab/skills/`).
+
+**System prompt (the contract):**
+
+```
+You are a research SUPERVISOR. You do NOT research the topic yourself — you ground the
+decomposition, fan out grounded-researcher workers, gate them, and FUSE their cited findings.
+
+THE SHAPE — ground → fan-out → gate → fan-in:
+1. GROUND     web_search FIRST to see what actually exists. Let the real landscape, not
+              your priors, define the sub-topics. Cite what you find.
+2. DECOMPOSE  split into DISJOINT sub-questions — non-overlapping ownership.
+3. FAN OUT    author a grounded-researcher profile per sub-question; spawn ALL of them in
+              ONE wave before awaiting any. Vary their angles. Never spawn-await-spawn.
+4. GATE       drain await_event. For each settled worker, run the deterministic checker
+              (Sketch 4). REJECT uncited or unsupported claims — a finding without a
+              source is not a finding. Steer or respawn on a fail.
+5. FAN IN     author a FINAL synthesis worker that fuses ONLY the gated findings into one
+              cited answer. Never paste raw worker dumps. Check each result for failure first.
+6. RECURSE    if a sub-question is itself large, spawn a SUB-supervisor (this profile +
+              the coordination MCP) to own it.
+
+NON-NEGOTIABLE:
+- Author EACH worker as a FULL profile (name, description, prompt, model, tools, skills).
+  A 2-sentence prompt with no tools is a stub, not a worker — the richness gate will flag it.
+- Never go blind: keep pulling until every spawned worker is terminal.
+- Settle only on gated, cited output. Budget is conserved and depth is bounded by the Scope.
+```
+
+**Why this shape:** the supervisor's only real lever is *the quality of the profiles it authors* —
+that is the capability `supervisor-lab` measures (`thinProfileRatio`,
+`bench/supervise-topology.ts`). The gate (step 4) reuses the cheap verifier so the supervisor doesn't
+burn its budget re-judging.
+
+---
+
+## Sketch 4 — `dedup-verifier` (thin, cheap, mostly deterministic)
+
+**This is the emilkowalski dedup lesson made into a profile.** It is deliberately *thin* — the
+"taste" lives in the deterministic validator, the profile is just the lens that applies it and
+escalates only the residual.
+
+**When to use:** called by a driver/supervisor at a gate (Sketch 2 step 3, Sketch 3 step 4). Never
+auto-invoked — the verifier equivalent of `disable-model-invocation: true`.
+
+**Tools:** `shell` (to run `agent-knowledge lint` / `validate --strict`), the
+`createResearcherValidator` call, and an LLM *only* for the one semantic check. **No `web_search`, no
+`fs` write, no generation tools** — a verifier that can edit content is a verifier that can cheat.
+
+**System prompt (the whole thing — it's short on purpose):**
+
+```
+You are a VERIFIER. You judge ONE research output against a fixed contract. You default
+to FAILING; a pass is earned. You never edit, research, or rewrite — you only judge.
+
+ORDER (cheapest check first, stop at the first hard fail):
+1. DETERMINISTIC   run the validator/lint: citation density >= floor, namespace match,
+                   links resolve, schema valid. If any fails → FAIL with the rule name.
+                   ~90% of failures die here, at zero LLM cost.
+2. SEMANTIC        ONLY if (1) passes: for each cited claim, does the cited source
+                   actually support it? This is the one thing a checker can't do. Be terse.
+
+OUTPUT: a findings table (claim | source | supported? | why) + a verdict (PASS / FAIL),
+grouped by severity. No prose. A violation is a finding.
+
+You carry NO generation ability by design. If you find yourself wanting to fix the
+output, STOP — that is the worker's job, not yours.
+```
+
+**Why thin beats heavy here:** the dedup already happened in `createResearcherValidator` and the lint
+path. A heavy verifier that re-reasons every claim with an LLM pays full model cost to re-derive a
+check the validator does for free, and (worse) a verifier with generation tools can drift into doing
+the work and grading itself. Thin + deterministic-first is both cheaper *and* harder to game. Measured
+claim to test when built: on a real run, the LLM (step 2) should fire on **< ~10–20% of gated outputs**
+because the deterministic check (step 1) absorbs the rest — if it fires on most, the validator floor
+is mis-set, not the verifier.
+
+---
+
+## supervisor-lab — status and port plan
+
+**It exists.** `~/code/supervisor-lab` is a real, non-trivial repo
+(`github.com/tangle-network/supervisor-lab`), not a stub. `ls ~/code | grep -i supervisor` → it's
+there.
+
+It already is what one might propose to "create": the product/experiment layer for supervisor agents
+over the `agent-runtime` substrate, dependency-one-way (`supervisor-lab → agent-runtime →
+agent-eval`). It ships:
+
+- **the two-agent loop, already ported** — `bench/supervise-topology.ts` is exactly the "two-agent
+  loop": a supervisor mounts the coordination MCP over a live `Scope`/`Supervisor`
+  (`createSupervisor`, `serveCoordinationMcp`), authors worker `AgentProfile`s as code, spawns them,
+  drains the bus (`await_event`), steers (`steer_agent`), and grades on a real judge. It has an
+  **OFFLINE $0 scripted path** and a LIVE cli-bridge path. This is the loop to plug these sketches
+  into — it does not need to be built.
+- **profile archetypes** — `profiles/research/{grounded-researcher,research-then-build-driver}.ts`,
+  `profiles/engineering/{parallel-fanout-supervisor,long-horizon-plan-driver,hardware-auditor}.ts`.
+  Sketches 1 and 3 above are *already these files*.
+- **a skill layer** — `skills/{authoring-agent-profiles,orchestrating-workers,dynamic-workflows,
+  spawning-research-loops}/SKILL.md`, each in the exact emilkowalski frontmatter+rules shape.
+- **a catalog + ingest pipeline** — `src/catalog/`, `src/ingest/skills.ts` ingests vendored
+  Claude-Code-style skill packs (the same shape as `emilkowalski/skills`) by convention.
+- **the richness gate** — `assessAuthoredProfile` / `profileRichnessFinding` / `thinProfileRatio`,
+  the deterministic "is this a stub" check that is the dedup-verifier's first line.
+
+### How to port the two-agent loop (it's already there — this is how to extend it)
+
+Because the loop already exists, "porting" means **adding these four profiles + the thin-verifier gate
+into the existing harness**, not rebuilding it:
+
+1. **Land the profiles as catalog files.** Sketches 1 and 3 are already
+   `profiles/research/grounded-researcher.ts` and `research-then-build-driver.ts`. Sketch 2
+   (`verifier-driver`) and Sketch 4 (`dedup-verifier`) are new files under
+   `profiles/research/` — author them as `defineAgentProfile` entries, resolve their skills via the
+   `skills(...)` helper in `profiles/_shared.ts` (fails closed on an unknown skill).
+
+2. **Wire the dedup-verifier into the gate.** In `bench/supervise-topology.ts`, the worker's
+   `runWorker` already grades on `adapter.judge`. For research tasks, replace/augment that with the
+   deterministic `createResearcherValidator` + `agent-knowledge lint` path FIRST, and only escalate to
+   the LLM semantic check on a deterministic pass. This is the dedup point made executable: the
+   existing `assessAuthoredProfile` richness gate is the *profile* check; the validator is the
+   *output* check. Both run before any LLM judge.
+
+3. **Add a research bench arm.** `supervise-topology.ts` auto-detects domain (repo vs. answer/text).
+   A research arm is an "answer/text" task whose `adapter.judge` is the cited-output validator. Add
+   `BENCH=research` that loads a research question + namespace and grades via
+   `createResearcherValidator`. The OFFLINE scripted path already proves the harness at $0; extend
+   `scriptedRun.workerResult` to emit a cited/uncited synthesis so the offline smoke exercises the
+   verifier without spend.
+
+4. **Run the existing experiment knob.** The whole point of the lab is the one knob: catalog/skills
+   ON vs. OFF (`CATALOG=1`). With these profiles + the thin verifier in the catalog, run
+   capability-aware vs. baseline on a hard research task and read `thinProfileRatio` + delivery rate —
+   does giving the supervisor the research archetypes + the cheap gate produce better-composed teams
+   and more *cited, gated* deliveries.
+
+### Cross-repo note
+
+`agent-knowledge` already owns the deterministic research checker (`createResearcherValidator`, the
+`lint`/`validate` CLI) and the researcher profile (`researcherProfile`,
+`multiHarnessResearcherFanout`). The thin verifier should **call those**, not reimplement them —
+`supervisor-lab` depends on `agent-runtime`, and the research checks live in `agent-knowledge`, so the
+research bench arm pulls `@tangle-network/agent-knowledge` for the verifier's deterministic line. That
+keeps the dedup in one place: the validator is authored once, the verifier profile is a thin lens over
+it.