Joseph Magly
afc9dad1b2
* docs(policy): allow low-impact contributor courtesy cleanup * chore(aiwg): migrate to shared BT6 maintainer plugin * chore: reconcile delivery validation
125 lines
6.3 KiB
Markdown
125 lines
6.3 KiB
Markdown
# ADR-005 — Separate Current State from Research Vision
|
|
|
|
## Metadata
|
|
|
|
- **ADR ID:** ADR-005
|
|
- **Status:** Accepted
|
|
- **Decision date:** 2026-07-20
|
|
- **Authors:** Architecture baseline process
|
|
- **Reviewers:** Maintainer, architecture, and evaluation-review roles; named human approval is not recorded
|
|
- **Supersedes:** None
|
|
- **Current level:** L3 — Accepted and applied to the SDLC baseline
|
|
|
|
## Context
|
|
|
|
### Problem
|
|
|
|
`VISION.md` intentionally explores autonomous, distributed, cognitive, adversarial-ML, swarm, knowledge, and evolutionary directions beyond the stable product. Treating that direction as current architecture would create fictitious components, unsafe assumptions, and misleading capability claims. Conversely, ignoring the vision would make design evolution incoherent.
|
|
|
|
### Constraints
|
|
|
|
- Current architecture must be supported by code, tests, retained evidence, or explicit runtime configuration.
|
|
- A benchmark proves only its declared corpus, harness, model, and metric.
|
|
- Stable and experimental features share product surfaces and therefore need conspicuous maturity boundaries.
|
|
- Persistent autonomy, distributed execution, and shared knowledge services materially change safety and operational architecture.
|
|
|
|
### Stakeholders
|
|
|
|
- Users need honest expectations about reliability and support.
|
|
- Researchers need freedom to explore future directions without premature product claims.
|
|
- Maintainers need explicit promotion gates and architecture triggers.
|
|
- Safety/evaluation reviewers need evidence that matches claim strength.
|
|
|
|
## Source Verification and Claim Tracking
|
|
|
|
| Claim | Source | Verification |
|
|
| --- | --- | --- |
|
|
| Vision contains broader future directions | `VISION.md` | Direct document inspection |
|
|
| Current implementation realizes directions unevenly | Source, tests, benchmark receipts, SAD | Vision-alignment evidence matrix |
|
|
| Product docs label maturity | README/features documentation | Documentation consistency review; automation remains planned |
|
|
|
|
## Decision
|
|
|
|
Maintain two linked but distinct views:
|
|
|
|
1. A current-state SAD derived from implemented code, tests, configuration, and versioned evidence.
|
|
2. A vision-alignment matrix that classifies each direction as implemented, partial/experimental, research, or future and states the next proof required.
|
|
|
|
Alignment is not implementation. Promotion to stable requires deterministic shared-safety tests, an operational path, current documentation, reproducible evidence appropriate to the claim, and updated UC/US/NFR/SAD traceability. Persistent autonomy, distributed workers, hosted multi-tenancy, or shared knowledge infrastructure triggers new threat modeling and ADR/SAD work.
|
|
|
|
## Alternatives Considered
|
|
|
|
### Treat the vision as the target architecture
|
|
|
|
- **Pros:** A single aspirational design narrative.
|
|
- **Cons:** Documents unimplemented systems as real and obscures immediate trust boundaries.
|
|
- **Why not chosen:** Violates evidence-based architecture and capability honesty.
|
|
|
|
### Remove future vision from architecture governance
|
|
|
|
- **Pros:** Purely current-state documentation.
|
|
- **Cons:** Loses strategic intent and makes research promotion ad hoc.
|
|
- **Why not chosen:** The vision is useful when explicitly separated and evidence-gated.
|
|
|
|
### Use a single stable/unstable label
|
|
|
|
- **Pros:** Simple classification.
|
|
- **Cons:** Conflates scaffold, experiment, research result, and supported capability.
|
|
- **Why not chosen:** The lifecycle needs more precise promotion and claim language.
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
- Architecture remains factual while research direction remains visible.
|
|
- Each maturity promotion has an evidence and governance trigger.
|
|
- Benchmark success cannot silently upgrade general product maturity.
|
|
|
|
### Negative
|
|
|
|
- Maintainers must synchronize product docs, SAD, alignment, requirements, and tests.
|
|
- Classification disagreements require explicit evidence review.
|
|
- A manual consistency process can drift until automation is implemented.
|
|
|
|
## Risks and Mitigations
|
|
|
|
| Risk | Likelihood / impact | Mitigation |
|
|
| --- | --- | --- |
|
|
| Aspirational language leaks into stable claims | High / High | Alignment matrix, claim verifier, documentation audit |
|
|
| Mature feature remains mislabeled experimental | Medium / Medium | Promotion checklist and periodic review |
|
|
| Benchmark is generalized beyond evaluated scope | Medium / High | ADR-004 evidence boundary and corpus-scoped wording |
|
|
| New distributed/autonomous path bypasses architecture review | Medium / Critical | Explicit new-baseline triggers in SAD/NFR-12 |
|
|
|
|
## Implementation and Verification
|
|
|
|
- **Current-state source:** SAD, ADRs, requirements, code/tests, and CI evidence.
|
|
- **Directional source:** `VISION.md`.
|
|
- **Reconciliation artifact:** `vision-alignment.md` with evidence and next-proof columns.
|
|
- **Testing/governance:** Claim verification, stub-honesty/arsenal-count tests, documentation review, and planned machine-checkable maturity audit.
|
|
- **Regression guard:** No roadmap/research item is described as stable without completing the promotion evidence and traceability update.
|
|
|
|
## Definition of Done
|
|
|
|
- [x] Current-state and directional documents are distinct and cross-referenced.
|
|
- [x] Each vision vector has a maturity classification, evidence, and next proof.
|
|
- [x] Promotion triggers are documented.
|
|
- [ ] Machine-checkable cross-document maturity consistency gate is implemented.
|
|
- [ ] Named maintainer/evaluation approval is recorded.
|
|
|
|
## References
|
|
|
|
- @VISION.md — Directional research vision.
|
|
- @README.md — Primary product capability surface.
|
|
- @FEATURES.md — Feature and maturity inventory.
|
|
- @.aiwg/architecture/software-architecture-doc.md — Implemented current-state baseline.
|
|
- @.aiwg/architecture/vision-alignment.md — Evidence-based maturity reconciliation.
|
|
- @.aiwg/requirements/UC-005.md — Claim reproduction requirements.
|
|
- @.aiwg/requirements/nfr-register.md — Honesty and maintainability constraints.
|
|
- @src/__tests__/stub-honesty.test.ts — Stub/maturity evidence.
|
|
- @src/__tests__/arsenal-count-honesty.test.ts — Public-count honesty evidence.
|
|
- @scripts/verify-claims.mjs — Claim derivation gate.
|
|
|
|
## Review and Approval
|
|
|
|
The decision governs the current baseline. Named historical review evidence is not present; no approval is inferred. Promotion or reclassification requires an evidence review recorded in the SAD review log and alignment matrix.
|