openhermes 4.11.2 → 4.13.0

package/CONTEXT.md

@@ -3,7 +3,7 @@
 ## Terms
 **OpenHermes** — OpenCode-native orchestration layer for this package.
 **Skill** — A `SKILL.md` loaded on demand through OpenCode's skill tool.
-**Command** — A slash command backed by package-local markdown in `harness/commands/`.
+**Command** — A slash command backed by package-local command markdown; legacy compatibility loaders remain only where runtime-backed.
 **Agent** — A primary or subagent definition loaded through OpenCode config.
 **Instruction** — Markdown loaded through `AGENTS.md` or `opencode.json` instructions.
 **Bootstrap** — The first-message context injected by the OpenHermes plugin.

package/ETHOS.md

@@ -9,7 +9,7 @@ OpenCode-native loading over manual copying or hidden state.
 Every file earns its keep. Prefer markdown when behavior is declarative.
 
 ## Skills Over Glue
-Behavior lives in `SKILL.md`, `commands/*.md`, and `agents/*.md`.
+Behavior lives in `SKILL.md`, command markdown, and agent markdown. Legacy command-doc compatibility loaders remain supported only where runtime-backed.
 
 ## Always Delegate — Never Execute
 OpenHermes orchestrates and reports. Sub-agents execute. OpenHermes never writes code, runs tests, or touches files directly.

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/openhermes"><img src="https://img.shields.io/npm/v/openhermes?style=for-the-badge&label=version&color=FFD700" alt="v4.11.1"></a>
+  <a href="https://www.npmjs.com/package/openhermes"><img src="https://img.shields.io/npm/v/openhermes?style=for-the-badge&label=version&color=FFD700" alt="npm version"></a>
   <a href="https://github.com/nathwn12/openhermes/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License: MIT"></a>
   <a href="https://opencode.ai"><img src="https://img.shields.io/badge/runs%20on-OpenCode-6366f1?style=for-the-badge" alt="Runs on OpenCode"></a>
   <a href="https://github.com/nathwn12/openhermes"><img src="https://img.shields.io/badge/⭐%20star%20on-GitHub-181717?style=for-the-badge" alt="Star on GitHub"></a>
@@ -33,18 +33,13 @@ To install from `dev` (latest features, may be unstable):
 
 ## One sentence. One engine.
 
-OpenHermes v4.11 ships with a hardened internal architecture — 8 subsystems working together to make every session faster, more reliable, and fully autonomous:
+OpenHermes ships with a focused internal architecture — 3 subsystems working together to make every session faster, more reliable, and fully autonomous:
 
 | Subsystem | What it does |
 |-----------|-------------|
 | **Prompt Composer** | 9 modular fragments joined at runtime → byte-identical. Add a fragment, never edit the composition code. |
-| **Auto-Recovery** | 9 error categories with typed actions — retry with backoff, compact on overflow, escalate on unknowns. Self-healing. |
-| **4-Tier Memory** | System → Project → Mission → Task. Importance-scored, budget-enforced, plan-file-persisted. Context that survives hops. |
-| **Hook Registry** | Pluggable pre-tool, post-tool, route, and session hooks with topological sort. 8 built-in hooks, zero routing boilerplate. |
-| **MVCC Sync** | Atomic writes, version counters, conflict detection. Multiple sub-agents writing the same plan file — no data loss. |
-| **Sanity Checker** | 8 output degeneration detectors — repetition, gibberish, low diversity — with automatic escalation and recovery injection. |
-| **Background Cmd** | Fire-and-forget process spawning with timeout, status polling, and auto-cleanup. Non-blocking long-running tasks. |
-| **Test Harness** | Disposable temp dirs (Symbol.asyncDispose), factory builders, restore-capable mocks. Professional-grade test utilities. |
+| **Hook Registry** | Pluggable pre-tool, post-tool, route, and session hooks with priority-sort ordering. 7 built-in hooks, zero routing boilerplate. |
+| **Plan Location** | Resolves plan file paths per project with directory-per-project layout in `~/.local/share/openhermes/plans/`. |
 
 ---
 
