kernel-corpus-analysis

Kernel Corpus Analysis

Use this skill for PseudoForge Kernel Corpus analysis. The corpus data stays outside this skill; this file only defines the operating procedure and answer contracts.

Hard rule for every major claim:

Claim -> EA -> function name -> artifact path -> inference level

First Moves

1. Locate the pack root from the user, thread context, MCP config, or a local path such as <workspace>/pseudoforge_out/kernel_corpus/<target>.
2. Run the local freshness validator when the pack may be old or when derived evidence packs/atlas pages already exist.
3. Call corpus_status before analysis. Check schema, function count, skipped count, manifest path, SQLite path, and warnings.
4. Use MCP first when available. If MCP is unavailable, use the local CLIs under tools/kernel_corpus/.
5. For cross-build or pack-revision drift questions, call compare_canonical_answers first when available. Compare by canonical topic id and normalized function name; treat EAs as build-local evidence.
6. For broad lifecycle, subsystem, or security-engineering questions, call plan_kernel_answer first when available. If the planner is unavailable, call find_canonical_answers or list_canonical_answers before live retrieval when canonical tools are available.
7. For multi-topic navigation, shared-function analysis, or "what connects these areas?" questions, call get_topic_graph, find_topic_paths, or get_function_roles when available.
8. Prefer focused evidence packs over loading broad raw corpus output.
9. Do not answer from generic Windows internals alone.

Local freshness fallback:

python -B .\tools\kernel_corpus\validate_pack.py --pack-root "<pack-root>" --include-derived --format text

Local lifecycle fallback:

python -B .\tools\kernel_corpus\lifecycle.py --pack-root "<pack-root>" --topic process_object --depth 2 --output "<pack-root>\evidence-packs\process_object.json"

Supported lifecycle topics:

• process_object
• thread_object
• file_object
• driver_object
• device_object
• registry_key
• section_object
• module_image

Local subsystem atlas fallback:

python -B .\tools\kernel_corpus\atlas.py --pack-root "<pack-root>" --output-dir "<pack-root>\reports\atlas"

Local answer harness fallback:

python -B .\tools\kernel_corpus\answer_harness.py --pack-root "<pack-root>" --evidence-pack "<pack-root>\evidence-packs\process_object.json" --question "<question>" --atlas-page process.md --prompt-out "<pack-root>\answer-prompts\process_object.md" --answer-in "<pack-root>\answers\process_object.md" --report-out "<pack-root>\answer-reports\process_object.json"

Local canonical answer fallback:

python -B .\tools\kernel_corpus\canonical_store.py find --pack-root "<pack-root>" --query "<question>" --max-topics 5
python -B .\tools\kernel_corpus\canonical_store.py get --pack-root "<pack-root>" --topic process_object_lifecycle --quality --gaps --max-chars 12000

Local answer planner fallback:

python -B .\tools\kernel_corpus\answer_planner.py --pack-root "<pack-root>" --question "<question>" --format markdown --plan-out "<pack-root>\answer-plans\planned-answer.md"

Local answer eval fallback:

python -B .\tools\kernel_corpus\answer_eval.py --pack-root "<pack-root>" --answers-dir "<pack-root>\answers" --format markdown --report-out "<pack-root>\answer-eval\answer-eval-report.md"

Local canonical drift fallback:

python -B .\tools\kernel_corpus\canonical_compare.py --pack-root-a "<old-pack-root>" --pack-root-b "<new-pack-root>" --topic process_object_lifecycle --format markdown --report-out "<workspace>\pseudoforge_out\kernel_corpus\drift\process_object_lifecycle.md"

Local knowledge graph fallback:

python -B .\tools\kernel_corpus\knowledge_graph.py --pack-root "<pack-root>" --priority P0 --include-atlas --include-lifecycle --format markdown --output "<pack-root>\reports\knowledge-graph.md"
python -B .\tools\kernel_corpus\knowledge_graph.py shared-functions --pack-root "<pack-root>"
python -B .\tools\kernel_corpus\knowledge_graph.py function-topics --pack-root "<pack-root>" --function PspAllocateProcess

Tool Workflow

• Cross-build drift questions: call compare_canonical_answers for compact JSON, or get_canonical_drift_report for bounded Markdown. Inspect missing topics, quality/status changes, same-name different-EA entries, selected-function additions/removals, phase changes, edge changes, and stale quality warnings before drafting.
• Relationship/navigation questions: call get_topic_graph for a bounded subgraph, find_topic_paths for topic-to-topic paths, or get_function_roles for all topic roles of a function. Use graph output to choose follow-up canonical answers, evidence packs, get_function, or get_neighbors.
• Canonical answer questions: call find_canonical_answers for the user's wording, then get_canonical_answer for the best passing topic. Inspect quality.md and gaps.md; use degraded topics only with caveats, and use failed topics only as retrieval hints. Cite the canonical topic id alongside EA, function name, and artifact path.
• Broad natural-language questions: call plan_kernel_answer and follow its selected canonical candidates, live retrieval steps, citation contract, and stop conditions before drafting. The planner does not generate final prose.
• Lifecycle questions: call trace_lifecycle first with topic such as process_object, thread_object, file_object, driver_object, device_object, registry_key, section_object, or module_image, then inspect high-impact functions with get_function, and use get_neighbors for ambiguous transitions.
• Function questions: use search_functions or exact EA lookup with get_function; request disassembly when pseudocode precision matters, inspect data refs, then cite cleaned/raw/disassembly/summary artifact paths.
• Subsystem questions: generate or inspect atlas pages first when available; then search by names, tags, imports, and strings; expand nearby callers/callees; build an evidence pack for broad answers.
• Import/string/data-reference questions: use search_by_import, search_by_string, or search_by_data_ref, then verify with get_function.
• Broad answers: prefer a passing canonical answer when available, then call build_evidence_pack or trace_lifecycle for verification, gap filling, or unsupported topic boundaries.
• Freshness checks: use validate_pack.py before reusing older pack roots, lifecycle evidence packs, or atlas pages. Treat validator errors as stop-and-rebuild signals.
• Durable handoff or review: call the local answer harness to generate the bounded prompt and validate the drafted Markdown answer. For repeatable workflow regression, run answer_eval.py against the pack and drafted answers.

