kc-beta 0.8.1 → 0.8.3

package/template/skills/en/auto-model-selection/SKILL.md

@@ -2,53 +2,73 @@
 name: auto-model-selection
 tier: meta
 description: >
-  Use Context7 CLI to get up-to-date LLM model information. Use whenever you need to
-  know about available models, model capabilities, pricing, context window sizes, or
-  which model is suitable for a task — including tier assignment, worker LLM workflow
-  design, model comparison, and provider-specific API usage. Context7 gives you current
-  information that your training data may not have. Requires context7 CLI installed
-  (npm i -g context7). Optional plugin.
+  Use Context7 CLI for up-to-date model facts (size, API format, context window) and the
+  guidance below for "what kind of models are good for what part of a doc verification app".
+  Consult whenever you need to pick a model for a tier slot, decide between provider
+  alternatives, or sanity-check an existing tier assignment. Context7 gives you fresh
+  facts; this skill gives you the heuristic that maps those facts onto KC's pipeline.
+  Optional plugin (Context7 install: npm i -g context7).
 ---
 
-# Auto Model Selection via Context7
+# Auto Model Selection
 
-## What Context7 Is
+Model selection is not a frequently called skill — for most users, the tiers in workspace `.env` are already set sensibly, and a 4-tier cost-sensitive selection is overkill. This skill exists for two moments: when the conductor is bootstrapping fresh tier assignments (rare), and as a reference inside `skill-to-workflow` when a workflow needs to pick which worker LLM is right for its job.
 
-Context7 (`c7`) is a lightweight CLI tool that fetches up-to-date documentation for libraries and APIs. Install: `npm i -g context7`. Two commands:
-- `c7 library <query>` — search for a library/provider by name
-- `c7 docs <libraryId> <query>` — get specific documentation and code examples
+The teaching below is empirical — what the author has found works in this domain. Treat it as a starting heuristic with a 3-6 month shelf life, since model families update quickly.
 
-## When to Use
+## Worker LLM family — practical heuristic
 
-- User's `model-tiers.json` is outdated (KC hasn't been updated)
-- User switched to a new provider and needs model discovery
-- User explicitly asks to update model selections
-- Onboarding `/models` endpoint failed and curated list is stale
+- **Qwen family** — robust and cheap for general worker work. The flagship MoE in this family at any given time is usually one of the best workhorses for routine extraction / classification. Smaller sizes (3B-70B) are plentiful and reliable. Good default.
+- **DeepSeek** — excellent on more complicated tasks. Worth reaching for when the rule involves multi-step reasoning, nested judgment, or anything where Qwen's shorter-context behavior shows strain.
+- **GLM and Kimi** — also strong for the same complicated-task range as DeepSeek. Trade-off: they don't usually ship smaller variants (3B-70B), so they're tier1/tier2 only, not tier3/tier4.
 
-## How It Works
+## Flagship-MoE shape and the tier1 baseline
 
-1. User chooses provider and provides API key (or coding plan)
-2. Use `c7 library <provider-name>` to find the provider's library ID
-3. Use `c7 docs <id> "available models"` to get current model listings
-4. From the docs, identify: model names, capabilities (reasoning, coding, vision), context window sizes, pricing tiers
-5. Assign models to tiers based on capability and cost:
-   - LLM tier1: most capable (complex judgment, extraction)
-   - LLM tier2-3: mid-range (routine extraction, simple judgment)
-   - LLM tier4: cheapest (high-volume simple tasks)
-   - VLM tier1-3: vision models for document parsing/OCR
-6. Update `model-tiers.json` or workspace `.env` with assignments
+The current generation of flagship MoE LLMs has a recognizable shape: total parameter count in the 200-400B range, ~20B of activated expert size per token. Examples (these will be stale within months): Qwen's flagship MoE in the 200-400B-A20B band, DeepSeek-V4-Flash, etc.
 
