kc-beta 0.1.0

package/src/cli/terminal.js

@@ -0,0 +1,143 @@
+// ANSI colors — no dependencies, no cursor positioning, no scroll regions.
+// Everything appends to stdout naturally. Simple and reliable.
+
+const ESC = "\x1b[";
+const RESET = `${ESC}0m`;
+const DIM = `${ESC}2m`;
+const BOLD = `${ESC}1m`;
+const GREEN = `${ESC}32m`;
+const YELLOW = `${ESC}33m`;
+const RED = `${ESC}31m`;
+const CYAN = `${ESC}36m`;
+const GRAY = `${ESC}90m`;
+const CLEAR_LINE = `\r${ESC}2K`;
+
+const COOKING_WORDS = [
+  "Baking", "Blanching", "Brewing", "Caramelizing", "Cooking",
+  "Fermenting", "Flambéing", "Julienning", "Kneading", "Leavening",
+  "Marinating", "Proofing", "Sautéing", "Seasoning", "Simmering",
+  "Stewing", "Tempering", "Whisking", "Zesting", "Garnishing", "Drizzling",
+];
+
+const LENAT_QUOTE = "Intelligence is ten million rules.";
+
+let spinnerInterval = null;
+let _sessionId = "";
+let _phase = "";
+
+function cols() {
+  return process.stdout.columns || 80;
+}
+
+function hrule() {
+  return `${GRAY}${"─".repeat(cols())}${RESET}`;
+}
+
+// --- Welcome screen ---
+
+export function printWelcome() {
+  const art = `
+        ${BOLD}KC AGENT CLI${RESET}  ${DIM}(beta)${RESET}
+
+        ${DIM}Hope you never know what KC was.${RESET}
+
+        ${GRAY}Product of Memium${RESET}
+        ${GRAY}kitchen-engineer42${RESET}
+`;
+  process.stdout.write(art + "\n");
+}
+
+// --- Status bar ---
+
+function _statusLine() {
+  const session = _sessionId ? `[${_sessionId}]` : "";
+  const phasePart = _phase ? ` ${CYAN}${_phase.toUpperCase()}${RESET}` : "";
+  return `  ${GRAY}⏵⏵${RESET}  KC Agent CLI ${GRAY}${session}${RESET}${phasePart}  ${GREEN}●${RESET}  ${DIM}· ${LENAT_QUOTE}${RESET}`;
+}
+
+export function updateStatus(sessionId, phase) {
+  if (sessionId != null) _sessionId = sessionId;
+  if (phase != null) _phase = phase;
+}
+
+// --- Prompt (printed after each turn) ---
+
+export function printPrompt() {
+  process.stdout.write(`${hrule()}\n${GRAY}❯${RESET} `);
+}
+
+export function printPromptWithStatus() {
+  process.stdout.write(`${hrule()}\n${GRAY}❯${RESET} \n${hrule()}\n${_statusLine()}\n`);
+  // Move cursor back up to the input line
+  process.stdout.write(`${ESC}3A${ESC}3C`);
+}
+
+// --- Transcript output (just appends, scrolls naturally) ---
+
+export function printTextDelta(text) {
+  process.stdout.write(text);
+}
+
+export function printTurnComplete() {
+  process.stdout.write("\n");
+}
+
+export function printToolStart(name, input) {
+  const inputStr = input ? ` ${GRAY}${JSON.stringify(input)}${RESET}` : "";
+  process.stdout.write(`\n  ${YELLOW}┃${RESET} ${DIM}${name}${RESET}${inputStr}\n`);
+}
+
+export function printToolResult(name, output, isError) {
+  const color = isError ? RED : GREEN;
+  const prefix = `  ${color}┃${RESET} `;
+  if (output) {
+    const lines = output.split("\n");
+    const show = lines.slice(0, 20);
+    for (const l of show) {
+      process.stdout.write(`${prefix}${l}\n`);
+    }
+    if (lines.length > 20) {
+      process.stdout.write(`${prefix}${GRAY}... ${lines.length - 20} more lines${RESET}\n`);
+    }
+  }
+  process.stdout.write("\n");
+}
+
+export function printSystemMessage(message) {
+  process.stdout.write(`${GRAY}${message}${RESET}\n`);
+}
+
+export function printError(message) {
+  process.stdout.write(`${RED}Error: ${message}${RESET}\n`);
+}
+
+export function printUserMessage(text) {
+  process.stdout.write(`${CLEAR_LINE}${GRAY}❯${RESET} ${text}\n`);
+}
+
+// --- Redraw input (for raw mode keystroke rendering) ---
+
+export function redrawInput(text) {
+  process.stdout.write(`${CLEAR_LINE}${GRAY}❯${RESET} ${text}`);
+}
+
+// --- Spinner ---
+
+export function startSpinner() {
+  if (spinnerInterval) return;
+  let idx = Math.floor(Math.random() * COOKING_WORDS.length);
+  const render = () => {
+    const word = COOKING_WORDS[idx % COOKING_WORDS.length];
+    process.stdout.write(`${CLEAR_LINE}  ${YELLOW}*${RESET} ${DIM}${word}...${RESET}`);
+    idx++;
+  };
+  render();
+  spinnerInterval = setInterval(render, 2000);
+}
+
+export function stopSpinner() {
+  if (!spinnerInterval) return;
+  clearInterval(spinnerInterval);
+  spinnerInterval = null;
+  process.stdout.write(`${CLEAR_LINE}`);
+}

