kc-beta 0.6.2 → 0.7.0

package/template/release/v1/run.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""
+KC release runner v1.
+
+Entry point for a self-contained KC release bundle. Loads the manifest,
+iterates rules, dispatches each rule's workflow against the supplied
+input documents, writes per-document verdict JSONs to output/results/.
+
+Usage:
+    python3 run.py <input_dir>
+    python3 run.py <input_dir> --rules R001,R005,R012
+    python3 run.py --doc <single_file>           # single-doc smoke test
+
+The bundle is shipped from KC's finalization phase. KC's run-in-CLI
+mode is the source of truth; this is the ship-as-artifact form for
+re-running verification on new document batches without the full KC
+toolchain installed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import subprocess
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+
+# Add kc_runtime to path so submodules import cleanly when run from any cwd.
+sys.path.insert(0, str(HERE))
+
+from kc_runtime import doc_parser, confidence  # noqa: E402
+
+
+def _load_json(path: Path, *, required: bool = False, default=None):
+    if not path.exists():
+        if required:
+            raise SystemExit(
+                f"required file missing: {path}\n"
+                f"this release bundle was shipped without a complete manifest.\n"
+                f"re-run KC finalization or contact the bundle author."
+            )
+        return default
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _select_rules(catalog, rule_filter):
+    if not rule_filter:
+        return catalog
+    wanted = set(rule_filter.split(","))
+    return [r for r in catalog if r.get("id") in wanted]
+
+
+def _list_input_docs(input_dir: Path):
+    if not input_dir.is_dir():
+        raise SystemExit(f"input_dir not a directory: {input_dir}")
+    docs = []
+    for entry in sorted(input_dir.iterdir()):
+        if entry.is_file() and not entry.name.startswith("."):
+            docs.append(entry)
+    return docs
+
+
+def _run_workflow(rule_id: str, workflow_path: Path, doc_path: Path) -> dict:
+    """
+    Dispatch a single workflow against a single document.
+
+    Each workflow is a stand-alone Python script that takes a document
+    path on argv and emits a JSON verdict on stdout. Workflows are
+    sandbox-runnable: no shared module state, no special imports beyond
+    stdlib + kc_runtime.
+    """
+    if not workflow_path.exists():
+        return {
+            "rule_id": rule_id,
+            "verdict": "ERROR",
+            "confidence": 0.0,
+            "error_type": "workflow_missing",
+            "reason": f"workflow not found: {workflow_path.name}",
+        }
+    try:
+        proc = subprocess.run(
+            [sys.executable, str(workflow_path), str(doc_path)],
+            capture_output=True,
+            text=True,
+            timeout=180,
+        )
+        if proc.returncode != 0:
+            return {
+                "rule_id": rule_id,
+                "verdict": "ERROR",
+                "confidence": 0.0,
+                "error_type": "workflow_exit_nonzero",
+                "reason": (proc.stderr or proc.stdout or "").strip()[:500],
+            }
+        # Workflow contract: last stdout line is the verdict JSON.
+        last = next(
+            (line for line in reversed(proc.stdout.splitlines()) if line.strip()),
+            None,
+        )
+        if not last:
+            return {
+                "rule_id": rule_id,
+                "verdict": "ERROR",
+                "confidence": 0.0,
+                "error_type": "empty_workflow_output",
+            }
+        verdict = json.loads(last)
+        verdict.setdefault("rule_id", rule_id)
+        return verdict
+    except subprocess.TimeoutExpired:
+        return {
+            "rule_id": rule_id,
+            "verdict": "ERROR",
+            "confidence": 0.0,
+            "error_type": "workflow_timeout",
+        }
+    except json.JSONDecodeError as exc:
+        return {
+            "rule_id": rule_id,
+            "verdict": "ERROR",
+            "confidence": 0.0,
+            "error_type": "workflow_output_not_json",
+            "reason": str(exc),
+        }
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="run.py", description="KC release runner")
+    parser.add_argument("input_dir", nargs="?", help="Directory of input documents")
+    parser.add_argument("--doc", help="Single document path (smoke-test mode)")
+    parser.add_argument("--rules", help="Comma-separated rule_ids to run (default: all)")
+    parser.add_argument("--output-dir", default=str(HERE / "output" / "results"))
+    args = parser.parse_args()
+
+    if not args.input_dir and not args.doc:
+        parser.error("either input_dir or --doc is required")
+
+    manifest = _load_json(HERE / "manifest.json", required=True)
+    catalog = _load_json(HERE / "catalog.json", required=False, default=[])
+    historical = _load_json(
+        HERE / "confidence_calibration.json",
+        required=False,
+        default={"historical_accuracy": {}},
+    )
+
+    rules = _select_rules(catalog, args.rules)
+    if not rules:
+        raise SystemExit("no rules to run (catalog empty or filter excluded all)")
+
+    if args.doc:
+        docs = [Path(args.doc).resolve()]
+    else:
+        docs = _list_input_docs(Path(args.input_dir).resolve())
+
+    output_dir = Path(args.output_dir).resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    workflows = manifest.get("workflows", {})
+    summary = {"total_runs": 0, "by_verdict": {}, "errors": 0}
+
+    for doc in docs:
+        # Lightweight parse — let the workflow do its own parse if needed,
+        # but offer a doc_parser preflight so workflows can rely on the
+        # text being available.
+        try:
+            doc_parser.preflight(doc)
+        except Exception as exc:
+            print(f"[run.py] preflight failed for {doc.name}: {exc}", file=sys.stderr)
+
+        results = {}
+        for rule in rules:
+            rule_id = rule.get("id")
+            if not rule_id:
+                continue
+            wf_relpath = workflows.get(rule_id)
+            if not wf_relpath:
+                results[rule_id] = {
+                    "rule_id": rule_id,
+                    "verdict": "NO_WORKFLOW",
+                    "confidence": 0.0,
+                }
+                continue
+            wf_path = HERE / wf_relpath
+            verdict = _run_workflow(rule_id, wf_path, doc)
+            verdict = confidence.calibrate(verdict, historical)
+            results[rule_id] = verdict
+            summary["total_runs"] += 1
+            v = verdict.get("verdict", "UNKNOWN")
+            summary["by_verdict"][v] = summary["by_verdict"].get(v, 0) + 1
+            if v == "ERROR":
+                summary["errors"] += 1
+
+        out_file = output_dir / f"{doc.stem}.json"
+        out_file.write_text(
+            json.dumps(
+                {"document": str(doc), "results": results}, ensure_ascii=False, indent=2
+            ),
+            encoding="utf-8",
+        )
+
+    summary_path = output_dir / "summary.json"
+    summary_path.write_text(
+        json.dumps(summary, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/template/release/v1/serve.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+# Minimal local-preview server for the KC release dashboard.
+# Renders dashboard.html if missing, then serves on PORT (default 8765).
+
+set -e
+HERE="$(cd "$(dirname "$0")" && pwd)"
+cd "$HERE"
+
+PORT="${PORT:-8765}"
+
+if [ ! -f dashboard.html ] || [ output/results/summary.json -nt dashboard.html ]; then
+  echo "rendering dashboard.html..."
+  python3 render_dashboard.py output/results/ > dashboard.html
+fi
+
+echo "serving on http://localhost:$PORT/dashboard.html"
+exec python3 -m http.server "$PORT"

package/template/skills/en/meta-meta/work-decomposition/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: work-decomposition
+description: Decide how to decompose the rule set into TaskBoard tasks during rule_extraction → skill_authoring transition. Covers ordering methodologies (difficulty-first / Shannon–Huffman, breadth-first, depth-first, binary partition), grouping rules (when to bundle multiple rules into one task vs. keep separate), three-axis difficulty estimation, and how to write PATTERNS.md project memory that stays useful across the run. Use when entering rule_extraction, when entering skill_authoring, or whenever the TaskBoard feels wrong and you want to re-decompose.
+---
+
+# Work Decomposition
+
+KC's main agent is the conductor. The conductor decides what work to do next — and that decision is upstream of every other choice that follows. Wrong decomposition makes the rest of the run expensive: if rules are processed in the wrong order, the agent re-designs the same shape three times. If unrelated rules are bundled into one skill, the resulting check.py becomes the unified-runner anti-pattern from E2E #4. If related rules are split across separate skills, the agent re-derives the shared chunker logic 17 times.
+
+This skill is the conductor's playbook for that decision. It ships under `meta-meta/` because work decomposition is a system-level discipline, not a per-rule technique. The complementary `task-decomposition` skill (also under `meta-meta/`) covers the *internal* structure of one rule's check — locate, extract, normalize, judge, comment. This skill covers how the rule **set** should be split into TaskBoard items.
+
+## When to use this skill
+
+- **Entering rule_extraction.** Read the regulation, decompose into rules, then decide how those rules will be ordered and grouped before declaring the phase done. Coverage audit + chunk refs are downstream of these decisions.
+- **Entering skill_authoring.** TaskBoard is empty (engine no longer auto-populates per-rule tasks). Read the rule list from `describeState`, decide grouping + order, then call `TaskCreate` for each unit of work.
+- **Mid-run re-decomposition.** If the TaskBoard feels wrong (rules accumulating in the wrong order, an obviously-bundled pair across two tasks), stop adding work and re-decompose. The cost of pausing 5 minutes to re-plan is recovered within 2 rules of better-shaped work.
+
+## Locked principles
+
+1. **Hard tracking, soft executing.** The engine derives milestones from disk facts (`rule_skills/<id>/SKILL.md`, `check_*.py`, `workflows/<id>/...`) regardless of how you grouped your tasks. Coverage is engine-verified; grouping is your call. You cannot bypass the floor by clever task naming, but the floor doesn't dictate task shape.
+2. **The hardest rule contains the most information.** Hard rules force the chunker, classifier, verdict shape, and worker LLM tier you'll need. Easy rules can compile down to a subset of that machinery cheaply. Encode the hard cases first; let the easy cases inherit.
+3. **PATTERNS.md is the load-bearing memory.** Without an accumulating reference, every rule starts from a blank slate and you re-design the same shape repeatedly. With it, work compounds.
+
+---
+
+## Ordering methodologies
+
+Pick one explicitly and write it into your first PATTERNS.md entry. "I'm going Shannon–Huffman because R028's multi-party verdict shape will dictate the chunker for everyone else" is a valid decision; "I started at the top of catalog.json and kept going" is not — it's just absence of decision.
+
+### Shannon–Huffman (difficulty-first) — recommended default
+
+Process the **hardest** rule first. Use the chunker, verdict shape, and worker tier that hard rule demands as the design floor. Process subsequent rules in descending difficulty, each one a degenerate case of the machinery already built.
+
+**When to pick:** the rule set has uneven complexity and you suspect a few hard rules will dictate the shape (almost always true for compliance / regulatory work). E2E #5 GLM accidentally followed this path and produced 0.6% ERROR on real LLM-driven workflows; DS started bottom-up and shipped 78% NOT_APPLICABLE.
+
+**Why "Huffman" not "Shannon" for the analogy:** Huffman builds optimal prefix codes by processing low-frequency symbols first. KC's analogue is the high-cost-per-rule, low-frequency rules — the R028s that dominate the design space even though there are few of them. Touch them first. The easy rules inherit the framework cheaply.
+
+**The ordering compiler-design parallel:** don't optimize the common case until you've handled the worst case correctly. The common case being fast doesn't matter if the worst case requires a redesign.
+
+### Breadth-first (round-robin)
+
+Process every rule to a shallow depth (skill skeleton + first regex pass), then go back and deepen each one. Useful when:
+
+- The full set's quality matters more than per-rule depth (e.g., you need a coverage report fast)
+- You don't yet know which rules are hard
+- You're piloting a new methodology and want to validate the pipeline shape across many rules cheaply
+
+**Trap:** you may declare rule_extraction done with shallow skills that never deepen. Worse than depth-first because the gate appears satisfied from coverage alone.
+
+### Depth-first (one rule at a time, fully done)
+
+Process rule 1 to completion (SKILL.md + check.py + tests passing) before touching rule 2. Useful when:
+
+- Rules are largely independent (rare in compliance work)
+- The conductor model has small context and re-loading shape between rules is cheap
+- You're proving the end-to-end pipeline before scaling
+
+**Trap:** the first rule's shape gets locked in; refactoring after rule 5 means rewriting 1-4. Combine with PATTERNS.md to mitigate.
+
+### Binary partition
+
+Split the rule set into two halves on a meaningful axis (public/private products, document type, regulation chapter), then recurse. Useful when:
+
+- The split axis is structural (e.g., banking rules vs trust rules) — you can build separate tools per partition
+- Some partitions can be skipped entirely (D6 applicability filter says "not applicable for this corpus")
+
+**Trap:** premature partitioning when the axis isn't real. The agent commits to two tools that turn out to need a shared base. Validate the split with 2-3 rules per side before committing.
+
+### "Easiest first" — what NOT to default to
+
+Tempting because it builds confidence and ships something visible quickly. Do not default to it for regulatory rule sets — the easy rules teach you nothing transferable about the hard ones, and the framework crystallizes around the wrong shape. Use it only when you're piloting tooling on a brand-new project and need to prove the pipeline can produce ANY output before sizing the real work.
+
+---
+
+## Grouping rules
+
+The default is **one rule per task → one rule per skill directory**. This keeps coverage measurable and the TaskBoard clear. Group only when grouping reduces total work without coupling unrelated concerns.
+
+### When to bundle
+
+Bundle multiple rules into a single task (and a single check_r###_r###.py file) when ALL of:
+
+- The rules share the same source chunk(s) — looking at the same paragraph of the same regulation
+- They share the same input format (e.g., a required-fields table)
+- The judgment logic for one rule is a substring or close variant of the next
+- A single failure typically implies multiple failures (you can't pass R013 if R015 fails)
+
+Example: R013 / R015 / R017 all check that a specific table on page 3 of the report contains certain mandatory fields. Same chunk, same parse, same verdict shape. Bundle as `check_r013_r015_r017.py` and create a single TaskCreate task `R013/R015/R017 — required-fields table`. The engine's filesystem-derived milestones recognize the grouped check.py and credit all three rule_ids.
+
+### When to keep separate
+
+Keep separate when ANY of:
+
+- Rules cite different regulation chapters — even if conceptually related (e.g., R013 disclosure-content and R028 custodian-responsibility — both about reports, but different chapters / different evidence chains)
+- Rules need different worker LLM tiers (R005 needs a flagship for nuanced judgment, R001 is regex)
+- Rules apply to different document types (one applies only to public-fund reports, another only to private-fund reports)
+- One rule's failure mode is a specific failure mode of another (don't bundle parent + child rules — the child's check redundantly re-runs the parent's)
+
+The v0.6.2 D2 anti-pattern wording captures the failure case clearly:
+> If you find yourself writing a unified_qc.py-style monolith that bypasses individual skills, your per-rule skills are wrong. Fix them, don't replace them.
+
+That came from E2E #4 where one conductor wrote a 2,400-line `unified_qc.py` that ran all rules at once. It produced 1,150 ERROR verdicts (16.6%) because every rule's failure cascaded into every other rule's verdict. Per-rule skills are KC's unit of granularity for a reason.
+
+### Naming convention for grouped checks
+
+When you do bundle, name the file with the explicit range:
+
+- `check_r013_r015_r017.py` — three specific rules
+- `check_r002_r007.py` — contiguous range (R002 through R007)
+- `check_r013-r017.py` — alternative spelling, also accepted
+
+The engine's filesystem-derived milestones parse these names and credit each constituent rule_id. The grouping is documentation as much as code organization — downstream consumers (workflow-run, dashboards, release tool) read the filename to know coverage.
+
+---
+
+## Difficulty estimation — three-axis triage
+
+Before you commit to an order, score each extracted rule on three axes. One quick worker LLM call per rule (tier3 is sufficient — not a deep judgment) writes a `rules/difficulty.json` that the conductor then reads when deciding TaskBoard order.
+
+### Axis 1 — Chain-of-thought depth
+
+How many sequential judgments does the rule require? Count operations the agent has to chain together:
+
+- 1: `text contains "industry-unified channel"` (regex)
+- 2: classify product type, then check channel (two-step)
+- 3+: classify product type, locate disclosure section, parse table, compare against another section's table (multi-step)
+
+Score: 1 / 2 / 3+ on this axis.
+
+### Axis 2 — Module count
+
+How many distinct sub-checks does the rule encompass? A "module" is a logically separable predicate.
+
+- 1: single predicate ("must mention channel A")
+- 2-3: a small required-fields list ("must mention A, B, C, D")
+- 4+: a large checklist or conditional branch ("if public fund, then channels X+Y; if private, then channel Z; in all cases also include the manager identity")
+
+Score: 1 / 2-3 / 4+ on this axis.
+
+### Axis 3 — Cross-rule interaction
+
+Does the rule reference another rule, depend on its output, or have to resolve consistency with it?
+
+- 0: standalone (most rules)
+- 1: cross-references one other rule (e.g., R007 references R013's table existence)
+- 2+: tightly coupled with multiple rules, requires consistency reasoning across them
+
+Score: 0 / 1 / 2+ on this axis.
+
+### Total difficulty
+
+Sum the three axes (1+1+0 = 2 minimum, 3+3+2 = 8 maximum). Sort descending. The 2-3 highest are your design-floor cases — work them first.
+
+For a 70-rule corpus, expect difficulty distribution roughly:
+- 10-15 hard (sum 5-8)
+- 30-40 medium (sum 3-4)
+- 20-30 easy (sum 2)
+
+Don't over-engineer the triage. It's a planning aid, not a contract. If during work you discover a rule scored 2 was actually a 6, update PATTERNS.md and re-sort the remaining queue.
+
+---
+
+## PATTERNS.md — project memory discipline
+
+KC's main agent does not have continuous memory across phases. Every time the agent re-reads `describeState`, it sees the same rule list and the same milestones. Without an external accumulating reference, every rule's design starts from scratch.
+
+`rules/PATTERNS.md` is that reference. The agent owns it (writes via `workspace_file`, not via any tool wrapper). The engine surfaces it in every system prompt of skill_authoring + skill_testing. Capped at ~5 KB so token cost stays trivial.
+
+### What to write — patterns that transfer
+
+A good PATTERNS.md entry captures something that will SAVE work on the next rule. Three legitimate categories:
+
+✅ **Transferable shape** — a verdict shape, chunker granularity, or interface decision that subsequent rules will reuse.
+
+```
+R028 (custodian responsibility) needed multi-party verdict shape:
+  { primary_party: PASS|FAIL, secondary_parties: [...], reasons: [...] }
+Adopting as default for any rule with multiple liable entities.
+Confirmed reusable on R029, R031.
+```
+
+✅ **Project-level constraint** — a fact about the corpus or environment that affects multiple rules.
+
+```
+Sample corpus has bilingual table headings (EN+ZH).
+Chunker MUST split on the ZH heading boundary, not the EN one —
+verified on 5 sample docs. Without this, R013 / R015 / R017 all
+under-extract.
+```
+
+✅ **Anti-pattern with rationale** — a thing you tried, why it failed, what to do instead.
+
+```
+Tried tier4 for JSON-output verdicts → empty responses 80% of the time.
+tier3 (Qwen3.5) hallucinates field names. Settled on tier2 (DeepSeek-V3.2)
+for any structured-output rule. Tier1 reserved for verdict reasoning under
+ambiguous evidence (R005, R024).
+```
+
+### What NOT to write — log-dump anti-patterns
+
+These add token cost without adding decision value. Future-you reading PATTERNS.md is trying to figure out what to do, not reconstruct what already happened.
+
+❌ **Completion log** — already in tasks.json + filesystem.
+
+```
+R001 done. R002 done. R003 partial pass. R004 done.
+```
+
+❌ **Tool history echo** — already in events.jsonl.
+
+```
+Called workspace_file to write check_R013.py. Then called sandbox_exec.
+Then ran the result through worker_llm_call.
+```
+
+❌ **Filesystem-authoritative facts** — the engine derives these from disk.
+
+```
+Workflows live under workflows/R001_workflow.py. There are 28 of them.
+```
+
+❌ **Conversation summary** — neither agent nor user reads PATTERNS.md as narrative.
+
+```
+After discussing with the user, we decided to focus on banking rules first.
+The user mentioned that trust products are out of scope.
+```
+
+If a project-level decision came out of conversation, write it as a constraint:
+
+```
+Trust products excluded from this run (D6 applicability NO).
+Skip R078, R092, R104 — their skills exist as stubs only.
+```
+
+### When to update vs append
+
+- **Append** when you discover something new and transferable.
+- **Update an existing entry** when work on a later rule reveals a better abstraction. Don't lock yourself into the first hard rule's shape — JIT compilers recompile when profile data invalidates the original assumption; PATTERNS.md should evolve the same way.
+- **Delete an entry** when you discover it was wrong. Mark the deletion with a brief rationale at the bottom of the file:
+
+```
+[DELETED 2026-04-29] "Always use tier1 for FAIL verdicts"
+Why: R005 + R007 work fine on tier2; tier1 reserved for genuinely
+ambiguous evidence cases only (3 rules across the set).
+```
+
+### Sizing
+
+Keep PATTERNS.md under ~5 KB total. If it exceeds, prune the least-actionable entries (the ones that haven't influenced any decision in the last 5 rules). Memory is for what you're using, not what you've seen.
+
+---
+
+## Putting it together — opening sequence
+
+When entering skill_authoring with an empty TaskBoard:
+
+1. **Read `describeState`.** Look at the rule list, the milestones (rules with chunk refs / coverage audited), and any existing PATTERNS.md.
+2. **If PATTERNS.md is empty:** spend ~2 turns deciding ordering methodology + first 3-5 patterns. Write PATTERNS.md as your first artifact, before any skill code.
+3. **If `rules/difficulty.json` exists:** sort rules by difficulty descending. Group where appropriate per the rules above. Call `TaskCreate` for each unit.
+4. **If `rules/difficulty.json` doesn't exist:** decide whether to spend the worker LLM calls to triage (almost always yes for a corpus of >20 rules). Run the triage step (one tier3 call per rule, batched in groups of 10 if you want), write `rules/difficulty.json`, then proceed to step 3.
+5. **Pick the first task.** Work it to completion (skill + check + at least one local test). Update PATTERNS.md with whatever you learned. Move to the next task.
+6. **At task ~5 and task ~10:** stop and re-read PATTERNS.md. If patterns suggest a refactor of earlier work, do it now (cheap) rather than later (expensive).
+
+The engine's filesystem-derived milestones (Group A v0.7.0) verify coverage on disk regardless of how you split the work. The TaskBoard is your scratchpad; the disk is the contract.

package/template/skills/en/skill-creator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-creator
-description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
+description: Anthropic's skill-scaffolding toolkit — use for iterating/improving existing skills or running evals on them, NOT as the primary reference for building KC's per-rule verification skills. For KC rule skills, read `meta-meta/skill-authoring` first (canonical folder layout + granularity rules + KC-specific check.py entry-point conventions) and `meta-meta/work-decomposition` for ordering + grouping decisions. This skill applies once per-rule skills exist and the agent wants to optimize their description/triggering or run formal evals.
 ---
 
 # Skill Creator