OKLMdocumentation v1.0.3
On this page

Gap analysis: the coding-agent specification against oklm agent

Every section of agent_skill_chat_spec.md, then of process_spec.md, git_spec.md and commands_spec.md, against what the harness already does, of serving_spec.md against the server, and of rag_spec.md against what retrieval can build on, with evidence. The plan built on it is agent-design.md.

Status: audits of 2026-11-02: the agent specification's M0, then the process (P0), git (G0), commands (C0) and serving (S0) specifications' sections at the end, then the RAG specification's K0 (2026-11-08); each is updated at the start of its milestones.

Review of 2026-11-04: every row not marked ✅ was checked against the code again. 88 rows changed, most of them done by later milestones (hooks, compaction, templates, checkpoints, services, integrations, the git layer). What is still open (2026-11-08, the order to take it in is the roadmap's "Next": housekeeping, small leftovers, known speed gaps, larger work, what is optional, what is deferred, what is blocked, what stays out on purpose and why):

  • Two defects found, both fixed since: with --worktree, the project's settings were parsed and its WorktreeCreate hook ran before the trust question; processes started by a background sub-agent had no owner and could die with its thread (PR_SET_PDEATHSIG is per thread).
  • Missing by choice: LS, mcp serve, /keybindings, /voice, /subtask, /fast, /advisor, iOS (the reasons in the roadmap, "Left out on purpose"); the job tests on Windows wait on a real Windows machine (roadmap, "Blocked"). The command classifier is done.
  • Partial: the rows marked 🟡, each saying what is left.
  • Training on a large base: done on Qwen3-8B (two QLoRA rounds of the MCP fine-tune on the quantized base, the T rows below); the security fine-tune's next run is deferred (the roadmap's "Next", section 5); the hybrid layers' real-weight check is blocked (an 80B release only).

Legend: ✅ present, 🟡 partial, ❌ missing, ⚠️ conflicting with the spec's conventions (on purpose where the row says so). Paths are relative to the repository root. In apps/oklm.c, functions are named instead of lines, which move often.

Answers to the spec's "fill in before starting"

Question Answer Evidence
Interpreter / runtime OKLM's own C inference engine, in the same process: the agent tokenizes, keeps the KV cache of the common prefix, evaluates and samples itself. The OpenAI-compatible server (/v1/chat/completions with tools) exists, but the agent does not use it. The only other source of text is the generate callback, which the tests use as a mock. src/harness/agent.c:1447-1596 (model_turn); include/oklm/harness/agent.h:203-221; src/server/server.c
Model(s) and context window Any supported GGUF family (Llama, Qwen 2/3, Gemma 1-3, Phi 2/3, Granite and its MoE, GPT-2, DeepSeek 1/2, Qwen MoE). The default model is Qwen3-8B Q4_K_M, found in the models directories when nothing names one (Qwen3-4B Q4_K_M for quick runs). oklm agent opens 32768 tokens by default, within the model's training length; a turn has at most 8192 tokens and a message 32 turns. apps/oklm.c cmd_agent; agent.c:231-239; compatibility.md; agent-loop.md
Native tool calling Yes. The tools go into the chat template's tools variable, in five wire formats: Hermes (<tool_call>), Llama 3 (<|python_tag|> or bare JSON), Mistral ([TOOL_CALLS]), GLM-4.5 (<tool_call> with <arg_key> / <arg_value> pairs) and GLM-4-0414 (the name, then JSON arguments, at the start of the turn). The format is detected from the template or set with --tool-format, Hermes otherwise. From the trigger on, the call is constrained by a grammar built from the tools' schemas. include/oklm/model/tool_calls.h; agent.c:1225-1239, 1527-1576; adr/0009-tool-calls-and-grammars.md
Vision The engine yes (oklm describe, SmolVLM). The agent no: messages are text, and Read refuses images as binary. include/oklm/mm/vision.h; src/harness/tools.c:449-465
Implementation language C17 with POSIX threads; libc and nilorea (compiled from source) only. adr/0001-language-and-dependencies.md, adr/0014-nilorea-as-source-tree.md
Platforms Linux: everything, commands confined by namespaces, seccomp and limits. Windows (MinGW, tested under Wine): everything but the confinement, commands get Job Object limits only. macOS: not a target. build.md; src/harness/sandbox.c; adr/0011-sandbox.md
Binary, config dir, memory file ⚠️ on purpose (agent-design.md decisions 1 and 2): oklm agent (a subcommand), .oklm/ in the project and ~/.config/oklm/ for the user ($XDG_CONFIG_HOME, %APPDATA% on Windows), managed /etc/oklm/managed-settings.json ($OKLM_MANAGED_SETTINGS), .agent/ read as a fallback. Memory files: AGENTS.md (written by /init), OKLM.md, AGENT.md, CLAUDE.md (M5b). src/harness/permissions.c:618-631; skills.c:1121-1156; memory.c default_names

§0, §0A Principles and audit

§ Feature Status Evidence Notes
0 Swappable backend ✅ (M1) agent.h oklm_agent_backend; agent_http.c; agent_mock.c The model in process, an OpenAI-compatible HTTP server, fixtures, or the caller's callback (as row 49). test_agent.c test_mock, test_http_chunks
0 Tools never crash the loop ✅ tools.c:3941-4016 Failures become OKLM_TOOL_ERROR / DENIED text. test_tools.c test_files, test_asking; test_agent.c test_denied
0 Testable without a model ✅ test_agent.c (scripted generate)
0A Gap analysis and design note ✅ this file, agent-design.md

§1 Directory layout

§ Feature Status Evidence Notes
1 Layout ✅ src/harness/ (about 40 modules), include/oklm/harness/, tests/harness/ One module per concern with its own test (agent-design.md, principles of the mapping); new modules go to src/harness/.

§2 Model adapter