-## Tier Assignment Principles
+This shape is a good first-choice worker LLM — not necessarily the absolute best at tier1, but a reasonable benchmark to start from. When you're picking a tier1 model, start from one of these and only move if you have a specific reason.
 
-- Cheapest model that meets accuracy threshold for the task
-- Regex is tier0 — smaller than any LLM
-- Not all tiers need to be filled — blank tiers are fine if the provider lacks suitable models
-- Record what works in AGENT.md for future reference
+## Smaller LLMs — basically free below 30B
 
-## Prerequisites
+Once you drop below ~30B parameters, models are extremely cheap on most providers. Qwen ships a ton of choices in this range and they work well.
+
+Two rules for picking in this range:
+- **Avoid "coder" variants** (models with `coder` / `code` in the name) at small sizes — these are mostly unreliable for general worker tasks. Use them only when the task is literally code-related.
+- **Prefer no-thinking-mode variants** when available. Tasks assigned to small workers are simple and fixed; extra thinking buys nothing and adds latency + token cost.
+
+## VLM / OCR selection
+
+First question: what's the visual task?
+
+- **Characters in scanned docs, seal stamps, handwriting** — use a dedicated OCR model. Current strong choices (subject to change): Paddle-OCR family, GLM-OCR, DeepSeek-OCR. Previous versions still work fine. No need to use a larger general VLM for plain character recognition.
+- **Graphs, complex tables, structures with strange or no frame lines** — try a larger and more expensive general VLM. The structure-understanding gap between OCR-specific models and general VLMs widens fast on these cases.
+
+When in doubt, run the cheapest OCR option first and only upgrade if the cheap path misses structure information.
+
+## Context7 — model facts on demand
+
+The heuristics above are about *which kind* of model to pick. For the specific facts (current model names, exact context window, pricing, API format), use Context7:
 
 ```bash
-npm i -g context7
+c7 library <provider-name>
+c7 docs <libraryId> "available models"
 ```
 
