Joseph Magly
afc9dad1b2
* docs(policy): allow low-impact contributor courtesy cleanup * chore(aiwg): migrate to shared BT6 maintainer plugin * chore: reconcile delivery validation
80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
# 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
|
||
|
||
1. The selected adapter parses and validates surface-specific input.
|
||
2. It translates the request into a shared domain operation.
|
||
3. Shared mission, target, provider, arsenal, and reporting services execute the request.
|
||
4. The adapter translates the result into the documented surface contract.
|
||
5. 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.
|