Joseph Magly
afc9dad1b2
* docs(policy): allow low-impact contributor courtesy cleanup * chore(aiwg): migrate to shared BT6 maintainer plugin * chore: reconcile delivery validation
3.6 KiB
3.6 KiB
UC-003 — Operate Through Supported Surfaces
Metadata
- ID: UC-003
- Status: Baselined (brownfield)
- Level: User goal
- Scope: CLI, library, localhost HTTP/War Room, and MCP adapters
- Primary actor: Operator or integrating client
- Goal: Start and inspect supported capabilities through an appropriate surface while preserving shared domain behavior.
- Related stories: US-02, US-06
- Quality drivers: NFR-04, NFR-06, NFR-07, NFR-08
Preconditions
- The selected surface is installed and configured.
- The operation is supported by that surface; MCP is intentionally narrower than the full application.
- Any real target activity satisfies UC-001 preconditions.
Trigger
The actor invokes a CLI command, library export, localhost HTTP route, browser action, or MCP tool.
Main Success Scenario
- The selected adapter parses and validates surface-specific input.
- It translates the request into a shared domain operation.
- Shared mission, target, provider, arsenal, and reporting services execute the request.
- The adapter translates the result into the documented surface contract.
- The actor receives structured state, output, or an actionable error.
Alternate Flows
- CLI/library: Execute in the current Node.js process with terminal or typed return values.
- War Room/HTTP: Bind to loopback by default and serve browser/API responses after Host and origin validation.
- MCP: Expose only declared MCP tools over stdio and reuse common validation for supported reconnaissance.
Exception Flows
- Invalid schema or arguments: reject at the adapter boundary before domain execution.
- Invalid Host/origin: reject the HTTP request before a sensitive route is reached.
- Unsupported MCP capability: return a documented MCP error rather than silently invoking a broader internal API.
- Domain failure: preserve the underlying failure semantics and do not convert it to a surface-specific success.
Postconditions
- Equivalent supported operations preserve shared safety and domain invariants across surfaces.
- The result conforms to the chosen surface’s documented schema.
- Surface-specific exposure does not broaden privileges.
Acceptance Criteria
- CLI and library operations reach shared domain modules rather than duplicate mission logic.
- The HTTP server defaults to loopback and rejects invalid Host/origin combinations.
- MCP input is schema-validated and returns structured output for supported tools.
- Unsupported operations fail explicitly on the selected surface.
- Contract changes are typechecked, tested, documented, and visible during release review.
Design and Test Traceability
| Surface | Implementation | Verification |
|---|---|---|
| CLI | src/cli.ts |
Build, CLI smoke, and validation tests |
| Library | src/index.ts |
Export and index tests |
| HTTP / War Room | src/server.ts, src/ui/ |
Local API hardening and proxy tests |
| MCP | src/mcp-server.ts |
Schema/static validation and documentation review |
References
- @.aiwg/architecture/adr-001.md — Local-first modular-monolith decision.
- @.aiwg/architecture/software-architecture-doc.md — Delivery adapter and API surface design.
- @src/cli.ts — Command-line adapter.
- @src/index.ts — Library composition surface.
- @src/server.ts — Local HTTP and War Room adapter.
- @src/mcp-server.ts — MCP stdio adapter.
- @src/tests/local-api-hardening-static.test.ts — HTTP boundary evidence.
- @src/tests/validation.test.ts — Input-validation evidence.
- @docs/API_REFERENCE.md — Human-readable HTTP contract.
- @docs/MCP_GUIDE.md — Human-readable MCP contract.