-Verify: `c7 library openai` should return results.
+Two commands. The first finds the provider's library ID, the second fetches up-to-date docs and code examples. Useful when:
+
+- Workspace `model-tiers.json` looks stale (KC hasn't been updated since the last model launch)
+- User switched providers and needs model discovery
+- The `/models` endpoint on a new provider was empty or unhelpful
+- You're sanity-checking that a model name in `.env` is still served
+
+Install: `npm i -g context7`. Verify: `c7 library openai` should return results.
+
+## When tier1/tier2 are picked
+
+The tier assignment ends up driving cost. Cheapest model that meets the accuracy bar wins. Regex is the implicit "tier 0" and should be the first reach when the rule can be satisfied by pattern matching alone — see `skill-to-workflow` for when to escalate from regex to worker LLMs.
+
+Not all tiers need to be filled. Blank tier3/tier4 slots are fine if the provider doesn't ship suitable small models. Record what works in `AGENT.md` so the next session inherits the choice.
+
+## Refresh cadence
+
+This skill's heuristics will drift. Author plans to revisit every 3-6 months as new model generations land. If you find yourself applying advice here that contradicts what Context7 shows today, trust Context7 — the facts have moved.

package/template/skills/en/bootstrap-workspace/SKILL.md

@@ -87,6 +87,19 @@ Update AGENT.md at natural checkpoints: after the developer user gives you a sub
 
 A future session resumes by reading AGENT.md first. The richer it is, the less re-explanation the developer user has to do.
 
+### Phase-transition cadence
+
+A recurring failure mode worth flagging: agents bootstrap AGENT.md richly, then never touch it again — many hours of phase work pass without a single AGENT.md commit. That defeats the long-term-memory purpose.
+
+Cadence to adopt: **append a one-line decision log to AGENT.md at each phase transition**. Format:
+
+```
+[<timestamp> | rule_extraction → skill_authoring]
+N rules extracted; coverage_audit complete; R03/R05/R07 flagged judgment-heavy.
+```
+
+Three lines of friction per phase transition; thirty lines of insight for the next auditor / next session. The format is loose — the cadence matters more than perfect prose.
+
 ## When to Re-Bootstrap
 
 Return to this skill when:

package/template/skills/en/compliance-judgment/SKILL.md

@@ -81,3 +81,17 @@ Map these dependencies in the rule catalog. Execute rules in dependency order. P
 - **Multiple values**: The document contains the entity in multiple places with different values. Flag as `uncertain`. Report all found values.
 - **Conditional rules**: "If the loan exceeds 1M, then collateral is required." Check the condition before applying the rule. If the condition is not met, the rule does not apply — result is `pass` (or `not_applicable` if you add that category).
 - **Negative results**: Some rules check for absence. "The document must NOT contain guarantees to related parties." Searching for absence is harder than searching for presence. Be thorough in the search, then be confident in the negative.
+
+## Cross-document consistency of confidence bars
+
+For a rule that judges multiple documents (which is the common case), **the confidence threshold for "pass" must be the same across all documents** for that rule. A rule that requires 0.85 confidence to pass on document A and 0.75 on document B isn't a rule — it's two rules pretending to be one.
+
+When the worker LLM is the judge, set the threshold in the prompt or in postprocessing, not "let the LLM decide" per call. Random variation between LLM calls means each call lands somewhere on a distribution; your job is to set the bar that distribution must clear.
+
+Two ways to enforce:
+- **In the prompt**: explicit "output 'PASS' only if confidence ≥ 0.85" language. Cheap. Vulnerable to LLM drift between calls.
+- **In postprocessing**: ask the LLM for verdict + confidence separately, then apply the threshold in a small Python wrapper. More reliable. Engine sees the threshold as code, not prompt prose.
+
+For rules with stable patterns (formats, presence checks), prefer postprocessing. For rules with subjective judgment (adequacy, sufficiency), the prompt-level threshold is easier to write but worth auditing — sample a batch and check whether the LLM honored the bar.
+
+The `confidence-system` skill describes how to compose confidence from multiple signals; this section is about applying it consistently across documents for the same rule.

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

@@ -50,21 +50,43 @@ Does this document match any known corner case pattern?
 - Near miss: slightly lower confidence.
 - No match: neutral (no adjustment).
 
+### Signal: Format-Pattern Conformance
+Does the extracted value match a regex-expressible format that the rule implies? Many fields have a known shape — phone numbers, ID numbers, dates, currency amounts, regulatory codes — that can be checked cheaply with a regex independent of the LLM's confidence in its own output.
+- Value matches the expected format pattern: positive signal.
+- Value violates the format pattern (e.g., a phone field with letters): strong negative signal, often a hallucination indicator.
+- No applicable format pattern for the field type: neutral.
+
+This catches a common failure: the LLM correctly identifies *where* the value lives but gets the format wrong (typos a digit, drops a country code, returns a stand-in like "see appendix").
+
+### Signal: Statistical Outlier
+For numeric values, does this value sit far from the typical range seen across other documents for the same field?
+- Within 1 standard deviation of average: neutral / mild positive.
+- 2-3 standard deviations: mild negative.
+- Beyond 3 std dev or outside a domain-plausible range: strong negative — often a unit error (yuan vs. 万元), a decimal mistake, or a hallucinated digit.
+
+Useful especially for amounts, percentages, ratios. Compute the reference range from QC-confirmed historical data; refresh periodically. For categorical fields, the analog is "value not in the observed value-set" — flag novel values for review.
+
 ### Combining Signals
 
-Start with a simple weighted average:
+Combine the signals into a single confidence score. The form is usually a weighted sum:
 
 ```
-confidence = w1 * method_prior + w2 * source_presence + w3 * historical_accuracy + w4 * corner_case_adjustment
+confidence = w_method     * method_prior
+           + w_source     * source_presence
+           + w_history    * historical_accuracy
+           + w_corner     * corner_case_adjustment
+           + w_format     * format_conformance
+           + w_outlier    * outlier_check
 ```
 
-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
+How to set the weights is **your judgment call** per rule and per project. A few orienting principles, not prescriptions:
+
+- Historical accuracy is the most predictive signal once you have data — favor it heavily after the first few QC cycles.
+- Method prior and source presence are always available — they carry the early iterations before history exists.
+- Format conformance and outlier signals are independent of the LLM — they keep working even when the LLM is overconfident, which is exactly when you want them.
+- Corner-case adjustment is usually small but should fire decisively when a known corner case is matched.
 
-When historical accuracy is not yet available (early iterations), redistribute its weight to the other signals.
+When historical accuracy is not yet available (early iterations), redistribute its weight to the other signals. The right weights for this rule on this corpus will reveal themselves through calibration — that's the loop the next section describes.
 
 ## Threshold Bands
 

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

@@ -1,22 +1,35 @@
 ---
 name: corner-case-management
 tier: meta
-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.
+description: Identify, catalog, and handle corner cases that do not fit the mainstream verification workflow. Use AFTER several rounds of skill/workflow iteration have surfaced documents that genuinely don't fit and can't be accommodated by reasonable changes to the standard flow. Covers when something is a corner case vs. a systemic fix needed, how to register it, how to wire detection-and-resolve so the corner case stays out of the hot path until a similar document appears again, and when to promote a corner case to a regular rule.
 ---
 
 # 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.
+A good workflow handles the bulk of cases cleanly. Corner cases are documents that don't fit — individually rare, collectively non-negligible. 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.
+Instead, maintain a separate registry. Check incoming documents against the registry; handle matches with specific resolutions; keep the main workflow lean.
+
+## When to reach for this skill
+
+Corner cases are identified **after** the testing iterations, not during initial design. The typical pathway:
+
+1. You've built a skill/workflow for a rule.
+2. You've run it on the sample set. Most cases pass; some fail.
+3. You iterate — change code, change prompts, run back-tests.
+4. After several rounds, some cases stubbornly don't fit. Either:
+ - The current workflow doesn't catch them and changing the workflow to catch them would cost too much (breaks unrelated cases, adds too much complexity, requires architectural rework).
+ - The cases are swinging — one round of changes fits them, the next round breaks them, and oscillation continues.
+
+That's when you use this skill. Not on the first iteration. Not when you can plausibly fix it in the workflow. Only when fitting the case into the standard flow costs more than the case is worth.
 
 ## 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.
+Corner cases are a fact of life in document verification. Financial documents come from 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 question is not "how do I eliminate corner cases?" but "how do I manage them efficiently without polluting the main path?"
 
-The answer is: separate them from the main logic. Keep the workflow clean. Keep the corner cases cataloged, detectable, and resolvable.
+The answer is: separate them. Keep the main workflow clean. Keep the corner cases cataloged, detectable, and resolvable when they recur.
 
 ## The Corner Case Registry
 
@@ -39,7 +52,7 @@ A structured file (`corner_cases.json`) in the rule skill's `assets/` directory:
       "action": "Multiply extracted value by 100 before threshold comparison",
       "code_snippet": "if value < 1.0: value *= 100"
     },
