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:
Joseph Magly authored and GitHub committed 2026-08-02 17:17:28 -04:00
1 parent 8f658891f2
commit afc9dad1b2
89 files changed
+4683 -1512

No files matched your search

+74 -8
View File
@@ -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.