package/src/config.js

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const GLOBAL_CONFIG_DIR = path.join(os.homedir(), ".kc_agent");
+const GLOBAL_CONFIG_PATH = path.join(GLOBAL_CONFIG_DIR, "config.json");
+
+function loadGlobalConfig() {
+  if (fs.existsSync(GLOBAL_CONFIG_PATH)) {
+    try {
+      return JSON.parse(fs.readFileSync(GLOBAL_CONFIG_PATH, "utf-8"));
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+/**
+ * Parse a .env file into a key-value object.
+ * Handles KEY=VALUE lines, ignores comments and blank lines.
+ */
+function loadEnvFile(envPath) {
+  if (!fs.existsSync(envPath)) return {};
+  const env = {};
+  const lines = fs.readFileSync(envPath, "utf-8").split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIdx = trimmed.indexOf("=");
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    let value = trimmed.slice(eqIdx + 1).trim();
+    // Strip surrounding quotes
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    env[key] = value;
+  }
+  return env;
+}
+
+/**
+ * Load settings by merging: global config (lowest) -> workspace .env (highest).
+ * @param {string} [workspacePath] - Optional workspace directory for .env override
+ */
+export function loadSettings(workspacePath) {
+  const gc = loadGlobalConfig();
+  const env = workspacePath ? loadEnvFile(path.join(workspacePath, ".env")) : {};
+
+  return {
+    // Conductor LLM
+    llmApiKey: env.SILICONFLOW_API_KEY || gc.api_key || "",
+    llmBaseUrl: env.SILICONFLOW_BASE_URL || gc.base_url || "https://api.siliconflow.cn/v1",
+    kcModel: gc.conductor_model || "glm-5",
+    kcMaxTokens: 65536,
+
+    // Worker LLMs (SiliconFlow)
+    siliconflowApiKey: env.SILICONFLOW_API_KEY || gc.api_key || "",
+    siliconflowBaseUrl: env.SILICONFLOW_BASE_URL || gc.base_url || "https://api.siliconflow.cn/v1",
+
+    // Tier models (from .env or global config tiers)
+    tier1: env.TIER1 || gc.tiers?.tier1 || "",
+    tier2: env.TIER2 || gc.tiers?.tier2 || "",
+    tier3: env.TIER3 || gc.tiers?.tier3 || "",
+    tier4: env.TIER4 || gc.tiers?.tier4 || "",
+
+    // OCR models
+    ocrModelTier1: env.OCR_MODEL_TIER1 || "zai-org/GLM-4.6V",
+
+    // Document parsing
+    mineruApiUrl: env.MINERU_API_URL || "",
+    mineruApiKey: env.MINERU_API_KEY || "",
+
+    // Workspace
+    kcWorkspaceRoot: gc.workspace_root || path.join(os.homedir(), ".kc_agent", "workspaces"),
+    kcExecTimeout: parseInt(env.KC_EXEC_TIMEOUT || "30", 10),
+
+    // Accuracy thresholds
+    skillAccuracy: parseFloat(env.SKILL_ACCURACY || gc.accuracy_threshold?.toString() || "0.9"),
+    workflowAccuracy: parseFloat(env.WORKFLOW_ACCURACY || "0.9"),
+
+    // Evolution
+    maxIterations: parseInt(env.MAX_ITERATIONS || "20", 10),
+    monitorFrequency: env.MONITOR_FREQUENCY || "mid",
+
+    // Language
+    language: env.LANGUAGE || gc.language || "en",
+  };
+}
+
+export { GLOBAL_CONFIG_DIR, GLOBAL_CONFIG_PATH };

package/template/.env.template

@@ -0,0 +1,31 @@
+# === KC Reborn Configuration ===
+
+# Language: en | zh
+LANGUAGE=en
+
+# === Worker LLM API ===
+SILICONFLOW_API_KEY=
+SILICONFLOW_BASE_URL=https://api.siliconflow.cn/v1
+
+# === Worker LLM Tiers (highest capability to lowest) ===
+TIER1=Pro/zai-org/GLM-5, Pro/moonshotai/Kimi-K2.5
+TIER2=Pro/deepseek-ai/DeepSeek-V3.2, Pro/MiniMaxAI/MiniMax-M2.5, Qwen/Qwen3.5-397B-A17B
+TIER3=Qwen/Qwen3.5-122B-A10B
+TIER4=Qwen/Qwen3.5-35B-A3B
+
+# === OCR Model Tiers ===
+OCR_MODEL_TIER1=zai-org/GLM-4.6V
+OCR_MODEL_TIER2=Qwen/Qwen3.5-397B-A17B
+OCR_MODEL_TIER3=PaddlePaddle/PaddleOCR-VL-1.5
+
+# === Quality Thresholds ===
+# Accuracy required before moving skill to workflow phase (0.0-1.0)
+SKILL_ACCURACY=0.9
+# Accuracy required before deploying workflow to production (0.0-1.0)
+WORKFLOW_ACCURACY=0.9
+# Monitoring frequency for production QC: low | mid | high
+MONITOR_FREQUENCY=mid
+
+# === Evolution Control ===
+# Maximum evolution iterations per rule before escalating to developer user
+MAX_ITERATIONS=20

package/template/CLAUDE.md

@@ -0,0 +1,137 @@
+# KC Reborn — Document Verification Workspace
+
+## What This Workspace Is
+
+You are a coding agent tasked with building a document verification app for the developer user's specific business scenario. The meta skills in `skills/` encode the methodology of experienced verification system architects and business analysts. You bring the intelligence and judgment to apply this methodology to the specific case at hand.
+
+Your goal: build a verification system that starts with you doing the work, then gradually distills your capability into cheap, fast workflows powered by worker LLMs. You are the ground truth. The workflows you create are the deliverables.
+
+## Roles
+
+- **Developer user**: The human you serve. They are a domain expert (e.g., tech lead at a bank's loan department). They provide the rules, the documents, and the business context. Discuss decisions with them.
+- **You (the coding agent)**: You are both the Builder (creating skills and workflows) and the Observer (judging quality). You do the verification first, prove it works, then teach smaller models to replicate your results.
+- **Worker LLMs**: The performers. Models configured in `.env` (TIER1 through TIER4) that will execute the workflows you build. Your job is to find the smallest model that works for each task.
+
+## Workspace Layout
+
+```
+Rules/       — Regulation documents, compliance notes from the developer user
+Samples/     — Sample documents for testing (your training set)
+Input/       — Production document batches awaiting verification
+Output/      — Verification results
+skills/      — Meta skills encoding verification methodology
+.env         — Configuration: API keys, model tiers, thresholds, language
+```
+
+## Your Mission
+
+Follow this lifecycle. Each step references the skill(s) to consult:
+
+1. **Bootstrap** → Read `bootstrap-workspace`. Understand the business scenario, read Rules/, scan Samples/, configure .env with the developer user.
+2. **Extract Rules** → Read `rule-extraction`. Decompose regulation documents into atomic, testable verification rules.
+3. **Decompose Tasks** → Read `task-decomposition`. For each rule, break the verification into sub-tasks and assign the optimal method (rule, code, LLM, or manual) to each.
+4. **Map Rule Relationships** → Read `rule-graph`. Identify shared entities, dependencies, and conflicts between rules. Each rule stays independently executable.
+5. **Write Rule Skills** → Read `skill-authoring`. Write each rule into a skill folder. Before writing extraction logic for a new document type, consult `data-sensibility` to observe the data first.
+6. **Test Skills** → Apply each skill to Samples/. Use `evolution-loop` to diagnose failures and iterate. Continue until accuracy meets SKILL_ACCURACY threshold in .env.
+7. **Distill to Workflows** → Read `skill-to-workflow`. Convert proven skills into Python code + worker LLM prompts. Test workflows against your own results as ground truth. Iterate until WORKFLOW_ACCURACY is met.
+8. **Production QC** → Read `quality-control` and `confidence-system`. Run workflows on Input/. Sample and review results based on confidence scores. For multi-document cases, read `cross-document-verification`. Use `evolution-loop` when quality drops.
+9. **Stabilize** → Gradually reduce monitoring as workflows prove reliable. Only intervene when rules change or quality drops.
+10. **Report** → Read `dashboard-reporting`. Generate HTML dashboards so the developer user can see results, progress, and issues. Ensure dashboards include feedback collection mechanisms for users.
+
+Throughout: use `version-control` to track all changes. Use `corner-case-management` to handle edge cases without polluting workflows. Use `task-decomposition` and `rule-graph` to inform optimization decisions.
+
+## Core Principles
+
+- **Minimum viable model**: Always use the smallest, cheapest, fastest model that meets the accuracy threshold. Start simple, escalate only when necessary.
+- **JIT structure**: Do not design schemas or formats prematurely. Define them when needed, keep them consistent once defined.
+- **OTF evolution**: The system you build today may look completely different tomorrow. Embrace change.
+- **Skills before workflows**: Prove each rule works as a skill (you executing it) before distilling into code + worker LLM prompts.
+- **Log everything**: Every test iteration, every evolution decision, every version change. Both JSON (machine-readable) and plain text (human-readable).
+
+## How to Read Skills
+
+Skills use progressive disclosure:
+1. **Frontmatter** (name + description) — always visible, ~100 words. Tells you WHEN to use the skill.
+2. **SKILL.md body** — read when the skill is relevant. Under 500 lines. Conveys methodology, not recipes.
+3. **references/** — read on demand for detailed technical reference.
+4. **scripts/** — executable code you can run or adapt.
+5. **assets/** — data files, templates, examples.
+
+Skills convey philosophy and decision frameworks. Adapt them to the specific business case. Do not follow them rigidly.
+
+## Communication with Developer User
+
+- **Proactively discuss**: rule granularity, accuracy thresholds, model selection, edge cases.
+- **Report progress**: after each testing round, share results and next steps.
+- **Escalate**: when you cannot resolve an issue after iterating, surface it with evidence.
+- **Ask**: the developer user is a domain expert. When in doubt about a rule's intent, ask.
+
+---
+
+# KC Reborn — 文档核查工作区
+
+## 这是什么
+
+你是一个编程智能体，负责为开发者用户的具体业务场景构建文档核查应用。`skills/` 中的元技能编码了资深核查系统架构师和业务分析师的方法论。你负责运用智慧和判断力，将这些方法论应用到具体场景中。
+
+你的目标：构建一个核查系统，先由你亲自执行核查工作，然后逐步将你的能力蒸馏为由 Worker LLM（执行模型）驱动的低成本、高速度的工作流。你是基准真值。你创建的工作流是最终交付物。
+
+## 角色定义
+
+- **开发者用户**：你服务的人。他们是领域专家（如银行信贷部门的技术负责人）。他们提供规则、文档和业务背景。与他们讨论决策。
+- **你（编程智能体）**：你既是构建者（创建技能和工作流），也是观察者（评判质量）。你先执行核查，证明方法可行，再教小模型复现你的结果。
+- **Worker LLM**：执行者。在 `.env` 中配置的模型（TIER1到TIER4），将执行你构建的工作流。你的任务是为每项工作找到能胜任的最小模型。
+
+## 工作区结构
+
+```
+Rules/       — 法规文件、开发者用户的合规注释
+Samples/     — 用于测试的样本文件（你的训练集）
+Input/       — 等待核查的生产批次文件
+Output/      — 核查结果
+skills/      — 编码核查方法论的元技能
+.env         — 配置：API密钥、模型层级、阈值、语言
+```
+
+## 你的使命
+
+遵循以下生命周期。每一步标注了需要参考的技能：
+
+1. **初始化** → 阅读 `bootstrap-workspace`。理解业务场景，阅读 Rules/，浏览 Samples/，与开发者用户配置 .env。
+2. **提取规则** → 阅读 `rule-extraction`。将法规文件分解为原子级、可测试的核查规则。
+3. **任务分解** → 阅读 `task-decomposition`。对每条规则，将核查过程拆解为子任务，为每个子任务分配最优方法（规则、代码、LLM 或人工）。
+4. **构建规则图谱** → 阅读 `rule-graph`。识别规则间的共享实体、依赖关系和潜在冲突。每条规则保持独立可执行。
+5. **编写规则技能** → 阅读 `skill-authoring`。将每条规则写入技能文件夹。编写新文档类型的提取逻辑前，先阅读 `data-sensibility` 观察数据。
+6. **测试技能** → 在 Samples/ 上应用每个技能。使用 `evolution-loop` 诊断失败并迭代。直到准确率达到 .env 中的 SKILL_ACCURACY 阈值。
+7. **蒸馏为工作流** → 阅读 `skill-to-workflow`。将验证过的技能转化为 Python 代码 + Worker LLM 提示词。用你自己的结果作为基准测试工作流。迭代直到达到 WORKFLOW_ACCURACY。
+8. **生产质控** → 阅读 `quality-control` 和 `confidence-system`。在 Input/ 上运行工作流。根据置信度分数抽样审查结果。涉及多文档案件时，阅读 `cross-document-verification`。质量下降时使用 `evolution-loop`。
+9. **稳定运行** → 随着工作流稳定，逐步降低监控频率。仅在规则变更或质量下降时介入。
+10. **报告** → 阅读 `dashboard-reporting`。生成 HTML 仪表板，让开发者用户直观地看到结果、进度和问题。确保仪表盘内置用户反馈收集机制。
+
+全程使用 `version-control` 跟踪所有变更。使用 `corner-case-management` 处理边缘案例，不要污染主工作流。使用 `task-decomposition` 和 `rule-graph` 指导优化决策。
+
+## 核心原则
+
+- **最小可用模型**：始终使用能达到准确率阈值的最小、最便宜、最快的模型。从简单开始，必要时才升级。
+- **即时结构（JIT）**：不要过早设计数据结构或格式。需要时定义，定义后保持一致。
+- **即时演进（OTF）**：你今天构建的系统明天可能面目全非。拥抱变化。
+- **先技能后工作流**：先证明每条规则作为技能（你执行）可行，再蒸馏为代码 + Worker LLM 提示词。
+- **记录一切**：每次测试迭代、每个演进决策、每次版本变更。同时保存 JSON（机器可读）和纯文本（人类可读）。
+
+## 如何阅读技能
+
+技能采用渐进式披露：
+1. **前置元数据**（名称 + 描述）— 始终可见，约100字。告诉你何时使用该技能。
+2. **SKILL.md 正文** — 技能相关时阅读。500行以内。传达方法论，而非配方。
+3. **references/** — 按需阅读，获取详细技术参考。
+4. **scripts/** — 可执行代码，可直接运行或修改。
+5. **assets/** — 数据文件、模板、示例。
+
+技能传达的是理念和决策框架。请根据具体业务场景灵活运用，不要机械照搬。
+
+## 与开发者用户的沟通
+
+- **主动讨论**：规则粒度、准确率阈值、模型选择、边缘案例。
+- **汇报进度**：每轮测试后，分享结果和下一步计划。
+- **升级问题**：迭代后仍无法解决的问题，附带证据提交给开发者用户。
+- **多问**：开发者用户是领域专家。对规则意图有疑问时，问他们。

package/template/skills/en/meta/compliance-judgment/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: compliance-judgment
+description: Determine whether extracted entities comply with verification rules. Use after entity extraction to make the pass/fail judgment for each rule on each document. Covers translating natural language rules into executable logic, choosing between Python calculation and LLM semantic judgment, and producing actionable comments on failures. Also use when designing the judgment step of a workflow or when a rule's judgment logic needs debugging.
+---
+
+# Compliance Judgment
+
+Judgment is the moment of truth. You have the extracted entity. You have the rule. Do they comply? The answer must be clear, correct, and — when the answer is no — accompanied by a concise, actionable comment.
+
+## The Judgment Spectrum
+
+Rules fall on a spectrum from fully deterministic to fully semantic:
+
+### Deterministic Judgments (Use Python)
+
+Rules with clear, computable criteria:
+
+- **Threshold checks**: "The capital adequacy ratio must be >= 8%."
+  ```python
+  result = "pass" if extracted_ratio >= 8.0 else "fail"
+  ```
+- **Format validation**: "The loan number must match pattern XX-YYYY-ZZZZZZ."
+  ```python
+  result = "pass" if re.match(r"[A-Z]{2}-\d{4}-\d{6}", loan_number) else "fail"
+  ```
+- **Date arithmetic**: "The contract must be signed within 30 days of application."
+  ```python
+  result = "pass" if (sign_date - app_date).days <= 30 else "fail"
+  ```
+- **Cross-field consistency**: "The total must equal the sum of line items."
+  ```python
+  result = "pass" if abs(total - sum(items)) < 0.01 else "fail"
+  ```
+
+These are best implemented as pure Python. They are free, instant, and deterministic. When possible, prefer this form.
+
+### Semantic Judgments (Use LLM)
+
+Rules requiring language understanding:
+
+- **Adequacy**: "The risk disclosure must adequately describe the key risks."
+- **Completeness**: "The management discussion must address financial performance, strategic outlook, and market conditions."
+- **Consistency**: "The executive summary must be consistent with the detailed findings."
+- **Compliance with template**: "The report must follow the format specified in Regulation Appendix A."
+
+For these, design an LLM prompt:
+1. Provide the rule text (what constitutes compliance).
+2. Provide the extracted content (what the document says).
+3. Ask for a structured verdict: pass/fail, reasoning, and comment.
+4. Ask the model to be conservative — flag as fail only when clearly non-compliant. When truly ambiguous, use a "partial" or "uncertain" result rather than a hard fail.
+
+### Hybrid Judgments (Most Common)
+
+Most rules combine deterministic and semantic elements:
+- Extract the number (regex) → compare to threshold (Python) → if borderline, assess the explanation (LLM).
+- Check that a section exists (deterministic) → check that it covers required topics (semantic).
+
+Design the pipeline to run cheap steps first. Only invoke the LLM when the deterministic check is insufficient.
+
+## Output Format
+
+For each rule × document combination:
+
+```json
+{
+  "rule_id": "R001",
+  "document": "report_2024_q1.pdf",
+  "result": "pass | fail | missing | error | uncertain",
+  "extracted_value": "12.5%",
+  "expected": ">= 8.0%",
+  "comment": "",
+  "confidence": 0.95
+}
+```
+
+**Result values:**
+- **pass**: Entity complies with the rule.
+- **fail**: Entity does not comply. Comment is required.
+- **missing**: The entity could not be found in the document. This is different from fail — the information is absent, not non-compliant.
+- **error**: Something went wrong during extraction or judgment (parsing failure, API error). Needs investigation.
+- **uncertain**: The judgment is ambiguous. May need human review.
+
+**Comments:**
+- Required only when result is `fail`. Skip for `pass` unless the developer user specifically requests pass comments.
+- Be concise and factual: "Capital adequacy ratio is 7.2%, below the regulatory minimum of 8.0%."
+- Do not editorialize: not "This is a serious violation that could result in penalties." Just state the facts.
+- Include the extracted value and the expected value/condition for context.
+
+### Lightweight Annotation Markup
+
+For human review, token-efficient logging, and clean diff comparisons, results can also be expressed in compact text markup:
+
+```
+[PASS] capital_adequacy <- 12.5% (>= 8.0%) | conf:0.95 | src:p3-s2
+[FAIL] sign_date_gap <- 75d (<= 30d) | conf:0.90 | src:p1-s4 | note:Signing overdue by 45 days
+[MISSING] collateral_value | conf:0.60 | note:Collateral valuation not found in document
+```
+
+This format is losslessly convertible to and from the JSON format above. Use it when presenting results to the developer user for quick review, logging to evolution iteration summaries where token economy matters, or computing diffs between verification runs. See `references/output-format.md` for the full specification and conversion rules.
+
+## Judgment Ordering
+
+Some rules depend on the results of other rules:
+- Rule B might only apply if Rule A passes. "If the borrower is a new customer (Rule A), then additional documentation is required (Rule B)."
+- Rule C might use a value computed by Rule A. "The risk-weighted capital ratio (Rule A) determines the required reserve level (Rule C)."
+
+Map these dependencies in the rule catalog. Execute rules in dependency order. Pass upstream results as context to downstream rules.
+
+## Handling Edge Cases
+
+- **Null extraction**: The entity was not found. Default to `missing`, not `fail`. A missing value is an extraction problem, not a compliance problem.
+- **Multiple values**: The document contains the entity in multiple places with different values. Flag as `uncertain`. Report all found values.
+- **Conditional rules**: "If the loan exceeds 1M, then collateral is required." Check the condition before applying the rule. If the condition is not met, the rule does not apply — result is `pass` (or `not_applicable` if you add that category).
+- **Negative results**: Some rules check for absence. "The document must NOT contain guarantees to related parties." Searching for absence is harder than searching for presence. Be thorough in the search, then be confident in the negative.