Kernforge Detailed Usage Guide

July 23, 2026 · View on GitHub

This document explains how to use the currently implemented Kernforge features in real engineering workflows, with concrete examples and recommended command sequences.

Reference point:

Codebase snapshot: 2026-07-24

Intended readers:

Windows security engineers
Anti-cheat engineers
Kernel and user-mode telemetry engineers
Driver, signing, symbol, and package readiness engineers
Unreal Engine security and integrity engineers

Goals of this guide:

Explain real usage patterns instead of just listing features.
Show which command combinations fit which kinds of problems.
Teach the full loop of analyze-project -> analyze-performance -> investigate/simulate -> find-root-cause or fuzz-func -> review/edit/plan -> verify -> evidence/memory/hooks.

1. The Best Way To Think About Kernforge

Kernforge can be used like a normal coding CLI, but its strongest current value now comes from building a reusable project knowledge pack before running sensitive engineering changes through the rest of the loop.

The best current loop looks like this:

If the workspace is large or unfamiliar, run /analyze-project first.
Use /analyze-performance to turn the latest knowledge pack into a bottleneck lens when performance or startup paths matter.
If live state matters, use /investigate to capture the current system state.
If an extra risk lens matters, use /simulate to evaluate tamper, visibility, or forensic blind spots.
If you already have a user-visible symptom and need to narrow likely causes, run /find-root-cause.
If attacker-controlled parameter behavior matters, run /fuzz-func for source-level fuzz reasoning; when a seed handoff is useful, Kernforge prints /fuzz-campaign run as the next step.
Use /review selection, /edit-selection, /review plan, or /new-feature to drive the work.
Run /verify to execute the verification plan.
Use /evidence ... and /memory ... to inspect both recent signals and longer-lived context.
Follow the printed handoff blocks and /session continuity packet after analysis, investigation, simulation, performance, root-cause, fuzzing, verification, evidence, memory, checkpoint, feature, worktree, jobs, and task-owner actions instead of memorizing the command order.
Let hooks act as the final policy layer before push or PR.

Practical interpretation:

analyze-project builds a reusable architecture map instead of a disposable summary.
analyze-performance extracts likely hot paths and bottlenecks from the latest architecture knowledge.
investigate captures what is happening live.
simulate highlights risk-oriented weak spots using lightweight heuristics.
find-root-cause turns a symptom, trigger, expected invariant, and observed failure into worker/reviewer causal analysis.
fuzz-func synthesizes attacker input states, counterexamples, and branch deltas from real source-level guard/probe/copy/dispatch behavior.
verify turns code changes and recent context into a concrete validation plan.
evidence stores structured recent signals.
memory keeps conclusions across sessions.
hooks turn that accumulated context back into guardrails.

2. Core Features And When To Use Them

Input And Cancellation Handling

Purpose:

Keep prompt cancel and in-flight request cancel distinct on Windows consoles.
Avoid missing brief Esc taps during a running request.
Prevent leftover console Esc input from auto-canceling the next prompt after request cancel.

Current behavior:

Esc while typing cancels only the current prompt input.
Esc during model response wait cancels the in-flight request.
On Windows, Kernforge combines async key-state checks with console input polling so short Esc taps are still recognized.
After request cancel, Kernforge waits briefly for Esc release and clears pending console input before opening the next prompt.
Assistant streaming now suppresses empty leading chunks, flushes cleanly before progress lines, and breaks repeated follow-on preambles onto separate lines for readability.
Generic waiting text is collapsed so the thinking indicator does not repeat the same status twice.
The thinking elapsed timer is rebased at phase boundaries, and abnormal stale values are clamped at the 2-hour display mark.
Repeated blank streamed chunks are converted into a compact working status instead of printing empty lines.
If a final streamed answer appears to stop mid-sentence, Kernforge asks the model to continue once and merges the continuation before returning to the prompt.
Pressing Enter on an empty main prompt is ignored so empty turns do not clutter the session transcript.
progress_display controls progress visibility and defaults to quiet, so routine turns stay Cursor/Codex/Grok-like. /progress-display quiet|compact|auto|stream changes it from the REPL: quiet keeps mid-turn activity in the footer, compact adds durable working notes, auto keeps durable tool/model events without shell-body spam, and stream persists every update for detailed debugging.
OpenAI-compatible and OpenAI Codex streaming providers emit tool-call construction events so users can see when the model is preparing a tool call and when its arguments are ready.
DeepSeek and other OpenAI-compatible follow-up requests normalize saved tool transcripts before replay. Orphaned tool results are dropped, and missing tool-call responses are synthesized as aborted outputs so provider-side message validation does not reject recovered sessions. Runtime guidance paths that supersede a tool-call batch persist explicit NOT_EXECUTED outputs before the guidance message instead of recovering internal tool output as user context.
Post-change diff review does not import final-answer coding-harness state. Worker/causal-evidence blockers remain visible for final/completion-audit gates, but they do not become post-change code-review blockers.
The REPL opens with a compact branded banner and keeps assistant output separate from tool and verification activity lines.
Before each new prompt, Kernforge prints a compact operator footer with cwd, provider/model, runtime gate, permission profile, progress display, MCP, skills, verification, memory, warnings, and provider-route errors. The footer uses the same renderer and compact status vocabulary as /status, and it splits into two lines on narrow terminals.
!cd and directory-listing shortcuts resolve from the REPL current directory while keeping the workspace boundary fixed. !cd .. can move upward inside the workspace or active worktree, but cannot cross above that boundary.
Direct ! shell commands print a one-line result summary before output with ok/failed state, exit code when available, elapsed time, output line count, and command preview. Failed commands also include the first useful error line and a short next action.
Model-driven run_shell completion summaries include the output line count before the first meaningful output line.
Direct ! shell output uses a compact preview when output is long. The transcript keeps the first 80 and last 20 lines, or applies a character budget for very long single-line output, then marks the header as collapsed and prints the omitted line or character count. Korean locales use Korean collapse markers.

Runtime Inspection And Approval State

Purpose:

Distinguish between current session state and merged effective settings.
Make write, diff, shell, and git approvals visible without opening config files.
Keep git-mutating actions on a separate approval path from normal file edits.

Useful commands:

/status
/config
/provider status

Current behavior:

/status shows session and runtime state. It starts with the same compact operator summary used by the prompt footer: cwd, provider, gate, permission profile, progress display, MCP, skills, verification, memory, warnings, and route errors. Detailed session id, approvals, selection state, verification state, MCP counts, and runtime gate ledger remain below. Use runtime_gate, review_freshness, blocker/warning counts, and next_command to decide whether review, verification, or completion audit needs repair before final answers or write-side actions.
/config shows effective settings such as provider defaults, token limits, locale behavior, hook settings, verification defaults, and request-runtime migration settings.
/provider status shows the active provider, normalized endpoint, API key presence, and provider-specific budget visibility.
For OpenRouter, /provider status performs a live lookup of key-level limit_remaining and usage, and it also shows account credits when the key is a management key.
For DeepSeek, /provider status performs a live /user/balance lookup when an API key is configured and shows the provider's dynamic concurrency guidance.
For OpenAI and Anthropic, /provider status intentionally shows officially documented billing and usage visibility limits instead of inventing a live balance endpoint.
kernforge --version, kernforge -version, and kernforge version print the executable version before config/session loading. On Windows release builds this is the PE FileVersion; unstamped developer builds fall back to the embedded app version.
kernforge --help includes the same version at the top of the general help text.
Permission prompts use the same keys: y allows once, a allows that action for the current session, n denies, and Esc cancels.
Diff preview asks y=open once, a=accept edits for session, n=cancel edit, and Esc=cancel; automatic verification asks y=run once, a=session auto-run, n=skip, and Esc=cancel.
Git-mutating tools such as git_add, git_commit, git_push, and git_create_pr use a separate Allow git? session approval.
Git-mutating tools are intended for explicit user requests rather than normal review or edit turns.
/hooks prints the same compact runtime gate summary as /status, so hook/policy checks do not invent a second interpretation of review freshness.

Decision Journal And Cross-Project Preference Evidence

Purpose:

Capture why the user chose one material implementation approach and rejected the alternatives.
Aggregate explicit judgment evidence across repositories without adding personal journal files to each worktree.
Derive conservative project, domain, and global preference rules without automatically forcing later choices.

Command:

/decision

Current behavior:

On a file-mutation request, the model may propose a checkpoint after inspecting the relevant code and before the first edit. The runtime requires two to four viable options, exactly one advisory recommendation, and material-fork confidence of at least 0.65; style choices and decisions already fixed by the user are excluded.
The user must explicitly select one option or Other, explain the selection, and explain why every listed alternative was rejected. Enter does not accept the recommendation.
A canceled or non-interactive checkpoint remains pending in the session. Until it is completed, only the decision tool and tools explicitly declared read-only are allowed; other custom and MCP tools also fail closed.
Completed records, immutable prior revisions, and a rebuildable preference profile live under ~/.kernforge/decision-rationales/. Project identity groups temporary worktrees with their base repository while keeping moved or separately cloned paths distinct.
/decision opens one authenticated loopback dashboard for current/all-project browsing, correction, revision history, soft delete/restore, profile-rule overrides, rebuild, and filtered JSON export. It has no subcommands and requires a long-lived interactive KernForge process.
Preference promotion requires repeated explicit user evidence and detector_confidence >= 0.80. Derived rules are currently visible evidence for a future consumer; the active agent does not automatically apply them.
The default export removes selected local runtime metadata but retains project hashes, fingerprints, timestamps, and rationales, so it is privacy-reduced rather than anonymous. Secret redaction is best-effort and the plaintext local files are access-controlled, not encrypted.

Detailed contract: Decision Journal or Decision Journal (한국어).

Prompt Intent Routing

Purpose:

Keep analysis and explanation requests read-only by default.
Keep explicit fix requests tool-driven instead of drifting into prose-only advice.
Reduce accidental patch handoff or accidental git mutation during normal code review.

Current behavior:

Requests that ask to analyze, explain, diagnose, review, or document default to read-only investigation mode unless they also explicitly ask for a fix.
Requests that explicitly ask to fix code keep edit tools available and Kernforge nudges the model back toward direct tool use if it tries to hand the patch back to the user.
Git staging, commit, push, and PR creation are blocked unless the user explicitly asked for that git action.
Each turn gets a RequestEnvelope before the model call. It records the primary request class, whether file mutation, git mutation, web research, and verification are allowed, and whether the request is a draft-only goal prompt or document-authoring turn.
Tool exposure is derived from that envelope. Review-only and plan-only turns keep read tools but hide edit and git tools; explicit edit turns expose edit tools; latest/current research turns can expose web-research tools; explicit git turns expose git tools without implying normal file edits.
Tool calls are normalized and validated at the runtime boundary. Malformed, incomplete, unsupported, forbidden, skipped, or aborted calls are converted into synthetic NOT_EXECUTED/error results before the next model turn, so provider replay and recovery prompts remain valid.
Draft-only goal prompt requests stay non-mutating unless the user saves the prompt, passes it to /goal, or explicitly asks to run it. Document-artifact requests are allowed to write the requested artifact and use artifact-quality/final-answer gates instead of being forced through unrelated code-review loops.
Continuation turns after compaction or history rewrite preserve the current mutable patch context and verification requirement, while orphan tool results are dropped and missing tool-call results are synthesized before provider replay.
The optional request runtime migration config is:

{
  "request_runtime": {
    "mode": "disabled",
    "enabled_classes": ["review_only", "plan_only", "document_authoring", "explicit_edit", "git", "research", "default"]
  }
}

Use disabled for legacy behavior, shadow to compare legacy and v2 decisions while still executing legacy behavior, and enabled to enforce v2 decisions for the listed classes. Shadow divergence logs are sanitized and constrained to .kernforge/request_runtime_shadow; they contain request class, exposed/disabled tools, intervention kinds, and final-gate differences, not full prompts or provider transcripts. 10. The request scenario replay matrix lives under cmd/kernforge/testdata/request_scenarios and covers Korean review/edit requests, plan-only, draft-only goal prompts, document authoring, latest research, explicit/non-explicit git, empty stops, orphan tool results, repeated read loops, generated-doc final-only, unavailable verification, and compaction/history rewrite.

Self-Driving Work Loop

Purpose:

Keep implementation, fix, and execution requests from stopping at analysis.
Seed TaskState and TaskGraph with an inspect, implement, verify, summarize loop.
Keep the task in recovery instead of marking it complete when post-edit verification fails.

Current behavior:

Requests such as "implement this", "fix this", "handle the remaining items", or "run the tests and finish" become self-driving candidates.
If an independent cross review route is configured, Kernforge can use it for reviewer/planner preflight; otherwise it uses the active main model and deterministic gates.
Read-only prompts such as "why did that error happen?", "what is the current state?", or "analyze this" do not start an automatic edit loop.

Proactive Suggestion Dashboard

Purpose:

Collect Kernforge's current next-action suggestions in one view.
Compare analysis stale markers, verification gaps, evidence gaps, and changed paths in the same dashboard.
Link each suggestion to the relevant dashboard or command.

Useful commands:

/suggest
/suggest accept <id>
/suggest dismiss <id>
/suggest mode <observe|suggest|confirm>
/suggest dashboard --html

Current behavior:

/suggest dashboard --html renders integrated signals and suggested next actions together.
Suggestion cards include related command chips, evidence refs, and dashboard links such as /verify dashboard --html, /evidence dashboard --html, and /analyze-dashboard.
Cards include /suggest accept <id> and /suggest dismiss <id> chips so repeated suggestions can be managed.
/suggest candidates are synchronized into TaskGraph as suggest:<id> nodes with ready/in_progress/completed/canceled states.
In /suggest mode confirm, accepting a suggestion only runs safe commands such as /verify, dashboards, /docs-refresh, /automation add, and /review pr.
Accepted or dismissed suggestions are also promoted into persistent memory as preference records.

Session Dashboard

Purpose:

Show the current thread, task graph, automation state, changed files, and artifact refs in one local HTML view.
Make long-running sessions easier to resume without reading the full transcript.
Surface due or failed automation together with open task graph nodes and recent runtime events.

Useful commands:

/session dashboard --html
/session events tail 20
/session events export

Current behavior:

Writes .kernforge/session_dashboard/latest.html for the current workspace.
Includes session/provider metadata, context size, task status counts, open task graph nodes, automation due/failed/paused counts, recent conversation events, changed files, background jobs/bundles, and artifact refs.
Records the dashboard path in the conversation event log and opens it automatically in interactive mode when possible.
/session events tail [n] prints recent session events as JSONL records, while /session events export [path] writes a durable local event stream to .kernforge/events/<session-id>.jsonl and .kernforge/events/latest.jsonl.

Continuity Packet and Local Jobs

Purpose:

Recover naturally from failed local shell commands, failed verification, or stale background work without pasting logs again.
Give a long-running task a local resume packet that survives compaction, model switches, and handoff.
Let the terminal user inspect persistent background jobs and bundles directly, not only through model tool calls.

Useful commands:

/session continuity
/session continuity continue Codex parity work
/session recover
/session recover continue failed verification
/session recover execute-safe continue failed verification
/session audit
/session audit finish Codex parity work
/session jobs status
/session jobs check latest
/session jobs bundle latest
/session jobs cancel <job-id> stale verification
/session jobs cancel-bundle <bundle-id> superseded
/worktree list
/worktree enter
/worktree attach <path> [branch]

Current behavior:

/session continuity writes .kernforge/continuity/latest.md and .kernforge/continuity/latest.json.
The packet includes active/base workspace roots, branch, provider/model, changed files, open task graph nodes, worktree leases, active edit loop, active failure repair, latest verification failure, background jobs/bundles, recent runtime errors, artifact refs, recovery actions, next commands, and a suggested continuation prompt.
Direct !shell failures are recorded as command_error conversation events, so later /session continuity and recent-error answers can recover from the failure without requiring the user to paste the output again.
/session jobs syncs and prints persisted background job/bundle status, then supports direct polling and cancellation by id or latest.
/worktree list shows the session worktree, task-owner editable worktree leases, and git worktree list --porcelain in one view before resuming or switching roots.
/worktree enter re-enters the recorded isolated worktree after /worktree leave, and /worktree attach <path> [branch] attaches an existing worktree as an unmanaged session worktree.
/session recover writes .kernforge/recovery/latest.md and .json as a narrower failure runbook from the latest error, verification failure, failure-repair state, background jobs, open tasks, and next commands. The runbook includes a structured diagnosis, stable failure signature, action plan status, and execution log.
/session audit writes .kernforge/completion_audit/latest.md and .json with blockers, warnings, required artifacts, latest verification, open tasks, background jobs, recent errors, and coding harness evidence before finalizing.
/session recover execute-safe runs only safe-auto recovery actions and records their status. Shell replay is limited to whitelisted verification/status commands without chaining or redirection.
Slash actions are validated against their recorded artifacts: failed /verify reports and non-ready /session audit results become failed recovery actions, and stop_on_failure skips dependent actions.
The safe-auto shell whitelist allows narrow commands such as go test, go vet, go list, git status, and git diff --check, but rejects high-risk Go/Git flags that can launch external tools or write side artifacts.

Autonomous Goals

Purpose:

Let the user define a Codex-style goal once, then let Kernforge keep working without write, diff preview, shell, or git follow-up prompts while implicit model-backed reviews still honor the consent policy.
Support objectives written inline or stored in markdown files.
Repeat implementation, self-review, verification, completion audit, final semantic review, and recovery until the goal is complete or a concrete blocker is recorded.

Useful commands:

/goal "add the missing recovery tests and update docs" designs a plan then runs until complete (or blocked)
/goal @GOAL.md loads a markdown objective and runs the same flow
Bare /goal resumes an incomplete goal or prints a snapshot when idle
/goal --file GOAL.md --max-iterations 12
/goal --time-budget 10m @GOAL.md
/goal --token-budget 120000 "finish the refactor without exceeding context budget"
/goal --research "survey latest TPM attestation trends"
/goal --worktree "risky refactor in isolation"
/goal --rollback-on-regression "finish the refactor and keep verification green"
kernforge -goal "finish the verification policy change"
kernforge -goal "finish the refactor" -goal-token-budget 120000 -goal-max-iterations 12
kernforge -goal-file GOAL.md

Current behavior:

/goal creates a GoalState, compiles acceptance criteria, drafts plan/slices, writes .kernforge/goals/* artifacts, prints a plan preview plus live progress snapshots, and immediately starts the autonomous loop.
Markdown goals use @GOAL.md, --file GOAL.md, or -goal-file. One-shot -goal / -goal-file execute immediately with matching budget flags.
Interrupt with Esc; bare /goal resumes. Edit ## Execution Plan in latest.md while interrupted if needed; resume reloads it. Draft-only "write a goal prompt" stays chat unless /goal/-goal/file/save is explicit.
Each iteration: checkpoint (when configured) → implement → independent review gate → optional repair → adaptive verify → completion audit → semantic review (slice-scoped when a DAG exists).
Review prompts include implementation replies, checkpoint diffs, git context, and bounded untracked excerpts.
Session-bypasses write/diff/shell/git confirmations during the loop; model-review consent still applies for implicit reviews (skipped_single_model_route on single-model routes).
Full verification follows the scheduled cadence. Generated/runtime/build artifacts are filtered from goal patch/progress scope.
Repeated identical verification failures without patch-scope edits block instead of looping.
Progress ledger tracks files, verify/audit, review/semantic verdicts, no-progress, failure signatures, token estimate, and command history.
Completes only when audit is ready and semantic review approves (all slices complete when a DAG exists); otherwise iterates until budget/blocker/interrupt.

Local Automations MVP

Purpose:

Provide a local-session foundation for Codex-style recurring workflows.
Connect recurring verification and PR review report generation to suggestions and the task graph.
Validate due checks, safe command execution, and report recording locally before adding cloud jobs.

Useful commands:

/automation
/automation add recurring-verification /verify
/automation add recurring-verification --every 2h /verify
/automation add pr-review /review pr
/automation due
/automation digest
/automation monitor
/automation monitor --notify
/automation watch --interval 5m --notify
/automation daemon-start --interval 5m --notify
/automation daemon-status
/automation daemon-stop
/automation notify --webhook-url https://example.invalid/kernforge
/automation notify
kernforge -command "/automation monitor --notify"
/automation run-due
/automation run <id>
/automation pause <id>
/automation resume <id>
/automation remove <id>
/review pr
/review pr --github
/review pr --github --draft-comments
/review pr --github --post-comments
/review pr --resolve-thread <thread-id>
/review pr --draft-issue
/review pr --create-issue
/review pr --create-issue --label bug,security --assignee <login> --milestone "May 2026"

Current behavior:

Automation slots are stored in the session JSON under automations.
--every, --hourly, and --daily schedules write next_run_at plus a next-run hint, and /automation due shows active scheduled slots whose time has passed.
/automation run <id>, /automation run-due, and /automation monitor execute registered commands through the safe command dispatcher.
/automation digest, /automation monitor, /status, and the REPL startup notice surface due, failed, and paused automation state.
/automation notify and /automation monitor --notify write .kernforge/automation/latest_digest.md so an external watcher, CI step, or shell script can consume the latest automation state without scraping terminal output.
/automation notify|monitor|watch --webhook-url <url> POSTs digest JSON to an external receiver. Webhook URLs are redacted in conversation events.
/automation watch [--interval 5m] [--cycles N|--once] [--notify] [--webhook-url <url>] runs a foreground standing monitor loop. Each cycle runs due safe automations, prints the digest, and optionally refreshes the digest artifact or sends a webhook.
/automation daemon-start|daemon-status|daemon-stop manages a process-detached local automation watcher with state and logs in .kernforge/automation/daemon.json and daemon.log.
-command "/automation monitor --notify" lets Windows Task Scheduler, service wrappers, or CI run a slash command without entering the REPL.
/review pr writes git status, diff stat, changed files, and a review checklist to .kernforge/pr_review/latest.md, then records an artifact ref in the conversation event log.
/review pr --github adds current PR metadata, review decision, comments, and checks from gh pr view --json ... when available.
/review pr --draft-comments writes .kernforge/pr_review/comments.md as a file-level review comment draft without posting to GitHub.
/review pr --post-comments runs gh pr review --comment --body-file .kernforge/pr_review/comments.md after generating the draft. This write-side action is only allowed from the explicit command, not suggestion acceptance or scheduled automation.
/review pr --resolve-thread <thread-id> runs GitHub's resolveReviewThread GraphQL mutation through gh api graphql. This write-side action is also explicit-only.
/review pr --draft-issue writes .kernforge/pr_review/issue.md, and /review pr --create-issue posts that draft with gh issue create --title ... --body-file .... Issue creation is explicit-only.
Issue drafts and create calls accept repeated or comma-separated --label, repeated or comma-separated --assignee, and quoted --milestone values. Create mode passes them through to gh issue create.
When verification gaps or dirty diffs exist, /suggest can recommend recurring verification or PR review automation registration.

Delegation Handoff

Purpose:

Save the minimum state needed to pass the current task to a Codex cloud task, another local agent, or a human reviewer.
Package changed files, open task graph nodes, recent events/artifacts, verification state, and a continuation prompt.
Import a result packet from another agent or cloud task and merge its task status/artifact refs back into the current session.

Useful commands:

/session handoff
/session handoff continue automation scheduler work
/session handoff import .kernforge/handoff/imports/cloud_result.json

Current behavior:

Writes .kernforge/handoff/latest.md and .kernforge/handoff/latest.json.
Records the generated artifact refs in the conversation event log.
The next agent starts from Suggested Prompt, Changed Files, Open Tasks, and Artifact Refs.
/session handoff import <path> normalizes JSON or markdown results into .kernforge/handoff/imports/*.json and *.md, records a conversation event, and marks matching completed_tasks IDs complete in the TaskGraph.

Coding Harnesses And Repair Loop

Purpose:

Check the final answer against the real workspace state before it is shown.
Structure the Codex-style completion loop around acceptance, artifacts, scenarios, subagent evidence, test impact, open tasks, background jobs, failure repair, completion audit, and user-change isolation.
Treat blockers as feedback that requires revision, verification, or explicit disclosure.

Current behavior:

AcceptanceContract extracts expected behavior, non-goals, changed surfaces, required artifacts, and verification requirements from the user request.
Patch transactions record edit tools, scoped shell writes, changed paths, fingerprints, and failed tool calls so the final harness knows what actually changed.
The artifact-quality harness reads requested or claimed document artifacts and flags placeholder/TODO content, very thin content, or missing topic coverage.
The scenario-replay harness detects when/expected/but observed bug scenarios and requires replay/verification evidence or an explicit "not run" disclosure before a code-changing fix claim.
The subagent-orchestration harness checks whether root-cause answers connect worker evidence and reviewer validation to a real causal bridge. It blocks hidden reviewer failures or weak worker evidence that cannot lead to the user-visible symptom.
The test-impact harness maps code-like changed paths to recommended verification commands and records a warning when successful verification evidence is missing.
Build/test shell commands that may write artifacts use an explicit command lifecycle. Kernforge shows them as a verification approval request before execution, not as an already-started shell job. Non-interactive -prompt -y runs auto-approve this prompt the same way they accept diff previews without opening them, while non-bypass prompt runs skip instead of guessing approval. If the user declines the pinned verification prompt, the tool result is verification_status=skipped and command_execution_status=declined; that result is not successful verification evidence, does not clear pending verification checks, and must not be retried or polled in the same turn unless the user explicitly approves verification. Declined or prompt-failed automatic verification is also saved as a skipped VerificationReport, leaves the verification pending check active, and prompts final answers to say verification was not run instead of treating the run as completed. Generated-document-only artifact turns are exempt from that pending state after deterministic artifact-quality checks approve the report and the final answer avoids unsupported verification claims; they complete the self-driving state instead of re-entering shell validation or review. Background verification starts are recorded as verification_status=pending with verification_evidence=false; only completed zero-exit background checks become successful evidence. After a terminal decline or skipped automatic verification, same-turn verification retries and latest background polls are folded into a synthetic NOT_EXECUTED tool result before any new shell/progress status is emitted, steering the model toward disclosure instead of another fake recovery attempt. Final answers can disclose that verification was not run, but the edit-loop ledger still remains risk_accepted until successful verification evidence exists for the changed paths. Background job bundles store job lists in job_entries; scalar job_status remains a single-job status field. Generated analysis, fuzz, and manifest findings are informational verification evidence with an empty command and output-only text; they are reported as skipped evidence context, never executed as shell.
The job-supervisor harness prevents final answers from hiding failed, stale, or still-running background jobs and bundles.
/session audit externalizes the final readiness gate as .kernforge/completion_audit/latest.md/json, so a human or scheduler can see the same blockers and warnings outside the model turn.
The failure-repair harness keeps the first meaningful failure line, repeated count, narrow rerun command, and next repair steps in active context after verification fails.
User-change isolation blocks overwrites when a target file changed outside the agent after the turn began, forcing a fresh read and merge-aware edit.
The final-answer reviewer now runs only for unresolved verification, coding-harness blockers, or actual patch transaction changes. Plan state or task-graph presence alone no longer creates an extra reviewer/revision round-trip.

Practical interpretation:

Before saying "done", Kernforge rechecks actual artifacts and verification evidence.
For root-cause work, the important bar is not plausibility; it is the causal chain from trigger to invalid state to user-visible symptom.
When a blocker appears, the user does not need to restate the request. Harness feedback is injected into the next model turn so the agent can repair, verify, or disclose the remaining gap.

Read Reuse And Large-File Inspection

Purpose:

Reduce repeated read_file churn on very large source files.
Make grep results expose when nearby context was already read.
Nudge the model away from scanning the same region again when cache evidence already exists.

Current behavior:

read_file reuses unchanged exact ranges, covered subranges, and partial overlaps before it falls back to fresh file reads.
Cached read_file replies include a NOTE: prefix so the model can treat them as already-seen context rather than fresh evidence.
Repeated same-file read_file turns now use that cache signal to warn earlier when the model is looping on the same chunk.
grep annotates matches with [cached-nearby:inside] when the matching line already sits inside a recent read span.
grep annotates matches with [cached-nearby:N] when the match is near a recently read span, which encourages a narrower follow-up read_file request.
Stale read hints are ignored automatically when file size or modification time changes.

Practical interpretation:

If you see NOTE: returning cached content..., the tool is telling the model it already has that text and should only read a missing adjacent range if necessary.
If grep returns [cached-nearby:inside], the next best action is usually edit, explain, or read a tiny adjacent gap rather than rescanning a large block.
If grep returns [cached-nearby:2], [cached-nearby:5], and similar markers, the model should usually read only that small uncovered neighborhood.

2.0 Project Analysis

Purpose:

Build a reusable architecture document for a large workspace.
Split analysis across multiple worker and reviewer passes.
Keep a latest knowledge pack and performance lens for follow-up work.
Reuse unchanged shard results when incremental mode is enabled.
Preserve a structural index, Unreal semantic graph, and vector corpus for downstream automation.
Preserve deterministic architecture facts so cached deep-structure answers can be checked against source-derived invariants.
End the run with a highlighted Analysis artifacts: block and an Analysis handoff so the user can continue into the dashboard, fuzz campaign automation, target drilldown, or verification without memorizing the sequence.
In local-provider or explicitly route-limited setups, cap shared worker/reviewer model routes through the global scheduler to reduce provider saturation and low-confidence placeholder cascades.
Let Kernforge adapt shard size for local models when shard limits are not configured, then automatically retry once with smaller shards when a final timeout or 5xx/overload-style provider error still stops the run.
Show live execution progress with worker slot count, shard waves, completed/failed shard totals, cache/review state, and model wait events labeled by analysis stage and shard.
Prefer graph-guided shard communities for startup, IOCTL, callback, handle/memory, RPC, asset/config, build-context, and generated-artifact evidence before falling back to directory chunks.
Run the deterministic claim verifier on every run so high-confidence claims require valid packet, source, line, symbol, graph, and security-boundary evidence.
Publish a security/anti-cheat overlay for Windows driver and Unreal authority/config surfaces alongside the final report, docs, and dashboard.

Useful commands:

/analyze-project [--path <dir>] [--mode map|trace|impact|surface|security|performance] [goal]
/docs-refresh
/analyze-performance [focus]
/model analysis
/model analysis-worker <provider> <model> [reasoning_effort]
/model analysis-reviewer <provider> <model> [reasoning_effort]
/model analysis-worker 0
/model analysis-reviewer 0

The goal is optional. If omitted, Kernforge infers a practical goal from the selected mode and path. Follow-up modes automatically load a previous map run as baseline structure when available. This lets trace, impact, surface, security, and performance start from the architecture map without sharing the same shard cache. Before confirmation, the analysis plan prints the selected baseline_map so the user can see which map run will be reused. Large runs are provider-failure tolerant: worker/reviewer rate limits are recorded as low-confidence shard failures, and synthesis falls back to a local document when the final model request fails. For local-model providers such as LM Studio, vLLM, llama.cpp, and Ollama, unset max_files_per_shard / max_lines_per_shard values are adjusted from provider, model size, max tokens, and request timeout before the plan is confirmed. If the run still ends in a timeout, 5xx, overload, empty response, connection reset, or similar provider-pressure error after normal request retries are exhausted, Kernforge prints an adaptive_retry_shards line and reruns once with smaller shard limits. Rate limits are not retried this way because smaller shards usually create more requests. When worker and reviewer use the same provider/model/base_url/reasoning_effort route, shard execution is capped by the model route limit. Local providers default to serial execution with a route limit of 1; cloud/API routes are not forced to serial execution unless model_routes says so. Reasoning effort is stored per configured model target, not as one global override. The main profile, optional cross review route, analysis worker/reviewer, and explicit task-owner model overrides can each carry a different reasoning_effort; selecting a new effort-capable main, analysis, or task-owner target defaults that target to low when it was still undefined, while the cross review route defaults to at least high and raises saved low/medium values to high at runtime. Strict omission retry is finding-field driven: Kernforge retries when a structured finding is actually omitted, cut off, or weak with omission markers, but it accepts usable structured findings even if prose summary text contains words such as omitted. Route-specific base_url values for the cross review route, analysis worker/reviewer, and task-owner model overrides can be omitted safely. Same-provider routes inherit the main endpoint; different-provider routes use their own configured or default endpoint so proxy/local routes do not drift silently. Changing the main provider/model preserves explicit analysis worker and reviewer profiles. Use /model analysis clear when you want project analysis to inherit the current main model again instead of a previously dedicated route, or use /model analysis-worker 0 / /model analysis-reviewer 0 to reset only one role. In the interactive provider picker for analysis worker, analysis reviewer, or cross-review, choose 0 to reset that target to its inherited/default route. Scripted cross-review resets use /model cross-review 0 or /model clear cross-review. /analyze-project generates docs, manifests, and dashboards by default. Older --docs input is accepted only as quiet backward compatibility and is not shown in help or completion; use /docs-refresh when you only need to rebuild docs from the latest saved run. The generated documentation set includes FINAL_REPORT.md, which preserves the assistant-facing final synthesis that was printed at the end of the run, plus the operational docs used for architecture, security, entrypoints, build artifacts, verification, fuzz targets, and operations. The dashboard opens those documents in an inline Markdown viewer. Use the Reader button for a full-window reading mode when the final report or another generated document is too long for the default panel. If the goal explicitly asks for English or Korean output, that request is passed through to the worker and synthesis prompts instead of relying only on the detected conversation language. Live model-wait/progress text is truncated on UTF-8 rune boundaries so localized status text does not become mojibake.

Role split:

README.md is the quick product-scope, flagship-command, and artifact-location document.
This feature guide explains the operating sequence across investigation, simulation, root-cause, fuzzing, verification, evidence, and memory.
Generated analyze-project docs are the per-run project knowledge base with source anchors, confidence, and stale/invalidation markers.

Mode summary:

map is the default mode and prioritizes architecture ownership and module boundaries.
trace emphasizes runtime flow, caller/callee chains, and dispatch order.
impact emphasizes change impact, downstream dependencies, and retest scope.
security emphasizes trust boundaries, validation, and privileged surfaces.
performance emphasizes startup cost, hot paths, contention, and blocking chains.

Best used when:

You are entering a large codebase and need more than an ad hoc summary.
The work spans startup, integrity, ETW, scanner, compression, memory, or upload paths.
You want follow-up review and verification to inherit a stable architecture view.
You are dealing with a UE5-scale codebase where modules, targets, reflection, replication, and asset/config coupling all matter at once.

Additional artifacts now produced by project analysis:

snapshot: structured scan output plus runtime and project edges.
structural index: symbol anchors, references, build contexts, build ownership edges, call edges, and overlay-oriented analysis state.
unreal graph: UE project, module, network, asset, system, and config semantics.
architecture facts: deterministic domain hints, top-level directory facts, critical anchors, dispatch/registration flows, boundary facts, and answer invariants.
knowledge pack: human-readable architecture digest and subsystem summaries.
vector corpus: embedding-ready project, subsystem, and shard documents.
vector ingest exports: staging files for pgvector, SQLite, and Qdrant pipelines.
graph_shards, graph_reuse, and evidence_graph: graph communities, symbol-level reuse fingerprints, and evidence edges used by worker prompts.
claim_verification and unsupported_claims: deterministic verifier results, downgraded claims, blocking issues, and follow-through commands.
security_overlay: Windows/driver/IOCTL/callback/handle/memory/RPC/telemetry plus Unreal RPC/replication/asset/config/integrity boundary nodes and edges.

What materially changed for large and Unreal-heavy workspaces:

A semantic shard planner now prioritizes startup, build_graph, unreal_network, unreal_ui, unreal_ability, asset_config, integrity_security, and unreal_gameplay.
Worker and reviewer prompts now carry shard-specific semantic focus and review checklists.
Graph-guided planning separates security and runtime communities such as security_driver, security_ioctl, callback_registration, security_handles, security_memory, security_rpc, asset_config, build_context, and generated_artifact.
Incremental reuse now considers semantic and graph fingerprints instead of relying only on file hashes.
Build alignment now promotes .uproject, .uplugin, .Build.cs, .Target.cs, and compile_commands.json into reusable build-context records.
Source anchors now lift Go, C++, and C# functions into symbol records with line ranges, call edges, build ownership edges, and security overlays.
trace, impact, and security retrieval now expand graph neighborhoods instead of relying only on keyword hits, and they persist build_context_v2 plus path_v2 evidence.
The C++ anchor parser now covers template out-of-line methods, operators, requires, decltype(auto), API-macro-wrapped scopes, and friend functions.
Output documents now expose subsystem invalidation reasons, evidence, diffs, top change classes, and graph-section stale markers.
The dashboard stale diff links graph-related changes directly into trust-boundary, data-flow, and project-edge sections.
Persisted artifacts now include machine-readable snapshot, structural index, Unreal semantic graph, vector corpus, and ingestion seed files for downstream retrieval pipelines.
The architecture fact pack is injected into worker/reviewer/synthesis prompts and into cached answer packs so structure answers stay source-grounded even when no extra tool call is needed.
C/C++ and driver-oriented scanners now look for dispatch tables, unload/finalize paths, callback registrations, filter registrations, aliases, macros, and include-driven registration helpers instead of relying only on filename heuristics.
.kernforge/analysis/latest is replaced per run, avoiding stale artifact bleed-through across repeated analysis tests.
Goal text can narrow analysis to matching directories when you clearly target a sub-area.
Interactive runs can flag hidden or external-looking directories so you can exclude them before scanning.

Root-Cause Investigation

Purpose:

Turn a user-reported symptom into source-evidence-backed root-cause candidates.
Select only source files and symbols that appear relevant, then analyze them with 1-8 worker shards whose concurrent model calls follow model_routes.
Require reviewer and deterministic gate validation that a worker-reported issue can actually lead to the user's symptom.

Useful commands:

/find-root-cause <problem description>
/find-root-cause --pattern-pack <path-or-dir> <problem description>
/root-cause-patterns list [--type <project_type>] [--json]
/root-cause-patterns match <problem symptom> [--json]
/root-cause-patterns github-search [--type <project_type>] [--limit 20] [--out .kernforge/root_cause/github_issues.json] [query words...]
/root-cause-patterns normalize --in .kernforge/root_cause/github_issues.json --out .kernforge/root_cause/pattern_pack.json [--type <project_type>]
/root-cause-patterns validate [--in <pattern_pack.json>] [--json]

Good prompt shape:

/find-root-cause In <component/feature>, when <input/command/event sequence/state>, expected <normal behavior or invariant>, but observed <failure>. Frequency/env: <how often and where>. Repro/log/value: <exact prompt, API call, command, DB value, or log line>.

Examples:

/find-root-cause In the party system, after inviting and kicking members repeatedly, expected the party size limit to block new invites, but observed extra members can still be invited.
/find-root-cause My Win32 service process does not stop through sc stop.

Current behavior:

With no prompt, the command prints usage and examples.
If affected component, trigger/repro, observed failure, or expected behavior/invariant is unclear, Kernforge prints the missing pieces and asks for a sharper /find-root-cause ... command before starting agents.
Source hints and an optional model clarity check reduce false rejections for natural-language Korean symptom reports.
Workspace scan, source path/symbol matches, built-in pattern priors, and explicit --pattern-pack inputs are combined into candidate code matches.
Worker count is estimated from code size and candidate count, from 1 up to 8 shards.
Workers focus on what happens when input parameters, DB/config values, cached state, counters, ids, enums, nullable references, and lifecycle state fall outside the range the code expects.
Worker candidates must include causal chain, evidence file/function, out-of-range case, required runtime observation, probes, and disproof conditions.
Reviewers check symptom overlap, complete causal stages, and evidence quality.
If reviewers need more proof, evidence_requests route additional focused shards, and rejected candidates stay in the audit trail as regression priors.
Deep verification rechecks reviewer-approved candidates with symbol-aware source excerpts and adjusts confidence breakdowns.
Final synthesis deduplicates candidates into clusters and reports confidence, instrumentation, verification probes, and "this is not the root cause if..." disconfirmation conditions.

Pattern pack workflow:

The built-in pack provides search priors for recurring bug classes in Windows services, Windows kernel drivers, Unreal clients/servers, web backends, and Go/CLI agents.
/root-cause-patterns match shows pattern candidates for the current workspace type and symptom text.
/root-cause-patterns github-search collects closed GitHub issues with bug, fix, or root-cause signals.
/root-cause-patterns normalize converts that issue corpus into a provisional pattern pack.
/root-cause-patterns validate reports pack quality issues.
Pattern packs are priors, not proof. /find-root-cause still requires current source evidence plus reviewer causality validation.

Source-Level Function Fuzzing

Purpose:

Show how attacker-controlled parameters could open guard, probe, copy, dispatch, and cleanup paths directly from source.
Go beyond generic review comments by telling you which predicate to flip with which value and which sink opens afterward.
Let you start from either one function or one suspicious file and still converge on the most relevant input-facing path.

Useful commands:

/fuzz-func <function-name>
/fuzz-func <function-name> --file <path>
/fuzz-func <function-name> @<path>
/fuzz-func <function-name> --source-scan focused
/fuzz-func <function-name> --source-scan full
/fuzz-func <function-name> --no-source-scan
/fuzz-func --from-candidate <candidate-id>
/fuzz-func --file <path>
/fuzz-func @<path>
/fuzz-func status
/fuzz-func show [id|latest]
/fuzz-func list
/fuzz-func continue [id|latest]
/fuzz-func language [system|english]
/fuzz-campaign
/fuzz-campaign run
/source-scan run
/source-scan run --limit 50
/source-scan run --only-slugs probe-copy-size-drift,double-fetch-user-buffer
/source-scan run --files driver/nsi.c,api/registry.c
/source-scan list
/source-scan show [id|latest]
/create-driver-poc <driver-name> [--type objectfilter|minifilter|registryfilter|wfpcallout]

Best used when:

You need fast triage on IOCTL handlers, parsers, validators, or buffer-processing code.
You know the suspicious file but not yet the best root function.
You want source-only reasoning about size drift, branch flips, check/use desync, or dispatch divergence before building a runtime harness.

Current behavior:

If you provide a function name, Kernforge resolves the symbol directly. If you provide only a file path, Kernforge expands through include/import plus actual call flow to pick a representative root automatically.
Planning no longer requires analyze-project or a prebuilt structural_index_v2; Kernforge can rebuild snapshot and semantic-index context on demand.
Kernforge extracts real guard, probe, copy, dispatch, and cleanup observations from function bodies and uses them to synthesize attacker input states.
Higher-risk findings now include concrete sample values, source-derived branch predicates, minimal counterexamples, branch outcomes, and downstream call chains.
Output is organized as Conclusion, Risk score table, Top predicted problems, and Source-derived attack surface so the most actionable finding is visible first.
By default, /fuzz-func reuses a matching /source-scan candidate or runs a focused source scan over the target and reachable files before saving the plan. Use --source-scan off, --source-scan focused, --source-scan full, or --no-source-scan to control this.
/source-scan run persists ranked function-window candidates and prints the natural next command, /fuzz-func --from-candidate <candidate-id>, for explicit candidate handoff. Each candidate records evidence spans, file/symbol fingerprints, confidence breakdown, dataflow/control-flow facts, stale-source state, and native feedback calibration.
Built-in source matchers include Windows kernel double-fetch, IOCTL output infoleak, WDF request buffer size drift, integer allocation overflow, and pool/refcount lifetime surfaces in addition to the existing probe/copy, dispatch, IRQL, callback, minifilter, Unreal RPC, and telemetry parser signals.
/create-driver-poc <driver-name> [--type objectfilter|minifilter|registryfilter|wfpcallout] generates an x64-only C++20 MSVC/WDK POC driver template. Omitting --type keeps the original WDM SCM/IOCTL ping POC; typed templates generate object manager process/thread access filtering, filesystem minifilter open/rename/delete user-mode decision messaging, registry create/open/set/delete/rename callback blocking, or WFP outbound callout blocking contracts. Completion prints a security workflow handoff (/source-scan, /fuzz-func, /fuzz-campaign run, /verify, /investigate start platform-security, signing notes, Driver Verifier) and writes .kernforge/security/workflow_seed.json with next commands and type-aware fuzz focus.
Native execution is an optional follow-up. If build context such as compile_commands.json is missing, Kernforge explains the gap before asking whether to continue. Build-only failures are classified (missing-include, unresolved-symbol, wdk-macro, abi-or-link) and a bounded 1–3 self-repair loop re-emits the harness or records durable build blockers.
Artifacts are written under .kernforge/fuzz/<run-id>/ with files such as report.md, harness.cpp, plan.json, and when an IOCTL surface is detected ioctl_contract.json plus multi-call corpus/sequences/*.json seeds.
/fuzz-func automatically prints a campaign handoff when source-only scenarios are ready, so the user can continue with /fuzz-campaign run instead of learning campaign internals.
/fuzz-campaign shows the next recommended campaign step and /fuzz-campaign run performs the safe automatic action, such as creating a campaign, attaching the latest useful run, promoting source-only scenarios and IOCTL multi-call sequence seeds into corpus/<run-id>/, updating deduplicated finding lifecycle and coverage gap entries, ingesting libFuzzer logs, llvm-cov text, LCOV, and JSON coverage summaries, capturing sanitizer reports, Windows crash dumps, Application Verifier, and Driver Verifier artifacts, and recording native run results into reports and evidence.
Campaign manifests now include a finding list, dedup keys, duplicate counts, merged native/evidence links, parsed coverage reports, run artifacts, coverage gaps, and artifact graph that link targets, seeds, native results, coverage reports, sanitizer/verifier artifacts, evidence ids, source anchors, verification gates, and tracked-feature gates.
Native crash findings are feasibility-gated (target_plausible vs spurious). Harness-only stacks are marked spurious and do not promote as validated target bugs requiring verification/feature close-block. Plausible crashes still merge by crash fingerprint, source anchor, and suspected invariant.
Coverage gaps feed the next generated FUZZ_TARGETS.md refresh so unexercised seed targets receive explicit ranking feedback.
/fuzz-func completion shows function and file usage hints first, then switches to real file candidates after @.
/investigate start platform-security collects best-effort Secure Boot, VBS, HVCI/Memory Integrity, test-signing, driver signature enforcement, and TPM readiness into snapshot attributes and platform_security findings (fields are unavailable when a probe cannot run).

Practical interpretation:

Most useful branch delta is usually the first line worth reading.
Concrete hypothetical input examples are internal analysis inputs synthesized by Kernforge, not instructions for manual reproduction.
Source-derived attack surface is the highest-confidence section because it comes from real function-body evidence.
Even high-score findings should still be checked against the cited source excerpt, especially when helper or exploit-side files appear in the closure.

2.1 Hook Engine

Purpose:

Warn, confirm, or block risky actions.
Inject extra review context and verification steps before verification runs.
Strengthen push and PR policy using recent evidence.
Create automatic checkpoints before risky flows.

Useful commands:

/hooks
/hook-reload
/init hooks
/override
/override add <rule-id> <hours> <reason>
/override clear <override-id|rule-id|all>

Current actions:

warn
ask
deny
append_context
append_review_context
add_verification_step
create_checkpoint

Best used when:

Your team repeatedly hits signing, symbol, provider, XML, or scanner regressions.
Passing normal tests is not enough for approval.
You want repeatable PR and push guardrails instead of relying on memory.

Recommended operating model:

Start with the windows-security preset.
Add workspace-specific rules in .kernforge/hooks.json.
Begin with warn and ask.
Promote only repeat incident classes to deny.
Use /override add only with an expiration and a reason.

2.2 Security-Aware Verification

Purpose:

Infer security-relevant categories from the changed files.
Build verification steps that match the change type.
Pull recent simulation and investigation context into verification planning.

Current categories and signals:

driver
telemetry
unreal
memory-scan
Recent high-risk simulation findings
Active investigations and live findings

Useful commands:

/verify
/verify --full
/verify src/foo.cpp,driver/guard.cpp
/verify dashboard
/verify dashboard --html
/set-auto-verify [on|off]
/verify tools detect
/verify tools set msbuild <path>
/verify tools set cmake <path>
/verify tools set ctest <path>
/verify tools set ninja <path>

Best used when:

Generic go test, msbuild, or ctest is not enough.
You need signing, symbols, package, provider, XML, or verifier-oriented follow-up.
You already saw risky investigation or simulation findings and want them reflected in validation.

Operational notes:

auto_verify is now the master switch for edit-triggered verification.
When a Windows verification tool such as msbuild, cmake, ctest, or ninja is missing, Kernforge first tries to auto-detect and save a usable path for the workspace, then falls back to prompting if detection still fails.
Use quotes for paths that contain spaces, for example /verify tools set msbuild "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe".
Model request timeout is configurable through request_timeout_seconds, while max_request_retries and request_retry_delay_ms control retries for timed-out or transient provider failures.
For long-running local validation, prefer run_shell_background plus check_shell_job so the agent can reuse one expensive build or test job across multiple turns.
Shell workspace writes follow the permission mode (Grok-aligned): under plan/edit, hand-authored shell writes (Set-Content, Out-File, redirection, etc.) stay blocked — use write_file / apply_patch / replace_in_file. Tool-style writes such as gofmt -w prompt under edit via a separate shell-write approval. Under full, shell workspace writes are allowed (config deny rules and hooks still apply).
In interactive shell mode, use !cd .. freely to move back up within the workspace after drilling into a subdirectory. Kernforge rejects only the step that would leave the workspace or active worktree boundary.

2.3 Evidence Store

Purpose:

Store verification, override, investigation, and simulation output as structured evidence.
Give you a fast way to inspect recent failed or high-risk signals.
Feed recent state back into hooks and verification planning.

Useful commands:

/evidence
/evidence search <query>
/evidence show <id>
/evidence dashboard [query]
/evidence dashboard --html [query]

Common evidence kinds:

verification_category
verification_artifact
verification_failure
hook_override
investigation_session
investigation_snapshot
investigation_finding
simulation_run
simulation_finding

2.4 Persistent Memory

Purpose:

Keep important context across sessions.
Let you find earlier decisions, failures, and verification context later.
Support long-running investigations and repeated regression classes.

Useful commands:

/memory recent
/memory search <query>
/memory show <id>
/memory dashboard [query]
/memory dashboard --html [query]

Strength:

It stores more than text. It also stores verification categories, tags, artifacts, failures, severities, signals, and risk.

2.5 Live Investigation Mode

Purpose:

Capture live Windows state as investigation snapshots.
Store live findings as evidence and memory.
Feed those live findings into simulation and verification later.

Useful commands:

/investigate
/investigate start <preset> [target]
/investigate snapshot [target]
/investigate note <text>
/investigate stop [summary]
/investigate list
/investigate show <id>
/investigate dashboard
/investigate dashboard-html

Current presets:

driver-visibility
process-visibility
provider-visibility
platform-security (aliases: platform, vbs-hvci, security-posture)

Best used when:

Static code review is not enough.
You need to capture live verifier, module, driver, service, or provider state before editing.
You want a reusable record of the real runtime state that informed later decisions.
You want a lightweight visibility triage snapshot before deeper debugging.
You need a release/AC posture snapshot of Secure Boot, VBS, HVCI, test-signing, and TPM readiness (platform-security).

Important scope limit:

driver-visibility is not a deep root-cause analyzer for driver load failures.
Its current implementation is intentionally narrow and focuses on user-mode-visible driver, service, filter, verifier, and artifact state.
process-visibility is a process-listing triage snapshot, not a process attach or protection analyzer.
provider-visibility is a provider-listing triage snapshot, not a deep ETW or provider root-cause analyzer.
platform-security is best-effort user-mode posture collection; unavailable probes are recorded as unavailable. It does not change HVCI/VBS policy.

2.6 Adversarial Simulation Profiles

Purpose:

Evaluate recent evidence and investigation state through a lightweight risk lens.
Surface tamper, visibility, and forensic blind spots.
Feed that heuristic context back into review, edit, plan-review, and verification flows.

Useful commands:

/simulate
/simulate tamper-surface [target]
/simulate stealth-surface [target]
/simulate forensic-blind-spot [target]
/simulate list
/simulate show <id>
/simulate dashboard
/simulate dashboard-html

Current profiles:

tamper-surface
stealth-surface
forensic-blind-spot

Best used when:

You care about integrity or registration risk.
You suspect observer or telemetry visibility gaps.
You worry that post-incident artifacts may be too weak.

Important scope limit:

Simulation is a heuristic risk review, not proof of exploitability.
The profile names describe interpretation lenses, not offensive capability.

2.7 Selection-First Review And Edit

Purpose:

Review or edit only the selected code range instead of the whole file.
Route selection review through the common ReviewRun harness and gate instead of a one-off prompt.
Automatically inject recent simulation findings when they match the selected area.
Inspect workspace and selection diffs in a richer Windows diff surface before wider review or editing.

Useful commands:

/open <path>
/selection
/selections
/diff
/diff-selection
/review selection [extra]
/review selection --all [extra]
/edit-selection <task>
/note-selection <text>
/tag-selection <tag[,tag2]>

Diff workflow notes:

On Windows, /diff and /diff-selection prefer the internal WebView2 diff viewer.
The read-only diff viewer includes changed-file navigation, unified/split toggles, and intraline highlights.
If the internal surface is unavailable, Kernforge falls back to terminal output.
In Open diff preview?, y opens this preview, a accepts the current edit without opening a preview and applies that choice for future diff previews in the session, and n cancels the edit.

Best used when:

You want to focus on a single IOCTL handler, integrity check, or provider registration block.
You want to connect a recent simulation finding directly to the relevant code.

Review artifacts:

/review selection writes .kernforge/reviews/latest.json and .kernforge/reviews/latest.md.
The result includes typed findings, request class, lifecycle phase, route mode, request-class reason, freshness/redaction state, gate status, scope discovery, repair steps, runtime gate ledger, and recommended next commands.
MCP clients get the same structure through kernforge_review, including additive request_class and lifecycle fields plus model_plan, reviewer_runs, latest_review_freshness, edit_proposals, runtime_gate_ledger, single_model_second_pass, cross_review_triage, review_observability, scope_discovery, and action-contract fields on next_commands.
Protocol artifacts also include action envelopes, approval ledger, capability manifest, external lookup intents, artifact integrity, ledger consistency, resume sanity, state transitions, route health, document gate status, single-model second-pass status, and cross-review triage so CLI output, Markdown reports, JSON artifacts, and MCP responses describe the same lifecycle state without dumping raw model output into MCP.

Review UX/Ops observability:

Already implemented runtime enforcement remains in the review gate ledger, cross-review triage ledger, enforced single-model second-pass phase, and pre-final answer completeness gate.
New request-class-aware orchestration classifies the user request as review_only, document_artifact, review_then_modify, modify_then_review, verification_only, validation_only, or general. The selected class, reason, confidence, ambiguity flag, ambiguity warnings, and class-specific final-answer contract are persisted on ReviewRun, RuntimeGateLedger, status surfaces, artifacts, and MCP review responses.
In single-model mode, Kernforge treats the route as an explicit staged lifecycle, not as independent approval. The compact state exposes classify/context/review-or-implementation/second-pass/verification/final phases, whether second-pass ran, was cached, or was skipped, and why any skip is only a disclosure rather than approval.
A configured reviewer-only post-change route keeps the single-model policy state visible but avoids spending another primary second-pass call when that reviewer is already the only post-change reviewer. Weak, empty, malformed, stale, or timed-out reviewer output degrades the route; deterministic blockers and required verification gaps remain stronger than weak reviewer approval.
In cross-model mode, primary implementation responsibility stays separate from reviewer feedback. Actionable reviewer items must enter cross_review_triage as accepted_fixed, accepted_deferred, rejected_with_reason, or needs_user_decision; missing fix evidence, deferral reason, technical rejection reason, or user-decision guidance stays visible as an obligation.
Document-artifact requests use artifact-quality checks as the primary gate: requested artifact exists, requested topic is covered, content is not placeholder/TODO-only, and the final answer does not claim unsupported shell or code verification. Document-only report creation does not become a code-modification lifecycle, while a report plus source-code edit reopens modification review and validation obligations.
The UX/Ops layer exposes lifecycle decisions through /status, /hooks, session dashboard, Markdown artifacts, JSON artifacts, and MCP responses. The compact status view shows latest review id, request class, classification confidence/ambiguity, lifecycle phase, trigger/target/mode, route mode and route quality, review/repair/document/verification/final-answer gate status, gate verdict/action, second-pass state, triage counts by status, incomplete triage blockers, remaining obligations, final-answer correction state, blocker classes, and the next recommended command.
/status is compact by default. /status detail expands evidence-heavy sections, including the lifecycle timeline: classified_request, collecting_context, pre_write_review, applying_change, post_change_review, single_model_second_pass, cross_review_triage, artifact_quality_gate, verification, final_answer_contract, blocked, and completed. Each phase carries status, short reason, evidence ref when available, and next safe action when blocked or skipped.
/progress-display compact is the default operator experience. Review progress is rendered as short action lines such as review 1/6 scope, review 2/6 evidence, main ... done, cross ... done, review decision, and next ...; it does not repeat the full 1->6 flow text or raw phase/waiting_on/next diagnostic tokens. /progress-display auto also avoids verbose review-flow spam during normal interactive use.
/progress-display stream remains the detailed debugging mode. Stream mode keeps every progress update in the transcript, but still phrases stage/wait/next-action diagnostics as readable text instead of raw key-value token dumps. The existing verbose config alias still normalizes to stream.
Compact final review CLI output is result-first: verdict, blocker/warning/note counts, gate action, target/mode/request class, severity-grouped findings, report path, and one recommended next command. Lifecycle, route, and triage detail remain available in artifacts and stream/detail surfaces.
Compact CLI output collapses duplicate next commands by command string. The terminal shows the command, the strongest or combined short reason, and whether confirmation is required, while Markdown, JSON, MCP, and runtime ledgers preserve the full next-command records.
Blocker classes separate code_repair_blocker, reviewer_route_problem, evidence_gap, verification_gap, document_artifact_quality, final_answer_contract, and user_decision_required. This keeps a primary code blocker above cross-review route warnings or document artifact details.
Cross-review triage artifacts render each finding with id/title, reviewer route, severity, location, status, reason, required fix, fix evidence, verification evidence, and safe continuation guidance. needs_user_decision entries include concrete inspect targets, safe-to-change scope, do-not-change-yet scope, and a next command instead of asking the user to infer the next step from raw review text.
If the user says fix RF-004 or otherwise names a specific RF id, repair handoff carries only that selected RF through RepairFindings and pre-fix repair obligations. Unlisted RFs must not be intentionally fixed or reported as resolved; if the selected RF is inseparably coupled to another RF, the model must report that coupling and wait for the user's decision before broadening the edit.
Single-model mode is first-class, not degraded. Status and reports distinguish single_model_second_pass_ran, single_model_second_pass_cached, single_model_second_pass_skipped, cross_model_review_ran, and reviewer_only_post_change_review_used; a single-model second pass is never described as independent cross-review.
Document-artifact flows show artifact path, artifact-quality status, source-review evidence status when relevant, verification skip or required reason, and remaining limitations. A document-artifact final-answer correction is shown as a final-answer contract correction, not a code repair.
Final-answer completeness corrections are exposed as lifecycle facts: changed-file disclosure, review/self-review disclosure, validation disclosure, remaining-risk disclosure, review-only findings-first/no-edit formatting, or document-artifact path/quality/verification/limitation disclosure. Generic phrases such as "done", "patched", or "implemented" are never sufficient evidence by themselves.
MCP operator-card fields are additive and backward-compatible: lifecycle_timeline, compact_status, blocker_summary, route_quality, final_answer_contract_status, and next_recommended_command. MCP consumers can render a clear operator card without parsing prose or raw model output.
Known residual limits: raw model output stays in local artifact refs, MCP responses remain additive/backward-compatible instead of dumping transcripts, generated-document artifact skip behavior remains intentionally separate from code review gates, classification remains conservative for ambiguous natural language, and full-package tests may still need cluster-level diagnosis before a single all-in-one run is useful.

Review/Ops test strategy:

Start with go test ./cmd/kernforge -list . to confirm the package compiles and inventory current tests.
Use go test -json ./cmd/kernforge -count=1 -timeout 2m or -v when diagnosing a silent timeout; plain go test may print nothing until the package exits.
Run UX/Ops regressions as a focused cluster: go test ./cmd/kernforge -run "TestOperator|TestRuntimeGate|TestReviewMCPResponse|TestMCPStatus|TestCrossReview|TestSingleModel|TestPreFinalHarness|TestFinalAnswerContract" -count=1.
Run existing behavior clusters separately when needed: TestAgent|TestApplyEditProposal|TestRunShell|TestVerification|TestProjectAnalyzer.
The 2026-05-28 timeout investigation saved a JSON trace under .kernforge/test-logs/ and showed the short 2 minute budget expired in the project-analysis cluster after earlier agent/review tests consumed most of the time; the practical repeatable path is cluster isolation before a full go test ./cmd/kernforge -count=1 -timeout 15m.

2.8 Plan Review Workflow

Purpose:

Review implementation plans through the same common review harness used for code, selection, PR, goal, final, and analysis reviews.
Use the active main model as the primary review route and optional /model cross-review as the independent second-pass route; design/security/false-positive/test concerns are review lenses, not separate model routes.
In the interactive cross-review provider picker, choose 0 to clear the independent route and return to default single-model mode; the direct equivalent is /model cross-review 0.
Execute only when the gate and user flow allow it.

Useful commands:

/review plan <task>
/model cross-review status
/model cross-review
/model cross-review <provider> [model]
/model cross-review 0
/model clear cross-review
/review waive <finding-id> --reason <text>

Best used when:

A change spans multiple components.
Order of operations, rollback points, or operational caution matter.
You want simulation findings to shape the implementation plan before edits begin.

Current integration:

Recent simulation findings that match the task are injected into the review evidence pack.
The gate records objective fit, architecture risk, testability, security boundary, maintainability, and evidence gaps as structured findings.
Multi-model review is limited to primary plus optional cross route. Missing domain-specific roles are not reported; the planner records required_lenses and optional_lenses instead.
Unless an explicit timeout policy overrides it, model reviewer requests use bounded per-attempt timeouts so long preflight waits fail quickly and hand control back to the recovery path.
Natural-language review requests such as @file:line-line review this route to /review selection; focused review-and-fix requests are classified as review_then_modify, first run review, then continue the repair flow from the latest findings.
Focused review requests use a smaller evidence and prompt budget. Automatic pre-write review is diff-first and uses the proposed diff, edit proposal, and required repair findings before any broader context. For range-focused pre-write evidence, the current file context guarantees the selected range through the enclosing function end when possible, and function_body_excerpt is added as a separate source.
Automatic pre-write review runs on valid edit previews before an edit is applied, and automatic post-change review runs after changed paths exist.
Service, SCM, driver, and sensitive-path signals add the security lens. Detection, telemetry, scan, spoofing, and evasion-quality surfaces add the false_positive lens.
Review progress is compact by default. It prioritizes short action lines with main/cross phase, provider/model, elapsed time, finding count, review decision, and next command; detailed stage/wait/next-action diagnostics are available through /progress-display stream as readable text.
Simple exact edits can use apply_edit_proposal, which records file, operation, exact search, replacement/content, rationale, risk, preview fingerprint, and review evidence before the write. apply_patch remains available as a complex hunk-level fallback.
Runtime gate freshness links review, patch transaction, verification, completion audit, and final-answer review. Stale review coverage or unwaived blockers can block final answers, explicit git writes, MCP write-side responses, and completion audit readiness until /review, verification, or the displayed next_command repairs the ledger.
Invalid patch recovery normalizes common wrapper problems and records repeated patch signatures so the agent stops resubmitting the same malformed patch and refreshes target-file context instead.
Provider behavior drives review token caps, omission retry budgets, schema strictness, and recovery prompts. Weak or incomplete high-severity model findings are downgraded to evidence-gap warnings unless they include a concrete path or symbol, evidence, impact, and required fix. Finding locations can carry a structured line anchor, either from line: n or path: file:line, so downstream repair handoff does not have to scrape prose for the code location. test_gap is reserved for pure test or verification work; if a reviewer mislabels a production-code repair as test_gap but its required_fix changes implementation behavior, the repair plan still keeps it as an actionable obligation. DeepSeek review omission retries are intentionally tight to avoid repeated multi-minute strict-review loops. For optional cross-checks, if the main first-pass review already produced usable actionable findings and the reviewer stop reason is not an explicit token-limit or truncation signal, Kernforge does not run another DeepSeek strict retry just because the cross-check looked abbreviated. Focused and pre-write cross-reviewer calls normally use a 3 minute soft timeout, but if the configured review model is ranked lower than the active main model, Kernforge automatically extends that soft timeout to 5 minutes before treating the route as timed out.
Pre-fix review findings are surfaced to the user before any edit tool is allowed to run. When a repair turn has structured RF items, Kernforge emits and stores a deterministic Review findings: summary with those IDs and the intended repair direction before the implementation model starts. If the user names a specific RF id, such as fix RF-004, that RF is the only repair guidance, RepairFindings, and pre-fix obligation carried forward; other RFs are not reported as fixed. Kernforge still guards edit tools if no visible summary exists.
Local code review and repair turns stay on local source evidence. Web/search/browser MCP tools are hidden from the tool list and blocked before execution unless the user explicitly asks for external research. If the model still attempts web research, progress logs the query or URL it tried to check, then redirects the turn back to local code evidence. When the active task itself is a latest/current research request, continuation turns preserve that web-research intent until a web result exists, but fresh local code, git, or verification requests reset the priority back to local evidence.
In explicit fix flows, complete high-severity findings and actionable medium correctness, stability, or performance findings block the repair gate even when they are not security findings. Low-severity style, formatting, and maintainability findings stay as pre-fix warnings unless explicitly marked as blockers.
Pre-write review treats build/test verification gaps as post-edit obligations, not reasons to block the edit preview. Warnings that say only "verification was skipped" stay visible but do not force another patch rewrite, while patch-local style problems such as Allman brace or indentation violations do block so the edit can be corrected before writing. A verification report is treated as current only if it was produced for the current patch transaction and changed paths; stale session or persisted verification history becomes a runtime-gate warning rather than a review blocker. Artifact-writing build/test shell commands ask with the same pinned confirmation style as diff preview (Run automatic verification now? [y=run once, a=session auto-run, n=skip, Esc=cancel]), and non-interactive -prompt -y auto-approves that prompt just like diff preview. The lifecycle mirrors Codex command approvals: request approval, record the user decision, then record execution/result evidence only if the command actually ran. Background verification starts are pending evidence gaps until a poll records a completed pass or failure. Once verification is declined or skipped, same-turn shell verification retries and latest background polls are rejected with NOT_EXECUTED before any new shell/progress status is emitted. A final answer that discloses skipped verification satisfies the disclosure obligation only; it does not create successful evidence, so changed paths without a successful verification report keep the edit-loop status at risk_accepted. Background job bundle metadata keeps job-list evidence in job_entries and reserves scalar job_status for single-job state. After an edit, failed automatic verification is classified against the current patch scope before Kernforge asks the model to repair. Only direct command/scope references or failure lines that name the changed path can continue the repair loop; workspace or sibling-file failures without changed-path evidence are reported as verification risk and must not broaden edits into unrelated source or project files. An out-of-scope automatic verification failure no longer rejects same-turn tool calls with NOT_EXECUTED: interactive runs ask once per turn whether to keep repairing or to finish with the failure disclosed as ambient risk, and non-interactive runs fall back to guided continuation bounded by the edit-loop retry budget, so the turn cannot dead-lock in a final-answer-only state. Build artifact churn from verification commands is tolerated, but source/config file mutations are still rejected outside the edit review gate. C++/MSBuild adaptive verification prefers the nearest .vcxproj for changed source files and includes that project's declared Configuration|Platform properties when available, so MSBuild does not silently use an unsupported default platform. Full solution builds stay explicit full verification. Configured verification tool paths are normalized at the shell boundary; on PowerShell, quoted executable paths are invoked with & so a detected MSBuild/CMake/CTest/Ninja path does not become a string literal. Verification summaries keep both the logical command and the resolved shell command when they differ, and missing-tool classification keys off the primary executable instead of unrelated compiler/build text. Non-bypass non-interactive -prompt runs still render the verification plan plus the pinned confirmation label and read piped answers. EOF or missing stdin becomes a visible skipped/declined verification decision, not an invisible default approval or a fake tool failure. After an out-of-scope automatic verification failure, Kernforge also removes all tool definitions from the next model request so the route is forced into final-answer-only mode. If a scripted or degraded route still emits a tool call, Kernforge answers it as NOT_EXECUTED and repeats the terminal-state guidance. A final answer produced in this terminal state is not routed back through post-change review or final-answer repair gates for the same external blocker; Kernforge only ensures that the verification risk is disclosed. Final-answer text is sanitized outside code fences to collapse accidental repeated sentence runs and fix adjacent Korean sentence spacing from degraded/local routes. Review, final-answer, and completion-audit ledgers are scoped to the patch transaction when one exists. Ambient dirty git files remain visible for git-write gates, but they do not invalidate a review of the current repair patch.
Claude Code CLI built-in choices display the current Claude family version, but Kernforge passes CLI-safe aliases such as sonnet, opus, and haiku to the command. /review, natural-language review, and pre-fix repair checks are main-first: the active main model produces the first structured review from local evidence, then the optional cross route runs over the same evidence plus the primary draft. When no distinct cross route is configured, Kernforge runs a separate single_model_second_pass review phase through the primary route instead of relying only on prompt instructions. That pass receives the original request, touched files, relevant diff, implementation reply, latest verification summary, and first-pass review, then returns normal ReviewFinding records consumed by the same gate and repair loop. Accepted second-pass fingerprints are cached so identical reviewed diffs do not create infinite loops. The selected request class decides whether this is read-only review evidence, review-before-repair evidence, post-change self-review evidence, or document-artifact validation disclosure. Cross-review failures, empty responses, or weak output degrade the run and stay visible, but do not prevent the main review findings from being reported or the repair loop from starting. Actionable cross-review findings are persisted in cross_review_triage and must become exactly one of accepted_fixed, accepted_deferred, rejected_with_reason, or needs_user_decision; missing fix evidence, deferral reasons, technical rejection reasons, or actionable user-decision guidance become deterministic review blockers.
Implicit automatic model-backed reviews obey review.model_review_consent (ask by default, always, or never). Set it in user config (~/.kernforge/config.json) or trusted workspace config (.kernforge/config.json) under "review": {"model_review_consent": "ask"} using ask, always, or never, then run /reload; /status, /config, and /model cross-review status show the effective value. Automatic flags such as auto_after_change, auto_after_goal_iteration, and auto_before_git_write only make reviews eligible; they do not send a reviewer model request by themselves. The prompt is Run model review now? [y=run once, a=session auto-review, n=skip, Esc=cancel]; y runs once, n records skipped_by_user, a allows future implicit model reviews for the current session, and non-interactive ask skips with skipped_no_interactive_consent. On a single-model route (no independent reviewer configured anywhere), ask skips automatically with skipped_single_model_route and the prompt is not shown; always remains the explicit opt-in that keeps implicit self-reviews running. Explicit /review, natural-language review requests, MCP kernforge_review, and explicitly registered review automation remain explicit. Skipped or blocked automatic reviews expose the reviewer verdict/skip reason and preserve the original user-visible main-model proposal/ref when available.
The cross review route defaults to at least effort=high, and saved low/medium values are raised to high when the reviewer request is built. Focused pre-fix bug-hunt reviews keep that minimum even when the selected cross route was configured with a lower effort. Pre-write review remains the hard edit gate: once a concrete edit preview exists, a required main or cross reviewer that fails, returns an empty response, or completes with weak quality blocks the write as insufficient_evidence; Kernforge stops before touching files and reports the reviewer route problem instead of asking the implementation model to retry or gather web evidence. If the main first-pass pre-write review was usable, the stop message also offers an explicit fallback phrase (proceed with the main model review). When the user replies with that phrase and an interactive diff preview is available, Kernforge reruns the pre-write review with the cross-reviewer failure recorded as degraded evidence but no longer as a hard blocker, then still requires the normal diff preview confirmation before writing. On a single-model route the pre-write self-review (when it runs at all) is advisory end to end: its model findings surface as warnings, never as pre-write blockers, and the diff preview is the gate.
When pre-write review approves proceeding to diff preview, Kernforge prints the final review body before asking for diff preview confirmation. The visible body includes the verdict, blocker/warning counts, repair targets checked, remaining review items, evidence, impact, required fix, and test recommendation, and long fields are not hidden behind ... ellipses.
If a reviewed repair still fails the pre-write gate or exhausts its narrow inspection budget, Kernforge reports that the review did not pass, shows the latest review result and selected edit proposal, and asks Should I keep repairing from this review result? [y=continue, n=stop]. The confirmation is session state, not a natural-language prompt: only y resumes from the stored review/proposal, and n stops. After edit-target mismatch or pre-write repair blocking, broad recovery apply_patch calls are deferred without modifying files. A blocked pre-write proposal is not treated as current workspace state: before the next edit tool can run, the model must re-anchor with read_file, grep, or git_diff. replace_in_file mismatches include expected/current context diagnostics and name ambiguous matches explicitly; every mismatch re-requires a reanchor before another context edit, and document-deliverable turns keep context edit tools disabled until write_file succeeds. Review artifacts label unapplied previews as Proposed Paths or Blocked Proposal Paths, not Changed Paths, and the lifecycle applying_change phase remains pending or blocked until a write is applied. The next edit must be a current-file, narrow standalone patch; repeated broad recovery attempts stop with the latest review and proposal shown to the user.
External verification callbacks are normalized into the same runtime evidence contract as built-in verification. When a successful callback report omits GeneratedAt, Trigger, Workspace, or ChangedPaths, Kernforge fills them from the automatic verification request before review evidence and runtime-gate freshness are computed.
Non-interactive single-shot runs (-prompt, -command, -goal, and -goal-file) do not install the interactive cancel watcher. Mirroring Codex-style explicit event/decision boundaries, ambient keyboard state that cannot be confirmed by the user is not promoted to request cancellation, and long review/repair/goal loops stop only on real model, tool, or approval state.
Normal work turns print an elapsed-time line at completion. Local meta commands such as /exit, /status, /config, and /model suppress the elapsed-time footer.
The current review hardening layer records review action envelopes, approval ledgers, capability manifests, external lookup intents, artifact integrity, ledger consistency, resume sanity, and route health in the review run. Replay fixtures cover reviewer route failure, omission/truncation, patch mismatch loop, local web blocking, pre-fix repair obligations, compact final review output, RF-scoped repair handoff, and MCP response contracts.
Before a modification or local review final answer is exposed, the pre-final coding harness now enforces completion facts by request class. Modification replies must name changed files or clearly say no files changed, state review/self-review outcome, state validation outcome or why validation was not run, and state remaining risk or no known blocker. Review-only replies must remain read-only, lead with findings or an explicit no-finding result, and mention residual test/evidence risk when no issue is found. Review-then-modify replies must expose the review finding basis before repair, then summarize the scoped patch, post-change review or second-pass state, validation, and residual risk. Generated-document-only and trivial status/command turns are skipped from code-review completion gates so this gate does not over-block non-code flows; document artifacts still need artifact path and artifact-quality validation disclosure.

2.9 Tracked Feature Workflow

Purpose:

Create a long-lived feature workspace instead of a disposable plan.
Persist spec, plan, task, and implementation artifacts under .kernforge/features/<id>.
Separate planning from execution so large changes can be resumed safely.

Useful commands:

/new-feature <task>
/new-feature
/new-feature next
/new-feature list

Best used when:

A feature will span multiple sessions or handoffs.
You want explicit artifacts for scope, sequencing, and acceptance tracking.
You want implementation to be an explicit follow-up step instead of happening immediately after planning.

Current integration:

/new-feature <task> creates feature.json, spec.md, plan.md, and tasks.md.
The created feature becomes the active feature in the session status.
/new-feature shows the active feature, artifact paths, task preview, and next action.
/new-feature next executes the saved tracked plan, guides verification, or closes after a passing verification.

2.10 Interactive Ergonomics

Purpose:

Reduce typing friction in long investigative and verification-heavy sessions.
Make command discovery faster when subcommands or ids are easy to forget.

What Tab completion now covers:

Slash commands (Everyday + Hub preferred; expert aliases appear when their prefix matches)
Workspace paths and @file mentions
MCP resource and prompt targets
Fixed command arguments such as /settings auto-verify on|off, /settings progress-display auto|compact|stream, /permissions, /checkpoint auto, /provider status|openai-codex-subscription|openai-codex-cli|openai-api|anthropic-claude-cli|anthropic-api|deepseek|openrouter|opencode|opencode-go|ollama|lmstudio|vllm|llama.cpp, /profile list|pin|unpin|rename|delete, /model cross-review|clear cross-review|status, /verify --full, /investigate start <preset>, /simulate <profile>, /analyze project --mode <mode>, and /probe fuzz|scan|…
Saved ids for /resume, /memory evidence show, /memory show, /memory promote, /memory demote, /memory confirm, /memory tentative, /investigate show, and /simulate show; /new-feature uses the active feature instead of id-heavy subcommands
Inline descriptions for command and subcommand suggestions so the completion list explains what each candidate does

Command surface note:

Default /help is Everyday + Hub only; /help all prints the full catalog.
Prefer hubs (/selection, /analyze, /probe, /mcp, /hooks, /settings) over memorizing every legacy alias.
Legacy top-level names remain as hidden aliases for one compatibility window.

Prompt budget behavior that now matters:

Cached analyze-project summaries can be injected ahead of auto-scouted code snippets when they are more relevant.
If the cached project analysis and architecture fact pack are sufficient to answer a question, Kernforge can reply without spending extra tool iterations.
Deep project-structure answers are evaluated against deterministic facts, source anchors, closed directory sets, and flow invariants; contradictions trigger tool use instead of a confident cached answer.
Skill and MCP catalogs are now included in full only when the request is actually asking about them.
Auto-scout contributes fewer candidates and less text, and it now focuses on locate/definition/reference-style requests.
The default max_tokens is 8192; config files that still hold the old default 4096 are migrated at startup or /reload.
The default max_tool_iterations is 0 (unlimited). File search and large documentation turns no longer stop at the old default 16-tool cap unless you explicitly re-pin a positive limit, for example /set-max-tool-iterations 24.
When project analysis workers or review routes share the same OpenRouter or DeepSeek route as the main model, the default model-route limit is 2 to reduce upstream rate-limit or dynamic-concurrency cascades. Override model_routes.provider_limits.openrouter or model_routes.provider_limits.deepseek only when your key/provider pool can sustain more concurrency.
/analyze-project now uses the same progress ledger as tool/model streaming: auto records durable shard/wave and model-wait updates, compact keeps them in the footer, and stream records every update for long-run debugging.
Kernforge seeds the opt-in $goal-to-slice-planner skill into the user skill directory on startup. Use it explicitly before large implementation work when you want a draft-only slice plan with validation and documentation steps.

3. Recommended Real-World Flows

3.1 Driver Hardening Or Signing-Sensitive Work

Situation:

You changed driver/guard.cpp or driver/guard.inf.
Signing, symbols, verifier, or packaging readiness matters.
Similar failures happened recently.

Recommended flow:

/investigate start driver-visibility guard.sys
/investigate snapshot
/investigate note current driver visibility snapshot captured before edit
/simulate tamper-surface guard.sys
/open driver/guard.cpp
Select the relevant protection logic in the viewer.
/review selection integrity risk paths and verifier interactions
/edit-selection harden registration and signing assumptions
/verify
/evidence dashboard category:driver
/memory search category:driver signal:signing
/investigate stop hardened signing path reviewed

What Kernforge adds here:

A live driver-visibility capture before editing.
A tamper-oriented risk review before editing.
Automatic risk-oriented prompt context during review and edit.
Driver-aware verification steps plus recent investigation and simulation follow-up review steps.
Evidence-aware push or PR policy later.

3.2 Telemetry Provider Drift Or XML And Manifest Regression

Situation:

You changed a provider manifest and registration logic.
Runtime visibility is uncertain.
You also care about observer coverage and post-incident traceability.

Recommended flow:

/investigate start provider-visibility MyProvider
/investigate snapshot MyProvider
/simulate stealth-surface MyProvider
/open telemetry/provider.man
Select the manifest region.
/review selection provider visibility and schema drift
/open telemetry/register_provider.cpp
/edit-selection align provider registration and fallback visibility
/verify
/evidence search category:telemetry outcome:failed
/simulate forensic-blind-spot MyProvider
/memory search category:telemetry signal:provider
/investigate stop provider contract and visibility reviewed

Why this works well:

Investigation captures real provider state.
Stealth simulation asks whether you can still observe the path.
Forensic blind spot simulation asks whether later reconstruction will still work.
Verification turns those concerns into explicit review steps.

3.3 Memory Scan Or Pattern Scan Regression Work

Situation:

You are adjusting scanner logic for false positives, false negatives, or evasion resistance.
Recent scanner-related failures already exist.

Recommended flow:

/simulate stealth-surface scanner-core
/open scanner/patternscan.cpp
/review selection false positives, stealth coverage, and performance ceilings
/edit-selection reduce false positives without weakening evasion coverage
/verify
/evidence dashboard category:memory-scan
/memory search category:memory-scan risk:>=70

Why this works well:

Scanner work is usually about coverage and evasion, not just correctness.
Simulation brings an extra risk lens into the prompt.
Verification reasserts those review concerns before the loop closes.

3.4 Large Multi-Step Change With Plan Review

Situation:

The change spans driver and telemetry concerns together.
Ordering, rollback, and review discipline matter.

Recommended flow:

/simulate tamper-surface guard.sys
/simulate forensic-blind-spot guard.sys
/review plan harden driver registration, improve telemetry visibility, and preserve post-incident artifacts
Let the reviewer critique the plan.
Execute the approved plan.
/verify
/evidence dashboard

Current strength:

Simulation findings can shape the planning prompt.
They can also shape the final plan execution prompt.

3.5 Tracked Feature Lifecycle Across Multiple Sessions

Situation:

The work is substantial enough that you want durable planning artifacts.
You expect implementation, verification, and closure to happen over more than one sitting.

Recommended flow:

/simulate tamper-surface guard.sys
/new-feature harden driver registration, preserve telemetry audit artifacts, and document rollback points
/new-feature
Review the generated spec.md, plan.md, and tasks.md under .kernforge/features/<id>.
/new-feature next
/verify
/new-feature next

Why this works well:

The feature state survives session boundaries.
Planning artifacts are explicit and easy to inspect or regenerate.
Execution is intentionally separated from planning, which reduces accidental long-running edits from a rough first draft.

4. Command-By-Command Practical Usage

4.1 `/investigate`

Basic usage:

/investigate start driver-visibility guard.sys
/investigate snapshot
/investigate note verifier enabled on target system
/investigate stop initial driver state captured

Good use cases:

Before editing, when you want the current driver visibility or verifier state on record.
When you want a quick triage snapshot before deeper driver load debugging.
When you want to confirm a telemetry provider is really visible live.
When you want a reusable runtime record that later verification and review can reference.

Key interpretation:

Investigation does not replace verification.
It captures the real-world state that should inform later work.
In particular, driver-visibility is a lightweight visibility snapshot, not a full driver load analyzer.

4.2 `/simulate`

Basic usage:

/simulate tamper-surface guard.sys
/simulate stealth-surface MyProvider
/simulate forensic-blind-spot game.exe

Good use cases:

Right after a driver change, to look for integrity or registration risk surface.
Right after a telemetry change, to inspect observer visibility gaps.
When you want to know whether post-incident artifacts will still be usable.

Key interpretation:

Simulation is not proof of exploitation.
It is a structured way to highlight heuristic risk signals that deserve review.

4.3 `/review selection` And `/edit-selection`

Basic usage:

/open driver/guard.cpp
/review selection check risk surfaces and cleanup paths
/edit-selection harden the selected registration path

Good use cases:

When only one function or block matters.
When you want recent simulation findings tied directly to the selected area.

Current automatic behavior:

If recent simulation findings match the selected path, Kernforge injects Additional simulation risk focus into review and edit prompts.

4.4 `/review plan`

Basic usage:

/review plan harden driver load validation, improve telemetry provider visibility, and preserve audit artifacts

Good use cases:

Large or high-risk changes.
Work where rollback points and sequencing matter.
Cases where risk-oriented thinking should shape the implementation plan before edits begin.

Current automatic behavior:

Matching recent simulation findings are injected into the planning prompt.
They are also injected into the execution prompt after approval.

4.5 `/new-feature`

Basic usage:

/new-feature harden driver registration, preserve telemetry audit artifacts, and document rollback points
/new-feature
/new-feature next
/verify
/new-feature next

Good use cases:

New features that need durable scope and execution artifacts.
Work that should pause after planning so you can review or resume later.
Changes that benefit from an active feature id in session context.

Current automatic behavior:

A tracked feature workspace is created under .kernforge/features/<id>.
spec.md, plan.md, and tasks.md are generated when you create the feature and regenerated when a blocked feature continues through next.
/new-feature next executes the saved plan and writes implementation.md.
After implementation, /new-feature next guides verification first and closes only after a passing verification is recorded.

4.6 `/verify`

Basic usage:

/verify
/verify --full
/verify driver/guard.cpp,telemetry/provider.man

What the planner currently considers:

Changed files
Security categories
Verification policy
Verification history tuning
Hook-injected context and extra steps
Recent investigation and simulation state

Good use cases:

After editing, when you want a real verification plan instead of a generic test command.
When recent investigation or simulation findings should influence validation.
When you want security-aware review steps in addition to build or test steps.

4.7 `/evidence search` And `/evidence dashboard`

Useful queries:

/evidence search category:driver outcome:failed
/evidence search kind:simulation_finding severity:critical
/evidence search signal:tamper risk:>=60
/evidence dashboard category:telemetry

Good use cases:

When you want to inspect what simulation just produced.
When you want only recent signing, provider, or scanner-related failures.
When you want to see active overrides and recent high-risk state together.

4.8 `/memory search`

Persistent memory is also injected automatically before the model sees a new turn. Kernforge now includes a small Workspace continuity section with recent high-value records from the same workspace, then adds Query matches when the current prompt has file mentions, ASCII search terms, or structured filters. When continuity memory is injected, a visible memory activity line lists the reused memory ids and compact summaries. This helps a fresh session remember recently touched files, verification outcomes, completed steps, and failed attempts without rereading the same project docs first.

Useful queries:

/memory search category:driver signal:signing
/memory search category:telemetry tag:provider
/memory search severity:critical risk:>=80
/memory search artifact:guard.sys

Good use cases:

When you want earlier reasoning from previous sessions.
When you want long-lived context for repeated artifacts or failures.

4.9 `/hooks` And `/override-*`

Inspect:

/hooks
/override

Create an exception:

/override add deny-driver-pr-with-critical-signing-or-symbol-evidence 4 urgent hotfix after manual verification

Clear:

/override clear all

Good use cases:

When you want to understand why policy is blocking.
When you need a temporary exception with an audit trail.

4.10 `/fuzz-func`

Basic usage:

/fuzz-func ValidateRequest
/fuzz-func ValidateRequest --file src/guard.cpp
/fuzz-func ValidateRequest @src/guard.cpp
/fuzz-func ValidateRequest --source-scan focused
/fuzz-func ValidateRequest --source-scan full
/fuzz-func ValidateRequest --no-source-scan
/fuzz-func --from-candidate sc-0123456789abcdef
/fuzz-func @Driver/HEVD/Windows/DoubleFetch.c
/source-scan run --limit 50
/source-scan show latest
/fuzz-func show latest
/fuzz-func language system
/fuzz-campaign
/fuzz-campaign run
/create-driver-poc AcmePoc

What the planner currently considers:

Function signatures and parameter types
Real size, null, dispatch, and cleanup guards in the function body
Probe, copy, alloc, publish, and cleanup sinks on the same path
The caller/callee chain from the representative root
The file-expansion path from the selected starting file into the cited source file
Saved source candidates, focused source-scan results, and the matcher slug that linked the function fuzz plan
Build context, compile_commands.json, and snapshot or semantic-index availability

Good use cases:

When you want to see branch flips and sink reachability on input-facing driver or anti-cheat code quickly.
When you know the suspicious file but not the best root function yet.
When you want concrete "which value breaks which predicate and opens which copy/probe path" guidance before normal review or editing.

5. When To Use Each Dashboard

5.1 `/verify dashboard`

Best when:

You want recent verification trends.
You want to see which checks fail most often.

5.2 `/evidence dashboard`

Best when:

You want the current workspace risk picture.
You want recent failed or high-risk signals plus overrides in one view.

5.3 `/memory dashboard`

Best when:

You want long-term context, trust tiers, and verification artifact patterns.
You want to skim what the system has learned across sessions.

5.4 `/investigate dashboard`

Best when:

You want to see how many investigation sessions exist.
You want preset, finding category, and finding severity distribution.

5.5 `/simulate dashboard`

Best when:

You want to see which risk profiles you have been using.
You want severity, signal, finding, and recommended-action breakdowns.

6. Suggested Baselines By Team

6.1 Driver Team

Recommended:

Enable windows-security.
Run driver-visibility investigation before risky changes.
Run tamper-surface simulation before review or edit.
Run /verify.
Inspect /evidence dashboard category:driver.
Promote only repeated high-risk failures to deny.

6.2 Telemetry Team

Recommended:

Use provider-visibility investigation before manifest and provider changes.
Run stealth-surface after provider changes.
Run forensic-blind-spot when incident traceability matters.
Run /verify.
Inspect /evidence search category:telemetry outcome:failed.
Use /memory search category:telemetry tag:provider for long-lived context.

6.3 Anti-Cheat Or Memory-Scan Team

Recommended:

Use stealth-surface before scanner changes.
Use selection-first review and edit aggressively.
Run /verify.
Let repeated high-risk failures drive checkpoint and deny policy.

7. Cases Where You Should Not Over-Enforce Yet

Avoid overly strong policy in these cases:

Very early prototyping
New projects with almost no evidence history
General utility work not tied to the security workflow

Recommended progression:

Start with warn
Move recurring issues to ask
Reserve deny for genuine operational incident classes

8. Quick Scenario Recipes

Scenario A: Driver Integrity Hardening

/investigate start driver-visibility guard.sys
/investigate snapshot
/simulate tamper-surface guard.sys
/open driver/guard.cpp
/review selection integrity risk paths
/edit-selection harden the selected integrity checks
/verify
/evidence dashboard category:driver

Scenario B: Telemetry Provider Visibility Drift

/investigate start provider-visibility MyProvider
/investigate snapshot MyProvider
/simulate stealth-surface MyProvider
/open telemetry/provider.man
/review selection schema and visibility drift
/verify
/evidence search category:telemetry outcome:failed

Scenario C: Plan Review Before A Large Change

/simulate tamper-surface guard.sys
/simulate forensic-blind-spot guard.sys
/review plan harden driver registration and preserve telemetry audit artifacts
/verify
/simulate dashboard

Scenario D: Source-level fuzzing for input-facing path triage

/fuzz-func @Driver/HEVD/Windows/DoubleFetch.c
/fuzz-func TriggerDoubleFetch --file Driver/HEVD/Windows/DoubleFetch.c
/fuzz-func show latest
/fuzz-campaign
/fuzz-campaign run
/verify

Interpretation:

The first run starts coarse at file scope so Kernforge can pick the representative root and the highest-risk reachable path.
The second run pins the target function so predicates, counterexamples, and branch deltas become more precise.
show latest lets you re-read the report and source excerpts before moving into verification or code changes.

Scenario E: Tracked Feature With Explicit Execution

/simulate tamper-surface guard.sys
/new-feature harden driver registration and preserve telemetry audit artifacts
/new-feature
/new-feature next
/verify
/new-feature next

9. Summary

The best current one-line description of Kernforge is this:

"Observe first, apply a risk lens, work in focused code regions, verify with recent context, and feed the result back into evidence, memory, and policy."

That means the strongest current loop is:

/investigate
/simulate
/fuzz-func
/review selection or /edit-selection
/review plan
/new-feature
/verify
/evidence dashboard
/memory search
Push or PR under hook policy

That loop is the clearest current Kernforge differentiator.