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:
2026-04-26 06:38:52 +00:00
parent bac335274d
commit bde1cc4e70
16 changed files with 1264 additions and 748 deletions

View 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.