kc-beta 0.1.0

package/template/skills/en/meta/compliance-judgment/references/output-format.md

@@ -0,0 +1,151 @@
+# Lightweight Output Format Specification
+
+This document defines the compact text markup format for verification results, its grammar, JSON conversion rules, and edge case handling.
+
+## Grammar
+
+```
+[RESULT] field_name <- value (constraint) | conf:score | src:location | note:text
+```
+
+| Component | Required | Format | Description | Example |
+|-----------|----------|--------|-------------|---------|
+| `[RESULT]` | Yes | One of: PASS, FAIL, MISSING, ERROR, UNCERTAIN | The judgment outcome. | `[FAIL]` |
+| `field_name` | Yes | snake_case identifier | The rule or field being checked. | `capital_adequacy` |
+| `<- value` | No (omit for MISSING) | Free text, no pipes | The extracted value from the document. | `<- 12.5%` |
+| `(constraint)` | No (omit if no constraint) | Parenthesized expression | The expected value or condition. | `(>= 8.0%)` |
+| `conf:score` | Yes | Decimal 0.00-1.00 | Confidence score of the judgment. | `conf:0.95` |
+| `src:location` | No | Page-section reference or trace ID prefix | Source location in the document. | `src:p3-s2` |
+| `note:text` | No | Free text to end of line | Human-readable comment. | `note:Signing overdue by 45 days` |
+
+Components after `field_name` are separated by ` | ` (space-pipe-space). The `<- value` and `(constraint)` components appear before the first pipe, space-separated.
+
+## Field Definitions
+
+### Result Values
+
+| Value | Meaning | When to Use |
+|-------|---------|-------------|
+| `PASS` | Entity complies with the rule. | Deterministic or semantic check confirms compliance. |
+| `FAIL` | Entity does not comply. | Clear non-compliance detected. Note is strongly recommended. |
+| `MISSING` | Entity not found in document. | Extraction could not locate the required field. |
+| `ERROR` | Processing failure. | Parsing error, API timeout, unexpected format. |
+| `UNCERTAIN` | Ambiguous judgment. | Borderline values, conflicting evidence, low confidence. |
+
+### Confidence Score
+
+A decimal between 0.00 and 1.00 representing the system's confidence in the result. For deterministic Python checks, confidence is typically 0.95-1.00. For LLM semantic judgments, confidence reflects the model's self-assessed certainty. Scores below the configured threshold in `.env` trigger human review.
+
+### Source Location
+
+The `src:` component uses a compact reference format: `p{page}-s{section}`. Example: `src:p3-s2` means page 3, section 2. For trace ID integration, use the trace ID prefix: `src:R001-DOC042-P3-S2` (see Integration with Trace IDs below).
+
+## JSON Conversion
+
+### Markup to JSON
+
+```
+Input:  [FAIL] sign_date_gap <- 75d (<= 30d) | conf:0.90 | src:p1-s4 | note:Signing overdue by 45 days
+
+Output:
+{
+  "field": "sign_date_gap",
+  "result": "fail",
+  "extracted_value": "75d",
+  "expected": "<= 30d",
+  "confidence": 0.90,
+  "source": "p1-s4",
+  "comment": "Signing overdue by 45 days"
+}
+```
+
+Pseudocode:
+1. Parse `[RESULT]` -> lowercase -> `result` field.
+2. Parse next token -> `field` field.
+3. If `<-` follows, parse until `(` or `|` -> `extracted_value`.
+4. If `(...)` follows, parse contents -> `expected`.
+5. Split remaining by ` | `. For each segment:
+   - `conf:X` -> `confidence` (parse as float).
+   - `src:X` -> `source`.
+   - `note:X` -> `comment`.
+
+### JSON to Markup
+
+Pseudocode:
+1. `[` + uppercase(`result`) + `] ` + `field`.
+2. If `extracted_value` exists: ` <- ` + `extracted_value`.
+3. If `expected` exists: ` (` + `expected` + `)`.
+4. ` | conf:` + format(`confidence`, 2 decimal places).
+5. If `source` exists: ` | src:` + `source`.
+6. If `comment` exists: ` | note:` + `comment`.
+
+## Diff Example
+
+Comparing two verification runs is where markup shines.
+
+**Markup diff** (clean, scannable):
+```
+  [PASS] capital_adequacy <- 12.5% (>= 8.0%) | conf:0.95 | src:p3-s2
+- [PASS] sign_date_gap <- 28d (<= 30d) | conf:0.92 | src:p1-s4
++ [FAIL] sign_date_gap <- 75d (<= 30d) | conf:0.90 | src:p1-s4 | note:Signing overdue by 45 days
+  [MISSING] collateral_value | conf:0.60 | note:Collateral valuation not found
+```
+
+**JSON diff** (noisy, hard to scan):
+```json
+  {
+    "field": "sign_date_gap",
+-   "result": "pass",
++   "result": "fail",
+-   "extracted_value": "28d",
++   "extracted_value": "75d",
+    "expected": "<= 30d",
+-   "confidence": 0.92,
++   "confidence": 0.90,
+    "source": "p1-s4",
+-   "comment": ""
++   "comment": "Signing overdue by 45 days"
+  }
+```
+
+The markup diff communicates the same information in one changed line vs. five changed lines.
+
+## Edge Cases
+
+### Multi-Value Fields
+When a field has multiple extracted values (e.g., the same metric appears in two places with different values), separate values with semicolons:
+```
+[UNCERTAIN] total_assets <- 1,234,567;1,234,590 | conf:0.50 | src:p3-s1;p7-s2 | note:Conflicting values found
+```
+
+### Long Notes
+In markup, truncate notes longer than 80 characters with `...`. The full text is preserved in JSON. Example:
+```
+[FAIL] risk_disclosure <- (see detail) | conf:0.85 | note:Missing discussion of liquidity risk, market risk, and operational ri...
+```
+
+### Special Characters
+If a value or note contains the pipe character `|`, escape it with a backslash: `\|`. During JSON conversion, unescape back to `|`.
+
+### Fields with No Constraint
+Omit the parenthetical entirely:
+```
+[MISSING] collateral_value | conf:0.60 | note:Collateral valuation not found in document
+```
+
+### Fields with No Extracted Value
+Omit the `<-` component (common for MISSING and ERROR results):
+```
+[ERROR] capital_adequacy | conf:0.00 | note:PDF parsing failed on page 3
+```
+
+## Integration with Trace IDs
+
+The `src:` component can encode trace ID prefixes, linking each result line to the full trace ID defined by `version-control`. Use the trace ID format directly:
+
+```
+[PASS] capital_adequacy <- 12.5% (>= 8.0%) | conf:0.95 | src:R001-DOC042-P3-S2
+[FAIL] sign_date_gap <- 75d (<= 30d) | conf:0.90 | src:R003-DOC042-P1-S4 | note:Signing overdue by 45 days
+```
+
+When converting to JSON, the `src:` value maps to the `trace_id` field in the full result object. The character range (`C{start}:{end}`) can be appended when full precision is needed: `src:R001-DOC042-P3-S2-C120:180`.

