Files

glm-5.1 307b8a2b54 Add architecture specification and bump taskgraph to v0.0.2

Architecture docs for the open-tasks plugin covering the registry pattern
dispatch design, operation set, error handling, data flow, and constraints.
Includes four ADRs (registry pattern, no-cache policy, risk operation merge,
frontmatter normalization). The depends_on/dependsOn compatibility issue in
@alkdev/taskgraph is resolved in v0.0.2, so the dependency is bumped and
the docs reflect the fix.

AGENTS.md updated: canonical dependsOn field, dependents operation added,
hooks clarification, field naming note.

2026-04-28 09:29:26 +00:00

1.7 KiB

Raw Blame History

status, last_updated

status	last_updated
draft	2026-04-28

ADR-002: No Caching — Fresh Graph Per Invocation

Context

Task files change frequently during active work. Agents update task status (pending → in-progress → completed), add notes, modify acceptance criteria. A cached TaskGraph would become stale and produce misleading analysis.

Options considered:

Fresh read per call — parse files and build graph on every invocation
Session-scoped cache — cache the graph within a session, invalidate on file change detection
Time-based TTL cache — cache for N seconds, then re-parse

Decision

Fresh read per call (Option 1). Each tool invocation reads the tasks directory and constructs a new TaskGraph.

Consequences

Positive:

Guaranteed correctness — analysis always reflects the current state of task files
No invalidation logic to get wrong
No cache coherence bugs
Simple mental model for the agent — "what I see is what's on disk"

Negative:

Redundant I/O for consecutive calls within a short time window
Slight latency increase for each call

Why this is acceptable:

Typical task directories contain 5-50 files. parseTaskDirectory + TaskGraph.fromTasks is sub-second for this scale.
The plugin is read-only — there's no mutation to cache anyway
File I/O is the plugin's only expensive operation, and it's inherently cheap for small task sets
Open-memory makes no attempt to cache SQLite query results either; freshness trumps efficiency

References

@alkdev/taskgraph parseTaskDirectory: async file reading + YAML frontmatter parsing
Open-memory pattern: stateless queries, no caching between calls

1.7 KiB Raw Blame History