kc-beta 0.1.0

package/template/skills/en/meta-meta/quality-control/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: quality-control
+description: Design and execute quality control for production verification workflows. Use when workflows are deployed on Input/ documents and results need to be monitored, when designing the QC sampling strategy for a rule, or when evaluating whether monitoring can be reduced. Covers LLM-as-Judge evaluation, adaptive sampling strategies, confidence-based triage, and the transition from active monitoring to stable oversight. Also use when production quality drops and you need to diagnose whether to trigger the evolution loop.
+---
+
+# Quality Control
+
+Quality control is the Observer role. You are watching the worker LLMs perform and deciding whether they are doing it well enough. The goal is not to review every result — that would defeat the purpose of automation. The goal is to review just enough to maintain confidence that the system is working.
+
+## Five-Layer QA Architecture
+
+Quality control is not one activity — it is five layers that build on each other. Lower layers must pass before higher layers run.
+
+| Layer | Name | What It Checks | Method |
+|-------|------|---------------|--------|
+| L1 | Text Integrity | Files exist, encoding correct, source text preserved after processing | Scripts (`lint_*`) |
+| L2 | Syntax | Output format valid (JSON/CSV), required fields present, types correct | Scripts (`lint_*`) |
+| L3 | Data Completeness | Required fields populated, values in valid domain (dates are dates, amounts are positive) | Scripts (`validate_*`) |
+| L4 | Business Logic | Cross-field consistency, threshold compliance, sequence reasonableness | Scripts + LLM |
+| L5 | Cross-Phase | Entities in results match extraction output, rules match catalog, workflow output matches skill ground truth | Scripts (`cross_validate_*`) + LLM |
+
+**Key principles:**
+- **Fail fast**: If L1 fails (file missing), do not run L4 (business logic). Lower layers block higher layers.
+- **Code first**: L1-L3 should be pure code — cheap and deterministic. LLM-as-Judge (below) operates at L4 and L5.
+- **Naming convention**: `lint_*` for L1-L2, `validate_*` for L3-L4, `cross_validate_*` for L5.
+
+**QC vs Reflection**: QC catches problems in outputs (this skill). Reflection diagnoses WHY problems occur and fixes them (see `evolution-loop`). QC feeds data to Reflection; Reflection feeds fixes back to the system.
+
+See `references/qa-layers.md` for detailed layer specifications and example patterns.
+
+## LLM-as-Judge
+
+Use yourself (the coding agent) or a high-tier worker LLM to evaluate workflow outputs. The judge receives:
+- The source document (or relevant section).
+- The workflow's extracted value.
+- The workflow's pass/fail determination.
+- The workflow's comment (if any).
+
+The judge produces a structured verdict:
+
+- **correct**: The extraction and judgment are both right.
+- **partial**: The extraction is roughly right but imprecise, or the judgment is right but the comment is misleading.
+- **incorrect**: The extraction or judgment is wrong.
+- **missing**: The workflow failed to produce a result when it should have.
+
+Field-level verdicts should include: the field name, the verdict, the expected value (what the judge thinks is correct), and brief reasoning.
+
+## Adaptive Sampling
+
+Do not review everything forever. Start at high coverage and reduce as quality stabilizes:
+
+### Initial Deployment
+- Review 100% of results for the first batch. This is your baseline.
+- Establish per-rule accuracy from this batch.
+
+### Early Production
+- Review all results that the workflow flagged as low confidence.
+- Additionally, randomly sample a percentage of high-confidence results.
+- The percentage depends on MONITOR_FREQUENCY in `.env`:
+  - `high`: 50% random sample
+  - `mid`: 20% random sample
+  - `low`: 10% random sample
+
+### Stable Production
+- Review only low-confidence results.
+- Random sample drops further (5-10%).
+- Trigger full review if random samples reveal unexpected failures.
+
+### The Decay Function
+The sampling rate should decay based on observed accuracy, not just time. If accuracy stays above the threshold for N consecutive batches, reduce sampling. If accuracy drops, increase sampling immediately.
+
+The exact decay curve is for you to design per rule, based on:
+- How variable the documents are.
+- How complex the rule is.
+- How much the developer user trusts the workflow.
+
+Discuss the sampling strategy with the developer user. They may have preferences.
+
+## Confidence-Based Triage
+
+Confidence scores (from the `confidence-system` skill) determine review priority:
+
+- **High confidence (above auto-accept threshold)**: Spot-check only. These are results the workflow is sure about.
+- **Medium confidence (between thresholds)**: Sample at the rate determined by MONITOR_FREQUENCY.
+- **Low confidence (below full-review threshold)**: Review every one. These are results the workflow is uncertain about.
+
+The thresholds themselves should be calibrated per rule. Start with reasonable defaults (e.g., 0.9 / 0.6) and adjust based on whether the thresholds actually distinguish correct from incorrect results.
+
+## Triggering Evolution
+
+Quality control can trigger the evolution loop. Criteria:
+
+- Average accuracy across reviewed results drops below WORKFLOW_ACCURACY.
+- A single rule's accuracy drops significantly (e.g., 15+ percentage points below its historical average).
+- A new pattern of failures emerges that was not seen during skill/workflow testing.
+
+When triggering evolution, provide the quality control data as input to the diagnosis step.
+
+## Batch Processing
+
+For production Input/ documents:
+
+1. Process the batch through workflows. Results go to Output/.
+2. Assign confidence scores to each result.
+3. Select the review sample based on confidence triage + random sampling.
+4. Review the selected results (LLM-as-Judge or manual review by the developer user).
+5. Compute batch accuracy from reviewed results.
+6. Log batch QC report.
+7. If accuracy is acceptable, finalize the batch. If not, trigger evolution loop.
+
+## Developer User Involvement
+
+The developer user should see QC results through the dashboard (see `dashboard-reporting`). Key metrics to surface:
+- Per-rule accuracy over time.
+- Confidence distribution (are most results high-confidence?).
+- Sampling rate (is monitoring decreasing as expected?).
+- Flagged issues requiring human attention.
+
+The developer user may also want to review specific results themselves, especially for high-stakes rules. Accommodate this by marking results for human review in the output.
+
+## User Feedback Collection
+
+Build error reporting and comment mechanisms into every verification app you create. These are not optional features — they are essential data sources.
+
+### Two Audiences
+
+- **Developer users**: Technical error reporting — field-level correction, rule re-evaluation requests, false positive/negative flags with context. They see the full result detail.
+- **End users**: Simplified feedback — flag a result as wrong, add a comment, indicate severity. They see a clean interface without technical internals.
+
+### Feedback as Ground Truth
+
+When a user reports an error on a verification result, that correction is ground truth. It overrides the coding agent's judgment and the worker LLM's output. Feed user corrections into the `evolution-loop` immediately as confirmed failures — they are higher priority than agent-detected issues.
+
+### Feedback Data Flow
+
+Collect feedback via the dashboard (see `dashboard-reporting`) → Store as structured records (result_id, reporter_role, feedback_type, corrected_value, comment, timestamp) → Feed into `evolution-loop` as regression test cases → Track correction trends in QC metrics.
+
+See `references/sampling-strategies.md` for detailed sampling patterns.