package/template/skills/en/meta/confidence-system/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: confidence-system
+description: Design and calibrate confidence scoring for extraction and verification results. Use when building any workflow that needs to quantify trust in its output, when setting up quality control sampling thresholds, or when calibrating existing confidence scores against actual accuracy. Confidence is the bridge between workflows and quality control — high confidence means less review, low confidence means more review. Also use when the quality control skill reports that confidence scores do not correlate with actual correctness.
+---
+
+# Confidence System
+
+Confidence is not about the model's certainty — it is about your system's track record. A confidence score should predict: "If I see this score, how likely is the result to be correct?" If your 0.9 confidence results are correct 90% of the time, your confidence system is calibrated.
+
+## Why Confidence Matters
+
+Without confidence, you have two choices:
+1. Review everything (expensive, defeats the purpose of automation).
+2. Review nothing (risky, errors slip through).
+
+With confidence, you can review intelligently: spend your review budget where errors are most likely.
+
+## Composite Scoring
+
+Confidence for a single extraction or judgment result should combine multiple signals. No single signal is reliable enough on its own.
+
+### Signal: Extraction Method Prior
+How inherently reliable is the extraction method?
+- Regex match with validated format: 0.90-0.95
+- LLM extraction with structured output: 0.75-0.85
+- LLM extraction with free-form output: 0.60-0.75
+- Fallback or inferred value: 0.40-0.50
+
+This is a prior — it reflects the method's general reliability, not this specific result.
+
+### Signal: Source Text Presence
+Was the extracted value clearly present in the source text?
+- Exact string found in source: high signal
+- Approximate match found: medium signal
+- No matching text in source (model inferred or generated): low signal
+
+This catches hallucination. If the model claims "capital adequacy ratio is 12.5%" but "12.5" does not appear anywhere in the source section, that is a red flag.
+
+### Signal: Historical Accuracy
+How often has this rule, on this document type, with this extraction method, been correct in the past?
+- First iteration (no history): use the method prior only.
+- After QC reviews: compute actual accuracy and blend it in.
+
+This is the most valuable signal over time. It reflects real performance, not assumptions.
+
+### Signal: Corner Case Proximity
+Does this document match any known corner case pattern?
+- Exact match: lower confidence (the standard workflow may not apply).
+- Near miss: slightly lower confidence.
+- No match: neutral (no adjustment).
+
+### Combining Signals
+
+Start with a simple weighted average:
+
+```
+confidence = w1 * method_prior + w2 * source_presence + w3 * historical_accuracy + w4 * corner_case_adjustment
+```
+
+Initial weights (adjust through calibration):
+- w1 (method): 0.25
+- w2 (source): 0.25
+- w3 (history): 0.35 (most important once available)
+- w4 (corner case): 0.15
+
+When historical accuracy is not yet available (early iterations), redistribute its weight to the other signals.
+
+## Threshold Bands
+
+Define bands that map confidence to review action:
+
+| Band | Confidence Range | Action |
+|------|-----------------|--------|
+| High | Above auto-accept threshold | Spot-check only (5-10% random sample) |
+| Medium | Between thresholds | Sample at MONITOR_FREQUENCY rate |
+| Low | Below full-review threshold | Review every result |
+
+Starting thresholds: auto-accept = 0.85, full-review = 0.60. These are defaults — calibrate per rule.
+
+## Calibration
+
+Calibration is the process of checking: "Do my confidence scores actually predict accuracy?"
+
+### How to Calibrate
+
+After each QC review cycle:
+1. Group reviewed results by confidence band (e.g., 0.0-0.2, 0.2-0.4, ..., 0.8-1.0).
+2. For each band, compute the actual accuracy (% of results that QC confirmed as correct).
+3. Compare actual accuracy to the confidence band's midpoint.
+4. If they match (0.8-0.9 band has ~85% actual accuracy), the system is calibrated.
+5. If they diverge (0.8-0.9 band has only 60% actual accuracy), the confidence is overestimated — adjust weights.
+
+### When to Recalibrate
+
+- After the first QC review cycle (establishing initial calibration).
+- After a workflow version change (new code may have different reliability characteristics).
+- After confidence thresholds are adjusted.
+- When the QC skill reports that confidence does not predict correctness.
+
+## Integration Points
+
+- **Entity extraction** assigns initial confidence based on method prior and source presence.
+- **Compliance judgment** may adjust confidence based on the complexity of the judgment.
+- **Quality control** uses confidence bands to determine review sampling.
+- **Evolution loop** uses confidence trends to detect degradation.
+- **Dashboard** displays confidence distribution for developer user visibility.
+
+## Keep It Simple Initially
+
+Do not over-engineer the confidence system upfront. Start with the method prior alone:
+- Regex: 0.90
+- LLM: 0.75
+- Fallback: 0.50
+
+Run QC on the first few batches. See whether these scores predict actual accuracy. If they do, you are done for now. If they do not, add signals incrementally.
+
+The confidence system should earn its complexity, not start with it.

