From f0f3c977d972283fbbf41504b938f7fd71d9a55c Mon Sep 17 00:00:00 2001 From: Joseph Magly <1159087+jmagly@users.noreply.github.com> Date: Mon, 20 Jul 2026 18:04:56 -0400 Subject: [PATCH] docs(architecture): baseline current design 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/architecture/adr-001.md | 16 ++ .aiwg/architecture/adr-002.md | 16 ++ .aiwg/architecture/adr-003.md | 16 ++ .aiwg/architecture/adr-004.md | 16 ++ .aiwg/architecture/adr-005.md | 16 ++ .../architecture/software-architecture-doc.md | 116 ++++++++++++ .aiwg/architecture/vision-alignment.md | 22 +++ .aiwg/deployment/ci-cd-scaffold.md | 15 ++ .aiwg/intake/codebase-analysis-report.md | 80 +++++++++ .aiwg/intake/intake-form.md | 44 +++++ .aiwg/intake/option-matrix.md | 134 ++++++++++++++ .aiwg/intake/project-intake.md | 170 ++++++++++++++++++ .aiwg/intake/risk-screening.md | 13 ++ .aiwg/intake/solution-profile.md | 109 +++++++++++ .aiwg/planning/iteration-001-plan.md | 24 +++ .aiwg/reports/abm-gate-report.md | 15 ++ .aiwg/reports/construction-ready-brief.md | 44 +++++ .aiwg/reports/lom-gate-report.md | 14 ++ .aiwg/requirements/UC-001.md | 21 +++ .aiwg/requirements/UC-002.md | 13 ++ .aiwg/requirements/UC-003.md | 13 ++ .aiwg/requirements/UC-004.md | 15 ++ .aiwg/requirements/UC-005.md | 13 ++ .aiwg/requirements/nfr-register.md | 16 ++ .aiwg/requirements/user-stories.md | 14 ++ .aiwg/team/team-profile.md | 15 ++ .aiwg/testing/test-strategy.md | 34 ++++ .aiwg/working/sdlc-accelerate/state.json | 42 +++++ 28 files changed, 1076 insertions(+) create mode 100644 .aiwg/architecture/adr-001.md create mode 100644 .aiwg/architecture/adr-002.md create mode 100644 .aiwg/architecture/adr-003.md create mode 100644 .aiwg/architecture/adr-004.md create mode 100644 .aiwg/architecture/adr-005.md create mode 100644 .aiwg/architecture/software-architecture-doc.md create mode 100644 .aiwg/architecture/vision-alignment.md create mode 100644 .aiwg/deployment/ci-cd-scaffold.md create mode 100644 .aiwg/intake/codebase-analysis-report.md create mode 100644 .aiwg/intake/intake-form.md create mode 100644 .aiwg/intake/option-matrix.md create mode 100644 .aiwg/intake/project-intake.md create mode 100644 .aiwg/intake/risk-screening.md create mode 100644 .aiwg/intake/solution-profile.md create mode 100644 .aiwg/planning/iteration-001-plan.md create mode 100644 .aiwg/reports/abm-gate-report.md create mode 100644 .aiwg/reports/construction-ready-brief.md create mode 100644 .aiwg/reports/lom-gate-report.md create mode 100644 .aiwg/requirements/UC-001.md create mode 100644 .aiwg/requirements/UC-002.md create mode 100644 .aiwg/requirements/UC-003.md create mode 100644 .aiwg/requirements/UC-004.md create mode 100644 .aiwg/requirements/UC-005.md create mode 100644 .aiwg/requirements/nfr-register.md create mode 100644 .aiwg/requirements/user-stories.md create mode 100644 .aiwg/team/team-profile.md create mode 100644 .aiwg/testing/test-strategy.md create mode 100644 .aiwg/working/sdlc-accelerate/state.json diff --git a/.aiwg/architecture/adr-001.md b/.aiwg/architecture/adr-001.md new file mode 100644 index 00000000..0058ca7f --- /dev/null +++ b/.aiwg/architecture/adr-001.md @@ -0,0 +1,16 @@ +# ADR-001 — Retain a Local-First Modular Monolith + +**Status:** Accepted (retrospective) +**Date:** 2026-07-20 + +## Context + +T3MP3ST ships CLI, library, localhost HTTP/War Room, MCP, orchestration, tools, evidence, and benchmarks in one Node/TypeScript package. Operators value low-friction self-hosting and local control. + +## Decision + +Treat the current architecture as a modular monolith with adapter boundaries. Do not describe it as microservices. Keep the default HTTP surface loopback-only and local artifacts operator-controlled. + +## Consequences + +Installation and typed reuse remain simple. Module boundaries require review/tests rather than process isolation. Hosted multi-tenancy or distributed workers require a new decision and architecture baseline. diff --git a/.aiwg/architecture/adr-002.md b/.aiwg/architecture/adr-002.md new file mode 100644 index 00000000..2051d27e --- /dev/null +++ b/.aiwg/architecture/adr-002.md @@ -0,0 +1,16 @@ +# ADR-002 — Keep the Reasoning Backbone Provider-Neutral + +**Status:** Accepted (retrospective) +**Date:** 2026-07-20 + +## Context + +Users may use hosted APIs, local OpenAI-compatible servers, or already-authenticated coding-agent CLIs. No single provider supplies a stable universal capability contract. + +## Decision + +Resolve provider/model differences behind shared configuration and LLM/agent adapters. Treat provider responses as untrusted proposals; safety and tool contracts remain in T3MP3ST. + +## Consequences + +Users retain keyless/local options and provider choice. Compatibility and fallback testing expand, and lowest-common-denominator assumptions must not erase provider-specific behavior. diff --git a/.aiwg/architecture/adr-003.md b/.aiwg/architecture/adr-003.md new file mode 100644 index 00000000..b360a1f1 --- /dev/null +++ b/.aiwg/architecture/adr-003.md @@ -0,0 +1,16 @@ +# ADR-003 — Enforce Scope and Approval Below Model Reasoning + +**Status:** Accepted (retrospective) +**Date:** 2026-07-20 + +## Context + +Models and target content are nondeterministic and may suggest unsafe or off-scope actions. The arsenal performs real operations. + +## Decision + +Target scope, egress containment, exact-origin credentials, and dangerous-tool approvals are enforced in deterministic target/arsenal/runtime paths, not solely in prompts. + +## Consequences + +Prompt compromise does not automatically authorize execution. Every new network/tool adapter must carry and test these controls; bypasses are release-blocking defects. diff --git a/.aiwg/architecture/adr-004.md b/.aiwg/architecture/adr-004.md new file mode 100644 index 00000000..5980c801 --- /dev/null +++ b/.aiwg/architecture/adr-004.md @@ -0,0 +1,16 @@ +# ADR-004 — Derive Public Claims from Versioned Evidence + +**Status:** Accepted (retrospective) +**Date:** 2026-07-20 + +## Context + +Offensive-AI performance claims are easy to overfit or report without reproducible evidence. + +## Decision + +Headline claims must be recomputed from committed corpus, ground truth, and receipts. Anti-fitting, provenance, and claim-verification gates are architectural product controls. + +## Consequences + +Repository size and CI cost increase, but claims are auditable. Raw sensitive transcripts may be withheld, so documentation must distinguish re-derivable graded verdicts from full raw reproduction. diff --git a/.aiwg/architecture/adr-005.md b/.aiwg/architecture/adr-005.md new file mode 100644 index 00000000..2b90e7df --- /dev/null +++ b/.aiwg/architecture/adr-005.md @@ -0,0 +1,16 @@ +# ADR-005 — Separate Current State from Research Vision + +**Status:** Accepted +**Date:** 2026-07-20 + +## Context + +`VISION.md` deliberately explores autonomous, distributed, cognitive, and evolutionary directions beyond the stable product. Treating it as current architecture would misrepresent capability and risk. + +## Decision + +Maintain a current-state SAD backed by code paths and a separate vision-alignment matrix. Classify each direction as implemented, partial/experimental, research, or future. Promotion requires evidence and documentation updates. + +## Consequences + +Architecture remains honest and reviewable. Maintainers must update two views when capabilities evolve, and vision alignment alone cannot justify a stable label. diff --git a/.aiwg/architecture/software-architecture-doc.md b/.aiwg/architecture/software-architecture-doc.md new file mode 100644 index 00000000..1db49374 --- /dev/null +++ b/.aiwg/architecture/software-architecture-doc.md @@ -0,0 +1,116 @@ +# Software Architecture Document — Current-State Baseline + +**System:** T3MP3ST +**Baseline:** revision `186afe6` on 2026-07-20 +**Status:** BASELINED (brownfield description) +**Scope:** Implemented repository state; `VISION.md` is a directional source, not proof of implementation. + +## 1. Purpose and Architectural Drivers + +T3MP3ST turns a model or coding agent into the reasoning layer of a local offensive-security platform. The architecture must coordinate long-running, tool-backed security work while preserving target authorization, evidence, and honest claims. The strongest drivers are therefore not raw throughput. They are safe execution, local control, portability across reasoning providers, reproducibility, and the ability to evolve specialized security domains without copying the whole platform. + +The system supports UC-001 through UC-005. UC-001 drives mission and safety boundaries; UC-002 drives provider abstraction; UC-003 drives multiple delivery adapters; UC-004 drives source-ingest extensibility; UC-005 drives the committed benchmark/provenance subsystem. NFR-01 through NFR-12 constrain all changes, particularly scope, authorization, provenance, secret isolation, and maturity labeling. + +## 2. System Context + +The principal human is an authorized operator. The operator uses a terminal, the browser War Room, or an integrating client. T3MP3ST communicates with one or more hosted model APIs, local inference servers, or authenticated local coding-agent processes. It invokes internal Node implementations and approved external security tools against targets named in rules of engagement. It writes local reports, evidence, configuration, and benchmark results. MCP clients can request the narrower MCP-exposed capability. GitHub hosts source collaboration and CI, while isolated Docker environments support application and challenge execution. + +Trust boundaries exist between: browser and localhost server; client and HTTP/MCP adapters; T3MP3ST and each model provider; the orchestration core and tool processes; tools and target networks; runtime and local artifact storage; repository source and third-party benchmark/tool corpora. No diagram or prose may collapse these into a single trusted process merely because deployment is local. + +## 3. Architectural Style + +The implementation is a modular TypeScript monolith with ports/adapters characteristics. Domain modules share one Node.js runtime and package but expose cohesive responsibilities. Delivery adapters translate CLI, HTTP, library, and MCP calls into common modules. Provider adapters translate common model requests to hosted APIs, local OpenAI-compatible endpoints, or connected coding agents. Arsenal adapters translate approved tool intents to internal functions or external processes. Filesystem artifacts form the principal persistence mechanism; there is no application database in the current baseline. + +This style is intentional for a self-hosted tool: installation remains straightforward, domain operations can share typed contracts, and local artifacts remain visible to operators. The cost is that dependency discipline must be maintained in code review because process boundaries do not enforce module boundaries. + +## 4. Runtime and Deployment Views + +### 4.1 CLI and Library + +`src/cli.ts` provides the operator command surface, while `src/index.ts` exports the library-facing composition surface. Commands construct configuration, targets, missions, operators, and tools in-process. This is the lowest-overhead path and the natural entry for scripts and terminal operators. + +### 4.2 War Room and HTTP API + +`src/server.ts` hosts the browser War Room assets and JSON endpoints. It binds to `127.0.0.1:3333` by default. Localhost CORS/origin and Host-header defenses matter because HTTP endpoints can initiate local tool or model activity. Docker Compose preserves this boundary by publishing `127.0.0.1:3333:3333`, mounts `reports/` and `evidence/`, and checks `/api/health`. + +### 4.3 MCP + +`src/mcp-server.ts` exposes a stdio MCP server with a deliberately narrower supported surface than the entire HTTP/CLI application. MCP is an adapter, not a second mission engine; it must reuse shared validation and tool behavior and avoid silently broadening privileges. + +### 4.4 Model and Agent Providers + +`src/llm/`, `src/config/`, and agent/provider code resolve credentials, model identifiers, capabilities, timeouts, and fallback. Cloud-provider keys are optional when a connected local agent or local OpenAI-compatible server is used. Provider output is untrusted input to orchestration: it may suggest operations, but target, approval, evidence, and tool contracts remain authoritative. + +## 5. Core Logical Components + +### 5.1 Mission and Orchestration + +`src/mission/` owns mission state and lifecycle. `src/admiral/` and `src/orchestration/` plan and coordinate tasks, context packs, prompts, and adjudication. `src/operators/` supplies role-specific behavior. The current system implements a coordinated operator model, but public evidence is stronger for benchmarked single-agent paths than for reliable end-to-end swarm exploitation. The architecture baseline therefore classifies swarm superiority as unproven rather than an invariant. + +### 5.2 Target, Scope, and OPSEC + +`src/target/` represents the authorized target context. `src/opsec/` and arsenal approval logic apply operational constraints. Once a mission target is set, built-in networked tools reject unrelated public hosts while allowing target/subdomain and loopback/private contexts under documented rules. Exact-origin target headers prevent credential forwarding to a different origin. These controls implement NFR-01, NFR-02, and NFR-05 and are the primary safety boundary. + +### 5.3 Arsenal + +`src/arsenal/` provides catalog, parser, adapter, post-exploitation, and approval modules. Some tools are internal Node implementations; others adapt external binaries. Dangerous or catalog-only drivers have narrow approved paths instead of generic arbitrary execution. Tool output is evidence, not automatically a validated finding. Changes here require adversarial tests for argument construction, scope propagation, timeout/exit behavior, and output parsing. + +### 5.4 Evidence, Findings, and Reporting + +`src/evidence/`, `src/analysis/`, and report/disclosure scripts transform raw observations into retained artifacts and deliverables. Verification scripts and disclosure generation support the transition from candidate to substantiated finding. Reports and evidence are mounted/preserved local paths and may contain credentials or pre-disclosure vulnerabilities; filesystem ownership does not remove the need for retention and access procedures. + +### 5.5 Reconnaissance and Source Ingest + +Black-box reconnaissance uses real DNS, network, TLS, and HTTP operations. White-box ingestion in `src/recon/code-ingest.ts`, `ts-parse.ts`, `ts-grammars.ts`, and `whitebox.ts` extracts structural units across supported languages using web-tree-sitter, with Python retaining a specialized parser. The current documentation identifies multi-language ingest as experimental. Benchmark results can prove performance on a corpus without promoting the general engine to stable. + +### 5.6 Benchmarks and Provenance + +`bench/` stores corpora, manifests, ledgers, ground truth, and receipts. Scripts recompute claims, grade flags/findings, test model matrices, and reject fitting. `.github/workflows/ci.yml` runs lint, typecheck, tests, coverage, doctor, claim verification, anti-fitting checks, provenance gate, prompt audit, and smoke tests. This subsystem is part of product architecture because reproducibility is a product promise, not auxiliary documentation. + +## 6. Data and State + +Configuration comes from environment variables, a local configuration store, and browser localStorage. Target header configuration is origin-bound. Mission state lives in memory and local artifacts according to the execution path. Reports and evidence are persisted in repository-local mounted directories by the Docker setup. Benchmark inputs and derived receipts are committed selectively. Update tooling preserves declared sensitive or expensive local paths. + +There is no current transactional application database, distributed queue, centralized cache, or multi-tenant identity store. Any future hosted architecture would introduce fundamentally new trust, tenancy, retention, backup, migration, and compliance requirements and must not be treated as a small deployment variation. + +## 7. Security Architecture + +The security model assumes the operator host, model output, external tools, target responses, browser requests, and imported repositories may all introduce risk. Default loopback exposure reduces remote attack surface but does not protect against malicious local content or DNS rebinding without Host/origin validation. Scope containment reduces accidental or model-driven egress but must be propagated through every network-capable adapter. Approval gates reduce the chance of executing high-impact actions without human intent. Evidence/provenance controls reduce false reporting but do not make model output trustworthy. + +Key failure modes are scope bypass, credential misrouting, shell/argument injection, unsafe parsing, evidence confusion, prompt injection from target/code content, and false maturity claims. CI and smoke tests cover important deterministic contracts; manual/release review remains necessary for new tools and trust-boundary changes. + +## 8. Quality and Operations + +The project favors deterministic CI that does not require live targets or paid models. Live tests and benchmarks are separated or opt-in. Timeouts bound slow local agents and task/planning calls. Doctor, preflight, smoke, capability, and gauntlet scripts provide layered diagnostics. The current codebase does not establish fleet-level SLOs, centralized observability, on-call, or disaster-recovery objectives, so those are unknown rather than missing implementation promises. + +## 9. Vision Relationship + +`VISION.md` describes seven research directions: cognitive architecture, swarm dynamics, adversarial machine learning, continuous autonomous operations, knowledge architecture, distributed/edge execution, and evaluation science. The current system strongly realizes evaluation science, partially realizes cognitive/swarm/knowledge ideas, contains research experiments for self-improvement, and leaves persistent autonomy and distributed execution largely future-facing. The authoritative classification and evidence are in `vision-alignment.md`. + +Architectural evolution must preserve a two-axis view: maturity of implementation and alignment with direction. A feature can align with the vision while remaining experimental; conversely, a stable implementation need not imply completion of the broader vision vector. + +## 10. Architectural Risks and Evolution Rules + +The main structural risk is unsafe coupling across delivery, orchestration, provider, and tool layers in a single process. The mitigation is typed shared contracts, narrow adapters, trust-boundary tests, and ADR review. The main product risk is confusing benchmark success with general system maturity. The mitigation is corpus-scoped claims, re-derivation, maturity labels, and the alignment matrix. + +Future changes require an ADR when they add a delivery surface, persistence system, privilege boundary, generic execution mechanism, network egress class, provider contract, or maturity promotion. A hosted/multi-tenant mode, distributed worker architecture, or autonomous persistent operation requires a new SAD baseline rather than an amendment that assumes current trust boundaries still apply. + +## 11. Traceability + +| Use case | Architectural coverage | +| --- | --- | +| UC-001 | Mission/orchestration, target/OPSEC, arsenal, evidence/reporting | +| UC-002 | Model and agent provider adapters | +| UC-003 | CLI/library, War Room/HTTP, MCP runtime views | +| UC-004 | Reconnaissance and source-ingest components | +| UC-005 | Benchmark/provenance subsystem and CI | + +## 12. Accepted Decisions + +This baseline is governed by: + +- ADR-001 — modular monolith and local-first deployment +- ADR-002 — provider-neutral reasoning backbone +- ADR-003 — scope and approval enforcement below model output +- ADR-004 — evidence-derived public claims +- ADR-005 — explicit separation of current state from research vision diff --git a/.aiwg/architecture/vision-alignment.md b/.aiwg/architecture/vision-alignment.md new file mode 100644 index 00000000..06567de6 --- /dev/null +++ b/.aiwg/architecture/vision-alignment.md @@ -0,0 +1,22 @@ +# Vision-to-Code Alignment Matrix + +**Reference:** `VISION.md` +**Rule:** Alignment is directional; only code/tests/receipts establish implementation maturity. + +| Vision vector | Current maturity | Current evidence | Gap / next architectural proof | +| --- | --- | --- | --- | +| Cognitive architecture | Partial / experimental | Admiral planning, context packs, prompts, operator roles, adjudication | Demonstrate durable reasoning-state architecture and comparative outcomes beyond prompt composition | +| Swarm dynamics | Partial / experimental | Eight operator archetypes, orchestration, task assignment, shared mission context | Reproducible end-to-end swarm benchmark showing coordination reliability and value over solo baselines | +| Adversarial machine learning | Research / partial | Refusal-frontier probes, model matrices, adversarial benchmarks, anti-fitting | Formal threat model and stable adaptive defenses against prompt/model manipulation | +| Continuous autonomous operations | Future with small foundations | Mission lifecycle, lessons, update/preflight tooling | Persistent scheduler, safe pause/resume, operator governance, resource budgets, and incident controls | +| Knowledge architecture | Partial / research | Evidence, reports, lessons, benchmark corpora, context packs | Unified provenance-aware knowledge model with retention, conflict, and poisoning controls | +| Distributed and edge execution | Future | Local agents, local model servers, Docker, multiple surfaces | Authenticated worker protocol, tenancy, distributed state, failure recovery, and zero-trust execution design | +| Evaluation science | Strongly implemented | `bench/`, `verify-claims`, ground truth, model matrix, anti-fitting/provenance CI | Broaden external replication, workload/cost measures, and statistically powered comparisons | + +## Alignment Rules + +1. `README.md` and `FEATURES.md` maturity labels are product claims and must remain consistent with this matrix. +2. A benchmark validates only its defined corpus, model, harness, and metric. +3. Promotion to stable requires deterministic safety tests, an operational path, documentation, and a reproducible receipt. +4. Persistent autonomy, distributed execution, or shared knowledge services trigger new threat models and ADRs. +5. The SAD is updated from implementation evidence; the vision is not reverse-engineered into fictitious components. diff --git a/.aiwg/deployment/ci-cd-scaffold.md b/.aiwg/deployment/ci-cd-scaffold.md new file mode 100644 index 00000000..cc172bc6 --- /dev/null +++ b/.aiwg/deployment/ci-cd-scaffold.md @@ -0,0 +1,15 @@ +# CI/CD Baseline and Architecture Additions + +## Current Pipeline + +The repository already has a substantial GitHub Actions pipeline: `npm ci`, lint, typecheck, tests, coverage, doctor, claim verification, anti-fitting, provenance gate, prompt audit, and smoke. + +## Recommended Additions + +1. **Architecture document check:** required SAD, ADR, alignment, NFR, and gate files exist and contain accepted identifiers. +2. **Traceability check:** SAD references UC-001 through UC-005 and ADR-001 through ADR-005. +3. **Maturity consistency check:** stable/experimental/research/roadmap labels do not conflict across product docs. +4. **Adapter safety inventory:** every registered network-capable adapter maps to a scope test and approval classification. +5. **Release provenance:** consider signed tags/artifacts and SBOM generation according to the project threat model. + +These are proposed pipeline stages, not claims that they already run. Existing CI remains authoritative until changes are implemented and reviewed. diff --git a/.aiwg/intake/codebase-analysis-report.md b/.aiwg/intake/codebase-analysis-report.md new file mode 100644 index 00000000..8a7d33e1 --- /dev/null +++ b/.aiwg/intake/codebase-analysis-report.md @@ -0,0 +1,80 @@ +# Codebase Analysis Report + +**Project:** T3MP3ST +**Directory:** `/home/roctinam/dev/bt6/T3MP3ST` +**Generated:** 2026-07-20 +**Revision:** `186afe6b50e365371774aa2ed7986d73eb0656db` + +## Summary + +- **Tracked files:** 1,665 +- **Primary implementation:** TypeScript/Node.js ESM +- **Source size:** 111 TypeScript files and approximately 46,129 lines under `src/` +- **Test indicators:** 75 test/spec-named files in `src/` and `scripts/` +- **Documentation:** 52 Markdown files in `docs/` and `docsite/` +- **Architecture:** Modular monolith with CLI, localhost web/API, MCP, model/provider, agent orchestration, tool adapters, evidence/reporting, and benchmark subsystems +- **Profile:** Established open-source security product with stable core and explicitly experimental/research modules +- **Team signal:** More than ten author identities and 151 commits in the last year; exact active human team size is unknown + +## Evidence-Based Inferences + +### High Confidence + +- T3MP3ST is an authorized-use offensive-security platform (`README.md`, `SECURITY.md`). +- The runtime is Node.js/TypeScript and package version is 1.0.0 (`package.json`). +- Users can operate through CLI, browser War Room/API, and MCP (`package.json`, `src/`, developer docs). +- The server and Docker deployment bind to loopback by default (`docs/DEVELOPER_GUIDE.md`, `docker-compose.yml`). +- The architecture is a modular monolith rather than microservices (`src/` layout, one application image/service). +- CI has extensive quality, provenance, claim, safety, and smoke gates (`.github/workflows/ci.yml`). +- The repository uses committed benchmark corpora and deterministic claim verification (`bench/`, README, scripts). +- Real offensive tools and sensitive artifacts make scope, approval, credentials, and evidence primary risk domains (`SECURITY.md`, `src/arsenal/`, Docker mounts). + +### Medium Confidence + +- The contributor community is medium-to-large for an open-source project, but aliases and automated-agent identities prevent an exact human team count. +- The system is production-grade as a distributed open-source tool, while not necessarily operated as a production hosted service. +- Reliability maturity is moderate: strong pre-release verification exists, but no hosted-service SLO/telemetry model is evident. +- Security maturity is strong for the product category, but certification and organization-level controls cannot be inferred. + +### Unknown + +- Active users, installations, and workload volume +- Maintainer staffing, funding, and availability +- General support/on-call model +- Formal contractual or regulatory obligations +- Production incident rate and recovery objectives +- Near-term product priority and deadline +- Whether package repository metadata intentionally remains pointed at the upstream owner + +## Quality Assessment + +### Strengths + +- Clear stable/experimental/roadmap labeling +- Strong verification culture and reproducible public claims +- Extensive automated CI gates +- Broad documentation for operators, developers, security, benchmarks, releases, and integrations +- Localhost-first deployment and explicit authorization doctrine +- Modular source organization and multiple integration surfaces +- Private vulnerability-reporting process and response target + +### Risks and Weaknesses + +- Large capability surface and external-tool ecosystem amplify regression and supply-chain risk. +- Stable and experimental code share core execution and brand surfaces. +- Multi-agent/swarm reliability is less demonstrated than single-agent benchmark performance. +- No formal workload/capacity baseline was found. +- Sensitive artifacts rely heavily on operator-controlled local storage. +- Repository ownership references differ between current tracker configuration and `package.json`. +- Eighteen debt markers in implementation/script paths need owner triage. + +## Generated Files + +- `.aiwg/intake/project-intake.md` +- `.aiwg/intake/solution-profile.md` +- `.aiwg/intake/option-matrix.md` +- `.aiwg/intake/codebase-analysis-report.md` + +## Recommended Next Action + +Have maintainers validate the five owner questions in `option-matrix.md`, then select incremental expansion, stabilization, research, or hosted evolution as the governing near-term path. The code evidence favors incremental expansion with explicit safety and benchmark promotion gates. diff --git a/.aiwg/intake/intake-form.md b/.aiwg/intake/intake-form.md new file mode 100644 index 00000000..3f358823 --- /dev/null +++ b/.aiwg/intake/intake-form.md @@ -0,0 +1,44 @@ +# SDLC Accelerate Intake — T3MP3ST + +**Entry mode:** Existing codebase +**Baseline revision:** `186afe6b50e365371774aa2ed7986d73eb0656db` +**Guidance:** Capture architecture and design as current state, emphasize SAD/ADRs, and test alignment between `VISION.md` and implemented code. + +## Problem Statement + +Offensive-security capability is costly to assemble, difficult to coordinate, and easy to overstate. T3MP3ST provides a local-first orchestration platform that connects an operator's existing coding agent or model provider to scoped reconnaissance, exploitation, evidence, verification, and reporting workflows while retaining authorization and provenance controls. + +## Stakeholders + +- Authorized security operators and researchers +- Project maintainers and contributors +- Developers integrating through CLI, HTTP, library, or MCP surfaces +- Target/system owners who authorize engagements +- Recipients of verified findings and coordinated disclosures + +## Current-State Scope + +The implemented system is a TypeScript modular monolith with CLI, localhost War Room/API, MCP server, mission/admiral/operator orchestration, target and OPSEC controls, arsenal adapters, evidence/reporting, provider abstraction, source ingestion, and reproducible benchmarks. Stable, experimental, research, and planned capabilities remain explicitly distinct. + +## Success Criteria + +1. Every stable public capability claim remains re-derivable through `npm run verify-claims` and CI. +2. Networked operations reject out-of-scope public targets by default and require explicit authorization context. +3. The current-state SAD traces every core use case and names concrete implementation modules. +4. Major implemented design choices have accepted retrospective ADRs with evidence and consequences. +5. Every vision vector is classified as implemented, partial/experimental, research, or future without presenting aspiration as current state. + +## Constraints + +- Node.js 18+ and TypeScript/ESM +- Local-first and self-hosted operation, including connected local agents +- Real offensive tooling only for authorized targets +- Sensitive credentials/evidence remain operator-controlled +- AGPL-3.0-or-later licensing +- Existing CLI, HTTP, MCP, and benchmark interfaces require compatibility discipline + +## Out of Scope for This Baseline + +- Redesigning or implementing roadmap features +- Claiming hosted-service scale, enterprise certification, or production SLOs without evidence +- Treating `VISION.md` as an implemented specification diff --git a/.aiwg/intake/option-matrix.md b/.aiwg/intake/option-matrix.md new file mode 100644 index 00000000..e3eb852b --- /dev/null +++ b/.aiwg/intake/option-matrix.md @@ -0,0 +1,134 @@ +# Option Matrix (Project Context and Intent) + +**Purpose:** Capture what the project is and expose the decisions that owner input must complete. +**Generated:** 2026-07-20 + +## Project Reality + +T3MP3ST is a mature, self-hosted TypeScript offensive-security platform with a local browser UI, CLI, HTTP API, MCP integration, external security-tool adapters, reproducible benchmarks, and extensive documentation. Its stable core operates real tools against authorized targets, while selected multi-agent, domain-specific, and evolutionary capabilities remain experimental or planned. + +### Audience and Scale + +| Attribute | Current evidence | Confidence | +| --- | --- | --- | +| Audience | Authorized operators, researchers, CTF users, developers, contributors | High | +| Distribution | Open-source package/repository, self-hosted execution | High | +| Active users/installations | Not measurable from the codebase | Unknown | +| Support expectations | Documentation and security-response target exist; no general SLA found | Medium | +| Geographic reach | Public open-source distribution implies global reach | Medium | +| Runtime concurrency | Local missions and agent/tool tasks; fleet scale unknown | Medium | + +### Deployment and Infrastructure + +| Attribute | Current state | +| --- | --- | +| Deployment model | Hybrid local application: CLI + browser UI/API + MCP + external tools | +| Hosting | Developer/operator workstation or Docker host; HTTP binds to loopback by default | +| Persistence | Local config, browser localStorage, reports, evidence, benchmark artifacts | +| Application database | None detected | +| CI/CD | GitHub Actions quality pipeline; no hosted-production deployment pipeline detected | +| Complexity | Modular monolith with many external integrations and high-risk execution boundaries | + +### Technical Complexity + +- Approximately 46,129 lines across 111 TypeScript files under `src/` +- 1,665 tracked files, dominated by committed JSON benchmark artifacts +- TypeScript primary; supporting JavaScript/MJS, shell, YAML, Python, C, Java, Go, Rust, Perl, HTML, and container definitions +- 75 test/spec-named files in `src/` and `scripts/` +- 52 Markdown documentation files across `docs/` and `docsite/` +- High-risk factors: real offensive operations, credentials, external tools, network access, sensitive evidence, model nondeterminism, multi-provider compatibility, and public benchmark claims + +## Constraints and Context + +### Known + +- AGPL-3.0-or-later open-source licensing +- Node.js 18+ runtime and Node.js 22 CI +- Local-first/keyless operation is a core product promise +- Authorized use and target scope are non-negotiable safety constraints +- Claims are expected to be reproducible from committed evidence +- Stable versus experimental status must remain explicit +- The project supports a heterogeneous contributor base and multiple provider/runtime environments + +### Unknown + +- Maintainer availability and budget +- User/install base and growth targets +- Revenue or funding model +- Contractual obligations and general support SLA +- Formal compliance or certification objectives +- Release cadence and next milestone +- Current highest-priority pain point + +## Priorities and Trade-offs + +The codebase supports this provisional weighting, which must be validated by owners: + +| Criterion | Provisional weight | Evidence-based rationale | +| --- | ---: | --- | +| Quality and security | 0.35 | Real offensive actions, secrets, evidence, authorization, and reputation risk | +| Reliability and scale | 0.25 | Mission orchestration and tool/model execution must fail safely; actual fleet scale is unknown | +| Delivery speed | 0.25 | Active roadmap and competitive research space favor iteration | +| Cost efficiency | 0.15 | Local/keyless operation is a product value, but maintainer budget is unknown | +| **Total** | **1.00** | Provisional only | + +**Optimizing for:** Credible, reproducible offensive-security capability that remains safe-by-default and accessible through infrastructure users already possess. + +**Likely acceptable trade-off:** Experimental capabilities may iterate before they are fully reliable if maturity is conspicuous and shared safety boundaries remain enforced. + +**Non-negotiable:** Authorization, target containment, secret protection, evidence integrity, honest capability claims, and human control over disclosure or materially dangerous actions. + +## Decision Options + +| Option | Description | Benefits | Risks | Best fit | +| --- | --- | --- | --- | --- | +| A. Stabilize the core | Concentrate on existing stable paths, safety boundaries, docs, and release quality | Highest trust and lower regression surface | Slower domain expansion | Reliability or adoption is the immediate goal | +| B. Incremental expansion | Promote one experimental domain at a time using explicit benchmark and safety gates | Balanced learning and credibility | Requires disciplined promotion criteria | Default recommendation from code evidence | +| C. Swarm-first research | Prioritize multi-agent coordination and evolutionary capability | Differentiated research upside | Cost, nondeterminism, and safety complexity | Research funding and tolerance are explicit | +| D. Hosted/enterprise evolution | Add centralized service operations, tenancy, governance, and compliance | Broader organizational adoption | Major architecture and operating-model change | Real customer demand and resources exist | + +## Framework Application + +**Recommended now:** + +- Full rigor for core safety, release, provenance, and claim-bearing paths +- Moderate rigor for experimental modules +- Architecture decisions for trust boundaries and maturity promotion +- Continuous security, architecture, risk, and test-strategy cycles +- Operational runbooks for local server, agent/provider failures, external tools, and sensitive artifacts + +**Defer unless triggered:** + +- Enterprise governance and formal change boards +- Hosted multi-tenant architecture +- Multi-region infrastructure and centralized observability +- Formal compliance certification work + +**Adaptation triggers:** + +- Hosted service or centrally retained user/target data +- Contractual SLA or regulated customer requirement +- Material growth in maintainers or release frequency +- Dangerous-tool surface expansion +- Experimental capability promoted to stable +- Public claims not fully covered by deterministic verification +- Significant user/install growth or recurring production incidents + +## Owner Validation Needed + +To finalize intent rather than infer it from code, owners should answer: + +1. What decision or milestone triggered this intake? +Transition to AIWG memory system + +2. Which matters most for the next release: stability, domain expansion, swarm research, or adoption? +all of the above + +3. What is the current user/install scale and expected 12-month change? +thousands to tens of thousands + +4. What failures would be unacceptable beyond the documented authorization constraints? +none, failsafe patterns always + +5. Are there contractual, funding, compliance, or support commitments not represented in the repository? +no diff --git a/.aiwg/intake/project-intake.md b/.aiwg/intake/project-intake.md new file mode 100644 index 00000000..9ba35b9c --- /dev/null +++ b/.aiwg/intake/project-intake.md @@ -0,0 +1,170 @@ +# Project Intake Form (Existing System) + +**Document type:** Brownfield system documentation +**Generated:** 2026-07-20 +**Source:** Codebase analysis of `/home/roctinam/dev/bt6/T3MP3ST` + +## Metadata + +- **Project:** T3MP3ST — Tactical Execution Multi-agent Platform for Elite Security Testing +- **Repository:** `https://github.com/jmagly/T3MP3ST.git` (`origin`); package metadata references `elder-plinius/T3MP3ST` +- **Version:** 1.0.0 in `package.json`; analyzed revision `186afe6` +- **License:** AGPL-3.0-or-later +- **Runtime:** Node.js 18+; CI uses Node.js 22 +- **Last analyzed commit:** 2026-07-20, “add reproducible cross-model benchmark matrix” +- **Stakeholders:** Maintainers, contributors, authorized security operators, security researchers, and users of supported coding agents + +## System Overview + +T3MP3ST is a self-hosted, multi-agent offensive-security framework for authorized testing, research, and education. It coordinates reconnaissance, exploitation, evidence, and reporting through a CLI, a browser War Room, an HTTP API, and an MCP server. It supports hosted LLM providers, connected local coding-agent CLIs, and local OpenAI-compatible inference servers. + +**Current status:** Established open-source product with stable core paths, experimental subsystems, and research/roadmap modules explicitly distinguished in project documentation. + +**Known audiences:** + +- Authorized penetration testers and red-team operators +- Security researchers and CTF users +- Developers integrating security workflows through HTTP or MCP +- Contributors extending operators, tools, benchmarks, and target adapters + +Actual installation count, active-user count, commercial use, support commitments, and production fleet size are **unknown**. + +## Current Scope and Features + +Evidence in `README.md`, `FEATURES.md`, `src/`, and `bench/` shows these major capabilities: + +- Multi-agent mission planning and execution with an Op Admiral coordinator +- Eight operator archetypes covering the offensive-security kill chain +- Target definition, rules of engagement, and egress-scope containment +- Tool-backed reconnaissance and exploitation adapters +- Evidence collection, findings, reports, verification, and disclosure drafting +- CLI and localhost-only browser War Room +- Express HTTP API and stdio MCP server +- Provider/model abstraction for cloud, local, and connected coding-agent execution +- White-box source ingestion for multiple programming languages +- Benchmark and claim-verification suites for XBEN, Cybench, CVE hunting, cloud, mobile, binary, and evolutionary experiments +- Docker-based runtime and isolated CTF challenge environments + +The repository honestly marks cloud, mobile, binary/reverse-engineering, swarm reliability, and some advanced modules as scaffolding, experimental, or research rather than uniformly production-ready. + +## Architecture + +**Style:** Modular monolith with multiple delivery surfaces and externally executed tools. + +**Primary components:** + +- `src/cli.ts` and `src/index.ts`: command-line and library entry points +- `src/server.ts`: Express API and static War Room host +- `src/mcp-server.ts`: MCP stdio integration +- `src/orchestration/`, `src/mission/`, `src/admiral/`, `src/operators/`: planning, coordination, and mission lifecycle +- `src/arsenal/`: tool catalog, adapters, parsers, approvals, and post-exploitation support +- `src/target/`, `src/opsec/`, `src/evidence/`, `src/reporting/`: scope, safety, evidence, and deliverables +- `src/llm/`, `src/config/`: provider/model and runtime configuration +- `src/recon/`: black-box and multi-language white-box reconnaissance +- `bench/`: reproducible evaluation data and benchmark harnesses +- `ctf/`: isolated challenge manifests, executor, and containers +- `docs/` and `docsite/`: operator, developer, architecture, and release documentation + +**Persistence:** Primarily local configuration and filesystem artifacts. Docker mounts `reports/` and `evidence/`. Browser settings use localStorage. No application database is evident. + +**Integration points:** + +- Hosted model APIs and local OpenAI-compatible inference endpoints +- Connected local coding-agent CLIs +- MCP-aware clients +- Security command-line tools and network services +- GitHub for source, collaboration, releases, and private security advisories +- Pagenary for documentation publishing + +## Scale and Performance + +This is primarily a local/self-hosted operator platform rather than a centrally hosted multi-tenant service. Horizontal service scaling, distributed persistence, queue infrastructure, and formal load-balancing configuration were not detected. + +Performance-sensitive areas include: + +- LLM request latency and provider fallback +- Mission/task timeout management +- External tool execution +- Multi-language source ingestion +- Concurrent agent/operator orchestration +- Benchmark corpus processing + +Exact throughput, concurrent-user capacity, p95 latency, resource profiles, and installation scale are unknown. Existing timeout controls and deterministic benchmark harnesses provide a foundation for measuring these characteristics. + +## Security, Safety, and Compliance + +**Posture:** Strong product-level safety and verification controls for an established open-source offensive-security tool, but not evidence of a certified enterprise control environment. + +**Controls found:** + +- Explicit authorized-use and written-scope requirements +- Default localhost binding for the HTTP server and Docker port +- Localhost CORS/origin and Host-header guards +- Target-origin-bound credential/header injection +- Egress-scope containment for networked tools +- Approval gating for dangerous or catalog-only tool paths +- Environment-variable secret handling and protected local paths +- Evidence, finding verification, claim provenance, and anti-fitting checks +- Private vulnerability reporting through GitHub Security Advisories +- CI lint, type, test, coverage, claim, provenance, prompt, and smoke gates + +**Sensitive data potentially handled:** API keys, target authentication headers, vulnerability evidence, findings, captured credentials, private disclosure drafts, target metadata, and raw model/tool output. + +**Compliance context:** The software may be used in environments subject to GDPR, CCPA, PCI DSS, HIPAA, CFAA, and local cybercrime laws, but repository references are usage guidance—not proof that T3MP3ST itself is certified for any regime. + +## Team and Process + +- **Repository activity:** 151 commits in the last year at analysis time +- **Contributors:** More than ten author identities appear in the last-year history; exact active human team size is unclear because bot/agent and alias identities are mixed +- **Branch/process model:** Pull-request and `main` push CI; exact branch-protection and reviewer requirements are not inferable from the local checkout +- **Tests:** 75 test/spec-named files across `src/` and `scripts/` +- **CI:** GitHub Actions runs install, lint, typecheck, tests, coverage, doctor, claim verification, anti-fitting, provenance, prompt audit, and smoke checks +- **Documentation:** Extensive README, security policy, developer/operator guides, feature status, benchmark methodology, whitepaper, and generated docsite +- **Release/operations:** Release checklist and operational preflight tooling exist; formal on-call, SLA, incident-management, and hosted-service procedures are unknown + +## Dependencies and Infrastructure + +- TypeScript/ESM on Node.js +- Express and CORS for the local HTTP surface +- Model Context Protocol SDK +- Commander/Inquirer and terminal UI packages for CLI interaction +- AJV for schema validation +- Undici and SOCKS networking +- Tree-sitter WASM for multi-language source ingestion +- Vitest, ESLint, and TypeScript quality tooling +- Docker/Docker Compose for the application and isolated challenge/tool environments +- GitHub Actions CI + +No Kubernetes, Terraform, service mesh, managed database, centralized cache, or message queue was detected in the analyzed repository. + +## Known Issues and Technical Debt + +- Stable, experimental, research, and planned capabilities coexist in one product surface, increasing expectation-management and regression risk. +- Coordinated swarm exploitation remains less proven than the benchmarked single-agent path. +- White-box multi-language ingestion is explicitly experimental. +- Cloud, mobile, binary, and advanced modules remain partially scaffolded. +- The platform can execute real offensive actions, so scope enforcement and approval boundaries are continuously high-risk code. +- Local filesystem artifacts can contain sensitive engagement or pre-disclosure material. +- Eighteen TODO/FIXME/HACK/XXX markers were found in `src/` and `scripts/`; each requires triage rather than being assumed defective. +- Package and canonical tracker repository metadata point to different GitHub owners, which may confuse release provenance unless intentional and documented. + +## Why This Intake Now? + +The invocation supplied no additional business guidance. The evidenced purpose is to establish a current SDLC baseline from the existing codebase, preserve the distinction between shipped and aspirational capabilities, and provide a reviewable starting point for requirements, architecture, risk, and roadmap decisions. + +## Unknowns Requiring Owner Validation + +- Current active installations and users +- Maintainer roles, staffing, and support model +- Funding or commercial model +- Production usage patterns and capacity objectives +- Formal uptime, latency, recovery, or support commitments +- Regulatory or contractual obligations of maintainers +- Near-term milestone, roadmap priority, and desired investment trade-offs + +## Next Steps + +1. Validate the unknowns above with project owners. +2. Review the recommended rigor and roadmap in `solution-profile.md`. +3. Confirm priorities and trade-offs in `option-matrix.md`. +4. If accepted, use the intake as input to an Inception or continuous architecture/risk workflow. `intake-start` is not required for this generated intake. diff --git a/.aiwg/intake/risk-screening.md b/.aiwg/intake/risk-screening.md new file mode 100644 index 00000000..a1fa1771 --- /dev/null +++ b/.aiwg/intake/risk-screening.md @@ -0,0 +1,13 @@ +# Initial Risk Screening + +| ID | Risk | Severity | Evidence | Mitigation / control | Status | +| --- | --- | --- | --- | --- | --- | +| R-01 | Operations exceed authorized target scope | Critical | Real network/exploitation tools | Target scope model, egress containment, approvals, scope receipts | Controlled; continuous verification | +| R-02 | Secrets or engagement evidence leak | High | Provider keys, target headers, reports/evidence | Environment variables, target-origin binding, protected paths, local storage guidance | Open residual risk | +| R-03 | Aspirational capability is represented as shipped | High | Broad `VISION.md`; mixed maturity surface | Status labels, claim verifier, vision-alignment matrix | Controlled; governance required | +| R-04 | Model/tool nondeterminism produces false findings | High | LLM and external-tool execution | Ground-truth grading, finding verification, refuter/provenance gates | Open residual risk | +| R-05 | External tools or dependencies compromise host/supply chain | High | Arsenal and container/tool installation | Narrow adapters, approval paths, pinned CI actions, isolated execution guidance | Open | +| R-06 | Modular monolith accumulates unsafe coupling | Medium | Broad `src/` domain surface | Module boundaries, SAD, ADRs, architecture checks | Open | +| R-07 | Local artifact loss or retention mishandling | Medium | Filesystem reports/evidence and browser localStorage | Protected update paths and operator procedures | Open | + +No risk makes the documented current solution infeasible. R-01 is blocking for any release that weakens default containment without an approved replacement control. diff --git a/.aiwg/intake/solution-profile.md b/.aiwg/intake/solution-profile.md new file mode 100644 index 00000000..b81acb59 --- /dev/null +++ b/.aiwg/intake/solution-profile.md @@ -0,0 +1,109 @@ +# Solution Profile (Current System) + +**Document type:** Existing system profile +**Generated:** 2026-07-20 + +## Current Profile + +**Profile:** Established production-grade open-source tool with experimental and research subsystems. + +This classification reflects the repository rather than an unknown hosted deployment: + +- Stable CLI, mission engine, War Room, HTTP API, MCP, arsenal, and benchmark paths are documented. +- The project has a 1.0.0 package version, active contributors, comprehensive CI, Docker packaging, and release procedures. +- Real network and exploitation operations create materially higher safety and security obligations than an ordinary local developer tool. +- Several domains and coordinated-agent behaviors are still explicitly experimental, scaffolded, or research-stage. + +## Current-State Assessment + +### Security and Safety + +**Level:** Strong for a self-hosted offensive-security project; enterprise certification is unverified. + +Strengths include localhost defaults, target-bound authentication, scope containment, approvals, authorization doctrine, secret hygiene, private disclosure, provenance, and deterministic verification gates. + +Material risks remain around dangerous tool execution, third-party binaries, target secrets, sensitive evidence, prompt/model behavior, and the gap between declared and technically enforced rules of engagement. + +### Reliability and Observability + +**Level:** Moderate. + +Health endpoints, Docker health checks, timeout controls, structured mission state, smoke tests, preflight checks, and benchmark receipts are present. No repository evidence establishes production SLOs, centralized metrics/traces, alerting, fleet telemetry, backup/restore objectives, or an on-call model. + +### Testing and Quality + +**Level:** Strong. + +GitHub Actions runs broad deterministic gates. The repository includes Vitest tests plus many dedicated script-level self-tests and benchmark verifiers. Coverage thresholds explicitly protect multi-language ingest files. A repository-wide coverage percentage was not assumed because the intake did not execute the full coverage suite and the configuration scopes strict thresholds to selected files. + +### Documentation + +**Level:** Strong. + +The project includes operator and developer guides, API/MCP documentation, security and authorization policies, feature maturity labels, benchmark methodology, release guidance, a whitepaper, and a generated docsite. + +### Architecture and Maintainability + +**Level:** Moderate-to-strong. + +The modular TypeScript structure separates orchestration, operators, tools, targets, evidence, reporting, providers, and delivery surfaces. Complexity is elevated by the broad domain surface, external-tool adapters, multiple model/provider modes, live security actions, benchmark code, and the coexistence of stable and experimental paths. + +### Delivery and Operations + +**Level:** Moderate. + +Docker, GitHub Actions, release checklists, update tooling, doctor/preflight commands, and documentation publishing exist. The application is designed primarily for self-hosting; deployment automation beyond local Docker and CI is not evidenced. + +## Recommended Profile + +Adopt a **full SDLC rigor level for core safety boundaries and releases**, with **moderate, evidence-driven rigor for experimental modules**. + +Core areas needing full rigor: + +- Scope and authorization enforcement +- Credential and evidence handling +- Dangerous-tool approvals +- Mission execution and target containment +- Public benchmark and capability claims +- Release provenance and supply-chain controls + +Experimental modules should use lighter iteration while retaining explicit maturity labels, threat analysis, tests around shared safety boundaries, and benchmark criteria before promotion to stable. + +## Improvement Roadmap + +### Immediate + +1. Validate owner-only unknowns: users, deployment patterns, support commitments, roadmap, and compliance obligations. +2. Reconcile or document the intentional distinction between package repository metadata and the configured canonical tracker remote. +3. Triage the 18 source/script debt markers and classify each as actionable, intentional, or obsolete. +4. Define promotion criteria for every experimental/scaffolded domain: functional test, safety gate, benchmark receipt, docs, and rollback path. + +### Near Term + +1. Publish a concise architecture decision record for trust boundaries across UI/API, local agents, model providers, arsenal tools, target systems, and artifact storage. +2. Define measurable reliability targets for local server health, mission/task timeout behavior, provider fallback, and artifact durability. +3. Add a documented sensitive-artifact lifecycle covering retention, redaction, encryption expectations, backups, and coordinated-disclosure material. +4. Map CI gates to risks and public claims so maintainers can see which control prevents which failure. + +### Longer Term + +1. Establish an explicit maturity/promotion lifecycle from scaffolded → experimental → stable. +2. Add workload and concurrency benchmarks for mission orchestration and source ingestion. +3. Introduce release provenance controls appropriate to the threat model, such as signed tags/artifacts and dependency/SBOM policy, if not already handled outside the repository. +4. Revisit governance rigor when maintainer count, external integrations, hosted operation, contracts, or regulated usage grows. + +## Tailoring + +Recommended AIWG components: + +- Intake, architecture decisions, risk register, security requirements, threat model, test strategy, release/deployment plan, and operational runbook +- Continuous architecture, security-review, requirements-evolution, and risk-management workflows +- Traceability focused on safety controls and externally advertised claims + +Lower-value components until owner context changes: + +- Enterprise organizational governance, legal RACI, or formal change-control boards +- Multi-region hosted-service artifacts +- Database migration plans for an application database that does not currently exist + +Revisit those exclusions if the project becomes a hosted service, assumes contractual SLAs, processes centrally retained customer data, or grows into a larger formal organization. diff --git a/.aiwg/planning/iteration-001-plan.md b/.aiwg/planning/iteration-001-plan.md new file mode 100644 index 00000000..75f6a6c1 --- /dev/null +++ b/.aiwg/planning/iteration-001-plan.md @@ -0,0 +1,24 @@ +# Iteration 001 Plan — Architecture Alignment + +**Sprint goal:** Make current-state architecture and vision alignment maintainable, testable governance assets. + +## Planned Work + +1. Review and accept/amend SAD and ADR-001–005 with maintainers. +2. Reconcile canonical repository identity in package metadata and tracker configuration. +3. Add a documentation audit that detects stable/experimental/roadmap conflicts across README, FEATURES, SAD, and vision alignment. +4. Map each network-capable arsenal adapter to scope/approval tests. +5. Establish performance baselines for source ingestion and concurrent mission tasks. +6. Triage the 18 TODO/FIXME/HACK/XXX markers identified during intake. + +## Definition of Done + +- Maintainer decisions are reflected in accepted/superseded ADR status. +- CI or a documented release check validates maturity claim consistency. +- Safety-test coverage matrix has no unidentified network adapter. +- Baseline measurements include command, corpus, environment, and receipt. +- No roadmap capability is presented as current stable architecture. + +## Dependencies and Risks + +Owner validation is needed for repository identity and roadmap priority. Architecture documentation changes are non-runtime, but any resulting safety-control change requires the full security and claim gate suite. diff --git a/.aiwg/reports/abm-gate-report.md b/.aiwg/reports/abm-gate-report.md new file mode 100644 index 00000000..94f10d8a --- /dev/null +++ b/.aiwg/reports/abm-gate-report.md @@ -0,0 +1,15 @@ +# Architecture Baseline Milestone Gate Report + +**Status:** PASS +**Date:** 2026-07-20 + +| Criterion | Status | Evidence | +| --- | --- | --- | +| SAD exists and is baselined | PASS | `architecture/software-architecture-doc.md`; current-state, >1,000 words | +| At least three ADRs | PASS | ADR-001 through ADR-005 | +| Use-case architectural coverage | PASS | SAD traceability covers UC-001 through UC-005 | +| Test strategy exists | PASS | `testing/test-strategy.md` | +| No unmitigated blocking architecture risk | PASS | R-01 has enforced controls; weakening them is explicitly release-blocking | +| Vision/current-state separation | PASS | ADR-005 and `architecture/vision-alignment.md` | + +The architecture is baselined for maintenance and controlled evolution. “Construction ready” means the brownfield team can prioritize alignment work; it does not relabel experimental features as stable. diff --git a/.aiwg/reports/construction-ready-brief.md b/.aiwg/reports/construction-ready-brief.md new file mode 100644 index 00000000..6837dfe5 --- /dev/null +++ b/.aiwg/reports/construction-ready-brief.md @@ -0,0 +1,44 @@ +# Construction Ready Brief + +**Project:** T3MP3ST +**Date:** 2026-07-20 +**Status:** CONSTRUCTION READY — brownfield architecture alignment + +## Executive Summary + +T3MP3ST is baselined as a local-first TypeScript modular monolith with CLI, library, localhost War Room/API, MCP, provider-neutral reasoning, mission/operator orchestration, deterministic target/arsenal safety controls, evidence/reporting, source analysis, and reproducible evaluation. The architecture documents what is implemented and explicitly refuses to equate `VISION.md` with current capability. + +The highest-value construction work is architectural governance around existing code: validate the SAD/ADRs, automate maturity-claim consistency, complete the safety-test inventory for network adapters, and establish workload baselines. No rewrite or microservice migration is implied. + +## Artifact Index + +| Artifact | Status | +| --- | --- | +| Intake form, solution profile, option matrix, risk screening | Baselined | +| LOM gate | PASS | +| UC-001–UC-005, user stories, NFR register | Baselined | +| Current-state SAD | Baselined | +| ADR-001–ADR-005 | Accepted / retrospective | +| Vision-to-code alignment matrix | Baselined | +| Test strategy | Baselined | +| ABM gate | PASS | +| Iteration 001, team profile, CI/CD additions | Ready | + +## Key Decisions + +1. Retain a local-first modular monolith. +2. Keep reasoning provider-neutral and untrusted. +3. Enforce scope/approval beneath model reasoning. +4. Derive public claims from versioned evidence. +5. Separate implemented current state from research vision. + +## Risks to Watch + +Scope bypass, secret/evidence leakage, maturity overstatement, nondeterministic false findings, and external-tool supply-chain risk remain the leading concerns. See `intake/risk-screening.md` for controls and residual status. + +## First Steps + +1. Maintainers review the SAD and mark any ADR amended or superseded. +2. Execute Iteration 001 architecture-alignment work. +3. Preserve current CI gates while adding traceability/maturity checks. +4. Update the alignment matrix whenever a vision capability changes maturity. diff --git a/.aiwg/reports/lom-gate-report.md b/.aiwg/reports/lom-gate-report.md new file mode 100644 index 00000000..e027614c --- /dev/null +++ b/.aiwg/reports/lom-gate-report.md @@ -0,0 +1,14 @@ +# Lifecycle Objective Milestone Gate Report + +**Status:** PASS +**Date:** 2026-07-20 + +| Criterion | Status | Evidence | +| --- | --- | --- | +| Problem statement defined | PASS | `intake/intake-form.md` | +| Success metrics defined | PASS | Five measurable criteria in intake | +| Stakeholders identified | PASS | Five stakeholder groups in intake | +| Initial risk screening complete | PASS | Seven risks in `intake/risk-screening.md` | +| Solution approach viable | PASS | Existing operational codebase; no infeasible constraint | + +The gate authorizes brownfield elaboration. Unknown adoption, staffing, and SLO facts remain owner inputs but do not prevent documenting current architecture. diff --git a/.aiwg/requirements/UC-001.md b/.aiwg/requirements/UC-001.md new file mode 100644 index 00000000..ddfb24c5 --- /dev/null +++ b/.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. diff --git a/.aiwg/requirements/UC-002.md b/.aiwg/requirements/UC-002.md new file mode 100644 index 00000000..89cefb16 --- /dev/null +++ b/.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. diff --git a/.aiwg/requirements/UC-003.md b/.aiwg/requirements/UC-003.md new file mode 100644 index 00000000..7647cf65 --- /dev/null +++ b/.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/`. diff --git a/.aiwg/requirements/UC-004.md b/.aiwg/requirements/UC-004.md new file mode 100644 index 00000000..34e6adfb --- /dev/null +++ b/.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. diff --git a/.aiwg/requirements/UC-005.md b/.aiwg/requirements/UC-005.md new file mode 100644 index 00000000..e5df52b6 --- /dev/null +++ b/.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`. diff --git a/.aiwg/requirements/nfr-register.md b/.aiwg/requirements/nfr-register.md new file mode 100644 index 00000000..48dfec96 --- /dev/null +++ b/.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 | diff --git a/.aiwg/requirements/user-stories.md b/.aiwg/requirements/user-stories.md new file mode 100644 index 00000000..77e38be8 --- /dev/null +++ b/.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. | diff --git a/.aiwg/team/team-profile.md b/.aiwg/team/team-profile.md new file mode 100644 index 00000000..3e0198ff --- /dev/null +++ b/.aiwg/team/team-profile.md @@ -0,0 +1,15 @@ +# Team Profile for Architecture Stewardship + +## Observed Context + +The last-year Git history contains more than ten author identities, including likely aliases and agent identities, so exact active human staffing is unknown. The project accepts external contributions and uses GitHub Actions on pull requests and `main`. + +## Required Responsibilities + +- **Architecture steward:** Owns SAD, ADR lifecycle, and vision alignment. +- **Safety reviewer:** Reviews scope, credentials, approvals, and dangerous tools. +- **Evaluation steward:** Owns benchmark validity, provenance, and claim wording. +- **Release integrator:** Confirms CI, docs, package metadata, and release evidence. +- **Domain contributor:** Supplies implementation and tests for a specific target/tool domain. + +Roles may be held by the same person. A change crossing a trust boundary should receive both architecture and safety review; a capability/maturity claim should receive evaluation review. diff --git a/.aiwg/testing/test-strategy.md b/.aiwg/testing/test-strategy.md new file mode 100644 index 00000000..c920a940 --- /dev/null +++ b/.aiwg/testing/test-strategy.md @@ -0,0 +1,34 @@ +# Test Strategy — Architecture Baseline + +## Objectives + +Protect safety boundaries, cross-surface contracts, provider/tool adapters, evidence integrity, and public claims while keeping deterministic CI independent of live targets and paid models. + +## Layers + +- **Unit:** target normalization, scope predicates, parsers, configuration, provider selection, evidence transforms. +- **Contract:** CLI/HTTP/MCP schemas, provider adapters, tool argument construction, finding/report formats. +- **Integration:** mission lifecycle, connected-agent fallback, server guards, tool execution with controlled fixtures. +- **Security:** off-scope denial, exact-origin credential injection, command/argument injection, Host/origin controls, malicious target/source content. +- **Benchmark/provenance:** claim re-derivation, ground-truth grading, anti-fitting, model matrix, receipt validation. +- **Operational:** build, doctor, preflight, smoke, Docker health, updater preservation. + +## Architecture Gate Mapping + +| Decision / NFR | Required evidence | +| --- | --- | +| ADR-001 / NFR-04 | Loopback and server guard tests; Docker config review | +| ADR-002 / NFR-06 | Provider selection, fallback, timeout, and local-agent tests | +| ADR-003 / NFR-01/02/05 | Scope, approval, and exact-origin negative tests | +| ADR-004 / NFR-03/09 | Claims, provenance, grading, and anti-fitting gates | +| ADR-005 / NFR-09 | Documentation claim audit against vision-alignment matrix | + +## Release Policy + +Any regression in scope containment, credential routing, dangerous-tool approval, evidence provenance, or claim reproducibility blocks release. Live benchmark failures are evaluated against declared environment/infrastructure outcomes and cannot be silently converted to model failures or successes. + +## Gaps + +- Establish workload baselines for source ingestion and concurrent mission tasks. +- Add a machine-checkable maturity/vision consistency audit. +- Document coverage expectations for every external arsenal adapter. diff --git a/.aiwg/working/sdlc-accelerate/state.json b/.aiwg/working/sdlc-accelerate/state.json new file mode 100644 index 00000000..a19c96b1 --- /dev/null +++ b/.aiwg/working/sdlc-accelerate/state.json @@ -0,0 +1,42 @@ +{ + "status": "COMPLETE", + "started": "2026-07-20T16:20:00-04:00", + "completed": "2026-07-20T16:35:00-04:00", + "entry_mode": "codebase-analysis", + "guidance": "Capture current-state architecture and design; focus on SAD, ADRs, and vision-to-code alignment.", + "phases_completed": [ + "intake", + "lom-gate", + "elaboration", + "abm-gate", + "construction-prep", + "construction-ready-brief" + ], + "phases_remaining": [], + "artifacts_generated": [ + ".aiwg/intake/intake-form.md", + ".aiwg/intake/solution-profile.md", + ".aiwg/intake/risk-screening.md", + ".aiwg/reports/lom-gate-report.md", + ".aiwg/requirements/UC-001.md", + ".aiwg/requirements/UC-002.md", + ".aiwg/requirements/UC-003.md", + ".aiwg/requirements/UC-004.md", + ".aiwg/requirements/UC-005.md", + ".aiwg/requirements/user-stories.md", + ".aiwg/requirements/nfr-register.md", + ".aiwg/architecture/software-architecture-doc.md", + ".aiwg/architecture/adr-001.md", + ".aiwg/architecture/adr-002.md", + ".aiwg/architecture/adr-003.md", + ".aiwg/architecture/adr-004.md", + ".aiwg/architecture/adr-005.md", + ".aiwg/architecture/vision-alignment.md", + ".aiwg/testing/test-strategy.md", + ".aiwg/reports/abm-gate-report.md", + ".aiwg/planning/iteration-001-plan.md", + ".aiwg/team/team-profile.md", + ".aiwg/deployment/ci-cd-scaffold.md", + ".aiwg/reports/construction-ready-brief.md" + ] +}