@@ -72,14 +67,14 @@ The loop runs unsupervised because these never turn off:
 |---|---|
 | **Self-driving loop** | Type once. OpenHermes classifies, delegates, and routes — no pauses, no asking permission, no verbosity. |
 | **30 specialist skills** | Planning → building → testing → browser → security → review → shipping → retro. Every dev cycle phase. |
-| **Auto-detected user skills** | Drop a skill in `~/.agents/skills/`. OpenHermes finds it. Same name as a built-in? Your version wins. Survives `npm update`. |
+| **Auto-detected user skills** | Drop a skill in `~/.agents/skills/` or `~/.config/opencode/skills/`. OpenHermes finds it. Same name as a built-in? Your version wins. Survives `npm update`. |
 | **Shared operating model** | CHARTER + AUTOPILOT + CONTEXT + ETHOS injected every session. Every interaction grounded in the same rules. |
 | **CORE/DEEP skill format** | Every skill is a two-file system: CORE (SKILL.md) handles 80% of passes in one read. DEEP.md loads on demand for hard cases. |
 | **Plan file storage** | `~/.local/share/openhermes/plans/`. Survives `npm update`. |
-| **8 internal subsystems** | Compositor, hooks, memory, recovery, sync, sanity checks, background commands, test harness — all native Node.js / TypeScript. |
+| **3 internal subsystems** | Composer, hooks, plans — all native Node.js / TypeScript. |
 | **Zero npm dependency additions** | All new subsystems use native Node.js and TypeScript only. No new packages. |
 
-## 30 skills — three tiers
+## 30 skills — four tiers
 
 ### Tier 4 — Pipeline orchestrators
 Full multi-phase workflows:
@@ -138,21 +133,20 @@ openhermes-pkg/
 ├── AGENTS.md              # User-side routing overlay
 ├── CONTEXT.md             # Shared domain language
 ├── ETHOS.md               # Operating principles
+├── docs/
+│   ├── HOW-IT-WORKS.md     # Runtime data flow (routing, hooks, plans)
+│   └── adr/                 # Architecture Decision Records
 ├── bootstrap.ts           # Plugin entry — registers everything
 ├── index.ts               # Package entrypoint
 ├── harness/
 │   ├── agents/            # Agent manifests (OpenHermes primary)
 │   ├── codex/             # CHARTER, AUTOPILOT
-│   ├── commands/          # Slash commands
 │   ├── instructions/      # SHELL.md
 │   ├── lib/               # Internal subsystems
 │   │   ├── composer/      # Prompt fragment composition
-│   │   ├── recovery/      # Auto-recovery with error patterns
-│   │   ├── memory/        # 4-tier hierarchical memory
-│   │   ├── sync/          # MVCC plan synchronization
 │   │   ├── hooks/         # Pluggable hook registry
-│   │   ├── sanity/        # Output degeneration detection
-│   │   └── background/    # Fire-and-forget command system
+│   │   ├── plans/         # Plan file path resolution
+│   │   └── ...            # guards/ (guard config)
 │   └── skills/            # 30 skill SKILL.md files (CORE/DEEP format)
 ├── lib/                   # harness-resolver.ts
 └── test/

package/bootstrap.ts

@@ -4,21 +4,24 @@ import os from "node:os"
 import type { Plugin } from "@opencode-ai/plugin"
 import { getHarnessDir, setHarnessRootForTest, resolveHarnessRoot } from "./lib/harness-resolver.ts"
 import { compose } from "./harness/lib/composer/index.ts"
