Decompose monolithic architecture.md into modular docs/architecture/ documents
The 751-line architecture.md violated the SDD process modular documentation target (~500 lines). It also had duplicate TaskGraph class definitions (one monolith, one decomposed) that directly contradicted each other, and embedded consumer-specific tool dispatch mappings that belong in downstream projects. Changes: - Split into 8 focused documents + 7 ADR records + redirect page - Removed the monolithic TaskGraph class (kept only decomposed version) - Moved CLI→plugin dispatch mapping out (belongs in plugin architecture) - Extracted implementation code (frontmatter splitter, findCycles, DAG propagation) into WHAT/WHY descriptions per architect role spec - Added proper ADR format for all resolved design decisions - Fixed review issues: C_fail mapping, DuplicateNodeError/DuplicateEdgeError types, ValidationError/GraphValidationError definitions, mutation error handling contract, enum naming convention, validation timing clarification
This commit is contained in:
26
docs/architecture/decisions/006-deterministic-edge-keys.md
Normal file
26
docs/architecture/decisions/006-deterministic-edge-keys.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# ADR-006: Deterministic edge keys via addEdgeWithKey
|
||||
|
||||
**Status**: Accepted
|
||||
|
||||
## Context
|
||||
|
||||
graphology's default `addEdge(source, target)` generates random edge keys (e.g., `ge8kq2`). This makes debugging harder and adds overhead from key generation. For our use case, each source→target pair has at most one edge (no parallel edges in a DAG dependency graph).
|
||||
|
||||
## Decision
|
||||
|
||||
Use `addEdgeWithKey` with deterministic keys in the format `${source}->${target}` (e.g., `task-a->task-b`). This produces readable, debuggable edge identifiers and skips graphology's key generation overhead.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- Debuggable edge identifiers — `task-a->task-b` is immediately understandable
|
||||
- No random key generation overhead
|
||||
- Deterministic — exporting and re-importing produces the same graph
|
||||
|
||||
### Negative
|
||||
- Constraint enforced: no parallel edges between the same node pair
|
||||
- Key format collision if task IDs contain `->` (extremely unlikely with kebab-case slugs)
|
||||
|
||||
### Mitigation
|
||||
|
||||
Duplicate dependency declarations (same source→target pair declared twice) are a validation error, not a valid use case. The constraint is correct for DAG dependency graphs.
|
||||
Reference in New Issue
Block a user