feat: add task graph readiness projection

[devkade]

Summary

• Adds concrete TaskGraph/RuntimeTask readiness surfaces for DAG phase 1.
• Adds topological ordering, inspectable readiness reasons, transitive blocked/downstream status projection, and lightweight task-graph/readiness event records.
• Extends task-graph regression coverage with the requested 5-task two-branch fixture, indirect failed-dependency propagation, and README runtime-boundary alignment.

Linked issue

Closes #194

Problem

Issue #194 asks for the first DAG runtime slice: represent a task graph, validate dependencies, compute ready tasks, explain blocked/waiting tasks, project operator status, and specify events for graph creation/readiness changes.

Before this PR, src/domain/task-graph.ts had basic task IDs, dependencies, ready-id computation, and validation. It did not expose a first-class runtime task shape with titles/descriptions, topological ordering, inspectable readiness reasons, aggregate projection, or task-graph/readiness event records.

Options considered

1. Keep only computeReadyTaskIds() and document the rest as future work.
   • Pros: minimal diff.
   • Cons: does not satisfy inspectable readiness, projection, topological-order, or event acceptance criteria.
2. Add a focused domain-only TaskGraph surface in src/domain/task-graph.ts.
   • Pros: completes the phase-1 contract without CLI/worker dispatch coupling; keeps later claim/lease/worker phases separate.
   • Cons: leaves formatting/persistence adapters for future slices.
3. Wire readiness projection into CLI/report surfaces immediately.
   • Pros: visible operator output now.
   • Cons: broadens the slice beyond phase-1 domain contract and risks mixing runtime model with presentation before downstream phases land.

Selected approach

Selected option: 2 — focused domain-only TaskGraph surface.

Why this one: #194 is the phase-1 runtime primitive. Keeping this slice in the domain layer preserves adapter neutrality and gives later #197/#196 work a stable surface for claim/lease and worker execution without prematurely changing CLI behavior.

Risks/trade-offs: event records here are lightweight domain records, not durable RuntimeEventEnvelope instances. Durable envelope wiring can happen when execution persistence/reporting is connected.

Implementation by file/surface

• src/domain/task-graph.ts
  • Adds optional title/description to TaskNode and a strict RuntimeTask interface.
  • Adds computeTaskReadiness() with ready, waiting, blocked, and not_pending reasons.
  • Propagates failed-dependency blocking through downstream dependency chains with explicit upstream/via reasons.
  • Adds projectTaskGraphStatus() for aggregate operator/reporting projection.
  • Adds topologicalTaskIds() with validation-backed deterministic ordering.
  • Adds createTaskGraphRuntimeEvents() for task_graph.created and task.ready phase-1 event records.
  • Keeps repair supersession semantics intact.
• test/task-graph.test.ts
  • Adds the requested 5-task graph fixture with two parallel branches.
  • Covers topological ordering, ready tasks, waiting reasons, projection, and emitted readiness records.
  • Covers indirect failed-dependency propagation (failed -> blocked child -> blocked grandchild).
• README.md
  • Documents TaskGraph ownership of task titles/descriptions, topological ordering, readiness reasons, projections, and event records.

Why this fixes it

The TaskGraph domain can now reject malformed graphs, order valid DAGs, compute only dependency-complete tasks as ready, classify downstream tasks blocked by failed dependencies across multiple levels, expose machine-readable reasons, and emit phase-1 graph/readiness event records. That covers the issue’s phase-1 acceptance criteria while preserving non-goals: no worker dispatch, claim/lease expansion, integration, repair generation, or policy learning behavior.

QA / Verification