package/template/skills/en/meta/corner-case-management/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: corner-case-management
+description: Identify, catalog, and handle corner cases that do not fit the mainstream verification workflow. Use when the evolution loop classifies a failure as a corner case (affecting less than ~10% of documents), when adding a new edge case to the registry, or when deciding whether a corner case should be promoted to a systemic fix. Also use when designing the corner case detection mechanism for a workflow.
+---
+
+# Corner Case Management
+
+A good workflow handles 90% of cases cleanly. Corner cases are the other 10%. They are individually rare but collectively significant. The key insight: do NOT patch the main workflow to handle them. That leads to spaghetti logic, fragile code, and regressions.
+
+Instead, maintain a separate registry. Check incoming documents against the registry before the standard workflow. Handle matches with specific resolutions.
+
+## Philosophy
+
+Corner cases are a fact of life in document verification. Financial documents are produced by thousands of different organizations, each with their own formatting quirks, templates, and interpretations of regulations. No workflow will handle every variant.
+
+The question is not "how do I eliminate corner cases?" but "how do I manage them efficiently?"
+
+The answer is: separate them from the main logic. Keep the workflow clean. Keep the corner cases cataloged, detectable, and resolvable.
+
+## The Corner Case Registry
+
+A structured file (`corner_cases.json`) in the rule skill's `assets/` directory:
+
+```json
+[
+  {
+    "id": "CC001",
+    "rule_id": "R001",
+    "description": "Some reports express capital adequacy as a decimal (0.125) instead of percentage (12.5%)",
+    "affected_documents": ["report_bank_xyz_2024.pdf"],
+    "detection_pattern": {
+      "type": "regex",
+      "pattern": "资本充足率[：:]*\\s*0\\.\\d+",
+      "confidence_threshold": 0.8
+    },
+    "resolution": {
+      "type": "code",
+      "action": "Multiply extracted value by 100 before threshold comparison",
+      "code_snippet": "if value < 1.0: value *= 100"
+    },
+    "discovered_at": "2026-04-01",
+    "iteration": 3,
+    "status": "active"
+  }
+]
+```
+
+Each entry captures:
+- **What** the corner case is (description).
+- **How to detect** it (detection pattern with type: regex, keyword, structural, or model-based).
+- **How to resolve** it (resolution with type: code, regex, prompt, or manual).
+- **When** it was discovered and in which iteration.
+- **Status**: active, promoted (moved to main workflow), or deprecated.
+
+## Detection During Execution
+
+Before running the standard workflow on a document:
+
+1. Load the corner case registry for the relevant rule.
+2. Check the document against each active corner case's detection pattern.
+3. If a match exceeds the confidence threshold, apply the specific resolution instead of (or in addition to) the standard workflow.
+4. Log that a corner case was triggered.
+
+This is similar to a RAG pipeline with progressive disclosure:
+- The registry is the knowledge base.
+- Detection patterns are the retrieval queries.
+- High confidence thresholds prevent false matches.
+- Only relevant corner cases are loaded into context.
+
+## When to Add a Corner Case
+
+Add a corner case when:
+- The evolution loop classifies a failure as non-systemic (affects <10% of documents).
+- The failure has a recognizable, describable pattern.
+- The resolution is clear and self-contained.
+
+Do NOT add a corner case when:
+- The failure affects many documents (that is a systemic issue — fix the workflow).
+- The failure has no discernible pattern (that may be a data quality issue — escalate to developer user).
+- The resolution would require changing the core judgment logic (that belongs in the main workflow).
+
+## When to Promote a Corner Case
+
+A corner case should be promoted to the main workflow (i.e., the resolution becomes part of the standard logic) when:
+- It starts appearing in >10% of documents. It is no longer a corner case — it is a pattern.
+- Multiple similar corner cases suggest a common underlying issue.
+- The developer user explicitly says "this is how it always works."
+
+When promoting, remove the corner case from the registry and update the workflow. Version both changes.
+
+## Human Visibility
+
+The corner case registry must be readable and manageable by the developer user:
+- Format it clearly (JSON or a markdown table).
+- Include enough context that a domain expert can understand each case without reading the code.
+- Report new corner cases in the dashboard.
+- Allow the developer user to add corner cases from their own expertise.
+
+Developer users often know about edge cases that the coding agent has not yet encountered. They should be able to add entries like:
+- "Bank XYZ always uses a different template for their Q4 reports."
+- "Mutual fund documents from before 2020 follow the old regulation format."
+
+These are valuable inputs that prevent future failures.
+
+## Corner Case Cost
+
+Every corner case has a runtime cost: the detection check runs on every document. Keep the registry lean:
+- Remove deprecated corner cases.
+- Merge similar corner cases into a single entry with a broader pattern.
+- Keep detection patterns efficient (prefer regex over LLM-based detection).
+- Monitor the registry size. If it grows beyond ~50 entries for a single rule, that suggests the workflow itself needs improvement.

