kc-beta 0.3.0 → 0.3.2

package/QUICKSTART.md

@@ -0,0 +1,149 @@
+# KC Agent CLI (Beta) — Quickstart
+
+## Install
+
+```bash
+npm install -g kc-beta
+```
+
+Requires **Node.js 20+**.
+
+## Setup
+
+Run the onboarding wizard to configure your LLM provider and API keys:
+
+```bash
+kc-beta onboard
+```
+
+You'll be prompted to choose:
+
+1. **Language** — English or 中文
+2. **LLM Provider** — SiliconFlow, Aliyun Bailian, Anthropic, OpenAI, VolcanoCloud, Zhipu GLM, MiniMax, OpenRouter, or custom
+3. **API Key** — your provider API key (supports both API keys and Aliyun/VolcanoCloud coding plan keys)
+4. **Model Discovery** — KC auto-discovers available models via API or curated lists and suggests tier assignments with capability-based ranking
+5. **Conductor Model** — the main model that drives the agent
+6. **Worker LLM Tiers** — tier1 (best) through tier4 (cheapest) for verification tasks
+7. **VLM Tiers** — vision models for OCR/document parsing (tier1-3)
+8. **Worker Provider** (optional) — use a different provider for worker LLMs (defaults to conductor provider)
+
+Config is saved to `~/.kc_agent/config.json` and shared across projects.
+
+### Edit Settings Later
+
+```bash
+kc-beta config
+```
+
+Category-based editor for: LLM provider, model tiers, VLM tiers, worker LLM provider, quality thresholds, language.
+
+## Create a Project
+
+```bash
+kc-beta init my-project
+kc-beta init my-project --lang=zh   # Chinese skills
+```
+
+This creates a workspace with:
+
+```
+my-project/
+  .env              # Project-level config (overrides global)
+  Rules/            # Put regulation documents here
+  Samples/          # Put sample documents here
+  Input/            # Production batches
+  Output/           # Verification results
+  skills/           # Meta-methodology skills (en or zh)
+```
+
+## Start the Agent
+
+```bash
+kc-beta             # default language from config
+kc-beta --en        # this session in English (does not change config)
+kc-beta --zh        # this session in Chinese (does not change config)
+```
+
+Launch from your project directory — KC has full read/write access to the folder you launch from:
+
+```bash
+cd my-project
+kc-beta
+```
+
+The agent starts in **BOOTSTRAP** phase. It will:
+
+1. Set up the workspace structure
+2. Detect regulations and samples in your project directory
+3. Ask about your verification scenario
+
+Once regulations and samples are in place, the agent advances through 6 phases automatically:
+
+| Phase | What happens |
+|-------|-------------|
+| **BOOTSTRAP** | Workspace setup, understand the scenario |
+| **EXTRACTION** | Decompose regulations into atomic rules |
+| **SKILL_AUTHORING** | Write verification skills for each rule |
+| **SKILL_TESTING** | Test skills, iterate via evolution loop |
+| **DISTILLATION** | Convert skills to worker LLM workflows |
+| **PRODUCTION_QC** | Run workflows on production docs with QC |
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show available commands |
+| `/status` | Session info, model, phase, context usage |
+| `/clear` | Clear conversation history |
+| `/compact` | Summarize older messages to reduce context usage |
+| `/sessions` | List all sessions |
+| `/resume <name>` | Resume a previous session (restores phase + pipeline state) |
+| `/rename <name>` | Rename current session |
+| `/exit` | Save state and quit |
+
+## Keyboard Shortcuts
+
+- **Enter** — Send message
+- **Ctrl+C** — Clear queue (if streaming) or save & exit
+- **Ctrl+D** — Save & exit
+
+## Status Bar
+
+The status bar shows:
+- Session ID and current phase
+- **Context usage**: `CTX: 45.2k/200k (23%)` — turns green/yellow/red as context fills
+
+## Per-Project Config
+
+Override global settings in your project's `.env`:
+
+```env
+LLM_API_KEY=sk-xxx
+LLM_BASE_URL=https://api.siliconflow.cn/v1
+
+TIER1=Pro/zai-org/GLM-5
+TIER2=
+TIER3=
+TIER4=
+
+SKILL_ACCURACY=0.9
+WORKFLOW_ACCURACY=0.9
+MAX_ITERATIONS=20
+
+# Optional: web search via Tavily
+TAVILY_API_KEY=tvly-xxx
+```
+
+Legacy keys (`SILICONFLOW_API_KEY`, `SILICONFLOW_BASE_URL`) are still accepted for backward compatibility.
+
+## Web Search
+
+KC can search the web using Tavily when information is not available in your provided documents. Set `TAVILY_API_KEY` in your `.env` or global config. KC prioritizes your domain documents over web results.
+
+## Troubleshooting
+
+- **"No API key configured"** — Run `kc-beta onboard` first
+- **Connection errors** — Check your API key and base URL. KC retries up to 10 times with exponential backoff on transient failures.
+- **Context too long** — Use `/compact` to summarize older messages, or let automatic windowing handle it
+- **Resume after crash** — Use `/resume <session-name>` to pick up where you left off
+- **Node version** — Requires Node.js 20+. Check with `node --version`