§ Feature Status Evidence Notes
2.1 Adapter interface (context window, token count, stream events) ✅ (M1) agent.h oklm_agent_backend, oklm_agent_event The in-process model, a backend (HTTP, mock, the caller's), stream events with usage and stop reasons. Token counting per part is §10.
2.2 Chat template with tools and tool results ✅ agent.c:1330-1375; src/model/chat_template.c; adr/0006-chat-templates.md test_agent.c test_calls
2.2 Prefix cache reuse ✅ agent.c:1476-1498 The system prompt changes with the skills list and plan notice (agent.c:804-867), so a mode change drops the cache. No direct test.
2.2 Cancel during generation ✅ (M1) oklm_agent_cancel(); apps/oklm.c view_interrupt, view_keys Within a token; Esc and Ctrl-C on the terminal. test_server.c test_agent_model, test_agent.c test_cancel_text
2.2 Retry and backoff ✅ agent_http.c http_turn, oklm_agent_http_set_retries, oklm_agent_http_transient; settings maxRetries No connection, a time-out, 408, 409, 429 and 5xx sent again after 1, 2, 4 s... (30 s at most, or Retry-After), 4 times by default, never once part of the answer has arrived; a cancel stops the wait; 4xx fail at once. test_server.c test_agent_http_retry
2.3 Text tool-call protocol ⚠️ tool_calls.h; adr/0009-tool-calls-and-grammars.md On purpose (ADR-0009): each family's native format instead of {"name","input"}, Hermes the fallback.
2.3 Lenient parser ✅ (M2) src/model/tool_calls.c json_repair Code fences, single quotes, trailing commas, raw newlines, Python literals, calls cut off; fuzzed (fuzz_toolcalls, 46 million inputs). test_grammar.c test_tool_calls_lenient
2.3 Schema validation, error with the schema, N retries ✅ (M2) tools.c args_fit; agent.c watch_loop Every call checked against its schema, the error naming the fault and showing the schema; three invalid calls in a row stop the turn. test_tools.c test_search_options, test_agent.c test_loops
2.3 Fake tool results detected ✅ (M2) tool_calls.c before_fake_results Text from <tool_response> / [TOOL_RESULTS] on is dropped with any call after it.
2.4 <think> parsing ✅ src/harness/think.c; agent.c:1383-1387, 2725 test_think.c
2.4 Folded display; kept out of later context ✅ (M1) apps/oklm.c view_split, view_toggle; agent.c any_turn Folded with Ctrl-O; stripped from sub-agent reports and from what is sent back to a backend; the in-process templates drop it. test_agent.c test_think_in_content
2.4 "think hard" keywords, budget 🟢 agent.c model_turn, agent_send_inner; settings maxReasoningTokens maxReasoningTokens (OKLM_MAX_REASONING_TOKENS) caps a turn's <think> tokens, closing the block so the answer follows; a think hard/think harder/think deeply/ultrathink in the message lifts the cap for that turn. /effort still turns a template's reasoning on or off.
2.5 Fast model, /model, model per sub-agent ✅ oklm.c c_model, cmd_agent (smallModel); agent.c oklm_agent_set_aux_model, sub_model /model switches the main model (a GGUF reloaded, or the HTTP backend's). smallModel loads a small model beside the main one for the asides (titles, compaction summaries): it answers in its own context, the main model's cache untouched. A sub-agent definition's model: small (or fast) runs the sub-agent on it, in a context of its own. test_agent.c test_aux_model.
2.6 Mock adapter with fixtures ✅ (M1) agent_mock.c; oklm agent --mock JSONL fixtures, requests recorded. test_agent.c test_mock

§3 Messages

§ Feature Status Evidence Notes
3 Roles ✅ agent_internal.h:28-44; agent.c:286-323 OpenAI-style tool role.
3 Content blocks (text, image, thinking, tool use, tool result) 🟡 agent_internal.h agent_msg; agent.h OKLM_AGENT_EV_REASONING Text, parsed calls, results by call id and metadata; reasoning is a stream event left out of the history; no image blocks (Read says the model cannot see images).
3 One result per call, "Interrupted" ✅ (M2) agent.c oklm_agent_send Interrupted calls get "Interrupted by the user", calls that cannot run an error result. test_agent.c test_cancel_tools
3 Metadata (uuid, parent, time, usage, isMeta) ✅ (M2) oklm_agent_message() test_agent.c test_parallel_reads, test_loops

§4 Agent loop

§ Feature Status Evidence Notes
4 Generate, run tools, return results, repeat ✅ agent.c:4077-4411 test_agent.c test_calls
4 Hooks ✅ (M11) hooks.c oklm_hooks_run As rows 227 to 231: nine events, exit codes, JSON decisions. test_hooks.c
4 System reminders ✅ (M5) agent.c remind, push_meta; tools.c oklm_tool_ctx_changed_files Jobs, background reports, loops, the mode when it changes, files changed on disk, the task list gone stale; merged into the user's message for the template. test_agent.c test_reminders
4 Automatic compaction ✅ (M7) compact.c agent_context_check, micro_compact, agent_compact_now As row 175: compaction at compactThreshold (0.85) and micro-compaction of old tool results. test_compact.c test_long_session, test_rolling
4 Read-only tools in parallel ✅ (M2) agent.c parallel_group Read, Glob, Grep, JobOutput in a row, unasked. test_agent.c test_parallel_reads
4 Result truncation ✅ agent.c:2642-2663 Head only, no spill file.
4 Turn limit ✅ agent.c:4143-4145, --max-turns test_agent.c test_turn_limit
4 Interrupts (Esc, Ctrl-C) ✅ (M1) oklm_agent_cancel(), view_interrupt, view_keys Generation, a running command, the remaining calls; a second Ctrl-C on an empty prompt exits. test_agent.c test_cancel_*
4 Steering while working ✅ (M2) oklm_agent_steer(); apps/oklm.c view_key test_agent.c test_steering
4 Loop detection ✅ (M2) agent.c watch_loop test_agent.c test_loops
4 Token budget ✅ agent.h max_tokens, max_turns; oklm.c --max-turns, --max-tokens A budget per turn and a ceiling of turns, as the spec asks. test_agent.c test_turn_limit

§5 Tools

§ Feature Status Evidence Notes
5 Common contract ✅ tools.c tools_read_only, oklm_tool_ctx_read_only, custom-tool read_only; mcp.c (readOnlyHint); agent.c parallel_group Read-only calls run in parallel: the built-in read tools, and program-added or MCP tools that declare it (an MCP tool's readOnlyHint reaches the context, so its read calls parallelize). test_mcp.c test_server.
5 Truncation with spill file ✅ agent.c clip, clip_spill; process.c keeper Output capped at maxToolOutputChars (30000); when a foreground result is longer it is spilled whole to .oklm/tool-output/ and the cut tells the model the path to Read for the rest (background jobs keep their output in their log). test_agent.c test_spill.
5.1 Read ✅ (M2) tools.c t_read PDF page ranges, notebooks, images named (no vision), the read registry. test_tools.c test_read_kinds
5.2 Write ✅ (M3) tools.c t_write, freshness Atomic, parents created; an existing file only once read and unchanged (hash); CR LF and byte order mark kept. test_tools.c test_write_edit
5.3 Edit ✅ (M3) tools.c t_edit, apply_edit, edit_snippet Not-read and changed-since-read errors, Read's line numbers stripped, CR LF matched, numbered snippet in the result. test_tools.c test_write_edit
5.4 MultiEdit ✅ (M3) tools.c t_multi_edit In order, all or none. test_tools.c test_write_edit
5.5 Glob ✅ (M2) tools.c t_glob, list_files .gitignore files, newest first, 1000 at most. test_tools.c test_search_options
5.6 Grep ✅ (M2) tools.c t_grep OKLM's regex engine (no ripgrep); types, context, multiline, output modes, head_limit and offset. test_tools.c test_search_options
5.7 LS ❌ tools.c tools[] Optional; Glob and Bash list files.
5.8 Bash: persistent shell ✅ (M3) tools.c shell_wrap Directory and variables saved by an EXIT trap and restored (POSIX; not on Windows); a directory outside the project reset. test_tools.c test_shell
5.8 Timeouts, exit code, output ✅ tools.c:1971-2062 test_tools.c test_bash
5.8 Background ✅ tools.c:1648-1775; jobs.c Plus detach. test_jobs.c test_tools
5.8 Head and tail kept, ANSI stripped ✅ (M3) process.c keeper, strip_ansi test_tools.c test_shell
5.8 Interactive commands neutralized ✅ (M3) process.c (stdin from /dev/null, pager and editor variables) test_tools.c test_shell
5.9 BashOutput / KillShell ✅ tools.c (BashOutput read as ProcessOutput, KillShell as ProcessStop) The spec's names are aliases (agent-design.md decision 3); ProcessOutput gives the output since the model last read it.
5.10 WebFetch ✅ (M16) tools.c t_webfetch; client.c oklm_client_fetch No small-model summary of the page (the text is given, capped by the output limit), no cache. test_web.c
5.11 WebSearch ✅ (M16) tools.c t_websearch Through a SearXNG instance (webSearch.url) only. test_web.c
5.12 TodoWrite ✅ (M5) tools.c t_todo activeForm (todo_active), one task in progress, shown whole on the terminal, recalled by reminders. test_tools.c test_plan, test_agent.c test_reminders
5.13 Task ✅ (M12) agent.c run_subagent Named Agent on purpose, Task read as an alias (agent-design.md decision 3); as row 192. test_subagents.c
5.14 NotebookEdit ✅ (M16) tools.c t_notebook_edit test_web.c test_notebook
5.15 AskUserQuestion ✅ (M16) tools.c t_ask_question; oklm.c agent_question test_web.c test_ask; tools/check_commands.sh
5.16 ExitPlanMode / EnterPlanMode 🟡 tools.c t_exit_plan; oklm.c c_plan ExitPlanMode only: the model cannot enter plan mode itself; the user does with /plan, /mode plan or Shift+Tab. test_tools.c test_plan
5.17 Skill ✅ (M13) skills.c skill_tool; agent.c run_skill_fork {skill, args}; a forked skill as a sub-agent. §13. test_skills.c
5.18 ToolSearch, deferred tools ✅ (M13) agent.c agent_tools, run_tool_search, is_deferred deferredTools (by default ProcessList, PowerShell, LSP, ScheduleWakeup, Service, NotebookEdit, WebSearch, AskUserQuestion, EnterWorktree, ExitWorktree); the grammar accepts them all, so the prompt never changes; a backend offered what was loaded. test_skills.c test_tool_search, test_backend_tools
5.19 Registry, tools enabled per settings or agent ✅ agent.c tool_allowed, tool_offered, agent_tools, is_deferred; permissions.c oklm_perms_tool_denied Deferred tools and per-agent tool lists exist (rows 116, 194); a tool a deny rule or --disallowedTools refuses whatever its arguments is left out of the prompt, the deferred list, ToolSearch and the grammar (the run-time refusal stays).

§6 Permissions and sandbox

§ Feature Status Evidence Notes
6.1 Modes ✅ permissions.h:66-71; permissions.c:759-817 test_permissions.c test_modes
6.1 Shift+Tab cycling ✅ (M4) line_edit.c (OKLM_LINE_MODE); permissions.c oklm_perms_next_mode; tools.c oklm_tool_ctx_cycle_mode At the prompt and while the agent works. test_line_edit.c, test_permissions.c test_next_mode
6.1 Bypass mode ⚠️ permissions.c oklm_perms_set_mode; oklm.c view_mode On purpose (agent-design.md decision 4, ADR-0010): the banner, --dangerously-skip-permissions and the policy switch exist, and bypass needs the sandbox.
6.2 Rule syntax, MCP prefixes ✅ permissions.c:261-326, 645-655 test_permissions.c test_other_rules
6.2 Precedence ✅ permissions.c:1744-1751 test_permissions.c test_precedence
6.2 Compound commands ✅ util.c:139; permissions.c:1638-1715 test_permissions.c test_split, test_bash
6.2 Paths, symbolic links ✅ util.c:296-376; permissions.c:1728-1733 test_permissions.c test_paths, test_path_rules
6.2 Added directories, /add-dir ✅ (M4) permissions.c oklm_perms_add_dir; tools.c oklm_tool_ctx_add_dir; oklm.c /add-dir Settings, and /add-dir for the session (writable in the sandbox too).
6.3 Question shows the call ✅ (M4) tools.h oklm_ask; tools.c edit_preview; util.c text_diff The call in short, a unified diff for Write / Edit / MultiEdit. test_tools.c test_question, test_permissions.c test_diff
6.3 Yes / always / no with feedback ✅ (M4) tools.c always_rules, remember; permissions.c oklm_perms_save_rule "Always" names its rule and saves it to .oklm/settings.local.json; any other text refuses and reaches the model. test_tools.c test_question, test_permissions.c test_save_rule
6.4 Dangerous patterns ✅ (M4) permissions.c builtin_dangers, danger_bash, danger_path, oklm_perms_add_danger Allow turned into ask, in every mode; git's stateless entries and the integrations' included, git's state-dependent ones left to G2. test_permissions.c test_dangers
6.4 Command classifier 🟢 agent.c agent_classify_bash; tools.c oklm_tool_run (ctx->classify); settings commandClassifier With a smallModel set and commandClassifier on, the small model rates each Bash command for injection / exfiltration risk before it runs; a flag makes the call ask even when a rule allows it. Fails open (no small model or an unclear answer leaves the dangerous-pattern list, row 133, to decide). test_tools.c test_command_classifier, test_agent.c test_classify_bash.
6.4 Secrets masked ✅ telemetry.c oklm_mask_secrets / oklm_scan_secrets; agent.c clip; audit.c oklm_audit_scan; tools.c oklm_tool_run; git.c oklm_git_precommit Credential shapes (sk-, ghp_, AKIA, AIza, Bearer, token=, password=...) masked in a tool's output before the model, the transcript and the spill file see it (agent.c clip), and in telemetry, the debug log and /bug; refused at commit time. A tool's output is also scanned (oklm_tool_run): found secrets are registered with the audit log (masked in recorded arguments) and the user is told. test_telemetry.c test_scan, test_tools.c test_secret_scan.
6.4 Untrusted content policy ✅ (M4) agent.c (system prompt) Tool results, files and pages are data, not instructions.
6.5 OS sandbox ⚠️ sandbox.c; proxy.c; adr/0011-sandbox.md Own namespaces and seccomp rather than bubblewrap; the network all, none, or by domain through a proxy (M18); Windows limits only. test_sandbox.c test_network_filter; tools/check_network.sh

§7 Configuration

§ Feature Status Evidence Notes
7.1 Hierarchy ✅ (M6) settings.c oklm_settings_load, merge, oklm_settings_file Managed, command line, environment, local, project, user; arrays joined, objects merged, scalars from the highest; .agent/ files in place of missing OKLM ones. test_settings.c test_precedence, test_fallback
7.2 Keys ✅ (M6) settings.c known; oklm.c settings_apply All the spec's keys checked; model, baseUrl, outputStyle, bashTimeout, maxToolOutputChars, env, sandbox, permissions, memory used; the rest kept for their milestones.
7.3 Environment variables ✅ (M6) settings.c env_keys; oklm.c OKLM_MODEL, OKLM_BASE_URL, OKLM_API_KEY / OPENAI_API_KEY, timeouts, output limit, style; no telemetry exists. MAX_THINKING_TOKENS is not read (the maxReasoningTokens setting caps the reasoning).
7.4 /config, /permissions ✅ (M6) oklm.c config_command, permissions_command; settings.c oklm_settings_edit; permissions.c oklm_perms_save_rule_to, oklm_perms_remove_rule Line commands rather than full-screen editors (M9). test_settings.c test_edit

§8 Project memory

§ Feature Status Evidence Notes
8.1 Memory loading ✅ (M5b) memory.c oklm_memory_load test_memory.c
8.2 Scopes and order ✅ (M5b) memory.c load_all, read_dir AGENTS.md first, OKLM.md, AGENT.md, CLAUDE.md read too (agent-design.md decision 2); duplicates once. test_memory.c test_discovery, test_ancestors
8.3-8.8 Imports, lazy loading, format, commands, tests ✅ (M5b) memory.c expand, oklm_memory_touch, oklm_memory_render, oklm_memory_refresh, oklm_memory_append; agent.c touch_memory, oklm_agent_refresh_memory, oklm_agent_ask_once; oklm.c /init, #, /memory, /context, --no-memory Imports outside the project are refused rather than asked (no trust question yet); re-injection after compaction waits for compaction (M7). test_memory.c, test_agent.c test_memory

§9 System prompt

§ Feature Status Evidence Notes
9.1 Identity, core rules ✅ (M5) prompts/identity.md; prompt.c test_prompt.c
9.2 Tool policy ✅ (M5) prompts/tools.md, agents.md test_prompt.c
9.3 Tool definitions ✅ agent.c:468-489
9.4 Output style ✅ (M5) prompt.c oklm_prompt_style; --output-style, /output-style default, explanatory, learning, custom files. test_prompt.c test_styles
9.5 Environment ✅ (M5) prompts/environment.md; prompt.c put_environment Directory, git or not, platform, OS version, date, model.
9.6, 9.7 Git snapshot, memory ✅ (M5b, G1) git.c oklm_git_snapshot; memory.c oklm_memory_load Both in the prompt (rows 152, 489). test_git.c, test_prompt.c test_full
9.8 Replace or append the prompt ✅ (M5) --system / --system-prompt, --append-system-prompt
9 Skills list, plan notice ✅ prompt.c (skills); agent.c remind (plan mode, as a reminder)
9 Template files, snapshot test ✅ (M5) src/harness/prompts/*.md; prompt.c Template files, checked by a snapshot test (OKLM_UPDATE_SNAPSHOTS=1), as rows 160 to 164. test_prompt.c test_full

§10 Context

§ Feature Status Evidence Notes
10 Token accounting, /context ✅ (M7) compact.c count_text, msg_tokens, agent_context_measured, oklm_agent_context; oklm.c context_command Per message, system, memory, tools; scaled to the model's count of the last prompt. test_compact.c test_accounting
10 Compaction, micro-compaction, warning ✅ (M7) compact.c agent_context_check, micro_compact, agent_compact_now, rolling_summary; prompts/compact.md; oklm.c /compact, context_warning, agent_event Summary by the agent's model (the small model comes with §2.5); the PreCompact hook with §15; a warning line after the turn until the status bar (M9). test_compact.c test_manual, test_rolling, test_long_session
10 /clear ✅ (M7) oklm.c /clear, /reset

§11 Sessions

§ Feature Status Evidence Notes
11 Transcripts ✅ (M8) session.c put_line, agent_session_sync, load; agent.c (sync points) .oklm/sessions/<id>.jsonl (the project's, per the decisions); flushed and synced per line, a line cut short skipped. test_session.c test_round_trip, test_torn_line, test_killed
11 Continue, resume, fork ✅ (M8) session.c oklm_session_restore, branch, answer_dangling; oklm.c --resume, --fork-session, pick_session Titles from the first request (the small model comes with §2.5); -c stays the context's length. test_session.c test_dangling_call, test_clear_fork
11 Checkpoints, rewind ✅ (M8) session.c oklm_session_checkpoint, oklm_session_rewind; tools.c (Write, edit_store); oklm.c /rewind, Esc Esc Commands' effects not tracked, said in the question. test_session.c test_rewind
11 Cleanup ✅ (M8) session.c oklm_session_cleanup; jobs.c:50, 400-418 cleanupPeriodDays (0: no transcripts); the jobs keep their own 30 days. test_session.c test_list_cleanup
11 Export ✅ (M8) session.c oklm_session_markdown; oklm.c /export File, clipboard program, or conversation-<id>.md. test_session.c test_markdown

§12 Sub-agents

§ Feature Status Evidence Notes
12 Task tool ✅ (M12) agent.c agent_tool_json, run_subagent Agent (Task read as it): description, prompt, subagent_type, model (accepted, not acted on), run_in_background.
12 Own context, final message only ✅ agent.c:2363-2470 The foreground one shares the KV cache. test_agent.c test_subagent
12 Own prompt, fewer tools ✅ (M12) agent.c agent_tools, tool_allowed, subagent_params The type's instructions after the sub-agent prompt; its tools offered and enforced. test_subagents.c
12 Definitions, built-in types ✅ (M12) agents.c oklm_agent_defs_load; prompt.c (types listed) general-purpose, Explore, Plan; .oklm/agents/, the user's. test_subagents.c test_defs, test_types
12 Background, parent told ✅ agent.c:1945-2095 test_agent.c test_background, test_background_limits
12 Parallel foreground calls, SendMessage, worktrees ✅ / ❌ (M12) agent.c agent_group, run_agents_parallel, run_send_message, keep_agent Two to eight at once on their own contexts (or, through a backend, on copies of it: oklm_agent_backend.clone, a connection each with --url); SendMessage for the sixteen last; worktrees with the git spec (G9). test_subagents.c test_parallel_explore
12 Depth 1, no questions in background ✅ (M12) agent.c max_depth agents.maxDepth. test_subagents.c test_depth
12 /agents, SubagentStop ✅ (M12, M11) oklm.c c_agents; agent.c stop_hooks Creation written by the model.
12 Read-only agents in plan mode ✅ (M12) agent.c def_reads_only, subagent_decide Beyond the spec: Explore and Plan run in plan mode. test_subagents.c test_plan_mode

§13 Skills

§ Feature Status Evidence Notes
13.1 Skills exist ✅ skills.c; agent-tools.md Same SKILL.md format; skills and commands one format (commands spec §1.7).
13.2 Front matter ✅ (M13) skills.c skill_parse; util.c fm_parse Every key of the spec, context/agent too; YAML blocks, lists, quotes. test_skills.c test_yaml
13.3 Places, precedence ✅ (M13) skills.c skill_dirs .oklm/skills, .agent/skills, the user's, built-in; plugins with §17. test_skills.c test_discovery
13.3 Validation, warnings, reload ✅ (M13) skills.c skill_parse, oklm_tool_ctx_skills_changed; oklm.c repl_submit Errors leave a skill out, warnings told at start and in /skills (and in /doctor, C9). test_skills.c test_validation, test_reload
13.4 Three levels, a budget ✅ (M13) prompt.c oklm_prompt_skills_listed skills.listBudget (2000 tokens); past it, ToolSearch. test_skills.c test_prompt_budget
13.5 Model and user invocation, allowed tools, compaction, sub-agents ✅ (M13) permissions.c OKLM_SRC_SKILL; agent.c track_skill, preload_skills; compact.c Allowed until the request ends; the skills loaded named after a summary; skills: preloaded. test_skills.c test_allowed_scope, test_compaction_note, test_subagent_skills
13.6 /skills, skill-creator, skills validate ✅ (M13) oklm.c c_skills, agent_skills_cli; skills.c builtin_skills The list is text (the commands spec's toggling panel waits for C9).
13.7 Trust, scripts through Bash ✅ oklm.c trust_question Asked before a folder's files are read; -p runs without asking, as the other agents do.
13.8, 13.9 Tests, E2E ✅ (M13) test_skills.c; tools/check_skills_e2e.sh Qwen3-4B loads the zorblax skill and runs its script; twenty skills under the budget.

§14 Slash commands

§ Feature Status Evidence Notes
14.1 Built-ins ✅ (M10, C1 to C10) oklm.c repl_defs; commands.c One registry of about forty commands with aliases; see the Commands section. test_commands.c
14.2 Custom commands ✅ (C3) tools.c scan_commands; commands.c oklm_cmds_expand .oklm/commands/*.md with front matter, $ARGUMENTS, ! and @ (row 562); a command's model and context: fork are read but not acted on. test_commands.c test_expand, test_precedence

§15 Hooks

§ Feature Status Evidence Notes
15 Events ✅ (M11) tools.c oklm_tool_run; agent.c oklm_agent_send, stop_hooks; compact.c; oklm.c session_hooks, view_notify All nine. test_hooks.c
15 Settings, matchers ✅ (M11) hooks.c oklm_hooks_new, oklm_hook_matches Glob patterns with *, | alternation, and full regular expressions with the re: prefix (oklm_regex).
15 Input, exit codes, JSON answers ✅ (M11) hooks.c run_one, fold_json suppressOutput read, nothing to suppress (no verbose output of hooks yet).
15 At once, each once, timeouts ✅ (M11) hooks.c oklm_hooks_run
15 /hooks, change warning ✅ (M11) oklm.c c_hooks The session keeps its hooks until /hooks reload.

§16 MCP

§ Feature Status Evidence Notes
16.1 JSON-RPC, MCP ✅ (M15) jsonrpc.c; mcp.c Hand-written (no C SDK); protocol 2025-06-18.
16.2 Scopes, format, variables, CLI, trust ✅ (M15) oklm.c mcp_setup, mcp_accept, agent_mcp_cli; mcp.c oklm_mcp_add_servers, oklm_mcp_expand Local, project, user settings and .mcp.json, --mcp-config, --strict-mcp-config; managed allow and deny lists; reset-project-choices not done. tools/check_mcp.sh
16.3 stdio, lifecycle, parallel start, reconnect, list_changed ✅ (M15) mcp.c server_spawn, server_handshake, oklm_mcp_poll test_mcp.c test_server
16.3 Streamable HTTP ✅ (M15) mcp.c http_rpc; client.c oklm_client_set_headers, oklm_client_header JSON and event answers, session id, headers, timeouts; no GET stream, no session re-opened on 404. test_mcp.c test_http
16.3 Legacy SSE ✅ (M15) mcp.c sse_reader, sse_event, sse_rpc; client.c oklm_client_stream_get The server's requests on the stream are not answered back. test_mcp.c test_sse
16.4 Tools: names, pipeline, results, cap, deferral ✅ (M15) mcp.c list_tools, result_text, oklm_mcp_sync_tools; permissions.c tool_matches; agent.c in_list A stdio call interrupted sends notifications/cancelled; HTTP calls wait for their limit. test_mcp.c, tools/check_mcp.sh
16.5 Resources ✅ (M15) mcp.c run_ref, oklm_mcp_read_resource; oklm.c mention_files ListMcpResources, ReadMcpResource, @server:uri mentions; no @ completion of them, no subscriptions. tools/check_mcp.sh
16.6 Prompts as commands ✅ (M15) mcp.c list_prompts, oklm_mcp_prompt; oklm.c mcp_prompt_line Arguments in order; not in the / menu. test_mcp.c, tools/check_mcp.sh
16.7 OAuth ✅ (M15) oauth.c oklm_oauth_login, oklm_oauth_token; mcp.c auth_lines, srv_request, oklm_mcp_login; oklm.c c_mcp, agent_mcp_cli Discovery (RFC 9728 resource metadata from the 401's header or the well-known places, RFC 8414 / OpenID metadata, the older default endpoints), dynamic registration or oauth.clientId, PKCE S256 with a random state, the browser and a callback on 127.0.0.1, the resource indicator, endpoints on https unless local; tokens in mcp-credentials.json beside the user's settings (0600, per server name and URL), refreshed when expired or after a 401 (the request sent again once); a 401 without a token: the state "needs auth". No system keychain (a dependency, to decide), no encryption of the file. test_mcp.c test_oauth (a fake protected server and authorization server, the browser simulated)
16.8 Roots, elicitation, sampling 🟡 (M15) mcp.c incoming Roots answered, elicitation declined, sampling not offered.
16.9 /mcp ✅ (M15) oklm.c c_mcp "needs auth", /mcp login NAME, /mcp logout NAME (the clear-auth option); `oklm agent mcp login
16.10 mcp serve ❌ Optional: no oklm agent mcp serve exposing the agent's tools.
16.12 Fake server tests; official server E2E ✅ (M15) test_mcp.c (--serve); tools/check_mcp.sh; tools/check_mcp_official.sh @modelcontextprotocol/server-filesystem 2.1.0 through npx: listed and read under a fixture, and by Qwen3-4B on its own when its tools are shown. Its 14 tools (about 3300 tokens) fit the default mcp.deferAboveTokens, a quarter of the context window; deferred, Qwen3-4B read the file with Read in 9 runs of 9 and never searched for them.

§17, §18 Plugins, output styles

§ Feature Status Evidence Notes
17 Plugins: manifest, commands, skills, agents, hooks, MCP servers, scopes, enabledPlugins ✅ (M19) plugins.c; skills.c (NAME: namespace); agents.c oklm_agent_defs_add_dir; hooks.c oklm_hooks_add_json; oklm.c session_plugins, mcp_setup .oklm-plugin/plugin.json or .claude-plugin/plugin.json; ${OKLM_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_ROOT} in hook commands. tools/check_plugins.sh
17 Install, remove, enable, disable, marketplaces, /plugin ✅ (M19) oklm.c agent_plugin_cli, c_plugin From a directory, a git repository or NAME@MARKETPLACE; no signature check, no update command; a change takes effect in the next session.
18 Output styles ✅ (M5) prompt.c; oklm.c /output-style

§19 Terminal UI

§ Feature Status Evidence Notes
19 Markdown while streaming ✅ (M9) term_md.c oklm_md_feed; oklm.c view_split Tables aligned at their end, code colored by language, escape sequences dropped; a pipe gets the raw text. test_term.c
19 Compact tool calls ✅ (M9) term_ui.c oklm_term_tool; oklm.c agent_tool, /verbose ● Tool(subject) / ⎿ summary, diffs, task list; Ctrl-R or /verbose whole. test_term.c test_tools
19 Folded reasoning ✅ view_split, view_toggle Ctrl-O folds and unfolds in place. test_think.c; manual
19 Spinner ✅ (M9) term_ui.c oklm_term_spinner; oklm.c view_spin_main Verb or the task in progress, time, tokens, how to interrupt; reasoning's words. test_term.c test_spinner
19 Task list panel ✅ (M9) term_ui.c (TodoWrite); tui.c oklm_tui_todos, draw_tasks, oklm_tui_tasks_toggle; oklm.c tui_refresh_tasks, view_tasks Shown with ☐ ◼ ☒ at each change, its task in the spinner; in /tui a strip kept on screen above the transcript (16 rows or more, Ctrl-T hides or shows it), following each TodoWrite, the task in progress by its activeForm, completed beyond three folded, scrolled to keep the task in progress in sight; Ctrl-T prints it in the line-mode UI. test_tui.c test_tasks_strip, test_tasks_scroll, test_tasks_live; check_commands.sh
19 Input editor ✅ (M9) line_edit.c; oklm.c view_draw_line, view_complete, bang_command, mention_files Several lines, Ctrl-R, bracketed pastes and placeholders, @ completed and read, !, #; the / menu is M10's; no vim mode, no images pasted. test_line_edit.c
19 Keys ✅ (M9, P3) oklm.c view_key, view_edit_line, background_now Esc, Esc Esc, Shift+Tab, Ctrl-C, Ctrl-D, Ctrl-L, Ctrl-O, Ctrl-R, Ctrl-T (the task list) and Ctrl-B (the running command to the background); vim mode is left (roadmap Later). test_line_edit.c test_keys_view
19 Status line, notifications, themes ✅ (M9) term_ui.c oklm_status_*, oklm_git_branch; term_md.c themes; oklm.c status_line, view_notify statusLine.command with the session JSON, else built in; bell, OSC 9 or a desktop notification (a PowerShell toast on Windows, untested there); dark, light, colorblind, NO_COLOR. test_term.c, test_hooks.c test_toast_command
19 Welcome, trust question ✅ (M9) oklm.c welcome, trust_question; term_ui.c oklm_trust_* Asked on the first interactive run in a folder, kept in trusted-folders.json. test_term.c test_trust

§20 Headless use

§ Feature Status Evidence Notes
20 -p ✅ cmd_agent
20 Output and input formats ✅ (M14) headless.c; oklm.c headless_main text, json, stream-json; stream-json input for several requests. test_headless.c
20 Flags ✅ (M14) cmd_agent The spec's names read as OKLM's (--model, --allowedTools, --disallowedTools, --permission-mode, --system-prompt, --add-dir, --verbose); --mcp-config and --strict-mcp-config with M15.
20 Exit codes ✅ (M14) oklm_headless_result 0, 1 for a request in error (the turn limit included), 2 for usage.
20 Standard input into -p ✅ (M14) oklm.c read_piped_stdin Piped text first, -p - alone; a silent pipe left open does not hang.
20 Library API ✅ (M14) tools.h oklm_tool_ctx_add_tool; hooks.h oklm_hooks_add_callback Custom tools, hooks as functions, the ask callback, cancel, events; a callback API, not an iterator (C). test_headless.c

§21 to §23 Git, background work, diagnostics

§ Feature Status Evidence Notes
21 Git workflows ✅ (G1 to G11) git.c; prompts/git.md; skills.c commit, pr, bisect, git-history See the Git section; what is left is there (rows 491 to 520).
22 Background commands and agents ✅ jobs.c; agent.c:1945-2095; adr/0012-jobs.md test_jobs.c
22 Monitor, loops ✅ (P2, P5, C8) tools.c t_monitor, t_schedule_wakeup; events.c; oklm.c c_loop, c_schedule Monitor, ScheduleWakeup, /loop, /schedule. test_events.c
23 Tokens and time, /cost, /status ✅ (C9) oklm.c c_usage, c_status tools/check_commands.sh
23 Debug log ✅ (M17) telemetry.c oklm_telemetry_set_debug, oklm_telemetry_event; oklm.c debug_log_on, debug_command --debug, OKLM_DEBUG, /debug; $XDG_STATE_HOME/oklm/logs. test_telemetry.c; tools/check_diagnostics.sh
23 Price table, cost ✅ (M17) telemetry.c oklm_prices_lookup; headless.c oklm_headless_set_prices; oklm.c c_usage /usage, total_cost_usd. tools/check_diagnostics.sh
23 OpenTelemetry export ✅ (M17) telemetry.c oklm_telemetry_flush, export_main OTLP/HTTP JSON logs and metrics, off unless asked; no gRPC, no traces. test_telemetry.c test_export; tools/check_diagnostics.sh
23 /bug, /feedback ✅ (M17) oklm.c bug_bundle A local bundle, secrets masked; no drafts queue (no feedback tool). tools/check_diagnostics.sh
23 Audit log and viewer ✅ audit.c; cmd_audit test_permissions.c test_audit
23 /doctor ✅ (C9) oklm.c c_doctor, doctor_check Fixes: keys of the wrong type, orphans. tools/check_commands.sh

§24 Security checklist

Item Status Evidence, notes
Untrusted content policy ✅ (M4) prompts/tools.md: tool results, files and web pages are data, not instructions (row 136).
Paths and symbolic links ✅ util.c:296-376; test_permissions.c test_path_rules
Compound commands, fuzzed ✅ Unit tests and fuzz/fuzz_shsplit.c (with fuzz_toolcalls.c).
Secrets masked 🟢 telemetry.c oklm_mask_secrets / oklm_scan_secrets for the debug log, /bug and telemetry, and a tool's output before the model and the transcript (agent.c clip); a tool's output is scanned in oklm_tool_run, found secrets registered with the audit log (oklm_audit_scan, masked in recorded arguments) and the user told.
Trust before project settings, hooks, MCP ✅ (M9) oklm.c trust_question before any of the folder's files is read (its settings, the worktree --worktree makes with its WorktreeCreate hook), and an approval per MCP server; -p skips it by design (row 213). tools/check_commands.sh (refused on a terminal: the hook does not run)
WebFetch per domain ✅ WebFetch domain rules (M16), shared with the sandbox's proxy (M18).
Managed lockdown 🟡 permissions.c disableBypassPermissionsMode, allowManagedPermissionRulesOnly and the managed settings scope; no managed-only switch for hooks, MCP servers or plugins (left out on purpose, roadmap "Next").

§25 Tests

§ Feature Status Evidence Notes
25 Unit tests ✅ tests/harness/ The tool-call parser fuzzed (fuzz_toolcalls) and the command splitter (fuzz_shsplit, 7.4 million inputs: parts non-empty, the same on a second split, an unparsable line kept whole).
25 Mock-model integration ✅ (M1, M20) agent_mock.c; oklm agent --mock Fixture-driven mock backend, and the evals of tests/evals. test_agent.c test_mock
25 Snapshots, end to end, evaluation ✅ (M20) test_prompt.c (the system prompt's snapshot), test_term.c (frames); tests/evals/; tools/eval_agent.sh, make eval Seventeen tasks in temporary directories and repositories (the git evals 05, 11 to 15; the process evals 10, 16, 17), each with a checker; the report gives the pass rate, turns, tokens and seconds a task (agent-loop.md). Qwen3-8B, the default, passes 13 of 17 (2026-11-07; Qwen3-4B 7 of the first 12). CI (.gitea/workflows/ci.yml) runs the unit and mock tests with gcc and clang, under both sanitizers; the evals stay behind make eval, since a run needs the model and a GPU.

§26 Milestones against what exists

M State
M0 Done: this file and agent-design.md.
M1 ✅ Backends (in-process, HTTP, mock fixtures), stream events with usage and stop reasons, cancel from Esc / Ctrl-C (generation, commands, pending calls); reasoning kept out of the history sent back.
M2 ✅ Lenient parser (fuzzed), schema validation, fake results dropped, message metadata, a result per call, reminders, parallel reads, loop detection, steering, Read / Glob / Grep in full; "where is X defined?" answered by Qwen3-4B.
M3 ✅ Write / Edit with read-before-write checks, line ends kept, snippets; MultiEdit; a persistent shell, head and tail output, escape sequences stripped, pagers and editors neutralized; "create fizzbuzz, make test pass" done by Qwen3-4B.
M4 ✅ Modes with Shift+Tab, rules, compound commands, plan mode, the dangerous-pattern list, questions with diffs, rules saved, feedback, /add-dir, the untrusted-content policy; later follow-ups now done (roadmap "Done"): the command classifier, secrets found in output, broader "always" prefix rules (OKLM_ANSWER_ALWAYS_PREFIX, Bash(cmd:*)), read-only pipeline filters, /add-dir --remember, memory imports outside the project behind the trust question (mem_trust, oklm_trust_add), and the bypass mode without the sandbox behind a flag and a louder banner (--dangerously-skip-permissions, oklm_perms_allow_unsafe_bypass, ADR-0010).
M5 ✅ The prompt assembled from template files in a stable order (snapshot test), environment, output styles, appended or replaced text; TodoWrite with activeForm and one task in progress; reminders for the mode, changed files and a stale task list. The git snapshot waits for G1, the memory files for M5b.
M5b ✅ The memory files by scope (managed, user, project from the repository's root, local, sub-directories lazily), imports with caps and warnings, the prompt's section, changes reloaded, /init, #, /memory, /context, the memory settings; "always use pnpm" followed by Qwen3-4B. Left: the trust question for imports outside the project, /doctor. Re-injection after compaction came with M7.
M6 ✅ Settings merged by priority with their sources (merge-precedence tests), the spec's keys checked, environment variables, edits that keep a file's other content, /config and /permissions.
M7 ✅ Token accounting per part scaled to the model's count, /context with a bar, old tool results cleared, summaries by the model (after the conversation, or from a transcript in parts), the user's messages verbatim, task list, edited files and instructions kept, /compact [focus], /clear, the 70% warning, autoCompact / compactThreshold / contextWindow; a 440-turn synthetic session within a small window without losing its task.
M8 ✅ Transcripts as a tree of messages written as they go, --resume / --fork-session, the files kept before each change and /rewind (Esc Esc) of the conversation, the files or both, /export, cleanupPeriodDays; a process killed mid-turn resumed and its task finished, files restored by rewind.
M9 ✅ Markdown rendered as it streams, tool calls compactly with diffs, the spinner, the status line (built in or a command), several-line input with Ctrl-R, pastes, @ and !, notifications, themes and NO_COLOR, the welcome box and the trust question; frames tested, checked by hand on a pseudo-terminal and with Qwen3-4B.
M10 ✅ Slash commands, the commands spec's C1–C3: one registry (built-ins, skills, command files), the parser (stacking, escapes, namespaces, unknown names with suggestions), precedence with shadowed names kept, queued or immediate while the agent works, -p "/cmd", the / menu with argument completion, a picker reused by four commands, prompt commands expanded (!, @, placeholders) under their allowed tools, skillOverrides, /skills, /reload-skills.
M11 ✅ Hooks: the nine events, matchers, the event on standard input, exit codes and JSON answers (block, approve, new arguments, context, stop), run at once and once each with timeouts, /hooks with the change warning; a hook refusing edits of *.lock and a formatter after writes.
M12 ✅ Sub-agents: types (general-purpose, Explore, Plan, the project's and the user's definitions), their tools and instructions, several at once on their own contexts, SendMessage, a configurable depth, /agents; two Explore agents return summaries while the caller's context keeps only them. Worktrees with the git spec.
M13 ✅ Skills in full: every header key in the YAML skills use, checked (errors leave a skill out, warnings told), the project's, .agent's, the user's and built-in skills (skill-creator), a prompt budget with the rest found by ToolSearch, {skill, args}, allowed tools until the request ends, forked skills as sub-agents, preloaded skills, the loaded ones named after a summary, changes on disk noticed, /skills NAME, oklm agent skills validate; deferred tools loaded by ToolSearch. Qwen3-4B loads the zorblax skill by itself and runs its script.
M14 ✅ Headless: `--output-format text
M15 ✅ MCP: scopes, trust, stdio, Streamable HTTP and legacy SSE, tools, resources, prompts, OAuth, /mcp, oklm agent mcp, the official filesystem server end to end.
M16 ✅ WebFetch, WebSearch through SearXNG, NotebookEdit, AskUserQuestion.
M17 ✅ The debug log, a price table and costs, the OpenTelemetry export, /bug and /feedback.
M18 ✅ Linux, 🟡 Windows.
M19 ✅ Plugins: commands, skills, agents, hooks and MCP servers bundled, installed from a directory, a repository or a marketplace.
M20 ✅ The eval harness (make eval, tests/evals/, its report) and user-guide.md, extending.md.

§27 Local models

Item Status Notes
Small tool set 🟡 27 built-in tools, ten deferred by default (ProcessList, PowerShell, LSP, ScheduleWakeup, Service, NotebookEdit, WebSearch, AskUserQuestion, EnterWorktree, ExitWorktree); more than the spec's seven stay loaded.
Worked examples in the prompt ✅ (M2) agent.c default system prompt: finding a definition with Grep
Instructional errors ✅ tools.c: schema errors with the schema, "No matches" with a hint, a missing file's directory listed, a headless refusal naming the parts no rule covers, a TodoWrite with several tasks in progress kept with the first.
Lower temperature for calls ✅ Greedy by default; grammar on calls.
Write fallback measured, lower compaction threshold 🟡 compactThreshold can be set but is not lowered for small models; the evals do not measure Edit against a whole-file Write.

Tests already covering what is present

test_permissions.c (compound commands, paths, precedence, modes, rules, settings, audit), test_tools.c (files, search, Bash, questions, plan mode, skills), test_jobs.c (journal, restart, harness death, retention, tools), test_sandbox.c, test_think.c, test_line_edit.c, test_agent.c (calls, order, job notes, sub-agents, background, refusals, turn limit). Not covered by a test: the prefix cache reuse, -p, the terminal view, and the oklm permissions / oklm audit commands.

Processes & Services

Audit of process_spec.md (its P0), 2026-11-02, the same legend. The job manager already does the core of §2.2 and §2.5 (src/harness/jobs.c, adr/0012-jobs.md): jobs run in a process group or a kill-on-close Job Object, write a log and a journal with their start times, are stopped at close and die with the harness, and are re-attached or marked interrupted when the same session is opened again. What follows §2.5 (readiness, ports, events, Monitor, language servers, MCP, hooks, services, integrations) is missing or partial.

§ Feature Status Evidence Notes
0 Nothing outlives the session by accident ✅ (P4) jobs.c oklm_jobs_close, find_orphans Detached and kept-alive jobs outlive it on purpose; what a crash leaves is reaped at the next start.
0 Event-driven waiting ✅ (P2, P5) probe.c; events.c WaitFor, Monitor, events.
0 Logs on disk ✅ jobs.c:1457-1463, 1041-1046; tools.c:2212
0 Integrations as skills ✅ skills.c searchable_skills (docker, dev-server, database, playwright, kubernetes, android, vms, cloud, tunnels, git-history) Built-in integration skills, found by the skill search; no iOS skill (row 427). tools/check_integrations.sh
2.1 Ids, kinds, labels ✅ (P1) jobs.h oklm_job_spec, oklm_job_kind Integer ids shown as job 3 (decided in process-design.md); six kinds; labels. test_jobs.c test_spec
2.1 Command, directory, environment ✅ (P1) jobs.c spawn Its own directory; markers and neutralized pagers in the environment.
2.1 Process and group ids, Job Object ✅ jobs.c:77-114, 1121
2.1 Owner, status, times, exit and signal ✅ (P1) jobs.c note_end, oklm_jobs_info Owner, start and end times, signal in the info and the journal; readiness is a wait (WaitFor), not a state.
2.1 Ports, readiness, restart, ring, readers ✅ (P1, P2) jobs.c oklm_jobs_read, note_end; probe.c Readers kept by the manager; restart on failure with backoff; ports found per job; no ring buffer (the log is read where the reader is). test_jobs.c test_readers, test_restart_policy
2.1 Resources ✅ sandbox.c (RLIMIT_CPU, AS, FSIZE, NOFILE, NPROC); process.c (Job Object limits on Windows); jobs.c limiter_for, oklm_jobs_limits_available; services.c resources Shared limits, and per job a memory and CPU limit in a cgroup v2 of its own on Linux (systemd's user manager; memLimit, cpuLimit of a service); on Windows in the job's Job Object (job memory, a hard CPU rate; job_cpu_rate, job_memory_limit), cross-compiled, untested on Windows. test_jobs.c test_limits, test_job_object_limits, test_services.c test_resources
2.2 Own group or session; Job Object; standard input closed ✅ jobs.c:1031-1198; process.c:306-361, 478-486 Detached Windows jobs break away from the Job Object (jobs.c:1155).
2.2 Output merged with timestamps ⚠️ jobs.c spawn Merged; no timestamps on purpose: the log stays what the program wrote and offsets stay bytes (the journal has the times).
2.2 OKLM_SESSION_ID, OKLM_PROCESS_ID ✅ (P1) jobs.c spawn With the git specification's editor and pager variables; inherited descriptors closed. test_jobs.c test_spec
2.2 Concurrency limit ✅ (P1) jobs.c oklm_jobs_start_spec, oklm_jobs_running 20 (processes.maxConcurrent); the error lists what runs.
2.3 ANSI stripped, rotation ✅ (P1) jobs.c oklm_jobs_read, rotate Copy and truncate past 32 MiB; rotated journalled. test_jobs.c test_rotation
2.3 Reading with reader, filter, tail, cap ✅ (P1, P3) jobs.c oklm_jobs_read; tools.c t_process_output The model's reader, the user's in /tasks output.
2.3 Retention ✅ (P1) jobs.c retire_old processes.logRetentionDays.
2.4 Readiness probes ✅ (P2) probe.c port, http, log, command, delay, all, any; timeout, fail fast, last 30 lines. test_probe.c
2.5 Stop: TERM, grace, KILL ✅ (P1) jobs.c oklm_jobs_stop 5 s, a setting and per job, the group confirmed gone; on Windows CTRL_BREAK to the group, the grace, then termination (verified on a real Windows machine is "Blocked" in the roadmap). test_jobs.c test_stopping
2.5 Stop hooks per integration ✅ (P1) jobs.c oklm_jobs_stop A stop command per job; the integrations give theirs (P9).
2.5 Session end ✅ (P1, P4) jobs.c oklm_jobs_close, oklm_jobs_keep, keep_mark; sandbox.c sb_pass_term; oklm.c leave_ok Reverse order, kept-alive jobs left running and said; the exit question on the terminal with a "keep" answer; a kept job is marked so the TERM of its harness's end (PR_SET_PDEATHSIG) does not stop it (keep_alive, processes.keepOnExit and --keep-services jobs too, which that TERM used to end). test_jobs.c test_keep_at_exit
2.5 Registry with process start times ✅ jobs.c:222-327 .oklm/jobs/<session>.jsonl.
2.5 Orphan reaper ✅ (P4) jobs.c find_orphans, group_lives, oklm_jobs_reap Every other session's journal at open; groups checked on Linux (leader dead or alive; a leader id held by a process of another start time is a reused id, no orphan), the leader elsewhere; asked at start or processes.autoReapOrphans; jobs kept at exit listed as such. test_process.c test_orphans, test_jobs.c test_reused_pid, test_keep_at_exit
2.5 Docker label ✅ oklm.c containers_cleanup; skills.c docker Containers labelled oklm.session=$OKLM_SESSION_ID (or compose project oklm-ID) are stopped at the session's end, volumes kept; the label is the skill's convention, not added to docker commands by the harness. tools/check_integrations.sh
2.6 Ports: free check, detection, loopback ✅ (P2) / 🟡 probe.c oklm_port_holder, oklm_job_ports, port_rows_holder The holder named on Linux; on Windows from GetExtendedTcpTable (cross-compiled, untested on Windows) and on macOS from libproc (never compiled); elsewhere only whether a port answers. A held port named before waiting. A job's ports on Linux only. test_probe.c test_ports, test_port_rows
2.7 Re-attach on resume; died while away shown with its code ✅ oklm.c --resume; jobs.c alive A resumed session reopens its jobs: running ones re-attach, those that died show their code. test_jobs.c test_restart
3 Bash background ✅ (P3) tools.c bash_job Id and log path at once; detach declared.
3 Backgrounding on timeout ✅ (P3) process.c proc_run_ex; jobs.c oklm_jobs_adopt Decided; sleep stopped; POSIX (Windows stops it). test_process.c test_auto_background
3 WaitFor ✅ (P2) tools.c t_wait_for Command probes only under an allow rule. test_probe.c test_tool
3 Ctrl+B, PowerShell, ProcessList ✅ (P3) oklm.c view_key; tools.c t_powershell, t_process_list PowerShell and ProcessList deferred. test_process.c
3 Monitor ✅ (P5) tools.c t_monitor; events.c Bash's rules for its command; its own job or attached (attaching allowed under a bare Bash deny, refused with Monitor's, the tool offered accordingly). test_events.c test_monitor_denied
3 LSP ✅ (P6) tools.c t_lsp; lsp.c Deferred. test_lsp.c
3 Service ✅ (P8) tools.c t_service; services.c; oklm.c c_services The Service tool, services.json with dependsOn and readiness, processes.autostartServices, /services. test_services.c test_load, test_run; tools/check_services.sh
3 ProcessOutput, ProcessStop ✅ (P3) tools.c t_process_output, t_process_stop BashOutput / KillShell read as them; JobOutput / JobKill kept, not offered.
4.1 Monitor ✅ (P5) events.c oklm_events_monitor filter, batch, rate, stop line, attach.
4.2 Events: job ended, background agent finished ✅ agent.c tell_jobs, tell_agents, tell_events At each turn's start, to the user's agent.
4.2 Other sources, coalescing, idle wake, wake cap ✅ (P5) / 🟡 events.c; oklm.c wake_wanted, wake_agent, headless_events Monitors and jobs; readiness, LSP and MCP events with their milestones. tools/check_events.sh
4.3 Scheduled wakeups ✅ (C8) events.c oklm_events_schedule; tools.c t_schedule_wakeup Not counted against the hour's cap; dropped at session end (not persisted). test_events.c test_wakeups, tools/check_events.sh
5 Language servers ✅ (P6) lsp.c; jsonrpc.c; jobs.c piped jobs Lazy start, sync, diagnostics after edits by version, the LSP tool; POSIX (piped jobs). test_lsp.c
6 MCP server processes ✅ (M15) mcp.c server_spawn Jobs of kind mcp (piped, outside the sandbox); a crash reconnects with a backoff; no ProcessExit hook yet (P7).
7 Background sub-agents listed as processes 🟡 (P7) agent.c oklm_agent_background_list; oklm.c c_tasks /tasks lists them (kind agent, state, time); not in ProcessList; no token use or last tool (reading a running sub-agent's messages would race). test_agent.c test_background
7 Processes owned by a sub-agent ✅ agent.c start_background, end_owned_jobs; jobs.c oklm_jobs_end_owner; process.c proc_fork A background sub-agent owns its jobs (agent N, nested agent N/agent M): stopped when it ends, Bash keep_alive hands one to the session, its report lists both. Every child is forked by one thread that lives as long as the harness, so PR_SET_PDEATHSIG (per thread) follows the process. test_jobs.c test_owner, test_thread_end; test_agent.c test_background_jobs
7 Concurrency limit, stop at exit ✅ agent.c:209-229, 1946-1962 test_agent.c test_background_limits
8 Hooks for processes ✅ (P7) hooks.h OKLM_HOOK_PROCESS_START, OKLM_HOOK_PROCESS_EXIT, OKLM_HOOK_MONITOR_EVENT, OKLM_HOOK_SERVICE_READY; events.c oklm_events_take_changes; services.c oklm_services_take_ready, oklm_services_ready_fields; oklm.c process_hooks, monitor_hook_blocks; agent.c tell_events ProcessStart, ProcessExit, MonitorEvent (which can block), and ServiceReady (a declared service passed its readiness probe, once per ready spell: name, job id, pid, ports, probe; matched on the name; listed by /hooks). test_hooks.c test_expansion, test_services.c test_ready; tools/check_events.sh
9 services.json, dependsOn order, readiness, monitors, /services, /init proposal, trust before autostart ✅ (P8) services.c; tools.c t_service; oklm.c c_services, c_init test_services.c; tools/check_services.sh (the spec's mock-model E2E)
10.1, 10.6-10.8 Docker / Podman, dev servers, databases, browsers (wave 1) ✅ (P9) / 🟡 skills.c docker, dev-server, database, playwright; permissions.c builtin_dangers; oklm.c containers_cleanup, doctor_check; tools.c bash_job (reuse) Skills with the recipes, OKLM_SESSION_ID for labels, the session's containers stopped at its end, image deletion and the host's network asking, /doctor on a silent daemon, a running command reused; a real-daemon check (tools/check_docker.sh, skipped when no daemon answers) passing against Docker 28.5.2 (2026-11-08); not tried against a real database or real browsers tonight; no SQL danger rules (the skill asks). tools/check_integrations.sh (a fake docker), test_permissions.c, test_jobs.c
10.2, 10.3 Kubernetes context safety, Android device safety, their skills ✅ (P10) / 🟡 devices.c oklm_cluster_danger, oklm_device_danger; tools.c tool_run; skills.c kubernetes, android test_devices.c; tools/check_integrations.sh (a fake kubectl); tools/check_emulator.sh: the checklist on a real emulator (Android 36.1, 14 checks: detection, start, boot, Monitor on logcat with its lines told, an activity, a screenshot, the UI tree, input, an APK built and installed with -r, pm clear, uninstall, adb without -s refused, emu kill).
10.5, 10.9, 10.10 VMs, cloud CLIs read-only by default, tunnels saying what they expose ✅ (P11) / 🟡 devices.c oklm_cloud_danger, oklm_tunnel_danger; skills.c vms, cloud, tunnels test_devices.c test_cloud_tunnels; no identity reminder, no credential redaction, a tunnel's URL not parsed for the user.
10.4 iOS Simulator ❌ Out of scope (macOS only).
11 Resource guardrails, the target in the question, cloud.readOnly, kubernetes.allowedContexts, OKLM_DISABLE_BACKGROUND_TASKS, docs/processes.md ✅ (P12) / 🟡 tools.c resource_danger, t_bash; devices.c; docs/processes.md A second VM or emulator and a container past processes.maxContainers ask; per-job memory and CPU limits in a cgroup (Linux); the evals report in agent-loop.md. test_jobs.c, tools/check_integrations.sh
11 Rule syntax, background jobs confined ✅ permissions.c:261-326; jobs.c:970-1068 test_sandbox.c test_jobs
11 Detach gated by a rule ✅ tools.c:1655-1700; permissions.c:98, 291, 1630-1633 Beyond the spec. test_jobs.c test_tools
11 Dangerous patterns, target in the question, guardrails 🟡 permissions.c builtin_dangers; devices.c oklm_cluster_danger, oklm_device_danger, oklm_cloud_danger, oklm_tunnel_danger; tools.c resource_danger The dangerous patterns and guardrails exist, and the question names the Kubernetes context, the adb serial and the tunnel's exposure; not the cloud account or the Docker host. tools/check_integrations.sh
11 Network exceptions 🟡 (M18) oklm.c (sandbox.allowedDomains, oklm_proxy_start); proxy.c Sandboxed commands reach the allowed domains through a filtering proxy; no per-integration exceptions (listening ports, daemon sockets). tools/check_network.sh
12 Settings and environment variables 🟡 oklm.c (processes.maxConcurrent, defaultGraceMs, logRetentionDays, logRotateMB, autoBackgroundOnTimeout, maxContainers, autostartServices, autoReapOrphans; events.*; kubernetes.allowedContexts, cloud.readOnly); tools.c OKLM_DISABLE_BACKGROUND_TASKS Most settings reach the jobs; BASH_MAX_OUTPUT sets the tool-output cap (as OKLM_MAX_TOOL_OUTPUT_CHARS); processes.keepOnExit leaves the session's running jobs alive at exit (jobs.c oklm_jobs_options.keep_on_exit, test_jobs.c test_keep_on_exit). monitor.defaultBatchMs is the Monitor tool's default batch window when a call omits batch_ms (tools.c t_monitor, tool-ctx monitor_batch_ms). integrations.<name>.enabled is not read (modest value).
13 /tasks panel ✅ (P3) oklm.c c_tasks, tui_jobs_panel; tui.c oklm_tui_jobs_key, oklm_tui_jobs_run, draw_jobs; jobs.c oklm_jobs_restart, oklm_jobs_keep_one The list with agents, stop N, output N, reap; in /tui an interactive panel kept up to date (state, run time, kind, label, last line): arrows select, Enter follows the output in a pager, s stops (ProcessStop), r restarts a service or a job with a restart policy, k keeps it running at exit, q closes. test_tui.c test_jobs_layout, test_jobs_keys; test_jobs.c test_restart_keep_one; check_commands.sh
13 Status line counts, Ctrl+B, notifications, exit prompt ✅ (P3, P4) oklm.c status_line, view_key, leave_ok, view_notify, show_notices; events.c oklm_events_notice, notice_crash; services.c start_one; agent.c bg_main Counts in the status line (running jobs, failed services, LSP and MCP servers), Ctrl+B; the user told once (a dimmed line and a notification, notification in stream-json) of a crashed job (non-zero exit or signal, not stopped), a failed readiness probe and a finished background agent, with the label and the reason, the model at its next turn; the exit question's "keep" answer (jobs left running, found by the next session with the orphans). test_events.c test_notices, test_services.c test_ready, test_agent.c test_background, test_jobs.c test_keep_at_exit
14 Headless events, --keep-services, event callback 🟡 (P5) oklm.c headless_events, --keep-services; jobs.c oklm_jobs_options.keep_services stream-json gets process_started, process_exited, monitor_event, process_ready (a service reaching its readiness probe, with its pid, ports and probe; oklm.c process_hooks, tools/check_events.sh) and notification (the user's notices; oklm.c show_notices). --keep-services leaves the service, LSP and MCP jobs running at exit (test_jobs.c test_keep_on_exit). Left: cleanup failures in the result, an event callback in the library.
15 Tree kill, Linux and Windows ✅ jobs.c:1678-1703; process.c:392-413, 528 A detached Windows job's descendants survive JobKill (jobs.c:1703).
15 Ports, shell, limits, messages 🟡 probe.c oklm_port_holder; tools.c PowerShell; sandbox.c, process.c, jobs.c limits; hooks.c oklm_notify_toast_command A port's holder named on Linux, Windows and macOS; PowerShell exists; rlimits and Job Object limits, per-job cgroups v2 on Linux and per-job Job Object memory and CPU-rate limits on Windows; a Windows toast for the system notification channel. The Windows parts are cross-compiled, untested on Windows; the macOS part was never compiled.
15 Job tests on Windows ❌ test_jobs.c main Skipped on Windows.
16 Kill tree, harness death, re-attach, retention, events mid-turn ✅ test_jobs.c, test_tools.c test_bash, test_agent.c test_job_note
16 Reused process id ✅ jobs.c alive (pid and start time), group_lives Reused pids are told apart by their start time, in the session's own journal and in the orphan finder (which took a group whose leader id was reused by a later process before); a live process faked under a recorded pid with another start time (earlier or later) is neither re-attached, signalled nor an orphan, the real start time is (test_jobs.c test_reused_pid); a pid that does not exist (test_jobs.c test_restart, test_retention).
16 The rest 🟡 test_jobs.c; test_probe.c; test_events.c; test_lsp.c; tools/check_services.sh, check_integrations.sh Most of the spec's tests exist; real Docker, kind and Playwright runs behind flags, the Android and iOS checklists are not run here. The real-model process evals (tests/evals 10, 16, 17) run on Qwen3-8B: 10 and 17 pass, 16 is the model's (agent-loop.md).
18 Deferred tools, worked example, "Running:" line 🟡 (M13) oklm.c deferredTools default; agent.c ToolSearch; tools.c Bash description Deferred tools and ToolSearch exist; the worked example is a sentence of the Bash description, not of the system prompt; no "Running: ..." reminder line.
18 Short event notes ✅ events.c; agent.c tell_events, tell_jobs; jobs.c oklm_jobs_last_line Short notes with the matched lines; a job's end note gives how it ended and its last non-empty line (escapes removed, secrets masked, clipped at a character; ProcessList uses the same). A job's output lines become events only through a monitor; its end is an event without one. test_agent.c test_job_note, test_jobs.c test_last_line

Processes conflicts (⚠️):

  1. Resolved (P1): the stop grace is 5 s.
  2. Resolved (P1): the journal has kind, directory and rotated, the retention is a setting (ADR-0012 amended).
  3. ADR-0012 and the spec make agents jobs; the code keeps them apart.
  4. Resolved (M8, P4): --resume reopens a session (re-attaching its jobs), and other sessions' orphans are reaped at start.
  5. Resolved (P3): a timeout moves a command to the background.
  6. Resolved (P3): a PowerShell tool next to Bash (which keeps cmd.exe).
  7. Resolved (P3): ProcessOutput / ProcessStop / ProcessList, readers kept by the manager, /tasks (integer ids kept, shown as job 3).
  8. In the default sandbox, jobs have their own network namespace: their ports cannot be reached or probed from the host.
  9. Resolved: PR_SET_PDEATHSIG is per thread, so every child is forked by one thread of the harness's own (process.c proc_fork); a job a background sub-agent starts no longer dies with its thread.
  10. On Windows, an owned job found alive on reopening is marked interrupted but not killed, and killing a detached job leaves its descendants.

Tests already covering it: test_jobs.c (test_basic, test_restart, test_harness_death, test_retention, test_tools; Unix only), test_tools.c test_bash, test_sandbox.c (test_jobs, limits, process namespace), test_agent.c (test_job_note, test_background, test_background_limits).

Git

Audit of git_spec.md (its G0), 2026-11-02, the same legend. The agent has no git code: nothing in src/harness/, include/oklm/harness/ or apps/oklm.c runs or reads git, except the directory walks skipping .git (tools.c:1011, 1034; permissions.c:1817, 1839). No git library either, so git goes through the command line as §0 wants. The "checkpoint" hits in the code are oklm train's.

§ Feature Status Evidence Notes
0 Git through the command line, Bash, jobs ✅ (G1 to G11) git.c oklm_git_detect, oklm_git_snapshot, oklm_git_state_danger, oklm_git_precommit, oklm_git_worktree_*; permissions.c A git layer of its own: detection, the snapshot, a classifier, state checks, pre-commit checks, worktrees. test_git.c
0 History never rewritten unasked ✅ permissions.c builtin_dangers (push --force, reset --hard, clean -f, filter-branch, update-ref); tools.c oklm_git_state_danger History rewriting asks even under an allow rule or the bypass mode (dangerous calls always ask). test_git.c test_state_dangers, test_branch_dangers
0 Commits only when asked; conventions mirrored ✅ prompts/identity.md, prompts/git.md; git.c conventions in the snapshot Commit and push only when asked; the repository's message style and branch names followed; safe staging, hook failures.
0 Works outside a repository ✅ Nothing depends on git.
1.1 Detection, worktrees, submodules, LFS, default branch, hosts, conventions, hooks, signing ✅ (G1) git.c oklm_git_detect Sparse checkout not read; no /cd (the commands spec's). test_git.c test_detect
1.2 Git snapshot in the prompt ✅ (G1) git.c oklm_git_snapshot; prompt.c; cmd_agent Once per session, with the conventions and the commit rules.
1.2 Reminder on branch or HEAD change ✅ (G1) agent.c turn_reminders; git.c oklm_git_head From the files, before each turn. test_git.c test_reminder
1.3 Status line, operations in progress at start ✅ (G1) cmd_agent; term_ui.c oklm_git_branch, oklm_status_default; git.c oklm_git_read_marks The branch in the status line with its marks (↑N ahead of the upstream, ↓N behind, * changed or untracked files; also git.ahead / behind / dirty for statusLine.command), read with one git status after a submitted line or a ! command, never per keystroke; the operation in progress told at start. test_git.c test_marks, tools/check_commands.sh (on a terminal)
2.1 Read-only git allowed without asking ✅ (G2) permissions.c read_git, class_git, class_gh Plan mode included. test_permissions.c test_git_classes
2.1 Rules on subcommands ✅ (G2) permissions.c check_bash Rules also meet the command read apart; allow rules only past -C and the pager options; a redirection makes a read a change.
2.1 Compound commands ✅ util.c:139-251; permissions.c:1638-1715 test_permissions.c test_split, test_bash
2.2 Mutating commands ask; rules approve them ✅ permissions.c:783-788, 1638-1715 acceptEdits with Bash has no test.
2.3 Always-ask list (force push, reset --hard, clean -f, branch -D, amend of pushed, --no-verify, config writes) ✅ (M4, G2) permissions.c builtin_dangers, class_git; git.c oklm_git_state_danger The list (M4), config writes, a push to the default or a protected branch, amends and rebases of pushed commits. test_git.c test_state_dangers
2.4 Interactive commands refused ✅ (G2) permissions.c class_git With what to do instead.
2.4 GIT_EDITOR, GIT_SEQUENCE_EDITOR, GIT_PAGER, PAGER, GIT_TERMINAL_PROMPT set ✅ (M3, P1) process.c proc_run; jobs.c spawn
2.5 Secret scan, large files, unwanted files, staging only the agent's files ✅ (G3) / 🟡 git.c oklm_git_precommit; tools.c tool_run Secrets block (gitleaks when installed); the others are told. Staging by name is in the rules and /commit, not enforced (an add -A asks like any change). test_git.c test_precommit
3 Commit workflow, trailer, amend rules, edge cases ✅ (G3) prompts/git.md; skills.c commit; cmd_agent git.coAuthorTrailer; amends of pushed commits ask; /commit; git.autoCommit tells the model to commit each change when done.
4 Branches: names, dirty switch, protected, sync, cleanup ✅ (G4) git.c oklm_git_state_danger; prompts/git.md A dirty switch and a commit to a protected branch ask; naming, sync and cleanup in the rules. test_git.c test_branch_dangers
5.1 /pr ✅ (G7) skills.c pr Template, Summary / Changes / Test plan, push without upstream asked, gh or glab; /sandbox network on for the push. tools/check_git_host.sh (a fake gh)
5.2 Existing PRs, comments, CI, /autofix-pr ✅ (G10) skills.c autofix-pr; permissions.c class_gh A loop on ScheduleWakeup, ten rounds at most. tools/check_git_host.sh (a fake gh failing, then passing)
5.3 Issues 🟡 permissions.c class_gh Reads allowed, creation asked; no workflow of its own.
6 Conflicts, rebase, cherry-pick, bisect, interrupted operations ✅ (G1, G5) prompts/git.md; agent.c (bisect reset at the request's end) test_git.c test_conflict_and_bisect
7 Archaeology, git-history skill ✅ (G10) skills.c git-history Loaded by the model when asked why, when or by whom.
7 Compact output 🟡 git.c oklm_git_snapshot; process.c The snapshot is compact (status lines capped, five subjects); git output through Bash gets the generic truncation.
8 /diff ✅ (G6) oklm.c c_diff The agent's files marked, stage / unstage / revert / open; no side-by-side view. tools/check_commands.sh
8 /code-review, /security-review, /simplify, /ultrareview ✅ (G8) skills.c code-review, security-review, simplify, ultrareview Prompt commands driving sub-agents by level; the last level not remembered. Measured with tools/eval_review.sh (six seeded bugs, medium): Qwen3-8B, the default, 6 of 6 then 5 of 6, above the 80% asked (Qwen3-4B 2, then 0). tools/check_git_host.sh
9 Worktrees, --worktree, sub-agent isolation, /batch, /doctor ✅ (G9) git.c oklm_git_worktree_add, _changes, _remove, oklm_git_worktrees; agent.c wt_make, wt_settle; oklm.c --worktree; skills.c batch test_git.c test_worktrees, test_isolation; tools/check_git_host.sh
9 EnterWorktree / ExitWorktree tools, git.worktree.setup, WorktreeCreate / WorktreeRemove hooks ✅ (G9) worktree.c oklm_worktree_make, oklm_worktree_drop, tool_enter_worktree, tool_exit_worktree, oklm_worktree_leave; hooks.c; settings.c node_at Keep, remove (forced once agreed), merge (a protected branch asks; a conflict undone); git.worktree.dir not offered (always under .oklm/worktrees). test_git.c test_worktree_tools, test_worktree_hooks; tools/check_git_host.sh
9 Sandbox and worktrees ✅ (G9) cmd_agent; sandbox.c The agent's worktrees are under the project, so the writable set holds them and the shared .git; a worktree made elsewhere by hand is not covered.
10 Checkpoints independent of git ✅ (M8) session.c oklm_session_checkpoint, oklm_session_rewind; oklm.c /rewind Checkpoints of the files the tools write, per turn, apart from git; changes made by shell commands are not tracked. test_session.c test_rewind
11 Git slash commands ✅ (G3, G7 to G10) skills.c commit, pr, code-review, security-review, simplify, ultrareview, bisect, batch, autofix-pr, git-history Every git command of the spec. tools/check_git_host.sh
12 git.* settings ✅ (G3) cmd_agent git.coAuthorTrailer, git.protectedBranches, git.worktree.*, and (as lines of the git snapshot the model follows) git.branchPrefix, git.commitConvention, git.prFooter, git.draftPRs, git.autoCommit. host (gh/glab detected), maxStatusLines (the snapshot's fixed cap) and secretScan (gitleaks when installed) stay as they are.
13 -p, credentials from the environment, CI workflow 🟡 (G10) cmd_agent; skills.c install-github-app JSON output since M14; /install-github-app writes the workflow; network cut by the sandbox unless /sandbox network on (sandbox.network in CI).
13 Bypass only inside the sandbox ✅ permissions.c:369-380, 598-610 test_permissions.c test_modes
14 Large repos, submodules, LFS, shallow clones ✅ (G11) git.c oklm_git_detect, oklm_git_snapshot, oklm_git_owners; oklm.c owners_note Said in the snapshot with what to do; with LFS, whether git-lfs is installed, the objects not pushed (git lfs status) and the files not pulled (git lfs ls-files); CODEOWNERS (.github/, the top, docs/; last match wins) for the files the session edited, given to /commit and /pr; timeouts on slow commands; pre-commit flags large files outside LFS. test_git.c test_detect, test_lfs (a stand-in git-lfs), test_owners, test_precommit; tools/check_commands.sh (/commit)
13 CI templates, pushes in CI 🟡 (G10) skills.c install-github-app /install-github-app writes the CI workflow; nothing more on pushes in CI.
14 Large repositories 🟡 git.c command timeout, snapshot caps As row 518: git commands time out and the snapshot is capped; nothing else for large repositories.
15 Fixture repositories, fake gh, git tests ✅ test_git.c (fixture repositories with a bare remote); tools/check_git_host.sh (a fake gh) Fixture repositories, a fake gh, git tests (test_detect, test_precommit, test_conflict_and_bisect, test_worktrees).

Git conflicts (⚠️):

  1. Resolved (M4, G2): dangerous calls ask even when a rule allows them.
  2. Bypass allows everything but deny rules (permissions.c:772-774).
  3. Resolved (G2): read-only git runs in plan mode.
  4. Resolved (G2): the classifier reads the command apart first.
  5. The sandbox cuts the network by default (sandbox.c:399; ADR-0011 all or nothing): fetch, push and host access need an answer (per call, or --allow-network).
  6. The sandbox's writable set excludes a linked worktree's git directory.
  7. Resolved (G3): the setting is git.coAuthorTrailer.

Tests already touching it: test_permissions.c (test_split, test_bash on git command lines, test_modes, test_precedence, test_settings), test_tools.c (test_bash, test_skills), test_jobs.c, test_sandbox.c.

Commands

Audit of commands_spec.md (its C0), 2026-11-02. Before M10 (C1–C3 since; the rows below say what is done): no command framework: two REPLs compared strings in place, cmd_agent (/exit, /thinking or Ctrl-O, /reset, /jobs, /mode MODE) and cmd_chat (/exit, /reset, /system TEXT, /tool RESULT); the GUI has none; -p goes to the model as it is.

Framework

§ Feature Status Evidence Notes
1.1 Command types ✅ (C1) commands.h oklm_cmd_type Actions, dialogs (picker or text), prompt commands; workflows and MCP prompts with their specs.
1.2 One registry ✅ (C1) commands.c oklm_cmds_add, oklm_cmds_add_skills; oklm.c repl_defs oklm chat keeps its own four commands (Later).
1.3 At the start of a message only ✅ (C1) commands.c oklm_cmds_parse Case aside. test_commands.c test_parse
1.3 Stacking, case, namespaces, $ARGUMENTS, // escape ✅ (C1, C3) commands.c oklm_cmds_parse, oklm_cmds_expand test_commands.c test_parse, test_expand
1.3 Usage errors ✅ (C1) oklm.c c_add_dir, c_skills; commands.c (stacking)
1.3 Unknown command not sent to the model ✅ (C1) commands.c suggest Up to three close names.
1.4 Precedence, shadowing warnings ✅ (C1) commands.c oklm_cmds_add_skills; tools.c add_skill (shadowed); oklm.c c_help /project:NAME, /user:NAME. test_commands.c test_precedence
1.5 Running while busy ✅ (C1) commands.c oklm_cmds_submit, oklm_cmds_take; oklm.c view_key, repl_send Queue, immediate, immediate-set; no confirmation for cache-invalidating changes (no /model yet). test_commands.c test_submit, test_busy_applies
1.6 Menu on /, completion ✅ (C2) commands.c oklm_cmds_menu; oklm.c view_draw_line, view_complete_arg Enum values and directories completed; sessions, servers, models with their commands. test_commands.c test_menu
1.7 Skills folder format ✅ skills.c:1065-1076, 1227-1263; agent.c:834-837 test_tools.c test_skills
1.7 .oklm/commands/, front matter superset, expansion (!, @) ✅ (C3) tools.c add_skill, scan_commands; commands.c oklm_cmds_expand model and context: fork read, not acted on (Later).
1.8 Visibility overrides ✅ (C3) tools.c oklm_tool_ctx_skill_override; oklm.c reload_skills, c_skills Managed locks with managed settings.
1.9 -p "/cmd" ✅ (C1) oklm.c repl_submit (headless)
2 Picker, settings panel, diff viewer 🟡 (C2) term_ui.c oklm_picker_*; oklm.c view_pick, tui_config_panel; tui.c oklm_tui_settings_* The picker (used by /rewind, /mode, /theme, /output-style); the settings panel of /config in the full-screen UI (edited in place, checked, saved to a scope); the diff viewer is the git spec's. test_term.c test_picker, test_tui.c test_settings_panel
2 Confirmation with "don't ask again" ✅ (M4) oklm.c (an "always" answer); tools.c oklm_perms_save_rule Saved as an allow rule in the settings. test_permissions.c test_save_rule
2 Progress view, text fallback ✅ oklm.c status_line, c_tasks, view_progress; tui.c oklm_tui_progress_set; view.tty, view.keys Background work in the status line and /tasks as text; in the full-screen UI a progress row above the status bar (writing with tokens and speed, a tool running with its time, jobs, context). test_tui.c test_progress
4 Bundled skills ✅ (M13, G3, C7) skills.c builtin_skills Every skill-type command of the spec is bundled (skill-creator, commit, pr, the reviews, bisect, batch, autofix-pr, run, verify, debug, deep-research, update-config, ...); /loop and /doctor are built-in commands.
5, 6 Settings, hook events ✅ (C3) settings.c (known_members), skills.c, commands.c review_args, oklm.c Every setting of the spec read: commands.maxStack, skillOverrides, feedback.bundleDir, commands.legacyDirs (the single-file command directories skipped), review.defaultLevel (/code-review without a level), goal.maxIterations (goal.maxTurns its older name), loop.defaultPrompt (after .oklm/loop.md), schedule.backend (cron; systemd, launchd, taskscheduler refused by /schedule as not written), ui.viewMode (classic, full, fullscreen), ui.promptColor; each member's type or value checked, a wrong one left out with a warning. CommandRun (commands.c) and DirectoryAdded (oklm.c c_add_dir) hook events fire. test_settings.c test_members, test_skills.c test_reload, test_commands.c test_review_level, tools/check_commands.sh
7 Tests ✅ (C1–C3) test_commands.c; test_term.c test_picker; test_line_edit.c

Catalog

Present in part (🟡) or under another name (⚠️); every other command of §3 is ❌, and the Skip rows have nothing (their "not available" stubs are C10's).

Command OKLM Evidence Notes
/clear [name] (/reset, /new) ✅ (C4) oklm.c c_clear A name labels the conversation left (its session's title).
/exit (/quit) ✅ (C1, P4) oklm.c c_exit, leave_ok Asks with jobs running.
/btw, /copy, /todos, /recap, /rename, /branch, /resume (/continue), /autocompact, /goal, /undo ✅ (C4) oklm.c c_btw, c_copy, c_todos, c_recap, c_rename, c_branch, c_resume, c_autocompact, c_goal Asides through oklm_agent_ask_aside() (not in the history); /recap not shown by itself after idle. tools/check_commands.sh
/fork, /background; oklm agent agents, attach, send, stop ✅ (C8) oklm.c c_background, c_fork, bg_spawn, agent_bg_cli, inbox_* Detached processes resuming the session (no daemon); peek replies through an inbox file; Linux and macOS only. /subtask and /stop not done. tools/check_background.sh
/plan ✅ oklm.c c_plan test_tools.c test_plan
/permissions ✅ oklm.c c_permissions, permissions_command In the REPL: the mode, added directories, rules by scope, allow / ask / deny / remove per scope; text, no panel, no list of recent denials.
/sandbox ✅ (C5) oklm.c c_sandbox
/add-dir ✅ (M4) oklm.c c_add_dir Applies from the next tool call, also while the agent works.
/cd, /import, /skill-doctor, /statusline, /color ✅ (C6) oklm.c c_cd, c_import, c_skill_doctor, c_statusline, c_color /import copies commands, agents and skills (not MCP servers, settings). tools/check_commands.sh
/keybindings, /terminal-setup ❌ oklm.c stubs Key bindings are fixed (no file to edit yet).
/skills, /reload-skills ✅ (C3) oklm.c c_skills, c_reload_skills
/tasks (/bashes) ✅ (P3, C8) oklm.c c_tasks; agent.c oklm_agent_background_list /jobs and /bashes its aliases; background agents, wakeups, loops and background sessions listed; text, and an interactive panel in /tui (follow, stop, restart, keep).
/loop (/proactive), /schedule (/routines) ✅ (C8) oklm.c c_loop, loop_round, c_schedule Loops on an interval or paced by ScheduleWakeup; /schedule through crontab only. tools/check_commands.sh
/help ✅ (C1) oklm.c c_help By source, aliases, shadowing.
/status ✅ (C9) oklm.c c_status Text, not the settings panel.
Skipped commands (§3.8), the generated reference (C10) ✅ (C10) oklm.c skipped_command, agent_commands_cli; docs/commands.md Typed, a skipped one says why.
/debug, /deep-research (bundled skills, §4) ✅ (C10) skills.c /deep-research has no web search.
/code-review (/review), /ultrareview, /security-review, /simplify, /batch, /autofix-pr, /commit, /pr, /bisect, /install-github-app, /run, /verify, /run-skill-generator ✅ (C7) skills.c built-ins Prompt commands; /review loads code-review (a project's or user's review skill wins over it). tools/check_git_host.sh
/voice ❌ cmd_transcribe; audio.h:115-133 Speech to text exists; nothing records.
/subtask ❌ oklm.c stub; agent.c; jobs.h Background sub-agents (the Agent tool) and /fork (a background session) exist, no /subtask forking the conversation into a sub-agent.
/context, /usage ✅ (C9) oklm.c c_usage (/cost, /stats); /context with M5b tools/check_commands.sh
/model, /effort ✅ (C5) oklm.c c_model, c_effort; agent.c oklm_agent_set_model, oklm_agent_set_template_var Checked switching Qwen2.5-0.5B to Qwen3-0.6B mid-session. /effort changes enable_thinking alone, the --template-vars ones (clear_thinking) kept (test_agent test_template_var).
/sandbox, /plan TEXT, /config KEY=VALUE, /update-config, /fewer-permission-prompts ✅ (C5) oklm.c c_sandbox, c_plan, c_config; skills.c tools/check_commands.sh
/fast, /advisor ❌ Local, optional: a second model.

OKLM commands outside the spec: /mode MODE, /thinking, and oklm chat's /system TEXT, /tool RESULT.

Commands conflicts (⚠️): an unknown /foo and any -p "/cmd" reach the model (§1.3, §1.9); /reset and /jobs are the spec's /clear and /tasks (aliases, per agent-design.md); /mode and /thinking have no row (kept as local built-ins, or folded into /plan, /permissions, /config: C0 decides); oklm chat has its own set (shared registry or not: C0); matching is exact and case-sensitive; skill shadowing is silent.

Tests already touching it: test_tools.c (test_skills, test_plan, test_asking), test_agent.c (test_calls with reset, test_job_note, test_background), test_permissions.c, test_jobs.c, test_line_edit.c, test_sandbox.c.

Serving

Audit of serving_spec.md (its S0), 2026-11-02, the same legend; ⚠️ here also marks a row where the spec's "What OKLM already does" table is wrong. Continuous batching over a fixed set of sequences exists: one scheduler thread, one oklm_eval_batch() a step, decode tokens first and prompt pieces in the rest of n_batch, requests joining between steps (sched.c:1371-1835). Memory is contiguous and reserved up front: --parallel × -c cells per layer (model.c:1931, 2293-2340), resident from the start. No block, no allocator, no preemption, no prefix shared between live requests. The design built on this audit is serving-design.md, the cache layout adr/0019-paged-kv-cache.md, the measured baseline in serving-design.md.

S1 (prerequisites and baseline)

Part Feature Status Evidence Notes
S1 Packed (ragged) input: flat tokens, per-token positions, per-sequence offsets, no padding ✅ model.h:296-326; model.c:2924-3032 (run_items), 3173-3209; model_internal.h:249-256 (model_group) Items carry a sequence and its tokens; positions come from seq_past, offsets are each group's r0. One item per sequence per call (model.c:3182-3183).
S1 Packed equals unbatched logits ✅ test_model.c:1138-1244 (check_sequences), 337 (test_batching) Mixed prompts, decodes, copies and truncation: 0.0 on the CPU, within 1e-5 on OpenCL (F32 cache).
S1 Reference path ✅ model.h:249 (oklm_eval); adr/0015-test-references.md llama.cpp is the test-only oracle; its llama-server was built for the baseline only.
S1 Benchmark harness: throughput, TTFT, TPOT at 1, 4, 16, 64 ✅ (S1) tests/model/bench_batch.c; tools/bench_serve.py The HTTP load generator (short and agent workloads, 503 retries, cached prompt tokens), its runs in serving-design.md.
S1 Non-streamed requests cancelled on disconnect; --workers over --parallel + --queue ✅ (S1) server.c completion, oklm_server_new; sched.c sched_req_wait_ms, take_queued, sched_submit; nilorea n_http_server_peer_gone Freed in 0.02 s against 1.7 s for the answer (test_server.c test_disconnect); a burst within the free sequences is not refused; the forward pass's view headers sized by the sequences (test_model.c test_many_sequences, 1024 in one batch).

S2 (paged KV cache)

Part Feature Status Evidence Notes
S2 KV pool of blocks ✅ (S2) model.c oklm_context_new (kv_blocks), paged_attend; kv_pool.c One pool tensor per layer and kind of kv_blocks * kv_block_size rows on the layer's device; kv_blocks = 0 keeps the contiguous cache bit for bit.
S2 Cache types ✅ model.h:138-140; model.c:1781-1797 (kv_type_ok), 2279-2291 (rotation) F32, F16, BF16, Q8_0, Q4_0, Q4_1, Q5_0, Q5_1, IQ4_NL; quantized ones need head_dim % 32 == 0. A cell is one token's row, quantization blocks run along head_dim (model.c:2307).
S2 Block allocator, free list, refcounts ✅ (S2) kv_pool.c kv_pool_take, kv_pool_unref, kv_pool_truncate; model.c paged_reserve, oklm_seq_copy A batch takes its blocks all or none; copies share full blocks and copy the partial one; a shared block is copied before a write. test_model.c test_paged_blocks
S2 Block size 16 ✅ (S2) model.h kv_block_size 16 by default, 32 allowed (ADR-0019), not on the command line.
S2 Memory profiled at start, the rest to the pool ✅ (M14) model.c oklm_kv_blocks_fit, oklm_context_device_bytes; backend_cl.c cl_free_memory; server.c oklm_server_new; --kv-mem The pool takes what the device says is free (AMD's CL_DEVICE_GLOBAL_FREE_MEMORY_AMD: other programs and models counted) less a 3 % margin, the weights not yet there and the activations (the context's buffers are all allocated up front, so they are computed, not sampled), within the total-based estimate; a draft model's weights, cache and activations come out of it. Four contexts' worth on the CPU.
S2 Slot mapping ✅ (S2) kv_pool.c kv_pool_slot; model.c paged_attend New rows written block by block to table[p / B] * B + p % B.
S2 Paged attention, step A (gather) ✅ (S2), replaced git history (paged_attend before step B) Measured and left behind: identical logits, half the OpenCL throughput (serving-design.md).
S2 Paged attention, step B (block-table kernel, decode and prefill) ✅ (S2) ops.h oklm_attention_paged; attention_cpu.c kv_row; kernels.cl KVR in attention and the tiled attention_tile*; backend_cl.c arg_table; model.c paged_attend, paged_upload_tables Keys and values read in place through the table on the CPU (every path, row by row) and OpenCL (decode and the tiled prompt kernels); the tables uploaded once per step. Identical logits; OpenCL within 4 % of the contiguous cache at 16 clients, equal at one. One launch per sequence and layer still (S6).
S2 Memory follows the tokens used ✅ (S2) model.c paged_reserve, oklm_seq_truncate; sched.c blocks_fit, reclaim_idle Blocks taken as tokens arrive and given back on truncation; idle sequences give theirs first; a full cache ends the newest request (length) until S3 preempts. 16 sequences of Qwen2.5-0.5B at -c 4096: 1478 MiB against 2052 contiguous. test_server.c test_kv_pressure
S2 Greedy output equals the reference ✅ (S2) test_server.c test_parallel (both caches); test_model.c test_paged_sequences Qwen2.5-0.5B, four concurrent chats: the paged and contiguous answers identical on the CPU and OpenCL.

S3 (scheduler)

Part Feature Status Evidence Notes
S3 waiting queue ✅ (S3) sched.c take_queued, sched_submit FCFS by submission; --queue 256 by default with the paged cache; preempted requests go back to its head.
S3 running set ✅ (S3) sched.c sched_main The requests holding sequences, 64 on OpenCL and 16 on the CPU by default; the paged cache's blocks are the real bound.
S3 swapped ✅ (M14) model.h oklm_seq_swap_out, oklm_seq_swap_in; sched.c preempt, assign, drop_swap; --swap-mem A preempted request of 64 positions or more moves its rows to host memory while the swapped ones hold under --swap-mem; running again it attaches what the prefix cache still holds and brings the rest back, its rows' keys recorded (its blocks cached again). Same answers as unpressured (test_server.c test_preemption), exact logits after a round trip (test_model.c check_swap). Not for a quantized cache on a device nor several devices (recompute).
S3 Engine step: decode reservation, admission, forward, sample, finish ✅ (S3) sched.c sched_main Decode tokens first (oldest first, blocks reserved), then admission while a sequence and the prompt's blocks are free, then prompt pieces oldest first capped by --prefill-chunk, one forward, sampling.
S3 Preemption (recompute) ✅ (S3) sched.c preempt, newest_running, feed_tokens The newest running request gives its blocks back and waits at the head of the queue; it replays its prompt, generated tokens and the pending one, its sampler kept. Answers identical to unpressured ones (test_server.c test_preemption); counted in /api/stats.
S3 FCFS ✅ sched.c:921-1009 (take_queued) Head of the queue first, into the free slot holding its longest prefix.
S3 No starvation or deadlock under memory pressure ✅ (S3) sched.c Strict FCFS (the head waits for its blocks, the newest is preempted first); prompts blocking each other release the newest; a request longer than the cache ends with length. test_server.c test_kv_pressure, test_preemption
S3 Engine bounded by memory, not by a sequence count ✅ (M14) server.c oklm_server_new; model.c paged_upload_tables By default as many sequences as a step has rows (512) or the pool has blocks, the fewer; a step uploads only its own sequences' tables, so idle sequences cost nothing per step. Qwen2.5-0.5B, 256 clients: 5203 to 7265 tokens/s, TTFT p50 4.57 to 0.22 s against 64 sequences.

S4 (chunked prefill)

Part Feature Status Evidence Notes
S4 Chunk capped to the budget left after decodes ✅ sched.c:1568-1627
S4 Partially prefilled sequences ✅ sched.c:73 (fed), 1749-1765 fed is the spec's num_computed_tokens.
S4 Decodes and chunks in one step ✅ sched.c:1439-1641
S4 Fairness between prefills ✅ (S3) sched.c sched_main Oldest request first, each piece capped by --prefill-chunk.
S4 30k-token prompt mid-generation, TPOT flat ✅ ⚠️ (M14) sched.c piece_cost, cost_fit, PIECE_PROBE; kernels.cl ATH_KERNEL, AT_KERNEL (GQA rows); tools/bench_stall.py Bounded, not flat (correction 8). Pieces sized by a fitted cost of their tokens and of their attention over the keys before them, so each at its depth; small probes until fitted. Prompt attention twice as fast (key tiles shared by a KV head's query heads, half tiles, accumulators in registers). Qwen3-4B, 32,872 tokens among four streams: the stall at its start gone (max gap 389 to 33 ms), its prefill 225 to 111 s, the streams' median 12.0 to 25.9 ms during it.

S5 (prefix caching)

Part Feature Status Evidence Notes
S5 Prefix reuse ✅ (S5) sched.c assign, take_queued, prefix_coming; model.h oklm_seq_attach_prefix, oklm_kv_prefix_cached A request starts from the longer of its sequence's own prefix and the prefix cache's, any request's; a waiting request whose prefix another is computing waits for its blocks instead of computing them again.
S5 oklm_seq_copy() sharing a prompt ✅ (S2) model.c oklm_seq_copy Paged: full blocks shared, the partial one copied on the device. The scheduler shares through the prefix cache instead.
S5 Block hashes chained on the parent ✅ (S5) kv_pool.c block_hash, kv_pool_written FNV-1a over the parent's hash, the block size and the rows, when a block becomes full: a token, or a media row's marker, its media's content hash and its index (S8); a row given as an embedding without a hash keeps its block unhashed.
S5 hash -> block map ✅ (S5) kv_pool.c map_lookup, map_insert Open addressing, rebuilt past a quarter of removed slots; a lookup compares the tokens, so a collision never attaches a wrong block.
S5 Reuse across live requests (refcount) ✅ (S5) kv_pool.c kv_pool_attach, kv_pool_ref Two requests at once start from a system prompt a finished one computed (test_server.c test_shared_prefix); 16 cold clients of the agent workload find 1297 of 1319 tokens on average.
S5 LRU of refcount-0 blocks ✅ (S5) kv_pool.c kv_pool_unref, kv_pool_take Released hashed blocks stay found until the pool takes them, least recently released first; counted as free. test_model.c test_prefix_cache
S5 Copy-on-write rule ✅ (S2, S5) kv_pool.c kv_pool_must_copy; model.c paged_reserve Shared or hashed blocks are copied before a write.
S5 Cached tokens reported ✅ server.c:1208-1213; sched.c:608, 623 usage.prompt_tokens_details.cached_tokens; cached_tokens in /api/stats.

S6 (model runner)

Part Feature Status Evidence Notes
S6 Launch overhead (the role of CUDA graphs) ✅ (S6) ops.h oklm_set_rows, oklm_attention_paged_tokens; kernels.cl set_rows, attention (per token); model.c model_attend, paged_upload_tables Per step and layer: one write of every sequence's keys and one of its values (float caches; quantized ones keep a copy per block on a device), one attention launch for the decode tokens of every sequence, the step's metadata (positions, table offsets, slots, tables) uploaded once. OpenCL TPOT at 16 clients 21.0 to 14.6 ms, throughput 750 to 1078 tokens/s; the rest of the step (projections, norms, the prompt groups' launches) is unchanged. At one client a token is 2.55 ms of kernels in 3.2 ms, at four 3.4 ms in 3.6 to 3.9: decode steps are compute-bound, no graph equivalent needed.
S6 Batched sampling ✅ (S6) sampling.c oklm_sampler_greedy, oklm_sampler_top_needed, oklm_sampler_sample_top; model.h argmax_only, top_n; kernels.cl argmax_rows, topk_rows Every row's best token (greedy) or best candidates (top_k plus the tokens a penalty may lower, up to 512) found on the device in one launch, only those read back; the host draws from the candidates, the same token as from the whole row (test_sample_top: 900 draws, penalties included). The whole row only for no top_k, grammars or penalties that raise logits. Temperature 0.8 at 64 clients: 2251 to 4917 tokens/s.
S6 Logits transfer ✅ (S6) model.c run_items Greedy rows read back one id; the other items their own rows only. 64 clients on OpenCL: 3340 to 5126 tokens/s.
S6 CPU and device overlap ✅ (S6), measured unneeded sched.c The host works 0.22 ms between 11 ms steps at 64 clients (2 %); within a step the kernels run as they are queued. A pipelined engine would win at most that.

S7 (serving layer)

Part Feature Status Evidence Notes
S7 One loop owning scheduler and device ✅ sched.c:1371-1835, 1903 One thread; HTTP threads only submit and wait.
S7 Requests through a queue, outputs through per-request channels ✅ sched.c:256-267 (sched_req_wait), 2017-2037; server_internal.h:32-96 Text and a condition variable per request; UTF-8 and stop-string holdback (sched.c:303-327).
S7 Concurrent connections ✅ (S1) server.c oklm_server_new; server.h --workers, by default --parallel + --queue + 8 (512 at most): 64 clients reach 64 sequences.
S7 Cancellation within one step ✅ (S1, S7) server.c stream_answer, completion; sched.c take_queued, finish A client that leaves frees its request at the next step, and with the paged cache every finished request gives its blocks back at once (the full ones stay as cached prefixes): kv_usage back to 0 after two clients hang up (test_server.c test_disconnect).
S7 OpenAI API, streaming, tools, JSON schemas ✅ server.c:2371-2462, 906-1101, 1393-1480; adr/0018-server-api.md n = 1 only (server.c:2043-2050); text parts of messages only (server.c:387-399).
S7 Agent tooling unchanged ✅ test_server.c:3063 (test_agent_http), 3680 (test_agent_model) oklm agent --url, OpenAI's Python client (server.md).
S7 Metrics: queue depth ✅ server.c:2295-2363; sched.c:2039-2048 queued, active, tokens, rate.
S7 Metrics: KV usage %, prefix hit rate, preemptions ✅ (S7) server.c stats; sched.c note_kv, assign, preempt; dashboard.html kv_blocks, kv_blocks_free, kv_usage, prefix_hit_rate (cached over all prompt tokens), queue_wait_ms (mean wait for a sequence), preemptions, in /api/stats and on the dashboard.
S7 Windows ✅ server.c:215; testing.md test_server under make wine-test.

S8 (extensions) and the models the paged cache must keep

Part Feature Status Evidence Notes
S8.1 Grammars per request ✅ sched.c:617-621, 706-755; sampling.c:372-375; adr/0009-tool-calls-and-grammars.md Lazy (tool-call trigger) and eager; the mask applied only when the first choice is refused. Independent of the cache.
S8.2 Speculative decoding, MTP ✅ (S8) sched.c ngram_drafts, draft_propose, sched_main; model.h oklm_get_argmax_row, oklm_context_device_bytes; --spec-ngram, --draft; test_server.c test_spec_ngram, test_draft_model In the server: drafts by prompt lookup (the tokens that followed a request's last 3, 2 or 1 tokens earlier in its own text), or from a draft model (--draft: a context of its own, paged, a sequence per slot brought to the slot's tokens lazily, a batch a round over every drafting request), verified in the same step, the cache truncated past the accepted ones; greedy requests by the argmax of every row, sampled ones by a draw a row from the same logits, so both keep plain decoding's answers. Only while at most 4 requests decode and while a request gains half a token a step; the draft model also only while its measured speed beats plain decoding. Rewriting a function on Qwen2.5-0.5B by prompt lookup: 253 to 569 tokens/s; Qwen3-4B with a 0.6B draft: 11 to 13 % faster on the CPU, 2 to 4 % slower on OpenCL (launch-bound small models). The MTP block stays out of the server (oklm run --mtp).
S8.3 Quantized and rotated KV ✅ (S8) model.c paged_attend, kv_type_ok; test_infer_public.c test_paged_quant Whole rows per token: a block of any token count holds whole quantization blocks. Paged, a Q8_0 cache gives the logits of the contiguous one exactly on the CPU and OpenCL (SmolLM2, two sequences, 40 steps); Qwen2.5-0.5B's answers through the server identical. On a device a quantized cache keeps a copy per block for its new rows (set_rows takes float caches).
S8.4 Several devices ✅ ⚠️ model.c:2166-2249, 2528-2586 (forward); opencl.md Layer ranges per device, each device holding its layers' cache; tensor parallelism decided against.
S8.5 LoRA multiplexing ✅ (S8.5) adapter.c oklm_adapter_load, model_adapt; kv_pool.c (salts); sched.c assign; server.c (model) ADR-0021: adapters beside the weights, stacked per weight, one gathered product per weight for a mixed batch; the prefix cache keeps each adapter's blocks apart; oklm serve --lora-module NAME=FILE, chosen by a request's model. test_train.c lora_serve_check, test_server.c test_adapters
model Sliding window (Gemma 2, 3) ✅ arch_llama.c:87-89, 660; ops.h:404 Full n_ctx cells kept, the window applied in attention: unchanged by paging.
model Latent attention (DeepSeek V2, V3) ✅ model.c:1939, 2777-2780; arch_llama.c:422-463 One compressed row per token in the key cache, the value cache one unused cell.
model Multimodal embeddings in a batch ✅ (S8) model.h oklm_seq_tokens.media; kv_pool.c block_hash, same_rows; prompt.c oklm_mm_build; server.c content_media, mcache_keep; sched.c piece_rows; test_model.c check_prefix_media, test_server.c test_media, test_mm_public.c test_smolvlm_rows Images and sounds in chat messages (--mmproj, base64 image_url / input_audio parts), encoded as the request arrives, their embeddings kept by content hash; their rows keyed in the paged cache by the media's content hash and the row's index, found again only with the same picture, exact against the contiguous cache on the CPU and OpenCL. SmolVLM-256M: the same picture again 4.43 to 0.13 s on OpenCL (336 of 349 rows cached), the answer unchanged.
model Weight streaming (--gpu-stream) ✅ model.c:2343-2372, 2497-2519 Device mirrors of the CPU layers' caches, copied per sequence range.

Testing strategy

Part Feature Status Evidence Notes
T Determinism, batched against the reference ✅ test_model.c check_sequences, check_prefix_cache, check_prefix_media, check_swap; test_server.c test_parallel, test_preemption, test_spec_ngram Batch composition and chunking, preemption by recompute and swap, prefix and media cache hits, speculative drafts: the answers of plain decoding.
T Stress test: random arrivals and cancellations, tiny pool ✅ (M14) test_server.c test_stress 24 clients, random lengths and moments, shared prefixes, streamed and sampled requests, a quarter hung up on, 24 blocks for 8 sequences with swapping: preemptions and swaps each run, every block and swap given back, every request ended.
T Allocator invariants ✅ (M14) kv_pool.c kv_pool_check; model.h oklm_kv_check; sched.c (OKLM_KV_CHECK=1) No count below 0, counts equal to the tables holding each block, free and cached blocks on their lists once, the hash map holding exactly the hashed blocks, no block lost; checked after every step of the stress test and through the model tests.
T ASan, TSan ✅ Makefile (asan-test, tsan-test) test_server runs under both.

Serving conflicts and corrections (⚠️):

  1. The spec's table says no freed prefix is kept: each sequence keeps its last request's tokens until another request takes it (sched.c:330, 520-626), so up to --parallel prefixes survive.
  2. It says oklm_seq_copy() copies a shared prompt: only the library and bench_batch use it; the scheduler never does.
  3. Decision 3 expects blocks of a multiple of 32 tokens for quantized caches: a cell is one token's row, quantized along head_dim (model.c:2307), so a block of any size holds whole quantization blocks.
  4. Decision 1 expects the device's free memory: OpenCL gives the total and the largest allocation only; AMD's CL_DEVICE_GLOBAL_FREE_MEMORY_AMD is used when the driver has it (M14), the total-based estimate or a budget otherwise, as on the CPU.
  5. Concurrency was capped at 32 by the HTTP workers and at --queue + --parallel by 503 answers, below the spec's 64 clients. Done in S1: --workers follows the two, and a burst the free sequences take is not refused.
  6. Speculative decoding and multimodal prompts existed in the library but not in the server: for the paged cache they were serving features to add, not ones to keep. S8 added them: prompt-lookup drafts, a draft model (--draft), and images and sounds (--mmproj).
  7. Attention costs one call per sequence and layer (model.c:2716-2790): the batch shares the weight reads, not the attention launches.
  8. S4's "TPOT flat" is not reached on this hardware: while a long prompt is read beside decoding requests, each step carries a piece whose attention reads every key before it (4.4 GB at 30k keys for Qwen3-4B's 36 layers), about a decode step's time even for a few tokens. What holds instead: no stall (the largest gap 33 ms), the slowdown bounded by --prefill-share, the prompt read twice as fast as before.

Tests already covering it: test_model.c (test_batching, check_sequences on the CPU and OpenCL), test_server.c (test_parallel, test_queue_and_halt, test_completions cached prompt, test_client cancel, test_agent_http, test_agent_model), tests/model/bench_batch.c.

ROCm

The audit (R0) of rocm_spec.md, 2026-11-04: what exists for a ROCm/HIP training path and LoRA, with evidence. The decisions and recommendations are in rocm-design.md.

Environment

Part Status Evidence Notes
GPU ✅ rocminfo: AMD Radeon RX 7900 XT, gfx1100 20 GB
HIP runtime ✅ hipcc --version: HIP 6.4; /opt/rocm/lib/libamdhip64.so.7.2.70204 ROCm 7.2.4
hipBLASLt ✅ ⚠️ /opt/rocm/lib/libhipblaslt.so, version 1.2.2 (hipblaslt-version.h:36-38) Its header is C++ only (hipblaslt.h:54-56 include <memory>, <regex>, <vector>; gcc -std=c17 fails), against the plan's constraint 7; its 24 functions are exported as C symbols (nm -D), so a run-time loader with OKLM's own declarations reaches them (conflict 1).
HIP runtime header in C ✅ hip/hip_runtime_api.h, hip/hip_runtime.h compile with gcc -std=c17 -D__HIP_PLATFORM_AMD__
rocBLAS in C ✅ rocblas/rocblas.h compiles as C; /opt/rocm/lib/librocblas.so.5 Approved in hipBLASLt's place after R1 (hipBLASLt no faster than the OpenCL kernel, rocBLAS 1.7 to 3.5 times).
Run-time loader, product wrapper ✅ (R1) src/train/hip_loader.c; src/train/gemm_rocblas.c (tr_rb_gemm); tests/train/test_rocblas.c; tests/train/bench_rocblas.c Every layout of the trainer's products within 7e-6 of tr_gemm.

Abstractions and paths

Part Status Evidence Notes
Compute backend interface ✅ include/oklm/core/backend.h:51-84 (oklm_backend_iface), src/core/backend.c Inference only; the trainer does not use it.
Trainer device seam ✅ src/train/train_internal.h:560-759 (tr_cl_*); src/train/train.c:1191-1204 (k_matmul_forward, k_matmul_backward), 658-661 (device chosen) A device launcher per CPU kernel, chosen through tr->cl.
Device memory ✅ src/train/train_cl.c:95-112 (tr_cl_buf, fake addresses), tr_cl_alloc, tr_cl_upload, tr_cl_download Pointers never dereferenced on the host.
Device product ✅ src/train/train_cl.c:624-630, 903-989 (gemm_batch, gemm), 1105 (pairs); src/train/train_kernels.cl:167 (tr_gemm) Strides on both operands, batched; the attention's batches map query heads to KV heads.
CPU reference product ✅ src/train/gemm_train.c:233 (tr_gemm) Bit-identical across SIMD levels.
Run-time loading ✅ src/core/opencl/cl_loader.c:32-34 (LoadLibraryA, dlopen), 68 (oklm_cl_load) The model for a HIP loader.
OpenCL types outside their modules ✅ none search for cl_mem, cl_kernel, cl_int, clEnqueue, cl_context, cl_command_queue outside src/core/opencl/ and src/train/train_cl.c No leaks.
Memory shared between OpenCL and HIP ✅ (R2) src/train/train_cl.c (tr_cl_alloc, shared_addr); src/core/opencl/cl_loader.c (clSVMAlloc) With --backend rocm the trainer's buffers are shared virtual memory wrapped in cl_mem; rocBLAS computes on the same bytes.
The trainer's products through rocBLAS ✅ (R2) src/train/train_cl.c (gemm, after_rb); tests/train/test_train_cl.c (the rocm pass) Large single products routed, hand-overs only on a switch; the device tests pass against the CPU; Nano 1.43 x, SmolLM2 1.26 x a step.
Build switches ✅ none Makefile:157-159 (-ldl), 239 (cl_loader.c), 535-539 (embedded kernels) Devices found at run time; no USE_*.

Math and training

Part Status Evidence Notes
Training kernels, CPU and OpenCL ✅ src/train/layers_train.c, train_kernels.cl, declared side by side in train_internal.h Norms, attention, GELU, SwiGLU, RoPE, dropout, cross-entropy, AdamW, gradient norm.
Layout ✅ include/oklm/core/tensor.h; train_internal.h:15-17 Row-major; hipBLASLt is column-major (operands swapped).
Test harness ✅ tests/oklm_test.h; tests/tolerances.h:87 (TOL_TRAIN_DEVICE 1e-4); tests/train/test_train_cl.c Finite differences, device against CPU, llm.c oracle.
LoRA / adapters ✅ (R3–R5, R7) src/train/train.c (layout_lora, lora_forward, lora_backward); tests/train/test_train.c (test_lora); tests/train/test_train_cl.c The paper's naming, Q/K/V and gate/up separately on the packed products; finite differences on five architectures; devices against the CPU. ADR-0020.
Frozen parameters ✅ (LoRA) src/train/train.c (G(), zero_grad, the update over [lora_off, n_params)) With LoRA the model's weight gradients are never computed and AdamW covers the adapters only.
Activation recompute ✅ train.c alloc_acts, block_forward, head_chunk, backward_rows recompute / oklm train --recompute: each block's input kept, its activations computed again before its backward pass (the same gradients to the bit); the head's logits held a chunk of rows at a time (a frozen LoRA head's gradient taken in the forward pass); activations 3 to 8 times smaller for 21 to 51 % more time a step (training.md, Speed). test_train.c, test_train_cl.c test_recompute, test_chunked_head
Quantized frozen base, transposed quantized product ✅ train.c load_packed, unpacked; train_cl.c tr_cl_dequantize; kernels.cl dequant_rows quantized_base / --quantized-base: with LoRA the blocks' matrices stay in the file's types, each unpacked into one F32 scratch before its products (dX = dY W included), the same results to the bit (Qwen3-4B Q4_K_M: 15.4 GB of weights to 3.8, 5 % slower). The token embeddings and output head packed too (a token's row unpacked as looked up, the head by tiles of rows), Qwen3-4B 2.6 GB for a 2.4 GB file. GPT-2's embeddings stay F32. test_train.c, test_train_cl.c test_quantized_base, test_quantized_head, test_dequantize
Adapter files ✅ (R7) src/train/checkpoint.c (write_adapter, oklm_trainer_load_lora); src/io/lora.c (oklm_lora_merge); apps/oklm.c (train --lora, lora-merge, --lora) llama.cpp's format; llama.cpp's --lora perplexity matches OKLM's merged model (27.3985 / 27.3989).

Baseline

OKLM_CL_PROFILE=1 on the gfx1100, 2026-11-04: the Llama Nano (16 x 256) spends 38.6 ms of a 47 ms step in 153 products a step (69 %, about 3.6 TFLOP/s); the SmolLM2-135M fine-tune (4 x 4 x 128) 429 ms of a 528 ms step in 3135 products a step (69.5 %, about 3.8 TFLOP/s).

ROCm conflicts and corrections (⚠️):

  1. The plan's API constraint expects hipblaslt/hipblaslt.h to be C-compatible; it is not (hipblaslt.h:54-56). The C symbols are reached through a run-time loader with OKLM's own declarations instead (decision 1).
  2. The plan expects a HIP backend for training only; OKLM already trains on this GPU through OpenCL, so HIP brings hipBLASLt's products (69 % of a step) and nothing else: the design note proposes routing products from the trainer's OpenCL device rather than a new backend, if the two runtimes share memory.
  3. The plan reaches the 27B base within R7; the trainer's F32 path does not fit it in 20 GB (108 GB of weights alone), so it is split out.

MCP training

The MCP tool-use fine-tuning specification mcp_training_spec.md against what exists, for its T0 audit; the plan built on it is mcp-training-design.md. T0 is read-only: no training code. Legend as above.

# Item State Where Note
T0.1 The inference prompt and tool-call shape ✅ chat_template.c oklm_chat_template_render; tools.c tools_json; agent.c:492-509; tool_calls.c parse_hermes:378, oklm_tool_format_detect:21 Qwen3's Hermes/ChatML template renders <tools> in the system turn and the call as <tool_call>{"name","arguments"}</tool_call>; captured in the design note. OKLM_LOG_LEVEL=DEBUG logs each raw turn (agent.c:2736).
T0.2 Schema validation (constrain and check) ✅ grammar.h oklm_json_schema_to_grammar:160, oklm_grammar_accept_text:100, oklm_grammar_complete:107; agent.c agent_grammar A tool's parameters schema becomes GBNF (ADR-0009); generation is constrained to it, and a candidate call is checked by accepting its text to completion. The data validator's function.
T0.3 Training mechanism ✅ (from R7) oklm train --lora; io/lora.h oklm_lora_merge; ADR-0020, ADR-0021; --quantized-base LoRA on every backend, adapter files, a quantized base so the 8B fits 20 GB. Missing and this plan's to add: the data (T1), the hyperparameters and the validation loop (T2/T3).
T0.4 Reference datasets (format only) ✅ tests/evals/03-mcp-tool; tests/harness/test_mcp.c Hermes function-calling corpora share the shape; the faithful source is capturing real oklm agent runs against the mock server. None imported.
T0.5 Evaluation harness ✅ tools/eval_agent.sh; tests/evals/; tests/harness/test_mcp.c:119-136 (mock MCP: echo, add, fail, big, slow) Scripted tasks judged by what the run left; 03-mcp-tool already calls a tool end to end; the mock server stands in for a real one, held-out tools for T3.
T0.6 Decisions ✅ mcp-training-design.md ## Decisions Data format (the in-process rendering), reasoning (a short <think> kept, capped), base (Qwen3-8B), proceed now (M15 and R7 done).
T1 Data capture ✅ tools/mcp_zoo.py, mcp_data.py (tasks, check, gate), mcp_run.sh, make_mcp_data.sh The tool zoo's training tools, tasks of the five categories, each run judged (answer, the tools needed, only its tools, the answer after the results), the gate (every call parsed and fitting its schema, duplicates, a held-out tenth). 117 conversations from 200 tasks on Qwen3-8B.
T2 Fine-tune (chat-data trainer) ✅ oklm train --chat-data --lora 16 --quantized-base --recompute; tools/mcp_loop.sh Rank 16 on the Q4_K_M base, 6144-token sequences, 30 steps a round (46 min); held-out loss 0.085 to 0.061. ROCm cannot allocate the base's shared memory; OpenCL runs it.
T3 Validation loop ✅ tools/mcp_loop.sh, mcp_data.py metrics; oklm agent --no-tool-grammar Base and two rounds, the grammar off: trained tools 8 to 11 of 15 tasks, schema-valid calls 78 to 94 %; held-out tools 7 of 9 then 5; JSON always valid (mcp-training-design.md).

T0 corrections (⚠️): none. The plan's assumptions hold — the tool-call shape, the schema path, the LoRA mechanism, the eval harness and the mock server all exist; T1 onward is data and training, not new engine code.

RAG

Audit of rag_spec.md (its K0), 2026-11-08, the same legend; ⚠️ marks a row where the spec's "What OKLM already has" table was wrong or incomplete (corrected there). The design built on this audit is rag-design.md, the index file adr/0022-rag-index-format.md. OKLM has no retrieval yet, but most of the pieces under it exist: bidirectional attention, LayerNorm with bias, exact GELU, rope and SwiGLU as ops (the vision and Whisper encoders already run on them), the final hidden state of a decoder (oklm_context_params.hidden), WordPiece and Unigram tokenizers, products of F32 rows against F16 / Q8_0 matrices with a top-k op (a search is one of them), an atomic GGUF writer and memory-mapped reads, System One scoring, the agent's ToolSearch, memory files, the debug log and the OpenTelemetry export. What is missing is the text encoder itself, pooling, chunking, the index, BM25, the cross-encoder and the glue.

Retrieval primitives

Primitive Status Evidence Verdict Notes, change needed
Encoder forward pass (bert, nomic-bert, XLM-R) ❌ model.c:1166-1182 (the architectures accepted: no bert); model_internal.h:28-32 (two families, ARCH_LLAMA and ARCH_GPT2) NEW (K1) ARCH_BERT and src/model/arch_bert.c: post-norm blocks, token types, learned positions (bert) or NEOX rope with SwiGLU (nomic-bert); XLM-R is written as bert by llama.cpp's converter (rag-design.md).
Encoder building blocks ✅ ops.h:46 (LayerNorm with bias), 50 (GELU_ERF), 51 (SwiGLU), 52 (rope), 53 (GET_ROWS), 406 (bidirectional attention); vision.c:285-340 and audio.c:471 use them REUSE ⚠️ the spec said "none": the vision and Whisper encoders are encoders already. On OpenCL, bidirectional attention runs on the CPU (backend_cl.c:2203): K1 adds it to the kernel or accepts the fallback, measured. No ALiBi (jina-bert-v2 left out).
Decoder-based embeddings (Qwen3-Embedding) 🟡 hf_config.c:40 (Qwen3ForCausalLM); model.h:153 (hidden), 293 (oklm_get_hidden); model.c:2069 (only ARCH_LLAMA) EXTEND (K1) ⚠️ the spec said last-token pooling did not exist: the final normalized hidden state of every token is already kept on request; what is missing is taking the last row, L2-normalizing, appending `<
Pooling (CLS, mean, last), normalization ❌ none; llama.cpp's numbering (NONE 0, MEAN 1, CLS 2, LAST 3, RANK 4) read from <arch>.pooling_type NEW (K1) src/rag/embed.c; GGUF key first, else sentence-transformers' 1_Pooling/config.json, else the family's default.
Embedding tokenizer, WordPiece 🟡 tokenizer.h:51 (OKLM_TOK_WPM); tok_hf.c:545, 593, 623 (from tokenizer.json), 310-316 (BertProcessing: [CLS] and [SEP] added); tok_gguf.c:111, 281-287; test_llama_vocabs.c:47, 166 (bert-bge parity with llama.cpp); test_tokenizer_parity.c:214 REUSE, EXTEND (K1) ⚠️ from a GGUF bert vocabulary OKLM adds [CLS] but not [SEP]: add_eos defaults to 0 and tokenizer.ggml.seperator_token_id is not read, while llama.cpp always ends a WordPiece text with SEP (llama-vocab.cpp:2768-2774, 3910-3936). K1 reads the separator and adds it.
Embedding tokenizer, Unigram (XLM-R: bge-m3, bge-reranker-v2-m3) ✅ tokenizer.h:52 (OKLM_TOK_UGM, GGUF t5); src/tok/ugm.c REUSE XLM-R's GGUF uses the t5 model with <s> … </s>; checked against llama.cpp in K1.
Pair encoding (query, passage) for a cross-encoder ❌ none NEW (K4) [CLS] q [SEP] d [SEP] (WordPiece) or <s> q </s></s> d </s> (XLM-R), token type 1 on the passage where the model has two types.
Test files of the default model ⚠️ tests/public_models.txt:48-50 (tokenizer.json of bge-small-en-v1.5); models/bge-small-en/config.json (_name_or_path bge-small-en, v1) EXTEND (K1) Only the tokenizer is there, not the weights; the config.json beside it is the v1 model's. K1 adds the v1.5 weights (safetensors and GGUF) to the list with their sha256.
Document loaders 🟡 ingest.h:42-48 (text, JSON, HTML, DOCX, PDF), 61 (oklm_ingest_file), 116 (oklm_ingest_pdf_pages); ingest.c:97-110 (CRLF made LF); oklm.c attach_doc (--doc: the whole text in the prompt); tools.c:456 (Read of DOCX and PDF) REUSE, EXTEND (K2) Offsets of chunks are offsets in the extracted text; for plain text the line ends change, so the index keeps line numbers too. Pages are known for PDF only (pdf_pages), kept as the chunk's page.
Chunkers ❌ none (chunk in src/ is prefill pieces and stream pieces only) NEW (K2) Fixed, recursive (Markdown headings, paragraphs, sentences), semantic, code-aware (braces and indentation, or LSP symbols: lsp.c:770-773).
Vector store ❌ none; the parts: ops.c:233 (oklm_matmul: F32 rows against weights of any computable type), 399 (oklm_topk); gguf.h:394, 417 (tensors, streamed), 425; gguf_write.c:507-516 (temporary file, then oklm_file_replace); file.h:46 (oklm_file_map), 109, 245 NEW (K2) on REUSED parts Vectors stored as a GGUF tensor [dim, n_chunks] in F32, F16 or Q8_0: one query is a product and a top-k on the existing kernels and threads (ADR-0022).
Model identity for the index header ✅ kv_file.c:180-210 (oklm_model_id: architecture, sizes, tensor table, sampled weights) REUSE The index records it with the pooling, normalization and prefixes, and refuses another model.
Keyword search 🟡 tools.c:1349 (t_grep: regular expressions, unranked) NEW (K3) BM25 (k1 1.2, b 0.75) over the chunks, postings in the index; the analyzer lowercases and splits on Unicode word boundaries (unicode.c), not the model's subwords.
Fusion ❌ none NEW (K3) RRF (k = 60) and weighted sums of normalized scores.
Reranker ❌ none NEW (K4) Cross-encoder = the K1 encoder plus cls / cls.output (llama.cpp's names).
Relevance scoring by the generator ✅ decide.h:78 (oklm_decide_question); decide.c:237 (oklm_decide_eval: levels from one forward pass); server.c:2444 (/v1/systemone, /v1/decide); src/server/decide.c:208 (srv_decide) REUSE (K4 fallback, K5 evaluator) A question "does this passage answer the query?" with levels relevant / partly / no gives K5's verdicts and their probabilities.
Evaluators (retrieval metrics) ❌ none: the agent evals measure pass rate, turns, tokens, time (Makefile:731, tools/eval_agent.sh, tests/evals/: 17 tasks) NEW (K1) oklm rag eval (recall@k, MRR, nDCG@10) and make rag-eval (rag-design.md, "Evaluation").
Tool registry ✅ tools.c:3300-3329 (built-in table), 3510 (oklm_tools_json); agent.c:641-694 (agent_tools: built-ins, the program's own tools, Agent / SendMessage, ToolSearch); mcp.c:1834 (oklm_mcp_sync_tools); tools.h:111 (searchable skills); plugins.c:124; agents.c:144 (sub-agent definitions) REUSE Every source K6 embeds is already enumerable in one place (all_tools_json and the skills array).
Tool selection 🟡 agent.c:566 (ToolSearch's definition), 606 (is_deferred), 3671-3797 (run_tool_search); tool_index.c:603-628 (oklm_tool_keyword_score: 3 a word in the name, 1 in the description); prompt.c:194-275 (put_deferred: built-ins in a line, each MCP server in its own), 356-376 (skills past the 2000-token budget left to ToolSearch); oklm.c cmd_agent (the default deferred list and deferredTools) EXTEND (K6) ⚠️ the spec placed ToolSearch in tools.c: it is in agent.c and prompt.c. Keyword match only; K6 adds an embedding rank behind the same tool.
Prompt assembly, context injection ✅ prompt.c:277 (oklm_prompt_build); agent.c:331 (agent_push_meta: reminders); compact.c:348 (rolling_summary); oklm.c attach_doc REUSE Retrieved chunks enter as a reminder (agent) or beside --doc (run, chat), so the system prompt's bytes and the prefix cache stay unchanged.
Memory 🟡 memory.c:701 (oklm_memory_load), 809 (oklm_memory_render); session.c:618, 1188 (oklm_session_turns), 1439 (oklm_session_list) EXTEND (K7) Memory files are put in the prompt whole; transcripts are listed and replayed, never searched.
Caching 🟡 server.c:50, 79, 424-452 (media embeddings by content hash); prefix_disk.c:167 (--prefix-dir); model.h:812 (oklm_kv_save) REUSE, EXTEND (K2) Nothing caches text embeddings; the index is that cache (chunks keyed by their hash, re-embedded only when changed), and the server keeps an LRU of query embeddings.
Telemetry 🟡 telemetry.c:573 (oklm_telemetry_debug), 601 (oklm_telemetry_event), 10 (OTLP export); server.c:2295 (/api/stats); dashboard.c EXTEND (K5) Retrieval decisions (queries, rewrites, hits and scores, verdicts, fallback) as debug lines, agent events, OTLP spans and /api/stats counters.
Rate limiting 🟡 server.c:264 (503 with Retry-After past --queue), 330 (API keys); agent_http.c:53 (429 retried) REUSE No per-key limits; embedding and rerank requests share the queue and its 503. WebSearch fallbacks capped per request (K5).
Web fallback ✅ tools.c:3195 (WebSearch through SearXNG), 2850 (WebFetch) REUSE (K5)

The taxonomy

Group Capability Status Evidence Verdict Notes, change needed
Foundational Vector RAG ❌ the primitives above NEW (K1, K2) Encoder, chunker, index, exact search.
Hybrid RAG ❌ tools.c:1349 (Grep only) NEW (K3) BM25 and fusion in the same index.
Graph RAG ❌ none NEW (K8) Entities and relations extracted by the generator (decide.c and grammars: grammar.h).
Agentic, adaptive Agentic RAG ❌ the tool table tools.c:3300 NEW (K7) A Retrieve tool over the project's index.
Adaptive RAG ❌ decide.c:237 NEW (K7) on REUSE A router question (none / one / several retrievals).
Self-RAG ❌ decide.c:237 NEW (K8) on REUSE Support and usefulness scored by System One.
Corrective RAG ❌ decide.c:237; tools.c:3195 NEW (K5) on REUSE Evaluator verdicts, rewrite, WebSearch, "no reliable source".
Agent-centric Hierarchical tool RAG 🟡 agent.c:3671 (keyword ToolSearch); prompt.c:194 (deferred tools grouped by MCP server) EXTEND (K6) Type to Service to Tool already shows in the prompt's grouping; the rank becomes semantic.
Multimodal RAG 🟡 vision.c:285 (SigLIP image embeddings into the language model, not a joint space); audio.c; video.c EXTEND (K8) Captions first, a joint encoder only if measured to be needed.
Conversational, memory RAG 🟡 memory.c:701; session.c:1188 EXTEND (K7) Query rewriting from the conversation; transcripts and memory files indexed.
Cross-cutting Chunking ❌ none NEW (K2)
Reranking ❌ decide.c:237 as the only scorer NEW (K4)
Query rewriting, expansion ❌ compact.c:348 (the summary turn is the nearest pattern) NEW (K5, K7) One generator call with a fixed prompt, logged.
Evaluation harness 🟡 Makefile:731; tools/eval_agent.sh; oklm.c cmd_ppl EXTEND (K1) make rag-eval beside make eval.
Caching, observability, budgets 🟡 the caching and telemetry rows above EXTEND (K5, K9) Token budget for injected chunks (--rag-tokens), latency per stage.
Graceful degradation ❌ none NEW (K5) Never an invented citation; an index of another model refused, not misread.

Capability matrix

DONE: usable as is. PARTIAL: exists, needs the change named. MISSING: new code.

Capability State Change needed Step
Encoder ops (LayerNorm, GELU, rope, SwiGLU, bidirectional attention) DONE the OpenCL bidirectional path (now the CPU) K1
BERT-family forward pass MISSING ARCH_BERT in model.c, src/model/arch_bert.c, src/io/names_bert.c, BertModel / XLMRobertaModel / NomicBertModel in hf_config.c K1
Decoder embeddings PARTIAL last row of oklm_get_hidden(), no output head, EOS appended K1
Pooling, normalization, oklm_embed() MISSING src/rag/embed.c, include/oklm/rag/embed.h K1
WordPiece from GGUF PARTIAL read tokenizer.ggml.seperator_token_id, add SEP K1
oklm embed, /v1/embeddings MISSING cmd_embed in apps/oklm.c, src/server/embed.c K1
RAG evaluation MISSING src/rag/eval.c, oklm rag eval, tools/rag_eval.sh, make rag-eval, tests/rag/docs_questions.jsonl K1
Loaders DONE chunk offsets, lines, PDF pages K2
Chunkers MISSING src/rag/chunk.c, src/rag/chunk_code.c K2
Index, exact search MISSING src/rag/index.c (ADR-0022) on the GGUF writer, oklm_matmul, oklm_topk K2
oklm rag index / search / info MISSING cmd_rag in apps/oklm.c K2
BM25, fusion MISSING src/rag/bm25.c, src/rag/fuse.c K3
Cross-encoder, /v1/rerank MISSING cls head in arch_bert.c, oklm_rerank(), the route K4
Generator scoring fallback DONE a relevance question over decide.c K4, K5
--rag in run, chat, serve MISSING src/rag/pipeline.c; gen_opts beside --doc; the server's per-request field K5
Corrective loop, logging MISSING evaluator stage, rewrite, WebSearch fallback, trace in telemetry and /api/stats K5
Tool selection by retrieval PARTIAL src/harness/tool_index.c, run_tool_search ranked by embeddings, toolSearch.mode setting K6
Agentic, adaptive, conversational retrieval MISSING Retrieve tool, router, rewrite, session and memory index K7
Graph, self-critique, multimodal MISSING src/rag/graph.c, self-critique questions, captions K8
Caching PARTIAL chunk-hash reuse in the index, query-embedding LRU in the server K2, K5
Telemetry PARTIAL retrieval events and counters K5
Rate limiting DONE the server's queue covers the new routes K1, K4

K0 corrections (⚠️), made in the spec's table: encoders' ops exist (the vision and Whisper encoders); decoder hidden states exist; ToolSearch is in agent.c and prompt.c, not tools.c; a GGUF WordPiece vocabulary gets no [SEP]; the bge files present are the v1.5 tokenizer and a v1 config.json, no weights; sentence-transformers needs PyTorch, which ADR-0015 rules out, so the second reference is a numpy float64 encoder (rag-design.md, "Test references"); the agent evals are 17 tasks.