kc-beta 0.3.2 → 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-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/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.

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

@@ -7,6 +7,19 @@ description: Manage versioning of skills, workflows, prompts, and system configu
 
 Version control here is about auditability and rollback, not collaboration. You need to know what changed, when, why, and be able to undo it if the change made things worse.
 
+## Git Is the Source of Truth
+
+The workspace is a git repository. Every workspace write to a tracked path (skills, workflows, rules, glossary, AGENT.md, tasks.json) is auto-committed by KC with a trace ID in the commit message. This means:
+
+- `git log --oneline` is the timeline of every meaningful change in this session.
+- `git diff HEAD~3 -- rule_skills/R001/` shows what changed in a skill across the last three meaningful writes.
+- `git checkout HEAD~5 -- workflows/R001/` rolls back a workflow without touching anything else.
+- The `snapshot` tool tags moments worth remembering (releases, "before risky operation"); restore with `git checkout snap/<label>`.
+
+Use `sandbox_exec` with `cwd: "workspace"` to run git commands directly. Don't fight git — it's the audit trail.
+
+The conventions below (per-version filename copies, `CHANGELOG.md`) are still useful for *human readability inside a single skill folder* — having `workflow_v1.py` and `workflow_v3.py` side-by-side lets the agent compare them without reading git history. But the system of record is git, not the deprecated `versions.json` manifest (which is no longer written for new workspaces).
+
 ## What to Version
 
 Everything that affects verification results:

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

@@ -122,6 +122,17 @@ versions.json           # 版本清单（工作空间根目录）
 }
 ```
 
+## 生产环境的定时摄取
+
+项目进入生产后，新文档通常会按固定节奏到达 —— 监管机构每日发布、API 每小时拉取、上游系统批量上传。用 `schedule_fetch` 工具注册摄取任务，让 OS 调度器在 kc-beta 关闭时也能跑：
+
+- 每个任务是一条 shell 命令（rsync、curl、自定义脚本），把文件落到 `$INPUT_DIR`。
+- KC 在 `scripts/ingest/<job-id>.sh` 下生成一个 wrapper 脚本；用户通过 `crontab -e` 把这一行装进自己的 crontab。
+- 新到达的文件会自动前缀成 `<job-id>_<UTC-时间戳>_`，文件名本身就告诉你来源和到达时间。
+- 用 `/schedule` 或 `schedule_fetch list` 查看状态；`logs/ingest.log` 末尾几行展示最近的运行情况。
+
+在初始化阶段就和开发者用户讨论这个节奏 —— 生产侧文档输入节奏直接决定 skill 和工作流的写法（批处理 vs 流式、幂等性要求等等）。
+
 ## 何时需要重新初始化
 
 以下情况需要重新运行本技能：

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

@@ -167,8 +167,11 @@ IF 当前批次准确率 < WORKFLOW_ACCURACY:
 5. 汇总评审结果
 6. 判断是否需要触发演化循环
 7. 生成质控报告
+8. 处理完的输入文档通过 `archive_file` 移到 `input/archived/`，下次 session 只看到新到达的批次
 ```
 
+生产环境的输入通常按节奏到达（见 `bootstrap-workspace` 的"生产环境的定时摄取"一节）。`input/` 中的文件由摄取 wrapper 自动加上 `<job-id>_<UTC-时间戳>_` 前缀，每个批次的文件名本身就带有溯源信息。批次质控不通过时，前缀能帮你定位是哪一次定时拉取出了问题。
+
 ### 输出结构
 
 ```
@@ -235,6 +238,15 @@ logs/qc/
 }
 ```
 
+## 两类仪表盘
+
+系统中有两个独立的仪表盘：
+
+- **开发者仪表盘** —— `dashboard_render` 工具，在工作区内基于 `output/results/`、`logs/evolution/`、`output/qc/` 生成。用于你自己审计、以及开发者用户在 BUILD/DISTILL 阶段的日常监控。
+- **终端用户仪表盘** —— release 包内自带的 `render_dashboard.py` 脚本（由 `release` 工具产出）。面向非开发者收件人，从一次 `run.py` 调用的结果渲染，与工作区无关。
+
+发布 release 后，把终端用户引导到 release 包内的仪表盘，不是工作区的那个。工作区仪表盘是你自己的开发者视图。
+
 ## 开发者用户参与
 
 质量监控不应该让开发者用户去读 JSON 文件。通过仪表盘技能生成可视化报告，开发者用户只需要关注：

package/template/skills/zh/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: