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

morlutoa9e00b83f376
diff --git a/AGENTS.md b/AGENTS.md
index 5585ecadd..d60f2b07f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,8 +21,8 @@ REA is a layered ESM TypeScript application. Dependencies flow inward from pure
- `src/domain/` owns pure provider-neutral semantics; `src/contracts/` owns caller-visible schemas and the canonical tool inventory.
- `src/hopper/`, `src/ghidra/`, `src/ida/`, `src/browser/`, `src/inspector/`, `src/native/`, `src/artifacts/`, and `src/dotnet/` own provider-specific boundaries. Keep provider protocols out of domain and application code.
-- `src/application/` composes shared CLI/MCP workflows; `src/server/` translates MCP requests; `src/cli.ts` and `src/main.ts` are the CLI and MCP entry points.
-- `src/process/` owns shared process lifecycle primitives, not provider wire protocols. `bridge/` contains provider-side adapters.
+- `src/application/` composes shared CLI/MCP workflows, including Evidence provenance, unknowns, and eligible snapshot bindings; `src/server/` translates MCP requests; `src/cli.ts` and `src/main.ts` are the CLI and MCP entry points.
+- `src/process/` owns shared process lifecycle primitives, not provider wire protocols. Reuse its supervision and identity primitives before adding provider-local lifecycle code; a PID and executable pathname alone do not establish ownership after exit or reuse. `bridge/` contains provider-side adapters.
- `tests/` contains unit, composition, boundary, acceptance, and conformance tests. `scripts/verify-*` and capability directories under `scripts/verify/` contain real-toolchain checks.
- `docs/public/product-catalog.json`, `docs/verification/managed-conformance-*.json`, and `skills/` are ignored build outputs. Update source contracts and authored instructions in `skill-src/`, then run `npm run build:cached`; never commit derived catalog digests or portable conformance projections.
- `src/generatedMcpToolCatalog.ts` is build-generated and gitignored. Never commit it; resolve any trace of it in merges by deleting it and running `npm run build:cached`.
@@ -56,9 +56,9 @@ Treat a boundary as a contract between the producer's actual representation and
When changing boundary behavior, inspect adjacent input representations, failure paths, and affected callers, and correct the underlying assumption across those cases.
-Keep portable evidence and scenario validation distinct from host-native execution checks. Absolute filesystem paths, file URLs, and HTTP paths have different semantics; do not substitute one platform's syntax for the domain concept. Interpret provider metadata according to its documented or observed producer behavior. When a transformation loses information, preserve the reported value and an explicit unknown rather than guessing a canonical identity.
+Keep portable evidence and scenario validation distinct from host-native execution checks. Absolute filesystem paths, file URLs, and HTTP paths have different semantics; do not substitute one platform's syntax for the domain concept. Interpret provider metadata according to its documented or observed producer behavior. Keep values used for identity, provenance, matching, and path resolution separate from display formatting. When normalization loses information, preserve the source value and an explicit unknown; display placeholders must not feed back into lookup or selection.
-Preserve meaningful failure reasons through application and adapter layers. Malformed input is distinct from an unsupported target, unavailable provider, or host operating-system permission denial. Diagnostics should identify the failed constraint and the target or lifecycle request it applies to. Recovery advice must address that reason and point to an available workflow; generic catches must not erase actionable validation details.
+Preserve meaningful failure reasons through application and adapter layers. Malformed input is distinct from an unsupported target, unavailable provider, or host operating-system permission denial. Diagnostics should identify the failed constraint and the target or lifecycle request it applies to. Recovery advice must address that reason and point to an available workflow; generic catches must not erase actionable validation details. Preserve collected observations on execution failure independently of whether cleanup succeeds.
Leave meaningful target, action, capture, and output choices to the agent. A selected operation already expresses intent; do not require approval booleans or repeated permission declarations. Trace each setting to its consumer: remove ignored options and single-value confirmations, derive built-in lifecycle behavior, and supply defaults for omitted optional metadata. Report actual effects and limitations where they help interpret results rather than asking callers to restate them.
@@ -82,7 +82,7 @@ Let agents compose experiments with ordinary commands, scripts, and local fixtur
- Use **observe/capture** only when runtime activity is required, and declare authority and lifecycle effects in the contract.
- Extend an existing tool when intent and result contract are unchanged. Add a tool for a distinct analyst outcome or materially different authority.
- Keep caller-facing names and results provider-neutral. Put engine-specific behavior in provider adapters and report each provider's exact coverage.
-- Keep results complete by default. Add a limit only when it follows from a real format, protocol, authority, or resource-safety constraint; explain truncation and unsupported facets. Keep observed, derived, inferred, and unknown results distinct.
+- Keep results complete by default. Add a limit only when it follows from a real format, protocol, authority, or resource-safety constraint; explain truncation and unsupported facets. Account for representation expansion and products of independently bounded dimensions before allocating or retaining output. Derive facet completeness from what was examined and exhausted, not an empty failure list. Keep observed, derived, inferred, and unknown results distinct.
- Include artifact identity, source locations, Evidence references, actionable errors, and relevant limitations when they affect conclusions. Return the evidence needed for the next analysis inline rather than requiring a resource or identifier lookup.
- Implement shared application workflows behind CLI and MCP adapters. Update canonical contracts and generated catalog together.
diff --git a/docs/testing.md b/docs/testing.md
index 7abebdae8..bbd5df1fa 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -425,7 +425,7 @@ behavior, and complete CI evidence before merging.
| `npm run test:watch:all` | Changed tests from every project; builds at startup, so rebuild after production edits before relying on compiled tests |
| `npm run check:changed` | Cached typecheck/lint and branch-related source feedback |
| `npm run check:pr` | Opt-in complete local deterministic gate and generated-file checks |
-| `npm run docs:check` | Committed generated-document freshness |
+| `npm run docs:check` | Generated-document validation from current source and build outputs |
For example:
@@ -460,19 +460,21 @@ broad changes or diagnosing CI, rather than after every edit. Package/install
changes additionally need package verification; provider changes need actual
provider evidence.
-Local full-suite Vitest runs use up to two workers and schedule projects one
-at a time. Process, acceptance and process-global projects serialize their
-files to prevent competing lifecycle observations. CI retains its two-worker
-budget.
+Each Vitest project uses up to two workers, bounded by available host parallelism.
+Default-group projects can run together. Only `process-boundary` runs in the
+later sequence group and serializes its files because process-tree observations
+share host sampling resources. Acceptance and process-global files retain isolated
+forks but are not serialized; isolation does not imply serial scheduling. CI uses
+the same per-project worker bound.
The pure domain/contracts and recording-port service projects share one worker
module context because their tests own no mutable runtime resources. MCP
boundary files also share the immutable server module graph while creating and
closing independent in-memory sessions. Adapter, composition, acceptance,
process-global, and other boundary projects retain per-file isolation.
-`npm test`, `npm run docs:check`, and `npm run docs:generate` share
-repository-local locks and fail fast when the same class of command is already
-running. The `npm test` build is inside that lock. `check:pr` runs its test task
-before starting generated-document validation.
+Build and documentation writers use checkout-local locks for their respective
+output files. `npm test` delegates its build to the build lock; the Vitest suite
+does not hold a test-command lock. `check:pr` runs its test task before starting
+generated-document validation.
Vitest and Node persistent compile caches are deliberately not enabled by
default. To evaluate repeated local runs, opt in for both cold and warm
diff --git a/docs/tool-design.md b/docs/tool-design.md
index 965e4243c..4a5c2fab6 100644
--- a/docs/tool-design.md
+++ b/docs/tool-design.md
@@ -80,7 +80,18 @@ or model-authored loop when one call can answer the question.
## Implement and evaluate
- Put shared user workflows in the application layer; keep MCP translation in
- the server adapter and CLI behavior aligned with the same workflow.
+ the server adapter and CLI behavior aligned with the same workflow. Share
+ Evidence provenance, unknown projection, and eligible snapshot binding through
+ application/session owners. Matching result payloads alone do not establish
+ equivalent retention or replay behavior.
+- Derive each facet's coverage from examined records, unsupported representations,
+ and exhaustiveness. Keep issues structured until presentation; do not select a
+ facet by matching diagnostic prose or infer completeness from an empty failure
+ list. Preserve available observations independently of cleanup success.
+- Measure the resource consumed before choosing a limit. Value alternatives,
+ retained records, trace-frame products, output bytes, and temporary-file growth
+ need different accounting. Enforce a justified budget before the costly step
+ and report its effect; an input-byte or graph-node cap does not bound every stage.
- Update the canonical contract inventory, output schemas, examples, generated
catalog, and relevant docs together.
- Verify valid, malformed, boundary, unavailable, cancellation, and partial