package/template/skills/en/meta/cross-document-verification/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: cross-document-verification
+description: Perform case-level analysis across multiple documents for the same transaction. Use when documents do not exist in isolation — main contracts have appendices, loan applications come bundled with income certificates, bank statements, credit reports, and property appraisals. Use to build comparison matrices, detect contradictions (hard mismatches and soft implausibilities), classify severity, and flag fraud signals. Also use when user or end-user reports a cross-document inconsistency — these reports are ground truth and take priority over agent judgment.
+---
+
+# Cross-Document Verification
+
+Single-document verification asks: does this document comply with the rules? Cross-document verification asks a different question: do all the documents in this transaction tell a consistent story?
+
+This is the difference between a document checker and a case analyst. A document checker reviews files one at a time. A case analyst lays them all on the table and looks for the threads that connect — or contradict — each other. When you activate cross-document verification, you are upgrading the system from checker to analyst.
+
+## The Case Concept
+
+A case is the set of documents that belong to one transaction, one borrower, or one deal. Documents within a case share entities: names, dates, amounts, identifiers. These shared entities are your anchors for comparison.
+
+Two common case patterns:
+
+1. **Main contract + appendices/supplements.** Same issuer, formally cross-referenced. The main contract states the total, the appendices break it down. The main contract references Appendix B; Appendix B must exist and match. The team has extensive experience with inconsistencies in this pattern — totals that do not match line item sums, referenced appendices that are missing or outdated, version mismatches between main body and supplements.
+
+2. **Multi-source bundle.** Loan application + income certificate + bank statement + credit report + property appraisal. Different issuers, different formats, same borrower. The applicant's name, ID number, income, and employment must be consistent across all documents.
+
+In both patterns, the shared entities are the anchors. Every anchor that appears in more than one document is a candidate for cross-verification.
+
+## Building the Comparison Matrix
+
+The comparison matrix is the core artifact. Rows are shared fields. Columns are source documents. Each cell contains the value found in that document for that field, or is marked absent.
+
+Example matrix for a loan case:
+
+| Field | Application | Income Cert | Bank Statement | Credit Report |
+|-------|-------------|-------------|----------------|---------------|
+| Applicant name | Zhang Wei | Zhang Wei | Zhang Wei | Zhang W. |
+| ID number | 310...1234 | 310...1234 | — | 310...1234 |
+| Monthly income | 85,000 | 82,000 | avg 43,000 | — |
+| Employer | ABC Corp | ABC Corp Ltd | — | ABC Corporation |
+| Employment start | 2019-03 | 2019-06 | — | 2019 |
+
+Example matrix for a contract + appendices case:
+
+| Field | Main Contract | Appendix A | Appendix B |
+|-------|---------------|------------|------------|
+| Total amount | 5,000,000 | — | 4,850,000 (sum of items) |
+| Party B name | Shenzhen XX Co. | Shenzhen XX Co., Ltd | Shenzhen XX Co. |
+| Effective date | 2024-01-15 | 2024-01-15 | 2024-02-01 |
+
+Populate the matrix using output from `entity-extraction`. An empty cell means the field was not found in that document — this is absence, not necessarily an error. But absence in a field that should be present is itself a finding.
+
+## Contradiction Types
+
+### Hard Contradictions
+
+Exact mismatches in fields that must be identical across documents:
+
+- **Identity mismatch**: Name spelled differently, ID number differs by digits, date of birth inconsistent.
+- **Amount mismatch**: Main contract states 5,000,000 but appendix line items sum to 4,850,000. Income certificate says 82,000/month but application says 85,000/month.
+- **Date mismatch**: Contract effective date in the main body differs from the date in an appendix.
+
+Hard contradictions are binary. Either the values match (within defined tolerance) or they do not.
+
+### Soft Contradictions
+
+Values that are not directly inconsistent but are implausible when considered together:
+
+- Monthly income claimed as 100,000 but bank statement average deposits are 5,000.
+- Property appraised at 3,000,000 but loan amount is 2,800,000 (93% LTV — technically possible but suspicious).
+- Employment start date 2019-03 on the application but 2019-06 on the income certificate — a 3-month gap that could be rounding or could be fabrication.
+
+Soft contradictions require thresholds and judgment. They are findings, not verdicts.
+
+### Cross-Reference Failures
+
+Structural integrity problems within formally linked documents:
+
+- Main contract references "Appendix B — Payment Schedule" but Appendix B is titled "Technical Specifications" or is missing entirely.
+- Appendix references a clause in the main contract that does not exist in the provided version.
+- Missing reciprocal reference: Appendix C references the main contract, but the main contract does not list Appendix C.
+- Version mismatch: main contract dated January, appendix dated March with different terms.
+
+See `references/contradiction-taxonomy.md` for the full field-level taxonomy with tolerances and severity classifications.
+
+## Severity Classification
+
+Not all contradictions are equal. Classify by impact:
+
+| Severity | Criteria | Example |
+|----------|----------|---------|
+| **Critical** | Identity field mismatch | ID number differs between documents |
+| **High** | Financial amount discrepancy > 10% | Income 85K vs bank avg 43K |
+| **Medium** | Date or employment detail mismatch | Employment start date 3 months apart |
+| **Low** | Formatting or abbreviation difference | "ABC Corp" vs "ABC Corp Ltd" |
+
+The developer user sets severity thresholds per field in the project configuration. The defaults above are starting points. Adjust based on the business context — in some scenarios, a 5% amount discrepancy is critical; in others, 15% is acceptable.
+
+## Fraud Signal Patterns
+
+Cross-document analysis reveals patterns that single-document review cannot detect. Flag these — do not accuse, flag:
+
+- **Consistent small discrepancies across documents.** Income inflated by exactly 5% in every document. Dates shifted by exactly one month. This consistency in error suggests coordinated fabrication rather than honest mistakes.
+- **Suspicious document consistency.** Multiple documents from supposedly different issuers use identical formatting, identical phrasing, or identical typos. Legitimate documents from different organizations look different.
+- **Values at regulatory thresholds.** LTV ratio at exactly 69.9% when the limit is 70%. DTI at exactly 49.8% when the limit is 50%. One occurrence is coincidence. A pattern across the case is a signal.
+- **Temporal impossibilities.** Income certificate issued before the employment start date. Bank statement covering a period before the account opening date. Appraisal dated after the loan disbursement.
+
+These are signals for escalation, not conclusions. Present them with evidence and let the developer user or downstream review process make the determination.
+
+## Workflow Sequence
+
+The recommended sequence for cross-document verification within a case:
+
+1. **Identify the case boundary.** Which documents belong together? Use shared identifiers (borrower name, loan number, contract reference) to group documents into cases.
+2. **Extract anchors.** Run `entity-extraction` on each document independently. Collect the shared fields.
+3. **Build the matrix.** Populate the comparison matrix. Flag empty cells.
+4. **Detect contradictions.** Apply hard/soft/cross-reference checks per `references/contradiction-taxonomy.md`.
+5. **Classify severity.** Assign severity per the configured thresholds.
+6. **Scan for fraud signals.** Run pattern checks across the matrix.
+7. **Produce the report.** Output the case-level consistency report with all findings.
+
+## Integration
+
+**Inputs:**
+- Entity extraction results from `entity-extraction` (the raw field values per document).
+- Compliance judgment results from `compliance-judgment` (per-document pass/fail already computed).
+
+**Outputs:**
+- Case-level consistency report: the comparison matrix, all contradictions found, severity classifications, and fraud signal flags.
+
+**Feeds into:**
+- `confidence-system`: Cross-document contradictions lower confidence in affected fields.
+- `evolution-loop`: Recurring contradiction patterns trigger workflow refinement.
+- `dashboard-reporting`: Case-level view alongside document-level results.
+
+**Ground truth principle:** User and end-user contradiction reports feed back as ground truth. When a user or end-user reports a cross-document inconsistency that the system missed, that report is prior to agent judgment. Log it, learn from it, and adjust detection thresholds accordingly. The system's job is to catch what humans catch — and then go further.

