kc-beta 0.3.1 → 0.5.3

package/template/release-runtime/kc_runtime/dashboard.py

@@ -0,0 +1,208 @@
+"""
+End-user dashboard renderer — Python port of DashboardRenderTool._renderHtml.
+
+Takes a release-run result JSON (the output of run.py) and emits a static
+HTML dashboard. Dark theme, two tabs (Summary + Per-Rule), no external
+dependencies, no JS framework — vanilla JS for tab switching only.
+"""
+
+import html as _html
+import json
+from datetime import datetime, timezone
+
+
+def render(result, manifest):
+    """
+    result: dict from run.py — keys: release, snapshot_tag, input,
+            started_at, duration_ms, results: [{rule_id, value, confidence,
+            confidence_band, extraction_method, exit_code, raw}]
+    manifest: dict from the bundle's manifest.json (for header info)
+    Returns: a complete HTML string.
+    """
+    label = manifest.get("label", result.get("release", ""))
+    snap_tag = manifest.get("snapshot_tag", result.get("snapshot_tag", ""))
+    input_doc = result.get("input", "")
+    started = result.get("started_at", "")
+    duration_ms = result.get("duration_ms", 0)
+    rules = manifest.get("rules", [])
+    rule_titles = {r["id"]: r.get("title", "") for r in rules}
+    results = result.get("results", [])
+    generated_at = datetime.now(timezone.utc).isoformat()
+
+    # Aggregates
+    total = len(results)
+    by_band = {"high": 0, "medium": 0, "low": 0}
+    failed = 0
+    for r in results:
+        b = r.get("confidence_band") or "low"
+        by_band[b] = by_band.get(b, 0) + 1
+        if r.get("exit_code", 0) != 0:
+            failed += 1
+
+    summary_rows = []
+    for r in results:
+        rid = r.get("rule_id", "")
+        title = rule_titles.get(rid, "")
+        value = _short(r.get("value") or _value_from_raw(r.get("raw")))
+        conf = r.get("confidence", 0)
+        b = r.get("confidence_band") or "low"
+        method = r.get("extraction_method") or "?"
+        exit_code = r.get("exit_code", 0)
+        status_icon = "✓" if exit_code == 0 else "✗"
+        status_class = f"band-{b}" if exit_code == 0 else "band-fail"
+        summary_rows.append(
+            f"<tr class='{status_class}'>"
+            f"<td>{status_icon}</td>"
+            f"<td><code>{_html.escape(rid)}</code></td>"
+            f"<td>{_html.escape(title)}</td>"
+            f"<td>{_html.escape(value)}</td>"
+            f"<td>{conf:.3f}</td>"
+            f"<td>{_html.escape(b)}</td>"
+            f"<td>{_html.escape(method)}</td>"
+            f"</tr>"
+        )
+
+    detail_blocks = []
+    for r in results:
+        rid = r.get("rule_id", "")
+        title = rule_titles.get(rid, "")
+        raw_json = json.dumps(r.get("raw") or {}, ensure_ascii=False, indent=2)
+        detail_blocks.append(
+            f"<div class='detail-card'>"
+            f"<h3><code>{_html.escape(rid)}</code> &middot; {_html.escape(title)}</h3>"
+            f"<dl>"
+            f"<dt>Value</dt><dd>{_html.escape(_short(r.get('value') or _value_from_raw(r.get('raw'))))}</dd>"
+            f"<dt>Confidence</dt><dd>{r.get('confidence', 0):.3f} ({_html.escape(r.get('confidence_band') or '')})</dd>"
+            f"<dt>Method</dt><dd>{_html.escape(r.get('extraction_method') or '?')}</dd>"
+            f"<dt>Exit code</dt><dd>{r.get('exit_code', 0)}</dd>"
+            f"</dl>"
+            f"<details><summary>Raw workflow output</summary>"
+            f"<pre>{_html.escape(raw_json)}</pre>"
+            f"</details>"
+            f"</div>"
+        )
+
+    return TEMPLATE.format(
+        label=_html.escape(label),
+        snap_tag=_html.escape(snap_tag),
+        input_doc=_html.escape(input_doc),
+        started=_html.escape(started),
+        duration_s=f"{duration_ms / 1000:.2f}",
+        total=total,
+        high=by_band["high"],
+        medium=by_band["medium"],
+        low=by_band["low"],
+        failed=failed,
+        summary_rows="\n".join(summary_rows) or "<tr><td colspan='7'>(no results)</td></tr>",
+        detail_blocks="\n".join(detail_blocks) or "<p>(no results)</p>",
+        generated_at=generated_at,
+    )
+
+
+def _short(s, n=80):
+    s = "" if s is None else str(s)
+    return s if len(s) <= n else s[: n - 1] + "…"
+
+
+def _value_from_raw(raw):
+    if not isinstance(raw, dict):
+        return ""
+    for k in ("extracted_value", "value", "result"):
+        if k in raw:
+            return raw[k]
+    return ""
+
+
+TEMPLATE = """<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>KC Release {label} — Verification Result</title>
+<style>
+  body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+         max-width: 1100px; margin: 0 auto; padding: 24px;
+         background: #0a0a0a; color: #e5e5e5; }}
+  h1 {{ color: #f4f4f5; font-size: 1.5em; margin-bottom: 4px; }}
+  .meta {{ color: #737373; font-size: 0.85em; margin-bottom: 24px; }}
+  .meta code {{ color: #a3a3a3; }}
+  .card {{ background: #171717; border: 1px solid #262626; border-radius: 8px;
+          padding: 16px; margin: 12px 0; }}
+  .metrics {{ display: flex; gap: 32px; flex-wrap: wrap; }}
+  .metric .value {{ font-size: 2em; font-weight: 600; }}
+  .metric .label {{ font-size: 0.8em; color: #737373; text-transform: uppercase; letter-spacing: .03em; }}
+  .v-high {{ color: #22c55e; }}
+  .v-med {{ color: #eab308; }}
+  .v-low {{ color: #f97316; }}
+  .v-fail {{ color: #ef4444; }}
+  .tabs {{ display: flex; gap: 0; border-bottom: 1px solid #262626; margin: 24px 0 12px; }}
+  .tab {{ padding: 8px 16px; cursor: pointer; color: #737373; border-bottom: 2px solid transparent; user-select: none; }}
+  .tab.active {{ color: #f4f4f5; border-bottom-color: #22c55e; }}
+  table {{ width: 100%; border-collapse: collapse; }}
+  th, td {{ text-align: left; padding: 8px 10px; border-bottom: 1px solid #262626; font-size: 0.92em; }}
+  th {{ color: #737373; font-weight: 500; font-size: 0.78em; text-transform: uppercase; letter-spacing: .04em; }}
+  td code {{ color: #a3a3a3; }}
+  tr.band-high td:nth-child(6) {{ color: #22c55e; }}
+  tr.band-medium td:nth-child(6) {{ color: #eab308; }}
+  tr.band-low td:nth-child(6) {{ color: #f97316; }}
+  tr.band-fail td:nth-child(6) {{ color: #ef4444; }}
+  .detail-card {{ background: #171717; border: 1px solid #262626; border-radius: 8px;
+                 padding: 14px 18px; margin: 14px 0; }}
+  .detail-card h3 {{ margin: 0 0 10px; font-size: 1em; color: #e5e5e5; }}
+  .detail-card dl {{ display: grid; grid-template-columns: 100px 1fr; gap: 4px 16px; margin: 0; }}
+  .detail-card dt {{ color: #737373; font-size: 0.85em; }}
+  .detail-card dd {{ margin: 0; color: #e5e5e5; }}
+  details summary {{ cursor: pointer; color: #a3a3a3; font-size: 0.85em; margin-top: 8px; }}
+  pre {{ background: #0d0d0d; border: 1px solid #262626; border-radius: 4px;
+        padding: 10px; overflow-x: auto; font-size: 0.82em; color: #d4d4d4; }}
+  .footer {{ color: #525252; font-size: 0.78em; margin-top: 32px; text-align: center; }}
+</style>
+</head>
+<body>
+<h1>KC Release <code>{label}</code></h1>
+<p class="meta">
+  Snapshot: <code>{snap_tag}</code> &middot;
+  Input: <code>{input_doc}</code> &middot;
+  Started: <code>{started}</code> &middot;
+  Duration: <code>{duration_s}s</code>
+</p>
+
+<div class="card metrics">
+  <div class="metric"><div class="value">{total}</div><div class="label">Rules run</div></div>
+  <div class="metric"><div class="value v-high">{high}</div><div class="label">High confidence</div></div>
+  <div class="metric"><div class="value v-med">{medium}</div><div class="label">Medium</div></div>
+  <div class="metric"><div class="value v-low">{low}</div><div class="label">Low</div></div>
+  <div class="metric"><div class="value v-fail">{failed}</div><div class="label">Failed</div></div>
+</div>
+
+<div class="tabs">
+  <div class="tab active" data-target="summary" onclick="kcShow('summary', this)">Summary</div>
+  <div class="tab" data-target="detail" onclick="kcShow('detail', this)">Per-rule detail</div>
+</div>
+
+<div id="summary" class="view">
+  <div class="card">
+    <table>
+      <tr><th></th><th>Rule</th><th>Title</th><th>Value</th><th>Conf.</th><th>Band</th><th>Method</th></tr>
+      {summary_rows}
+    </table>
+  </div>
+</div>
+
+<div id="detail" class="view" style="display:none">
+  {detail_blocks}
+</div>
+
+<p class="footer">Generated {generated_at} — KC Agent CLI</p>
+
+<script>
+function kcShow(id, tab) {{
+  document.querySelectorAll('.view').forEach(v => v.style.display = 'none');
+  document.getElementById(id).style.display = '';
+  document.querySelectorAll('.tab').forEach(t => t.classList.remove('active'));
+  tab.classList.add('active');
+}}
+</script>
+</body>
+</html>
+"""

