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.