package/template/skills/en/meta-meta/quality-control/references/qa-layers.md

@@ -0,0 +1,92 @@
+# QA Layer Specifications
+
+Detailed specifications for the five-layer QA architecture. Each layer builds on the one below it.
+
+## Layer Details
+
+### L1: Text Integrity
+
+- **Description**: Verify that source files exist, are readable, and that text content is preserved correctly after any processing (parsing, OCR, conversion).
+- **Input**: Raw document files and their processed text output.
+- **Output**: Pass/fail per file with error details.
+- **Example checks**: File exists and is non-empty. Encoding is UTF-8 (or declared encoding). No null bytes in text output. Character count is within expected range for document type.
+- **Common failures**: File path changed after processing. OCR produced empty output. Encoding mismatch causes garbled characters.
+- **Escalation**: If L1 fails, do not proceed to higher layers. Log the failure and flag for reprocessing.
+
+### L2: Syntax
+
+- **Description**: Verify that output files conform to their declared format and schema.
+- **Input**: Output files (JSON, CSV, etc.) from workflows.
+- **Output**: Pass/fail per file with parse errors or schema violations.
+- **Example checks**: JSON is valid (parses without error). Required top-level keys exist. Array fields are arrays, not strings. Date fields match ISO 8601 format.
+- **Common failures**: Trailing comma in JSON. Missing closing bracket. CSV with inconsistent column count. Unexpected null where value is required.
+- **Escalation**: Syntax failures indicate a bug in the output generation code. Fix the code, not the data.
+
+### L3: Data Completeness
+
+- **Description**: Verify that required data fields are populated with values in their valid domain.
+- **Input**: Parsed output records.
+- **Output**: Per-field validation results with reasons for any failures.
+- **Example checks**: Invoice date is a valid date (not "N/A" or empty). Amount is a positive number. Entity name is non-empty and does not contain only whitespace. Enum fields contain allowed values.
+- **Common failures**: Extraction returned "unable to determine" as a value. Amount includes currency symbol (string instead of number). Date extracted as partial (month and day but no year).
+- **Escalation**: Completeness failures feed back to extraction prompt improvement. If a field is consistently incomplete, the extraction logic needs work.
+
+### L4: Business Logic
+
+- **Description**: Verify cross-field consistency and compliance with business rules.
+- **Input**: Complete, validated records from L3.
+- **Output**: Per-rule validation results with reasoning.
+- **Example checks**: Contract end date is after start date. Invoice date falls within contract validity period. Total amount equals sum of line items. Signatory name matches authorized personnel list.
+- **Common failures**: Date comparison fails due to timezone differences. Rounding errors in amount calculations. Cross-reference lookup fails because entity names differ slightly (e.g., "ABC Corp" vs "ABC Corporation").
+- **Escalation**: Business logic failures may indicate rule misunderstanding. Consult the developer user if the rule intent is ambiguous.
+
+### L5: Cross-Phase
+
+- **Description**: Verify consistency across different phases of the verification pipeline.
+- **Input**: Outputs from multiple pipeline stages (extraction, verification, reporting).
+- **Output**: Cross-phase consistency report.
+- **Example checks**: Entities in final results match those in extraction output (nothing added or dropped). Rule IDs in results exist in the rule catalog. Workflow output for a skill matches the skill's own ground truth output. Confidence scores in results match those computed by the confidence system.
+- **Common failures**: A rule was added to the catalog but the workflow was not updated to include it. Extraction found 5 entities but results only report 4. Workflow output diverges from skill ground truth on edge cases.
+- **Escalation**: Cross-phase failures often indicate integration issues. Check the pipeline connections, not individual components.
+
+## Script Naming Convention
+
+| Prefix | Layer | Purpose | Examples |
+|--------|-------|---------|----------|
+| `lint_` | L1-L2 | Fast, syntactic checks | `lint_json.py`, `lint_encoding.py`, `lint_schema.py` |
+| `validate_` | L3-L4 | Domain and logic validation | `validate_fields.py`, `validate_dates.py`, `validate_amounts.py` |
+| `cross_validate_` | L5 | Cross-phase consistency | `cross_validate_extraction.py`, `cross_validate_rules.py` |
+
+Scripts should:
+- Accept a file or directory path as input.
+- Output structured JSON results (pass/fail per check, with reasons).
+- Return exit code 0 if all checks pass, non-zero otherwise.
+- Be idempotent — running twice produces the same result.
+
+## QC vs Reflection
+
+| Dimension | QC (this skill) | Reflection (evolution-loop) |
+|-----------|-----------------|---------------------------|
+| **Who runs it** | Coding agent or automated scripts | Coding agent |
+| **What triggers it** | Every batch, on schedule | QC failures, accuracy drops |
+| **Input** | Workflow outputs | QC reports, failure logs, iteration history |
+| **Output** | Pass/fail verdicts, accuracy metrics | Root cause diagnosis, fix proposals |
+| **Cost** | Low (mostly scripts, some LLM at L4-L5) | Higher (deep analysis, prompt rewriting) |
+| **When to use** | Always — every production batch | Only when QC reveals problems |
+| **Goal** | Detect problems | Fix problems |
+
+QC without Reflection detects issues but cannot fix them. Reflection without QC has no data to work from. They are complementary, not alternatives.
+
+## Integration Points
+
+### With `data-sensibility`
+
+The `data-sensibility` skill provides input validation that feeds L1-L3. If data-sensibility checks flag a document as anomalous before processing, QC can prioritize reviewing that document's outputs. Data-sensibility operates on inputs; QC operates on outputs. Together they bracket the pipeline.
+
+### With `cross-document-verification`
+
+Cross-document verification enables L5 cross-doc consistency checks. When multiple documents reference the same entity (e.g., same contract number across invoice and purchase order), L5 can verify that extracted values are consistent across documents. Without cross-document verification, L5 is limited to single-document cross-phase checks.
+
+### With `confidence-system`
+
+QC results calibrate the confidence system. When QC reveals that high-confidence results are sometimes wrong, the confidence thresholds need adjustment. Conversely, confidence scores drive QC sampling — low-confidence results get more review. This creates a feedback loop: QC improves confidence calibration, better calibration improves QC efficiency.

