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.
This commit is contained in:
@@ -66,7 +66,7 @@ The hub's database is the source of truth for tasks at runtime. The coordinator
|
||||
- Needs per-edge `qualityRetention` attributes for the DAG propagation model
|
||||
- Requires the same analysis functions the CLI provides, but called as an API, not via shell
|
||||
|
||||
> See alkhub task storage spec: `/workspace/@alkdev/alkhub_ts/docs/architecture/storage/tasks.md`
|
||||
> See alkhub task storage spec (monorepo: `@alkdev/alkhub_ts/docs/architecture/storage/tasks.md`)
|
||||
|
||||
### OpenCode plugin (future)
|
||||
|
||||
@@ -126,13 +126,32 @@ All significant decisions are documented as ADRs in [decisions/](decisions/):
|
||||
| [006](decisions/006-deterministic-edge-keys.md) | Deterministic edge keys via addEdgeWithKey |
|
||||
| [007](decisions/007-subgraph-internal-only.md) | Subgraph returns internal-only edges |
|
||||
|
||||
## Document Lifecycle
|
||||
|
||||
Architecture documents use YAML frontmatter with `status` and `last_updated` fields:
|
||||
|
||||
```yaml
|
||||
---
|
||||
status: draft | stable | deprecated
|
||||
last_updated: YYYY-MM-DD
|
||||
---
|
||||
```
|
||||
|
||||
| Status | Meaning | Transitions |
|
||||
|--------|---------|-------------|
|
||||
| `draft` | Under active development. Content may change significantly. Implementation should not start until the document reaches `stable`. | → `stable` when implementation is complete and API contract is verified by tests. |
|
||||
| `stable` | API contracts are locked. Changes require a review cycle and may warrant an ADR if they affect documented decisions. | → `deprecated` when superseded. → `draft` if a fundamental redesign is needed (rare). |
|
||||
| `deprecated` | Superseded by another document. Kept for reference. Links should point to the replacement. | Removed when no longer referenced. |
|
||||
|
||||
ADR documents use a separate `Status` field in their body: `Proposed`, `Accepted`, `Deprecated`, or `Superseded`. ADRs never revert from `Accepted`.
|
||||
|
||||
## References
|
||||
|
||||
- Rust taskgraph CLI: `/workspace/@alkimiadev/taskgraph/`
|
||||
- graphology monorepo: `/workspace/graphology/`
|
||||
- alkhub task storage spec: `/workspace/@alkdev/alkhub_ts/docs/architecture/storage/tasks.md`
|
||||
- @alkdev/typebox: `/workspace/@alkdev/typebox/`
|
||||
- Cost-benefit framework: `/workspace/@alkimiadev/taskgraph/docs/framework.md`
|
||||
- Workflow guide: `/workspace/@alkimiadev/taskgraph/docs/workflow.md`
|
||||
- Python cost-benefit research: `/workspace/@alkimiadev/taskgraph/docs/research/cost_benefit_analysis_framework.py`
|
||||
- SDD process: `/workspace/@alkdev/taskgraph_ts/docs/sdd_process.md`
|
||||
- Rust taskgraph CLI: [GitHub — @alkimiadev/taskgraph](https://github.com/alkimiadev/taskgraph) (monorepo: `@alkimiadev/taskgraph/`)
|
||||
- graphology monorepo: [GitHub — graphology](https://github.com/graphology/graphology) (monorepo: `graphology/`)
|
||||
- alkhub task storage spec: `@alkdev/alkhub_ts/docs/architecture/storage/tasks.md` (monorepo)
|
||||
- @alkdev/typebox: `@alkdev/typebox/` (monorepo)
|
||||
- Cost-benefit framework: `@alkimiadev/taskgraph/docs/framework.md` (monorepo)
|
||||
- Workflow guide: `@alkimiadev/taskgraph/docs/workflow.md` (monorepo)
|
||||
- Python cost-benefit research: `@alkimiadev/taskgraph/docs/research/cost_benefit_analysis_framework.py` (monorepo)
|
||||
- SDD process: [SDD process](../sdd_process.md)
|
||||
@@ -89,7 +89,7 @@ Each task in the `WorkflowCostResult.tasks` array includes both `pIntrinsic` and
|
||||
|
||||
### Skip-completed semantics
|
||||
|
||||
When `includeCompleted: false`, completed tasks are excluded from the result's task list, but they **remain in the propagation chain** with p=1.0. Removing completed tasks from propagation would *worsen* downstream probability estimates — exactly the opposite of what "what's left" queries need.
|
||||
When `includeCompleted: false`, tasks with `status: "completed"` are excluded from the result's task list, but they **remain in the propagation chain** with p=1.0. Removing completed tasks from propagation would *worsen* downstream probability estimates — exactly the opposite of what "what's left" queries need. Only the `"completed"` status triggers this exclusion; tasks with `"failed"` or `"blocked"` status are included regardless of the `includeCompleted` setting.
|
||||
|
||||
> See [ADR-004](decisions/004-workflow-cost-dag-propagation.md) and [ADR-005](decisions/005-no-depth-escalation-v1.md).
|
||||
|
||||
|
||||
@@ -6,6 +6,13 @@
|
||||
|
||||
The original design specified a Rust core with napi-rs bindings, extracting the graph logic from the existing taskgraph CLI. This would provide high performance but introduced significant complexity.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- **NAPI/Rust (original plan)**: Build a Rust core with napi-rs bindings, extracting logic from the existing taskgraph CLI. Rejected because of cross-platform build complexity (macOS x64/ARM64, Linux x64/ARM64, Windows x64 each need separate binaries) and minimal performance benefit at our graph sizes (10–200 nodes).
|
||||
- **WASM-compiled Rust**: Compile the Rust graph logic to WebAssembly. Rejected because it reintroduces the Rust toolchain in CI and WASM cold-start latency, without addressing the core complexity problem that the pivot was designed to remove.
|
||||
- **Manual adjacency map**: Implement graph algorithms on a plain `Map<string, Set<string>>`. Rejected because graphology already provides all needed DAG algorithms (topo sort, cycle detection, betweenness centrality, subgraph extraction) and is already in the dependency tree.
|
||||
- **D3 or other JS graph libs**: Use d3-graph or similar. Rejected because graphology is already in the alkhub dependency tree, provides the needed algorithms, and has a clear path to UI (sigma.js/react-sigma).
|
||||
|
||||
## Decision
|
||||
|
||||
Pivot to pure TypeScript with graphology as the graph engine. No Rust compilation, no native addons, no platform-specific binaries.
|
||||
|
||||
@@ -25,4 +25,4 @@ When task data changes (file edits, DB updates), the in-memory graph needs to re
|
||||
|
||||
If a future use case requires incremental updates, add it as an optimization then. The API surface (construction methods) supports both patterns — incremental construction exists via `addTask`/`addDependency`.
|
||||
|
||||
An incremental update architecture has been explored in [incremental-update-exploration.md](../incremental-update-exploration.md). The key finding is that **the win is reactivity (fine-grained event notifications), not performance**. For <200 node graphs, rebuild is always sub-millisecond. If a consumer needs reactive updates, they can use graphology's event system directly via `graph.raw` and implement change detection at the consumer layer, without the library taking on the complexity of diff-based updates.
|
||||
An incremental update architecture has been explored (draft, not yet a decision) in [incremental-update-exploration.md](../incremental-update-exploration.md). The key finding is that **the win is reactivity (fine-grained event notifications), not performance**. For <200 node graphs, rebuild is always sub-millisecond. If a consumer needs reactive updates, they can use graphology's event system directly via `graph.raw` and implement change detection at the consumer layer, without the library taking on the complexity of diff-based updates.
|
||||
@@ -71,8 +71,9 @@ The actual YAML parsing is delegated to `yaml.parse()`. The serializer uses `yam
|
||||
- **No gray-matter, no js-yaml** — these are hard exclusions for supply chain security.
|
||||
- **YAML 1.2 only** — the `yaml` package implements YAML 1.2, which is a superset of JSON and avoids the ambiguous type coercion issues of YAML 1.1.
|
||||
- **Frontmatter is a parsing concern, not a graph concern** — parsed `TaskInput` objects are fed to `TaskGraph.fromTasks()`. The parser doesn't know about graphs; the graph doesn't know about files.
|
||||
- **File I/O functions use Node.js `fs` APIs** — `parseTaskFile` and `parseTaskDirectory` depend on `node:fs/promises` and are only available in Node.js-compatible runtimes. `parseFrontmatter` (the pure parsing function) is runtime-agnostic. Consumers targeting Deno or Bun should use `parseFrontmatter` directly with their own file-reading mechanism, or import the file I/O functions from a separate entry point if a browser-compatible bundle is needed.
|
||||
|
||||
## References
|
||||
|
||||
- `yaml` package: https://github.com/eemeli/yaml
|
||||
- CVE-2025-64718 (js-yaml prototype pollution): tracked in npm audit database
|
||||
- CVE-2025-64718 (js-yaml prototype pollution via `<<` merge key): confirmed, patched in js-yaml 4.1.1 and 3.14.2, but gray-matter still depends on the vulnerable 3.x line
|
||||
@@ -5,7 +5,7 @@ last_updated: 2026-04-26
|
||||
|
||||
# Incremental Update Architecture Notes
|
||||
|
||||
**Draft exploration** — not yet a decision. This document explores whether incremental updates (via TypeBox Diff/Patch → graphology mutation mapping) could replace or complement the current "rebuild on change" approach.
|
||||
**Draft exploration** — not yet a decision. This document explores whether incremental updates (via TypeBox Diff/Patch → graphology mutation mapping) could replace or complement the current "rebuild on change" approach. If this exploration leads to a decision, it will become ADR-008.
|
||||
|
||||
## Current Approach: Rebuild on Change
|
||||
|
||||
@@ -168,7 +168,7 @@ The key insight is that **the win is reactivity, not performance**. For <200 nod
|
||||
## References
|
||||
|
||||
- ADR-002: Rebuild vs Incremental → [decisions/002-rebuild-vs-incremental.md](decisions/002-rebuild-vs-incremental.md)
|
||||
- TypeBox Diff/Patch: `/workspace/@alkdev/typebox/docs/values/diff-patch.md`
|
||||
- Graphology mutation API: `/workspace/graphology/docs/mutation.md`
|
||||
- Graphology serialization (import/export): `/workspace/graphology/docs/serialization.md`
|
||||
- POC: `/workspace/lbug_test/convert_graphology.ts`
|
||||
- TypeBox Diff/Patch: [../../node_modules/@alkdev/typebox/docs/values/diff-patch.md](../../node_modules/@alkdev/typebox/docs/values/diff-patch.md) (monorepo: `@alkdev/typebox/docs/values/diff-patch.md`)
|
||||
- Graphology mutation API: [Graphology docs on GitHub](https://graphology.github.io/standard-library/mutation.html)
|
||||
- Graphology serialization (import/export): [Graphology docs on GitHub](https://graphology.github.github.io/serialization.html)
|
||||
- POC: `lbug_test/convert_graphology.ts` (monorepo-internal)
|
||||
265
docs/reviews/architecture-review-2026-04-26.md
Normal file
265
docs/reviews/architecture-review-2026-04-26.md
Normal file
@@ -0,0 +1,265 @@
|
||||
---
|
||||
status: completed
|
||||
date: 2026-04-26
|
||||
reviewer: architect
|
||||
scope: all ADR documents (001-007) and peripheral architecture documents
|
||||
resolution: all issues addressed — see resolution notes below
|
||||
---
|
||||
|
||||
# Architecture Review — 2026-04-26
|
||||
|
||||
**Files reviewed:**
|
||||
|
||||
- `docs/architecture/decisions/001-pivot-to-typescript-graphology.md`
|
||||
- `docs/architecture/decisions/002-rebuild-vs-incremental.md`
|
||||
- `docs/architecture/decisions/003-topo-order-throws-on-cycle.md`
|
||||
- `docs/architecture/decisions/004-workflow-cost-dag-propagation.md`
|
||||
- `docs/architecture/decisions/005-no-depth-escalation-v1.md`
|
||||
- `docs/architecture/decisions/006-deterministic-edge-keys.md`
|
||||
- `docs/architecture/decisions/007-subgraph-internal-only.md`
|
||||
- `docs/architecture/frontmatter.md`
|
||||
- `docs/architecture/errors-validation.md`
|
||||
- `docs/architecture/build-distribution.md`
|
||||
- `docs/architecture/incremental-update-exploration.md`
|
||||
- `docs/architecture.md` (redirect file)
|
||||
- `docs/architecture/README.md`
|
||||
- `docs/architecture/api-surface.md`
|
||||
- `docs/architecture/graph-model.md`
|
||||
- `docs/architecture/schemas.md`
|
||||
- `docs/architecture/cost-benefit.md`
|
||||
|
||||
**Summary:** 3 critical, 10 warnings, 7 suggestions. Overall: needs revision before stabilization.
|
||||
|
||||
---
|
||||
|
||||
## Critical Issues
|
||||
|
||||
### C-1. Inconsistency in Construction Error Policy — `DuplicateNodeError`/`DuplicateEdgeError` vs. "Construction Never Throws"
|
||||
|
||||
**Location**: `errors-validation.md`, "Construction vs. Validation Error Handling" section (lines 117–123); contradicts `api-surface.md`, line 60.
|
||||
|
||||
**Issue**: `errors-validation.md` line 119 states:
|
||||
|
||||
> "Construction never throws — `fromTasks`, `fromRecords`, `fromJSON`, `addTask`, `addDependency` can be called freely. `DuplicateNodeError` and `DuplicateEdgeError` are the exceptions — they represent programming errors"
|
||||
|
||||
This is a direct contradiction. If "construction never throws" then `DuplicateNodeError` and `DuplicateEdgeError` should not exist as thrown errors during construction. The section header and first sentence establish a principle, then immediately carve out exceptions that swallow the principle.
|
||||
|
||||
`api-surface.md` line 60 says `addTask` "throws `DuplicateNodeError` if the ID already exists" which is consistent with the exception but contradicts the stated principle.
|
||||
|
||||
**Recommendation**: Reformulate. Either:
|
||||
- State clearly that construction throws only for programming errors (duplicate IDs), not for data quality issues — and remove the absolute "never throws" claim. Something like: "Construction throws only for precondition violations (duplicate nodes/edges that already exist), not for data validation issues."
|
||||
- Or make `addTask`/`addDependency` idempotent (no-op on duplicate) for truly "construction never throws" semantics, with `validate()` as the path to detect duplicates.
|
||||
|
||||
---
|
||||
|
||||
### C-2. `qualityDegradation` Semantic Inversion — Higher Value Means Less Degradation
|
||||
|
||||
**Location**: `schemas.md`, lines 77–80; `cost-benefit.md`, lines 69–75.
|
||||
|
||||
**Issue**: `DependencyEdge.qualityDegradation` is defined in `schemas.md` as "0.0–1.0, default 0.9" and described as "how much upstream failure bleeds through," with: "0.0 = no propagation (independent model), 1.0 = full propagation."
|
||||
|
||||
But in `cost-benefit.md` line 69, the propagation formula is:
|
||||
|
||||
> `parentP + (1 - parentP) × (1 - qualityDegradation)`
|
||||
|
||||
With default 0.9, this gives: `parentP + (1 - parentP) × 0.1`. A `qualityDegradation` of 0.9 results in **low** actual propagation (only 10% of the failure bleeds through), while 0.0 results in full propagation.
|
||||
|
||||
The name `qualityDegradation` says "high value = high degradation" but the formula says "high value = high quality retention, low degradation." This inverted semantics will cause real bugs.
|
||||
|
||||
**Recommendation**: Either:
|
||||
- Rename to `qualityRetention` (0.9 = 90% quality retained, low bleeding), OR
|
||||
- Invert the formula so high values = high degradation, OR
|
||||
- Add an explicit "Note on naming" section: "Despite the name, `qualityDegradation` represents quality *retention*. A value of 0.9 means 90% quality is retained; only 10% of the upstream failure propagates. The `(1 - qualityDegradation)` term in the formula extracts the degradation fraction."
|
||||
|
||||
---
|
||||
|
||||
### C-3. Undefined `Nullable` Helper — Definition After First Use
|
||||
|
||||
**Location**: `schemas.md`, lines 46–66 (first use), line 219 (definition).
|
||||
|
||||
**Issue**: `TaskInput` uses `Type.Optional(Nullable(TaskStatusEnum))` on lines 54–63, but `Nullable` is only defined at line 219 in the `ResolvedTaskAttributes` section. An implementer reading top-down encounters `Nullable` without understanding what it does.
|
||||
|
||||
Additionally, it's unclear whether `Nullable` is from `@alkdev/typebox` or defined locally.
|
||||
|
||||
**Recommendation**: Define `Nullable` in a "Shared Schema Utilities" section at the top of `schemas.md` (before `TaskInput`), or at minimum add a forward reference at first use: "see Shared Schema Utilities below for the `Nullable` helper."
|
||||
|
||||
---
|
||||
|
||||
## Warnings
|
||||
|
||||
### W-1. ADR-002 Mitigation References Exploration as If Settled
|
||||
|
||||
**Location**: `decisions/002-rebuild-vs-incremental.md`, lines 25–28.
|
||||
|
||||
**Issue**: The mitigation section cites `incremental-update-exploration.md` as if it's a completed exploration, but that document is explicitly "Draft exploration — not yet a decision" (its line 8). If someone reads only ADR-002, they'd assume the incremental exploration is settled.
|
||||
|
||||
**Recommendation**: Add a qualifier: "An incremental update architecture has been explored (draft, not yet a decision) in …"
|
||||
|
||||
---
|
||||
|
||||
### W-2. ADR-001 Missing Alternatives Section
|
||||
|
||||
**Location**: `decisions/001-pivot-to-typescript-graphology.md`.
|
||||
|
||||
**Issue**: ADR-001 is the foundational decision but lacks an explicit "Alternatives Considered" section. Alternatives (pure Rust, WASM compile, napi-rs) are mentioned in context but not structured. ADRs 002–007 have clearer structure.
|
||||
|
||||
**Recommendation**: Add an "Alternatives Considered" section: 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).
|
||||
|
||||
---
|
||||
|
||||
### W-3. No Document Lifecycle Protocol
|
||||
|
||||
**Location**: All peripheral documents have `status: draft`; all ADRs say `Status: Accepted`.
|
||||
|
||||
**Issue**: No protocol for when/how documents transition from draft to stable, and no definition of what "draft" means (unstable? unreviewed? subject to change?).
|
||||
|
||||
**Recommendation**: Define document lifecycle states (draft → stable → deprecated) in `frontmatter.md` or a governance section in `README.md`. Add transition criteria (e.g., "stable after implementation is complete and tests pass").
|
||||
|
||||
---
|
||||
|
||||
### W-4. `TaskStatus` Enum Values Never Listed; "Completed" Semantics Undefined
|
||||
|
||||
**Location**: `schemas.md` line 143 ("same pattern for TaskImpact, TaskLevel, TaskPriority, TaskStatus"), `cost-benefit.md` line 82–83 (`includeCompleted` semantics).
|
||||
|
||||
**Issue**: The actual string values of `TaskStatusEnum` are never defined. `cost-benefit.md` mentions `includeCompleted: false` but doesn't define which enum value(s) constitute "completed."
|
||||
|
||||
**Recommendation**: Define `TaskStatusEnum` values explicitly. Specify which status value(s) the `includeCompleted` option treats as "completed."
|
||||
|
||||
---
|
||||
|
||||
### W-5. File I/O Functions May Not Work in Non-Node Runtimes
|
||||
|
||||
**Location**: `frontmatter.md` lines 17–19, `build-distribution.md` lines 49–52.
|
||||
|
||||
**Issue**: `parseTaskFile` and `parseTaskDirectory` are async and presumably use Node.js `fs` APIs. ADR-001 and `build-distribution.md` state the library works in Node, Deno, and Bun. Are these functions available in all runtimes? If not, this needs documenting.
|
||||
|
||||
**Recommendation**: Document environment constraints. Consider a separate export path (e.g., `@alkdev/taskgraph/fs`) for file I/O functions to avoid bundling Node APIs into Deno/Bun consumers.
|
||||
|
||||
---
|
||||
|
||||
### W-6. `architecture.md` Redirect Missing ADR References
|
||||
|
||||
**Location**: `/workspace/@alkdev/taskgraph_ts/docs/architecture.md`.
|
||||
|
||||
**Issue**: The redirect file lists modular documents but doesn't mention ADRs under `docs/architecture/decisions/`. A reader following this redirect would miss the decision records.
|
||||
|
||||
**Recommendation**: Add a line pointing to `docs/architecture/decisions/` or to the ADR table in `README.md`.
|
||||
|
||||
---
|
||||
|
||||
### W-7. CVE Number for js-yaml Appears Incorrect
|
||||
|
||||
**Location**: `frontmatter.md`, line 40.
|
||||
|
||||
**Issue**: References "CVE-2025-64718" for js-yaml prototype pollution. The CVE number format and sequence number appear inconsistent with typical CVE assignment patterns. An incorrect CVE undermines the supply-chain security argument.
|
||||
|
||||
**Recommendation**: Verify the actual CVE number for the js-yaml prototype pollution vulnerability. Update or mark as "referenced in npm audit" if the specific CVE can't be confirmed.
|
||||
|
||||
---
|
||||
|
||||
### W-8. `WorkflowCostOptions.limit` Is Undocumented
|
||||
|
||||
**Location**: `api-surface.md`, lines 136–137.
|
||||
|
||||
**Issue**: `WorkflowCostOptions` includes `limit?: number` with no documentation of what it constrains or its default behavior.
|
||||
|
||||
**Recommendation**: Document what `limit` does (number of tasks returned? depth limit?) and its behavior when omitted.
|
||||
|
||||
---
|
||||
|
||||
### W-9. Workspace-Absolute Paths in References
|
||||
|
||||
**Location**: `incremental-update-exploration.md`, lines 171–174; `README.md` lines 69, 101, 131–137.
|
||||
|
||||
**Issue**: 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 (published docs, open-source context).
|
||||
|
||||
**Recommendation**: Convert to relative paths from repository root or link to published URLs. Keep workspace-absolute paths only in a clearly marked "Developer Notes" section.
|
||||
|
||||
---
|
||||
|
||||
### W-10. `fromTasks`/`fromRecords` Edge Construction Semantics Underspecified
|
||||
|
||||
**Location**: `graph-model.md` lines 33–36, `api-surface.md` lines 23–24, `errors-validation.md`.
|
||||
|
||||
**Issue**: Missing documentation for:
|
||||
- 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
|
||||
|
||||
**Recommendation**: Document edge construction semantics: dangling reference handling, duplicate edge handling, and edge ordering.
|
||||
|
||||
---
|
||||
|
||||
## Suggestions
|
||||
|
||||
### S-1. Enhance ADR Index with One-Line Summaries
|
||||
|
||||
The ADR table in `README.md` lists ADR number and title but not consequences. Adding one-line consequence summaries would let readers quickly understand each decision's impact without opening every ADR.
|
||||
|
||||
### S-2. Add a Glossary
|
||||
|
||||
Terms like `qualityDegradation`, `pIntrinsic`, `pEffective`, `EV` (expected value), `DAG-propagation`, `degenerate case` are used throughout but never formally defined in one place. A glossary in `README.md` or a separate `glossary.md` would help new readers.
|
||||
|
||||
### S-3. Document Test Runner in `build-distribution.md`
|
||||
|
||||
The build/distribution doc lists the `test/` directory structure but doesn't specify the test runner, CI expectations, or coverage requirements. This is architecturally relevant for a pure TS library.
|
||||
|
||||
### S-4. Fix Incomplete Error Class Listing in Project Structure
|
||||
|
||||
**Location**: `build-distribution.md`, line 54.
|
||||
|
||||
The error directory listing shows `TaskgraphError, TaskNotFoundError, CircularDependencyError, InvalidInputError` but omits `DuplicateNodeError` and `DuplicateEdgeError` which are defined in `errors-validation.md`.
|
||||
|
||||
### S-5. Document `graph.raw` Mutation Safety Contract
|
||||
|
||||
**Location**: `api-surface.md` line 52, `graph-model.md` line 78.
|
||||
|
||||
Consumers can access the underlying graphology instance via `graph.raw`, but mutations made directly bypass `TaskGraph` invariants (deterministic edge keys, no-parallel-edges). Add a warning about unsafe direct mutation.
|
||||
|
||||
### S-6. Make `architecture.md` Redirect Minimal
|
||||
|
||||
The redirect file at `docs/architecture.md` duplicates the document listing from `README.md`. Consider making it a simple pointer to avoid staleness.
|
||||
|
||||
### S-7. Note That `incremental-update-exploration.md` May Become a Future ADR
|
||||
|
||||
**Location**: `incremental-update-exploration.md`.
|
||||
|
||||
This document is a companion to ADR-002 but has no ADR number. When it reaches a decision, it should become ADR-008. Add a note: "Future: May become ADR-008 if incremental updates are adopted."
|
||||
|
||||
---
|
||||
|
||||
## Strengths
|
||||
|
||||
- **ADR structure is consistent**: ADRs 002–007 follow clear Context/Decision/Consequences with Positive/Negative/Mitigation subsections.
|
||||
- **Cross-references are strong**: Main docs consistently link to relevant ADRs, and ADRs reference each other and peripheral docs.
|
||||
- **Construction vs. validation distinction is well-articulated**: The three-way split (construction, validation, operation) is a clear principled decision — once the DuplicateNodeError contradiction is resolved.
|
||||
- **Supply-chain security reasoning in `frontmatter.md` is exemplary**: CVE references, package counts, recent attack examples — this is how supply-chain decisions should be documented.
|
||||
- **Threat model is clearly stated**: The README threat model directly connects the library's existence to a concrete security posture.
|
||||
- **Propagation formula is clearly specified**: Despite the naming concern (C-2), the actual math in `cost-benefit.md` is detailed enough for unambiguous implementation.
|
||||
|
||||
---
|
||||
|
||||
## Resolution Status (2026-04-26)
|
||||
|
||||
All issues resolved. See `tasks/architecture/` for task details.
|
||||
|
||||
| Issue | Resolution |
|
||||
|-------|-----------|
|
||||
| C-1 (Construction error policy) | ✅ Reworded to "Construction methods enforce uniqueness, not data quality" — no longer contradicts DuplicateNodeError/DuplicateEdgeError. Construction error handling table added to graph-model.md. |
|
||||
| C-2 (qualityDegradation naming) | ✅ Renamed to `qualityRetention` across all documents. Added explicit "Note on naming" in schemas.md and graph-model.md documenting the rename. Updated ADR-004 and ADR-005. |
|
||||
| C-3 (Nullable helper placement) | ✅ Moved Nullable definition to "Schema Utility: Nullable" section before TaskInput in schemas.md. |
|
||||
| W-1 (ADR-002 draft qualifier) | ✅ Added "(draft, not yet a decision)" qualifier to ADR-002's reference to incremental-update-exploration. |
|
||||
| W-2 (ADR-001 alternatives) | ✅ Added "Alternatives Considered" section with NAPI/Rust, WASM, manual adjacency map, and D3/other JS libs. |
|
||||
| W-3 (Doc lifecycle protocol) | ✅ Added "Document Lifecycle" section to README.md with draft/stable/deprecated transitions and ADR status states. |
|
||||
| W-4 (TaskStatus enum values) | ✅ TaskStatusEnum values explicitly listed (pending, in-progress, completed, failed, blocked). `includeCompleted` semantics clarified — only `"completed"` status triggers exclusion. |
|
||||
| W-5 (File I/O runtime portability) | ✅ Added runtime constraint to frontmatter.md Constraints section: `parseTaskFile`/`parseTaskDirectory` depend on Node.js `fs`; `parseFrontmatter` is runtime-agnostic. |
|
||||
| W-6 (architecture.md redirect) | ✅ Added ADR directory reference to redirect file. |
|
||||
| W-7 (CVE-2025-64718) | ✅ Verified — CVE is legitimate. Updated frontmatter.md to confirm the CVE number and note patching status (js-yaml 4.1.1/3.14.2). |
|
||||
| W-8 (limit parameter) | ✅ Already documented with inline comments in api-surface.md (resolved by parallel agent). |
|
||||
| W-9 (Workspace paths) | ✅ Converted workspace-absolute paths to relative/monorepo references in README.md and incremental-update-exploration.md. External links use published URLs where available. |
|
||||
| W-10 (Edge construction semantics) | ✅ Construction Error Handling table added to graph-model.md with per-method behaviors for dangling references, duplicates, and cycles (resolved by parallel agent). |
|
||||
| S-4 (Error class listing) | ✅ DuplicateNodeError and DuplicateEdgeError added to build-distribution.md project structure listing (resolved by parallel agent). |
|
||||
| S-5 (graph.raw mutation safety) | ✅ Warning about direct mutation bypassing TaskGraph invariants added to api-surface.md (resolved by parallel agent). |
|
||||
| S-7 (Incremental ADR note) | ✅ Added "If this exploration leads to a decision, it will become ADR-008" to incremental-update-exploration.md. |
|
||||
- **All workspace-internal reference paths resolve correctly**: Verified every path reference and all point to existing files.
|
||||
25
tasks/architecture/c-1-construction-error-policy.md
Normal file
25
tasks/architecture/c-1-construction-error-policy.md
Normal file
@@ -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
|
||||
26
tasks/architecture/c-2-qualitydegradation-naming.md
Normal file
26
tasks/architecture/c-2-qualitydegradation-naming.md
Normal file
@@ -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
|
||||
21
tasks/architecture/c-3-nullable-helper.md
Normal file
21
tasks/architecture/c-3-nullable-helper.md
Normal file
@@ -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
|
||||
22
tasks/architecture/s-4-error-classes-in-project-structure.md
Normal file
22
tasks/architecture/s-4-error-classes-in-project-structure.md
Normal file
@@ -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
|
||||
19
tasks/architecture/s-5-raw-mutation-safety.md
Normal file
19
tasks/architecture/s-5-raw-mutation-safety.md
Normal file
@@ -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
|
||||
19
tasks/architecture/s-7-incremental-adr-note.md
Normal file
19
tasks/architecture/s-7-incremental-adr-note.md
Normal file
@@ -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
|
||||
19
tasks/architecture/w-1-adr2-qualification.md
Normal file
19
tasks/architecture/w-1-adr2-qualification.md
Normal file
@@ -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
|
||||
28
tasks/architecture/w-10-edge-construction-semantics.md
Normal file
28
tasks/architecture/w-10-edge-construction-semantics.md
Normal file
@@ -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
|
||||
19
tasks/architecture/w-2-adr1-alternatives.md
Normal file
19
tasks/architecture/w-2-adr1-alternatives.md
Normal file
@@ -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
|
||||
19
tasks/architecture/w-3-doc-lifecycle-protocol.md
Normal file
19
tasks/architecture/w-3-doc-lifecycle-protocol.md
Normal file
@@ -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
|
||||
21
tasks/architecture/w-4-taskstatus-enum-values.md
Normal file
21
tasks/architecture/w-4-taskstatus-enum-values.md
Normal file
@@ -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
|
||||
22
tasks/architecture/w-5-fileio-runtime-portability.md
Normal file
22
tasks/architecture/w-5-fileio-runtime-portability.md
Normal file
@@ -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
|
||||
19
tasks/architecture/w-6-redirect-adr-links.md
Normal file
19
tasks/architecture/w-6-redirect-adr-links.md
Normal file
@@ -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
|
||||
21
tasks/architecture/w-7-cve-number-verify.md
Normal file
21
tasks/architecture/w-7-cve-number-verify.md
Normal file
@@ -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
|
||||
22
tasks/architecture/w-8-limit-param-docs.md
Normal file
22
tasks/architecture/w-8-limit-param-docs.md
Normal file
@@ -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
|
||||
21
tasks/architecture/w-9-workspace-paths-to-relative.md
Normal file
21
tasks/architecture/w-9-workspace-paths-to-relative.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user