glm-5.1
bde1cc4e70
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
1.1 KiB
1.1 KiB
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-bis 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.