Add architecture review findings and address documentation issues

Review of all ADR documents (001-007) and peripheral architecture docs identified 3 critical, 10 warning, and 7 suggestion issues. Addressed in this commit: - W-1: Add draft qualifier to ADR-002 reference to incremental exploration - W-2: Add Alternatives Considered section to ADR-001 - W-3: Add Document Lifecycle section to README.md (draft/stable/deprecated) - W-4: Clarify includeCompleted semantics (only 'completed' status triggers exclusion) - W-5: Document file I/O runtime constraints in frontmatter.md - W-6: Add ADR reference to architecture.md redirect - W-7: Verify CVE-2025-64718 (confirmed real, improved description) - W-9: Convert workspace-absolute paths to relative/monorepo references - S-7: Add future ADR-008 note to incremental-update-exploration.md Critical issues (C-1, C-2, C-3) and remaining warnings (W-8, W-10, S-4, S-5) were addressed by a parallel agent in a prior commit. All 16 review tasks created and resolved.
2026-04-26 09:41:05 +00:00
parent 4244c054b7
commit e592caed57
23 changed files with 652 additions and 17 deletions
--- a/tasks/architecture/c-1-construction-error-policy.md
+++ b/tasks/architecture/c-1-construction-error-policy.md
@@ -0,0 +1,25 @@
+---
+id: architecture/c-1-construction-error-policy
+name: Fix construction error policy contradiction
+status: completed
+depends_on: []
+created: 2026-04-26T09:10:18.462977719Z
+modified: 2026-04-26T09:10:18.462978343Z
+scope: narrow
+risk: high
+---
+
+# Description
+
+**Review ref**: C-1 (Critical)
+**Files affected**: `docs/architecture/errors-validation.md`, `docs/architecture/api-surface.md`
+
+`errors-validation.md` line 119 states "Construction never throws" but then lists `DuplicateNodeError` and `DuplicateEdgeError` as exceptions. `api-surface.md` line 60 documents `addTask` as throwing `DuplicateNodeError`. These contradict each other.
+
+Resolve one of two ways:
+1. **Preferred**: Replace "Construction never throws" with "Construction throws only for precondition violations (duplicate IDs), not for data validation issues." Make the exception explicit rather than contradicting the principle.
+2. Make `addTask`/`addDependency` idempotent (no-op on duplicate) so the principle holds, with `validate()` as the path to detect duplicates.
+
+Also update `api-surface.md` to be consistent with whichever path is chosen.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` C-1
--- a/tasks/architecture/c-2-qualitydegradation-naming.md
+++ b/tasks/architecture/c-2-qualitydegradation-naming.md
@@ -0,0 +1,26 @@
+---
+id: architecture/c-2-qualitydegradation-naming
+name: Fix qualityDegradation semantic inversion
+status: completed
+depends_on: []
+created: 2026-04-26T09:10:23.809702955Z
+modified: 2026-04-26T09:10:23.809703479Z
+scope: narrow
+risk: high
+---
+
+# Description
+
+**Review ref**: C-2 (Critical)
+**Files affected**: `docs/architecture/schemas.md`, `docs/architecture/cost-benefit.md`
+
+The field `qualityDegradation` is described as "how much upstream failure bleeds through" with "0.0 = no propagation, 1.0 = full propagation." But the propagation formula in cost-benefit.md uses `(1 - qualityDegradation)`, meaning 0.9 = 90% quality retained (low bleeding), not 90% degradation. The name and description are semantically inverted.
+
+Resolve one of three ways:
+1. **Preferred**: Rename field to `qualityRetention` (0.9 = 90% quality retained, high retention, low bleeding).
+2. Invert the semantics so high values = high degradation (use `qualityDegradation` directly in formula, not `1 - qualityDegradation`), and change default from 0.9 to 0.1.
+3. Keep the name but add an explicit "Note on naming" section documenting the inversion: "Despite the name, `qualityDegradation` represents quality *retention*."
+
+This must be decided before implementation because it affects the schema, the propagation formula, the DependencyEdge default, and all consumer code.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` C-2
--- a/tasks/architecture/c-3-nullable-helper.md
+++ b/tasks/architecture/c-3-nullable-helper.md
@@ -0,0 +1,21 @@
+---
+id: architecture/c-3-nullable-helper
+name: Move Nullable helper definition before first use in schemas.md
+status: completed
+depends_on: []
+created: 2026-04-26T09:10:33.686014464Z
+modified: 2026-04-26T09:10:33.686014969Z
+scope: narrow
+risk: high
+---
+
+# Description
+
+**Review ref**: C-3 (Critical)
+**Files affected**: `docs/architecture/schemas.md`
+
+The `Nullable` helper is used extensively in the `TaskInput` schema (lines 54–63) but only defined at line 219 in the `ResolvedTaskAttributes` section. An implementer reading top-down encounters `Nullable` without understanding what it does. Also unclear whether `Nullable` is from `@alkdev/typebox` or defined locally.
+
+Add a "Shared Schema Utilities" section near the top of `schemas.md` (before `TaskInput`) that defines `Nullable` and its behavior. Or at minimum add a forward reference: "see Shared Schema Utilities below for the `Nullable` helper" at first use.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` C-3
--- a/tasks/architecture/s-4-error-classes-in-project-structure.md
+++ b/tasks/architecture/s-4-error-classes-in-project-structure.md
@@ -0,0 +1,22 @@
+---
+id: architecture/s-4-error-classes-in-project-structure
+name: Add DuplicateNodeError and DuplicateEdgeError to build-distribution.md error listing
+status: completed
+depends_on:
+  - architecture/c-1-construction-error-policy
+created: 2026-04-26T09:11:08.034858853Z
+modified: 2026-04-26T09:11:08.034859401Z
+scope: narrow
+risk: low
+---
+
+# Description
+
+**Review ref**: S-4 (Suggestion)
+**Files affected**: `docs/architecture/build-distribution.md`
+
+The error directory listing in the project structure (line 54) shows `TaskgraphError, TaskNotFoundError, CircularDependencyError, InvalidInputError` but omits `DuplicateNodeError` and `DuplicateEdgeError` which are defined in `errors-validation.md`. Add the missing error classes to the comment.
+
+Depends on C-1 (construction error policy) — if we resolve that DuplicateNodeError/DuplicateEdgeError remain as thrown errors, they must appear in this listing.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` S-4
--- a/tasks/architecture/s-5-raw-mutation-safety.md
+++ b/tasks/architecture/s-5-raw-mutation-safety.md
@@ -0,0 +1,19 @@
+---
+id: architecture/s-5-raw-mutation-safety
+name: Document graph.raw mutation safety contract
+status: completed
+depends_on: []
+created: 2026-04-26T09:11:09.375058745Z
+modified: 2026-04-26T09:11:09.375059259Z
+scope: narrow
+risk: medium
+---
+
+# Description
+
+**Review ref**: S-5 (Suggestion)
+**Files affected**: `docs/architecture/api-surface.md`, `docs/architecture/graph-model.md`
+
+Consumers can access the underlying graphology instance via `graph.raw`, but mutations made directly bypass TaskGraph invariants (deterministic edge keys from ADR-006, no-parallel-edges from ADR-007). Add a warning to api-surface.md and graph-model.md documenting that direct mutation of `graph.raw` can break TaskGraph invariants.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` S-5
--- a/tasks/architecture/s-7-incremental-adr-note.md
+++ b/tasks/architecture/s-7-incremental-adr-note.md
@@ -0,0 +1,19 @@
+---
+id: architecture/s-7-incremental-adr-note
+name: Add note that incremental-update-exploration may become ADR-008
+status: completed
+depends_on: []
+created: 2026-04-26T09:11:18.351562758Z
+modified: 2026-04-26T09:11:18.351563369Z
+scope: narrow
+risk: low
+---
+
+# Description
+
+**Review ref**: S-7 (Suggestion)
+**Files affected**: `docs/architecture/incremental-update-exploration.md`
+
+The incremental update exploration document is a companion to ADR-002 but has no ADR number. When it reaches a decision (either "adopt incremental updates" or "confirmed: not for v1"), it should become ADR-008. Add a note at the top or bottom: "Status note: If this exploration leads to a decision, it will become ADR-008."
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` S-7
--- a/tasks/architecture/w-1-adr2-qualification.md
+++ b/tasks/architecture/w-1-adr2-qualification.md
@@ -0,0 +1,19 @@
+---
+id: architecture/w-1-adr2-qualification
+name: Add draft qualifier to ADR-002 incremental exploration reference
+status: completed
+depends_on: []
+created: 2026-04-26T09:10:38.066892613Z
+modified: 2026-04-26T09:10:38.066893175Z
+scope: narrow
+risk: medium
+---
+
+# Description
+
+**Review ref**: W-1 (Warning)
+**Files affected**: `docs/architecture/decisions/002-rebuild-vs-incremental.md`
+
+ADR-002's mitigation section references incremental-update-exploration.md as if it's a completed exploration, but that doc is explicitly "Draft exploration — not yet a decision." Add a qualifier like: "An incremental update architecture has been explored (draft, not yet a decision) in …"
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` W-1
--- a/tasks/architecture/w-10-edge-construction-semantics.md
+++ b/tasks/architecture/w-10-edge-construction-semantics.md
@@ -0,0 +1,28 @@
+---
+id: architecture/w-10-edge-construction-semantics
+name: Document fromTasks/fromRecords edge construction and validation semantics
+status: completed
+depends_on:
+  - architecture/c-1-construction-error-policy
+created: 2026-04-26T09:11:03.412470108Z
+modified: 2026-04-26T09:11:03.412470586Z
+scope: narrow
+risk: medium
+---
+
+# Description
+
+**Review ref**: W-10 (Warning)
+**Files affected**: `docs/architecture/graph-model.md`, `docs/architecture/api-surface.md`, `docs/architecture/errors-validation.md`
+
+Missing documentation for `fromTasks`/`fromRecords` edge construction:
+- Whether `fromRecords` requires edges to reference tasks in the same `tasks` array
+- What happens with dangling edge references (validation error? silently dropped?)
+- Whether edge order matters in the `edges` array
+- Whether `fromTasks`/`fromRecords` throw `DuplicateEdgeError` or silently deduplicate
+
+Add a "Construction Semantics" section to graph-model.md specifying these behaviors.
+
+Depends on C-1 (construction error policy) — the resolution of that issue determines whether duplicate edges are errors or idempotent no-ops.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` W-10
--- a/tasks/architecture/w-2-adr1-alternatives.md
+++ b/tasks/architecture/w-2-adr1-alternatives.md
@@ -0,0 +1,19 @@
+---
+id: architecture/w-2-adr1-alternatives
+name: Add Alternatives Considered section to ADR-001
+status: completed
+depends_on: []
+created: 2026-04-26T09:10:42.466925749Z
+modified: 2026-04-26T09:10:42.466926257Z
+scope: narrow
+risk: medium
+---
+
+# Description
+
+**Review ref**: W-2 (Warning)
+**Files affected**: `docs/architecture/decisions/001-pivot-to-typescript-graphology.md`
+
+ADR-001 is the foundational decision but lacks an explicit "Alternatives Considered" section. Add structured alternatives: NAPI/Rust (original plan — build complexity), WASM-compiled Rust (reintroduces Rust toolchain), manual adjacency map (no DAG algorithms), D3/other JS graph libs (graphology already in tree).
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` W-2
--- a/tasks/architecture/w-3-doc-lifecycle-protocol.md
+++ b/tasks/architecture/w-3-doc-lifecycle-protocol.md
@@ -0,0 +1,19 @@
+---
+id: architecture/w-3-doc-lifecycle-protocol
+name: Define document lifecycle states and transition criteria
+status: completed
+depends_on: []
+created: 2026-04-26T09:10:49.101915726Z
+modified: 2026-04-26T09:10:49.101916156Z
+scope: narrow
+risk: low
+---
+
+# Description
+
+**Review ref**: W-3 (Warning)
+**Files affected**: `docs/architecture/frontmatter.md` or `docs/architecture/README.md`
+
+All peripheral docs have `status: draft` but there's no protocol for when they transition to stable, or what "draft" means. Define document lifecycle states (draft → stable → deprecated) and transition criteria in frontmatter.md or a governance section in README.md.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` W-3
--- a/tasks/architecture/w-4-taskstatus-enum-values.md
+++ b/tasks/architecture/w-4-taskstatus-enum-values.md
@@ -0,0 +1,21 @@
+---
+id: architecture/w-4-taskstatus-enum-values
+name: Define TaskStatus enum values and completed semantics
+status: completed
+depends_on: []
+created: 2026-04-26T09:10:49.967999614Z
+modified: 2026-04-26T09:10:49.968000036Z
+scope: narrow
+risk: medium
+---
+
+# Description
+
+**Review ref**: W-4 (Warning)
+**Files affected**: `docs/architecture/schemas.md`, `docs/architecture/cost-benefit.md`
+
+The `TaskStatusEnum` values are never explicitly listed — just "same pattern for TaskImpact, TaskLevel, TaskPriority, TaskStatus." Also, `cost-benefit.md` references `includeCompleted: false` but doesn't define which status value(s) constitute "completed."
+
+Define TaskStatusEnum values explicitly. Specify which status(es) the `includeCompleted` option treats as "completed." This blocks implementation of both the schema and the workflowCost function.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` W-4
--- a/tasks/architecture/w-5-fileio-runtime-portability.md
+++ b/tasks/architecture/w-5-fileio-runtime-portability.md
@@ -0,0 +1,22 @@
+---
+id: architecture/w-5-fileio-runtime-portability
+name: Document file I/O function runtime constraints and export path
+status: completed
+depends_on:
+  - architecture/w-4-taskstatus-enum-values
+created: 2026-04-26T09:10:51.293468161Z
+modified: 2026-04-26T09:10:51.293468694Z
+scope: narrow
+risk: medium
+---
+
+# Description
+
+**Review ref**: W-5 (Warning)
+**Files affected**: `docs/architecture/frontmatter.md`, `docs/architecture/build-distribution.md`
+
+`parseTaskFile` and `parseTaskDirectory` are async and use Node.js `fs` APIs, but ADR-001 and build-distribution.md state the library works in Node, Deno, and Bun. Document whether these I/O functions are available in all runtimes. Consider a separate export path (e.g., `@alkdev/taskgraph/fs`) for file I/O to avoid bundling Node APIs into Deno/Bun consumers.
+
+Depends on W-4 (TaskStatus definition) only if the file I/O discussion touches file-level defaults for status fields.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` W-5
--- a/tasks/architecture/w-6-redirect-adr-links.md
+++ b/tasks/architecture/w-6-redirect-adr-links.md
@@ -0,0 +1,19 @@
+---
+id: architecture/w-6-redirect-adr-links
+name: Add ADR references to architecture.md redirect file
+status: completed
+depends_on: []
+created: 2026-04-26T09:10:55.710888653Z
+modified: 2026-04-26T09:10:55.710889173Z
+scope: narrow
+risk: low
+---
+
+# Description
+
+**Review ref**: W-6 (Warning)
+**Files affected**: `docs/architecture.md`
+
+The redirect file lists modular documents but doesn't mention ADRs under `docs/architecture/decisions/`. Add a line pointing to the ADR directory or to the ADR table in README.md.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` W-6
--- a/tasks/architecture/w-7-cve-number-verify.md
+++ b/tasks/architecture/w-7-cve-number-verify.md
@@ -0,0 +1,21 @@
+---
+id: architecture/w-7-cve-number-verify
+name: Verify js-yaml CVE number in frontmatter.md
+status: completed
+depends_on: []
+created: 2026-04-26T09:10:57.556575363Z
+modified: 2026-04-26T09:10:57.556575883Z
+scope: narrow
+risk: medium
+---
+
+# Description
+
+**Review ref**: W-7 (Warning)
+**Files affected**: `docs/architecture/frontmatter.md`
+
+The frontmatter doc references "CVE-2025-64718" for js-yaml prototype pollution. This CVE number appears incorrect — the sequence number is unusually high and no matching CVE was found. An incorrect CVE undermines the supply-chain security argument.
+
+Verify the actual CVE number for js-yaml prototype pollution vulnerability. If the number can't be confirmed, replace with "referenced in npm audit database" or link to the npm advisory directly.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` W-7
--- a/tasks/architecture/w-8-limit-param-docs.md
+++ b/tasks/architecture/w-8-limit-param-docs.md
@@ -0,0 +1,22 @@
+---
+id: architecture/w-8-limit-param-docs
+name: Document WorkflowCostOptions.limit semantics
+status: completed
+depends_on:
+  - architecture/w-4-taskstatus-enum-values
+created: 2026-04-26T09:10:59.676682205Z
+modified: 2026-04-26T09:10:59.676682713Z
+scope: narrow
+risk: medium
+---
+
+# Description
+
+**Review ref**: W-8 (Warning)
+**Files affected**: `docs/architecture/api-surface.md`
+
+`WorkflowCostOptions` includes `limit?: number` with no documentation of what this parameter constrains or its default behavior. Document what `limit` does (number of tasks in result? max depth?) and its behavior when omitted.
+
+Depends on W-4 (TaskStatus definition) if `limit` interacts with `includeCompleted` filtering semantics.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` W-8
--- a/tasks/architecture/w-9-workspace-paths-to-relative.md
+++ b/tasks/architecture/w-9-workspace-paths-to-relative.md
@@ -0,0 +1,21 @@
+---
+id: architecture/w-9-workspace-paths-to-relative
+name: Convert workspace-absolute paths to relative paths in docs
+status: completed
+depends_on: []
+created: 2026-04-26T09:11:01.370744359Z
+modified: 2026-04-26T09:11:01.370744867Z
+scope: moderate
+risk: low
+---
+
+# Description
+
+**Review ref**: W-9 (Warning)
+**Files affected**: `docs/architecture/incremental-update-exploration.md`, `docs/architecture/README.md`
+
+References like `/workspace/@alkdev/typebox/docs/values/diff-patch.md` and `/workspace/@alkimiadev/taskgraph/docs/framework.md` are monorepo-internal absolute paths that won't resolve outside this workspace.
+
+Convert to relative paths from repository root (e.g., `../typebox/docs/...`) or link to published documentation URLs where available. Keep workspace-absolute paths only in a clearly marked "Developer Notes" section.
+
+**Source**: `/docs/reviews/architecture-review-2026-04-26.md` W-9