• npm ci — pass; installed local dependencies because tsx was absent in this fresh worktree.
• npm test -- test/task-graph.test.ts — pass; package script runs the full test/*.test.ts suite plus the explicit file argument (530 tests, 519 pass, 11 skipped).
• npm run check — pass.
• npm run check:unused — pass.
• npm run quality:budgets — pass with configured non-failing code_smells warning.
• npm run verify — pass before the review-response amendment (npm test, npm run check, npm run check:unused, npm run quality:budgets). The review-response amendment reran the same constituent gates listed above.
• git diff --check — pass.

Anomalies observed

• npm test -- test/task-graph.test.ts does not run only the named file because package.json defines tsx --test test/*.test.ts; it executed the full test suite.
• Node emitted existing [DEP0205] module.register() deprecation warnings during tests.
• npm run quality:budgets retains the existing warning: code_smells=60 vs target <=20; the command exits 0 under the configured budget policy.

Risks / Follow-up

• Durable runtime-event envelope persistence for TaskGraph creation/readiness is still a future adapter/integration step.
• CLI/report presentation of the new projection is intentionally not added in this phase-1 domain slice.

kapi-agent review expectations and current-head merge gate

• Current head: e9d25381ef0565541b9846f27383a05e3873be39
• Changed-line count: 192 additions+deletions against origin/dev (182 insertions, 10 deletions), under the review-size gate.
• kapi-agent should verify the domain-only scope, transitive failed-dependency blocking, graph validation interaction, and README alignment before merge.

[devkade]

@kapi-agent review

Revision explanation for current head 3330dba7d4b7a381083b941fa2946726f21b921e:

What changed:

• Added TaskGraph/RuntimeTask phase-1 domain surfaces for topological ordering, inspectable readiness reasons, status projection, and task-graph/readiness event records.
• Added a 5-task two-branch DAG fixture covering ready/waiting projection and emitted readiness records.
• Updated README graph-execution boundary wording to match the new domain behavior.

Why this closes the prior feedback:

• This is the initial review request for Sub-roadmap: DAG runtime phase 1 — task graph and readiness #194; the slice is intentionally domain-only and does not add worker dispatch, claim/lease expansion, or CLI presentation.
• The diff is 141 changed lines against origin/dev, under the review-size gate.

Verification:

• npm ci — pass.
• npm test -- test/task-graph.test.ts — pass; package script executed the full test suite (530 tests, 519 pass, 11 skipped).
• npm run check — pass.
• npm run verify — pass.
• git diff --check — pass.

[kapi-agent]

kapi-agent review completed

The formal GitHub PR review and required check were submitted separately. This request comment is kept concise to avoid duplicating the full review body.

kapi-agent request lifecycle:

• Status: COMPLETED
• Head: 3330dba7d4b7
• Formal review event: REQUEST_CHANGES
• Review API status: 200
• Required check API status: 201

[kapi-agent]

kapi-agent review

Verdict: REQUEST_CHANGES

Blocking issues

• src/domain/task-graph.ts: blocked readiness is only computed for direct failed dependencies, so downstream tasks remain classified as waiting even when an upstream failure makes them unexecutable.
  • Example: a: failed, b: pending depends on a, c: pending depends on b.
  • Current behavior: b is blocked, c is waiting.
  • For the stated contract of “blocked/downstream status projection” and “classify downstream tasks blocked by failed dependencies,” c should be represented as blocked or otherwise machine-readably blocked by the upstream failure chain.
  • Please add coverage for an indirect downstream failure case and update computeTaskReadiness() / projectTaskGraphStatus() accordingly.

Warnings / risks

• test/task-graph.test.ts covers the happy-path 5-task DAG but does not cover failed dependency propagation through multiple levels. That is the main regression risk for operator-facing status projection.
• TaskGraphRuntimeEvent records are intentionally lightweight domain records, not durable runtime envelopes. That is acceptable for this phase, but downstream integration should avoid treating these as persisted execution events without envelope metadata.

Suggestions

• Consider making readiness reasons for downstream blocking explicit, e.g. blocked by failed upstream dependency a via b, so future CLI/report surfaces can explain why a task is not merely waiting.
• Consider adding a small test for deterministic topological ordering when multiple roots are present, since the implementation sorts available nodes lexicographically rather than preserving input order.

Looks good

• The domain-only scope is well bounded and does not prematurely wire worker dispatch, CLI output, persistence, or claim/lease expansion.
• The new surfaces are small and cohesive: readiness projection, topological order, and event records all stay in src/domain/task-graph.ts.
• Existing validation is reused via assertValidGraph(), so malformed graphs still fail closed before readiness/topology computation.
• README alignment is minimal and matches the new runtime-boundary wording.

Verification notes

• Verifier gate status: PASS — npm ci && npm run verify exited 0.
• Size gate status: PASS — 141 changed lines, below the 200-line semantic review threshold.
• Revision-explanation status: not required for this initial kapi-agent review; explanation was nevertheless found.
• Ilchul review harness gate: PASS — STANDARD risk, neutral conclusion, no blocking findings.
• PR evidence reports npm ci, targeted/full tests, npm run check, npm run verify, and git diff --check passing.

---

Engine: pi

[devkade]

@kapi-agent review

Revision explanation for current head e9d25381ef0565541b9846f27383a05e3873be39:

What changed:

• Addressed the blocking review finding by propagating failed-dependency blocking through downstream dependency chains.
• Added machine-readable blocked projection for indirect failures: a task depending on a blocked child is now blocked, not merely waiting.
• Added regression coverage for failed -> blocked child -> blocked grandchild, including blockedBy and an explicit blocked by failed upstream dependency ... via ... reason.
• Updated the PR body with the new head, changed-line count, and review-response verification.

Why this closes the prior feedback:

• The kapi-agent example (a: failed, b depends on a, c depends on b) is now covered by the test shape (missing-fix, publish, announce).
• computeTaskReadiness() and projectTaskGraphStatus() now classify indirect downstream tasks as blocked with the original failed upstream dependency surfaced in blockedBy.

Verification:

• npm test -- test/task-graph.test.ts — pass; package script executed the full test suite (530 tests, 519 pass, 11 skipped).
• npm run check — pass.
• npm run check:unused — pass.
• npm run quality:budgets — pass with configured non-failing code_smells warning.
• git diff --check — pass.

[kapi-agent]

kapi-agent review completed

The formal GitHub PR review and required check were submitted separately. This request comment is kept concise to avoid duplicating the full review body.

kapi-agent request lifecycle:

• Status: COMPLETED
• Head: e9d25381ef05
• Formal review event: APPROVE
• Review API status: 200
• Required check API status: 201

[kapi-agent]

kapi-agent review

Verdict: APPROVE

Final approval summary

Review journey

The original goal was to add the phase-1 TaskGraph readiness projection surface: topological ordering, inspectable readiness reasons, operator status projection, and lightweight graph/readiness event records. The semantic scope is bounded to the domain layer plus targeted tests and a one-line README alignment update.

A prior kapi-agent review requested changes because blocked readiness only propagated from direct failed dependencies. The current revision includes an author explanation and addresses that feedback by propagating failed upstream dependency blocking through downstream dependency chains.

What changed

• src/domain/task-graph.ts
  • Adds readiness projection APIs and runtime event records.
  • Adds deterministic topological ordering.
  • Updates blocked-task computation to use readiness projection.
  • Propagates failed-dependency blockers transitively.
• test/task-graph.test.ts
  • Adds coverage for the 5-task DAG fixture.
  • Adds regression coverage for failed -> blocked child -> blocked grandchild.
• README.md
  • Aligns the graph execution runtime boundary wording with the new domain surface.

Why this is correct

The previous blocking case is now covered and implemented: a pending task depending on another blocked task is projected as blocked, with machine-readable blockedBy and an explanatory upstream/via reason. Existing repair supersession behavior remains represented through getCompletedOrRepairedTaskIds() / failed blocker filtering.

Evidence

• Verifier gate: PASS.
• Size gate: PASS, 192 changed lines under the 200-line review threshold.
• Revision explanation status: required and found.
• Ilchul review harness gate: PASS, risk profile STANDARD, blocking findings 0.
• Verified command evidence: npm ci && npm run verify exited 0.
• Inspected files: src/domain/task-graph.ts, test/task-graph.test.ts, README.md.

Remaining risks and approval rationale

Remaining risks are limited to future integration surfaces: durable runtime-event envelopes and CLI/report presentation are intentionally deferred. For this domain-only phase-1 slice, the implementation is bounded, tested, and closes the prior blocking feedback, so approval is justified.

Blocking issues

None.

Warnings / risks

• src/domain/task-graph.ts: TaskGraphRuntimeEvent remains a lightweight domain event shape rather than a durable runtime envelope. This is acceptable for the stated phase-1 boundary but should be revisited when persistence/reporting integration lands.
• CLI/operator presentation is intentionally not added in this PR, so consumers must call the new domain projection APIs directly until a later slice wires them into reports.

Suggestions

• Consider adding a future test for mixed dependency states, e.g. a task with one blocked dependency and one still-pending dependency, to lock down whether blocked should suppress or preserve waitingFor details.

Looks good

• The prior indirect-blocking issue is fixed with explicit regression coverage.
• computeBlockedTaskIds() now delegates to the richer readiness projection, reducing duplicated status logic.
• Graph validation remains fail-closed before readiness/topological operations.
• README wording matches the implemented domain behavior without overstating CLI/runtime integration.

Verification notes

• Verifier gate status: PASS — npm ci && npm run verify exited 0.
• Size gate status: PASS — 192 changed lines, below the configured threshold.
• Revision-explanation status: PASS — revision explanation was required and found.
• Ilchul review harness: PASS — STANDARD risk profile, neutral/comment verdict, no blocking findings.
• Local/CI evidence in PR body includes targeted task-graph testing, full verify gates, and git diff --check.

---

Engine: pi