-    "discovered_at": "2026-04-01",
+    "discovered_at": "<date>",
     "iteration": 3,
     "status": "active"
   }
@@ -53,60 +66,67 @@ Each entry captures:
 - **When** it was discovered and in which iteration.
 - **Status**: active, promoted (moved to main workflow), or deprecated.
 
-## Detection During Execution
+## How to handle corner cases — lazy retrieval with a high bar
+
+Corner cases live in the registry, not in the main verification path. They're **lazily loaded** with a **high retrieval threshold**, meaning:
 
-Before running the standard workflow on a document:
+- The main workflow runs first on every document.
+- The registry is consulted only when a new incoming document resembles a previously-collected corner case strongly enough to trigger that entry.
+- The "strongly enough" bar should be set high — false matches drag in a wrong resolution and pollute the main result. Better to miss a match (the main workflow handles it, possibly imperfectly) than to apply an irrelevant corner-case patch.
 
-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.
+Two detection patterns work for this:
 
-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.
+- **Cheap deterministic match**: regex or keyword fingerprint over document text. Fast, run on every document.
+- **Embedding-based similarity**: compute embedding of the document's rule-relevant region, compare to embeddings of registered corner cases. Catches semantic resemblance the regex misses; costs more.
 
-## When to Add a Corner Case
+For early-stage rules with a small registry, deterministic detection is enough. For mature rules with dozens of registered cases, embedding-based similarity scales better.
+
+When a match fires:
+1. Log that the corner case was triggered (audit visibility).
+2. Apply the registered resolution.
+3. Skip / supplement / override the standard workflow as the resolution prescribes.
+
+## 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.
+- Iterations of the standard workflow can't accommodate the document without disproportionate cost.
+- The failure has a recognizable, describable pattern (a fingerprint to detect again).
+- The resolution is clear and self-contained (not "rewrite the workflow").
 
 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).
