# Case Study: Agenda Intelligence MD

## Key facts
- **Role:** Builder & Maintainer.
- **Period:** February 2026–present.
- **Scope:** Deterministic evidence-packet linter with an MCP workflow plus compatibility HTTP, A2A, and Cloudflare Worker surfaces.
- **Primary outcome:** [v1.3.0](https://github.com/vassiliylakhonin/agenda-intelligence-md/releases/tag/v1.3.0) adds a runnable claim/source packet contract, strict CLI gate, packaged schemas, and published-wheel smoke checks; [v1.4.0](https://github.com/vassiliylakhonin/agenda-intelligence-md/releases/tag/v1.4.0) (2026-07-22) exposes the same preflight to MCP clients as `check_evidence_packet` and adds `create_brief` / `append_evidence`.
- **Evidence:** [GitHub repository](https://github.com/vassiliylakhonin/agenda-intelligence-md), releases, schemas, eval assets, and linked live endpoints.
- **Boundary:** Structural and evidence-readiness checks do not establish factual truth, legal sufficiency, production adoption, or benchmark performance.

## TL;DR
- Built **Agenda Intelligence MD** as a deterministic evidence-packet linter for claim-backed AI output.
- The primary workflow accepts claims, source IDs, optional quotations, and supplied source text; it returns broken references, quote mismatches, lexical-support gaps, unmatched numbers, and reviewer actions.
- It reports `packet_complete`, `source_review_required`, or `packet_incomplete`; `factuality_status` is always `not_assessed`.
- The older strategic-intelligence runtime, HTTP / A2A transports, and deployed Worker profiles remain available as compatibility surfaces and inspectable examples.

## First run

```bash
git clone https://github.com/vassiliylakhonin/agenda-intelligence-md
cd agenda-intelligence-md
python -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/agenda-intelligence check examples/evidence-packet/request.json --strict
```

## Evidence and boundaries
- Public GitHub repository: https://github.com/vassiliylakhonin/agenda-intelligence-md
- Live Cloudflare A2A workers: general Agenda Intelligence triage plus six vertical profiles — Middle Corridor Deal Risk Gate, Kazakhstan Market Entry Readiness Gate, CIS Secondary-Sanctions Exposure, Agentic Interaction Trust Gate, Gulf Maritime Exposure Gate, and Agent Output Verification. Public surfaces: [Middle Corridor Deal Risk Gate A2A endpoint](https://middle-corridor-deal-risk-gate-a2a.vassiliy-lakhonin.workers.dev) and [CIS Secondary-Sanctions Exposure browser demo](/cis-secondary-sanctions.html). Evidence triage only, not advice; illustrative usage.
- Agent-readable orientation file: `llms.txt`.
- Primary contracts: `schemas/v1/evidence-packet-request.schema.json` and `schemas/v1/evidence-packet-response.schema.json`.
- CLI package: `agenda-intelligence-md`.
- Release evidence: [v1.4.0 release](https://github.com/vassiliylakhonin/agenda-intelligence-md/releases/tag/v1.4.0) and [v1.3.0 release](https://github.com/vassiliylakhonin/agenda-intelligence-md/releases/tag/v1.3.0), [PyPI package](https://pypi.org/project/agenda-intelligence-md/), and green post-release smoke workflow.
- Source plans: sanctions, regulation, elections, conflict, technology/AI, markets, and regional monitoring.
- Evaluation assets: rubric, LLM judge prompt, human checklist, and sample cases.

## Project state (self-reported)
- Primary workflow: `agenda-intelligence check <packet.json>` auto-detects the evidence-packet shape; `--format json` supports agent/CI loops and `--strict` exits non-zero unless every claim is complete.
- Contract: the evidence-packet schemas are additive under `schemas/v1/`; older v1 request/memo contracts remain compatible.
- Distribution: PyPI package (`agenda-intelligence-md`), GitHub release wheel, editable source install, and plain Markdown protocol attachable to any agent.
- Compatibility layers: Markdown protocol, source plans, earlier validation/evaluation commands, MCP server, HTTP API shell, A2A adapter, and Cloudflare Worker profiles.
- Portfolio composition: Global Think Tank Analyst and both regional specialists now ship the same evidence-packet handoff, a synthetic packet, and a CI validator. Their packets run through this linter before human review.
- Commercial status: `portfolio-proof` / `build-to-learn`; no buyer, pilot, or product-market-fit claim.
- No production-usage, adoption, or benchmark numbers are claimed.

## Context
- AI agents increasingly produce claim-backed output, but their review packets can still contain missing source IDs, quotes that are absent from the named source, weak claim/source overlap, or numbers that do not appear in referenced text.
- A reviewer needs those packet defects surfaced before spending time on factual or substantive review.

## Challenge
The checker must be deterministic and useful in CI without pretending to prove truth. Lexical overlap can miss valid paraphrases and can overstate support when words overlap without entailment. The output therefore separates packet completeness from factuality and always requires human review.

## Delivery path
- Defined a small request contract: `claims[]` plus caller-supplied `sources[]`.
- Added deterministic checks for missing source IDs, quote presence, quote/source declaration consistency, lexical coverage, and unmatched numeric terms.
- Added a response contract with per-claim status, issues, reviewer actions, aggregate counts, explicit limitations, and `human_review_required: true`.
- Preserved legacy `check <agenda-brief.json>` behavior through shape auto-detection.
- Added golden/failure contract tests and kept top-level schemas byte-aligned with packaged wheel data.
- Added release-wheel smoke coverage so the published package—not only the source checkout—must execute the canonical packet.

## My contribution
- Defined the narrow packet-completeness boundary and kept it separate from factual verification.
- Built the request/response schemas, Python service function, CLI routing, example packet, tests, packaging sync, and release smoke path.
- Refocused the public README, manifests, plugin descriptions, and repository metadata while preserving older interfaces.
- Kept limitations explicit: lexical matching is not entailment, source discovery, source-authority assessment, or approval.

## Outcome
- Provides one inspectable first-run job instead of leading with every historical runtime surface.
- Returns machine-readable reviewer actions and a strict non-zero CI gate for incomplete packets.
- Preserves compatibility for existing agenda-brief, MCP, HTTP, A2A, and Worker users.
- Does not claim production adoption or standalone commercial demand.

## Runtime update — 2026-07
- **v1.4.0 MCP evidence-packet workflow** — the primary preflight is callable from MCP clients as `check_evidence_packet`, with `create_brief` and `append_evidence` for stateless contract-aware assembly and a runnable stdio example. Existing tool names, schemas, CLI commands, and response shapes stay compatible.
- **v1.3.0 evidence-packet preflight** — primary CLI/Python workflow, two additive schemas, packaged data parity, strict mode, release notes, PyPI wheel/sdist, and post-release smoke.
- **Shared reasoning-to-linter seam** — [Global Think Tank Analyst](https://github.com/vassiliylakhonin/global-think-tank-analyst/blob/main/docs/evidence-packet-handoff.md), [Central Asia + Caspian](https://github.com/vassiliylakhonin/central-asia-caspian-hybrid-intelligence-skill/blob/main/docs/evidence-packet-handoff.md), and [Gulf + Middle East](https://github.com/vassiliylakhonin/gulf-middle-east-hybrid-intelligence-skill/blob/main/docs/evidence-packet-handoff.md) now export the same claim/source packet shape. Each repo validates its own synthetic handoff in CI.
- **Seven live A2A workers** — general strategic-risk triage plus six vertical profiles: Middle Corridor, Kazakhstan Market Entry, CIS Secondary-Sanctions, Agentic Interaction Trust, Gulf Maritime Exposure, and Agent Output Verification. These are portfolio-grade public endpoints, not paid production deployments.
- **CIS Snapshot upstream** — the CIS profile now performs server-side possible-name matching against a compact public-list snapshot (OFAC / EU / UK) when active. It is a possible string match only, not identity verification, ownership resolution, or a sanctions determination.
- **Agent-readiness checks** — CLI and CI now include agent-card readiness linting and canon checklist coverage so published discovery surfaces do not drift from the runtime.
- **Confidential workflow scaffolds** — deterministic `weekly-delta` and `weekly-delta-bench` support alias-only evidence-readiness packets for confidential project status notes. Build-to-learn, no client names, no case-study traction claim.

## Trust-layer update — 2026-05

- **Threat model** ([`docs/threat-model.md`](https://github.com/vassiliylakhonin/agenda-intelligence-md/blob/main/docs/threat-model.md)) — honest accounting of what the validator catches versus what it does not. Ten classes of gaps the toolkit does **not** detect: factual correctness, semantic provenance correctness, source quality, recency truth, score gaming via stripped unsupported claims, JSON-projection drift, prompt-injection in processed content, adversarial structural inputs, cross-brief consistency, agent identity.
- **Known schema gaps** — flagged as observations (not commitments): no dedicated `data-integrity-notes` field on the brief schema; no `source-tier` field on evidence pack entries; no `retrieved_at` freshness assertion; no cross-claim consistency check.

Reframing for consumers: a passing brief means it passed a **structural** bar. It is not a brief that passed a **trust** bar. The two are different.

## Current outputs
- Packet status: `packet_complete`, `source_review_required`, or `packet_incomplete`.
- Per-claim missing source IDs and quote checks.
- Lexical-support status and coverage against referenced sources.
- Numeric values not found in referenced source text.
- Deduplicated reviewer actions.
- Explicit `factuality_status: not_assessed` and limitations.

## Regional lens packs

### Central Asia + Caspian
Focused on sanctions routing, corridor politics, Caspian chokepoints, banking/payment exposure, state leverage, energy, minerals, and regional political economy.

### Gulf + Middle East
Focused on Iran sanctions, GCC banking and sovereign wealth, energy markets, and Hormuz / Bab-el-Mandeb / Red Sea maritime exposure.

## Who it is for
- AI-agent builders who need a deterministic pre-review gate.
- Reviewers receiving claim-backed output and caller-supplied source text.
- Technical evaluators examining JSON contracts, packaging, and CI discipline.
- Teams willing to treat lexical support as a diagnostic, not proof of truth.

## Why it matters
It catches cheap-to-detect packet defects before a human spends time on substantive review. That narrows the first job and makes the limitation auditable.

**claims + supplied sources → deterministic packet checks → reviewer actions → human review**

## Tech stack
- Plain markdown.
- Python CLI package.
- JSON schemas.
- Evaluation toolkit.
- GitHub repository with CI validation.
- Agent-readable `llms.txt`.
- Codex-ready integration path.

## Relevance
This project demonstrates how I separate a narrow deterministic check from broader reasoning and from factual verification, then carry that boundary through schemas, packaging, CI, release automation, and public documentation.

## Compatibility example: before / after (illustrative)

> *Evidence mode: `reasoning-only`. Excerpt from a worked example in the repo, condensed for this page. Full example with the "what is wrong with the before" diagnosis and a side-by-side table: [`examples/before-after/sanctions-routing.md`](https://github.com/vassiliylakhonin/agenda-intelligence-md/blob/main/examples/before-after/sanctions-routing.md).*

**User question:** "Reports say more restricted goods may be moving through Central Asia to Russia. What does this mean?"

**Before — generic agent output:**

> Reports of restricted goods moving through Central Asia highlight the importance of sanctions compliance and supply-chain monitoring. Companies should ensure they conduct due diligence and monitor regulatory developments.

That is fluent and correct-sounding. It contains no signal classification, no specific transmission mechanism, no main uncertainty, and no falsifiable indicators.

**After — with the Agenda Intelligence MD protocol attached:**

- **Bottom line:** Treat as a compliance-relevant signal unless enforcement action, customs data, named firms, or regulator guidance escalate it. Key question: does suspected routing become a documented enforcement pattern.
- **Signal classification:** Weak signal → signal if supported by customs anomalies, designations, bank behavior, or named intermediaries.
- **What changed:** Central Asia is not a passive route; the relevant mechanisms are traders, customs brokers, banks, logistics firms, beneficial-ownership structures, and state tolerance for re-export revenue versus sanctions pressure.
- **Main uncertainty:** Whether the reports reflect isolated evasion cases, statistical noise, or a repeatable routing system.
- **Watch next:** sanctions designations; customs data by HS code; bank account closures; export-control advisories; named intermediaries; correspondent-banking behavior; customs-inspection changes.

The protocol does not make the agent sound smarter. It forces it to classify the signal, expose uncertainty, and name what would update the view.

## Portfolio context
Agenda Intelligence MD is the **evidence-packet linter** in the portfolio:

- **Evidence-packet checks** — Agenda Intelligence MD (this case study). Primary claim/source linter plus compatibility validation and transport surfaces.
- **Horizontal domain skill** — [Global Think Tank Analyst](https://github.com/vassiliylakhonin/global-think-tank-analyst). Reasoning method and memo modes, region- and topic-agnostic.
- **Vertical specialist** — [Central Asia + Caspian Hybrid Intelligence Skill](https://github.com/vassiliylakhonin/central-asia-caspian-hybrid-intelligence-skill). Region-deep reasoning for Central Asia, Caspian, sanctions, AML, banking, logistics, energy, and corridor risk.
- **Vertical specialist** — [Gulf + Middle East Hybrid Intelligence Skill](https://github.com/vassiliylakhonin/gulf-middle-east-hybrid-intelligence-skill). Region-deep reasoning for Iran sanctions, GCC finance and energy, sovereign wealth, and maritime chokepoint risk.
This repo does not duplicate its neighbors. Reasoning method and regional depth live in companion skill repos; this one provides the contracts, validators, and tooling.

## Project links
- GitHub repository: https://github.com/vassiliylakhonin/agenda-intelligence-md
- [v1.4.0 release](https://github.com/vassiliylakhonin/agenda-intelligence-md/releases/tag/v1.4.0)
- [v1.3.0 release](https://github.com/vassiliylakhonin/agenda-intelligence-md/releases/tag/v1.3.0)
- PyPI: https://pypi.org/project/agenda-intelligence-md/
- [Eval run: Agenda Intelligence MD, May 2026](/eval-agenda-intelligence-md-2026-05.html) — N=3 self-scored run against the protocol's own 8-criterion rubric.
- Companion horizontal proof: [Global Think Tank Analyst](/case-study-global-think-tank-analyst.html)
- Companion vertical proof: [Central Asia + Caspian Hybrid Intelligence Skill](/case-study-central-asia-caspian-skill.html)
- Companion vertical proof: [Gulf + Middle East Hybrid Intelligence Skill](/case-study-gulf-middle-east-skill.html)
- Live public surfaces: [Middle Corridor Deal Risk Gate A2A endpoint](https://middle-corridor-deal-risk-gate-a2a.vassiliy-lakhonin.workers.dev), [CIS Secondary-Sanctions Exposure browser demo](/cis-secondary-sanctions.html)