feat(task-manager): durable task system with append-only event history#132
Merged
Conversation
codeaholicguy
added a commit
that referenced
this pull request
Jul 1, 2026
) Add a guarded integration test proving the real TaskService (shipped on feature-task-system) satisfies the tracing ITaskService port end-to-end, with NO mapping-logic divergence. Round-trips every semantic (ensureFeatureTask, phase/progress/nextStep/blocker/evidence/attribution/note/custom/close) through the real service + file-backed store and asserts the exact contract event-type strings + persisted snapshot. - tests/integration.task-manager.test.ts: skips cleanly (1 passed | 5 skipped) when @ai-devkit/task-manager is not resolvable, so standalone CI is green before #132 merges; auto-activates once #132 lands. Both states verified. - .eslintrc.json: add package lint config (mirrors @ai-devkit/agent-manager). - README/implementation/testing: mark wiring SHIPPED; note the real TaskService is assignable to the port via method bivariance (no port change needed). Validation (fresh, real package resolvable): tsc --noEmit exit 0; vitest run 44 passed (38 unit + 6 real integration) exit 0; build exit 0; eslint 0 errors. Standalone (package absent): 39 passed | 5 skipped, exit 0.
codeaholicguy
force-pushed
the
feature-task-system
branch
7 times, most recently
from
b57e285 to
f0203cd
Compare
…UUID ids
Introduce @ai-devkit/task-manager as the durable unit for development/debug
work. A task has a stable id and encapsulates artifacts, evidence, progress,
blockers, lifecycle phase, agent attribution, branch/worktree/PR links, and an
append-only event history.
Structure (mirrors @ai-devkit/memory):
src/
task.types.ts # public types: Actor, Task, TaskEvent, payloads
task.errors.ts # TaskError hierarchy + isTaskEventType guard
task.ids.ts # raw UUIDv4 id generators (crypto.randomUUID)
actor-resolver.ts # resolveCurrentActor (env + process)
task.repository.ts # TaskRepository — task/event persistence (SQLite)
task.service.ts # TaskService (public consume-only surface)
database/ # connection.ts (getDatabase/closeDatabase singleton,
# WAL, busy_timeout), schema.ts, migrations/
index.ts
Persistence:
- SQLite at ~/.ai-devkit/tasks.db via better-sqlite3, mirroring @ai-devkit/memory:
process-wide getDatabase() singleton, versioned migrations via user_version,
SQL assets copied to dist by the build; tests reset with closeDatabase().
- TaskRepository owns the task/event SQL. A tasks table holds snapshots (full
Task JSON + indexed columns); a task_events table is the append-only history.
- No SPI / swappable-backend abstraction: TaskRepository is the single concrete
persistence class.
IDs: raw UUIDv4 (crypto.randomUUID()) stored as TEXT — globally unique, no
prefix, suffix, or collision checks. Generated in the service layer (like memory).
CLI: ai-devkit task create/list/show/update/phase/status/progress/next/blocker/
evidence/artifact/assign/note/event/close, with --json and attribution.
Tests: 890 passing repo-wide; task-manager coverage 90% stmt / 79% branch.
Public API: Task/TaskEvent shapes, TaskService methods, CLI commands, and the 14
task.* event types are stable. The only format change vs the prior draft is that
ids are now raw UUIDs (no task_/evt_ prefix); the persistence class is named
TaskRepository (concrete, in task.repository.ts).
codeaholicguy
force-pushed
the
feature-task-system
branch
from
94104f4 to
8d1d63f
Compare
codeaholicguy
added a commit
that referenced
this pull request
Jul 2, 2026
) Add a guarded integration test proving the real TaskService (shipped on feature-task-system) satisfies the tracing ITaskService port end-to-end, with NO mapping-logic divergence. Round-trips every semantic (ensureFeatureTask, phase/progress/nextStep/blocker/evidence/attribution/note/custom/close) through the real service + file-backed store and asserts the exact contract event-type strings + persisted snapshot. - tests/integration.task-manager.test.ts: skips cleanly (1 passed | 5 skipped) when @ai-devkit/task-manager is not resolvable, so standalone CI is green before #132 merges; auto-activates once #132 lands. Both states verified. - .eslintrc.json: add package lint config (mirrors @ai-devkit/agent-manager). - README/implementation/testing: mark wiring SHIPPED; note the real TaskService is assignable to the port via method bivariance (no port change needed). Validation (fresh, real package resolvable): tsc --noEmit exit 0; vitest run 44 passed (38 unit + 6 real integration) exit 0; build exit 0; eslint 0 errors. Standalone (package absent): 39 passed | 5 skipped, exit 0.
codeaholicguy
added a commit
that referenced
this pull request
Jul 2, 2026
…ogress tracking (#131) * feat(task-tracer): add tracing layer mapping lifecycle progress to the Task contract Introduce packages/task-tracer, a port-based (dependency inversion) tracing layer that maps dev-lifecycle / structured-debug progress semantics onto the LOCKED Task contract from feature-task-system. Task is the durable unit; tracing = task progress/events — no separate session-trace model, no task storage duplication. - contract.ts: async ITaskService port mirroring the locked TaskService API (Task/TaskEvent/Actor/TaskEventType) verbatim; consume-only. - TaskTracer: one method per semantic; each calls exactly one service mutator (phase/progress/nextStep/blocker/evidence/attribution/note/custom/close). - in-memory.ts: faithful InMemoryTaskService test double (not shipped storage). - status.ts: readStatus digest with staleness for orchestrator routing. - cli-argv.ts: pure argv builders for the upstream `ai-devkit task` CLI. - 38 vitest unit tests across contract conformance, mapping, status, argv. Validation (fresh): tsc --noEmit exit 0; vitest run 38 passed exit 0; swc + declarations build exit 0. Wires into @ai-devkit/task-manager (TaskService) with zero mapping changes when that package ships. * test(task-tracer): wire port to shipped @ai-devkit/task-manager (PR #132) Add a guarded integration test proving the real TaskService (shipped on feature-task-system) satisfies the tracing ITaskService port end-to-end, with NO mapping-logic divergence. Round-trips every semantic (ensureFeatureTask, phase/progress/nextStep/blocker/evidence/attribution/note/custom/close) through the real service + file-backed store and asserts the exact contract event-type strings + persisted snapshot. - tests/integration.task-manager.test.ts: skips cleanly (1 passed | 5 skipped) when @ai-devkit/task-manager is not resolvable, so standalone CI is green before #132 merges; auto-activates once #132 lands. Both states verified. - .eslintrc.json: add package lint config (mirrors @ai-devkit/agent-manager). - README/implementation/testing: mark wiring SHIPPED; note the real TaskService is assignable to the port via method bivariance (no port change needed). Validation (fresh, real package resolvable): tsc --noEmit exit 0; vitest run 44 passed (38 unit + 6 real integration) exit 0; build exit 0; eslint 0 errors. Standalone (package absent): 39 passed | 5 skipped, exit 0. * refactor(task-tracer): simplify pass — drop unused ActorResolver, fix docs Analysis-first simplification of PR #131. No semantics or contract changes. - Remove src/ActorResolver.ts (+ exports): 0 internal callers, 0 tests, 0 consumers. It duplicated the TaskService's env-resolution and was trivially replaceable by an Actor literal. Cheapest to remove pre-merge (v0.1.0, no consumers). README/design/implementation/planning updated; callers pass an explicit Actor directly. - TaskTracer.ts: fix ValidationInput.passed docstring ("defaults to true" was false — field is required, no default). - integration.task-manager.test.ts: drop tautology "integration guard" test (asserted `mod === null || mod !== null`, always true). vitest reports the skipped suite cleanly without it. Kept (considered, justified): contract.ts port (decouples from optional peer; ITaskService is task-tracer's own), InMemoryTaskService (fast hermetic no-IO unit tests + public export). Validation (fresh): tsc --noEmit exit 0; eslint 0 errors; build exit 0. Standalone (task-manager absent): 38 passed | 5 skipped, exit 0. Real package resolvable: 43 passed (38 unit + 5 real integration), exit 0. * feat(skill): add task skill for CLI-driven lifecycle/debug progress tracing Replace the packages/task-tracer package + contract/port docs with a focused skill/docs integration — the same pattern as the memory skill. The integration surface is the ai-devkit task CLI; no TypeScript abstraction layer. - skills/task/SKILL.md: canonical ai-devkit task CLI calls for dev-lifecycle / verify / structured-debug progress (phase, progress, next, blocker add/resolve, evidence, artifact, attribution, show/list). Feature key resolves positionally as <id>, so agents do no task-id bookkeeping. Token-efficient, emit-at-checkpoints. - skills/task/agents/openai.yaml: skill interface metadata. - constants.ts: register 'task' in BUILTIN_SKILL_NAMES so init/skill add --built-in install it. - .ai-devkit.json: install the task skill in this project. Removes packages/task-tracer (port, contract, in-memory double, CLI argv builders, all tests) and the contract/port-oriented feature docs added earlier on this branch — they net to zero vs main. Two reviewer-provided canonical examples were adapted to match the SHIPPED CLI (verified by running each command against a throwaway store): - '--workflow' is not a CLI flag (unknown option); feature key + phase carry the workflow — omitted. - 'progress <id> "text"' silently drops the text (progress.text stays null); the skill uses '--text'. Validation (fresh): npm run lint exit 0 (5 projects); npm run test exit 0 (870 passed, 5 projects); SKILL.md frontmatter + openai.yaml parse via the CLI's own skill parsers (validateSkillName, extractSkillDescription). * docs(skills): add optional task tracing guidance * docs(skills): keep agent management focused * docs(skills): simplify task tracing guidance * docs(skills): allow npx task fallback
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces
@ai-devkit/task-manageras an optional AI DevKit plugin for durable development/debug tasks. A task has a stable raw UUID id and captures artifacts, evidence, progress, blockers, lifecycle phase, actor attribution when supplied by the caller, branch/worktree/PR links, and an append-only event history.The core
ai-devkitCLI no longer imports or registers the task command. Users opt in by installing/enabling the package as a plugin:Once enabled, the plugin contributes
ai-devkit task .... Without the plugin, the core CLI avoids the extra task-manager dependency and command/context surface.What's included
@ai-devkit/task-manager:TaskServicepublic API for create/list/show/update/phase/status/progress/next/blocker/evidence/artifact/assign/note/event/close flows.TaskRepositorySQLite persistence overtasksandtask_events.busy_timeout, migrations, and default path~/.ai-devkit/tasks.db.task.*event type strings.package.jsondeclaresaiDevkit.commandsfortask.packages/task-manager/src/command.tsregisters task subcommands on the host-provided plugin command..ai-devkit.jsontasks.pathis resolved by the plugin command;--db-pathremains the explicit override.taskcommand registration.@ai-devkit/task-manager.Storage layout
SQLite database:
~/.ai-devkit/tasks.dbby default.tasks: one row per task snapshot, with full Task JSON plus indexed query columns.task_events: append-only event history, one row per event.The snapshot remains authoritative for reads; events preserve the audit trail.
Key decisions
opts.actor, CLI users pass--agent,--agent-type,--pid, or--session; omitted actors are stored asnull.phaseis a single advancing field.--db-path, then project.ai-devkit.jsontasks.path, then~/.ai-devkit/tasks.db.Validation
npm run lintvia commit hooknpm testvia commit hooknpx nx test task-managernpx nx build task-managernpx nx lint task-managernpx ai-devkit@latest lint --feature task-systemTests
packages/task-manager/tests/unit/{ids,errors}.test.tspackages/task-manager/tests/integration/{task.repository,service,add-event-coverage}.test.tspackages/task-manager/tests/command.test.tspackages/task-manager/tests/plugin-package.test.tsRisks / limitations (MVP)
Not for merge until review is complete.