Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

docs: clarify evidence ownership and verification guidance

morluto461541348e66
diff --git a/docs/ghidra-dos.md b/docs/ghidra-dos.md
index 4cd14673d..8f7b8a98d 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 fbac13ef5..4b6c28eff 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 5ed533edc..2650128e1 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