Decompose architecture into 28 atomic implementation tasks

Break the @alkdev/taskgraph architecture specs into dependency-ordered implementation tasks across 8 component directories: setup, schema, error, graph, analysis, cost-benefit, frontmatter, api, and review. Each task has clear acceptance criteria referencing specific architecture docs. Three review tasks serve as quality gates at critical junction points (schemas-and-errors, graph-complete, complete-library). The dependency graph is validated acyclic with 9 topological levels enabling significant parallelism across independent work streams.
2026-04-27 08:30:05 +00:00
parent e592caed57
commit 131e3e929b
28 changed files with 1306 additions and 0 deletions
--- a/tasks/implementation/schema/enums.md
+++ b/tasks/implementation/schema/enums.md
@@ -0,0 +1,44 @@
+---
+id: schema/enums
+name: Define TypeBox categorical enum schemas and type aliases
+status: pending
+depends_on:
+  - setup/project-init
+scope: narrow
+risk: trivial
+impact: component
+level: implementation
+---
+
+## Description
+
+Define all categorical enum schemas using `Type.Union([Type.Literal(...)])` pattern per [schemas.md](../../../docs/architecture/schemas.md). Each enum gets a schema constant (PascalCase + `Enum` suffix) and a `Static<typeof>` type alias (PascalCase, no suffix).
+
+The six enums: `TaskScopeEnum`, `TaskRiskEnum`, `TaskImpactEnum`, `TaskLevelEnum`, `TaskPriorityEnum`, `TaskStatusEnum`.
+
+## Acceptance Criteria
+
+- [ ] `src/schema/enums.ts` exports all six enum schemas and their type aliases
+- [ ] Each enum uses `Type.Union([Type.Literal("value"), ...])` pattern per [typebox-patterns.md](../../../docs/research/typebox-patterns.md)
+- [ ] `TaskScopeEnum`: `"single" | "narrow" | "moderate" | "broad" | "system"`
+- [ ] `TaskRiskEnum`: `"trivial" | "low" | "medium" | "high" | "critical"`
+- [ ] `TaskImpactEnum`: `"isolated" | "component" | "phase" | "project"`
+- [ ] `TaskLevelEnum`: `"planning" | "decomposition" | "implementation" | "review" | "research"`
+- [ ] `TaskPriorityEnum`: `"low" | "medium" | "high" | "critical"`
+- [ ] `TaskStatusEnum`: `"pending" | "in-progress" | "completed" | "failed" | "blocked"`
+- [ ] Type aliases derived via `Static<typeof>`: `TaskScope`, `TaskRisk`, `TaskImpact`, `TaskLevel`, `TaskPriority`, `TaskStatus`
+- [ ] Naming convention matches spec: `Enum` suffix on schema constants only, never on type aliases
+- [ ] `src/schema/index.ts` re-exports all schemas and types
+
+## References
+
+- docs/architecture/schemas.md — enum definitions, naming convention
+- docs/research/typebox-patterns.md — TypeBox enum patterns, naming convention
+
+## Notes
+
+> To be filled by implementation agent
+
+## Summary
+
+> To be filled on completion
--- a/tasks/implementation/schema/graph-schemas.md
+++ b/tasks/implementation/schema/graph-schemas.md
@@ -0,0 +1,42 @@
+---
+id: schema/graph-schemas
+name: Define TaskGraphNodeAttributes, TaskGraphEdgeAttributes, and SerializedGraph
+status: pending
+depends_on:
+  - schema/enums
+scope: narrow
+risk: low
+impact: component
+level: implementation
+---
+
+## Description
+
+Define graph attribute schemas and the serialized graph generic in `src/schema/graph.ts`. `TaskGraphNodeAttributes` carries only analysis-relevant metadata (no tags, assignee, due, etc.). `SerializedGraph` is a generic factory parameterized with node and edge attribute types.
+
+## Acceptance Criteria
+
+- [ ] `src/schema/graph.ts` exports:
+  - `TaskGraphNodeAttributes` schema: `name: Type.String()`, optional categorical enums (scope, risk, impact, level, priority, status) — **not** nullable on the graph (absent = not stored)
+  - `type TaskGraphNodeAttributes` derived
+  - `TaskGraphNodeAttributesUpdate = Type.Partial(TaskGraphNodeAttributes)` and type alias
+  - `TaskGraphEdgeAttributes` schema: `qualityRetention: Type.Optional(Type.Number())`
+  - `type TaskGraphEdgeAttributes` derived
+  - `SerializedGraph` generic factory parameterized with `<N extends TSchema, E extends TSchema, G extends TSchema>`
+  - `TaskGraphSerialized = SerializedGraph(TaskGraphNodeAttributes, TaskGraphEdgeAttributes, Type.Object({}))` and type alias
+- [ ] `SerializedGraph` generic follows graphology JSON format: `attributes`, `options: { type: "directed", multi: false, allowSelfLoops: false }`, `nodes: [{ key, attributes }]`, `edges: [{ key, source, target, attributes }]`
+- [ ] No schema version field on `TaskGraphSerialized` per spec
+- [ ] Re-exported from `src/schema/index.ts`
+
+## References
+
+- docs/architecture/schemas.md — graph attribute schemas, SerializedGraph
+- docs/research/typebox-patterns.md — section 6 (generic schema factories)
+
+## Notes
+
+> To be filled by implementation agent
+
+## Summary
+
+> To be filled on completion
--- a/tasks/implementation/schema/input-schemas.md
+++ b/tasks/implementation/schema/input-schemas.md
@@ -0,0 +1,39 @@
+---
+id: schema/input-schemas
+name: Define TaskInput, DependencyEdge, and Nullable helper
+status: pending
+depends_on:
+  - schema/enums
+scope: narrow
+risk: low
+impact: component
+level: implementation
+---
+
+## Description
+
+Define the `TaskInput` and `DependencyEdge` input schemas in `src/schema/task.ts`, plus the `Nullable` generic helper. `TaskInput` uses `Type.Optional(Nullable(...))` for categorical fields to support both absent and explicitly-null values (YAML frontmatter distinction).
+
+## Acceptance Criteria
+
+- [ ] `src/schema/task.ts` exports `Nullable` helper: `const Nullable = <T extends TSchema>(T: T) => Type.Union([T, Type.Null()])`
+- [ ] `TaskInput` schema defined with all fields per [schemas.md](../../../docs/architecture/schemas.md):
+  - `id: Type.String()`, `name: Type.String()`, `dependsOn: Type.Array(Type.String())`
+  - Categorical fields: `Type.Optional(Nullable(TaskXxxEnum))` for status, scope, risk, impact, level, priority
+  - Metadata fields: `tags`, `assignee`, `due`, `created`, `modified`
+- [ ] `DependencyEdge` schema: `from: Type.String()`, `to: Type.String()`, `qualityRetention: Type.Optional(Type.Number({ default: 0.9 }))`
+- [ ] Type aliases derived: `type TaskInput = Static<typeof TaskInput>`, `type DependencyEdge = Static<typeof DependencyEdge>`
+- [ ] Re-exported from `src/schema/index.ts`
+
+## References
+
+- docs/architecture/schemas.md — TaskInput, DependencyEdge, Nullable definitions
+- docs/research/typebox-patterns.md — section 6 (Nullable helper pattern)
+
+## Notes
+
+> To be filled by implementation agent
+
+## Summary
+
+> To be filled on completion
--- a/tasks/implementation/schema/numeric-methods-and-defaults.md
+++ b/tasks/implementation/schema/numeric-methods-and-defaults.md
@@ -0,0 +1,48 @@
+---
+id: schema/numeric-methods-and-defaults
+name: Implement categorical numeric functions and resolveDefaults
+status: pending
+depends_on:
+  - schema/enums
+  - schema/graph-schemas
+scope: narrow
+risk: low
+impact: component
+level: implementation
+---
+
+## Description
+
+Implement the standalone numeric functions that map categorical enum values to their numeric equivalents, plus `resolveDefaults` which fills in defaults for unassessed fields and computes derived numeric values. These live in `src/analysis/defaults.ts` per the project structure.
+
+## Acceptance Criteria
+
+- [ ] `src/analysis/defaults.ts` exports:
+  - `scopeCostEstimate(scope: TaskScope): number` — maps to 1.0–5.0 per table
+  - `scopeTokenEstimate(scope: TaskScope): number` — maps to 500–10000 per table
+  - `riskSuccessProbability(risk: TaskRisk): number` — maps to 0.50–0.98 per table
+  - `riskWeight(risk: TaskRisk): number` — maps to 0.02–0.50 (equals 1 - successProbability)
+  - `impactWeight(impact: TaskImpact): number` — maps to 1.0–3.0 per table
+  - `resolveDefaults(attrs: Partial<TaskGraphNodeAttributes> & Pick<TaskGraphNodeAttributes, 'name'>): ResolvedTaskAttributes`
+- [ ] All numeric mapping tables match [schemas.md](../../../docs/architecture/schemas.md) exactly:
+  - Scope: single=1.0/500, narrow=2.0/1500, moderate=3.0/3000, broad=4.0/6000, system=5.0/10000
+  - Risk: trivial=0.98/0.02, low=0.90/0.10, medium=0.80/0.20, high=0.65/0.35, critical=0.50/0.50
+  - Impact: isolated=1.0, component=1.5, phase=2.0, project=3.0
+- [ ] `resolveDefaults` handles null/undefined categorical fields by falling back to: risk→medium, scope→narrow, impact→isolated
+- [ ] `resolveDefaults` populates derived fields: costEstimate, tokenEstimate, successProbability, riskWeight, impactWeight
+- [ ] Label-only fields (level, priority, status) remain nullable after resolution — no default value assigned
+- [ ] `riskWeight(risk)` equals `1 - riskSuccessProbability(risk)` — guaranteed by implementation
+- [ ] Unit tests covering every enum value's numeric mapping and resolveDefaults with mixed null/present inputs
+
+## References
+
+- docs/architecture/schemas.md — numeric method tables, ResolvedTaskAttributes definition
+- docs/architecture/graph-model.md — categorical field defaults
+
+## Notes
+
+> To be filled by implementation agent
+
+## Summary
+
+> To be filled on completion
--- a/tasks/implementation/schema/result-types.md
+++ b/tasks/implementation/schema/result-types.md
@@ -0,0 +1,42 @@
+---
+id: schema/result-types
+name: Define analysis result TypeBox schemas (RiskPathResult, DecomposeResult, WorkflowCostResult, etc.)
+status: pending
+depends_on:
+  - schema/enums
+scope: narrow
+risk: trivial
+impact: component
+level: implementation
+---
+
+## Description
+
+Define all analysis function return type schemas in `src/schema/results.ts`. These are the structured outputs of the cost-benefit and analysis functions. Each schema has both a TypeBox constant and a `Static<typeof>` type alias.
+
+## Acceptance Criteria
+
+- [ ] `src/schema/results.ts` exports all result schemas and types:
+  - `RiskPathResult`: `{ path: string[], totalRisk: number }`
+  - `DecomposeResult`: `{ shouldDecompose: boolean, reasons: string[] }`
+  - `WorkflowCostOptions`: `{ includeCompleted?, limit?, propagationMode?, defaultQualityRetention? }`
+  - `WorkflowCostResult`: `{ tasks: [...], totalEv, averageEv, propagationMode }`
+  - `EvConfig`: `{ retries?, fallbackCost?, timeLost?, valueRate? }` with defaults (0, 0, 0, 0)
+  - `EvResult`: `{ ev, pSuccess, expectedRetries }`
+  - `RiskDistributionResult`: `{ trivial, low, medium, high, critical, unspecified }` — each `string[]`
+- [ ] All schemas use `Static<typeof>` for type aliases, no manual interface definitions
+- [ ] `WorkflowCostOptions.propagationMode` is `Type.Union([Type.Literal("independent"), Type.Literal("dag-propagate")])`
+- [ ] Re-exported from `src/schema/index.ts`
+
+## References
+
+- docs/architecture/api-surface.md — return type definitions
+- docs/architecture/schemas.md — result schema definitions
+
+## Notes
+
+> To be filled by implementation agent
+
+## Summary
+
+> To be filled on completion