# KHY OS vs oh-my-openagent Task Delivery Gap Analysis

> Analysis date: 2026-05-16
> KHY OS version: current main branch
> oh-my-openagent version: v4.1.2
> Trigger: KHY cannot independently complete a multi-file SSM (Spring + MyBatis) project

---

## Summary

KHY has the necessary coding tools (writeFile, editFile, scaffoldFiles, shellCommand, buildProject, runTests) but **the loop engine is too weak** to drive them through a full project build-fix-test lifecycle. The AI gets cut off mid-task before reaching a working state.

---

## 1. Quantified Limits

| Metric | KHY Current | Real Project Needs | oh-my-openagent |
|--------|-------------|-------------------|-----------------|
| Loop iterations | 10 (max 100 via env) | 20-30 | No hard limit (Ralph Loop) |
| Wall-clock timeout | 120s (max 600s via env) | 300-600s | Activity-based idle timeout |
| Shell output cap | 50 KB | 200 KB+ (Maven/Gradle logs) | Streaming, no truncation |
| Edit reliability | String match (old → new) | Hash-verified per line | Hashline xxh32 content hash |
| Failure recovery | Retry + exponential backoff | Checkpoint + resume | Boulder State persistence |
| Parallel agents | Serial (cliAgentRunner) | 2-4 concurrent | Team Mode + mailbox protocol |
| Mode switching | None | Intent-triggered | IntentGate keyword detection |
| Hook composition | Inline hardcoded | 5-tier fault-isolated | Session → ToolGuard → Transform → Continuation → Skill |

---

## 2. Five Critical Gaps

### Gap 1: No Persistent Execution Loop — P0

**Problem**: `toolUseLoop.js` defaults to 10 iterations / 120s hard timeout. A typical SSM project workflow requires:

```
create structure → write pom.xml → write Java classes → mvn install →
read errors → fix code → rebuild → write tests → run tests → fix → rerun
```

This easily exceeds 20 rounds and 300 seconds.

**oh-my-openagent solution**: Ralph Loop + Boulder State
- No iteration hard limit — loop continues as long as there's productive work
- Boulder State saves task progress to disk — survives crashes and session boundaries
- Cross-session continuation — resume exactly where it stopped

**KHY impact**: AI is forced to stop before the project compiles. User sees partial, broken output.

**Fix**: Implement activity-based idle timeout (stop only when no productive work for N seconds) and raise iteration cap to 50+. Add checkpoint/resume for long-running tasks.

---

### Gap 2: No IntentGate Mode Switching — P0

**Problem**: When user says "create an SSM project", KHY has no mechanism to:
- Inject a coding-mode system prompt (force structured task execution)
- Set `tool_choice: required` (force the AI to call tools, not just chat)
- Suppress conversational filler during execution

**oh-my-openagent solution**: IntentGate keyword detector
- Magic words (`ultrawork`, `search`, `analyze`, `team`, `hyperplan`) trigger mode injection
- Each mode injects a specialized system prompt + tool constraints
- `ultrawork` mode: long system prompt emphasizing autonomous completion, mandatory tool use, no stopping until done

**KHY impact**: AI responds with suggestions ("you could create a pom.xml with...") instead of actually creating the files. Particularly bad with weaker models.

**Fix**: Add IntentGate layer in agenticHarnessService. Detect project-creation / coding keywords → inject coding-mode prompt + force tool use.

---

### Gap 3: Unreliable Edits (No Hashline) — P1

**Problem**: `editFile` uses plain string matching (`old_string` → `new_string`). When a file has duplicate or similar content blocks, the edit can hit the wrong location. In a 200-file Java project, edit errors accumulate and cause cascading failures.

**oh-my-openagent solution**: Hashline LINE#ID system
- Each line gets a 2-char ID derived from xxh32 content hash (alphabet: `ZPMQVRWSNKTXJBYH`)
- Edit tool validates that target line content matches the hash before applying
- Stale edits (file changed since AI read it) are rejected with clear error

**KHY impact**: Silent corruption — AI thinks edit succeeded but changed the wrong block. Debugging cost multiplies.

**Fix**: Add content fingerprint validation to editFile. Before applying, verify `old_string` appears at the expected location. On mismatch, return error with current file state.

---

### Gap 4: No Hook Composition System — P1

**Problem**: Tool behavior is hardcoded inline across toolCalling.js, toolUseLoop.js, and individual tool files. No interception layer exists for cross-cutting concerns.

**oh-my-openagent solution**: 5-tier hook composition
| Tier | Purpose | Example |
|------|---------|---------|
| Session | Lifecycle events (start, end, error) | Auto-save session trace |
| ToolGuard | Pre/post tool validation (16 types) | Block dangerous shell commands |
| Transform | Input/output transformation | Compress large tool results |
| Continuation | Loop control | Ralph Loop continuation logic |
| Skill | Skill-specific behavior | Inject domain context |

Key hooks KHY is missing:
- **Comment Checker**: External binary that scans Write/Edit output for AI-generated slop comments (`// This function does X`, `// TODO: implement`) and blocks them
- **Edit Error Recovery**: On editFile failure, auto-injects "READ the file first, then retry" guidance
- **ToolGuard validators**: 16 pre-execution checks (path safety, output size, rate limiting)