package/README.md

@@ -0,0 +1,207 @@
+# KC Agent CLI (`kc-beta`)
+
+> Build, distill, and run document verification systems with an LLM agent.
+> Pure Node.js. One binary. Bring your own model.
+
+KC is a coding agent purpose-built for **rule-based document verification**:
+read a regulation, decompose it into atomic verification rules, write skills
+to check each rule against sample documents, and (optionally) distill those
+skills into cheap worker-LLM workflows for production batch processing.
+
+It is designed for the developer at a bank, insurer, or law firm who needs
+to verify hundreds of documents against dozens of compliance rules — and
+wants the system to be transparent, testable, and ownable.
+
+---
+
+## Quick Install
+
+```bash
+npm install -g kc-beta
+kc-beta onboard      # configure provider + API key
+cd my-project        # a folder containing rules/ and samples/
+kc-beta              # launch the agent
+```
+
+Requires **Node.js 20+**. See [QUICKSTART.md](./QUICKSTART.md) for the full setup walkthrough.
+
+---
+
+## What It Does
+
+KC drives a single coding agent through six phases:
+
+| Phase | What it does |
+|-------|-------------|
+| **BOOTSTRAP**       | Set up the workspace, detect rules/samples in your project |
+| **EXTRACTION**      | Decompose regulation documents into atomic, testable rules |
+| **SKILL_AUTHORING** | Write a verification skill for each rule (Anthropic skill-creator format) |
+| **SKILL_TESTING**   | Run skills on samples, iterate via the evolution loop |
+| **DISTILLATION**    | Convert proven skills into cheap worker-LLM workflows |
+| **PRODUCTION_QC**   | Run workflows on production batches with confidence-based sampling |
+
+The conductor LLM (your main model) drives all reasoning. Worker LLM tools
+are gated to DISTILL phases only, so the build phase is always grounded in
+high-quality output.
+
+---
+
+## Architecture
+
+```
+~/.kc_agent/
+  config.json                       # provider, API key, model tiers
+  workspaces/<sessionId>/           # KC's working files
+    rules/, rule_skills/, workflows/, samples/, output/, logs/
+    AGENT.md                        # per-project context (KC can edit)
+    tasks.json                      # ralph-loop task list
+    session-state.json              # phase + pipeline state for /resume
+
+your-project/                       # where you launched kc-beta
+  rules/        # source regulations (KC reads with scope="project")
+  samples/      # sample documents
+  Output/       # KC writes user-facing reports here
+```
+
+**Dual-directory design.** KC has full read/write to its own workspace plus
+*scoped* read/write to your project directory. Source files stay in your
+project; KC's working artifacts stay in `~/.kc_agent/workspaces/`.
+
+**Phase-gated tools.** Worker LLM, workflow runner, tier downgrade, and QC
+sampling tools only register during DISTILL phases. BUILD phases force the
+conductor to do the intellectual work directly — the results are the
+ground-truth baseline for distillation.
+
+**Skills as first-class deliverables.** Every rule produces a self-contained
+skill folder (SKILL.md + scripts + references + samples). For complex rules
+that worker LLMs can't reliably handle, the skill itself — run by a capable
+agent — is the production solution.
+
+---
+
+## Provider Support
+
+10 providers configured out of the box:
+
+- **SiliconFlow** (default, recommended for China)
+- **Aliyun Bailian** (with coding-plan key support)
+- **VolcanoCloud** (ByteDance Doubao)
+- **Anthropic** (Messages API native)
+- **OpenAI**
+- **Zhipu GLM**
+- **MiniMax**
+- **OpenRouter**
+- **AWS Bedrock** (stub)
+- **Custom** (any OpenAI-compatible endpoint)
+
+Model assignments live in [`src/model-tiers.json`](./src/model-tiers.json) —
+edit directly to update tier-1 through tier-4 LLM and tier-1 through tier-3
+VLM (vision) models per provider, no code changes needed.
+
+You can use **separate providers** for the conductor and worker LLMs (e.g.,
+Anthropic conductor + SiliconFlow workers).
+
+---
+
+## Ralph-Loop Autonomous Execution
+
+When KC extracts rules, it automatically generates a per-rule task list and
+processes them one at a time. Between tasks the conductor's context is
+compacted aggressively, so context stays bounded even with 50+ rules.
+
+```
+SKILL_AUTHORING  [████████░░░░] 8/12
+✓ R001  Registered capital check
+✓ R002  Net asset adequacy
+▸ R003  Related-party disclosure   ← current
+·  R004  Risk capital calculation
+...
+```
+
+Use `/tasks` to see the full list. The agent decides *how* to do each task;
+the task manager only tells it *what's next*.
+
+---
+
+## Slash Commands
+
+```
+/help                Show available commands
+/status              Session, model, phase, context usage
+/tasks               Show task list and progress
+/clear               Clear conversation (workspace preserved)
+/compact             Summarize older messages via the conductor
+/sessions            List all sessions
+/resume <name>       Resume a previous session
+/rename <name>       Rename current session
+/exit                Save state and quit
+```
+
+`--en` / `--zh` flags override language for one session without writing config.
+
+---
+
+## Optional Plugins
+
+Some heavyweight features ship as **meta-meta skills** the agent invokes on
+demand, rather than always-on dependencies:
+
+- **`pdf-review-dashboard`** — Two-column HTML dashboard (PDF on the left,
+  verification results on the right, click-to-jump) for manual review and
+  ground-truth collection.
+- **`auto-model-selection`** — Use [Context7](https://github.com/upstash/context7)
+  CLI to fetch current model listings when the bundled `model-tiers.json`
+  is stale or you've switched providers.
+
+Both are bundled in `template/skills/{en,zh}/meta-meta/` and discovered by
+the skill loader at startup.
+
+---
+
+## Configuration
+
+Global config: `~/.kc_agent/config.json` (set by `kc-beta onboard`).
+Per-project override: `<project>/.env`.
+
+Edit anytime with the category-based editor:
+
+```bash
+kc-beta config
+```
+
+Categories: LLM Provider, Model Tiers, VLM Tiers, Worker LLM Provider,
+Quality Thresholds, Language.
+
+---
+
+## Documentation
+
+- [QUICKSTART.md](./QUICKSTART.md) — full setup and slash command reference
+- [DEV_LOG.md](./DEV_LOG.md) — release history and design rationale
+- [docs/global_update_design_v3.md](./docs/global_update_design_v3.md) — v3 design plan and progress tracker
+- [docs/initial_spec_draft.md](./docs/initial_spec_draft.md) — original architectural spec
+
+---
+
+## Status
+
+**v0.3.1 — beta.** Production-readiness update covering the seven blocks
+of the v3 design plan: dual-directory permissions, AGENT.md per-project
+context, PDF review dashboard skill, parsing/extraction skill rewrites,
+production-experience meta-skill polish, model-tier baseline + Context7
+plugin, and ralph-loop autonomous task execution.
+
+We are inviting a small group of developer users to test before public launch.
+Bug reports and PRs welcome at <https://github.com/kitchen-engineer42/kc-cli>.
+
+---
+
+## License
+
+MIT. Bundled meta-skills under `template/skills/` are proprietary —
+distributed via npm but not open-source. See `template/skills/LICENSE` for
+terms.
+
+---
+
+*Built by Memium / kitchen-engineer42.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kc-beta",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "KC Agent — LLM document verification agent (pure Node.js CLI)",
   "type": "module",
   "bin": {
@@ -9,8 +9,18 @@
   "files": [
     "bin/",
     "src/",
-    "template/"
+    "template/",
+    "README.md",
+    "QUICKSTART.md"
   ],
+  "homepage": "https://github.com/kitchen-engineer42/kc-cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitchen-engineer42/kc-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kitchen-engineer42/kc-cli/issues"
+  },
   "engines": {
     "node": ">=20.0.0"
   },

package/src/agent/engine.js

@@ -22,6 +22,7 @@ import { TierDowngradeTool } from "./tools/tier-downgrade.js";
 import { AgentTool } from "./tools/agent-tool.js";
 import { WebSearchTool } from "./tools/web-search.js";
 import { SkillLoader } from "./skill-loader.js";
+import { TaskManager } from "./task-manager.js";
 import { Phase } from "./pipelines/index.js";
 import { ProjectInitializer } from "./pipelines/initializer.js";
 import { RuleExtractionPipeline } from "./pipelines/extraction.js";
@@ -76,6 +77,9 @@ export class AgentEngine {
     // Session state persistence
     this.sessionState = new SessionState(this.workspace.cwd);
 
+    // Task manager (ralph-loop)
+    this.taskManager = new TaskManager(this.workspace.cwd);
+
     // Build all tool instances (but register phase-appropriate ones)
     this._buildTools = this._createAllTools();
     this._phaseSummaries = [];
@@ -199,6 +203,11 @@ export class AgentEngine {
         `Write user-facing exports (reports, results) to the project directory when the user asks.`,
       );
     }
+
+    // Task progress (ralph-loop)
+    const taskContext = this.taskManager.describeForContext();
+    if (taskContext) lines.push("", taskContext);
+
     return lines.join("\n");
   }
 
@@ -489,6 +498,10 @@ export class AgentEngine {
                 });
                 this.currentPhase = pEvent.nextPhase;
                 this._registerToolsForPhase(this.currentPhase);
+
+                // Ralph-loop: create per-rule tasks for the new phase
+                this._createTasksForPhase(this.currentPhase);
+
                 this.saveState();
               }
               yield new AgentEvent({
@@ -506,4 +519,80 @@ export class AgentEngine {
       }
     }
   }
+
+  /**
+   * Create per-rule tasks when entering a new phase.
+   * Reads the rule catalog and creates one task per rule for the given phase.
+   */
+  _createTasksForPhase(phase) {
+    const catalogPath = path.join(this.workspace.cwd, "rules", "catalog.json");
+    if (!fs.existsSync(catalogPath)) return;
+
+    try {
+      const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf-8"));
+      const rules = Array.isArray(catalog) ? catalog : [];
+      if (rules.length > 0) {
+        this.taskManager.createRuleTasks(rules, phase);
+      }
+    } catch { /* skip if catalog can't be read */ }
+  }
+
+  /**
+   * Ralph-loop: run a turn, then auto-continue through pending tasks.
+   * Compacts context aggressively between tasks to prevent context blowup.
+   * If no tasks exist, behaves identically to runTurn().
+   *
+   * @param {string} userMessage
+   * @yields {AgentEvent}
+   */
+  async *runTaskLoop(userMessage) {
+    // Run the initial turn (user's request)
+    yield* this.runTurn(userMessage);
+
+    // Auto-continue through pending tasks
+    while (this.taskManager.getNextPending()) {
+      // Context safety: force compaction if above 70%, or light compaction if history is long
+      const stats = this.getContextStats();
+      if (stats.percentage > 70) {
+        await this.compact();
+      } else if (this.history.messages.length > 15) {
+        await this.compact({ recentCount: 8 });
+      }
+
+      const task = this.taskManager.getNextPending();
+      this.taskManager.updateTask(task.id, { status: "in_progress" });
+
+      // Yield task progress event for TUI
+      yield new AgentEvent({
+        type: "task_progress",
+        data: {
+          taskId: task.id,
+          title: task.title,
+          ruleId: task.ruleId,
+          status: "in_progress",
+          progress: this.taskManager.progress,
+        },
+      });
+
+      // Synthesize a task-focused prompt
+      const taskPrompt = `Continue with next task: ${task.title}` +
+        (task.ruleId ? ` (rule: ${task.ruleId})` : "");
+
+      yield* this.runTurn(taskPrompt);
+
+      this.taskManager.updateTask(task.id, { status: "completed" });
+      this.taskManager.save();
+      this.saveState();
+
+      yield new AgentEvent({
+        type: "task_progress",
+        data: {
+          taskId: task.id,
+          title: task.title,
+          status: "completed",
+          progress: this.taskManager.progress,
+        },
+      });
+    }
+  }
 }