+- The failure affects many documents — that's not a corner case, it's a pattern, and the main workflow should change.
+- The failure has no discernible pattern — that may be a data quality issue; escalate to the developer user.
+- The resolution would require changing the core judgment logic — that belongs in the main workflow.
 
-## When to Promote a Corner Case
+## 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.
+- It starts appearing across many documents. It's no longer a corner case — it's 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
+## 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.
+- Include enough context that a domain expert can understand each case without reading 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:
+Developer users often know about edge cases that the 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
+## 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.
+- Keep detection patterns efficient (prefer regex over LLM-based detection where possible).
+- Monitor the registry size. When it grows large for a single rule, that's a signal the workflow itself needs improvement — many of those "corner" cases probably want promotion to mainline handling.

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

@@ -1,132 +1,137 @@
 ---
 name: cross-document-verification
 tier: meta
-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.
+description: Build cross-document verification rule-skills and workflows — i.e., rules where the verdict depends on facts that appear in MORE than one document. Use when authoring or distilling a rule that requires comparing entities/values across documents in a case (main contract + appendices, loan application + income certificate + bank statement, etc.). Covers what the rule definition must specify (source-doc → entity → target-doc → entity → consistency level), how the resulting check.py/workflow walks the case, contradiction types to handle, and severity classification. Distinct from `compliance-judgment` (within-doc rules); KC is the builder, not the executor.
 ---
 
-# Cross-Document Verification
+# Cross-Document Verification — Building Rules That Span Documents
 
-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?
+KC's job in this phase is **building** verification rules that span multiple documents — not executing cross-doc checks at runtime. The output is a rule-skill / workflow that, once shipped, can be applied by KC or downstream systems to any case.
 
-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.
+If a rule's verdict depends on facts in more than one document, that fact has to be encoded in the rule itself. You can't build a within-doc check.py and hope the cross-doc check happens by magic at production time.
 
-## The Case Concept
+## What the rule definition must specify
 
-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.
+For a cross-doc rule, the catalog entry needs more than just "description + falsifiability_statement". It needs an **explicit cross-doc trajectory**:
 
-Two common case patterns:
+1. **Starting document class**: which document do we start from? How do we classify a document as belonging to this class? (e.g., "loan application form", "main contract", "annual disclosure report")
+2. **Anchor entity in the starting doc**: what do we extract first? (e.g., applicant ID, borrower name, contract reference number, reported total amount)
+3. **Target document class(es)**: which document(s) must we cross-check against? How do we identify them within the same case? (shared anchor key, naming pattern, explicit reference in the starting doc)
+4. **Target entity in each target doc**: what do we extract from each target doc to compare? It may or may not have the same field name — "monthly income" on the application vs. "average deposit" on the bank statement.
+5. **Consistency level for PASS**: when do we say the documents agree? Exact equality? Equality within tolerance? Plausibility check (within 1.5× of the other value)? Reciprocal-reference present?
+6. **What FAIL looks like**: hard mismatch, soft contradiction, or missing reciprocal reference — and what severity each carries.
 