Canonical Answer Workflow

Use canonical answers as the first evidence layer only after freshness and quality checks:

1. Validate pack freshness before trusting canonical artifacts.
2. Call find_canonical_answers for natural-language questions, or list_canonical_answers when filtering by priority, mode, or quality status.
3. Prefer canonical answers with quality.status == pass and zero validation warnings.
4. Inspect quality.md and gaps.md before making polished claims.
5. Use live retrieval with search_functions, get_function, get_neighbors, or trace_lifecycle to verify high-impact claims and fill gaps.
6. Cite canonical topic id, EA, function name, and artifact path for important claims.

Decision matrix:

If a review queue exists, prefer topics with review_state == approved and quality.status == pass. Treat pass without approval as generated but unreviewed, not as human-reviewed truth. Treat stale approvals as review debt.

Canonical answers never override fresher function artifacts. If live retrieval contradicts a canonical draft, cite the fresh evidence and call out the canonical artifact as stale, degraded, or needing regeneration.

Evidence Discipline

• Cite EA, function name, and artifact path for important claims.
• Separate confirmed corpus evidence from inference.
• Treat lifecycle phase labels and LLM rename suggestions as hypotheses until supported by function evidence or edges.
• Expect broad graph-neighbor lifecycle candidates from another object topic to be lower-quality unless the evidence pack records exact seed or target-topic evidence.
• State gaps from skipped functions, missing exact seeds, missing edges, stale packs, or low-confidence phase assignments.
• Do not claim a transition is proven unless the evidence pack contains a supporting edge or function relationship.
• Do not hide validator errors. Rebuild stale packs or derived artifacts before answering, unless the user explicitly wants a stale-pack comparison.
• Treat answer harness warnings as citation lint that must be reviewed before reusing an answer.
• Treat answer eval results as routing and citation regression signals, not expert review of the final reverse-engineering conclusion.
• Treat canonical quality status as retrieval quality metadata: pass can be used as the first evidence layer, degraded requires explicit caveats and live verification, and fail is not final-answer evidence.
• For drift answers, cite both pack labels or roots, canonical topic id, function name, both EAs when relevant, and artifact paths from both sides. Do not describe different EAs as semantic drift unless function evidence or selected role/edge/phase changes support that inference.
• Treat knowledge graph bridge functions, shared-function counts, topic paths, and centrality-like observations as navigation hints. Do not present them as proof without function artifacts or evidence packs.
• Do not mutate the source corpus or IDB. Writing a derived evidence pack is acceptable only when the workflow or user asks for a durable artifact.

Korean Query Mapping

Map Korean questions into corpus search terms and lifecycle topics before retrieval:

Lifecycle Answer Contract

Use this shape for lifecycle questions:

Overall flow:
1. Entry
2. Allocation and initialization
3. Object insertion and visibility
4. Notification side paths
5. Exit and rundown
6. Final dereference and delete

Major functions:
- `0x...` `FunctionName`: role, phase confidence, artifact path.

Confirmed from this corpus:
- Evidence-backed observations with EA/function/path citations.

Inference:
- Clearly marked reasoning that connects evidence.

Gaps:
- Missing edges, skipped functions, ambiguous phase assignments, or missing seeds.

Function Answer Contract

For a single function:

Identity:
- EA, name, tags, mode, artifact paths.

What this function appears to do:
- Evidence-backed summary from cleaned/raw/disassembly/summary artifacts and data refs.

Callgraph/import/string/data-reference evidence:
- Direct callers/callees, imports, strings, data refs, and why they matter.

Confidence:
- Confirmed evidence vs inference, including warnings or missing artifacts.

Subsystem Atlas Contract

For a subsystem or broad flow:

Scope:
- Corpus status and retrieval query terms.

Core clusters:
- Function groups by role, with EA/name/path citations.

Edges and entry points:
- Caller/callee relationships that are present in the evidence pack.

Operational interpretation:
- What the evidence suggests, separated from assumptions.

Gaps and next retrieval:
- Missing tags, skipped functions, deeper neighbors, or extra evidence packs to build.

Atlas hub lists are filtered retrieval hints. Generic helpers and subsystem-unrelated neighbors may be intentionally absent; use get_neighbors for exhaustive graph expansion.

Guardrails

• Do not copy generated ntoskrnl data into this skill.
• Do not rely on memory or generic Windows behavior when corpus evidence is available.
• Do not treat cleaned pseudocode as perfect; inspect raw, summary, and full-function disassembly artifacts when precision matters.
• Do not hide uncertainty. A useful kernel answer can say "unknown from this corpus" and propose the next retrieval.