+import { ensurePlanFile, findLatestPlanFile, planStorageDir, setPlanStorageDirForTest, resolvePlanAccess } from "./harness/lib/plans/plan-location.ts"
+import { clearRuntimeRouteDecision, consumeRouteGuidance, getRuntimeRouteDecision, rememberRuntimeRouteDecision } from "./harness/lib/routing/index.ts"
 
 // Hook system — pluggable lifecycle hooks with topological sort
 import {
   HookRegistry,
   HookResult,
+  nextRouteHook,
   planCheckHook,
   shellDetectHook,
   confidenceGateHook,
   delegationDepthHook,
   resetDepthTracker,
-  errorRecoveryHook,
-  memorySyncHook,
-  sanityCheckHook,
+  dynamicRouteHook,
   routeTrackingHook,
+  DEFAULT_GUARD_CONFIG,
 } from "./harness/lib/hooks/index.ts"
+import type { HookContext } from "./harness/lib/hooks/index.ts"
 
 const OPENHERMES_AGENT = "OpenHermes"
 
@@ -29,18 +32,7 @@ const USER_SKILL_DIRS: ReadonlyArray<string> = [
   path.join(os.homedir(), ".claude", "skills"),      // Claude Code backward compat
 ]
 
-// Canonical storage under OpenCode's data directory — survives npm updates
-let _planStorageOverride: string | undefined
-export function setPlanStorageDirForTest(dir: string | undefined): void { _planStorageOverride = dir }
-function planStorageDir(): string {
-  return _planStorageOverride ?? path.join(os.homedir(), ".local", "share", "openhermes", "plans")
-}
-
-function getProjectName(projectDir: string): string {
-  return path.basename(projectDir)
-}
-
-export { resolveHarnessRoot, setHarnessRootForTest, getHarnessDir, ensurePlanFile, findLatestPlanFile }
+export { resolveHarnessRoot, setHarnessRootForTest, getHarnessDir, ensurePlanFile, findLatestPlanFile, setPlanStorageDirForTest }
 
 function parseFrontmatter(raw: string | undefined): Record<string, string> {
   const frontmatter: Record<string, string> = {}
@@ -140,46 +132,6 @@ function uniqueStrings(existing: string[] = [], additions: string[] = []): strin
 }
 
 
