Explores the diff-based approach (TypeBox Value.Diff → graphology mutation
mapping) as an alternative to rebuild-on-change. Key findings:
- The diff must happen at the graph level, not the source level, because
TaskInput.dependsOn doesn't directly map to edge mutations
- graphology's import(merge=true) handles merges but not deletions
- The real win is reactivity (fine-grained event notifications), not performance
- For <200 node graphs, rebuild is always sub-millisecond
- A hybrid approach (diff for attribute-only changes, rebuild for structural
changes) is possible but adds significant complexity
Decision: defer to v2. ADR-002 (rebuild) stands. The exploration is preserved
for future reference.
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
