docs(architecture): baseline current design (#109)

Capture the brownfield architecture and its relationship to the project vision.\n\n- add the current-state SAD and five retrospective ADRs\n- classify vision vectors against implementation evidence\n- record requirements, risks, gates, and construction handoff

.aiwg/requirements/UC-001.md

@@ -0,0 +1,21 @@
+# UC-001 — Conduct a Scoped Security Mission
+
+**Primary actor:** Authorized operator  
+**Goal:** Execute a recon-to-report mission against an explicitly authorized target.
+
+## Main Flow
+
+1. Operator defines target and rules of engagement.
+2. System validates target/scope inputs and creates mission context.
+3. Admiral plans tasks and assigns operator roles.
+4. Operators invoke approved arsenal capabilities within scope.
+5. Tool outputs become evidence and candidate findings.
+6. Findings are verified and a report is produced.
+
+## Invariants
+
+- Out-of-scope public network access is denied.
+- Dangerous operations follow approval policy.
+- A finding must retain evidence/provenance.
+
+**Implementation coverage:** `src/mission/`, `src/admiral/`, `src/operators/`, `src/orchestration/`, `src/target/`, `src/arsenal/`, `src/evidence/`, `src/analysis/`, and report/disclosure scripts.

.aiwg/requirements/UC-002.md

@@ -0,0 +1,13 @@
+# UC-002 — Connect a Model or Coding Agent
+
+**Primary actor:** Operator or integrator  
+**Goal:** Use a hosted provider, local OpenAI-compatible model, or connected coding-agent CLI as the reasoning backbone.
+
+## Main Flow
+
+1. User selects/configures a provider or local agent.
+2. System resolves provider/model capabilities and credentials.
+3. Requests are routed with timeout and fallback behavior.
+4. Tool-capable orchestration consumes responses and records outcomes.
+
+**Implementation coverage:** `src/llm/`, `src/config/`, `src/agent/`, provider-model registry, setup and fallback tests.

.aiwg/requirements/UC-003.md

@@ -0,0 +1,13 @@
+# 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.
+
+## Main Flow
+
+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.
+
+**Implementation coverage:** `src/cli.ts`, `src/server.ts`, `src/index.ts`, `src/mcp-server.ts`, `src/ui/`.

.aiwg/requirements/UC-004.md

@@ -0,0 +1,15 @@
+# UC-004 — Analyze a Source Code Repository
+
+**Primary actor:** Security researcher  
+**Goal:** Ingest supported source languages and identify evidence-backed vulnerability candidates.
+
+## Main Flow
+
+1. Researcher supplies an authorized repository.
+2. Ingest identifies language and extracts structural blocks.
+3. Decomposition and analysis produce candidate findings.
+4. Results are graded or verified against evidence.
+
+**Implementation coverage:** `src/recon/code-ingest.ts`, `src/recon/ts-parse.ts`, `src/recon/ts-grammars.ts`, `src/recon/whitebox.ts`, `src/analysis/`, decomposition scripts.
+
+**Maturity note:** Multi-language ingestion is experimental even where benchmark results are proven.

.aiwg/requirements/UC-005.md

@@ -0,0 +1,13 @@
+# UC-005 — Reproduce Claims and Benchmark Results
+
+**Primary actor:** Maintainer, contributor, or evaluator  
+**Goal:** Re-derive public capability claims from committed data and detect fitting or provenance regressions.
+
+## Main Flow
+
+1. Evaluator runs claim or benchmark verification.
+2. Harness reads committed corpus, receipts, and ground truth.
+3. Scores and verdicts are recomputed.
+4. CI fails if claims, provenance, or anti-fitting invariants do not hold.
+
+**Implementation coverage:** `bench/`, `scripts/verify-claims.mjs`, model/benchmark scripts, anti-fitting tests, `.github/workflows/ci.yml`.

.aiwg/requirements/nfr-register.md

@@ -0,0 +1,16 @@
+# Non-Functional Requirements Register
+
+| ID | Requirement | Verification |
+| --- | --- | --- |
+| NFR-01 Safety | Networked tools must deny off-scope public hosts by default. | Scope-containment tests and smoke/gate suites |
+| NFR-02 Authorization | Real operations require an explicit authorized target context. | API/mission validation tests and doctrine audit |
+| NFR-03 Provenance | Public claims and findings must trace to committed or retained evidence. | `verify-claims`, finding verifier, provenance gate |
+| NFR-04 Local security | HTTP server defaults to loopback and guards Host/origin. | Server tests and Docker configuration inspection |
+| NFR-05 Secret isolation | Target credentials are injected only for their configured exact origin. | Target-header tests |
+| NFR-06 Portability | Core build supports Node.js 18+ on common desktop/server environments. | CI plus documented install matrix |
+| NFR-07 Compatibility | CLI, HTTP, library, and MCP contracts change intentionally and visibly. | Typecheck, contract tests, release review |
+| NFR-08 Testability | Deterministic paths must run without live model/network dependencies in CI. | Main CI workflow |
+| NFR-09 Honesty | Experimental/research/roadmap work must not be described as stable. | Vision alignment and claim audit |
+| NFR-10 Recoverability | Updates preserve configured sensitive artifact paths. | Update self-tests |
+| NFR-11 Performance | Timeout controls bound local-agent, task, and planning calls. | Timeout/fallback tests; future percentile baseline |
+| NFR-12 Maintainability | Major trust-boundary and platform decisions require ADR updates. | Architecture review checklist |

.aiwg/requirements/user-stories.md

@@ -0,0 +1,14 @@
+# User Stories
+
+| ID | Story | Acceptance signal |
+| --- | --- | --- |
+| US-01 | As an operator, I can define an authorized target and scope before execution. | Scope receipt exists; invalid/off-scope target is refused. |
+| US-02 | As an operator, I can launch and monitor a mission from the CLI or War Room. | Shared mission state is visible through both surfaces. |
+| US-03 | As an operator, I can connect an already-authenticated local coding agent. | Mission planning works without a new cloud API key. |
+| US-04 | As an operator, I can approve or reject dangerous actions. | Approval decision is enforced before execution. |
+| US-05 | As a researcher, I can preserve evidence behind each finding. | Finding links to tool/model evidence and verification state. |
+| US-06 | As an integrator, I can access supported reconnaissance through MCP. | MCP schema validates and returns structured output. |
+| US-07 | As a researcher, I can ingest supported source languages. | Supported grammar extracts blocks; unsupported input fails safely. |
+| US-08 | As a maintainer, I can reproduce headline claims. | `npm run verify-claims` succeeds from committed artifacts. |
+| US-09 | As a contributor, I can see whether a feature is stable, experimental, research, or roadmap. | Maturity classification is explicit in docs/alignment matrix. |
+| US-10 | As a maintainer, I can detect prompt, provenance, and fitting regressions in CI. | Corresponding CI gates fail on seeded violations. |