Merge pull request #80 from morluto/morl/roadmap-investigation-docs

Document the expanded analysis surface

AGENTS.md

@@ -11,7 +11,7 @@ See [docs/architecture.mermaid](docs/architecture.mermaid) for a visual architec
 - `src/cli.ts`: one-shot CLI adapter for setup, diagnostics, analysis, and decompilation.
 - `src/config.ts`: Zod-validated parsing of environment configuration into `AppConfig`.
 - `src/domain/`: pure, side-effect-free modules. `errors.ts` (tagged error algebra), `result.ts` (`Result`/`ok`/`err`), `hopperValues.ts` (boundary parsers for Hopper JSON), `symbolAnalysis.ts` (Swift/ObjC name parsing).
-- `src/contracts/`: caller-visible schemas for 31 direct, 8 enhanced, and 3 session tools; `enhancedInputs.ts` owns enhanced input parsing.
+- `src/contracts/`: caller-visible schemas for 33 direct, 10 enhanced, 5 native, 2 artifact, and 18 session tools; `enhancedInputs.ts` owns enhanced input parsing.
 - `src/hopper/`: Hopper launch and Unix-socket protocol mechanics. `BridgeLauncher.ts` spawns the Hopper app with the in-process bridge, `HopperClient.ts` correlates request/response over the socket with timeouts and cancellation, `protocol.ts` frames bridge messages.
 - `bridge/hopper_bridge.py`: runs inside Hopper and adapts declared operations to Hopper's public Python API. Hopper's bundled MCP server is not used.
 - `src/application/`: shared CLI/MCP session composition, setup and diagnostics, and the 8 enhanced workflows.
@@ -34,7 +34,7 @@ See [docs/architecture.mermaid](docs/architecture.mermaid) for a visual architec
 - `npm run jscpd`: detect duplicate code blocks.
 - `npm run scan:todos`: scan for TODO, FIXME, and HACK markers.
 - `npm run verify:hopper`: build and run the real-Hopper verifier with two distinct binaries.
-- `npm run verify:package`: pack and test the CLI, setup transaction, skill, and 42-tool target-free MCP server in an isolated environment.
+- `npm run verify:package`: pack and test the CLI, setup transaction, skill, and 68-tool target-free MCP server in an isolated environment.
 - `npm run docs:generate`: generate API documentation from JSDoc comments into `docs/api/` using TypeDoc.
 - `npm run config:print -- /path/to/binary`: print an MCP server config with absolute paths.
 - `HOPPER_TARGET_PATH=/path/to/binary npm start`: launch Hopper and run the built stdio MCP server.
@@ -54,7 +54,7 @@ Use ESM TypeScript, two-space indentation, and Prettier defaults. Keep compiler
 
 ## Testing Guidelines
 
-Name tests `*.test.ts`. Use Vitest and production seams (`tests/fixtures/`) rather than module mocks. Domain tests assert pure behavior; adapter tests use the fake launcher/socket; MCP tests connect with the beta.3 client. Preserve the 31 direct, 8 enhanced, and 3 session tool inventory (42 total). Cover malformed input, cancellation, timeouts, process exit, concurrency, limits, and clean shutdown. Real Hopper claims cannot be replaced by mocks — use `npm run verify:hopper` with two distinct binaries for end-to-end verification.
+Name tests `*.test.ts`. Use Vitest and production seams (`tests/fixtures/`) rather than module mocks. Domain tests assert pure behavior; adapter tests use the fake launcher/socket; MCP tests connect with the beta.3 client. Preserve the 33 direct, 10 enhanced, 5 native, 2 artifact, and 18 session tool inventory (68 total). Cover malformed input, cancellation, timeouts, process exit, concurrency, limits, and clean shutdown. Real Hopper claims cannot be replaced by mocks — use `npm run verify:hopper` with two distinct binaries for end-to-end verification.
 
 ## Commit & Pull Request Guidelines
 

docs/architecture.mermaid

@@ -1,6 +1,6 @@
 graph TD
     subgraph "Entry Points"
-        CLI["src/cli.ts<br/>One-shot CLI adapter<br/>setup, diagnostics, analysis, decompilation"]
+        CLI["src/cli.ts<br/>One-shot CLI adapter<br/>setup, diagnostics, analysis, inventory, extraction"]
         MAIN["src/main.ts<br/>MCP stdio server adapter<br/>config, session, process lifetime"]
         DISPATCH["scripts/rea.mjs<br/>Executable dispatcher<br/>routes mcp / one-shot"]
     end
@@ -18,12 +18,17 @@ graph TD
         HOPPER["src/hopper/<br/>Hopper launch & Unix-socket protocol<br/>BridgeLauncher, HopperClient, protocol"]
     end
 
+    subgraph "Provider Adapters"
+        ARTIFACTS["src/artifacts/<br/>Directory, ZIP/APK/IPA, ASAR, Mach-O slices<br/>safe transactional output"]
+        NATIVE["src/native/<br/>Bounded native macOS semantic inspection"]
+    end
+
     subgraph "Contracts Layer"
-        CONTRACTS["src/contracts/<br/>Caller-visible tool schemas<br/>31 direct, 8 enhanced, 3 session tools"]
+        CONTRACTS["src/contracts/<br/>Caller-visible tool schemas<br/>33 direct, 10 enhanced, 5 native, 2 artifact, 18 session"]
     end
 
     subgraph "Domain Layer"
-        DOMAIN["src/domain/<br/>Pure side-effect-free modules<br/>errors, Result, hopperValues, symbolAnalysis"]
+        DOMAIN["src/domain/<br/>Pure side-effect-free modules<br/>errors, Result, evidence, artifactGraph, residualUnknowns"]
     end
 
     subgraph "Configuration"
@@ -43,9 +48,14 @@ graph TD
     SERVER --> CONTRACTS
     SERVER --> APP
     APP --> HOPPER
+    APP --> ARTIFACTS
+    APP --> NATIVE
     HOPPER --> BRIDGE
     APP --> DOMAIN
     CONTRACTS --> DOMAIN
     HOPPER --> DOMAIN
+    ARTIFACTS --> DOMAIN
+    NATIVE --> DOMAIN
     TESTS -.-> MAIN
     TESTS -.-> HOPPER
+    TESTS -.-> ARTIFACTS