-function findLatestPlanFile(projectDir: string): string | null {
-  const projectName = getProjectName(projectDir)
-  const storage = planStorageDir()
-  const projectDirPath = path.join(storage, projectName)
-  if (!fs.existsSync(projectDirPath)) return null
-  let latest: string | null = null
-  let highest = -1
-  try {
-    for (const entry of fs.readdirSync(projectDirPath)) {
-      const m = entry.match(/^plan-(\d{3})\.md$/)
-      if (m) {
-        const n = parseInt(m[1], 10)
-        if (n > highest) {
-          highest = n
-          latest = path.join(projectDirPath, entry)
-        }
-      }
-    }
-  } catch {
-    return null
-  }
-  return latest
-}
-
-function readPlanFromFile(filePath: string): string | null {
-  if (!fs.existsSync(filePath)) return null
-  const source = fs.readFileSync(filePath, "utf8")
-  const status = source.match(/^Status:\s*(.+)$/m)?.[1]?.trim()
-  const objective = source.match(/^Objective:\s*(.+)$/m)?.[1]?.trim()
-  if (!status && !objective) return null
-  const parts = [status ? `status=${status}` : null, objective ? `objective=${objective}` : null].filter(Boolean)
-  return `Active plan: ${parts.join(" | ")}`
-}
-
-function readPlanSummary(projectDir: string): string | null {
-  const planFile = findLatestPlanFile(projectDir)
-  if (!planFile) return null
-  return readPlanFromFile(planFile)
-}
-
 function ensureDir(dir: string): void {
   try {
     if (!fs.existsSync(dir)) {
@@ -192,68 +144,6 @@ function ensureDir(dir: string): void {
   }
 }
 
-/**
- * Ensure a plan file exists for the project.
- * Creates a skeleton plan if none exists or if the latest is complete/abandoned.
- * Reuses an existing active or in-progress plan.
- * Returns the path to the plan file.
- */
-function ensurePlanFile(projectDir: string): string {
-  const projectName = getProjectName(projectDir)
-  const storage = planStorageDir()
-  const projectDirPath = path.join(storage, projectName)
-  ensureDir(projectDirPath)
-
-  // Reuse active or in-progress plan
-  const latest = findLatestPlanFile(projectDir)
-  if (latest) {
-    const content = fs.readFileSync(latest, "utf8")
-    const status = content.match(/^Status:\s*(.+)$/m)?.[1]?.trim()
-    if (status === "active" || status === "in-progress") {
-      return latest
-    }
-  }
-
-  // Determine next sequence number
-  let nextSeq = 1
-  if (latest) {
-    const m = path.basename(latest).match(/^plan-(\d{3})\.md$/)
-    if (m) nextSeq = parseInt(m[1], 10) + 1
-  }
-
-  const seq = String(nextSeq).padStart(3, "0")
-  const planId = `${projectName}/plan-${seq}.md`
-  const planPath = path.join(projectDirPath, `plan-${seq}.md`)
-  const now = new Date().toISOString().replace("T", " ").slice(0, 16)
-
-  const content = [
-    `# PLAN: ${projectName}`,
-    "",
-    `Plan ID: ${planId}`,
-    `Project: ${projectName}`,
-    `Status: active`,
-    `Created: ${now}`,
-    `Updated: ${now}`,
-    `Project Path: ${projectDir}`,
-    `Plan Path: ${planPath}`,
-    `Objective: (pending classification)`,
-    "",
-    "## Tasks",
-    "",
-    "- [ ] (discoverable — pending classification)",
-    "",
-  ].join("\n")
-
-  try {
-    fs.writeFileSync(planPath, content, "utf8")
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err)
-    console.error(`[openhermes] Failed to write plan file ${planPath}: ${msg}`)
-    // Don't throw — let the plan system degrade gracefully
-  }
-  return planPath
-}
-
 export function buildCompactionContext(projectDir: string): string[] {
   const context = [
     "OpenHermes: native-first, verify before claim, always delegate, concise over verbose.",
@@ -261,7 +151,7 @@ export function buildCompactionContext(projectDir: string): string[] {
     "Preserve blockers, current task, and next steps; do not invent durable state.",
   ]
 
-  const planSummary = readPlanSummary(projectDir)
+  const planSummary = resolvePlanAccess(projectDir)?.summary
   if (planSummary) context.push(planSummary)
 
   return context
@@ -333,13 +223,17 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
   // Ensure plan storage exists
   try { ensureDir(planStorageDir()) } catch {}
 
+
+
   return {
     config: async (config: OpenHermesConfig) => {
+
       // ── 1. Hooks System ─────────────────────────────────────────────────
       // Read experimental.hooks config from the raw config object
-      const hooksConfig = (config.experimental as Record<string, unknown> | undefined)?.hooks as
+      const experimental = config.experimental as Record<string, unknown> | undefined;
+      const hooksConfig = (experimental?.hooks as
         | Record<string, boolean>
-        | undefined
+        | undefined)
       const hooksEnabled = (hooksConfig?.enabled ?? true) as boolean
 
       if (hooksEnabled) {
@@ -349,12 +243,14 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
         if (hooksConfig?.plan_check ?? true) reg.registerPreTool(planCheckHook)
         if (hooksConfig?.shell_detect ?? true) reg.registerPreTool(shellDetectHook)
         if (hooksConfig?.delegation_depth ?? true) reg.registerPreTool(delegationDepthHook)
+        reg.registerRoute(nextRouteHook)
         if (hooksConfig?.confidence_gate ?? true) reg.registerRoute(confidenceGateHook)
-        if (hooksConfig?.error_recovery ?? true) reg.registerPostTool(errorRecoveryHook)
-        if (hooksConfig?.memory_sync ?? true) reg.registerPostTool(memorySyncHook)
-        if (hooksConfig?.sanity_check ?? true) reg.registerPostTool(sanityCheckHook)
-        if (hooksConfig?.route_tracking ?? true) reg.registerRoute(routeTrackingHook)
-
+        if (hooksConfig?.dynamic_route ?? true) reg.registerPostTool(dynamicRouteHook)
+        if (hooksConfig?.route_tracking ?? true) {
+          reg.registerRoute(routeTrackingHook)
+        } else {
+          reg.unregister("route-tracking")
+        }
         await logToOC("info", `hooks: ${reg.getPreToolHooks().length + reg.getPostToolHooks().length + reg.getRouteHooks().length} registered`)
       } else {
         await logToOC("info", "hooks: disabled via config")
@@ -379,10 +275,20 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
       const loadedAgents = agentDefinitions(agentsDir)
       // Use composer for the OpenHermes agent prompt — assemble from fragments
       let openHermesPrompt: string
+      const injectSelfKnowledge = (prompt: string): string => {
+        try {
+          const pkgDir = import.meta.dirname
+          const pkg = JSON.parse(fs.readFileSync(path.resolve(pkgDir, "package.json"), "utf-8"))
+          return `OpenHermes v${pkg.version} | Install: ${pkgDir} | Harness: ${hDir}\n\n${prompt}`
+        } catch {
+          return prompt
+        }
+      }
       try {
-        openHermesPrompt = compose()
+        openHermesPrompt = injectSelfKnowledge(compose())
       } catch {
         openHermesPrompt = loadedAgents[OPENHERMES_AGENT]?.prompt ?? "You are OpenHermes."
+        openHermesPrompt = injectSelfKnowledge(openHermesPrompt)
       }
       const openHermesAgent = {
         description: loadedAgents[OPENHERMES_AGENT]?.description ?? "OpenHermes primary orchestrator",
@@ -445,7 +351,7 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
             question: "allow",           // CAN ask user questions
             websearch: "allow",          // CAN search web for research context
             external_directory: {         // CAN read/write plan files outside worktree
-              "~/.local/share/opencode/openhermes/**": "allow",
+              "~/.local/share/openhermes/plans/**": "allow",
             },
           },
         },
@@ -482,24 +388,23 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
         // Access optional fields from input (SDK may include these at runtime)
         const inputAny = input as Record<string, unknown>
         const agentName = typeof inputAny.agent === "string" ? inputAny.agent : "unknown"
+        const pendingNextRoute = getRuntimeRouteDecision(ctx.directory) ?? undefined
 
         // Build hook context from input and current session state
-        const hookContext = {
+        const hookContext: HookContext = {
           sessionId: ctx.directory,           // project directory as session key
           agent: agentName,
           directory: ctx.directory,
           sessions: new Map(),
           _confidenceLevel: typeof inputAny.confidence === "string" ? inputAny.confidence : undefined,
           _confidenceExchanges: 0,
-          _maxDelegationDepth: 25,
-          _routeTrackingConfig: {
-            maxSkillRepeats: 5,
-            maxUnproductiveHops: 30,    // higher than max delegation depth (25) so depth guard fires first
-          },
+          _guardConfig: DEFAULT_GUARD_CONFIG,
+          _nextRoute: pendingNextRoute,
+          _routingSkillsDir: skillsDir,
         }
 
         // Run all registered PreToolUse hooks (plan check, shell detect, delegation depth)
-        let preToolResult: any
+        let preToolResult: { result: HookResult; modifiedContext?: HookContext }
         try {
           preToolResult = await reg.executePreTool(hookContext)
         } catch (err) {
@@ -515,7 +420,7 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
           const errOutput = output as { args: unknown; isError?: boolean; content?: unknown[] }
           errOutput.isError = true
           const message = (preToolResult.modifiedContext?._depthError as string)
-            ?? "LOOP GUARD: Delegation depth exceeded (max 25). " +
+            ?? `LOOP GUARD: Delegation depth exceeded (max ${DEFAULT_GUARD_CONFIG.maxDelegationDepth}). ` +
                "Surface to orchestrator with findings and stop delegating."
           errOutput.content = [{ type: "text", text: message }]
           return
@@ -546,7 +451,7 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
         // Run all registered RouteHooks — the agent/skill being delegated to IS the route
         // This fires confidence-gate (inject confirm/question on MEDIUM/LOW confidence)
         // and route-tracking (guard against infinite routing loops)
-        let routeResult: any
+        let routeResult: { result: HookResult; modifiedRoute?: string }
         try {
           routeResult = await reg.executeRoute(hookContext, agentName)
         } catch (err) {
@@ -560,13 +465,22 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
           // Loop guard triggered by route-tracking hook
           const errOutput = output as { args: unknown; isError?: boolean; content?: unknown[] }
           errOutput.isError = true
-          const ctxAny = hookContext as Record<string, unknown>
-          const optiReport = ctxAny._optiRoute
-            ? JSON.stringify(ctxAny._optiRoute, null, 2)
+          const optiReport = hookContext._optiRoute
+            ? JSON.stringify(hookContext._optiRoute, null, 2)
             : "Route guard: Excessive or unproductive routing detected."
           errOutput.content = [{ type: "text", text: `ROUTE GUARD: ${optiReport}\n\nSurface to orchestrator with findings and stop delegating.` }]
         }
 
+        if (routeResult.modifiedRoute) {
+          const concreteRoute = routeResult.modifiedRoute.split("?")[0] ?? routeResult.modifiedRoute
+          if (concreteRoute && concreteRoute !== agentName) {
+            inputAny.agent = concreteRoute
+          }
+          if (pendingNextRoute?.selected && concreteRoute === pendingNextRoute.selected) {
+            clearRuntimeRouteDecision(ctx.directory)
+          }
+        }
+
         if (routeResult.result === HookResult.INJECT && routeResult.modifiedRoute) {
           // Confidence gate wants to inject a confirmation/pause into routing.
           // Parse the modifiedRoute for markers and inject into task description/prompt.
@@ -605,19 +519,21 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
         const agentName = typeof inputAny.agent === "string" ? inputAny.agent : "unknown"
 
         // Build hook context from input and current session state
-        const hookContext = {
+        const hookContext: HookContext = {
           sessionId: ctx.directory,
           agent: agentName,
           directory: ctx.directory,
           sessions: new Map(),
           _confidenceLevel: typeof inputAny.confidence === "string" ? inputAny.confidence : undefined,
           _confidenceExchanges: 0,
-          _maxDelegationDepth: 25,
+          _guardConfig: DEFAULT_GUARD_CONFIG,
+          _routingSkillsDir: skillsDir,
         }
  
         // Extract output text from tool result
         // output.content may be array of content blocks, or a string, or undefined
         const outputAny = output as Record<string, unknown> | undefined
+        const mutableOutput = (output ?? {}) as Record<string, unknown>
         let outputText = ""
         if (outputAny?.content) {
           const content = outputAny.content
@@ -634,18 +550,27 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
         try {
           const postToolResult = await reg.executePostTool(hookContext, outputText)
 
-          // Surface recovery instructions from errorRecoveryHook and/or sanityCheckHook
-          if (postToolResult.recovery) {
-            await logToOC("warn", `PostTool recovery instruction:\n${postToolResult.recovery}`)
-          }
-
           // Log when hooks signal issues (INJECT = anomaly/error detected by a hook)
           if (postToolResult.result === HookResult.INJECT) {
             await logToOC("warn", "PostTool INJECT: hooks detected issues in tool output")
           }
 
-          // memorySyncHook catches its own errors (best-effort sync),
-          // so memory sync failures are already handled gracefully inside the hook
+          const routedOutput = consumeRouteGuidance(postToolResult.modifiedOutput ?? outputText)
+          const finalOutput = routedOutput.output
+          const runtimeNextRoute = rememberRuntimeRouteDecision(ctx.directory, finalOutput)
+
+          if (finalOutput !== outputText) {
+            if (typeof outputAny?.content === "string") {
+              mutableOutput.content = finalOutput
+            } else {
+              mutableOutput.content = [{ type: "text", text: finalOutput }]
+            }
+          }
+
+          if (runtimeNextRoute) {
+            mutableOutput._nextRoute = runtimeNextRoute
+          }
+
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err)
           await logToOC("error", `Hook error (PostTool): ${msg}`)

package/docs/HOW-IT-WORKS.md

@@ -0,0 +1,162 @@
+# How OpenHermes Works
+
+This document traces the runtime data flow of the OpenHermes plugin package.
+It is the primary bus-factor mitigation for the routing engine, hook system, plan storage, and composer.
+
+## 1. Skill Routing Flow
+
+```
+User Request
+     │
+     ▼
+Orchestrator (classifies task, loads skill)
+     │
+     ├── Skill SKILL.md frontmatter defines routes:
+     │     pass → [oh-ship, oh-gauntlet]
+     │     fail → oh-planner
+     │     blocker → surface
+     │
+     ▼
+Route Resolver (harness/lib/routing/route-resolver.ts)
+     │
+     ├── Collects route candidates from skill frontmatter
+     ├── Applies NEXT_ROUTE overrides from subagent output
+     ├── Applies ROUTE_GUIDANCE evidence from subagent output
+     └── Selects target skill or terminal (surface/done)
+     │
+     ▼
+Dispatch to target skill subagent
+```
+
+### Key files:
+- `harness/lib/routing/route-resolver.ts` — resolves route candidates from skill frontmatter
+- `harness/lib/routing/route-guidance.ts` — applies NEXT_ROUTE overrides and evidence
+- `harness/lib/routing/skill-frontmatter.ts` — parses pass/fail/blocker from SKILL.md
+
+## 2. Hook Lifecycle
+
+```
+BootstrapPlugin registers hooks during init
+     │
+     ▼
+PreTool hooks fire before tool execution (EARLY → NORMAL → LATE)
+     │
+     ├── confidence-gate: checks user input for injection tokens
+     ├── delegation-depth: prevents runaway agent chains (max 5)
+     ├── plan-check: ensures plan files exist for multi-step work
+     └── shell-detect: identifies Windows shell type
+     │
+     ▼
+PostTool hooks fire after tool execution
+     │
+     ├── route-tracking: logs which route was taken
+     ├── next-route: captures NEXT_ROUTE from output
+     └── dynamic-route: applies evidence-driven routing
+     │
+     ▼
+Route hooks modify routing decisions
+     │
+Session hooks fire on session boundaries
+```
+
+### Hook Types:
+| Type | When | Count |
+|------|------|-------|
+| PreTool | Before each tool call | 4 |
+| PostTool | After each tool call | 3 |
+| Route | During route resolution | 0 (extensible) |
+| Session | Session start/end | 0 (extensible) |
+
+### Phases (within each hook type):
+- **EARLY** — high-priority, runs first
+- **NORMAL** — standard priority
+- **LATE** — low-priority, runs last
+
+### Key files:
+- `harness/lib/hooks/builtins/` — 7 built-in hook implementations
+- `harness/lib/hooks/hooks.test.ts` — hook system tests (928 lines)
+- `bootstrap.ts` — hook registration in `plugin.tool.execute.before/after`
+
+## 3. Plan Storage
+
+```
+Plans stored at: ~/.local/share/openhermes/plans/<project>/
+     │
+     ├── <project>/plan-001.md
+     ├── <project>/plan-002.md
+     └── <project>/plan-003.md
+     │
+     ▼
+Sequential numbering (001, 002, 003...)
+     │
+     ▼
+Status lifecycle:
+     active/in-progress → keep
+     complete/abandoned → delete
+```
+
+### Key files:
+- `harness/lib/plans/plan-location.ts` — resolves canonical paths
+- `bootstrap.ts` — exports `ensurePlanFile`, `findLatestPlanFile`, `resolveHarnessRoot`
+
+## 4. Composer (Agent Prompt Assembly)
+
+```
+9 numbered fragments in harness/lib/composer/fragments/
+     │
+     ├── 01-identity.md    → "You are OpenHermes..."
+     ├── 02-delegation.md  → Core Behaviors
+     ├── 03-permissions.md → Permission matrix
+     ├── 04-task-flow.md   → Task flow steps
+     ├── 05-confidence.md  → Stop Conditions
+     ├── 06-parallelization.md → Parallelization rules
+     ├── 07-shell.md       → Shell Awareness
+     ├── 08-routing.md     → Plan Storage
+     └── 09-guardrails.md  → Guardrails + Routing
+     │
+     ▼
+compose.ts assembles fragments with phase filtering (EARLY/NORMAL/LATE)
+     │
+     ▼
+Path traversal sanitization prevents directory escape
+     │
+     ▼
+Output: complete agent prompt consumed by the LLM
+```
+
+### Key files:
+- `harness/lib/composer/compose.ts` — fragment assembly engine
+- `harness/lib/composer/fragments/` — 9 content fragments
+- `harness/agents/openhermes.md` — agent manifest declaring fragments
+
+## 5. Full Request Lifecycle (ASCII Overview)
+
+```
+┌─────────────────────────────────────────────────────┐
+│  User sends request                                 │
+│         │                                           │
+│         ▼                                           │
+│  OpenHermes Orchestrator                            │
+│         │                                           │
+│         ├── 1. Classify task (investigate/build/...)│
+│         ├── 2. Load skill (SKILL.md frontmatter)    │
+│         ├── 3. PreTool hooks fire (confidence, etc) │
+│         ├── 4. Delegate to subagent                 │
+│         ├── 5. Subagent returns output + evidence   │
+│         ├── 6. PostTool hooks fire (tracking, etc)  │
+│         ├── 7. ROUTE_EVIDENCE parsed                │
+│         └── 8. Route to next skill or surface       │
+│                    │                                │
+│                    ▼                                │
+│  Next skill (or surface/done)                       │
+└─────────────────────────────────────────────────────┘
+```
+
+## Architecture Summary
+
+| System | Purpose | Key File |
+|--------|---------|----------|
+| Routing | Resolves next skill from frontmatter + evidence | `harness/lib/routing/route-resolver.ts` |
+| Hooks | Plugin extensibility points | `harness/lib/hooks/builtins/` |
+| Plans | Canonical task tracking | `harness/lib/plans/plan-location.ts` |
+| Composer | Agent prompt assembly | `harness/lib/composer/compose.ts` |

package/docs/adr/ADR-0001-rebuild-vs-increment.md

@@ -0,0 +1,30 @@
+# ADR-0001: Rebuild v3→v4
+
+**Status**: Accepted
+**Date**: 2026-05-19
+
+## Context
+
+The project started as a memory-tools plugin (v1–v3) with OHC compression. After three major versions, the architecture had accumulated significant complexity from incremental additions. The codebase mixed memory-tool concerns with nascent orchestration logic. Two paths existed: continue patching the existing architecture with incremental fixes, or clean-sheet rebuild as a full skill-harness platform.
+
+Key constraints:
+- The platform vision demanded 30+ skills and 17+ agent types — far beyond the original scope
+- Existing users depended on v3 stability
+- Team bandwidth allowed only one major direction
+
+## Decision
+
+Clean-sheet rebuild into a 30-skill, 17-agent harness platform with:
+- Routing engine for skill dispatch
+- Hooks system for plugin extensibility
+- Canonical plan storage with sequential naming
+- Fragment-based prompt composition
+
+No backward compatibility with v3 memory-tools internals.
+
+## Consequences
+
+- **Positive**: Fundamentally better foundation for the platform vision. Clean separation between routing, hooks, plans, and composition. Easier to test each subsystem independently.
+- **Positive**: Ability to onboard new skill types and agent roles without fighting legacy constraints.
+- **Negative**: Temporary disruption of ongoing work — existing v3 features had to be re-implemented.
+- **Negative**: Migration cost for any v3 users adopting the new platform.