chore(aiwg): adopt shared BT6 maintainer workflow (#148)
* docs(policy): allow low-impact contributor courtesy cleanup * chore(aiwg): migrate to shared BT6 maintainer plugin * chore: reconcile delivery validation
This commit is contained in:
1 parent
8f658891f2
commit
afc9dad1b2
89 files changed
+4683
-1512
No files matched your search
@@ -1,13 +1,79 @@
|
||||
# UC-003 — Operate Through Supported Surfaces
|
||||
|
||||
**Primary actor:** Operator or integrating client
|
||||
**Goal:** Start and inspect capabilities through CLI, War Room/HTTP, library, or MCP.
|
||||
## Metadata
|
||||
|
||||
## Main Flow
|
||||
- **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
|
||||
|
||||
1. User selects an entry surface.
|
||||
2. Surface validates and translates input into shared domain operations.
|
||||
3. Shared mission, target, arsenal, and reporting services execute.
|
||||
4. Results return in surface-appropriate form.
|
||||
## Preconditions
|
||||
|
||||
**Implementation coverage:** `src/cli.ts`, `src/server.ts`, `src/index.ts`, `src/mcp-server.ts`, `src/ui/`.
|
||||
- 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.
|
||||
Reference in new issue
Block a user