All hooks are config-gated (`isHookEnabled()`) and fault-isolated (`safeCreateHook` — hook crash doesn't kill the loop).

**KHY impact**: Errors aren't auto-recovered. Quality isn't enforced at tool boundaries. Every fix requires modifying core loop code.

**Fix**: Design 3-tier hook registry (ToolGuard + Transform + Continuation). Implement Edit Error Recovery and Comment Checker as first hooks.

---

### Gap 5: No Parallel Team Mode — P2

**Problem**: `cliAgentRunner` dispatches agents serially. For a large project, one agent does everything sequentially.

**oh-my-openagent solution**: Team Mode
- Parallel multi-agent with role assignment (coder, tester, reviewer)
- Mailbox protocol for inter-agent communication
- Backpressure: if one agent is blocked, others continue
- Acknowledgment: agents confirm receipt of shared artifacts

**KHY impact**: Large projects take N× longer. No specialization — single agent must context-switch between writing code, running builds, fixing errors, and writing tests.

**Fix**: Extend cliAgentRunner with mailbox protocol and concurrent dispatch. Lower priority — P0/P1 fixes have higher ROI.

---

## 3. SSM Project Failure Walkthrough

What happens when user asks KHY to create an SSM project:

```
Round 1:  scaffoldFiles → create directory structure          ✅ (~2s)
Round 2:  writeFile × 5 → pom.xml files                      ✅ (~3s)
Round 3:  writeFile × 20 → Java entity/mapper/service classes ✅ (~5s)
Round 4:  shellCommand → mvn clean install                    ⚠️ (~45s, may timeout)
Round 5:  AI reads truncated Maven error (50KB cap)           ⚠️ (incomplete context)
Round 6:  editFile → fix first compilation error              ⚠️ (may hit wrong location)
Round 7:  shellCommand → mvn clean install again              ⚠️ (~45s)
Round 8:  More errors, more fixes needed                      ⚠️
Round 9:  Still fixing...                                     ⚠️
Round 10: HARD LIMIT REACHED — loop terminates                ❌
```

**Result**: User gets a half-built project that doesn't compile. Remaining work:
- 10+ compilation errors unfixed
- No tests written
- No application.yml configured
- No MyBatis mapper XML files
- Build never succeeded

---

## 4. Fix Roadmap

### P0 — Blocking (enables any project delivery)

| # | Fix | Files | Effort |
|---|-----|-------|--------|
| 1 | **Activity-based idle timeout** — replace hard 120s with idle detection (reset on tool completion, AI reply, stream chunk) | `toolUseLoop.js`, `agenticHarnessService.js` | Medium |
| 2 | **Raise iteration cap** — default 30, max 100, env-configurable | `toolUseLoop.js` | Small |
| 3 | **IntentGate mode injection** — detect coding/project keywords → inject system prompt + force tool_choice | `intentGate.js` (new), `agenticHarnessService.js` | Medium |
| 4 | **Shell output expansion** — 50KB → 200KB, auto-extract ERROR/FAILURE lines from large logs | `toolSandbox.js`, `shellCommand` tool | Small |

### P1 — Quality (reduces fix-loop iterations)

| # | Fix | Files | Effort |
|---|-----|-------|--------|
| 5 | **Edit Error Recovery hook** — on editFile failure, auto re-read file + retry with fresh content | `toolCalling.js` or new hook layer | Small |
| 6 | **Content fingerprint validation** — verify old_string location before applying edit | `editFile` tool | Medium |
| 7 | **Build error summarizer** — parse Maven/Gradle/npm output, extract actionable error list | New utility in `toolUseLoop.js` | Medium |

### P2 — Competitive parity (long-term)

| # | Fix | Files | Effort |
|---|-----|-------|--------|
| 8 | **3-tier hook composition** — ToolGuard + Transform + Continuation with config-gating | New `hookRegistry.js` | Large |
| 9 | **Comment Checker** — block AI slop comments in Write/Edit output | New hook | Medium |
| 10 | **Team Mode** — parallel agents with mailbox protocol | `cliAgentRunner.js` refactor | Large |
| 11 | **Boulder State** — checkpoint/resume for long tasks across sessions | New persistence layer | Large |

### Expected Outcome After P0

| Metric | Before | After P0 |
|--------|--------|----------|
| SSM project completion | ❌ Fails at round 10 | ✅ Completes in 20-30 rounds |
| Wall-clock budget | 120s hard | 600s+ activity-based |
| AI behavior on "create project" | Chatty, suggests instead of executes | Forced tool use, autonomous execution |
| Maven error visibility | Truncated at 50KB | Full errors extracted |

---

## 5. Comparison Matrix

| Capability | KHY OS | oh-my-openagent | Claude Code | Qwen Code |
|-----------|--------|-----------------|-------------|-----------|
| Max loop iterations | 10 | Unlimited | ~200 | ~100 |
| Timeout model | Hard wall-clock | Activity-based idle | Activity-based | Hard + idle hybrid |
| Edit validation | String match | Hashline xxh32 | Unique string match | AST-aware |
| Error recovery | Manual retry | Auto hook | Auto retry | Auto retry |
| Mode switching | None | IntentGate keywords | Plan mode toggle | Task/chat mode |
| Parallel agents | Serial | Team Mode mailbox | Background agents | Serial |
| Hook system | None | 5-tier composition | Pre/post hooks | Plugin hooks |
| Cross-session state | None | Boulder State | Task persistence | Session restore |

---

## References

- oh-my-openagent source: `/tmp/oh-my-openagent-dev/oh-my-openagent-dev/`
- Alignment log: `docs/guides/OHMYOPENAGENT_ALIGNMENT_LOG.md`
- Alignment dimensions: `AGENTS.md` lines 257-344
- KHY tool loop: `backend/src/services/toolUseLoop.js`
- KHY agentic harness: `backend/src/services/agenticHarnessService.js`
- KHY tool sandbox: `backend/src/services/toolSandbox.js`
