kc-beta 0.5.6 → 0.6.0

package/QUICKSTART.md

@@ -93,7 +93,12 @@ Once regulations and samples are in place, the agent advances through 6 phases a
 | Command | Description |
 |---------|-------------|
 | `/help` | Show available commands |
-| `/status` | Session info, model, phase, context usage |
+| `/status` | Session info, model, phase, context usage, parallelism |
+| `/tasks` | Show ralph-loop task list and progress |
+| `/tools` | List registered tools + which phase gates each (v0.6.0) |
+| `/phase [sub]` | advance / status / `<name>` — manual phase override |
+| `/parallelism [N]` | Show / set parallel worker count 1-8 (v0.6.0) |
+| `/schedule` | Show scheduled ingestion jobs and recent logs |
 | `/clear` | Clear conversation history |
 | `/compact` | Summarize older messages to reduce context usage |
 | `/sessions` | List all sessions |
@@ -101,9 +106,12 @@ Once regulations and samples are in place, the agent advances through 6 phases a
 | `/rename <name>` | Rename current session |
 | `/exit` | Save state and quit |
 
-## Keyboard Shortcuts
+## Keyboard Shortcuts (v0.6.0 TUI upgrades)
 
-- **Enter** — Send message
+- **Enter** — Send message (or queue it if the agent is mid-turn)
+- **Left / Right** — Move cursor inside the current line
+- **Up / Down** — Navigate session-local input history
+- **Ctrl+A / Ctrl+E** — Jump to start / end of line
 - **Ctrl+C** — Clear queue (if streaming) or save & exit
 - **Ctrl+D** — Save & exit
 
@@ -111,7 +119,12 @@ Once regulations and samples are in place, the agent advances through 6 phases a
 
 The status bar shows:
 - Session ID and current phase
-- **Context usage**: `CTX: 45.2k/200k (23%)` — turns green/yellow/red as context fills
+- **Context usage**: `CTX: 45.2k/200k (23%)` — smoothed over 30 samples;
+  shows `· peak 52.1k` when the session has spiked meaningfully above
+  the current value
+- **Parallelism**: effective worker count (silently clamped to 1 unless
+  `KC_PARALLELISM_VERIFIED=1` — see the "Parallel Ralph-Loop" section
+  of the README)
 
 ## Per-Project Config
 

package/README.md

@@ -29,7 +29,7 @@ Requires **Node.js 20+**. See [QUICKSTART.md](./QUICKSTART.md) for the full setu
 
 ## What It Does
 
-KC drives a single coding agent through six phases:
+KC drives a single coding agent through seven phases:
 
 | Phase | What it does |
 |-------|-------------|
@@ -39,10 +39,11 @@ KC drives a single coding agent through six phases:
 | **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 |
+| **FINALIZATION**    | Package deliverables — canonical layout, README, coverage report, final dashboard (v0.6.0) |
 
 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.
+are gated to DISTILL + FINALIZATION phases, so the build phase is always
+grounded in high-quality output.
 
 ---
 
@@ -127,8 +128,12 @@ the task manager only tells it *what's next*.
 
 ```
 /help                Show available commands
-/status              Session, model, phase, context usage
+/status              Session, model, phase, context usage, parallelism
 /tasks               Show task list and progress
+/tools               List registered tools + which phase gates each (v0.6.0)
+/phase [sub]         advance | status | <name> — manual phase override
+/parallelism [N]     Show / set parallel ralph-loop worker count 1-8 (v0.6.0)
+/schedule            Show scheduled ingestion jobs
 /clear               Clear conversation (workspace preserved)
 /compact             Summarize older messages via the conductor
 /sessions            List all sessions
@@ -137,7 +142,12 @@ the task manager only tells it *what's next*.
 /exit                Save state and quit
 ```
 
-`--en` / `--zh` flags override language for one session without writing config.
+`--en` / `--zh` / `--parallelism=N` flags override for one session without writing config.
+
+**v0.6.0 TUI upgrades:** input stays active during streaming (type-ahead
+queues automatically), left/right arrow keys move the cursor, up/down
+recalls session history, Ctrl-A/Ctrl-E jump to start/end. CTX status bar
+smooths over 30 samples and tracks a session peak.
 
 ---
 
@@ -156,6 +166,27 @@ demand, rather than always-on dependencies:
 Both are bundled in `template/skills/{en,zh}/meta-meta/` and discovered by
 the skill loader at startup.
 
