feat(cookbook): forensic-qoe — pre-LOI forensic QoE for private-company targets

[aniebyl]

Summary

Adds a managed-agent cookbook that runs a pre-LOI Quality-of-Earnings forensic screen on private-company acquisition targets. Same workflow as the OloLand Cowork plugin ololand-forensic-qoe, exposed as a headless cookbook for enterprise teams running diligence inside their own orchestration layer (Temporal / Airflow / Guidewire).

The cookbook drives the OloLand MCP server, which exposes deterministic financial engines (Beneish M-Score, Benford's Law, EBITDA bridge, revenue-quality deep dive, working-capital analysis, journal-entry testing, lapping detection) plus a 246-category risk taxonomy and a cross-document reconciler with source-hierarchy discipline (CPA-audited > tax > management > AI-extracted).

Output: a 1-page IC-defensible PDF (./out/forensic-screen-<deal>.pdf) plus a structured JSON receipt with every adjustment cited to a specific source document, page, and section.

Positioning: stage-1 pre-LOI screen, not a Big-4 QoE replacement. Big-4 forensic QoE runs $150K-$500K and 4-8 weeks. This cookbook runs the same seven-primitive battery in ~72h and produces the IC-defensible artifact that decides whether to commit Big-4 spend.

Why this belongs in the repo

The existing 10 cookbooks cover analyst-workflow and operations (pitch, research, earnings, modeling, GL recon, KYC, valuation review, close, statement audit, meeting prep). Forensic QoE is the underwriting-defensibility surface — different JTBD (IC red-pen, not analyst draft), different buyer (investment committee), different artifact (IC-defensible PDF with enforced citation discipline). It complements the existing cookbooks rather than duplicating any of them.

Security & three-tier isolation

Tier	Touches untrusted docs?	Tools	Connectors
document-reader	Yes	Read, Grep only	OloLand upload_deal_document only
forensic-runner / Orchestrator	No (reads through OloLand engines)	Read, Grep, Glob, Agent	OloLand (analyze + verify + read)
report-writer (Write-holder)	No	Read, Write, Edit	OloLand generate_forensic_screen_pdf + record_materialized_risks only

document-reader returns length-capped, schema-validated JSON. Document contents are routed through OloLand's ingestion pipeline (Qdrant embeddings + cross-doc reconciler) rather than read by the orchestrator turn — prompt-injection inside a source PDF cannot reach the forensic-runner or the report-writer. If the cross-document reconciler raises a gap on a required metric (revenue / EBITDA / net debt / total debt), the cookbook halts before PDF generation — forensic QoE on top of an unresolved source-document disagreement is not defensible.

Validation

• All 4 YAML manifests + steering-examples.json parse cleanly.
• scripts/deploy-managed-agent.sh forensic-qoe --dry-run resolves the full manifest (orchestrator + 3 subagents) and posts a clean payload to POST /v1/agents without errors.

Test plan

• Provision an OloLand agent key at app.ololand.ai/settings/api-keys, set OLOLAND_MCP_URL=https://api.ololand.ai/mcp plus an Authorization: Bearer olo_agent_sk_* header, and run scripts/deploy-managed-agent.sh forensic-qoe against a sandbox deal.
• Steer with one of the events in steering-examples.json and verify the PDF + JSON receipt land in ./out/.
• Verify record_materialized_risks write-back lands in OloLand's deal record.
• Confirm the cookbook halts cleanly when verify_sponsor_assumptions raises a reconciliation gap.

Strategic context

Anthropic ships the policy gradient (the 10 finance agents + JV + MCP connector grid); OloLand ships the verifier stack (deterministic financial engines + risk taxonomy + cross-document reconciliation + persistent deal record). This cookbook is the wedge that lets the JV's enterprise customers invoke OloLand's IC-defensible forensic screen from inside an Anthropic-managed agent run — without leaving the Claude Platform.

If the maintainers prefer this live under plugins/partner-built/ololand/ rather than alongside the first-party cookbooks, happy to move it — let us know.

🤖 Generated with Claude Code

[RJK134]

Hey @ololand-ai — did a mechanical pre-review pass on this PR (not a maintainer, just trying to clear the queue so Anthropic FSI's substantive review-time is spent on the right things). Two items worth addressing before someone with merge rights picks this up:

⚠️ Branch is behind main

The diff currently shows deletions of files that were merged upstream after this PR was opened — .githooks/pre-commit, .github/workflows/version-bump.yml, scripts/version_bump.py, the claude-for-msft-365-install sideload scripts, and a scripts/check.py regression. Merging as-is would remove the version-bump infrastructure that #208 introduced.

A git fetch upstream && git rebase upstream/main (or merge-from-main) should resolve all of these cleanly — none of them touch managed-agent-cookbooks/forensic-qoe/, so no real conflicts expected.

Question on the standalone pattern (not necessarily a blocker)

Every other cookbook in managed-agent-cookbooks/ uses system: file: ../../plugins/agent-plugins/<slug>/agents/<slug>.md so the system prompt is shared with a Cowork plugin counterpart in plugins/agent-plugins/<slug>/. This cookbook uses inline system: text: and has no corresponding plugin-side mirror — the README notes the Cowork equivalent lives in OloLand's own repo.

That asymmetry is fine if intentional, but it's worth confirming with maintainers since it sets precedent for vendor-driven cookbooks that don't follow the "two ways from one source" pattern. Could be worth a brief note in the PR description.

✅ Mechanical pass is otherwise clean

For reference:

• python3 scripts/check.py passes (all 7 required files present, all callable_agents.manifest refs resolve, all YAML parses)
• Subagent output schemas have appropriately restrictive regex patterns
• 3-tier isolation architecture (document-reader / forensic-runner / report-writer with Write only on the last) is sound

Substantive review (forensic methodology, security tier, vendor-MCP-dependency precedent, exec-summary positioning) is still on maintainers — not in scope of this mechanical pass.

Hope this helps move it along.