package/src/agent/task-manager.js

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Manages a per-session task list for ralph-loop style autonomous execution.
+ * Tasks are generated from KC's rule catalog — each rule becomes a task.
+ * Persisted to workspace/tasks.json.
+ */
+export class TaskManager {
+  /**
+   * @param {string} workspacePath - Session workspace directory
+   */
+  constructor(workspacePath) {
+    this._path = path.join(workspacePath, "tasks.json");
+    this._tasks = [];
+    this._load();
+  }
+
+  // --- Task CRUD ---
+
+  /**
+   * Add a task to the list.
+   * @param {{ id: string, title: string, phase: string, ruleId?: string }} task
+   */
+  addTask({ id, title, phase, ruleId }) {
+    // Don't add duplicates
+    if (this._tasks.find((t) => t.id === id)) return;
+    this._tasks.push({
+      id,
+      title,
+      phase,
+      ruleId: ruleId || null,
+      status: "pending",
+      summary: null,
+      createdAt: new Date().toISOString(),
+      completedAt: null,
+    });
+    this.save();
+  }
+
+  /**
+   * Update a task's status and optional summary.
+   * @param {string} id
+   * @param {{ status?: string, summary?: string }} updates
+   */
+  updateTask(id, { status, summary } = {}) {
+    const task = this._tasks.find((t) => t.id === id);
+    if (!task) return;
+    if (status) {
+      task.status = status;
+      if (status === "completed" || status === "failed") {
+        task.completedAt = new Date().toISOString();
+      }
+    }
+    if (summary !== undefined) task.summary = summary;
+    this.save();
+  }
+
+  /**
+   * Get the next pending task.
+   * @returns {object|null}
+   */
+  getNextPending() {
+    return this._tasks.find((t) => t.status === "pending") || null;
+  }
+
+  /**
+   * Get all tasks.
+   * @returns {Array}
+   */
+  getAllTasks() {
+    return [...this._tasks];
+  }
+
+  /**
+   * Check if there are any tasks at all.
+   */
+  get hasTasks() {
+    return this._tasks.length > 0;
+  }
+
+  // --- Bulk creation from rule catalog ---
+
+  /**
+   * Create one task per rule for a given phase.
+   * Reads rules from the provided array (typically from rules/catalog.json).
+   * @param {Array<{id: string, title?: string, description?: string}>} rules
+   * @param {string} phase - The phase these tasks belong to
+   */
+  createRuleTasks(rules, phase) {
+    for (const rule of rules) {
+      const ruleId = rule.id || rule.rule_id;
+      const title = rule.title || rule.description || ruleId;
+      this.addTask({
+        id: `${ruleId}-${phase}`,
+        title: `${title}`,
+        phase,
+        ruleId,
+      });
+    }
+  }
+
+  // --- Progress ---
+
+  /**
+   * @returns {{ total: number, completed: number, inProgress: number, pending: number, failed: number }}
+   */
+  get progress() {
+    const total = this._tasks.length;
+    const completed = this._tasks.filter((t) => t.status === "completed").length;
+    const inProgress = this._tasks.filter((t) => t.status === "in_progress").length;
+    const failed = this._tasks.filter((t) => t.status === "failed").length;
+    const pending = this._tasks.filter((t) => t.status === "pending").length;
+    return { total, completed, inProgress, pending, failed };
+  }
+
+  /**
+   * Format task list for injection into system prompt context.
+   * Compact checklist — not conversation history.
+   * @returns {string}
+   */
+  describeForContext() {
+    if (this._tasks.length === 0) return "";
+
+    const { total, completed, inProgress } = this.progress;
+    const current = this._tasks.find((t) => t.status === "in_progress");
+    const currentPhase = current?.phase || this._tasks.find((t) => t.status === "pending")?.phase || "";
+
+    const lines = [
+      `## Task Progress`,
+      `${completed}/${total} completed${currentPhase ? ` | Phase: ${currentPhase}` : ""}${current ? ` | Current: ${current.ruleId} — ${current.title}` : ""}`,
+      "",
+    ];
+
+    for (const t of this._tasks) {
+      const mark = t.status === "completed" ? "[x]"
+        : t.status === "in_progress" ? "[>]"
+        : t.status === "failed" ? "[!]"
+        : "[ ]";
+      const arrow = t.status === "in_progress" ? " <-- current" : "";
+      lines.push(`- ${mark} ${t.ruleId || t.id}: ${t.title}${arrow}`);
+    }
+
+    return lines.join("\n");
+  }
+
+  /**
+   * Format for /tasks slash command (more detailed than context injection).
+   * @returns {string}
+   */
+  formatForDisplay() {
+    if (this._tasks.length === 0) return "No tasks. Tasks are created when rules are extracted.";
+
+    const { total, completed, pending, failed } = this.progress;
+    const lines = [
+      `Tasks: ${completed}/${total} completed${failed ? `, ${failed} failed` : ""}, ${pending} pending`,
+      "",
+    ];
+
+    for (const t of this._tasks) {
+      const icon = t.status === "completed" ? "✓"
+        : t.status === "in_progress" ? "▸"
+        : t.status === "failed" ? "✗"
+        : "·";
+      lines.push(`  ${icon} ${t.ruleId || t.id}  ${t.title}  (${t.status})`);
+    }
+
+    return lines.join("\n");
+  }
+
+  // --- Persistence ---
+
+  save() {
+    fs.writeFileSync(this._path, JSON.stringify(this._tasks, null, 2), "utf-8");
+  }
+
+  _load() {
+    if (fs.existsSync(this._path)) {
+      try {
+        this._tasks = JSON.parse(fs.readFileSync(this._path, "utf-8"));
+      } catch {
+        this._tasks = [];
+      }
+    }
+  }
+}

