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,16 +1,126 @@
|
||||
# ADR-001 — Retain a Local-First Modular Monolith
|
||||
|
||||
**Status:** Accepted (retrospective)
|
||||
**Date:** 2026-07-20
|
||||
## Metadata
|
||||
|
||||
- **ADR ID:** ADR-001
|
||||
- **Status:** Accepted (retrospective baseline)
|
||||
- **Decision date:** 2026-07-20
|
||||
- **Authors:** Architecture baseline process
|
||||
- **Reviewers:** Maintainer and safety-review roles; named human approval is not recorded
|
||||
- **Supersedes:** None
|
||||
- **Current level:** L3 — Accepted; current implementation predates the record
|
||||
|
||||
## 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.
|
||||
### Problem
|
||||
|
||||
T3MP3ST exposes a CLI, typed library, localhost HTTP/War Room, MCP, orchestration, tool adapters, evidence, and benchmarks from one Node/TypeScript package. The baseline needs an honest architectural description and an evolution rule that preserves local control without implying service isolation that does not exist.
|
||||
|
||||
### Constraints
|
||||
|
||||
- Self-hosting and low-friction local installation are product values.
|
||||
- CLI, library, HTTP, and MCP reuse the same domain behavior.
|
||||
- Reports, evidence, configuration, and benchmark artifacts are primarily filesystem-backed.
|
||||
- Real tool execution creates safety boundaries that cannot rely on process naming alone.
|
||||
- No application database, distributed queue, multi-tenant identity service, or fleet control plane exists in the current baseline.
|
||||
|
||||
### Stakeholders
|
||||
|
||||
- Operators need local control and visible artifacts.
|
||||
- Integrators need stable typed and protocol surfaces.
|
||||
- Safety reviewers need clear trust boundaries despite a shared runtime.
|
||||
- Maintainers need coherent module ownership without distributed-system overhead.
|
||||
|
||||
## Source Verification and Claim Tracking
|
||||
|
||||
| Claim | Source | Verification |
|
||||
| --- | --- | --- |
|
||||
| Runtime and delivery surfaces ship in one package | `package.json`, CLI/server/MCP/library entry points | Direct code/package inspection |
|
||||
| HTTP defaults to local exposure | Server and Compose configuration | Static hardening tests and configuration inspection |
|
||||
| No application database or queue is part of the baseline | Source/configuration inventory and SAD | Repository inspection; future addition triggers a new ADR |
|
||||
|
||||
## 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.
|
||||
Treat the current system as a **local-first modular monolith with ports/adapters characteristics**. Delivery adapters and provider/tool adapters translate into shared domain modules in one Node.js runtime. Do not describe the architecture as microservices. Keep default HTTP exposure loopback-only and keep local artifacts under operator control.
|
||||
|
||||
Module boundaries are enforced through typed contracts, narrow adapters, tests, and architecture review. A hosted multi-tenant mode, distributed worker topology, or new durable shared store requires a new architecture baseline rather than being treated as a deployment toggle.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Microservices now
|
||||
|
||||
- **Pros:** Process isolation, independently deployable components, per-service scaling.
|
||||
- **Cons:** Adds network identity, distributed state, deployment, observability, and failure modes without evidenced fleet requirements.
|
||||
- **Why not chosen:** The operational cost conflicts with local-first installation and would not automatically solve tool/target safety.
|
||||
|
||||
### Plug-in processes for every domain
|
||||
|
||||
- **Pros:** Stronger fault and dependency isolation for tools/domains.
|
||||
- **Cons:** IPC contracts, packaging complexity, lifecycle management, and difficult local debugging.
|
||||
- **Why not chosen:** Selective external tool processes already exist; making every module a process is not justified by current evidence.
|
||||
|
||||
### Unstructured single-module application
|
||||
|
||||
- **Pros:** Minimal ceremony.
|
||||
- **Cons:** Unsafe coupling, poor test seams, and high regression risk across trust boundaries.
|
||||
- **Why not chosen:** The codebase already has meaningful domain/adaptor modules whose contracts must remain reviewable.
|
||||
|
||||
## 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.
|
||||
### Positive
|
||||
|
||||
- One install and runtime supports all primary local surfaces.
|
||||
- Shared typed modules reduce duplicated domain and safety logic.
|
||||
- Filesystem artifacts remain inspectable and operator-controlled.
|
||||
|
||||
### Negative
|
||||
|
||||
- Process boundaries do not enforce module isolation.
|
||||
- A crash or resource-exhaustion defect can affect multiple domains.
|
||||
- Scaling and hosted tenancy are not inherent properties of the architecture.
|
||||
|
||||
### Operational Impact
|
||||
|
||||
- Maintainers must review dependency direction and surface parity.
|
||||
- Local process startup, shutdown, filesystem permissions, and loopback exposure are architectural concerns.
|
||||
- External tools remain separate processes with explicit argument, timeout, and output contracts.
|
||||
|
||||
## Risks and Mitigations
|
||||
|
||||
| Risk | Likelihood / impact | Mitigation |
|
||||
| --- | --- | --- |
|
||||
| Unsafe cross-module coupling | Medium / High | Typed adapters, negative safety tests, ADR review for trust-boundary changes |
|
||||
| Local process resource exhaustion | Medium / Medium | Finite timeouts, bounded ingest, controlled subprocess execution |
|
||||
| Architecture mislabeled as distributed or production-fleet ready | Medium / High | SAD and maturity matrix; ADR-005 claim discipline |
|
||||
|
||||
## Implementation and Verification
|
||||
|
||||
- **Key integration points:** `src/cli.ts`, `src/index.ts`, `src/server.ts`, and `src/mcp-server.ts` compose shared domain code.
|
||||
- **State model:** In-memory mission state plus local configuration, reports, evidence, and benchmark artifacts; no shared transactional store.
|
||||
- **Concurrency model:** Node event-loop and explicitly managed parallel tasks/processes; shared mutable state remains process-local unless persisted as an artifact.
|
||||
- **Testing:** Build/typecheck, entry-surface tests, local API hardening, agent parallelism, adapter tests, smoke and doctor commands.
|
||||
- **Regression guard:** A change introducing a remotely exposed service, shared durable store, or distributed worker cannot close without an ADR/SAD update.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [x] Context, decision, alternatives, consequences, and risks documented.
|
||||
- [x] Current implementation and tests identified.
|
||||
- [x] SAD describes the same architectural style.
|
||||
- [ ] Named maintainer approval is recorded in a future review-incorporation log.
|
||||
- [ ] Measured startup/shutdown and resource baselines are added before any related performance claim.
|
||||
|
||||
## References
|
||||
|
||||
- @.aiwg/requirements/UC-003.md — Delivery-surface requirements.
|
||||
- @.aiwg/requirements/nfr-register.md — Local security, portability, compatibility, and maintainability constraints.
|
||||
- @.aiwg/architecture/software-architecture-doc.md — Current component, state, and deployment views.
|
||||
- @src/cli.ts — CLI adapter.
|
||||
- @src/index.ts — Library composition surface.
|
||||
- @src/server.ts — Local HTTP/War Room adapter.
|
||||
- @src/mcp-server.ts — MCP adapter.
|
||||
- @docker-compose.yml — Local container deployment and volume/port configuration.
|
||||
- @src/__tests__/local-api-hardening-static.test.ts — Local HTTP boundary evidence.
|
||||
|
||||
## Review and Approval
|
||||
|
||||
This record captures an implemented brownfield decision. It is accepted as the documentation baseline, not as evidence of a historical architecture-board vote. A maintainer may amend or supersede it; that review must name the reviewer, date, conditions, and affected SAD sections.
|
||||
Reference in new issue
Block a user