package/template/skills/en/meta-meta/quality-control/references/sampling-strategies.md

@@ -0,0 +1,76 @@
+# Sampling Strategies for Quality Control
+
+## Adaptive Sampling
+
+The core idea: review more when you are uncertain, less when you are confident. Confidence grows with evidence — consecutive batches of high accuracy.
+
+### Continuous Decay Model
+
+Rather than cliff-edge transitions between phases, use a smooth exponential decay driven by observed accuracy:
+
+```
+sampling_rate = max(floor_rate, exp(-λ × consecutive_successes))
+```
+
+Where:
+- `consecutive_successes`: number of consecutive batches where accuracy meets or exceeds the threshold. **Resets to 0** whenever a batch's accuracy drops below the threshold. This is the self-correcting mechanism — quality drops immediately increase monitoring.
+- `λ` (decay speed): controlled by MONITOR_FREQUENCY in `.env`.
+- `floor_rate`: the minimum sampling rate, never goes below this.
+
+### MONITOR_FREQUENCY Mapping
+
+| Setting | λ | floor_rate | Character |
+|---------|---|------------|-----------|
+| `high` | 0.1 | 0.10 | Slow decay, cautious — for high-stakes verification where errors are costly |
+| `mid` | 0.2 | 0.05 | Balanced decay — standard for most scenarios |
+| `low` | 0.3 | 0.05 | Fast decay — for well-understood domains with simple rules |
+
+As a rough mental model of the curve shape (for `mid`):
+- After 1 success: ~82% sampling
+- After 3 successes: ~55%
+- After 5 successes: ~37%
+- After 10 successes: ~14%
+- After 15 successes: ~5% (floor)
+
+These numbers, the formula, and even the exponential shape are recommended defaults. The coding agent and developer user should discuss and calibrate based on the specific business scenario. If a different decay function (linear, sigmoid, or hand-tuned) works better, use it. The framework — accuracy-driven decay with reset on quality drop — matters more than the specific formula.
+
+## Priority Sampling
+
+Not all results are equally worth reviewing. Priority sampling ensures that the most informative results are always in the review set:
+
+### Always Review
+- Results where the workflow reported low confidence (below the full-review threshold from `confidence-system`).
+- Results where the workflow produced an error or missing result.
+- Results from document types not seen during skill/workflow testing.
+
+### Usually Review
+- Results where the workflow's confidence is in the medium band.
+- Results from rules that historically have lower accuracy.
+- Results from the first occurrence of a new document format or variant.
+
+### Spot-Check
+- Results with high confidence from rules that historically have high accuracy.
+- These are selected randomly from the high-confidence pool.
+- The purpose is regression detection, not active improvement.
+
+## Stratified Sampling
+
+When documents vary significantly in complexity or type, stratify the sample:
+
+1. **Group documents** by type, complexity, or any relevant characteristic.
+2. **Sample proportionally** from each group, ensuring that minority groups are represented.
+3. **Over-sample** from groups that historically have lower accuracy.
+
+This prevents the random sample from being dominated by easy documents while missing systematic failures in hard documents.
+
+## Confidence Calibration Check
+
+Periodically (every N batches), run a calibration check:
+
+1. Take a random sample of high-confidence results.
+2. Review them (LLM-as-Judge or human).
+3. Compare: are 90%+ of "high confidence" results actually correct?
+4. If not, the confidence system needs recalibration (see `confidence-system` skill).
+5. If yes, you can safely reduce the sampling rate for high-confidence results.
+
+This is a meta-check on the quality of the quality control system itself.

package/template/skills/en/meta-meta/rule-extraction/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: rule-extraction
+description: Extract and organize business verification rules from regulation documents into discrete, testable units. Use when processing documents in Rules/ to identify individual verification rules, when decomposing a regulation into atomic checks, or when the developer user adds new regulation files. Covers reading regulation text, identifying rule boundaries, determining granularity, handling cross-references, and producing a rule catalog. Also use when rules are provided in structured formats like xlsx or csv.
+---
+
+# Rule Extraction
+
+Rules are the atoms of verification. Each rule you extract will become its own skill folder, its own workflow, and its own production pipeline. The quality of your extraction determines everything downstream.
+
+## Philosophy
+
+A well-extracted rule is:
+- **Atomic**: it checks one thing. "The borrower's debt-to-income ratio must not exceed 50%" is one rule. "The loan agreement must comply with Regulation X" is not — it is a container for many rules.
+- **Testable**: given a document, you can definitively say whether the rule passes or fails (or is not applicable).
+- **Self-contained**: the rule's meaning does not require reading ten other rules to understand. Cross-references should be resolved into the rule's description.
+- **Scoped**: you know WHERE in the document to look. "Chapter 3, Section 2" or "the risk disclosure section" or "the signature page."
+
+But perfection is the enemy of progress. Extract rules at the granularity that feels right for the regulation and the business scenario. You will iterate. The developer user will tell you if rules are too coarse or too fine.
+
+## Rule Schema Design Principles
+
+Individual rules should be atomic and testable (above). The rule catalog as a whole must also satisfy system-level properties:
+
+### Coverage Target
+Extracted rules should cover at least 95% of the regulation's checkable requirements. After initial extraction, perform a coverage audit: read the source regulation end-to-end and mark which paragraphs are covered by at least one rule. Uncovered paragraphs are either non-checkable (definitions, context) or gaps to close.
+
+### Atomicity Test
+One rule = one pass/fail outcome. If a rule can produce two independent pass/fail results, it should be two rules. Ask: "Can this rule partially pass?" If yes, decompose further.
+
+### Ambiguity Minimization
+No two rules should produce contradictory results on the same document. After extraction, review rule pairs that touch overlapping scope. If Rule A says pass and Rule B says fail for the same entity, their scope boundaries are unclear — fix them.
+
+### Downstream Anticipation
+Rules will be distilled into workflows (see `skill-to-workflow`). Design with distillation in mind: clear input/output boundaries, explicit judgment criteria, minimal reliance on implicit domain knowledge. If a rule requires reading between the lines, make the interpretation explicit. Use `task-decomposition` to identify natural boundaries between rules.
+
+### Catalog Versioning
+When rules change (additions, modifications, deprecations), version the entire rule catalog as a unit. Individual rule versions track specific rules; the catalog version tracks the coherent set. Record the catalog version in `versions.json` alongside individual rule versions.
+
+## Extraction Strategies
+
+### Strategy 1: Structured Input (Developer User Provides Rules)
+
+When the developer user provides rules in xlsx, csv, or a structured document where each row/entry is a distinct rule with clear scope:
+- Follow their structure exactly. Do not re-decompose.
+- Map each row to a rule, preserving the developer user's identifiers.
+- Ask clarifying questions only if entries are ambiguous.
+
+### Strategy 2: Hierarchical Extraction from Regulation Text
+
+For raw regulation documents (PDF, DOCX, legal text):
+
+1. **Survey the document structure.** Read the table of contents or scan headers. Understand the hierarchy: parts, chapters, sections, articles, clauses.
+2. **Identify rule-bearing sections.** Not every section contains a verification rule. Some are definitions, some are procedural, some are context. Focus on sections that impose obligations, prohibitions, thresholds, or requirements.
+3. **Peel the onion.** Start at the highest structural level and work downward:
+   - Level 1: What major areas does the regulation cover? (e.g., capital adequacy, risk disclosure, governance)
+   - Level 2: Within each area, what are the specific chapters or sections?
+   - Level 3: Within each section, what are the individual requirements?
+   - Stop peeling when you reach atomic rules.
+4. **Handle cross-references.** Regulations love to say "as defined in Section X" or "subject to the conditions in Article Y." Resolve these by including the referenced content in the rule's description, not just the reference.
+5. **Handle compound rules.** "The report must include (a) risk factors, (b) financial projections, and (c) management discussion" — this is three rules, not one. Decompose unless the developer user specifically wants them grouped.
+
+For long documents (100+ pages), use the onion-peeler approach described in `references/chunking-strategies.md`. Do not try to read the entire document in one pass.
+
+### Strategy 3: Expert Notes
+
+Sometimes rules come from the developer user's domain expertise rather than formal regulations:
+- "We always check that the guarantor's signature matches the name on page 1."
+- "If the collateral value is below 120% of the loan amount, flag it."
+
+Capture these with the same rigor as formal regulation rules. They are equally important in the verification app.
+
+## Rule Catalog
+
+Maintain a lightweight catalog of all extracted rules. This is your index, not the rules themselves (those live in skill folders). The catalog should track:
+
+- Rule ID (simple sequential: R001, R002, ...)
+- Rule title (one line)
+- Source (which regulation document, which section)
+- Status (extracted / skill-written / skill-tested / workflow-written / workflow-tested / production)
+- Dependencies (rules that must be checked before this one)
+
+Format: a simple markdown table or JSON file. Do not over-engineer this. The catalog exists to give you and the developer user an overview of progress.
+
+## Handling Ambiguity
+
+Regulations are often ambiguous. When you encounter ambiguity:
+1. Extract the rule as you understand it.
+2. Note the ambiguity explicitly in the rule description.
+3. Ask the developer user for clarification.
+4. Update the rule after receiving clarification.
+
+Do not skip ambiguous rules. They are often the most important ones.
+
+## When Rules Change
+
+Regulations evolve. When the developer user adds new or updated regulation documents:
+1. Identify which existing rules are affected.
+2. Extract new rules or update existing ones.
+3. Mark affected workflows for re-testing.
+4. Use `version-control` to track the change.