package/template/skills/en/meta/cross-document-verification/references/contradiction-taxonomy.md

@@ -0,0 +1,73 @@
+# Contradiction Taxonomy
+
+Field-level reference for cross-document contradiction detection. Use this taxonomy to configure comparison rules per field type.
+
+## Identity Fields
+
+| Field | Match Type | Tolerance | Severity | Notes |
+|-------|-----------|-----------|----------|-------|
+| Full name | Fuzzy | Abbreviation, spacing, honorifics | Critical | "Zhang Wei" vs "Zhang W." is fuzzy match; "Zhang Wei" vs "Li Ming" is hard fail |
+| ID number | Exact | None (zero tolerance) | Critical | Single-digit difference = different person or transcription error — both critical |
+| Date of birth | Exact | None | Critical | Cross-check against ID number encoding where applicable |
+| Address | Fuzzy | Abbreviation, floor/unit formatting | Medium | "Rm 1201, Bldg A" vs "Room 1201, Building A" is acceptable |
+| Phone number | Exact | Country code prefix | Medium | +86 prefix presence/absence is tolerated |
+| Company name | Fuzzy | Ltd/Co/Inc suffix, punctuation | High | Must match on core name; suffix variation tolerated |
+
+## Financial Fields
+
+| Field | Comparison Method | Tolerance | Severity | Notes |
+|-------|------------------|-----------|----------|-------|
+| Stated income | Cross-document | 10% relative | High | Application vs income certificate vs credit report |
+| Bank avg deposits | Income plausibility | 50% of stated income (floor) | High | If avg deposits < 50% of claimed income, flag |
+| Loan amount | Exact across docs | 0.1% relative | Critical | Must be identical in application and contract |
+| Property value | Appraisal consistency | 5% relative | High | Application estimate vs formal appraisal |
+| Existing debt | Cross-source | 20% relative | Medium | Self-reported vs credit report |
+| Net assets | Calculated consistency | Sum of components vs stated total | High | Assets - liabilities must equal stated net |
+| Contract total vs line items | Sum check | 0.01 absolute | Critical | Main contract total must equal appendix line item sum |
+
+## Temporal Fields
+
+| Field | Consistency Check | Tolerance | Severity | Notes |
+|-------|------------------|-----------|----------|-------|
+| Employment start date | Cross-document match | 90 days | Medium | Application vs income cert vs credit report |
+| Contract signing date | Sequence plausibility | Must be after application date | High | Cannot sign before applying |
+| Document issuance date | Freshness and sequence | Per business rule (typically 30-90 days) | Medium | Income cert issued 6 months ago may be stale |
+| Loan maturity date | Contract consistency | Exact match across docs | High | Application vs contract vs amortization schedule |
+| Appraisal date | Sequence plausibility | Must precede loan approval | Medium | Appraisal after disbursement is a red flag |
+
+## Logical Consistency Checks
+
+These are not single-field comparisons but cross-field logical validations:
+
+- **LTV ratio consistency**: Property value x LTV % should equal or exceed loan amount. Check across appraisal, application, and contract.
+- **DTI ratio reasonableness**: Monthly debt payments (from credit report) + proposed payment / monthly income (from income cert) should not exceed the stated DTI or regulatory limit.
+- **Timeline plausibility**: Employment start < income cert issuance < application date < contract signing < disbursement. Any violation of this sequence is a finding.
+- **Appendix completeness**: Every appendix referenced in the main contract must be present in the case file. Every appendix present must be referenced in the main contract.
+- **Guarantor cross-check**: If a guarantor is listed, their identity fields must also pass cross-document verification against any guarantor-specific documents.
+- **Amount decomposition**: If the contract specifies principal + interest + fees, these must sum to the total obligation stated elsewhere.
+
+## Comparison Matrix Template
+
+Output schema for the case-level comparison matrix:
+
+```json
+{
+  "case_id": "CASE-2024-0042",
+  "documents": [
+    {"doc_id": "DOC-001", "type": "loan_application", "source": "applicant"},
+    {"doc_id": "DOC-002", "type": "income_certificate", "source": "employer"}
+  ],
+  "matrix": [
+    {"field": "applicant_name", "category": "identity",
+     "values": {"DOC-001": "Zhang Wei", "DOC-002": "Zhang Wei"},
+     "status": "consistent", "severity": null}
+  ],
+  "contradictions": [
+    {"field": "monthly_income", "documents": ["DOC-001", "DOC-002"],
+     "values": [85000, 82000], "type": "hard_contradiction",
+     "severity": "medium", "detail": "3.5% discrepancy in stated income"}
+  ],
+  "fraud_signals": [],
+  "summary": {"total_fields_compared": 8, "consistent": 6, "soft_mismatch": 1, "hard_mismatch": 1, "absent": 0}
+}
+```