kc-beta 0.3.1 → 0.5.3

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/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/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/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/zh/meta-meta/rule-graph/SKILL.md

@@ -87,6 +87,22 @@ description: Build and maintain a graph of relationships between verification ru
 
 图谱关联这些规则到共享的角落案例，一处修复、多处感知。
 
+## 项目术语表（Glossary）
+
+术语表由 `rule-extraction` 构建并维护，存放于 `rules/glossary.json`。它是规范化标签的注册中心——`shares_entity`（共享实体）边能否成立，全靠它。没有术语表，两条规则可能针对同一个实体却用不同名字，它们之间的边就永远画不出来。
+
+涉及实体的边应该引用术语表中的规范化标签，而不是从规则描述中复制粘贴的自由文本：
+
+```json
+{"from": "R001", "to": "R004", "type": "shares_entity", "entity": "registered_capital"}
+```
+
+其中 `registered_capital` 是 `glossary.json` 里的规范化名称，`注册资本`、`paid-in capital`、`实收资本` 作为别名记录在该条目下。
+
+术语表更新时——发现新别名、合并两条目、修订定义——回过头检查受影响的 `shares_entity` 边。新别名可能让原本隐藏的跨规则关联浮现；合并的条目会把平行的边收敛为一条。
+
+术语表由 rule-extraction 构建和持有，rule-graph 只是消费方。
+
 ## 四个用途
 
 ### 1. 影响分析（Impact Analysis）

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:

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

@@ -168,6 +168,22 @@ description: Decompose each verification rule into independent sub-tasks and ass
 | `template` | 模板填充（批注生成等） |
 | `manual_review` | 人工审核 |
 
+## 多智能体协同 —— 不要用锁
+
+如果一个任务大到你打算用 `agent_tool` 起多个子智能体并行做，按独立单元分片（一个规则一个子智能体、一份文档一个子智能体），让子智能体之间不需要通过共享可变文件来协同。
+
+来自一个友邻团队的失败教训：他们让所有子智能体平等，通过共享协同文件领任务，并加锁防抢占。两类失败必然出现：
+
+1. 锁被持有太久，或者干脆忘了释放。即便锁机制工作，二十个智能体的吞吐会下降到只有两三个的水平 —— 大部分时间都在等。
+2. 系统脆弱：智能体可能在持有锁时崩溃，或重复获取自己已经持有的锁，或干脆不获取锁就更新协同文件。
+
+KC 偏好的两种模式：
+
+- **单调度器** —— `TaskManager` 一次发一个任务给主 conductor。无锁，无 peer 协同。这是 ralph-loop 的默认架构。
+- **按单元分片** —— 用 `agent_tool` 起子智能体时，每个子智能体只负责一个不重叠的切片（一规则、一文档）。子智能体的状态写到自己的 `sub_agents/<taskId>/` 下，共享产物（`rule_skills/<id>/`、`workflows/<id>/`）按规则路径分开。Block 11 的 git 自动提交把共享路径的写入序列化，按规则分片让"后写覆盖前写"不再是问题。
+
+如果两个本应并行的子智能体非要相互通信才能推进，那它们其实应该是一个任务（顺序跑）或一条流水线（父智能体发完 A 再发 B），而不是平行的 peer。
+
 ## 反模式
 
 ### LLM 万能论

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

@@ -5,6 +5,19 @@ description: Manage versioning of skills, workflows, prompts, and system configu
 
 # 版本控制与制品溯源
 
+## Git 即唯一真相源
+
+工作区是一个 git 仓库。每次对受跟踪路径（skills、workflows、rules、glossary、AGENT.md、tasks.json）的写入，都由 KC 自动提交，提交信息中带有 trace ID。这意味着：
+
+- `git log --oneline` 就是本次 session 中所有有意义变更的时间线。
+- `git diff HEAD~3 -- rule_skills/R001/` 显示某个技能在最近三次有意义写入间的变化。
+- `git checkout HEAD~5 -- workflows/R001/` 回滚一个工作流，不影响其他任何东西。
+- `snapshot` 工具用来标记值得记住的时刻（发版、"高风险操作前"），用 `git checkout snap/<label>` 恢复。
+
+通过 `sandbox_exec` 加 `cwd: "workspace"` 直接跑 git 命令。不要绕开 git —— 它就是审计链路本身。
+
+下文中按版本号复制文件名（`workflow_v1.py`、`workflow_v3.py`）和 CHANGELOG.md 的约定依然有用，但作用是 *在单个技能文件夹内提升人类可读性* —— 让智能体直接对比，不必每次都去翻 git 历史。系统的真相记录在 git，不在已废弃的 `versions.json` manifest（新工作区不再写入这个文件）。
+
 ## 设计目标
 
 这套版本控制机制不是为了多人协作——在这个系统中，编程智能体是唯一的执行者。版本控制的目的是：

package/template/workspace.gitignore

@@ -0,0 +1,22 @@
+# Auto-installed by KC at session start. Do not commit secrets, runtime
+# noise, or user source documents — git tracks KC's outputs only.
+
+# Secrets
+.env
+
+# Runtime / session noise
+logs/
+sub_agents/
+session-state.json
+.DS_Store
+*.log
+
+# User-provided source documents (read in place, not tracked)
+samples/
+
+# High-volume IO
+input/
+output/
+
+# Deprecated metadata manifest (old workspaces only — replaced by git)
+versions.json