From 461541348e66d71cddcda02db002ce195a8979d9 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Fri, 23 Oct 2026 17:09:35 +0800 Subject: [PATCH] docs: clarify evidence ownership and verification guidance --- docs/ghidra-dos.md | 22 ++++++++++++---------- docs/testing.md | 8 +++++++- docs/tool-design.md | 9 +++++++-- 3 files changed, 26 insertions(+), 13 deletions(-) diff --git a/docs/ghidra-dos.md b/docs/ghidra-dos.md index 4cd14673d6..8f7b8a98d8 100644 --- a/docs/ghidra-dos.md +++ b/docs/ghidra-dos.md @@ -23,17 +23,19 @@ not name its entry function `entry`. MCP uses `open_binary`, `list_procedures`, `procedure_info`, `read_function_instructions`, and `analyze_function` with the same admitted target and provider semantics. -The classifier validates MZ page counts, initialized module length, header and +The DOS MZ parser validates page counts, initialized module length, header and relocation-table bounds, relocation destinations, and the initialized entry -point. DOS structural facts are parsed independently from Windows-header -evidence. A recognized PE signature remains PE; recognized NE, LE, and LX -headers are explicitly unsupported. A nonzero Windows-header pointer without a -recognized signature remains an unresolved candidate, even when the DOS -structure validates: automatic target selection fails closed and reports the -DOS facts alongside the candidate. REA does not infer DOS intent from padding -or infer a damaged Windows header from the pointer alone. Inventory -classification returns `unknown` for that candidate and when its bounded prefix -cannot establish the format; this is distinct from complete DOS validation. +point using the available structural bytes and actual file length. It reports +those DOS facts separately from Windows-header evidence. A recognized PE +signature remains PE; recognized NE, LE, and LX headers are explicitly +unsupported. A nonzero Windows-header pointer without a recognized signature +remains an unresolved candidate, even when the DOS structure validates: +automatic target selection fails closed and reports both observations. +REA does not infer DOS intent from padding or infer a damaged Windows header +from the pointer alone. Inventory classification is a bounded-prefix format +hint; it returns `unknown` for that candidate or when its prefix cannot +establish the format. That result is distinct from complete DOS validation and +does not decide target admission. Ghidra imports a private target snapshot with `MzLoader`, language `x86:LE:16:Real Mode`, and compiler specification `default`. These settings, diff --git a/docs/testing.md b/docs/testing.md index fbac13ef5a..4b6c28eff8 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -236,7 +236,13 @@ instrumentation remains equivalent. ## Choose verification for the change -| Change or claim | First check | Additional coverage | +`test:local` is fast source-level feedback. For the strongest practical +regression, prefer a real public CLI/MCP workflow, then production-boundary +integration, then a producer golden; use the table to select quick feedback and +claim-specific additional evidence. Provider-behavior claims require the +matching real-provider lane. + +| Change or claim | Fast feedback | Claim-specific coverage | | ----------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------- | | Source semantics | `npm run test:local -- PATH...` | Relevant boundary cases when the behavior crosses a port | | CLI/MCP workflow | `npm run test:focused -- PATH...` | Actual public calls; an injected provider has limited scope | diff --git a/docs/tool-design.md b/docs/tool-design.md index 5ed533edc8..2650128e13 100644 --- a/docs/tool-design.md +++ b/docs/tool-design.md @@ -30,8 +30,13 @@ inside one tool. A primitive reports a reusable fact about an identified object or relationship. A format-specific decoder qualifies; one application's business interpretation -belongs outside the general contract. Expose provider APIs when they add a -useful capability that existing tools cannot express. +belongs outside the general contract. The format owner reports source +observations and structural validation; the application or workflow owner +applies use-case-specific admission policy without reinterpreting raw fields. +For example, DOS MZ structure and Windows-header evidence stay separate, while +target resolution decides whether the unresolved header permits admission. +Expose provider APIs when they add a useful capability that existing tools +cannot express. Compose a workflow when repeated use demonstrates a multi-source outcome REA can join without hiding caller choices or uncertainty. Batch homogeneous reads