-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.
+Without these five anchors, the rule is just a wish. With them, the resulting check.py can walk the case deterministically.
 
-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.
+## How this differs from `compliance-judgment`
 
-In both patterns, the shared entities are the anchors. Every anchor that appears in more than one document is a candidate for cross-verification.
+`compliance-judgment` covers within-doc rules: read one document, apply the rule, return a verdict. The judgment can be regex, deterministic Python, or LLM-augmented — but the input is one document.
 
-## Building the Comparison Matrix
+This skill covers rules where the **input is a case** (a set of related documents). The check.py for such a rule:
 
-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.
+- Receives a case-level structure (list of documents + metadata), not a single doc.
+- Performs entity extraction across the relevant documents.
+- Builds the comparison matrix needed for that specific rule (not a generic everything-vs-everything matrix — only the fields this rule cares about).
+- Applies the consistency check defined in the rule.
+- Returns the verdict plus the matrix-cells that drove it (evidence).
 
-Example matrix for a loan case:
+KC is the **builder** of this check.py / workflow, not the executor. The teaching below is about what to design, not what to do at runtime.
 
-| 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 |
+## Case patterns to design for
 
-Example matrix for a contract + appendices case:
+Two patterns cover most cross-doc rules:
 
-| 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 |
+1. **Main contract + appendices/supplements.** Same issuer, formally cross-referenced. The main contract states the total, the appendices break it down. Issues to expect: totals that don't match line-item sums, referenced appendices missing or outdated, version mismatches between main body and supplements.
 
-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.
+2. **Multi-source bundle.** Loan application + income certificate + bank statement + credit report + property appraisal. Different issuers, different formats, same borrower/case. Issues to expect: identity drift across docs (name spellings, employer name variants), value contradictions (income claimed vs. observed), suspicious consistency (multiple docs with identical formatting/phrasing → possible fabrication).
 
-## Contradiction Types
+When authoring a rule, name the pattern it targets. The check.py shape differs between the two — the contract+appendices pattern expects formal references and reciprocal links; the multi-source pattern expects normalization (entity reconciliation across formats).
 
-### Hard Contradictions
+## Contradiction taxonomy (what the rule may need to detect)
 
-Exact mismatches in fields that must be identical across documents:
+A cross-doc rule may flag one or more of these:
 
-- **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
+Exact mismatches in fields that must be identical across docs.
+- Identity field mismatch (name, ID, DoB).
+- Amount mismatch beyond tolerance (totals, line items, reported incomes).
+- Date mismatch on fields that should be identical (effective date, signing date).
 
-Hard contradictions are binary. Either the values match (within defined tolerance) or they do not.
+Hard contradictions are binary. Either the values match (within defined tolerance) or they don't.
 
-### Soft Contradictions
+### Soft contradictions
+Values not directly inconsistent but **implausible** when considered together.
+- Monthly income claimed at one level; bank statement averages significantly below it.
+- Property appraisal close to the loan amount (high LTV — technically possible, but a signal).
+- Employment dates with multi-month gaps across documents.
 
-Values that are not directly inconsistent but are implausible when considered together:
+Soft contradictions need thresholds and judgment. They are findings, not verdicts — the rule should specify whether they trigger FAIL, WARNING, or just evidence-collection for downstream review.
 
-- 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.
+### Cross-reference failures
+Structural integrity problems within formally linked documents.
+- Main contract references "Appendix B — Payment Schedule" but Appendix B is missing or has a different title.
+- Appendix references a clause that doesn't exist in the main contract.
+- Missing reciprocal reference: appendix references main contract, but main contract doesn't list appendix.
+- Version mismatch: main contract dated one date, appendix dated a much later date with different terms.
 
-Soft contradictions require thresholds and judgment. They are findings, not verdicts.
+See `references/contradiction-taxonomy.md` for the field-level taxonomy with tolerances and severity templates the rule designer can borrow.
 