package/src/agent/tools/document-parse.js

@@ -178,17 +178,12 @@ export class DocumentParseTool extends BaseTool {
         const page = await doc.getPage(i + 1);
         const viewport = page.getViewport({ scale: 2.0 }); // Higher res for OCR
 
-        // Use OffscreenCanvas or node-canvas if available, otherwise skip
+        // Render to PNG via node-canvas if available; otherwise skip VLM and let
+        // the escalation chain fall through to MineRU.
         let imageBase64;
         try {
-          // In Node.js, pdfjs can render to a canvas-like object
-          // We'll use the simpler approach: convert page to image via the API
           const { createCanvas } = await import("canvas").catch(() => ({ createCanvas: null }));
-          if (!createCanvas) {
-            // No canvas available — fall back to sending raw text content hint + page number
-            pages.push(`--- Page ${i + 1} (VLM) ---`);
-            continue;
-          }
+          if (!createCanvas) return null;
           const canvas = createCanvas(viewport.width, viewport.height);
           const ctx = canvas.getContext("2d");
           await page.render({ canvasContext: ctx, viewport }).promise;

package/src/cli/components.js

@@ -52,6 +52,40 @@ export function StatusBar({ sessionId, phase, contextTokens, contextLimit }) {
   );
 }
 
+// --- Task dashboard (ralph-loop) ---
+
+export function TaskDashboard({ tasks, progress }) {
+  if (!tasks || tasks.length === 0) return null;
+
+  const { total, completed } = progress || { total: 0, completed: 0 };
+  const barWidth = 20;
+  const filled = total > 0 ? Math.round((completed / total) * barWidth) : 0;
+  const bar = "\u2588".repeat(filled) + "\u2591".repeat(barWidth - filled);
+
+  // Show at most 8 tasks — current + a few before/after
+  const currentIdx = tasks.findIndex((t) => t.status === "in_progress");
+  const startIdx = Math.max(0, Math.min(currentIdx - 2, tasks.length - 8));
+  const visible = tasks.slice(startIdx, startIdx + 8);
+  const hasMore = tasks.length > 8;
+
+  return h(Box, { flexDirection: "column", marginLeft: 2, marginBottom: 1, borderStyle: "single", borderColor: "gray", paddingLeft: 1, paddingRight: 1 },
+    h(Text, { dimColor: true }, `Tasks [${bar}] ${completed}/${total}`),
+    ...visible.map((t) => {
+      const icon = t.status === "completed" ? "\u2713"
+        : t.status === "in_progress" ? "\u25b8"
+        : t.status === "failed" ? "\u2717"
+        : "\u00b7";
+      const color = t.status === "completed" ? "green"
+        : t.status === "in_progress" ? "cyan"
+        : t.status === "failed" ? "red"
+        : "gray";
+      const label = `${t.ruleId || t.id}  ${t.title}`;
+      return h(Text, { key: t.id, color }, `  ${icon} ${label.slice(0, 50)}`);
+    }),
+    hasMore ? h(Text, { dimColor: true }, `  ... ${tasks.length - 8} more`) : null,
+  );
+}
+
 // --- Welcome banner ---
 
 export function WelcomeBanner({ projectDir } = {}) {

package/src/cli/index.js

@@ -10,6 +10,7 @@ import {
   StatusBar,
   CookingSpinner,
   ToolBlock,
+  TaskDashboard,
   HRule,
   InputPrompt,
 } from "./components.js";
@@ -32,6 +33,8 @@ function App({ engine, config }) {
   const [spinnerStatus, setSpinnerStatus] = useState(null);
   const [contextTokens, setContextTokens] = useState(0);
   const [contextLimit, setContextLimit] = useState(config.kcContextLimit || 200000);
+  const [taskList, setTaskList] = useState([]);
+  const [taskProgress, setTaskProgress] = useState(null);
 
   const engineRef = useRef(engine);
   const streamingRef = useRef(false);
@@ -60,7 +63,7 @@ function App({ engine, config }) {
     let accumulated = "";
 
     try {
-      for await (const event of engineRef.current.runTurn(text)) {
+      for await (const event of engineRef.current.runTaskLoop(text)) {
         switch (event.type) {
           case "text_delta":
             accumulated += event.text ?? "";
@@ -110,6 +113,16 @@ function App({ engine, config }) {
             break;
           }
 
+          case "task_progress": {
+            const tp = event.data;
+            setTaskList(engineRef.current.taskManager.getAllTasks());
+            setTaskProgress(tp.progress);
+            if (tp.status === "in_progress") {
+              setSpinnerStatus(`Task: ${tp.title}`);
+            }
+            break;
+          }
+
           case "error":
             addMessage({ role: "system", content: `Error: ${event.message ?? "Unknown error"}` });
             break;
@@ -144,6 +157,7 @@ function App({ engine, config }) {
             "Commands:\n" +
             "  /help                Show this help\n" +
             "  /status              Show session info, model, phase, workspace\n" +
+            "  /tasks               Show task progress\n" +
             "  /clear               Clear conversation history (keep workspace)\n" +
             "  /compact             Summarize older messages to reduce context\n" +
             "  /sessions            List all sessions\n" +
@@ -172,6 +186,13 @@ function App({ engine, config }) {
         return true;
       }
 
+      case "/tasks":
+        addMessage({
+          role: "system",
+          content: engineRef.current.taskManager.formatForDisplay(),
+        });
+        return true;
+
       case "/clear":
         engineRef.current.history = new ConversationHistory(engineRef.current.workspace.cwd);
         setMessages([]);
@@ -323,6 +344,9 @@ function App({ engine, config }) {
     // Welcome banner
     showWelcome ? h(WelcomeBanner, { projectDir: config.projectDir }) : null,
 
+    // Task dashboard (ralph-loop)
+    taskList.length > 0 ? h(TaskDashboard, { tasks: taskList, progress: taskProgress }) : null,
+
     // Message history
     ...messages.map((msg, i) => {
       if (msg.role === "user") {

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）