Update to OloLand DD

{
  "description": "Use when an OloLand artifact (CIM section, IC memo paragraph, risk narrative, DCF write-up) needs to be verified against the deal's source documents and deterministic engine runs — e.g. before partner review, before IC submission, or to spot-check a number that \"looks off\". Explains the four atomic-claim verifiers, what each catches, what each misses, and the right interpretation of PASS/FAIL.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 452
    }
  ],
  "name": "verifier-stack",
  "skill_md_contents": "---\nname: verifier-stack\ndescription: \"Use when an OloLand artifact (CIM section, IC memo paragraph, risk narrative,\\\n  \\ DCF write-up) needs to be verified against the deal's source documents and deterministic\\\n  \\ engine runs \\u2014 e.g. before partner review, before IC submission, or to spot-check\\\n  \\ a number that \\\"looks off\\\". Explains the four atomic-claim verifiers, what each\\\n  \\ catches, what each misses, and the right interpretation of PASS/FAIL.\"\n---\n\n# Verifier Stack\n\nOloLand's verifier stack mechanically checks that every number in an artifact is supported by the deal's source documents, that every citation marker points at a real retrievable chunk, and that the deal's stored DCF identities hold. It is the \"defend every number, cite every source\" guarantee in code, not in marketing copy.\n\n## What the verifiers actually do\n\n### `verify_inline_numbers`\n\nExtracts every dollar amount and every percentage from the artifact text. For each number, checks whether it appears (within 5% relative / 0.5pt absolute tolerance) in at least one chunk retrieved from the deal corpus.\n\n- **Catches:** fabricated revenue figures, transposed digits (e.g. $34.2M vs $32.4M), unit drift (`$304K` reported as `$304M`).\n- **Misses:** numbers that happen to appear in the corpus by coincidence (e.g. a generic \"$1M\" mentioned in a risk factor section); numbers that are derived but never raw in the source (e.g. growth rates the analyst computed correctly but the chunk only shows the underlying revenues).\n\n### `verify_claim_chunks`\n\nStricter than `verify_inline_numbers`. Splits the text into sentences containing financial numbers. A sentence passes only when **all** of its numbers can be matched in a single chunk.\n\n- **Catches:** sentences that stitch together unrelated numbers from different sources (a tell for hallucinated synthesis).\n- **Misses:** the same coincidence cases as above.\n\n### `verify_citation_existence`\n\nFor artifacts that use the legacy `[Source: file=..., p.N]` block format: extracts every block and validates that the filename exists in the deal's document set (with fuzzy matching) and the cited page is in range.\n\n- **Catches:** invented filenames, wrong page numbers.\n- **Skipped:** when the artifact uses the modern `[N]` marker format only — that's audited by `check_citation_coverage`.\n\n### `verify_dcf_arithmetic`\n\nReplays the two DCF identities against the deal's most recent `DCFRun`:\n\n1. `enterprise_value == pv_fcf_sum + pv_terminal_value`\n2. `equity_value == enterprise_value - net_debt`\n\nTolerance: 0.1% relative.\n\n- **Catches:** internally inconsistent DCF models — a load-bearing check, because every number cited from a broken DCF is suspect even if it appears verbatim in the source.\n- **Status `no_data`** when the deal has no `DCFRun` — pass `include_dcf_arithmetic=false` if the artifact does not reference a DCF.\n\n### `check_citation_coverage` (`[N]` marker audit)\n\nCounts `[N]` markers in the artifact, retrieves the same chunk set the verifier uses, and reports markers that fall outside the available range. The orchestrator drops out-of-range markers at turn end; this lets external callers see the same view.\n\n- **Catches:** markers the model invented (e.g. `[12]` when only 8 chunks were retrieved).\n- **Misses:** markers that are in-range but cite the wrong chunk (use `verify_claim_chunks` for that).\n\n### `reconcile_documents`\n\nWalks the CPA > tax > management > AI source hierarchy across `FinancialDataSnapshot` and `AIExtractedFinancialMetric` observations. Returns per-metric reconciliation status (reconciled / discrepancy / unverified), recommended values, discrepancy spreads, and overall confidence.\n\n- **Catches:** silent disagreements between CPA-audited financials and management-supplied numbers; AI-extracted figures that contradict primary sources.\n- **Use when:** the artifact is going to IC or a regulator-facing deliverable. Skip for back-of-envelope work — it's heavier than the per-number verifiers.\n\n## Interpreting the verdict\n\n| Outcome | Meaning |\n|---|---|\n| `passed: true` | Every enabled verifier passed. The artifact is mechanically defensible. |\n| `passed: false`, `citations_available: 0` | Verifier could not retrieve any chunks for the deal. **Not a fail of the artifact — a fail of the corpus.** Re-ingest documents and re-run. |\n| Inline numbers FAIL, claim chunks PASS | Unusual — usually means a small number is uncited but each whole sentence is otherwise grounded. Investigate the specific `unsupported` entries. |\n| Inline numbers PASS, claim chunks FAIL | A claim sentence mixes a verified number with an unverified one. Common in hallucinated synthesis. Fix the offending sentence. |\n| DCF arithmetic `no_data` | No `DCFRun` for this deal. Either run DCF first, or pass `include_dcf_arithmetic=false`. |\n| `out_of_range_dropped` non-empty | The model invented citation markers. Re-run the generator with stricter prompt grounding, or strip the invalid markers. |\n\n## What the verifier is NOT\n\n- **Not a fact-checker for prose.** It does not judge whether a qualitative claim (\"the company has strong moats\") is true. It only checks numbers and citations.\n- **Not a grader.** It is a precondition for grading. A high grader score on an artifact with verifier-FAIL is structurally suspect.\n- **Not a replacement for human IC review.** It catches the mechanical failure modes (fabricated numbers, dangling citations, broken DCF identities). Strategic, judgment-based review still belongs with the partner.\n\n## Methodology references\n\n- Atomic-claim verifiers: `backend/services/ai/scorers/inline_number_verifier.py`, `claim_chunk_verifier.py`, `citation_existence_checker.py`\n- DCF identity check: `backend/services/harness/dd_tools.py::_verify_dcf_arithmetic`\n- Source hierarchy + reconciliation: `backend/services/financial/cross_doc_reconciler.py`\n- Citation-marker validation: `backend/services/agent_runtime/orchestrator.py::validate_citation_markers`\n\nCompanion command: `ololand-dd-verify`.\n\n\n## OpenAI execution requirements\n\nUse the connected MCP server's current tool schemas. Do not invent tool arguments, job-status endpoints, inputs, or outputs. If a referenced tool is unavailable, explain the limitation and request the needed connection or data. Invoke writes only when the user has requested the corresponding action. Do not initiate purchases or payments. An unrun, unsupported, or unavailable procedure is a gap, never a passing result.\n\n\nOpenAI cannot execute local lifecycle hooks. Use the packaged explicit setup/review workflow when requested. Server-side MCP auditing remains authoritative; preserve evidence blockers and human-only approval gates.\n\nClaim-correction submission is unsupported in this OpenAI upload because the current handler records surface=cowork. Do not invoke submit_agent_claim_correction from OpenAI. Explain the limitation and retain proposed correction text for human review without claiming submission. See unsupported-workflows.json for the excluded canonical workflow.\n"
}