-### Cross-Reference Failures
+## Severity classification (rule-level decision)
 
-Structural integrity problems within formally linked documents:
+Not all contradictions carry the same weight. The rule must specify how its findings map to severity:
 
-- 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.
+| Severity | Typical example |
+|----------|-----------------|
+| Critical | Identity field mismatch (different ID across docs) |
+| High | Significant financial amount discrepancy |
+| Medium | Date or employment-detail mismatch |
+| Low | Formatting / abbreviation difference ("ABC Corp" vs "ABC Corporation") |
 
-See `references/contradiction-taxonomy.md` for the full field-level taxonomy with tolerances and severity classifications.
+The actual thresholds are domain-specific. The developer user sets them per field; the rule's design should leave room for the configured values rather than hardcode percentages.
 
-## Severity Classification
+## Fraud-signal patterns the rule may surface
 
-Not all contradictions are equal. Classify by impact:
+Some patterns are visible only at the case level:
 
-| 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" |
+- **Consistent small discrepancies across docs**: e.g., every doc inflated by ~5%, every date shifted by exactly one month. Consistency-in-error suggests coordinated fabrication rather than honest mistakes.
+- **Suspicious doc consistency**: multiple docs from supposedly different issuers using identical formatting / phrasing / typos.
+- **Values at regulatory thresholds**: LTV exactly at the limit, DTI exactly at the limit. One coincidence is harmless; a pattern across the case is a signal.
+- **Temporal impossibilities**: income certificate issued before employment start; bank statement covering a period before account opening; appraisal dated after loan disbursement.
 
-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.
+If the rule's job includes any of these, encode them. These are **signals for escalation**, not conclusions — the rule should output "flagged" with evidence, and let the developer user or downstream review process determine the final verdict.
 
-## Fraud Signal Patterns
+## Designing the case-walk in check.py
 
-Cross-document analysis reveals patterns that single-document review cannot detect. Flag these — do not accuse, flag:
+For a cross-doc rule, a typical check.py:
 
-- **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.
+1. Receives the case (list of doc paths/handles + classification metadata).
+2. Selects the **starting document** of the class declared in the rule.
+3. Extracts the **anchor entity** (using entity-extraction).
+4. Locates the **target document(s)** in the case by the anchor or by formal reference.
+5. Extracts the **target entity** from each target doc.
+6. Applies the **consistency check** per the rule's PASS criteria.
+7. Returns:
+   - verdict (PASS / FAIL / WARNING / NOT_APPLICABLE)
+ - evidence (the cells of the comparison matrix that drove the verdict, with source-doc + page references)
+   - confidence (per `confidence-system`)
 
-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.
+The comparison matrix is rule-specific — only the fields this rule needs. Building a generic "all entities × all docs" matrix is expensive and pollutes the evidence trail.
 
 ## 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).
+**Inputs to the rule's check.py at runtime:**
+- Case structure (set of related documents + identifiers).
+- Entity extraction available per-doc (skill: `entity-extraction`).
+- Compliance judgment may have already produced per-doc verdicts (skill: `compliance-judgment`) that this rule can use as part of its inputs.
 
 **Outputs:**
-- Case-level consistency report: the comparison matrix, all contradictions found, severity classifications, and fraud signal flags.
+- A case-level verdict plus the comparison-matrix slice that justifies it.
 
 **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.
+- `confidence-system`: cross-doc contradictions are a strong signal, often lowering confidence in affected fields.
+- `evolution-loop`: recurring contradiction patterns the rule didn't anticipate trigger workflow refinement.
+- `dashboard-reporting`: case-level view alongside per-doc results.
+
+## Ground-truth principle
 
-**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.
+When the developer user or end user reports a cross-doc inconsistency that this rule missed, that report is prior to agent judgment. Log it, treat it as a corner case (`corner-case-management`) or as a trigger for rule refinement, and adjust detection thresholds accordingly. The rule's job is to catch what humans catch — and then go further.