alkdev/taskgraph_ts
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix critical architecture review issues

Browse Source 
Critical fixes:
- Rename qualityDegradation → qualityRetention across all docs
  (semantically inverted: 0.9 meant 90% quality RETAINED, not 90%
  degradation). Updated schemas, graph-model, cost-benefit, ADRs.
- Add TaskInput → TaskGraphNodeAttributes transformation section
  to graph-model.md, documenting how Nullable(Optional) input fields
  map to Optional graph attributes
- Fix DuplicateEdgeError fields: source/target → prerequisite/dependent
  to match the established edge direction convention
- Fix resolveDefaults signature: Partial<TaskGraphNodeAttributes>
  → Partial<...> & Pick<TaskGraphNodeAttributes, 'name'> to
  require the name field
- Move Nullable helper definition before its first use in schemas.md
- Fix 'construction never throws' contradiction: rephrase to
  'construction enforces uniqueness, not data quality'
- Define all 6 enum value sets in schemas.md (previously only
  TaskScope and TaskRisk were explicit)
- Add EvConfig parameter table with defaults and semantics
- Document WorkflowCostOptions.limit parameter
- Add construction error handling table to graph-model.md
- Add graph.raw mutation safety warning to api-surface.md
- Update build-distribution.md error class list to include
  DuplicateNodeError and DuplicateEdgeError
This commit is contained in:
glm-5.1
2026-04-26 09:13:14 +00:00
parent 13d55b981e
commit 4244c054b7
11 changed files with 113 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/architecture/decisions/004-workflow-cost-dag-propagation.md
View File

@@ -8,7 +8,7 @@ The Rust CLI computes expected value per-task independently — no upstream qual
## Decision
**DAG-propagation is the default mode.** The independent model is a degenerate case accessible via `propagationMode: 'independent'` or `defaultQualityDegradation: 0`.
**DAG-propagation is the default mode.** The independent model is a degenerate case accessible via `propagationMode: 'independent'` or `defaultQualityRetention: 1.0`.
## Consequences
@@ -16,12 +16,12 @@ The Rust CLI computes expected value per-task independently — no upstream qual
- More accurate cost estimates — captures the structural reality that upstream failures multiply downstream damage
- Per-task output includes both `pIntrinsic` and `pEffective` so consumers can see the degradation effect
- The independent model is still available as an opt-in degenerate case
- Per-edge `qualityDegradation` allows fine-grained modeling of how much each dependency bleeds failure
- Per-edge `qualityRetention` allows fine-grained modeling of how much quality is preserved through each dependency
### Negative
- More complex implementation than simple sum
- Results differ from the Rust CLI — consumers migrating from CLI to library will see different numbers
- Requires `qualityDegradation` per edge (default 0.9) which adds a concept the Rust CLI didn't have
- Requires `qualityRetention` per edge (default 0.9) which adds a concept the Rust CLI didn't have
### Mitigation

4
docs/architecture/decisions/005-no-depth-escalation-v1.md
View File

@@ -15,7 +15,7 @@ In the DAG-propagation model, each hop compounds another `<1.0` factor. This imp
### Positive
- No double-counting of depth effects
- Simpler model to explain, implement, and debug
- Architecture supports future depth-escalation via per-edge `qualityDegradation` adjustments or `risk` categorical escalation without API changes
- Architecture supports future depth-escalation via per-edge `qualityRetention` adjustments or `risk` categorical escalation without API changes
### Negative
- May underestimate cost for very deep dependency chains where risk genuinely escalates with depth
@@ -23,4 +23,4 @@ In the DAG-propagation model, each hop compounds another `<1.0` factor. This imp
### Future
If empirical data from actual task outcomes shows that depth-escalation is needed, it can be added without API changes — either by adjusting `qualityDegradation` per depth, or by escalating the `risk` categorical. This is a calibration question, not an architecture question.
If empirical data from actual task outcomes shows that depth-escalation is needed, it can be added without API changes — either by adjusting `qualityRetention` per depth, or by escalating the `risk` categorical. This is a calibration question, not an architecture question.