package/template/skills/en/meta-meta/rule-extraction/references/chunking-strategies.md

@@ -0,0 +1,80 @@
+# Chunking Strategies for Long Documents
+
+When regulation documents exceed what you can process in a single pass, use these proven strategies to decompose them into manageable chunks while preserving semantic coherence.
+
+## The Onion Peeler (Primary Strategy)
+
+Hierarchical header-based decomposition. Named because you peel the document layer by layer, from the outermost structure inward.
+
+### How It Works
+
+1. **Parse the document's header hierarchy.** Identify all headers by level (H1, H2, H3, etc. — or their equivalents in the document's formatting: "Part I", "Chapter 1", "Section 1.1", "Article 1").
+2. **Build a tree.** Each header becomes a node. Content between headers belongs to the nearest preceding header at that level.
+3. **Check sizes.** Walk the tree. If a node's content (including all its children) fits within your processing limit, stop — this node is a chunk.
+4. **Split only when necessary.** If a node exceeds the limit, descend to its children. Only split when a node is too large AND has sub-headers to split on.
+5. **Leaf nodes that are still too large** get handled by the wedge-driving fallback (see below).
+
+### Why This Works
+
+- Respects the document's own semantic structure. A "Chapter 3: Risk Disclosure" chunk contains exactly what the author intended that chapter to contain.
+- Minimizes information loss. You never cut in the middle of a thought.
+- Produces chunks of varying size — and that is fine. A short chapter is better as one chunk than split into artificial halves.
+
+### Pattern Discovery Shortcut
+
+Before building a full parser, explore several sample documents for structural patterns:
+- Do all chapter titles start with "Chapter X" or "第X章"?
+- Are sections numbered consistently (1.1, 1.2, 1.3)?
+- Are there visual markers (bold text, specific fonts, horizontal rules)?
+
+If you find consistent patterns, a regex-based splitter is faster and more reliable than LLM-based structure detection. For example:
+- `^第[一二三四五六七八九十百]+章` for Chinese chapter headers
+- `^Chapter \d+` for English chapter headers
+- `^\d+\.\d+` for numbered sections
+
+Always validate the regex against multiple documents before committing to it.
+
+## Wedge Driving (Fallback Strategy)
+
+For content without clear headers — dense legal text, continuous prose, or leaf nodes from the onion peeler that are still too large.
+
+### How It Works
+
+The algorithm uses a **rolling context window** to process documents of arbitrary length without loading the full text at once.
+
+**Step 1: Window the content.** Load up to MAX_TOKENS (e.g., 100K tokens — configurable) of the remaining unprocessed text into a window. If the remaining text fits in a single chunk, stop — no further splitting needed.
+
+**Step 2: Ask an LLM for cut points.** Prompt the LLM to identify 1-3 natural break points within the window where topic or subject changes. For each cut point, the LLM returns:
+- `tokens_before`: ~K tokens (default K=50) immediately BEFORE the cut, copied verbatim from the text.
+- `tokens_after`: ~K tokens immediately AFTER the cut, copied verbatim.
+- `chunk_title`: a 5-10 word title describing the chunk that precedes the cut.
+
+Using token count (not word count) gives consistent granularity across languages — critical for Chinese text which has no whitespace-delimited words.
+
+**Step 3: Locate the cuts via fuzzy matching.** The LLM's quoted tokens will not be a perfect match to the source text (minor paraphrasing, whitespace differences, encoding artifacts). Use Levenshtein distance (edit distance) to find the best match:
+1. Search the source text for the position that best matches `tokens_before`. Require at least 70% similarity (similarity = 1 - edit_distance / max_length).
+2. The cut position is immediately after the matched `tokens_before` region.
+3. Verify by checking that `tokens_after` appears near the cut position. If `tokens_after` cannot be matched, fall back to the position derived from `tokens_before` alone.
+
+**Step 4: Slide and repeat.** Create a chunk from the text before the first confirmed cut. Move the window forward: the new window starts from the last cut point. Repeat until all remaining text fits in a single chunk.
+
+### Why This Works
+
+- The LLM identifies semantic boundaries, not arbitrary character counts.
+- The LLM never regenerates text — it only quotes positions. No hallucination risk.
+- K-token quoting with Levenshtein matching is language-agnostic. It works for Chinese, English, and mixed-language documents equally well.
+- The rolling window means documents of any length can be processed incrementally — the algorithm is not bounded by context window size.
+- Fuzzy matching handles the inevitable small differences between the LLM's quoted text and the actual source.
+
+### When to Use
+
+- Only when the onion peeler cannot split further (no sub-headers available).
+- For documents with no structural markup at all.
+- Cost consideration: this requires LLM calls. Use the cheapest model that can identify topic boundaries (often TIER3 or TIER4 is sufficient).
+
+## Practical Guidelines
+
+- **Chunk size depends on the downstream task.** For rule extraction by the coding agent, chunks can be large (100K+ tokens). For worker LLM processing, chunks must fit in 16K-32K context.
+- **Preserve context.** When splitting, include the parent header chain as context. A chunk from "Part II > Chapter 3 > Section 3.2" should include those headers so downstream processing knows where the content belongs.
+- **Cache the tree.** Once a document's structure is parsed, save the tree. Multiple rules may need content from the same document, and re-parsing is wasteful.
+- **Log your chunking decisions.** Which strategy was used, how many chunks were produced, their sizes. This helps debug downstream issues.