+## Parallel Ralph-Loop (v0.6.0)
+
+`--parallelism=N` (1-8) runs up to N verification tasks concurrently via
+subagent orchestration. Safety guardrails:
+
+- Silently clamps to 1 unless `KC_PARALLELISM_VERIFIED=1` is set in the
+  workspace `.env` — prevents accidental multi-hundred-dollar runs before
+  you've confirmed heap behavior.
+- `logs/heap.jsonl` is sampled every 60 s permanently. Run
+  `node scripts/heap-analyze.js` to get a FLAT / DRIFTING / GROWING
+  verdict from the current workspace's run.
+- `rules/catalog.json` writes serialize through a POSIX file lock;
+  concurrent workers no longer race each other.
+- `agent_tool` operations: `spawn` / `wait` / `poll` / `list` / `kill`
+  give the agent visibility and control over its own subagents. A
+  `stale_subagents` pipeline event on phase_advance lets the main agent
+  clean up before moving on.
+
+Recommended flow: run a 2h serial baseline first, confirm the heap
+verdict is FLAT, then set `KC_PARALLELISM_VERIFIED=1` and try N=2.
+
 ---
 
 ## Configuration
@@ -185,13 +216,29 @@ Quality Thresholds, Language.
 
 ## 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.
+**v0.6.0 — first architectural beta.** This release lands:
+
+- Parallel ralph-loop (up to 8 concurrent workers) with a heap-safety
+  conformance gate
+- Native chunker + RAG (onion-peeler + CJK bigram keyword index +
+  one-shot LLM bundle classifier, ported from the AMC verification app)
+- Source-context auto-attach on skill_authoring tasks (rule NL + evidence
+  chunks + sibling rules injected into the prompt, no manual search needed)
+- Workspace file locking for shared coordination files (`rules/catalog.json`,
+  `rules/manifest.json`, `tasks.json`, etc.)
+- `agent_tool` gets `wait` / `poll` / `list` / `kill` operations +
+  `stale_subagents` phase-advance signal
+- New FINALIZATION phase packages the session into a shippable deliverable
+  (canonical `rule_skills/` layout + README + coverage report + final
+  dashboard)
+- Input stays active during streaming (type-ahead queue), arrow keys +
+  history recall, CTX smoothing + peak, per-provider context-limit caps,
+  `/tools`, `/parallelism`, and more
+
+See [DEV_LOG.md](./DEV_LOG.md) for the full v0.6.0 change breakdown and
+[docs/update_design_v5.md](./docs/update_design_v5.md) for the plan that
+drove it.
 
-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>.
 
 ---

package/bin/kc-beta.js

@@ -1,16 +1,50 @@
 #!/usr/bin/env node
 
-// Parse --en / --zh from anywhere in argv (session-only language override)
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+// Parse --en / --zh / --parallelism from anywhere in argv
 const args = process.argv.slice(2);
 let languageOverride = null;
+let parallelismOverride = null;
 const filtered = [];
 for (const arg of args) {
   if (arg === "--en") languageOverride = "en";
   else if (arg === "--zh") languageOverride = "zh";
+  else if (arg.startsWith("--parallelism=")) {
+    const n = parseInt(arg.slice("--parallelism=".length), 10);
+    if (Number.isFinite(n) && n >= 1) parallelismOverride = Math.min(n, 8);
+  }
   else filtered.push(arg);
 }
 const subcommand = filtered[0];
 
+// B3: Surface parallelism intent via env so loadSettings() picks it up uniformly.
+// Matches the workspace-.env pattern other KC configs use.
+if (parallelismOverride !== null) {
+  process.env.KC_PARALLELISM = String(parallelismOverride);
+}
+
+// A4: Startup banner. Prevents the v0.3.2-ghost-install problem (user ran
+// 4 releases worth of "fixes" that were silently not installed because of
+// a stale global npm cache — invisible in field trials until v0.5.5).
+// Always-on; prints version + resolved script path so users can immediately
+// see what's running. Skipped for `--version` / `--help` because those have
+// their own output.
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function printBanner() {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(__dirname, "..", "package.json"), "utf-8"));
+    const scriptPath = __filename;
+    process.stderr.write(`⏵⏵  KC Agent CLI  v${pkg.version}  ·  ${scriptPath}\n`);
+  } catch { /* package.json missing or unreadable — silent */ }
+}
+const suppressBanner = args.includes("--version") || args.includes("-v") ||
+                       args.includes("--help") || args.includes("-h");
+if (!suppressBanner) printBanner();
+
 (async () => {
   if (subcommand === "onboard" || subcommand === "setup") {
     const { onboard } = await import("../src/cli/onboard.js");

package/package.json

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