package/template/release-runtime/render_dashboard.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""
+Re-render an HTML dashboard from an existing run.py result JSON.
+
+Useful when run.py was invoked without --dashboard, or when the dashboard
+template is updated and you want to re-render past results.
+
+Usage:
+    python render_dashboard.py <result.json> [--output dashboard.html]
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+from kc_runtime import dashboard as kc_dash
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("result", help="Path to a result.json produced by run.py")
+    ap.add_argument("--output", "-o", help="HTML output path (default: alongside result)")
+    args = ap.parse_args()
+
+    result_path = Path(args.result).resolve()
+    if not result_path.is_file():
+        print(f"error: result file not found: {result_path}", file=sys.stderr)
+        sys.exit(2)
+
+    manifest_path = HERE / "manifest.json"
+    if not manifest_path.is_file():
+        print(f"error: manifest.json not found alongside this script", file=sys.stderr)
+        sys.exit(2)
+
+    result = json.loads(result_path.read_text(encoding="utf-8"))
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    html = kc_dash.render(result, manifest)
+
+    out_path = Path(args.output) if args.output else result_path.with_suffix(".html")
+    out_path.write_text(html, encoding="utf-8")
+    print(f"Wrote {out_path}")
+
+
+if __name__ == "__main__":
+    main()

package/template/release-runtime/run.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""
+KC release runner — standalone, no kc-beta dependency.
+
+Loads the bundled release manifest, runs each rule's workflow against an
+input document, scores confidence, aggregates results.
+
+Usage:
+    python run.py <input-doc> [--rule R001] [--output result.json] [--dashboard]
+
+Required env vars (same conventions as KC's .env):
+    LLM_API_KEY, LLM_BASE_URL
+    TIER1, TIER2, TIER3, TIER4   (any subset of model lists, comma-separated)
+
+Workflows are invoked as `python <workflow_path> <input-doc>` and must emit
+their result as a single JSON object on the last line of stdout.
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+# kc_runtime is bundled next to this file
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+from kc_runtime import confidence as kc_conf
+from kc_runtime import dashboard as kc_dash
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Run a KC release on a document.")
+    ap.add_argument("input", help="Path to the input document (PDF, DOCX, TXT, ...)")
+    ap.add_argument("--rule", help="Run only this rule id (default: all rules in catalog)")
+    ap.add_argument("--output", "-o", help="Write aggregated JSON here (default: stdout)")
+    ap.add_argument("--dashboard", action="store_true",
+                    help="Also emit an HTML dashboard next to the JSON output")
+    args = ap.parse_args()
+
+    input_path = Path(args.input).resolve()
+    if not input_path.is_file():
+        _die(f"Input file not found: {input_path}")
+
+    manifest = _load_json(HERE / "manifest.json", required=True)
+    catalog = _load_json(HERE / "catalog.json", required=False) or []
+    historical = _load_calibration(HERE / "confidence_calibration.json")
+    corner_cases = _load_json(HERE / "corner_cases.json", required=False)
+
+    rules = manifest.get("rules", [])
+    if args.rule:
+        rules = [r for r in rules if r.get("id") == args.rule]
+        if not rules:
+            _die(f"No rule '{args.rule}' in manifest")
+
+    if not _check_env():
+        sys.exit(2)
+
+    started = datetime.now(timezone.utc).isoformat()
+    t0 = time.monotonic()
+
+    results = []
+    any_failure = False
+    for rule in rules:
+        result = _run_one(rule, input_path, catalog,
+                          historical=historical, corner_cases=corner_cases)
+        results.append(result)
+        if result.get("exit_code", 0) != 0:
+            any_failure = True
+
+    duration_ms = int((time.monotonic() - t0) * 1000)
+    aggregated = {
+        "release": manifest.get("label"),
+        "snapshot_tag": manifest.get("snapshot_tag"),
+        "input": str(input_path),
+        "started_at": started,
+        "duration_ms": duration_ms,
+        "results": results,
+    }
+
+    out_text = json.dumps(aggregated, ensure_ascii=False, indent=2)
+    if args.output:
+        out_path = Path(args.output).resolve()
+        out_path.write_text(out_text, encoding="utf-8")
+        print(f"Wrote {out_path}", file=sys.stderr)
+    else:
+        print(out_text)
+
+    if args.dashboard:
+        html = kc_dash.render(aggregated, manifest)
+        if args.output:
+            html_path = Path(args.output).with_suffix(".html")
+        else:
+            html_path = HERE / f"result_{int(time.time())}.html"
+        html_path.write_text(html, encoding="utf-8")
+        print(f"Dashboard: {html_path}", file=sys.stderr)
+
+    sys.exit(1 if any_failure else 0)
+
+
+def _run_one(rule, input_path, catalog, *, historical, corner_cases):
+    rule_id = rule.get("id")
+    workflow_rel = rule.get("workflow")
+    if not workflow_rel:
+        return _error_result(rule_id, "no workflow path in manifest")
+
+    workflow_abs = (HERE / workflow_rel).resolve()
+    if not workflow_abs.is_file():
+        return _error_result(rule_id, f"workflow not found: {workflow_rel}")
+
+    try:
+        proc = subprocess.run(
+            ["python", str(workflow_abs), str(input_path)],
+            capture_output=True, text=True, timeout=300,
+        )
+    except subprocess.TimeoutExpired:
+        return _error_result(rule_id, "workflow timed out (300s)")
+    except FileNotFoundError:
+        return _error_result(rule_id, "`python` not found on PATH")
+
+    raw_stdout = (proc.stdout or "").strip()
+    raw_data = _parse_last_json_line(raw_stdout)
+
+    extracted_value = _extract_value(raw_data)
+    method = (raw_data or {}).get("extraction_method") or "llm"
+    source_text = (raw_data or {}).get("raw_text") or ""
+
+    conf = kc_conf.score(
+        rule_id=rule_id,
+        extracted_value=str(extracted_value),
+        source_text=source_text,
+        method=method,
+        document=str(input_path),
+        historical=historical,
+        corner_cases=corner_cases,
+    )
+
+    return {
+        "rule_id": rule_id,
+        "value": extracted_value,
+        "confidence": conf,
+        "confidence_band": kc_conf.band(conf),
+        "extraction_method": method,
+        "exit_code": proc.returncode,
+        "raw": raw_data if raw_data is not None else {"stderr": (proc.stderr or "")[:2000]},
+    }
+
+
+def _error_result(rule_id, msg):
+    return {
+        "rule_id": rule_id,
+        "value": None,
+        "confidence": 0.0,
+        "confidence_band": "low",
+        "extraction_method": "fallback",
+        "exit_code": 2,
+        "raw": {"error": msg},
+    }
+
+
+def _parse_last_json_line(text):
+    if not text:
+        return None
+    # Walk lines from the bottom, return the first that parses as a JSON object
+    for line in reversed(text.split("\n")):
+        line = line.strip()
+        if not line:
+            continue
+        if line[0] not in "{[":
+            continue
+        try:
+            return json.loads(line)
+        except json.JSONDecodeError:
+            continue
+    return None
+
+
+def _extract_value(raw):
+    if not isinstance(raw, dict):
+        return None
+    for k in ("extracted_value", "value", "result"):
+        if k in raw:
+            return raw[k]
+    return None
+
+
+def _load_json(path, *, required):
+    if not path.is_file():
+        if required:
+            _die(f"Required file missing: {path.name}")
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        _die(f"Invalid JSON in {path.name}: {e}")
+
+
+def _load_calibration(path):
+    data = _load_json(path, required=False)
+    if not data:
+        return {}
+    return data.get("historical_accuracy") or data or {}
+
+
+def _check_env():
+    missing = []
+    for k in ("LLM_API_KEY",):
+        if not os.environ.get(k):
+            missing.append(k)
+    tiers = [t for t in ("TIER1", "TIER2", "TIER3", "TIER4") if os.environ.get(t)]
+    if not tiers:
+        missing.append("at least one of TIER1..TIER4")
+    if missing:
+        print("Missing env vars: " + ", ".join(missing), file=sys.stderr)
+        print("Workflows in this release call worker LLMs and need these set.", file=sys.stderr)
+        return False
+    return True
+
+
+def _die(msg):
+    print(f"error: {msg}", file=sys.stderr)
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

package/template/release-runtime/serve.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Serve this release directory locally so dashboards open in a browser.
+# Generated HTML files (e.g. result_*.html, dashboard.html) become reachable
+# at http://localhost:<port>/...
+#
+# Usage:
+#   ./serve.sh           # default port 8080
+#   ./serve.sh 9000      # custom port
+#
+# Stop with Ctrl-C.
+
+PORT="${1:-8080}"
+cd "$(dirname "$0")" || exit 1
+echo "Serving $(pwd) on http://localhost:${PORT}/"
+exec python -m http.server "$PORT"

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

@@ -49,6 +49,12 @@ Many real verification tasks require semantic understanding — "is this descrip
 
 If a method's results fall below the accuracy threshold, try a different method or a more capable model. If regex works and meets accuracy — keep it, it's free. If regex produces results below threshold, escalate to worker LLM. If a cheap worker LLM isn't accurate enough, try a more capable tier. Record what works for each extraction type in AGENT.md for future reference.
 
+## Project Glossary
+
+The project glossary (built and maintained by `rule-extraction`, stored at `rules/glossary.json`) is a useful resource when designing extraction. It records canonical names and known aliases for entities that appear across rules. Reading it before extracting helps keep entity names schema-aligned and avoids parallel labels for the same thing.
+
+Whether the glossary becomes more than a naming convention — for instance, driving cheap pattern matching for entities with stable surface forms — is a per-project judgment. Apply the same cost-accuracy logic as elsewhere: whatever method meets the accuracy threshold for the task at hand.
+
 ## Schema Design
 
 Define the expected output for each extraction. Keep it simple and JIT:

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

@@ -61,6 +61,17 @@ After the conversation:
 5. Initialize version tracking (a `versions.json` manifest).
 6. Log the bootstrap conversation summary for future reference.
 
+## Scheduled Ingestion (Production)
+
+Once a project is past bootstrap and into production, fresh documents often arrive on a regular cadence — daily regulator drops, hourly API pulls, batch uploads from upstream systems. Use the `schedule_fetch` tool to register ingestion jobs the OS scheduler runs while kc-beta is closed:
+
+- Each job is a shell command (rsync, curl, custom script) that lands files in `$INPUT_DIR`.
+- KC writes a wrapper script under `scripts/ingest/<job-id>.sh`; the user installs the script line into their crontab via `crontab -e`.
+- Newly-arrived files are auto-prefixed with `<job-id>_<UTC-timestamp>_` so origin and arrival time are visible in the filename.
+- View status with `/schedule` or `schedule_fetch list`. Tail of `logs/ingest.log` shows recent runs.
+
+Discuss the cadence with the developer user during bootstrap — knowing the production input rhythm shapes how skills and workflows should be written (batch vs streaming, idempotency requirements, etc.).
+
 ## When to Re-Bootstrap
 
 Return to this skill when:

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

@@ -106,7 +106,19 @@ For production Input/ documents:
 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.
+7. Move processed input docs to `input/archived/` via `archive_file` so the next session sees only fresh arrivals.
+8. If accuracy is acceptable, finalize the batch. If not, trigger evolution loop.
+
+Production input often arrives on a schedule (see `bootstrap-workspace` → "Scheduled Ingestion"). Files in `input/` are auto-prefixed with `<job-id>_<UTC-timestamp>_` by the ingestion wrapper, so each batch carries provenance in its filenames. When a batch fails QC, the prefixes let you trace which scheduled run produced the bad data.
+
+## Two Dashboard Surfaces
+
+There are two distinct dashboards in this system:
+
+- **Developer dashboard** — `dashboard_render` tool, generated inside the workspace from `output/results/`, `logs/evolution/`, and `output/qc/`. For your audit and the developer user's day-to-day monitoring during BUILD and DISTILL.
+- **End-user dashboard** — the `render_dashboard.py` script bundled inside a release (built via the `release` tool). For non-developer recipients of a packaged release. It renders results from a single `run.py` invocation; no workspace dependency.
+
+When a release is built, point end users at the bundled dashboard, not the workspace one. Workspace dashboard stays your developer surface.
 
 ## Developer User Involvement
 

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

@@ -104,6 +104,41 @@ Maintain a lightweight catalog of all extracted rules. This is your index, not t
 
 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.
 
+## Project Glossary
+
+Alongside the rule catalog, build a project glossary — a living vocabulary of the entities, terms, and patterns the verification system encounters. The glossary is what keeps entity names consistent across rules: without it, the same balance-sheet item might be named "注册资本", "registered capital", and "paid-in capital" by three different rule skills, breaking shared-entity matching and producing inconsistent extraction outputs.
+
+The glossary is not frozen at the end of extraction. It is a living document. Update it when you discover new aliases in samples, when a worker LLM extraction reveals a variant phrasing, when corner cases surface unfamiliar terminology. Both the coding agent and any operator can edit it.
+
+### When to seed it
+
+During rule extraction. As you decompose each rule, note the entities the rule references — capital ratios, signature pages, related-party transactions, dates, parties, monetary values. Seed the glossary with the canonical name and any aliases already visible in the source documents.
+
+### Storage and shape
+
+Save as `rules/glossary.json` next to `catalog.json`. Each entry is small:
+
+```json
+{
+  "canonical": "registered_capital",
+  "aliases": ["注册资本", "registered capital", "实收资本"],
+  "definition": "The capital amount registered with regulators",
+  "entity_type": "monetary_value",
+  "seen_in": ["rules/regulation_A.pdf:p12", "samples/annual_report_2024.pdf:p3"],
+  "status": "extracted"
+}
+```
+
+Status field tracks maturity: `extracted` (from rules), `validated` (confirmed in samples), `production` (used by deployed workflows). Add or drop fields as the project demands — same JIT philosophy as the rule schema.
+
+### How it integrates
+
+- `rule-graph` consumes the glossary so `shares_entity` edges reference canonical labels rather than free-text strings.
+- `entity-extraction` references the glossary for canonical names and known aliases when designing extraction logic.
+- Skills authored under `skill-authoring` should use canonical names in their schemas.
+
+How the glossary is used downstream is a per-project judgment. A mature glossary may enable cheap pattern-based matching for some entities; for others it just keeps naming consistent. Let the cost-accuracy logic in `entity-extraction` decide per case.
+
 ## Handling Ambiguity
 
 Regulations are often ambiguous. When you encounter ambiguity:

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

@@ -43,6 +43,22 @@ Two rules that can produce contradictory guidance. Regulation A requires disclos
 
 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.
 
+## Project Glossary
+
+The glossary (built and owned by `rule-extraction`, stored at `rules/glossary.json`) is the canonical-label registry that makes `shares_entity` edges meaningful. Without it, two rules can target the same entity under different names and the edge between them never gets drawn.
+
+Edges that reference entities should use the glossary's canonical labels, not free-text strings copied from rule descriptions:
+
+```json
+{"from": "R001", "to": "R004", "type": "shares_entity", "entity": "registered_capital"}
+```
+
+Where `registered_capital` is the canonical name in `glossary.json`, with aliases like `注册资本` and `paid-in capital` recorded under it.
+
+When the glossary is updated — new aliases discovered in samples, two entries merged, a definition refined — revisit affected `shares_entity` edges. New aliases may surface previously hidden cross-rule connections; merged entries collapse parallel edges into one.
+
+The glossary is built and owned by rule-extraction; rule-graph just consumes it.
+
 ## Three Uses
 
 ### 1. Impact Analysis

package/template/skills/en/meta-meta/skill-to-workflow/SKILL.md

@@ -135,6 +135,14 @@ The coding agent's skill-based results are the ground truth. For each document i
 
 Each iteration of a workflow is a new version file: `workflow_v1.py`, `workflow_v2.py`, etc. Track which version is active in `config.json`. See `version-control` skill for the full methodology.
 
+## Releasing Workflows
+
+Once workflows hit accuracy threshold, they can be packaged for end users via the `release` tool. Each release is a self-contained directory under `output/releases/<slug>/` with the pinned workflows, a Python runner, a confidence scorer, an HTML dashboard generator, and a `serve.sh` helper. The bundle has no kc-beta dependency — anyone with Python and a worker LLM API key can run `python run.py <doc>` and produce verification results.
+
+What to include is your call: all rules in catalog, or a curated subset via the `include` parameter; bundling 1-3 representative samples as `fixtures/` if you want the recipient to be able to dry-run without their own data.
+
+The `release` tool snapshots the workspace first (git tag `snap/release-<slug>`), so the bundle is regenerable from git even if `output/releases/` is later cleaned. Decide when to release — there's no automation, no forced cadence. Typical triggers: workflows reach SKILL/WORKFLOW_ACCURACY thresholds, a stakeholder needs a hand-off, a production cron should run pinned versions instead of latest. Discuss with the developer user.
+
 ## Cost Tracking
 
 Track the cost of each workflow run:

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

@@ -96,6 +96,19 @@ Tags enable three capabilities that you cannot afford to lose:
 
 Tag format: a simple string field on every intermediate output. Example values: `regex`, `python_calc`, `llm_tier2`, `manual_review`. Be consistent within a project. Define the tag vocabulary once at project setup and enforce it across all skills and workflows.
 
+## Multi-agent coordination — keep it lock-free
+
+When a task is large enough that you reach for `agent_tool` to spawn parallel sub-agents, partition by an independent unit (one rule per sub-agent, one document per sub-agent, etc.) so the sub-agents never need to coordinate through a shared mutable file.
+
+Lesson from a peer-team failure: they tried equal-status agents claiming work via a shared coordination file with locks. Two predictable failures emerged. (1) Agents held locks too long or forgot to release them; even with locks working, twenty agents' throughput dropped to that of two or three because most time went to waiting. (2) Fragility — agents could fail while holding a lock, try to acquire a lock they already held, or update the coordination file without acquiring a lock at all.
+
+KC's preferred patterns:
+
+- **Single-dispatcher** — `TaskManager` hands tasks out one at a time to the conductor. No locks, no peer coordination. This is the default ralph-loop architecture.
+- **Partition-by-unit** — when spawning sub-agents via `agent_tool`, give each one a non-overlapping slice (per-rule, per-document). Sub-agents write to their own `sub_agents/<taskId>/` for state, and to per-rule paths in `rule_skills/<id>/` or `workflows/<id>/` for shared artifacts. Block 11's git auto-commit serializes the shared writes; partition-by-rule keeps last-writer-wins from being a problem.
+
+If two would-be sub-agents need to talk to each other to make progress, they should probably be one task (run sequentially) or a sequence (parent dispatches second after first finishes), not concurrent peers.
+
 ## Anti-Patterns
 
 Five failure modes recur across projects. Learn to recognize them early.