package/template/skills/en/meta-meta/rule-graph/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: rule-graph
+description: Build and maintain a graph of relationships between verification rules — shared entities, logical dependencies, and conflicts. Use when analyzing the impact of a regulation change, when optimizing extraction to avoid duplicate work, when checking rule catalog completeness, or when rolling up document-level results into a summary. Critical constraint — the graph is an overlay for analysis, NOT a prerequisite for execution. Every rule must remain independently runnable.
+---
+
+# Rule Graph
+
+Rules do not exist in isolation. They share entities, depend on each other's results, and sometimes contradict each other. The rule graph makes these relationships explicit so you can reason about the rule catalog as a system rather than a flat list.
+
+But a graph can become a trap. If rules cannot run without the graph, you have built a monolith. The graph is a lens for analysis — never a gate for execution.
+
+## Independence First
+
+**CRITICAL: Every rule MUST have a self-sufficient workflow.** This is not a suggestion. It is the single most important constraint in the entire rule graph design.
+
+Enterprise systems integrate at the individual rule level. A bank's existing compliance platform calls Rule R001 to check capital adequacy, independently of any other rule. If R001 requires R003 to run first, the integration breaks. If R001 requires the graph to be loaded, the integration breaks.
+
+The graph is an overlay. It exists for the coding agent's analysis and optimization. It does NOT create hard dependencies between rules. Any rule, extracted from the graph and dropped into a standalone system, must produce correct results with only its own inputs.
+
+When you find a genuine dependency (Rule B only makes sense if Rule A has already been evaluated), encode it as metadata in the graph. The workflow for Rule B should handle the case where Rule A's result is unavailable — by computing it inline, requesting it as an optional input, or marking its own result as incomplete.
+
+## What the Graph Captures
+
+### Shared Entities
+
+Rules that extract the same entity from the same document region. R001 (capital adequacy) and R004 (tier-1 capital ratio) both need the capital figures from the balance sheet. The graph records this so an optimizer can extract once and share.
+
+But shared extraction is an optimization, not a requirement. Each rule's workflow must include its own extraction logic as the default path. The shared extraction is a fast path that the system can use when rules run together.
+
+### Logical Dependencies
+
+Rule B applies only if Rule A passes. "If the borrower is classified as high-risk (R012), then enhanced due diligence documents are required (R013)." The graph captures this so that:
+- When presenting results, R013 can be shown in context of R012.
+- When R012's logic changes, you know R013 may be affected.
+
+The workflow for R013 must still function if R012's result is not available — it should either compute the high-risk classification itself or flag that it cannot determine applicability.
+
+### Conflicts
+
+Two rules that can produce contradictory guidance. Regulation A requires disclosure of all related-party transactions; Regulation B's privacy provisions restrict disclosure of certain transaction details. The graph marks this conflict so the coding agent can escalate to the developer user rather than silently choosing one rule over the other.
+
+### Shared Corner Cases
+
+Edge cases that affect multiple rules. A document with an unusual structure (merged cells in a table, non-standard date format) may cause extraction failures across several rules. The graph links these rules to the shared corner case so a fix in one propagates awareness to others.
+
+## Three Uses
+
+### 1. Impact Analysis
+
+A regulation changes. Which rules are affected? Traverse the graph from the changed rule:
+- Direct edges: rules that share entities or have dependencies.
+- Second-degree edges: rules that depend on affected rules.
+- Conflict edges: rules whose conflict resolution may need revisiting.
+
+Without the graph, impact analysis requires reading every rule to check for overlap. With the graph, it is a traversal.
+
+### 2. Optimization
+
+When processing a batch of documents against many rules, the graph identifies:
+- **Shared extraction**: extract entity X once, use it in rules R001, R004, R007.
+- **Execution ordering**: if R012 runs before R013, R013 can use R012's result as a shortcut (but must not require it).
+- **Parallel groups**: rules with no edges between them can run in parallel.
+
+The optimization is opportunistic. It makes batch processing faster. It must never make individual rules dependent on the batch context. A rule pulled out of the batch and run alone must still work.
+
+### 3. Completeness Checking
+
+Map regulation paragraphs to rules. The graph helps identify:
+- **Uncovered sections**: regulation paragraphs that no rule addresses.
+- **Over-covered sections**: paragraphs addressed by multiple overlapping rules (potential redundancy).
+- **Coverage target**: aim for 95% of substantive regulation paragraphs mapped to at least one rule.
+
+### 4. Document-Level Rollup
+
+When presenting results for a document checked against many rules, use the graph to:
+- **Group related results**: show capital adequacy rules together, show disclosure rules together.
+- **Order by dependency**: show R012 (risk classification) before R013 (enhanced due diligence).
+- **Highlight conflicts**: when two rules produce contradictory results, surface the conflict rather than burying it in a flat list.
+- **Aggregate severity**: if five related rules all fail, that cluster may be more significant than five unrelated failures.
+
+## Representation
+
+The graph is stored as a JSON adjacency list in the rule catalog directory.
+
+```json
+{
+  "nodes": {
+    "R001": {"name": "Capital adequacy ratio", "category": "capital"},
+    "R004": {"name": "Tier-1 capital ratio", "category": "capital"},
+    "R012": {"name": "Borrower risk classification", "category": "risk"},
+    "R013": {"name": "Enhanced due diligence", "category": "due_diligence"}
+  },
+  "edges": [
+    {"from": "R001", "to": "R004", "type": "shares_entity", "entity": "capital_figures"},
+    {"from": "R012", "to": "R013", "type": "depends_on", "condition": "R012 result is high-risk"},
+    {"from": "R008", "to": "R015", "type": "conflicts_with", "detail": "Disclosure vs privacy"}
+  ]
+}
+```
+
+**Edge types:**
+- `shares_entity`: Both rules extract the same entity. Optimization opportunity.
+- `depends_on`: Target rule's applicability depends on source rule's result. Metadata only — not a hard execution dependency.
+- `conflicts_with`: Rules may produce contradictory guidance. Requires escalation logic.
+- `shares_corner_case`: Both rules are affected by the same edge case pattern.
+
+The graph is updated whenever the rule catalog changes — new rules added, rules modified, rules retired. It is visualizable through `dashboard-reporting` as a node-link diagram.
+
+## Integration
+
+**Input:** Rule catalog from `rule-extraction`. The graph is built after rules are extracted and updated as rules evolve.
+
+**Enriches:**
+- `skill-authoring`: When writing a new rule skill, check the graph for related rules. Reference shared entities and dependencies in the skill's SKILL.md.
+- `quality-control`: When a rule's accuracy drops, check the graph for downstream rules that may also be affected.
+
+**Feeds:**
+- `dashboard-reporting`: Graph visualization, impact analysis results, coverage metrics.