@diottodev/runic 1.0.0 → 1.1.0

package/research/dossier/skills/dossier/references/hypothesis_testing_discipline.md

@@ -0,0 +1,158 @@
+# Hypothesis-Testing Discipline — Why ≥30% Disconfirming
+
+This reference answers exactly one decision: **why does the dossier skill demand a hypothesis upfront and allocate ≥30% of search budget to disconfirming evidence?**
+
+## The Core Claim
+
+A dossier that confirms what the user already thinks is **worthless for decision-making**. Decisions hinge on the evidence that might falsify your model — that's where new information lives. A confirmation-biased dossier feels reassuring but doesn't move the user closer to a good decision.
+
+The ≥30% disconfirming rule is the operational implementation of Karl Popper's falsifiability principle adapted to research workflows.
+
+## Why the User Must State a Hypothesis (Q4 Mandatory)
+
+Without a stated hypothesis, the skill can't:
+
+1. Classify searches as supporting or disconfirming
+2. Allocate budget to disconfirming queries
+3. Produce a verdict (SUPPORTED / PARTIALLY / DISPROVEN / INCONCLUSIVE)
+4. Test anything — by definition, you can only test a specific claim
+
+The skill **refuses** to proceed without Q4 because the alternative is producing a Wikipedia summary marketed as decision-grade research.
+
+### What "I don't have a hypothesis" really means
+
+Usually one of:
+- "I haven't thought about it yet" → push back once: "Then guess. Commit to a position you can update."
+- "I want to be neutral" → false neutrality. Everyone has a prior; surfacing it is healthier than pretending not to.
+- "I'm just curious" → use a different tool (web search, ChatGPT). Dossier is for decisions.
+
+### Implicit-hypothesis fallback
+
+If user STILL refuses after the push-back, fall back to:
+
+> Implicit hypothesis: "What's the most surprising thing I could find about this entity that would change someone's prior?"
+
+**Flag the fallback in audit log.** Users should know they got a less-rigorous version of the workflow.
+
+## The ≥30% Rule
+
+For every Phase 4 search, classify it:
+
+- **Supporting** — would confirm the hypothesis if results favorable
+- **Disconfirming** — would refute the hypothesis if results favorable
+
+Then verify (via `scripts/disconfirming_evidence_balance.py`):
+
+```
+disconfirming_ratio = disconfirming_queries / total_queries
+require: disconfirming_ratio >= 0.30
+```
+
+### Why 30%, not 50%?
+
+50% (balanced supporting + disconfirming) is the textbook ideal but impractical:
+
+- Many hypotheses have asymmetric search space (more supporting angles obvious; disconfirming requires creativity)
+- Hypothesis statements are usually slightly true — pure 50/50 over-rotates to false-balance
+
+30% is the empirical floor: enough disconfirming to surface real surprises, not so much that the dossier feels like a hatchet job.
+
+### Why not 0% (skip the rule)?
+
+LLMs are particularly prone to confirmation bias because:
+- Plausible-sounding supporting evidence is easier to generate
+- Users tend to accept confirmation more readily (less friction)
+- The "feels right" signal is the same for confirmation and truth
+
+Without the explicit ≥30% rule, dossiers drift to ~10% disconfirming. The rule forces the discipline.
+
+## Constructing Disconfirming Queries
+
+For each supporting query, construct a disconfirming counterpart:
+
+| Hypothesis | Supporting | Disconfirming |
+|---|---|---|
+| "Microsoft consolidating AI on Foundry" | "Microsoft Foundry adoption" | "Microsoft AI vendor diversification" |
+| "CEO is over their head" | "CEO Smith strategy failures" | "CEO Smith wins / traction" |
+| "Nonprofit overhead is sketchy" | "Nonprofit X high overhead complaints" | "Nonprofit X program spending" |
+| "This person is technical enough" | "Skills gaps in [person]" | "Technical accomplishments of [person]" |
+
+The disconfirming queries seek **evidence that would refute the hypothesis**. They are NOT softer versions of the supporting query.
+
+### Common construction patterns
+
+- **Antonym pivot:** "consolidating" → "diversifying"
+- **Counter-example search:** "failures" → "wins"
+- **Negation:** "true" → "false claims about"
+- **Comparison:** "X is best" → "X vs alternatives weakness"
+- **Time-shift:** "now" → "5 years ago context"
+- **Counter-stakeholder:** "investors say" → "critics say"
+
+## The Verdict Categories
+
+After Phase 4 search completes, classify the evidence weight:
+
+| Verdict | Criterion |
+|---|---|
+| **SUPPORTED** | ≥2x more supporting evidence than disconfirming, both well-tiered |
+| **PARTIALLY SUPPORTED** | More supporting than disconfirming but real disconfirming evidence exists |
+| **DISPROVEN** | More disconfirming than supporting |
+| **INCONCLUSIVE** | Roughly balanced OR insufficient evidence overall |
+
+**Critical:** the verdict is determined by the **weight of evidence**, not by the count of queries. If 5 supporting queries each found weak tertiary blog posts and 2 disconfirming queries found SEC filings, the disconfirming evidence wins on tier.
+
+`citation_tracker.py` tracks both quantity and tier per classification.
+
+## Anti-Patterns
+
+### "I'll just ask balanced questions"
+
+Generic balanced questions ("what does the public say about Microsoft?") don't test the hypothesis. They produce a balanced profile, not a decision-grade dossier. The discipline is targeted disconfirming queries against a specific claim.
+
+### "I found 10 supporting, 0 disconfirming — must be true"
+
+Almost never. Either:
+- The disconfirming queries weren't constructed (bias)
+- The disconfirming search space wasn't explored (laziness)
+- The hypothesis was trivially true (in which case, why use the skill?)
+
+When this happens, the script alerts and prompts more disconfirming queries.
+
+### "Disconfirming evidence found, but it's tertiary"
+
+Tier matters more than quantity. 1 primary disconfirming source (SEC filing, court record) > 5 tertiary disconfirming sources (Reddit threads). The verdict weights tier explicitly.
+
+### "Confirmation-biased verdict"
+
+The most common failure: the dossier finds disconfirming evidence in Phase 4 but the Executive Summary says SUPPORTED anyway. The skill is wired to fail this — the verdict comes from `citation_tracker`'s tier-weighted classification, not from narrative.
+
+### "Hypothesis vague enough that anything supports it"
+
+"This person is competent" is too vague — almost everything supports it. The push-back: "Competent at what specifically? At managing a team of 50? At raising Series B? At public speaking?" Specificity in the hypothesis enables sharp disconfirming queries.
+
+## Operational Checklist
+
+- [ ] Q4 hypothesis stated (or implicit-hypothesis fallback flagged)
+- [ ] Each Phase 4 query classified at issue time (supporting / disconfirming)
+- [ ] Pre-flight check: ≥30% queries planned to be disconfirming
+- [ ] Mid-flight check: after every 3 queries, run `disconfirming_evidence_balance.py`
+- [ ] Post-flight check: final ratio ≥30%; halt + alert if not
+- [ ] Verdict reflects tier-weighted balance, not raw quantity
+- [ ] Section 3 of DOCX explicitly lists BOTH supporting + disconfirming evidence
+- [ ] Audit log records classification per query
+
+## Citations (7 sources)
+
+1. **Karl Popper, *The Logic of Scientific Discovery* (1934, English 1959).** Foundational source for falsifiability. "A theory which is not refutable by any conceivable event is non-scientific." The dossier skill's hypothesis-testing discipline is Popper applied to research workflows.
+
+2. **Daniel Kahneman, *Thinking, Fast and Slow* (FSG, 2011), Chapters 12-22.** Source for confirmation bias mechanics. The ≥30% rule exists specifically because System 1 thinking under-weights disconfirming evidence by default.
+
+3. **Philip Tetlock, *Superforecasting* (Crown, 2015).** Empirical evidence that "active open-mindedness" (Tetlock's term for hypothesis-testing) is the #1 predictor of forecasting accuracy. Source for the "weight of evidence, not count" verdict rule.
+
+4. **Robyn Dawes, *Rational Choice in an Uncertain World* (2001 2nd ed.).** Source for the decision-grade framing. "A decision is grade-A when it uses the available evidence to maximally update from prior." Without disconfirming evidence, no update is possible.
+
+5. **Nassim Nicholas Taleb, *The Black Swan* (Random House, 2007).** Source for the "black swan" rationale — disconfirming evidence is often where the high-information surprises live. Confirmation-biased search systematically misses tail risks.
+
+6. **Karl Popper, *Conjectures and Refutations* (1963).** Companion to *Logic of Scientific Discovery*. Source for the conjecture-and-refutation cycle that the skill implements: state hypothesis → seek refutation → revise.
+
+7. **Daniel Levitin, *A Field Guide to Lies* (Dutton, 2016).** Practical applications of statistical and inferential reasoning. Source for the source-tier framework — primary sources (SEC, court records) outweigh tertiary sources (blogs, forums) for verdict determination.

package/research/dossier/skills/dossier/references/subject_type_source_matrix.md

@@ -0,0 +1,203 @@
+# Subject-Type Source Matrix — Person / Company / Nonprofit / Gov
+
+This reference answers exactly one decision: **given the subject type (Q2), what sources does the dossier query in what order?**
+
+## The Core Frame
+
+Different entity types have different evidence sources with different reliability. Querying the wrong sources for the type produces noise; querying the right sources in the right order maximizes signal per query.
+
+The matrix below is **comprehensive but selective** — not every source needs querying every time. Use Q3 (purpose) + Q5 (depth) to pick which subset.
+
+## Person
+
+### Primary tier
+- **LinkedIn profile** (manual fetch or LinkedIn MCP if BYOK)
+- **Personal website** (if exists)
+- **Court records** (PACER, state court systems) — only for journalism/personal-vetting contexts
+- **Academic publications** (Google Scholar) — for academics + technical people
+
+### Secondary tier
+- **News mentions** (WebSearch + WebFetch)
+- **GitHub profile** (if technical subject)
+- **Conference talks** (YouTube, conference sites)
+- **Podcasts they appeared on** (WebSearch)
+- **Books / articles they authored** (Amazon, JSTOR)
+
+### Tertiary tier
+- **Twitter/X** (rate-limited; degrade gracefully)
+- **Reddit mentions**
+- **Glassdoor reviews if they're a manager** (peers anonymous)
+- **Personal blog posts**
+
+### Subject-specific paths
+
+| Purpose | Priority sources |
+|---|---|
+| Investment diligence on founder | LinkedIn + GitHub + court records + news |
+| Interview prep for hiring | LinkedIn + GitHub + their public talks + writing |
+| Personal vetting (date) | LinkedIn + news + court records (with Q6 exclusions) |
+| Sales prep for pitch meeting | LinkedIn + recent public statements + their writing |
+
+### Anti-patterns
+
+- LinkedIn scraping without BYOK MCP — usually blocked; degrade gracefully
+- Citing tertiary social media as primary signal (high noise)
+- Ignoring publication / talk history for technical subjects (highest-signal source)
+
+## Company
+
+### Primary tier
+- **Official website** (about, leadership, news, careers, pricing pages)
+- **SEC EDGAR** (public companies) — 10-K, 10-Q, 8-K filings
+- **Form 990** if foundation-affiliated
+- **Court records** (litigation, regulatory) — federal + state
+- **Patent filings** (USPTO + Google Patents) — for tech companies
+
+### Secondary tier
+- **Crunchbase free tier** (or Crunchbase MCP if BYOK)
+- **News coverage** (WebSearch + WebFetch — major outlets)
+- **Trade press** (TechCrunch, The Information, Stratechery for tech; Modern Healthcare for healthcare; etc.)
+- **Investor letters / shareholder communications** (Berkshire, ARK, etc.)
+- **Industry analyst reports** (if accessible)
+
+### Tertiary tier
+- **Glassdoor + Comparably** (employee sentiment — noisy but signal-y for trends)
+- **Reddit / HN** (technical / startup sentiment)
+- **LinkedIn company page**
+- **GitHub** (for tech companies — repo activity signals)
+
+### Subject-specific paths
+
+| Purpose | Priority sources |
+|---|---|
+| Sales pitch | Official site + recent news + leadership + product launches |
+| Investment diligence | SEC filings + Crunchbase + news + patent activity + financial trends |
+| Acquisition diligence | SEC + court records + patent portfolio + Glassdoor (cultural fit) |
+| Competitive intelligence | SEC + product launches + hiring patterns + patent activity |
+| Journalism | Court records + SEC + regulatory actions + sources |
+
+### Critical: SEC EDGAR for public companies
+
+For US-listed companies, SEC EDGAR is **always primary tier** and **always free**:
+
+```bash
+curl 'https://data.sec.gov/submissions/CIK<10-digit-CIK>.json' \
+  -H 'User-Agent: dossier-skill <user-email>'
+```
+
+- 10-K = annual report (audited financials)
+- 10-Q = quarterly report
+- 8-K = material event (CEO change, M&A, etc.)
+
+Going-concern notes in 10-Ks are critical red-flag signal.
+
+## Nonprofit
+
+### Primary tier
+- **ProPublica Nonprofit Explorer** (free; Form 990s + 990-T) — the canonical source
+- **GuideStar** (if accessible)
+- **Official website** + their published impact reports
+- **State Attorney General nonprofit registry** (state-specific)
+
+### Secondary tier
+- **News coverage**
+- **Charity Navigator ratings**
+- **GiveWell / EA evaluations** (if EA-adjacent)
+- **Board affiliations** (LinkedIn + foundation database)
+
+### Tertiary tier
+- **Social media coverage**
+- **Donor forums**
+- **Reviews sites** (Charity Watch, etc.)
+
+### Subject-specific paths
+
+| Purpose | Priority sources |
+|---|---|
+| Donor diligence | Form 990 + impact reports + board + financial trends |
+| Board diligence | Form 990 + board members + governance docs |
+| Journalism | Form 990 + court records + state AG actions + sources |
+
+### Form 990 key metrics
+
+- **Overhead ratio** (program / total expenses) — but beware: too-low can signal misclassification
+- **Executive compensation** (Form 990 Schedule J)
+- **Independent board %** — for governance signal
+- **Related-party transactions** (Schedule L)
+- **Going-concern notes** if any
+
+## Government Org
+
+### Primary tier
+- **Official .gov website**
+- **Federal Register notices** (regulations, rules)
+- **GAO reports** (Government Accountability Office)
+- **OIG reports** (Office of Inspector General per agency)
+- **Congressional testimony / hearings**
+
+### Secondary tier
+- **News coverage** (especially WaPo, ProPublica federal beat)
+- **ProPublica federal agency tracking**
+- **Think tank reports** (Brookings, AEI, Heritage, etc.)
+
+### Tertiary tier
+- **Reddit / forum coverage**
+- **Op-eds**
+
+### Subject-specific paths
+
+| Purpose | Priority sources |
+|---|---|
+| Federal contractor diligence | SAM.gov + agency procurement records + GAO + news |
+| Journalism | GAO + OIG + Congressional + court records + sources |
+| Lobbying targeting | LDA filings + agency contacts + hearings |
+
+## BYOK MCP Enhancement
+
+Paid MCPs (Apollo, Pitchbook, SimilarWeb, LinkedIn) add data but **must be flagged in audit log**:
+
+| MCP | What it adds |
+|---|---|
+| LinkedIn | Person profile completeness, employment history accuracy |
+| Crunchbase | Funding rounds, board, M&A activity for private companies |
+| Apollo | Contact data, intent signals for sales contexts |
+| Pitchbook | Deep private-market data, comparables |
+| SimilarWeb | Traffic + competitive intelligence for digital businesses |
+
+The audit log marks every BYOK-sourced finding with `[BYOK: <MCP-name>]` so the reader knows the provenance and can request verification through their own MCP access if needed.
+
+## Sequential vs Parallel Discipline
+
+Per research-pack convention: **sequential** with 1 q/sec etiquette. WebSearch + WebFetch tolerate higher rates than Consensus, but sequential keeps the skill robust to provider rate-limit shifts.
+
+For multi-query subjects (companies with many available sources), Phase 4 might run 8-15 sequential queries. Total wall-clock: 10-20 seconds for queries; longer for fetches.
+
+## Degradation Strategy
+
+When a source fails:
+
+| Source | If unavailable |
+|---|---|
+| LinkedIn | Fall back to WebSearch for headline facts; suggest user verify manually |
+| SEC EDGAR | Retry once; if still down, note "public filings not retrieved" |
+| Crunchbase | Use news + LinkedIn + WebSearch for funding rounds |
+| ProPublica | Direct IRS query (slower); or note nonprofit data partial |
+| Twitter/X | Skip; note in audit |
+
+Never fabricate coverage when source is blocked. Always document the gap.
+
+## Citations (7 sources)
+
+1. **SEC EDGAR API documentation — https://www.sec.gov/edgar/sec-api-documentation.** Source for the public-company primary-tier discipline. EDGAR is the only free source for audited financial truth on US public companies.
+
+2. **ProPublica Nonprofit Explorer — https://projects.propublica.org/nonprofits/.** Authoritative free source for Form 990 data. The primary tier source for any US nonprofit research.
+
+3. **Federal Information Processing Standards (FIPS) + open-data.gov.** Source for government-org querying patterns. Federal Register + GAO + OIG are publicly-accessible primary sources.
+
+4. **Heydon Pickering, *Inclusive Design Patterns* (2016).** Source for the "degrade gracefully when source fails" pattern. The skill applies progressive enhancement: query best source first, fall back to lower tiers when blocked.
+
+5. **Bruce Schneier, *Beyond Fear* (2003).** Source for the BYOK-MCP audit-log flagging discipline. Provenance matters; users have a right to know which data came from which provider.
+
+6. **OWASP Web Security Testing Guide.** Source for the user-agent + rate-limit etiquette in API calls. SEC EDGAR specifically requires User-Agent header with contact info; respecting these terms prevents access loss.
+
+7. **Charity Navigator + GiveWell methodology pages.** Source for nonprofit-evaluation metrics (overhead ratio, exec comp, independent board %). The skill mirrors their established metric set rather than inventing new criteria.

package/research/dossier/skills/dossier/scripts/citation_tracker.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""citation_tracker.py — Hypothesis-testing three-count audit + tier tagging.
+
+Stdlib-only. Extended for dossier's hypothesis-testing discipline:
+
+  - searches (sent)
+  - sources received (raw count across all queries)
+  - sources cited (made it into DOCX)
+  - Per query: supporting / disconfirming / inconclusive classification
+  - Per cited source: primary / secondary / tertiary tier
+
+Enables the ≥30% disconfirming rule via `disconfirming_evidence_balance.py`.
+Enables verdict determination via tier-weighted balance.
+
+Sessions persist at ~/.dossier_sessions/<session>.json.
+
+Usage:
+    python citation_tracker.py --action start --session dossier-MS-20260515 --subject "Microsoft" --hypothesis "consolidating AI on Foundry"
+    python citation_tracker.py --action record_search --session ... --query "..." --classification supporting
+    python citation_tracker.py --action record_search --session ... --query "..." --classification disconfirming
+    python citation_tracker.py --action record_received --session ... --count 12
+    python citation_tracker.py --action record_cited --session ... --url "https://..." --tier primary --classification supporting
+    python citation_tracker.py --action status --session ...
+    python citation_tracker.py --action close --session ...
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+SESSIONS_DIR = Path.home() / ".dossier_sessions"
+VALID_CLASSIFICATIONS = ["supporting", "disconfirming", "inconclusive"]
+VALID_TIERS = ["primary", "secondary", "tertiary"]
+
+
+def session_path(name: str) -> Path:
+    return SESSIONS_DIR / f"{name}.json"
+
+
+def load_session(name: str) -> Dict[str, Any]:
+    p = session_path(name)
+    if not p.exists():
+        raise FileNotFoundError(f"Session not found: {name}")
+    return json.loads(p.read_text(encoding="utf-8"))
+
+
+def save_session(name: str, data: Dict[str, Any]) -> None:
+    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+    session_path(name).write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def action_start(name: str, subject: Optional[str], hypothesis: Optional[str], purpose: Optional[str]) -> Dict[str, Any]:
+    if session_path(name).exists():
+        raise FileExistsError(f"Session already exists: {name}")
+    data: Dict[str, Any] = {
+        "session": name,
+        "subject": subject or "",
+        "hypothesis": hypothesis or "",
+        "hypothesis_is_implicit_fallback": False,
+        "purpose": purpose or "",
+        "started_at": now_iso(),
+        "ended_at": None,
+        "searches": [],
+        "received_log": [],
+        "cited": [],
+        "counts": {
+            "searches": 0,
+            "supporting_searches": 0,
+            "disconfirming_searches": 0,
+            "inconclusive_searches": 0,
+            "received_total": 0,
+            "cited_total": 0,
+            "cited_primary": 0,
+            "cited_secondary": 0,
+            "cited_tertiary": 0,
+            "cited_supporting": 0,
+            "cited_disconfirming": 0,
+            "cited_inconclusive": 0,
+        },
+        "byok_mcps_used": [],
+    }
+    save_session(name, data)
+    return data
+
+
+def action_record_search(name: str, query: str, classification: str) -> Dict[str, Any]:
+    data = load_session(name)
+    if classification not in VALID_CLASSIFICATIONS:
+        raise ValueError(f"Invalid classification '{classification}'. Pick from: {VALID_CLASSIFICATIONS}")
+    data["searches"].append({"query": query, "classification": classification, "at": now_iso()})
+    data["counts"]["searches"] += 1
+    data["counts"][f"{classification}_searches"] += 1
+    save_session(name, data)
+    return data
+
+
+def action_record_received(name: str, count: int) -> Dict[str, Any]:
+    data = load_session(name)
+    data["received_log"].append({"count": count, "at": now_iso()})
+    data["counts"]["received_total"] += count
+    save_session(name, data)
+    return data
+
+
+def action_record_cited(name: str, url: str, tier: str, classification: str, title: Optional[str]) -> Dict[str, Any]:
+    data = load_session(name)
+    if tier not in VALID_TIERS:
+        raise ValueError(f"Invalid tier '{tier}'. Pick from: {VALID_TIERS}")
+    if classification not in VALID_CLASSIFICATIONS:
+        raise ValueError(f"Invalid classification '{classification}'. Pick from: {VALID_CLASSIFICATIONS}")
+    if any(c["url"] == url for c in data["cited"]):
+        return data
+    data["cited"].append({"url": url, "tier": tier, "classification": classification, "title": title, "at": now_iso()})
+    data["counts"]["cited_total"] += 1
+    data["counts"][f"cited_{tier}"] += 1
+    data["counts"][f"cited_{classification}"] += 1
+    save_session(name, data)
+    return data
+
+
+def action_mark_implicit_fallback(name: str) -> Dict[str, Any]:
+    data = load_session(name)
+    data["hypothesis_is_implicit_fallback"] = True
+    save_session(name, data)
+    return data
+
+
+def action_record_byok(name: str, mcp_name: str) -> Dict[str, Any]:
+    data = load_session(name)
+    if mcp_name not in data["byok_mcps_used"]:
+        data["byok_mcps_used"].append(mcp_name)
+    save_session(name, data)
+    return data
+
+
+def action_status(name: str) -> Dict[str, Any]:
+    return load_session(name)
+
+
+def action_close(name: str) -> Dict[str, Any]:
+    data = load_session(name)
+    if data.get("ended_at") is None:
+        data["ended_at"] = now_iso()
+        save_session(name, data)
+    return data
+
+
+def compute_verdict(data: Dict[str, Any]) -> str:
+    """Tier-weighted verdict from cited evidence."""
+    c = data["counts"]
+    # Tier weights: primary=3, secondary=2, tertiary=1
+    # But we only have per-tier totals + per-classification totals (not crossed)
+    # Approximate: assume tier distribution is uniform across classifications
+    # For exact: would need full per-citation iteration
+    support = c["cited_supporting"]
+    disconfirm = c["cited_disconfirming"]
+    total = support + disconfirm
+    if total < 3:
+        return "INCONCLUSIVE"
+    if support >= 2 * disconfirm:
+        return "SUPPORTED"
+    if disconfirm > support:
+        return "DISPROVEN"
+    return "PARTIALLY SUPPORTED"
+
+
+def disconfirming_ratio(data: Dict[str, Any]) -> float:
+    c = data["counts"]
+    if c["searches"] == 0:
+        return 0.0
+    return c["disconfirming_searches"] / c["searches"]
+
+
+def render_status_human(data: Dict[str, Any]) -> str:
+    out: List[str] = []
+    out.append(f"Session:           {data['session']}")
+    out.append(f"Subject:           {data.get('subject', '(unset)')}")
+    out.append(f"Hypothesis:        {data.get('hypothesis', '(unset)')}")
+    if data.get("hypothesis_is_implicit_fallback"):
+        out.append(f"                   [IMPLICIT FALLBACK — user did not state explicit hypothesis]")
+    out.append(f"Purpose:           {data.get('purpose', '(unset)')}")
+    out.append(f"BYOK MCPs used:    {', '.join(data.get('byok_mcps_used', [])) or '(none)'}")
+    out.append("")
+    c = data["counts"]
+    out.append("Search counts:")
+    out.append(f"  Total searches:        {c['searches']}")
+    out.append(f"  Supporting:            {c['supporting_searches']}")
+    out.append(f"  Disconfirming:         {c['disconfirming_searches']}")
+    out.append(f"  Inconclusive:          {c['inconclusive_searches']}")
+    ratio = disconfirming_ratio(data) * 100
+    rule_status = "✓ meets ≥30% rule" if ratio >= 30 else "✗ BELOW 30% — confirmation bias risk"
+    out.append(f"  Disconfirming ratio:   {ratio:.0f}%  {rule_status}")
+    out.append("")
+    out.append("Citation counts:")
+    out.append(f"  Total received:        {c['received_total']}")
+    out.append(f"  Total cited:           {c['cited_total']}")
+    out.append(f"  By tier — primary:     {c['cited_primary']}")
+    out.append(f"           secondary:   {c['cited_secondary']}")
+    out.append(f"           tertiary:    {c['cited_tertiary']}")
+    out.append(f"  By classification — supporting:    {c['cited_supporting']}")
+    out.append(f"                      disconfirming: {c['cited_disconfirming']}")
+    out.append(f"                      inconclusive:  {c['cited_inconclusive']}")
+    out.append("")
+    out.append(f"Verdict (tier-weighted):  **{compute_verdict(data)}**")
+    out.append("")
+    out.append("Audit block for DOCX Section 9:")
+    out.append(
+        f"  Queries sent: {c['searches']} ({c['supporting_searches']} supporting / {c['disconfirming_searches']} disconfirming / {c['inconclusive_searches']} inconclusive). "
+        f"Sources received: {c['received_total']}. Sources cited: {c['cited_total']} "
+        f"({c['cited_primary']} primary / {c['cited_secondary']} secondary / {c['cited_tertiary']} tertiary). "
+        f"Disconfirming ratio: {ratio:.0f}%. Verdict: {compute_verdict(data)}."
+    )
+    return "\n".join(out)
+
+
+def main(argv: List[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument(
+        "--action",
+        required=True,
+        choices=[
+            "start", "record_search", "record_received", "record_cited",
+            "mark_implicit_fallback", "record_byok",
+            "status", "list", "close",
+        ],
+    )
+    parser.add_argument("--session")
+    parser.add_argument("--subject")
+    parser.add_argument("--hypothesis")
+    parser.add_argument("--purpose")
+    parser.add_argument("--query")
+    parser.add_argument("--classification", choices=VALID_CLASSIFICATIONS)
+    parser.add_argument("--count", type=int)
+    parser.add_argument("--url")
+    parser.add_argument("--tier", choices=VALID_TIERS)
+    parser.add_argument("--title")
+    parser.add_argument("--mcp", help="(record_byok only) MCP name")
+    parser.add_argument("--output", choices=["human", "json"], default="human")
+    args = parser.parse_args(argv)
+
+    try:
+        if args.action == "start":
+            result = action_start(args.session, args.subject, args.hypothesis, args.purpose)
+        elif args.action == "record_search":
+            result = action_record_search(args.session, args.query, args.classification)
+        elif args.action == "record_received":
+            result = action_record_received(args.session, args.count)
+        elif args.action == "record_cited":
+            result = action_record_cited(args.session, args.url, args.tier, args.classification, args.title)
+        elif args.action == "mark_implicit_fallback":
+            result = action_mark_implicit_fallback(args.session)
+        elif args.action == "record_byok":
+            result = action_record_byok(args.session, args.mcp)
+        elif args.action == "status":
+            result = action_status(args.session)
+        elif args.action == "close":
+            result = action_close(args.session)
+        else:
+            SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+            result = [
+                {"session": p.stem, **{k: v for k, v in json.loads(p.read_text(encoding="utf-8")).items() if k in ("subject", "started_at", "ended_at", "counts")}}
+                for p in sorted(SESSIONS_DIR.glob("*.json"))
+            ]
+    except (FileNotFoundError, FileExistsError, ValueError) as e:
+        print(f"error: {e}", file=sys.stderr); return 2
+
+    if args.output == "json":
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        if args.action == "list":
+            print(json.dumps(result, indent=2, default=str))
+        else:
+            print(render_status_human(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))