@tangle-network/agent-knowledge 4.0.1 → 5.0.0

package/docs/results/adaptive.md

@@ -1,9 +1,9 @@
 # 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
+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
+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.
@@ -19,7 +19,7 @@ stopping at the first that decides:
    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.
+   relevance verifier (`createVerifyingResearchDriver`), one call each.
 
 ## Live frontier, n=5 topics (glm-5.2)
 
@@ -39,24 +39,24 @@ is the per-arm `RouterClient.usage()` diff (#36). Total spend for the run:
 | **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
+($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
+## Interpretation: adaptive occupies one cost-quality point
 
 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
+  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
+  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.
 
@@ -65,19 +65,19 @@ 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 —
+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
+## 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
+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
+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,
@@ -95,12 +95,12 @@ neither seen on this authoritative-host-heavy set:
 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
+and qualifies the **quality** half accurately: 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
+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.
 

package/docs/results/claim-grounding.md

@@ -1,22 +1,22 @@
 # 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
+**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?
+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**.
+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
+`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
@@ -31,25 +31,25 @@ proposals. Cost diffed per arm with the #36 `RouterClient.usage()` instrumentati
 
 | n=5 topics | misattributions caught | marginal $ | $/topic | per-$ caught |
 |---|---|---|---|---|
-| no-verifier | 0 / 5 | $0.0000 | — | — |
+| no-verifier | 0 / 5 | $0.0000 | n/a | n/a |
 | 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
+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 —
+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 —
+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
@@ -63,7 +63,7 @@ de-duplication.
   (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.
+  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**
@@ -78,9 +78,9 @@ grounded sources, while relevance and no-verifier both admit **2/2**.
 - **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.
+  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 —
+  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).
 

package/docs/results/cost-quality.md

@@ -2,7 +2,7 @@
 
 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
+"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 |
@@ -11,7 +11,7 @@ actually N `verifySource` LLM calls. Pricing the calls shows what that hid.
 | 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] |
+| cleanliness Δ (single − two admitted) | n/a | n/a | +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
@@ -19,9 +19,9 @@ grouped-query attention 0, rotary position embeddings +1, KV-cache quantization
 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*
+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
+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/results/investment-thesis.md

@@ -1,25 +1,25 @@
-# From paper-retrieval to investigation — a research eval where one search is not enough, a metric that discriminates depth, and a 3-arm topology A/B
+# Investment-research depth eval and three-arm comparison
 
 *Tangle Network · `agent-knowledge`*
 
-## Verdict (BLUF)
+## Verdict
 
-We moved the research eval off ML-paper retrieval — where a **single** web search
+We moved the research eval off ML-paper retrieval, where a **single** web search
 already returns the answer, so the only thing the metric could measure was
-*collection* — onto **investment research**, where the material facts are buried in
+*collection*, onto **investment research**, where the material facts are buried in
 the footnotes of an SEC filing and genuinely require *investigation* to surface. On
 this harder domain we (1) **calibrated** a `$0`, model-free metric and proved it
-discriminates research depth — a shallow ticker summary scores **1/27 (4%)**, a
-deep filings-grounded thesis scores **27/27 (100%)**, a **+96-point** gap — and then
+discriminates research depth, a shallow ticker summary scores **1/27 (4%)**, a
+deep filings-grounded thesis scores **27/27 (100%)**, a **+96-point** gap, and then
 (2) ran **three research topologies head-to-head** on the same five held-out
 companies at matched compute, grading each one's knowledge base against a firewalled
 checklist of **27 buried material facts** a ticker search misses.
 
-**The honest A/B verdict: the research-DRIVING loop surfaced the most buried facts
-(16/27, 59%), +5 over blind collection (11/27, 41%) — but at n=5 companies that lift
+**A/B result: the research-driving loop surfaced the most buried facts
+(16/27, 59%), +5 over blind collection (11/27, 41%), but at n=5 companies that lift
 is NOT statistically clean: the 95% confidence interval crosses zero (P(Δ≤0)=0.08).**
-The verify/dedup loop did **not** beat collection at all (10/27, 37% — a wash,
-slightly worse). So no topology *significantly* beats collection here either —
+The verify/dedup loop did **not** beat collection at all (10/27, 37%, a wash,
+slightly worse). No approach *significantly* beats collection here.
 **driving is the only arm that even points the right way, and it points there
 suggestively, not significantly.** What the reframe *did* buy is a domain and a meter
 where the question is finally well-posed: the metric is no longer measuring whether a
@@ -27,7 +27,7 @@ single search ran, but whether investigation reached the buried fact.
 
 | arm | what the coordinator does | material facts | cost (5 cos.) | chats | searches | tokens |
 |---|---|---|---|---|---|---|
-| **A · collection** | nothing — accepts every source (1 agent collects) | 11/27 (41%) | $0.082 | 10 | 20 | 64,248 |
+| **A · collection** | nothing; accepts every source (1 agent collects) | 11/27 (41%) | $0.082 | 10 | 20 | 64,248 |
 | **B · verify/dedup** | LLM gates each source for relevance, rejects off-topic | 10/27 (37%) | $0.125 | 56 | 52 | 84,678 |
 | **C · driving (deepen)** | extracts claims, demands corroboration, asks deep follow-ups | **16/27 (59%)** | $0.157 | 33 | 28 | 124,387 |
 
@@ -35,17 +35,17 @@ Cost is real provenance, not an estimate: every `$`/call/token is diffed from
 `RouterClient.usage()` per company (the router's own `usage` field, priced at
 glm-5.2 rates), so "driving cost 1.9× collection" is measured, not modelled.
 
-## 1. The domain reframe — why we left ML-paper retrieval
+## 1. The domain reframe: why we left ML-paper retrieval
 
 The companion paper's depth eval (`docs/two-agent-research-ab.md` §9) measures a
-research loop on **20 deep questions across 5 ML topics**. That apparatus is sound —
+research loop on **20 deep questions across 5 ML topics**. That method is sound:
 its grader scores 0/20 on a one-line topic definition and 20/20 on a mechanism-rich
 paragraph, so it *can* tell depth from surface. But the topology A/B on top of it
-came back a clean null (driving 16/20 @ budget 4, 13/20 @ budget 6 — the winner
+came back a clean null (driving 16/20 @ budget 4, 13/20 @ budget 6, the winner
 *flips with the compute budget*, and the within-arm swing is as large as the
 between-arm gap). The autopsy named the cause: **on an ML topic a single good search
 already collects the answer.** Every arm finished in one effective round because the
-generic "one source closes the gap" readiness was met by the *first* fetch — so the
+generic "one source closes the gap" readiness was met by the *first* fetch, so the
 driving driver, whose entire mechanism is steering a *second* round, never got to
 act. When one search suffices, there is no investigation for a smarter coordinator to
 do, and the metric can only reward collection. That is the failure-mode-in-spirit the
@@ -55,12 +55,12 @@ easy for topology to matter.
 So we changed the domain to one where a single search **provably cannot** suffice.
 **Investment research**: give a loop a company + ticker + an as-of cutoff date and ask
 for a thesis; grade it on the buried, material, non-obvious drivers a thorough analyst
-flags and a ticker search misses. The decisive facts here live in 10-K footnotes — an
+flags and a ticker search misses. The decisive facts here live in 10-K footnotes, an
 HTM securities mark roughly equal to a bank's entire equity (SIVB), a deposit base
 that is 97% uninsured, a negative per-unit gross margin, a related-party lease. A web
 search for the company name returns "profitable regional bank" or "high-growth auto
 e-commerce"; the filing shows the mark-to-market hole the size of capital. **The
-answer is not collectable in one fetch — it has to be investigated for.** That is the
+answer is not collectable in one fetch, it has to be investigated for.** That is the
 property the ML domain lacked, and it is what makes a topology A/B finally meaningful:
 if a smarter coordinator can ever beat blind collection, a domain where the answer is
 buried is where it has the room to.
@@ -69,7 +69,7 @@ The held-out set is **5 companies, 27 material facts**, every fact read live out
 the primary SEC EDGAR 10-K during curation, every dollar figure quoted from the
 de-tagged filing text, every value knowable *at the cutoff* (the eventual collapse is
 recorded for the reader only and is **never graded**). The companies skew distressed /
-downside-risk — a documented curation bias, not a hidden one (full provenance, the
+downside-risk, a documented curation bias, not a hidden one (full provenance, the
 drop log, and the per-fact keyword groups: `docs/eval/investment-material-facts.md`):
 
 | ticker | company | as-of cutoff | CIK | facts |
@@ -80,25 +80,25 @@ drop log, and the per-fact keyword groups: `docs/eval/investment-material-facts.
 | PTON | Peloton | 2022-09-07 | 1639825 | 6 |
 | SI | Silvergate | 2022-02-28 | 1312109 | 5 |
 
-## 2. Calibration — does the metric discriminate depth? (the gate the ML exam passed only weakly)
+## 2. Calibration: does the metric discriminate depth? (the gate the ML exam passed only weakly)
 
 A topology A/B is meaningless unless the metric grading it can tell a *deep* thesis
-from a *shallow* one. If it can't, it is measuring word-collection — the exact failure
-the reframe set out to escape — and any A/B on top of it is noise. So **before** the
+from a *shallow* one. If it can't, it is measuring word-collection, the exact failure
+the reframe set out to escape, and any A/B on top of it is noise. So **before** the
 A/B, we ran a calibration gate (`$0`, offline, the binding result):
 
 For each of the 5 companies we hand-wrote two theses and scored each with the metric's
 pure core (`materialFactsSurfacedInText`):
 
-- **shallow** — a one-paragraph ticker summary: what the company does, a vibe on the
+- **shallow**: a one-paragraph ticker summary: what the company does, a vibe on the
   stock, generic macro/competition risk. The kind a single name-search returns. Names
   none of the buried, filing-level facts.
-- **deep** — a filings-grounded analyst memo naming the buried drivers (the duration
+- **deep**: a filings-grounded analyst memo naming the buried drivers (the duration
   loss, the buyback drain, the negative unit margin, the deposit concentration, the
   related party) in independent prose, with the real numbers.
 
 The grader is the same `$0`, model-free, case-insensitive substring check the held-out
-checklist ships (`gradeFactAgainstText`); the checklist is firewalled — read only by
+checklist ships (`gradeFactAgainstText`); the checklist is firewalled, read only by
 the metric, never shown to a loop.
 
 | ticker | shallow | deep | gap |
@@ -110,20 +110,20 @@ the metric, never shown to a loop.
 | SI | 0/5 (0%) | 5/5 (100%) | +100pp |
 | **total** | **1/27 (4%)** | **27/27 (100%)** | **+96pp** |
 
-**The metric is VALID:** it cleanly separates a shallow ticker-summary from a deep,
-filings-grounded thesis — a +96-point aggregate gap, every company clearing the bars
+**Calibration result:** the metric separates a shallow ticker-summary from a deep,
+filings-grounded thesis, a +96-point aggregate gap, every company clearing the bars
 (shallow `< 30%`, deep `> 70%`) with wide margin. Two guards make the gap real and not
 a teaching-to-the-test artifact:
 
 - **Anti-circularity.** The gate asserts **no deep thesis verbatim-embeds any
-  checklist `evidence` string** — the deep theses state the same publicly-documented
+  checklist `evidence` string**, the deep theses state the same publicly-documented
   facts in independent analyst prose. A high deep score is the meter catching real,
   independently-phrased depth, not an answer-key echo.
-- **The one honest shallow hit.** The single shallow surface (SIVB 1/6) is SIVB/f5 —
-  the innovation-economy / venture-client concentration — which fires on "technology"
+- **The one shallow hit.** The single shallow surface (SIVB 1/6) is SIVB/f5:
+  the innovation-economy / venture-client concentration, which fires on "technology"
   / "venture" in the SVB summary. That genuinely *is* the least-buried of SVB's six
   facts (a ticker search does return "SVB banks tech and venture startups"). We kept it
-  as a 4% leak rather than tighten the group, because it honestly reflects one
+  as a 4% leak rather than tighten the group, because it reflects one
   near-surface fact while the five truly buried ones (the ~$15B HTM loss, the
   equity-sized mark, the $151.5B uninsured base, the 20-point deposit-mix shift, the
   AFS/AOCI loss) stay unsurfaced. The firewall holds (17% << 30%).
@@ -132,38 +132,38 @@ Calibration also did its job as more than a rubber stamp: the first pass had the
 **Silvergate shallow thesis scoring 3/5 (60%)**, blowing the bar, because three fact
 groups accepted bare crypto-bank vocabulary (`crypto`, `grew rapidly`, `proprietary` /
 `payment network`) that any one-line summary trips. We tightened those three to require
-the *buried* signal — the deposit-**concentration** framing, the specific **$14.3B**
-figure, the **SEN** (Silvergate Exchange Network) name — and dropped the generic vocab.
+the *buried* signal, the deposit-**concentration** framing, the specific **$14.3B**
+figure, the **SEN** (Silvergate Exchange Network) name, and dropped the generic vocab.
 The deep thesis still hits all three; the shallow one no longer does. The metric found
 a way it could be fooled and we closed it before any A/B depended on it.
 
 **This is the gate the ML exam passed only in spirit.** The ML grader discriminated
-0/20 vs 20/20 too — but on a domain where the deep answer was *collectable* in one
+0/20 vs 20/20 too, but on a domain where the deep answer was *collectable* in one
 search, so the discrimination measured grammar, not investigation. Here the +96-point
 gap is over facts that are *buried by construction*, so a high score is reachable only
 by reaching into the filing. Same shape of result, materially harder domain.
 
-## 3. The 3-arm A/B — what each topology surfaced, head-to-head
+## 3. The 3-arm A/B: what each topology surfaced, head-to-head
 
 For each company the loop is told **only** `{company, ticker, cik, cutoff}` plus a
 generic set of analyst-lens readiness specs (balance-sheet risk, concentration,
-leverage, margins, liquidity, governance, regulatory — the *lenses* and where they
-live, the latest SEC 10-K — **not the answers**). It researches the company *as of* the
+leverage, margins, liquidity, governance, regulatory, the *lenses* and where they
+live, the latest SEC 10-K, **not the answers**). It researches the company *as of* the
 cutoff over web + SEC EDGAR (both public), writes a thesis, and we grade the resulting
-KB with `materialFactsSurfaced` — the firewalled checklist the loop never sees.
+KB with `materialFactsSurfaced`, the firewalled checklist the loop never sees.
 
 **Compute is matched by construction.** All three arms run the *same* web worker, the
 *same* 3-round budget, the *same* worker config (`resultsPerQuery: 3, queriesPerGap: 1,
-maxSourcesPerRound: 6`). The **only** thing that varies is the driver — the coordinator
+maxSourcesPerRound: 6`). The **only** thing that varies is the driver, the coordinator
 between the worker and the knowledge base:
 
-- **A · collection** (`createCollectionResearchDriver`) — an inert rubber stamp:
+- **A · collection** (`createCollectionResearchDriver`), an inert rubber stamp:
   accepts every source, gates nothing, steers only with the loop's built-in open-gap
   list. The driver adds **zero** router calls. This is the blind-collection floor.
-- **B · verify/dedup** (`createVerifyingResearchDriver`) — an LLM relevance gate: one
+- **B · verify/dedup** (`createVerifyingResearchDriver`), an LLM relevance gate: one
   chat call per candidate source to accept-or-reject for on-topic relevance and
   near-duplication. The worker ADDS; the driver GATES.
-- **C · driving** (`createResearchDrivingDriver`) — extracts each source's claims,
+- **C · driving** (`createResearchDrivingDriver`), extracts each source's claims,
   tracks how many *independent* sources corroborate each, and synthesizes deep
   follow-up sub-questions (comparative / mechanism / gap / contradiction) it folds into
   the worker's next prompt to push depth and demand corroboration.
@@ -200,13 +200,13 @@ Every interval crosses zero. **Driving vs collection is the closest to clean
 coin flip. This is the project's well-documented small-n mirage: exciting deltas born
 at n=5 do not survive a paired bootstrap.
 
-## 4. Autopsy — the two things worth understanding
+## 4. Autopsy: the two things worth understanding
 
 ### 4.1 Why driving wins where it wins
 
 Driving's mechanism is multi-round: extract claims from round 1, then steer the worker
 in rounds 2–3 to corroborate the weak ones and chase the deep questions. It helps most
-where the **first** fetch lands real filing data the driver can build on — the two
+where the **first** fetch lands real filing data the driver can build on, the two
 banks, where SEC bank-call-report / 10-K data is dense and reachable. SIVB jumps from 2
 buried facts (collection) to 5 (driving): the duration loss, the deposit concentration,
 the AFS/AOCI mark all surface once the driver demands the balance-sheet detail a second
@@ -230,21 +230,21 @@ ROUND 1: accepted=0 rejected=3 writtenPages=0
 ROUND 2: accepted=0 rejected=2 writtenPages=0
 ```
 
-The verifier was **correct on the merits** — those are aggregators, not the primary
+The verifier was **correct on the merits**, those are aggregators, not the primary
 filing, and last10k showed a post-cutoff filing. But the worker never surfaced the
 EDGAR primary for BBBY, so a strict primary-only gate left the KB **empty**. Collection
 accepts the same aggregator pages and scores 4/5 on BBBY; driving accepts them and
 scores 5/5. **The gate's strictness is a liability when the worker's sourcing is
-imperfect:** it throws away the only evidence the loop had. This is a genuine topology
-trade-off worth naming, not a harness break — the verify arm surfaced facts fine on
-CVNA (2), PTON (4), SI (4), so the harness works.
+imperfect:** it throws away the only evidence the loop had. This is a real coordination
+trade-off. The verify arm still surfaced facts on CVNA (2), PTON (4), and SI (4),
+which rules out a general execution failure.
 
-### 4.3 The empty-thesis caveat (honest)
+### 4.3 The empty-thesis caveat
 
 Some runs show `thesis=0ch` (empty synthesis) yet still score facts. That is expected:
-`materialFactsSurfaced` grades the **whole KB** (the worker's fetched `knowledge/*.md`
-pages), not only the final thesis page. glm-5.2 occasionally spends its entire output
-budget on hidden reasoning and returns empty visible content on the synthesis call — a
+`materialFactsSurfaced` grades the **whole KB**, including the worker's fetched
+`knowledge/*.md` pages and the final thesis page. glm-5.2 occasionally spends its entire output
+budget on hidden reasoning and returns empty visible content on the synthesis call, a
 known reasoning-model behavior we floor at 1200 tokens but can't fully eliminate. The
 score still reflects what the loop fetched, so an empty thesis does not invalidate a
 run; it just means the synthesis prose was lost while the curated evidence was not.
@@ -252,7 +252,7 @@ run; it just means the synthesis prose was lost while the curated evidence was n
 ## 5. What this does and does not establish
 
 - **Does**: the metric *discriminates depth on a domain where one search is not
-  enough* (calibration: 1/27 shallow vs 27/27 deep, +96pp) — so the topology A/B on top
+  enough* (calibration: 1/27 shallow vs 27/27 deep, +96pp), so the topology A/B on top
   of it is finally well-posed, unlike the ML retrieval exam where one search already
   collected the answer. At matched compute on the 5-company held-out set, the
   research-driving topology surfaced the most buried material facts (16/27 vs 11/27 for
@@ -272,10 +272,10 @@ run; it just means the synthesis prose was lost while the curated evidence was n
 ## 6. Reproduce
 
 ```bash
-# The calibration gate that must pass FIRST ($0, offline) — the metric is valid.
+# The calibration gate that must pass FIRST ($0, offline): the metric is valid.
 pnpm test investment-calibration
 
-# The offline task wiring ($0) — proves page → index → grade end-to-end.
+# The offline task wiring ($0): proves page → index → grade end-to-end.
 pnpm test investment-thesis-task
 
 # The full live 3-arm A/B (costs ~$0.36 total at 5 companies × 3 arms × 3 rounds).
@@ -291,12 +291,12 @@ AGENT_KNOWLEDGE_LIVE=1 IT_LIVE_TICKERS=CVNA IT_LIVE_ARMS=collection \
 
 `IT_LIVE_ARMS` (`|`-separated subset of `collection|verify|driving`) and
 `IT_LIVE_TICKERS` scope the run; `IT_LIVE_ROUNDS` sets the per-arm round budget
-(default 3 — driving needs > 1). The smoke (one cheap glm-5.2 call) runs once before any
+(default 3, driving needs > 1). The smoke (one cheap glm-5.2 call) runs once before any
 arm, so a bad key fails fast, before the burn.
 
 ---
 
-*Run provenance. Calibration: `$0`, offline, reproducible — numbers from
+*Run provenance. Calibration: `$0`, offline, reproducible, numbers from
 `tests/eval/investment-calibration.test.ts` (shallow `< 30%`, deep `> 70%`,
 gap `> 40pp` per company and aggregate; all pass). A/B: 5 companies × 3 arms × 3 rounds
 = 15 live company-runs, glm-5.2 over the Tangle router, ~37.5 min wall, $0.36 total;