kc-beta 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kc-beta",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "KC Agent — LLM document verification agent (pure Node.js CLI)",
   "type": "module",
   "bin": {

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/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/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/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）