stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

save progress

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-26 22:03:32 +02:00
parent 9a4cd2e0f7
commit e6c47c8f50
3634 changed files with 253222 additions and 56632 deletions
Download Patch File Download Diff File Expand all files Collapse all files

329
docs/implplan/archived/2025-12-28-docs-consolidation/SPRINT_1228_0001_DOCS_module_documentation_consolidation.md Normal file
View File

@@ -0,0 +1,329 @@
# Sprint: Module Documentation Consolidation
| Field | Value |
|-------|-------|
| **Sprint ID** | SPRINT_1228_0001 |
| **Batch** | 001 - Documentation Alignment |
| **Module** | DOCS (Documentation) |
| **Topic** | Merge existing documentation with current module state |
| **Priority** | P1 - Infrastructure |
| **Estimated Effort** | High |
| **Dependencies** | None |
| **Working Directory** | `docs/modules/` |
---
## Objective
Ensure all StellaOps modules in `src/` are documented in `docs/modules/` with consistent architecture.md files, aligned with the current codebase state.
---
## Executive Summary
### Current State Analysis
**Source Modules (50+ in `src/`):**
AdvisoryAI, AirGap, Aoc, Api, Attestor, Authority, Bench, BinaryIndex, Cartographer, Cli, Concelier, Cryptography, DevPortal, EvidenceLocker, Excititor, ExportCenter, Feedser, Findings, Gateway, Graph, IssuerDirectory, Mirror, Notifier, Notify, Orchestrator, PacksRegistry, Policy, Provenance, ReachGraph, Registry, Replay, RiskEngine, Router, SbomService, Scanner, Scheduler, Sdk, Signals, Signer, SmRemote, Symbols, TaskRunner, Telemetry, TimelineIndexer, Unknowns, VexHub, VexLens, VulnExplorer, Web, Zastava
**Documented Modules (48 dirs in `docs/modules/`):**
advisory-ai, airgap, attestor, authority, benchmark, binaryindex, cartographer, ci, cli, concelier, cryptography, devops, evidence, evidence-locker, excititor, export-center, findings-ledger, gateway, graph, issuer-directory, mirror, notify, orchestrator, platform, policy, provcache, reachgraph, registry, router, sbomservice, scanner, scheduler, sdk, signals, signer, snapshot, symbols, taskrunner, telemetry, triage, ui, unknowns, vexhub, vex-lens, vuln-explorer, web, zastava
**Modules with architecture.md (35):**
advisory-ai, attestor, authority, benchmark, binaryindex, ci, cli, concelier, devops, excititor, export-center, gateway, graph, issuer-directory, notify, orchestrator, platform, policy, provcache, reachgraph, registry, router, sbomservice, scanner, scheduler, signals, signer, taskrunner, telemetry, ui, vexhub, vex-lens, vuln-explorer, zastava
---
## Gap Analysis
### Category 1: Missing from docs/modules/ entirely (No folder)
These `src/` modules have NO corresponding documentation folder:
| Module | Purpose | Priority |
|--------|---------|----------|
| **Aoc** | Architecture-of-Code analyzers | Medium |
| **Api** | Shared API contracts | Low (library) |
| **DevPortal** | Developer portal frontend | Medium |
| **Feedser** | Evidence collection for backport detection | High (active) |
| **Notifier** | Legacy notification service (vs Notify) | Low (clarify vs Notify) |
| **PacksRegistry** | Task packs registry | Medium |
| **Provenance** | Provenance attestation tooling | High |
| **Replay** | Deterministic replay engine | High |
| **RiskEngine** | Risk scoring engine | High |
| **SmRemote** | SM cryptography remote service | Medium |
| **TimelineIndexer** | Timeline event indexing | Medium |
### Category 2: Has docs folder but NO architecture.md
| Module | Existing Docs | Action |
|--------|---------------|--------|
| **airgap** | README, evidence-reconciliation, exporter-cli-coordination, mirror-dsse-plan | Create architecture.md |
| **cartographer** | (empty or minimal) | Create architecture.md |
| **cryptography** | README, multi-profile-signing-specification | Create architecture.md |
| **evidence** | (unclear purpose) | Clarify: merge into evidence-locker? |
| **evidence-locker** | README, attestation-contract, bundle-packaging, etc. | Create architecture.md |
| **findings-ledger** | (minimal) | Create architecture.md |
| **mirror** | provenance/observers | Create architecture.md |
| **sdk** | (minimal) | Create architecture.md |
| **snapshot** | (unclear purpose) | Clarify purpose |
| **symbols** | (minimal) | Create architecture.md |
| **triage** | (minimal) | Create architecture.md |
| **unknowns** | (minimal) | Create architecture.md |
| **web** | (minimal) | Create architecture.md (frontend) |
### Category 3: Meta/Organizational docs (not direct src modules)
| Doc Folder | Mapping | Action |
|------------|---------|--------|
| **benchmark** | Maps to `src/Bench/` | Rename or add alias note |
| **ci** | DevOps/CI infrastructure | Keep as infrastructure docs |
| **devops** | DevOps infrastructure | Keep as infrastructure docs |
| **evidence** | Unclear | Clarify: merge into evidence-locker |
| **platform** | Umbrella/cross-cutting | Keep as overview docs |
| **provcache** | Library under `__Libraries` | Document as library |
| **snapshot** | Unclear | Research purpose |
| **triage** | Feature, not standalone module | Document as feature |
| **ui** | Maps to `src/Web/` | Merge with web or clarify |
### Category 4: Naming Mismatches
| docs/modules/ | src/ | Action |
|---------------|------|--------|
| benchmark | Bench | Add cross-reference |
| findings-ledger | Findings | Align naming |
| ui | Web | Merge or cross-reference |
---
## Documentation Template Standard
Every module MUST have an `architecture.md` following this structure:
```markdown
# component_architecture_{module}.md - **Stella Ops {Module}** (YYYY-QQ)
> Aligned with Epic X - {Epic Name}
> **Scope.** Implementation-ready architecture for **{Module}**: {brief description}
---
## 0) Mission & boundaries
**Mission.** {One paragraph describing the module's core purpose}
**Boundaries.**
* {What the module does NOT do}
* {Interactions with other modules}
* {Scope limitations}
---
## 1) Solution & project layout
```
src/{Module}/
├─ StellaOps.{Module}.WebService/ # if applicable
├─ StellaOps.{Module}.Worker/ # if applicable
├─ StellaOps.{Module}.Core/ # core logic
├─ StellaOps.{Module}.Models/ # DTOs, entities
├─ StellaOps.{Module}.Persistence/ # database layer
└─ __Tests/ # test projects
```
---
## 2) External dependencies
* {Database requirements}
* {Message queue requirements}
* {External service dependencies}
* {Authentication/Authorization}
---
## 3) Contracts & data model
### 3.1 Core entities
{Entity definitions with JSON examples}
### 3.2 Database schema
{Table definitions}
---
## 4) REST API (if applicable)
{API endpoint documentation}
---
## 5) Configuration (YAML)
```yaml
{module}:
# configuration options
```
---
## 6) Security & compliance
* {Authentication requirements}
* {Authorization model}
* {Data handling}
---
## 7) Performance targets
* {Throughput targets}
* {Latency targets}
* {Resource limits}
---
## 8) Observability
* **Metrics**: {key metrics}
* **Tracing**: {span patterns}
* **Logs**: {log patterns}
---
## 9) Testing matrix
* {Test categories}
* {Coverage requirements}
---
## 10) Failure modes & recovery
* {Failure scenarios}
* {Recovery procedures}
---
```
---
## Execution Plan
### Phase 1: Critical Modules (Priority P0)
Create architecture.md for actively developed modules:
| Task | Module | Effort | Status |
|------|--------|--------|--------|
| 1.1 | Feedser | Medium | DONE |
| 1.2 | Replay | Medium | DONE |
| 1.3 | RiskEngine | Medium | DONE |
| 1.4 | Provenance | Medium | DONE |
| 1.5 | evidence-locker (add arch) | Low | DONE |
| 1.6 | cryptography (add arch) | Low | DONE |
| 1.7 | airgap (add arch) | Low | DONE |
### Phase 2: Standard Modules (Priority P1)
| Task | Module | Effort | Status |
|------|--------|--------|--------|
| 2.1 | PacksRegistry | Low | DONE |
| 2.2 | TimelineIndexer | Low | DONE |
| 2.3 | SmRemote | Low | SKIPPED (minimal module) |
| 2.4 | DevPortal | Low | SKIPPED (minimal module) |
| 2.5 | mirror (add arch) | Low | DONE |
| 2.6 | unknowns (add arch) | Low | DONE |
| 2.7 | symbols (add arch) | Low | DONE |
| 2.8 | web (add arch) | Low | DONE |
### Phase 3: Cleanup & Alignment (Priority P2)
| Task | Action | Status |
|------|--------|--------|
| 3.1 | Resolve evidence vs evidence-locker | DONE (both valid: evidence=concept, evidence-locker=module) |
| 3.2 | Resolve ui vs web | DONE (cross-referenced, ui=comprehensive, web=triage-specific) |
| 3.3 | Resolve benchmark vs Bench naming | DONE (benchmark=competitive, bench=performance) |
| 3.4 | Clarify Notifier vs Notify | DONE (Notifier=host, Notify=toolkit; created docs/modules/notifier) |
| 3.5 | Document Aoc purpose | DONE (created docs/modules/aoc/) |
| 3.6 | Document Api contracts | DONE (created docs/modules/api/) |
| 3.7 | Clarify snapshot purpose | DONE (already documented as cross-cutting concept) |
| 3.8 | Clarify triage scope | DONE (already documented as cross-cutting concept) |
### Phase 4: Cross-Reference Updates (Priority P2)
| Task | Action | Status |
|------|--------|--------|
| 4.1 | Update CLAUDE.md module table | DONE (added 15+ modules) |
| 4.2 | Update 07_HIGH_LEVEL_ARCHITECTURE.md | DONE (added docs/modules/README.md reference) |
| 4.3 | Create docs/modules/README.md index | DONE (comprehensive module index) |
| 4.4 | Verify all module AGENTS.md files | DEFERRED (existing files adequate) |
---
## Merge Strategy
When merging existing documentation with current module state:
### Step 1: Audit Current Code
- Read the module's main project files
- Identify all sub-projects and their purposes
- Document external dependencies
- Capture API contracts and data models
### Step 2: Preserve Existing Content
- Keep operational docs (runbooks, operations/)
- Keep API docs (api/)
- Keep design docs (design/)
- Integrate into architecture.md where appropriate
### Step 3: Reconcile Differences
- If code has evolved past docs, update docs to match code
- If docs describe planned features, mark as "Roadmap"
- Document any deprecated functionality
### Step 4: Validate
- Run through template checklist
- Ensure all sections are populated
- Cross-reference with related modules
- Update module's AGENTS.md if needed
---
## Decisions & Risks
| ID | Decision/Risk | Status |
|----|---------------|--------|
| D1 | Use kebab-case for docs/modules folder names | DECIDED |
| D2 | Feedser is now a library consumed by Concelier | NOTED |
| D3 | Notifier/Notify relationship | CLARIFIED: Notifier=host, Notify=toolkit (per 2025-11-02 module boundary) |
| D4 | evidence vs evidence-locker | CLARIFIED: evidence=cross-cutting concept, evidence-locker=src module |
| D5 | ui vs web | CLARIFIED: both document src/Web/, ui=comprehensive, web=triage-focused |
| D6 | benchmark vs Bench | CLARIFIED: benchmark=competitive accuracy, Bench=performance benchmarks |
| R1 | Some modules may have minimal code (stubs) | MONITOR |
---
## Execution Log
| Date | Action | By |
|------|--------|----|
| 2025-12-28 | Created gap analysis and plan | Claude |
| 2025-12-28 | Completed Phase 1: Created 7 architecture.md files | Claude |
| 2025-12-28 | Completed Phase 2: Created 6 architecture.md files, skipped 2 minimal modules | Claude |
| 2025-12-28 | Completed Phase 3: Resolved 8 documentation ambiguities | Claude |
| 2025-12-28 | Completed Phase 4: Updated CLAUDE.md, created module index, updated HIGH_LEVEL_ARCHITECTURE | Claude |
---
## Delivery Tracker
| Deliverable | Status | Notes |
|-------------|--------|-------|
| Gap analysis complete | DONE | See above |
| Template standard defined | DONE | See above |
| Phase 1 architecture.md files | DONE | 7 modules completed |
| Phase 2 architecture.md files | DONE | 6 completed, 2 skipped (minimal) |
| Phase 3 cleanup | DONE | 8 tasks completed |
| Phase 4 cross-references | DONE | 3 completed, 1 deferred |